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 namedtoken
- 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 theaction_state
claim to decide whether to proceed with business logic or a authetication pipeline in their flows.
Example OIDC flow diagram
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.
- Initialize Authentication End point (
/init-auth
) - OIDC Authorize End Point (
/oidc/auth
) - 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
{
"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
{"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.
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
{"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
}