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 the iss 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

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).

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"
}