Open ID Connect (OIDC)

OpenID Connect (OIDC) is an authentication protocol built on top of OAuth 2.0. It allows a user to authenticate with an external identity provider.

Authsignal's OIDC integration allows OIDC clients to federate passwordless and multi-factor authentication (MFA) flows to Authsignal, securely returning back the outcome of the authentication challenge through a set of claims.

Authsignal OIDC Flows

The Authsignal OIDC flows extends on the OIDC protocol in two ways:

• The authorization endpoint (/oidc/auth) will only work within the scope of an already identified resource owner, typically a userId identifying the resource owner. This extension requires a short lived access token to be generated before redirecting the resource owner to the authorization endpoint via our initialization auth endpoint (/init-auth). The access token geneated will be appended to the authorization endpoint (/oidc/auth) as a URL parameter named token
• On redirection, in the Authsignal OIDC flow, regardless of authentication outcome, we will always respond with a authorization code grant type. This slightly deviates from the OIDC specification, where un-successful outcomes do not generate an authorization code. It is important for the client to exchange the authorization code for an acess token (/oidc/token), and inspect the action_state claim to decide whether to proceed with business logic or a authetication pipeline in their flows.

Example OIDC flow diagram

Download PDF Version

Endpoints

As documented in the above diagram and description, there are 3 important endpoints.

1. Initialize Authentication Endpoint (/init-auth)
2. OIDC Authorize Endpoint (/oidc/auth)
3. OIDC Access Token Exchange (/oidc/token)

Endpoint URLs

Region	API URL
US (Oregon)	https://connect.authsignal.com
AU (Sydney)	https://au-connect.authsignal.com
EU (Dublin)	https://eu-connect.authsignal.com

1. Initialize Authentication

The initialize authentication POST /init-auth endpoint is a prerequisite before redirecting the user to the OIDC Authorize endpoint. This endpoint allows the authorize endpoint to scope the flow to a single userId and add important metadata to facilitate the Authsignal rules engine to make decisions like whether challenge flows should be performed.

cURL

curl --location --request POST 'https://AUTHSIGNAL_CONNECT_HOSTNAME/init-auth' \
--header 'Authorization: Basic YOUR_TENANT_API_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userId": "123456",
    "action": "manageAuth",
    "appId": "7aae2f7a-394a-415a-a386-4ea218f6f579",
    "scope": "readonly write changeprofile",
    "custom": {
        "yourCustomBoolean": true,
        "yourCustomString": "NZD",
        "yourCustomNumber": 10.00
    },
    "redirectToSettings": false
}'

Request

• userIdstring

  The unique ID for this user in your database.

• actionstring

  The code of the action e.g signIn, manageAuthenticators.

• appIdstring | undefined

  The clientId or appId in the context of the calling identity provider.

• scopestring

  The scopes being requested by the calling identity provider, formatted as a space-separated list.

• customobject | undefined

  A custom JSON object. Use this to send a list of custom data points. Rules can be used to match against these data points.

• redirectToSettingsboolean | undefined

  The flag indicating whether the challenge flow should redirect to the self service management screens for the user to manage their authenticators.

POST /init-auth

{
    "userId": "123456",
    "action": "manageAuth",
    "appId": "7aae2f7a-394a-415a-a386-4ea218f6f579",
    "scope": "readonly write changeprofile",
    "custom": {
        "yourCustomBoolean": true,
        "yourCustomString": "NZD",
        "yourCustomNumber": 10.00
    },
    "redirectToSettings": false
}

Response

• tokenstring

  The short lived token to be appended to the OIDC authorize GET request.

POST /init-auth

