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, in this case Authsignal will act as a authentication/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 end point (/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 end point via our initialization auth end point (/init-auth). The access token geneated will be appended to the authorization end point (/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

End points

As documented in the above diagram and description, there are 3 important end points in-order to succesfully integrate the Authsignal OIDC flow.

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

End point host names

Region	API endpoint host
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 end point is a pre-requisite before redirecting the user to the OIDC Authorize end point. This end point allows the authorize end point 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 name of the action e.g signIn, manageAuthenticators.

• appIdstring | undefined

  The clientId of appId in the context of the calling Identity Provider.

• scopestring

  The scopes being requested of the calling identity provider, this should conform to standard OIDC as a space separated list of scopes

• customobject | undefined

  A custom JSON object. Use this attribute 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 End points

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

Authsignal's OIDC connector supports authorization_code grant types.

Type	End point
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 End point

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

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

• statestring | undefined

  An opaque value, used for security purposes. If this request parameter is set in the request, then it is 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 End point

The POST /oidc/token endpoint is used by the application/client in order to get an access token, expect to always call this end point, 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 API Secret Key

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_code": "manageAuth",
  "action_state": "CHALLENGE_SUCCEEDED",
  "iat": 1673814248
}