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)

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

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

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

FieldDescription
userIdThe unique ID for this user in your database.
actionThe code of the action (e.g signIn, manageAuthenticators).
appIdThe clientId or appId in the context of the calling identity provider.
scopeThe scopes being requested by the calling identity provider, formatted as a space-separated list.
customA custom JSON object in which you can pass your own data points. Rules can be used to match against these data points.
redirectToSettingsA flag indicating whether to redirect to the Authsignal self-service management screens where the user can add and remove authenticators.

Response

FieldDescription
tokenThe short-lived token to be appended to the OIDC authorize GET request.

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

FieldDescription
clientIdThe Authsignal tenant ID.
tokenThe short-lived token generated via /init-auth.
redirect_uriAll responses from this endpoint result in a redirect to this URI.
stateThe OAuth state parameter. If this is set in the request then it will be returned to the application as part of the redirect_uri.

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

FieldDescription
grant_typeThe grant type for the OIDC flow. Authsignal only supports authorization_code.
codeThe authorization code returned via the redirect back from the authorization endpoint.
client_idThe Authsignal tenant ID.
client_secretThe Authsignal tenant secret.

Response

FieldDescription
access_tokenThe access token container the JWT claims including the action_state claim.

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.

Was this page helpful?