{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTYiLCJleHAiOjE2NzM5MjExNTksImlzcyI6Imh0dHBzOi8veXFqN2phYXV0ZS5leGVjdXRlLWFwaS51cy13ZXN0LTIuYW1hem9uYXdzLmNvbSIsIm90aGVyIjp7ImlkZW1wb3RlbmN5S2V5IjoiNWUwYjJiNGItMDE1OC00ZmYxLTgzYmQtNTcwNTljMWFhZTQyIiwidGVuYW50SWQiOiI2ZTcwNTNiZS05Y2NhLTRkYWItODcwMi0wMGM4MTE2ZmViODUiLCJwdWJsaXNoYWJsZUtleSI6IjNkMTI5YjJhZmFmNjBjOWQ2MWIwMDAzYmFhMTY5YjM1IiwidXNlcklkIjoiMTIzNDU2IiwiYWN0aW9uIjoibWFuYWdlQXV0aCIsInJlZ2lvbiI6InVzIiwiZW5yb2xsbWVudCI6ZmFsc2UsInJlZGlyZWN0VG9TZXR0aW5ncyI6ZmFsc2V9LCJpYXQiOjE2NzM5MjA1NTl9.DQAmCzp4UkMEGYmNkyJfudcTHXXwoKsyU9aoa72-Jr0"}

OIDC Protocol Endpoints

The following endpoints documents the OIDC protocol based endpoints. Depending on your client library you may not need to do any additional customizations.

Authsignal's OIDC connector supports authorization_code grant types.

Type	Endpoint
OIDC Discovery	https://AUTHSIGNAL_CONNECT_HOSTNAME/oidc/.well-known/openid-configuration
Authorization	https://AUTHSIGNAL_CONNECT_HOSTNAME/oidc/auth
Token (Access Token Exchange)	https://AUTHSIGNAL_CONNECT_HOSTNAME/oidc/token

2. OIDC Authorize Endpoint

The GET /oidc/auth endpoint is used to interact with the resource owner and get the authorization to access the protected resource. It's compulsory to pass the token url parameter to the request along side the compulsory OIDC parameters. The token would have been generated using the /init-auth call prior.

cURL

curl --location --request GET 'https://AUTHSIGNAL_CONNECT_HOSTNAME/oidc/auth?client_id=6e7053be-9cca-4dab-8702-00c8116feb85&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTYiLCJleHAiOjE2NzM5MjExNTksImlzcyI6Imh0dHBzOi8veXFqN2phYXV0ZS5leGVjdXRlLWFwaS51cy13ZXN0LTIuYW1hem9uYXdzLmNvbSIsIm90aGVyIjp7ImlkZW1wb3RlbmN5S2V5IjoiNWUwYjJiNGItMDE1OC00ZmYxLTgzYmQtNTcwNTljMWFhZTQyIiwidGVuYW50SWQiOiI2ZTcwNTNiZS05Y2NhLTRkYWItODcwMi0wMGM4MTE2ZmViODUiLCJwdWJsaXNoYWJsZUtleSI6IjNkMTI5YjJhZmFmNjBjOWQ2MWIwMDAzYmFhMTY5YjM1IiwidXNlcklkIjoiMTIzNDU2IiwiYWN0aW9uIjoibWFuYWdlQXV0aCIsInJlZ2lvbiI6InVzIiwiZW5yb2xsbWVudCI6ZmFsc2UsInJlZGlyZWN0VG9TZXR0aW5ncyI6ZmFsc2V9LCJpYXQiOjE2NzM5MjA1NTl9.DQAmCzp4UkMEGYmNkyJfudcTHXXwoKsyU9aoa72-Jr0&redirect_uri=https://yourredirecturl.com&state=xxxx'

Request

• clientIdstring

  The Authsignal tenant ID.

• tokenstring

  The short lived token generated in /init-auth.

• redirect_uristring

  All responses from this endpoint results in a redirect to this URL.

• statestring | undefined

  The OAuth state parameter. If this is set in the request then it will be returned to the application as part of the redirect_uri.

GET /oidc/auth

https://AUTHSIGNAL_CONNECT_HOSTNAME/oidc/auth?client_id=6e7053be-9cca-4dab-8702-00c8116feb85&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTYiLCJleHAiOjE2NzM5MjExNTksImlzcyI6Imh0dHBzOi8veXFqN2phYXV0ZS5leGVjdXRlLWFwaS51cy13ZXN0LTIuYW1hem9uYXdzLmNvbSIsIm90aGVyIjp7ImlkZW1wb3RlbmN5S2V5IjoiNWUwYjJiNGItMDE1OC00ZmYxLTgzYmQtNTcwNTljMWFhZTQyIiwidGVuYW50SWQiOiI2ZTcwNTNiZS05Y2NhLTRkYWItODcwMi0wMGM4MTE2ZmViODUiLCJwdWJsaXNoYWJsZUtleSI6IjNkMTI5YjJhZmFmNjBjOWQ2MWIwMDAzYmFhMTY5YjM1IiwidXNlcklkIjoiMTIzNDU2IiwiYWN0aW9uIjoibWFuYWdlQXV0aCIsInJlZ2lvbiI6InVzIiwiZW5yb2xsbWVudCI6ZmFsc2UsInJlZGlyZWN0VG9TZXR0aW5ncyI6ZmFsc2V9LCJpYXQiOjE2NzM5MjA1NTl9.DQAmCzp4UkMEGYmNkyJfudcTHXXwoKsyU9aoa72-Jr0&redirect_uri=https://yourredirecturl.com&state=xxxx

3. OIDC Token Endpoint

The POST /oidc/token endpoint is used by the application/client in order to get an access token. Expect to always call this endpoint, parse the access token and determine the state of the Authsignal challenge/auth flow using the action_state claim.

cURL

curl --location --request POST 'https://AUTHSIGNAL_CONNECT_HOSTNAME/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=fa1f91f2236118247ee53c02051d900f' \
--data-urlencode 'client_id=6e7053be-9cca-4dab-8702-00c8116feb85' \
--data-urlencode 'client_secret=xxxx'

Request

• grant_typestring

  The grant type for the OIDC flow, Authsignal only supports authorization_code.

• codestring

  The authorization code returned from the redirect.

• client_idstring

  The Authsignal tenant ID.

• client_secretstring

  The Authsignal tenant secret.

Response

• access_tokenstring

  The access token container the JWT claims including the action_state claim.

POST /oidc/token

{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik5KZ28zR2Z1dEJ4UXNsYXFUanVfOVNLcFdJQXZyV1lEZnI2d0lCbE81dWsifQ.eyJzdWIiOiIxMjM0NTYiLCJleHAiOjE2NzM4MTQ4NDgsImlzcyI6Imh0dHBzOi8veXFqN2phYXV0ZS5leGVjdXRlLWFwaS51cy13ZXN0LTIuYW1hem9uYXdzLmNvbSIsImF1ZCI6IjZlNzA1M2JlLTljY2EtNGRhYi04NzAyLTAwYzgxMTZmZWI4NSIsImFjdGlvbl9jb2RlIjoibWFuYWdlQXV0aCIsImFjdGlvbl9zdGF0ZSI6IkNIQUxMRU5HRV9TVUNDRUVERUQiLCJpYXQiOjE2NzM4MTQyNDh9.Wk_IvWF23zHqM33TobSTQ2D7kqK5Ps0g44nQHaO-_K15JqdItcNk8Wr5p6MStWg5PjA0XIA0hb9KMoZghFdM_KIZmD6i0-ZrgLHdDiilrul8ADDw56nFb3SNLHAG5dVZ4uOP9OKFUaB8hi67l84bRqQHuBvK88pC3QQHxcCfU3eLfAtEQblKLZkkGTlTrkjieIVsT8HW2Hr7kuyiC_QrIuuPoxK4xGovCIM7QUbEHpiB-9pzRoPrHDm2Pz9hu1Jwn7nxCq1Oso90ELvM-qiGGzWVT2EaY4taendYYg3FPKyfrthyAhDkkoC_fhNxUGl3cNxI9NbAigv0rWst5KPUQg","id_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik5KZ28zR2Z1dEJ4UXNsYXFUanVfOVNLcFdJQXZyV1lEZnI2d0lCbE81dWsifQ.eyJzdWIiOiIxMjM0NTYiLCJleHAiOjE2NzM4MTQ4NDgsImlzcyI6Imh0dHBzOi8veXFqN2phYXV0ZS5leGVjdXRlLWFwaS51cy13ZXN0LTIuYW1hem9uYXdzLmNvbSIsImF1ZCI6IjZlNzA1M2JlLTljY2EtNGRhYi04NzAyLTAwYzgxMTZmZWI4NSIsImFjdGlvbl9jb2RlIjoibWFuYWdlQXV0aCIsImFjdGlvbl9zdGF0ZSI6IkNIQUxMRU5HRV9TVUNDRUVERUQiLCJpYXQiOjE2NzM4MTQyNDh9.Wk_IvWF23zHqM33TobSTQ2D7kqK5Ps0g44nQHaO-_K15JqdItcNk8Wr5p6MStWg5PjA0XIA0hb9KMoZghFdM_KIZmD6i0-ZrgLHdDiilrul8ADDw56nFb3SNLHAG5dVZ4uOP9OKFUaB8hi67l84bRqQHuBvK88pC3QQHxcCfU3eLfAtEQblKLZkkGTlTrkjieIVsT8HW2Hr7kuyiC_QrIuuPoxK4xGovCIM7QUbEHpiB-9pzRoPrHDm2Pz9hu1Jwn7nxCq1Oso90ELvM-qiGGzWVT2EaY4taendYYg3FPKyfrthyAhDkkoC_fhNxUGl3cNxI9NbAigv0rWst5KPUQg"}

Action state claim

The access token contains the action_state claim. The following is an example of the claims data payload.

To evaluate the decision, check the value of the action_state claim. If the value is CHALLENGE_SUCCEEDED or ALLOW continue with processing, if CHALLENGE_FAILED or BLOCK is returned termimate any additional authentication processes.

{
  "sub": "123456",
  "exp": 1673814848,
  "iss": "https://yqj7jaaute.execute-api.us-west-2.amazonaws.com",
  "aud": "6e7053be-9cca-4dab-8702-00c8116feb85",
  "action": "manageAuth",
  "action_state": "CHALLENGE_SUCCEEDED",
  "iat": 1673814248
}