This document describes the user interface and the steps that a user needs to go through to get authenticated. It is assumed that the Trust1Connector is installed.

From the customers webpage the user is redirected to the authentication pages of Trust1Team. These pages can be branded according to the colour scheme and logo of the customer.

Landing page for first authentication

The user is first requested to link his mobile to his account so that in a later stage he can quickly authenticate using his mobile phone and a OTP (One Time Password)

In the top right corner that language can be changed. Default is English, but also Dutch, French and German are offered. Other languages can be added on customer request.

Below the logo, the authentication steps are indicated. Once a step is completed the next step will light up so that the user knows where he is in the process.

After entering a valid phone number the customer will receive a OTP on this mobile.

The OTP is a 4-digit numerical code. The user needs to enter this number in the appropriate field. The user has a limited time ( configurable parameter) in which the OTP is valid. If the user did not receive an OTP he can request to receive a new one. (Resend OTP token)

If the end-user enters a correct OTP, he will be redirected to the identification page (third step).

The user can choose between different identification means: Card reader or Smart-ID

Card reader

If the end-user does not have a card reader connected to his device or his ID eID inserted in the card reader The Identity selection page will remain blanc. There will not be any available readers.

If the end-user has not got the Trust1Connector installed he will be asked to do so (.)

The blue banner on the screen is an example on how "recent" discovered issue with an OS is tackled until a new version of the T1C is released or until the OS is updated.

By clicking on the available identity the certificates of the eID are read.

When the certificates are valid, the user will be receive a green confirmation that the certificates are qualified and gets a button "Authentication" that will lead him to the next step where he needs to enter his pincode.

If the certificates are not valid, the token is expired or the user is trying to use the token twice, the user will get a red warning of invalid certificates.

After pressing the authenticate button the user receive a pop-up window in which he needs to enter the pin-code of his eID.

After entering a valid pin-code the user will be redirected to the customers portal. The user can also cancel the authentication by pressing the cancel button.

The user will only have 3 attempts to enter the correct pin-code. If the users enters 3 consecutive times the wrong pin-code his ID card will be blocked.

Smart-ID

The user can also chose to use Smart-ID as an authentication method.

After selecting Smart-ID the user can either enter his National Registration Number or scan the QR-code that is displayed.

Using National Registration Number

The user needs to enter his National Registration Number and click continue. In the next screen the users needs to click on authenticate to continue

The user will than receive a code on the screen and a notification on his mobile phone to verify the code. The user will have to enter his authentication pin-code (pin-code 1) in the Smart-ID app to be authenticated.

Using QR-code

If the user scans the QR-code with this Smart-ID app he will be asked to enter his authentication pin-code and is than immediatly authenticated. Please note that for security reasons the QR-code changes every second. This does not impact the functionality.

Endpoints

Acceptance/Staging: https://acc-auth.t1t.eu

Production: https://auth.t1t.eu

Integration Steps

The integration can be summarized in 2 required steps, and 1 optional step:

• start a new session and redirect the user to the authentication page

• parse the result (through a webhook) and give access to requester (user of your application)

• [optionally] retrieve a detailed validation report

Postman Collection

The HTTP REST collection is available on

Overview Sequence Flow

The following sequence diagram denotes partially the steps executed, with regards to the user who needs to be authenticated.

Start a new Session

The initial call sets the context for a new session. The context must be unique for each user who needs to log in. Once the context has been created a JWT is issued and can be used to redirect the user to the authentication page.

Set Context

A new session can be started by initiating a POST request with your provided 'apikey':

Properties

Example Response

The HTTP reponse contains a Json reponse with a token property

The token MUST be set for the end-user to start the flow on the Authentication web page.

The token is added as a query parameter on the URL for the Authentication web page:

From here the user will be guided through the authentication flow

Optional: Provide a public key for response encryption

In the set context request, an optional public key can be provided by the web application who wants to use the Trust1Authentication service.

When a public key is provided, the biometric information from the authentication user will be encrypted with the provided public key, on the user's device itself, avoiding any data to be leaked during the authentication flow.

No sensitive data is stored on the Trust1Authentication service.

Parse the received result (success)

Once the user has completed the flow, the webhookUri will be used, prior to initiating the redirect (redirectUri).

The webhook MUST be a POST HTTP endpoint, who will expect the following data to be received:

The included bio data is provided as a Json string (encrypted only if the session has been created with a public key property).

The Json has the following format:

When there is no bio information available (typically for PKCS11 only tokens), the bio not be provided upon a successful authentication response

Parse the received result (failed)

When the session has been expirect, and no successfull result has been pushed OR when the use case fails in a way that the end-user is blocked, a response will be sent to the webhook with isSuccess: false An additional error property is added with more explanation. The session context and tracker is always provided in the respone:

Parse the received result (cancelled)

When a user cancels, the webhook is called with a similar response as the failure response. The main difference is that the cancel_state property will be set to false

Examples

Generate 4096 bit RSA Keypair

The RSA keypair generated MUST have a size of 4096 bit:

Public key must be send in a base64 encoded format!

Copy base64 encoded public key as a single string to the clipboard (Mac example):

Setting up the session context, becomes

The following response contains a token, which can be used to redirect the user to the login page:

Redirect URL:

These pages describe the installation of the Trust1Connector during the first usage of Trust1Authentication

After the verification of the mobile number, the Trust1Authenticator will verify if the Trust1Connector is installed on the end-users device. If this is the case and the end-user has a card reader with his eID installed, the eID will be read and used for the authentication.

If the Trust1Authentication detects that the Trust1Connector is not installed the user will be requested to download the Trust1Connector and install it. Trust1Authentication will detect he operating system of the end-users device and present to him the most appropriate links. If the end-user would like to use a different version of the Trust1Connector he can click on "all download links".

The Trust1Connector will be downloaded. You can retrieve the package in your donwload folder.

Install the package

After installation of the Trust1Connector Trust1Authentication will continue the user flow if an eID is available.

The end-user will be asked to give his consent

After giving consent the authentication flow will continue as described in the User manual.

High-level architecture

The following component diagram denotes the interfaces and services involved:

Introduction

The T1Authentication service, hosted by Trust1Team is an authentication page which can be used to authenticate users to your application using:

• smart cards, tokens or other hardware identity means

• Smart-ID mobile app

The service is web layer on top of the to enable smart token interactions with a local device. The concept enforced by using the Trust1Connector, is to enable a decentralized Identity borker which in solely control of the end-user, the user of your web application.

Benefits when using the Trust1Authentication service:

• very quick and easy integration (see further and try it out)

• dynamic configurable means (ways for a user to autenticate)

• detailed report for certificate validation

User Interaction Flow

The Relying Party can opt-in for multiple authentication means. An authentication mean is for example:

• 'beid': use Belgian eID smart card for authentication

• 'smart-id: use SmartID mobile application for user authentication

Depending on the allowed authentication means, the user is redirected to the authentication page. The authentication flow is summarized in the image below:

The steps for a user Authentication are:

• Verify phone

• Verify secret (OTP)

• [Optional] Select Authentication mean

• Identify

After a succesfull user authentication, the user is redirected back to the Relying Party application. When the Relying Party has provided a webhook initially, a HTTP POST request will be provided to the application, prior to the user redirect.

The POST request, contains the following information:

• result status

• session context (RP application parameters, correlation ID)

• session tracker information (process step results, tracing information)