Open ID Connect (OIDC)

Authsignal’s OIDC integration allows clients to federate passwordless and MFA flows to Authsignal, securely returning back the outcome of the authentication challenge through a set of claims.

​

Overview

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

1. The authorization endpoint (/oidc/auth) will only work within the scope of an already identified resource owner - typically a user ID. This extension requires a short-lived token to be generated before redirecting the resource owner to the authorization endpoint. The endpoint to obtain a short-lived token is our init auth endpoint (/init-auth). This token can then be appended to the authorization endpoint (/oidc/auth) as a token URL param.

2. When redirecting back to the resource owner, Authsignal will always respond with a authorization_code grant type regardless of the outcome of the challenge. It is important for the client to exchange the authorization_code for an access token via our token endpoint (/oidc/token) and then inspect the action_state claim to determine the result of the challenge.

There are 3 key endpoints:

1. Init endpoint (/init-auth)
2. OIDC authorize endpoint (/oidc/auth)
3. OIDC token endpoint (/oidc/token)

​

Regions

The OIDC API is served on the connect.authsignal.com domain and is available in 3 regions.

​

Init endpoint

POST /init-auth

The init 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 --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

​

Response

​

OIDC Configuration endpoint

GET /oidc/.well-known/openid-configuration

This endpoint is the standard configuration endpoint which can be used to determine the provider’s other endpoints and metadata.

​

OIDC Authorize endpoint

GET /oidc/auth

This 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 param in the request alongside the other compulsory OIDC parameters. This token would have been generated using the /init-auth call prior.

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

​

OIDC Token endpoint

POST /oidc/token

This endpoint is used by the client application to obtain an access token. Expect to always call this endpoint and determine the state of the Authsignal challenge/auth flow by inspecting the action_state claim.

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

​

Response

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

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

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.