Elements Manual
Elements 3 Manual
Elements 3 Manual
  • Welcome 👋
  • QUICK START
    • Elements in Five Minutes or Less
    • Accessing the Web UI (CRM)
    • Creating A User
  • General
    • General Concepts
    • N-Tier Architecture
    • Security Model
  • Core Features
    • Core API Overview
    • Sessions
    • Applications
    • Users and Profiles
    • Digital Goods
    • Progress and Missions
    • Leaderboards
    • Matchmaking
    • Followers
    • Friends
    • Reward Issuance
    • Save Data
    • Schemas and Metadata Specifications
    • Queries
      • Base Query Syntax
      • Boolean Queries
      • Object Graph Navigation
      • Advanced Operators
        • .ref
        • .name
    • Custom Code
      • Element Structure
      • RESTful APIs
      • Websockets
    • Auth Schemes
      • OIDC
      • OAuth2
  • Web 3
    • Omni Chain Support
    • Vaults
    • Wallets
    • Smart Contracts
      • Smart Contracts: Ethereum
      • Smart Contracts: Flow
      • Smart Contracts: Solana
      • Smart Contracts: Neo
  • CONFIGURATION
    • Direct Database Access and Batch Configuration
    • Batch Samples
      • Item Upload Bash Script Sample
      • Mission Upload Bash Script Sample
  • RESTful APIs
    • Swagger and Swagger UI
    • API Specification
      • /application
      • /application/configuration
      • /auth
      • /auth_scheme
        • /custom
        • /oauth2
        • /oidc
      • /blockchain
      • /followee
      • /follower
      • /friend
      • /google
      • /index
      • /inventory
      • /item
      • /large_object
      • /leaderboard
      • /rank
      • /score
      • /match
      • /mission
      • /progress
      • /reward_issuance
      • /schedule
      • /notification
      • /profile
      • /save_data
      • /metadata_spec
      • /mock_session
      • /session
      • /health
      • /version
      • /signup
      • /user
    • Javadocs
  • Releases
    • 3.1 Release Notes
Powered by GitBook
On this page
  • How does it work?
  • Managing Auth Schemes
  1. Core Features
  2. Auth Schemes

OIDC

When creating a new Session, you have the option to authenticate using a predefined OIDC Auth Scheme.

How does it work?

An OIDC Auth Scheme is comprised of:

  • an issuer, which is generally the URL of the service that provided the authentication token.

  • the keys URL, which is where the public keys are stored in the form of JWKs.

  • the media type for the request to fetch the keys, which will almost always be application/json

  • the keys, which are used to validate the signature of the auth token

To authenticate using an OIDC Auth Scheme, you must have a scheme defined with an issuer matching the value of theiss key in the JWT that you are sending. Here's an example decoded JWT from Apple:

Header
{
  "kid": "fh6Bs8C",
  "alg": "RS256"
}

Payload
{
  "iss": "https://appleid.apple.com",
  "aud": "com.mycompany.myapplication",
  "exp": 1703881696,
  "iat": 1703795296,
  "sub": "x.y.z",
  "nonce": "c182a093d0a21f15282a1701feabd9ffbdff318de5f52046ce1e093f16e74f43",
  "c_hash": "t2_yMK6paDfgGiNPROjYKw",
  "email": "someid@privaterelay.appleid.com",
  "email_verified": "true",
  "is_private_email": "true",
  "auth_time": 1703795296,
  "nonce_supported": true
}

This would automatically attempt to use the scheme defined for https://appleid.apple.com

When sending the JWT to Elements, it must be Base64 encoded. This is also typically how the JWT is received from the issuer.

Managing Auth Schemes

Elements will create several default schemes for common SSO providers. However, it is possible to create new schemes.

In the Auth section of the CRM, under the OIDC tab, you can create a new scheme or manage existing schemes.

An OIDC Auth Scheme follows the following structure:

{
    "id": "67d673f5131dde00b60e230b",
    "issuer": "https://accounts.google.com",
    "keys": [
        {
            "alg": "RS256",
            "kid": "d9740a70b0972dccf75fa88bc529bd16a30573bd",
            "kty": "RSA",
            "use": "sig",
            "e": "AQAB",
            "n": "oeS547_9wjr2KSN8kA8shy-1arjHHxrx8QeARyWQ9tjQZ8xuF62y-2Ffz0J9F8A_vjrtWCv-ApD1m2v86qs6ZhCXYjvFOPzu7eehcSIojxqgjcN8rqMmhOloPVll_xsc1XXs3djFYL4cGaozJ4b7C5HWQqCJwkKqDTUPAfNTgQG-CSFlGVMM9Yu5ZElsiQIvP_DHfmyMsSIfmi5xxJD_xIBxumh9C8pOOcarw2oi8eLqtyj9jnnjEJncm51PsjkyATCzcMKSFIGFr-UPVnH4-4mYpeqwwYzcvb95DH-exQANjYLANFiSbyRU0SxzJ39yKPAPIBwqrA37BVwsD5AJvw"
        },
        {
            "alg": "RS256",
            "kid": "3628258601113e6576a45337365fe8b8973d1671",
            "kty": "RSA",
            "use": "sig",
            "e": "AQAB",
            "n": "vHJNSdOKUAG53oCGHbEp2PJFX-NksFDrw1_TEzK8yF72Jbp8cYebwkoZpCkr2THVAmRuvDe8GuuXYyRih9w7APwAH0aNy8og4Q1rqPuX-q1TAqO9KXYJNd2VIaICwY2IvY3IgQNu0r9GKouSBeeaXGBlUYi2IR74T4ICOwcpJYTQOE2GWcWeri7iaeFzMfqKa0NJrv6f7paGA0DNu0PggNpgOQMbZoriWc7-PGa7lP4QrStpGikgNOcbGfEw53LeB6dbw72uCCpGbd1iuhzv6M6B-7gLQEp4188mAgjSkmr4TruyZ36Nn4gK_FTOFI44QNMvAGUBJ1L7M49V0KyELQ"
        }
    ],
    "keysUrl": "https://www.googleapis.com/oauth2/v3/certs",
    "mediaType": "application/json"
}

It is not necessary to define the JWKs ahead of time. The keys listed here are cached keys that have been fetched from the Keys URL. When attempting to authenticate, the JWT will contain the Key Id (kid). If the cached keys do not contain a key with this id, then Elements will fetch the keys from the Keys URL and retry the authentication attempt with the new keys. If authentication is successful, then the new keys will be cached.

PreviousAuth SchemesNextOAuth2

Last updated 1 month ago

To send an , you will need to first fetch a Json Web Token (JWT) from the issuer. The JWT will then need to be sent to Elements to verify the signature using the cached Json Web Key (JWK).

authentication request