OpenID Connect Integration Guide

Integration Guide

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.

  1. Handling the OIDC callback
  2. Creating a verification request
  3. Handling the verification callback
  4. 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.
sequenceDiagram participant end_user as "End User" participant customer_login as "Your Application" participant OIDC_Service as "tru.ID" 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 tru.ID 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

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 and check_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.
sequenceDiagram participant end_user as "End User" participant customer_login as "Your Application" participant OIDC_Service as "tru.ID" 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

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 the code.
  • tru.ID returns to Your Backend Server the result of the PhoneCheck, (match either true or false).
sequenceDiagram participant end_user as "End User" participant customer_login as "Your Application" participant OIDC_Service as "tru.ID" 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

4) 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.
sequenceDiagram participant end_user as "End User" participant customer_login as "Your Application" participant OIDC_Service as "tru.ID" 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

Resources

Download our Developer Console mobile app
Made withacross the 🌍
© 2022 4Auth Limited. All rights reserved. tru.ID is the trading name of 4Auth Limited.