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 IDlayr'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.
- IDlayr 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 IDlayr API with a
GETrequest to/oauth2/v1/auth. - End User enters their required login hint (phone number, username for example), which are submitted to IDlayr.
- A POST request is made from IDlayr to the
flow_post_urlon 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.
sequenceDiagram
participant end_user as "End User"
participant customer_login as "Your Application"
participant OIDC_Service as "IDlayr"
participant customer_server as "Your Backend Server"
activate end_user
activate customer_login
activate OIDC_Service
note over end_user, customer_server: Handling OIDC callback
end_user ->> customer_login: Login to protected application
customer_login-->>end_user: Redirect to IDlayr auth url
end_user ->> OIDC_Service: GET /oauth2/v1/auth
alt login_hint not present:
OIDC_Service ->> end_user: Show login hint UI
end_user ->> OIDC_Service: Submit phone number, username, etc.
end
OIDC_Service ->> customer_server: POST flow_post_url
customer_server ->> customer_server: lookup user for login_hint e.g. on DB, User Directory, etc.
note over customer_server: you now should have access to a user profile and thus a phone number
deactivate OIDC_Service
deactivate customer_login
deactivate end_user
End User initiates authentication flow
IDlayr makes a POST request to `flow_post_url` on Your Backend Server
2) Creating a verification request
- Your Backend Server makes a
POSTrequest to/phone_check/v0.2/checksat IDlayr to initiate the PhoneCheck process. - IDlayr returns to Your Backend Server a
check_idandcheck_url. - Your Backend Server makes a
PATCHrequest to/oidc/v0.2/flows/{flow_id}at IDlayr with the relevant information. - IDlayr returns a status, such as a
200 OKresponse. - Your Backend Server redirects the End User to the
qr_code_delegation_url.
sequenceDiagram
participant end_user as "End User"
participant customer_login as "Your Application"
participant OIDC_Service as "IDlayr"
participant customer_server as "Your Backend Server"
activate customer_server
activate OIDC_Service
note over end_user, customer_server: Verification Request
customer_server ->> OIDC_Service: POST /phone_check/v0.2/checks
OIDC_Service ->> customer_server: check_id + check_url
customer_server ->> OIDC_Service: PATCH /oidc/v0.1/flows/{flow_id}
OIDC_Service ->> customer_server: 200 OK
customer_server -->> end_user: Redirect to qr_code_delegation_url
deactivate OIDC_Service
deactivate customer_server
Your Backend Server creates a PhoneCheck with IDlayr's API
Your Backend Server send PATCH request to IDlayr's flow, signalling that you want IDlayr to take over the verification UI.
PATCH request to IDlayr's flow, signalling that you want IDlayr to take over the verification UI.3) Handling the verification callback
- IDlayr redirects back to the End User with a
code. - End User follows the redirect to Your Backend Server.
- Your Backend Server makes a
PATCHrequest to IDlayr with thecode. - IDlayr returns to Your Backend Server the result of the PhoneCheck, (
matcheithertrueorfalse).
sequenceDiagram
participant end_user as "End User"
participant customer_login as "Your Application"
participant OIDC_Service as "IDlayr"
participant customer_server as "Your Backend Server"
activate OIDC_Service
activate customer_server
activate end_user
note over end_user, customer_server: QR code verification flow
OIDC_Service -->> end_user: Redirect with code
end_user ->> customer_server: Follow redirect
customer_server ->> OIDC_Service: exchange code for PhoneCheck result
OIDC_Service ->> customer_server: PhoneCheck result match=true
deactivate end_user
deactivate customer_server
deactivate OIDC_Service
Backend Server makes PATCH request to IDlayr PhoneCheck API
PATCH request to IDlayr PhoneCheck API4) Completing the authentication flow
- Your Backend Server makes a
PATCHrequest to/oidc/v0.1/flows/{flow_id}at IDlayr with the userinfo claims, e.g.sub: user_id. - IDlayr redirects the End User to the
flow_result_url. - Your Application makes a
POSTrequest to/oauth2/v1/tokenwith the code from the previous step to IDlayr. - IDlayr returns to Your Application an ID token.
sequenceDiagram
participant end_user as "End User"
participant customer_login as "Your Application"
participant OIDC_Service as "IDlayr"
participant customer_server as "Your Backend Server"
activate OIDC_Service
activate end_user
activate customer_server
note over end_user, customer_server: Complete Authentication Flow
customer_server ->> OIDC_Service: PATCH /oidc/v0.1/flows/id with userinfo claims e.g. "sub: user_id"
deactivate customer_server
OIDC_Service -->> end_user: Redirect to flow_result_url
end_user ->> customer_login: Follow redirect
customer_login ->> OIDC_Service: POST /oauth2/v1/token with code from previous step
OIDC_Service ->> customer_login: ID token
deactivate end_user
deactivate OIDC_Service
Your Backend Server sends a PATCH request to IDlayr's flows, updating the OIDC flow
PATCH request to IDlayr's flows, updating the OIDC flow
