> ## Documentation Index
> Fetch the complete documentation index at: https://docs.authsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Open ID Connect (OIDC)

> Learn about Authsignal's OIDC integration model.

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

| Region        | API URL                             |
| ------------- | ----------------------------------- |
| US (Oregon)   | `https://us-connect.authsignal.com` |
| AU (Sydney)   | `https://au-connect.authsignal.com` |
| EU (Ireland)  | `https://eu-connect.authsignal.com` |
| CA (Montreal) | `https://ca-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.

```bash cURL theme={null}
curl --location --request POST 'https://AUTHSIGNAL_CONNECT_HOSTNAME/init-auth' \
--header 'Authorization: Basic YOUR_TENANT_SERVER_API_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userId": "123456",
    "action": "manageAuth",
    "appId": "7aae2f7a-394a-415a-a386-4ea218f6f579",
    "scope": "readonly write changeprofile",
    "email": "user@example.com",
    "emailVerified": true,
    "phoneNumber": "+14155552671",
    "phoneNumberVerified": true,
    "custom": {
        "yourCustomBoolean": true,
        "yourCustomString": "NZD",
        "yourCustomNumber": 10.00
    },
    "redirectToSettings": false
}'

```

### Request

<ParamField body="userId" type="string" required>
  The unique ID for this user in your database.
</ParamField>

<ParamField body="action" type="string" required>
  The code of the action (e.g `signIn`, `manageAuthenticators`).
</ParamField>

<ParamField body="appId" type="string">
  The clientId or appId in the context of the calling identity provider.
</ParamField>

<ParamField body="scope" type="string">
  The scopes being requested by the calling identity provider, formatted as a space-separated list.
</ParamField>

<ParamField body="phoneNumber" type="string">
  The user's phone number in E.164 format (e.g., +14155552671).
</ParamField>

<ParamField body="email" type="string">
  The user's email address.
</ParamField>

<ParamField body="emailVerified" type="boolean">
  When `true` and `email` is provided, syncs the user's email authenticator to the new email
  address. This is useful when integrating with identity providers where the email has already
  been verified by the IdP.
</ParamField>

<ParamField body="phoneNumberVerified" type="boolean">
  When `true` and `phoneNumber` is provided, syncs the user's phone authenticator to the new
  phone number. This is useful when integrating with identity providers where the phone number
  has already been verified by the IdP.
</ParamField>

<ParamField body="custom" type="object">
  A custom JSON object in which you can pass your own data points. Rules can be used to match
  against these data points.
</ParamField>

<ParamField body="redirectToSettings" type="boolean">
  A flag indicating whether to redirect to the Authsignal self-service management screens where the
  user can add and remove authenticators.
</ParamField>

### Response

<ResponseField name="token" type="string" required>
  The short-lived token to be appended to the OIDC authorize GET request.
</ResponseField>

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

```bash cURL theme={null}
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

<ParamField query="client_id" type="string" required>
  The Authsignal tenant ID.
</ParamField>

<ParamField query="token" type="string" required>
  The short-lived token generated via `/init-auth`.
</ParamField>

<ParamField query="redirect_uri" type="string" required>
  All responses from this endpoint result in a redirect to this URI.
</ParamField>

<ParamField query="state" type="string">
  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.
</ParamField>

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

```bash cURL theme={null}
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

<ParamField body="grant_type" type="string" required>
  The grant type for the OIDC flow. Authsignal only supports `authorization_code`.
</ParamField>

<ParamField body="code" type="string" required>
  The authorization code returned via the redirect back from the authorization endpoint.
</ParamField>

<ParamField body="client_id" type="string" required>
  The Authsignal tenant ID.
</ParamField>

<ParamField body="client_secret" type="string" required>
  The Authsignal tenant secret.
</ParamField>

### Response

<ResponseField name="access_token" type="string" required>
  The access token containing the JWT claims including the action\_state claim.
</ResponseField>

<ResponseField name="id_token" type="string" required>
  The ID token containing the JWT claims including the action\_state claim.
</ResponseField>

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

```json theme={null}
{
  "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",
  "action_verification_method": "AUTHENTICATOR_APP",
  "is_enrolled": true,
  "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, terminate any additional authentication processes.