Authenticator Integration Guide

The Authenticator API allows developers to integrate extra security into their mobile, web or desktop applications. By using the Authenticator API, you can add a second factor to a web flow, a CLI or Desktop app, or even adopt a passwordless approach with a mobile phone for a web flow. The Authenticator API provides two methods of verification, push notification with tru.ID's silent SIM-Based phone verification, or Time-based One-time Password (TOTP).

This guide will be using three different entities. These are:

• User's Device - the device of the person trying to access the customer application.
• Your Backend - the server that coordinates which verification factors should be used e.g. PhoneCheck, Push Notifications, etc. and how to complete the authentication flow.
• tru.ID API - the API used by the customer to coordinate the authentication flow and issue phone number verifications.

Project setup

Before the Authenticator API is integrated, some configuration is needed. Within the tru.ID project, three fields need to be added:

• issuer_name: The name of the issuer for this Factor. This is shown in authenticator application, whenever you onboard a factor.
• challenge_callback_url: The callback URL where you'll receive the challenge status changes.
• challenge_default_message: The default challenge message to be displayed to the person attempting the authentication.

You can update these three fields within the project of your tru.ID developer console, or you can update it programmatically with this API PATCH request to /console/v0.2/workspaces/{workspace_id}/projects/{project_id}:

PATCH /console/v0.2/workspaces/{id}/projects/{id}
Content-Type: application/json-patch+json
[{
	"op": "add",
	"path": "/configuration",
	"value": {
		"authenticator": {
      "issuer_name": "https://example.com/handle-flow",
      "challenge_callback_url": "https://example.com/app/challenges"
			"challenge_default_message": "Please confirm your login"
    }
	}
}]

200 OK
Content-Type: application/json
{
	"project_id": "..."
	// other project attributes
  // ...
	"configuration": {
		"authenticator": {
      "issuer_name": "https://example.com/handle-flow",
      "challenge_callback_url": "https://example.com/app/challenges"
			"challenge_default_message": "Please confirm your login"
    },
		// other config entries
		// ...
	}
}

Authenticator Workflow Integration

The Authenticator workflow consists of two sections.

1. Onboarding a Factor
2. Issuing Verification Challenges

1) Onboarding a Factor

Initiating the authentication flow and utilizing an Authenticator Application is carried out with the following steps:

• The User Device notifies Your Backend that they wish to onboard authenticator on their device.
• Your Backend makes a POST request to /authenticator/v0.1/factors with the user's phone_number and an external_user_id to tru.ID.
• tru.ID returns a 200 OK response with the body data_url which is a base64 image.
• Your Backend displays this QR code image to the User Device.
• The User scans the QR code with the Authenticator Application.
• Authenticator Application displays a TOTP to the User.
• The User sends the TOTP code to Your Backend.
• Your Backend makes a PATCH request to /authenticator/v0.1/factors/{factorId} with the TOTP code to tru.ID.
• tru.ID returns a success response to show the factor is now active.
• Your Backend returns to the User Device a successful message.

2) Issuing Verification Challenges

Issuing Verification Challenges with the Authenticator API is carries out as follows:

• Your Backend makes a POST request to /authenticator/v0.1/factors/{factorId}/challenge with a reference_id to tru.ID.
• tru.ID returns to Your Backend a 200 OK response with challenge_id in the body.
• Your Backend displays to the User Device a TOTP code capture form.
• User Device opens the Authenticator Application and copies the TOTP code.
• User Device sends the TOTP code to Your Backend.
• Your Backend makes a PATCH request to /authenticator/v0.1/factors/{factorId}/challenge/{challengeId} with the TOTP code to tru.ID.
• tru.ID returns a 200 OK response with the body containing status: VERIFIED.
• Your Backend displays a success message to the user.