Custom User Verification

# Introduction

Verification is the process that enrols a device with cryptographic material used for future authentications. With the M-PIN Authentication Protocol, an authentication can’t be facilitated without a User ID provisioned in advance. There are no restrictions on this process. It can be online - email or SMS verification or offline - end user presenting their national ID to a representative. MIRACL Trust uses email verification by default and Custom User Verification is the mechanism to implement a bespoke verification flow. Using Custom User Verification, you are responsible for verifying your end users and MIRACL Trust requires this verification to issue a User ID.

# How It Works

Custom User Verification allows you to implement any verification flow. You need to verify the User ID of the end user and push that verification to the platform which generates a verification URL. When the client application recieves the verification URL, it should confirm the verification by calling the getActivationToken method. This is handled authomatically if you use the MIRACL Trust authorization page or the MIRACL Trust Authenticator. Otherwise you can use the getActivationToken method of the Client JS Library, Android or iOS libraries.

Then the end user is prompted to choose a PIN. After the PIN is confirmed, the enrolment process is completed. The device where this process is taking place is provisioned with a User ID. End users can now authenticate using the PIN chosen for the device. They can go through the verification process for each device they want to use for authentication or use QuickCode to enrol additional devices using the already enrolled one.

# Custom User Verification

With MIRACL-managed Custom User Verification, a Verification URL is issued that can be used to enrol a device without any verification from the platform side. This Verification URL can be used both during the actual verification (sent as email, SMS, IM to verify the identity) or after the verification. When opened, the end user is prompted to choose their PIN and the device is enrolled.

sequenceDiagram Client ->+ RPA: Start verification process for User ID RPA ->+ MIRACL: Request Verification URL MIRACL -->- RPA: Verification URL RPA -->- Client: Verification URL Client ->+ MIRACL: Request Activation Token MIRACL -->- Client: Activation token Client --> Client: Enter PIN Client --> Client: Complete User ID registration

# Implement the Verification

The Verification URL is generated by making an authenticated POST request to https://api.mpin.io/verification.

curl \
    --request POST \
    --user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
    --data '{
        "userId": "'"${USER_ID}"'",
        "deviceName": "'"${DEVICE_NAME}"'",
        "clientId": "'"${YOUR_CLIENT_ID}"'",
        "redirectURI": "'"${YOUR_REDIRECT_URI}"'",
        "expiration": "'"${EXPIRATION}"'",
        "scope": ["openid", "email"],
        "delivery": "no"
    }' \
    https://api.mpin.io/verification

With the following response:

{
  "verificationURL": "https://api.mpin.io/verification/confirmation?user_id=<USER_ID>&code=<CODE>"
}

All values are redacted.

The end user needs to follow the URL from the response to enrol a new device.

See MIRACL Trust Backend API for more details.

# Configure the Verification

Before using any of the Custom User Verification mechanisms, you need to:

Go to the MIRACL Trust Portal to change the settings of your project.
Go to your project.
Select User Verification in the Configuration navigation section.
In the Verification Method dropdown, change the value from Email to Custom. This enables additional configuration options for customised verification:

Custom Verification URL - If the end user navigates to the login page without having a pre-registered User ID, they are requested to start the verification process. The Custom Verification URL is the link on your system to which the end user is redirected to start the verification process.
Custom Verification Text - Before being redirected to the Custom Verification URL, the end user sees a screen with verification instructions. Here you can specify a custom text to be displayed. The default text is:
```
We need to verify this device before you can register. Select Start Verification to be redirected to the verification page.
```
User ID Type - By default, MIRACL Trust uses an email address as an end-user identifier. If you use Custom User Verification where this is not a requirement, you can have an User ID scheme that does not rely on emails. You can change the value to Alphanumeric to allow for other identifiers like usernames or account numbers.
User ID Text - The label that is displayed when referring to the end-user identifier. When you set the User ID Text to Email, it defaults to Email. When you set it to Alphanumeric, it defaults to User ID.

Configuring Custom User Verification incurs additional costs for your account.

# Use-Cases

# Manual Invitation Creation

Sometimes online verification is not possible. In those cases, a manual flow can be implemented. The idea in this kind of flows is that a person or a group of people are responsible for the verification of end users. When an end user wants to be enroled they need to identify in front of those people. After successful identification, the end user is issued some kind of one-time code that they can use to establish the enrolment on a device of their choosing. This code can be transferred to the end user using trusted messenger, alternative email address, QR Code printed on paper, etc.

This kind of flow is suitable in many cases.

Internal use-case for a company. The HR team is responsible for the verification.
Bank use-case. End users need to present identification to a bank assistant in the office of the bank. The assistant issues a verification code.
Online platform which requires in-person identification.
Institutions that can verify people on the phone. The user can call to be verified based on some secret questions. The user is issued a code that they can use an online system to enrol.

# SMS Validation

Many applications nowadays use the mobile phone number as an ID for an end user. Phone numbers can easily be verified using code sent via SMS.

# Common Considerations

Code expiration

Although in many flows there can be a considerable amount of time between verification and enrolment, it is always a good idea to have a reasonable expiration for the verification code.

Code invalidation

Consider invalidating codes after they are used. In some cases, this may not be practical but it is worth the security benefits to consider it.

There are possible attacks against verification flows using phone numbers like SIM Swap.

# Useful Links

MIRACL Trust Verification Service is a service implementing various useful verification flows.