Add Custom User Verification

# Introduction

Verification is the process that enrols a device with cryptographic material (M-Pin ID) used for future authentications. With the M-Pin Authentication Protocol, an authentication can’t be facilitated without an M-Pin ID provisioned in advance. There are no restrictions on this process. It can be online - email or SMS verification or offline - user presenting his 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” the client is responsible for verifying their users and MIRACL Trust requires this verification to issue an M-Pin ID.

# How it Works

Custom User Verification allows you to implement any verification flow. You need to verify the identity of the user and push that verification to the platform. When done, the user is redirected to the MIRACL Trust authentication page where he must choose a PIN. After the PIN is confirmed the enrolment process is completed. The device where this process is taking place is provisioned with an M-Pin ID. Users can now authenticate using the PIN chosen for the device. Users 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.

There are two distinct APIs that can be used:

  • MIRACL-managed Custom User Verification,
  • Client-managed Custom User Verification.

# MIRACL-Managed Custom User Verification

This is a beta API and can be a subject of change!

With MIRACL-managed Custom User Verification clients issue a Verification URL 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 user is prompted to choose their PIN and the device is enrolled.

sequenceDiagram Client ->+ RPA: Start verification process for userID RPA ->+ MIRACL: Request Verification URL MIRACL -->- RPA: Verification URL RPA -->- Client: Verification URL Client ->+ MIRACL: Follow Verification URL MIRACL -->- Client: Client secret shares Client --> Client: Enter PIN Client --> Client: Complete identity registration

Using this mechanism users can leverage the MIRACL Trust Authenticator application. When opened on a mobile device the user is redirected to the mobile application and enrolled. This enrolment can be used both to enrol on the mobile device and on a desktop computer using the LOG IN USING MOBILE option of the MIRACL Trust authentication page.

# Implementation

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 user needs to follow the URL from the response to enrol new device. After following it, the user is redirected to the MIRACL Trust authorization endpoint to create new identity.

See reference for more details.

# Client-Managed Custom User Verification

With Client-Managed Custom User Verification clients issue an Activation Code that is used by the user to create a pre-verified identity. The Activation Code is short lived and needs to be issued just before enrolment.

sequenceDiagram Client ->+ RPA: Start verification process for userID RPA ->+ MIRACL: Activation Code MIRACL -->- RPA: MPinID, Activation Code RPA -->- Client: MPinID, Activation Code Client ->+ MIRACL: Initiate Registration with activation code MIRACL -->- Client: Client secret shares Client --> Client: Enter PIN Client --> Client: Complete identity registration

This mechanism is not supported by the MIRACL Trust Authenticator mobile application.

# Implementation

After the user is verified, their identity needs to be activated in the MIRACL Platform. You can do this by making an authenticated POST request to https://api.mpin.io/activate/initiate.

curl \
    --request POST \
    --user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
    --data '{
        "userId": "'"${USER_ID}"'",
        "deviceName": "'"${DEVICE_NAME}"'",
    }' \
    https://api.mpin.io/activate/initiate

With the following response:

{
    "mpinId": <MPIN_ID>,
    "hashMPinId": <HASH_MPIN_ID>,
    "actToken": <ACTIVATION_TOKEN>,
    "expireTime": <EXPIRE_TIME>,
    "redirectURI": ""
}

All values are redacted.

After a successful activation request, the user needs to be redirected to the OIDC authorization endpoint (as described in Integrate through OIDC). You should pass the activation token from response to the authorization endpoint as an URL parameter acttoken. Also you should pass the user ID to prerollid so you have it prefilled in the PIN Pad.

Here is an example of an authorization endpoint URL:

https://api.mpin.io/authorize?client_id=<YOUR_CLIENT_ID>&redirect_uri=<YOUR_REDIRECT_URL>&response_type=code&scope=openid+email&acttoken=<ACTIVATION_TOKEN>&prerollid=<USER_ID>

See reference for more details.

# Configuration

Before using any of the Custom User Verification mechanisms, you need to change the settings of your project from the MIRACL Trust Management Console. After authenticating in the console, navigate to your Project and choose Settings from the Administration navigation section. There you find a section for the Verification Method, which has value Email. You can change this value to Custom. This enables additional configuration options for a customized verification:

  • Custom Verification URL - If the users navigate to the login page without having a pre-registered identity, they see a screen that requests they start the verification process. The Custom Verification URL is the link on your system to which the user is redirected to start the verification process.

  • Custom Verification Text - Before being redirected to the Custom Verification URL, the user sees a screen explaining how to verify. 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 a user identifier. If you are using custom user verification where this is not a requirement, you can have an identity 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 user identifier. When you set the User ID Type to Email it defaults to Email. When you set it toAlphanumeric it defaults to Identity.

Configuring Custom User Verification incurs additional costs for your account.