Introduction
Pluggable Verification is what enables the provision of custom verification methods instead of the default email confirmation process. This flow consists of two parts:
-
External verification - The Relying Party Application (RPA) creates their own unique verification flow based on their needs. Once the verification has passed, the RPA makes a request to the MIRACL platform to register an MPin Identity and receive an activation code for the given user.
-
User registration - With the received activation code, the Client activates the user identity and finalizes the registration process on our platform.
sequenceDiagram Client ->+ RPA: Start verification process for userID RPA->+MIRACL: Generate MPin Identity and 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
Configuration
Before using pluggable verification, you need to change the settings of your
project from the MIRACL Trust Management Console. After authenticating in the
console, navigate to Settings. There you will find a section for the
Verification Method, which should have a value of Default (email)
. You
can change this value to Custom
and this will reveal the additional
configuration options for a customised verification:
- Verification URL - If the users navigate to the login page without having a pre-registered identity, they will see a screen that tells them they need to start the verification process. The Verification URL is the link on your system to which the user will be redirected in order to start the verification process.
- Verification Expire Time - The expiration time for the verification session in seconds. Has a default value of 3600 (1 hour).
- Identity Type - By default MIRACL Trust uses an email address for a user
identifier. If you are using pluggable verification that is not a requirement,
as 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. - Identity Type Label - The label that will be displayed when refering to the
user identifier. When the Identity Type is set to
Email
it will default toEmail
and when set toAlphanumeric
it will default toIdentity
. - Create Identity Text - Before being redirected to the Verification URL,
the user will see a screen explaining to them how to verify. Here you can
specify a custom text to be displayed on that screen. It will default to
We need to verify this device before you can register. Select Start Verification to be redirected to the verification page.
Configuring Pluggable Verification will incur additional costs for your account.
Authorization endpoint
After a successful activation request, the user needs to be redirected to the
OIDC authorization endpoint (as described in Integrate through
OIDC). The activation
token from the response should be passed to the authorization endpoint as an URL
parameter acttoken
. In addition the user ID for which the activation was done
needs to also be passed as prerollid
. Here is an example of an authorization
endpoint URL:
https://api.mpin.io/authorize?client_id=wplkh5ertuboa&redirect_uri=https%3A%2F%2Fexample.com%2Flogin&response_type=code&scope=openid+email+profile&acttoken=ACTIVATION_TOKEN&prerollid=user@example.com
API reference
- POST
/activate/initiate
- Creates an MPin Identity and receives an activation token used to activate the identity during the registration process.
Authorization: "Basic <base64(clientId:clientSecret)>"
Payload:
{
userId: string,
deviceName: string
}
Response:
{
mpinId: string,
hashMPinId: string,
actToken: string,
expireTime: integer
}