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": "[email protected]",
  "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

To send an authentication request, 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).

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.