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

RegionAPI 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

The unique ID for this user in your database.

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

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

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

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

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

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.

TypeEndpoint
OIDC Discoveryhttps://AUTHSIGNAL\_CONNECT\_HOSTNAME/oidc/.well-known/openid-configuration
Authorizationhttps://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

The Authsignal tenant ID.

The short lived token generated in /init-auth.

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

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

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

The authorization code returned from the redirect.

The Authsignal tenant ID.

The Authsignal tenant secret.

​
Response

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
}

Was this page helpful?