OpenID Connect (OIDC) 1.0 is an identity layer that sits on top of the OAuth 2.0 protocol. This layer enables clients to verify the identity of the end user based on the authentication requirements carried out by the authorization server. OIDC allows the customer to control how many verification steps are required to complete the authentication flow. OIDC also allows you to obtain basic profile information about the end user in a REST-like way.
This guide will walk you through a common approach to integrating an OIDC flow with your application using tru.ID's PhoneCheck product as the extra step of verification.
This guide will be using four different entities. These are:
- End User's Device - the device of the person trying to access the customer application.
- Your Application - the customer application which requires end-users to log in.
- tru.ID API - the API used by the customer to coordinate the authentication flow and issue phone number verifications.
- Your Backend Server - the server that coordinates which verification factors should be used e.g. PhoneCheck, Push Notifications, etc. and how to complete the authentication flow.
OpenID Connect (OIDC) Workflow Integration
The OIDC workflow consists of four sections.
- Handling the OIDC callback
- Creating a verification request
- Handling the verification callback
- Completing the authentication flow
1) Handling the OIDC callback
Initiating the authentication flow and handling the OIDC callback is carried out with the following steps:
- End User initates the request to log in to the protected application.
- Your Application redirects the flow to the tru.ID API with a
GET
request to/oauth2/v1/auth
. - End User enters their required login hint (phone number, username for example), which are submitted to tru.ID.
- A POST request is made from tru.ID to the
flow_post_url
on Your Backend Server. - Your Backend Server uses the information provided to look up the End User.
- If an End User exists, Your Backend Server now has located their user record, including their Phone Number.
End User initiates authentication flow
tru.ID makes a POST request to `flow_post_url` on Your Backend Server
2) Creating a verification request
- Your Backend Server makes a
POST
request to/phone_check/v0.2/checks
at tru.ID to initiate the PhoneCheck process. - tru.ID returns to Your Backend Server a
check_id
andcheck_url
. - Your Backend Server makes a
PATCH
request to/oidc/v0.2/flows/{flow_id}
at tru.ID with the relevant information. - tru.ID returns a status, such as a
200 OK
response. - Your Backend Server redirects the End User to the
qr_code_delegation_url
.
Your Backend Server creates a PhoneCheck with tru.ID's API
Your Backend Server send PATCH
request to tru.ID's flow, signalling that you want tru.ID to take over the verification UI.
PATCH
request to tru.ID's flow, signalling that you want tru.ID to take over the verification UI.3) Handling the verification callback
- tru.ID redirects back to the End User with a
code
. - End User follows the redirect to Your Backend Server.
- Your Backend Server makes a
PATCH
request to tru.ID with thecode
. - tru.ID returns to Your Backend Server the result of the PhoneCheck, (
match
eithertrue
orfalse
).
Backend Server makes PATCH
request to tru.ID PhoneCheck API
PATCH
request to tru.ID PhoneCheck API4) Completing the authentication flow
- Your Backend Server makes a
PATCH
request to/oidc/v0.1/flows/{flow_id}
at tru.ID with the userinfo claims, e.g.sub: user_id
. - tru.ID redirects the End User to the
flow_result_url
. - Your Application makes a
POST
request to/oauth2/v1/token
with the code from the previous step to tru.ID. - tru.ID returns to Your Application an ID token.
Your Backend Server sends a PATCH
request to tru.ID's flows, updating the OIDC flow
PATCH
request to tru.ID's flows, updating the OIDC flow