Start Seamless Integration

The MIRACL Trust platform allows for complete customisation of the verification, authentication and signing flows, empowering you to create secure solutions tailored to your specific needs while ensuring an excellent user experience.

This integration allows you to seamlessly integrate the authentication client within your website by letting you host it on your domain with your unique design and implementation. MIRACL Trust provides all the necessary tools you need to achieve that quickly. By implementing a custom PIN pad, you can fully customise the authentication clients’ functionality and user experience. You have endless possibilities, such as custom design and deep integration with the website, custom rules for PIN selection, integrated device management, conditional logic when the device is not enrolled, and easy invocation for signing whenever necessary.

Before you begin, you must register on MIRACL Trust.

# Integrate with Your Application

This integration requires you to create a custom client. For this purpose, we have provided the Client JS Library, which is available on GitHub. You can install it as an NPM package by using the npm install command. With the Client JS Library, you can implement the registration, verification and authentication processes for your client.

# Verification

Before an end user is authenticated, they must register the device they want to authenticate on. For this to happen, you need to implement a verification process. You can use the built-in email verification provided by MIRACL Trust out of the box. For use cases where it is impractical, MIRACL Trust offers Custom User Verification as an alternative. This mechanism allows you to create a personalised verification flow tailored to your use case.

# Registration

After the verification process is completed, the end user’s device must be registered. For this to happen, get an activation token using the getActivationToken method and the received Verification URL:

try {
  const result = await mcl.getActivationToken(
    "https://yourdomain.com/verification/confirmation?userId=alice@miracl.com&code=theVerificationCode",
  );
  console.log(result);
} catch (err) {
  // Handle any potential errors
}

Then pass the User ID (email or any string you use for identification) and activation token to the register method:

try {
  const result = await mcl.register(userId, actToken, function (passPin) {
    // Here you need to prompt the user for their PIN
    // and then call the passPin argument with the value
    passPin(pin);
  });
  console.log(result);
} catch (err) {
  // Handle any potential errors
}

# Authentication

If the registration is successful, the end user can then be authenticated. The custom browser authentication using the MIRACL Trust Client JS Library gives you full control over all aspects of the authentication client. It provides two options:

Authenticate users on the same application

In this case, the authenticate method generates a JWT authentication token that is then sent to the application server for verification.

Authenticate users on another application via an AppLink, QR code or push notification.

For information about implementing the authentication with the Client JS Library, see the corresponding article in the Authentication section of the documentation.

# Digital Signing

Additionally, you can use the Client JS Library to integrate the MIRACL Trust’s Designated Verifier Signature (DVS) scheme for digital signing into your web application. DVS allows a client entity to sign a message/document which can be verified only by the designated verifier. For more information, see Client JS Library under Digital Signature.

# MIRACL Custom Client Sample

To see the functionality in action, check the MIRACL Custom Client Sample. Note that it is only a client-side example and does not include what needs to be done on the back end.

# Preliminary Steps

Before you set up the sample, you must do some preliminary configurations:

Go to the MIRACL Trust Portal and create a project.
On the General page, set Allowed CORS Origins to http://localhost:9090.
On the User Verification page, set the Verification Method to Email Code.

# Configure the Sample

To set up the sample:

Clone the project:

git clone https://github.com/miracl/custom-client-sample.git

Install the project dependencies:
```
npm install
```
Create a .env file under the root project directory:
```
touch .env
```
Populate it with the following environment variable and replace <YOUR_PROJECT_ID> with your Project ID, which you can get from the General page in the MIRACL Trust Portal:
```
VITE_MIRACL_PROJECT_ID=<YOUR_PROJECT_ID>
```
Execute the following command to run the sample:
```
npm start
```

# Run the Sample

Go to http://localhost:9090 to access the sample.
Type your email address and click Submit. An email with a verification code is sent to your email address.
Copy the verification code from the email, paste it into the sample, and click Submit.
Choose a PIN for your device and click Submit. Your device is now registered.
To authenticate, enter the PIN and click Submit. A signed JSON Web Token (JWT) is then displayed.

To properly finish the authentication process, the token must be sent to the application server for verification. You must use a JWT library that is suitable for your back end. To verify the token signature, use the MIRACL Trust JSON Web Key Set (JWKS) endpoint. The keys should be cached for subsequent requests, so you might need to fetch them again periodically to ensure they are up to date or to request them again if a token arrives with an unknown key ID. Make sure your implementation does not assume the keys don’t change as they will be periodically rotated.

# Security

The MIRACL Trust PIN Pad, provided by the platform, is built following the best security practices in its architecture and implementation. It is carefully vetted to provide and maintain the best protection possible. It works on a dedicated domain controlled by MIRACL, which segregates the client from other scripts that might be malicious or might affect the authentication client in a way that makes it less secure. A strict Content Security Policy also protects it. It is built using minimum external dependencies, which undergo a strict security review process. This architecture makes all Cross-Site Scripting attacks impossible by design. It also protects against many other popular and less-known attacks.

You take ownership of the solution’s security by implementing the authentication client. MIRACL strongly recommends following similar architecture and practices to achieve the same or better security.

For more information, see Client JS Library.