Client JS Library

The M-PIN protocol involves cryptographic operations over stored cryptographic material on the client side. That’s why MIRACL Trust provides the MIRACL Trust Client JS Library for its authentication that handles all the cryptography, as well as enrolment, identity management and much more.

# Configuration

To prevent certain attacks, browsers restrict cross-origin HTTP requests by default. This means that by default, a web application can only request resources from the domain on which it is running. Cross-origin resource sharing (CORS) is an HTTP-header-based mechanism that allows restricted resources to be accessed from a domain different from the requesting one. It relies on the “preflight” request that the browser makes to check if the server permits the actual request using headers that indicate the HTTP method and headers of the actual request. If the resource is allowed for the requesting domain, the server response contains the Access-Control-Allow-Origin header with the value of the requesting domain.

# Allow CORS Requests

As a preliminary step, you must allow CORS requests for your project to enable custom authentication clients. To do this:

1. Go to your project’s settings in the MIRACL Trust Portal.
2. Select General under Configuration.
3. Scroll down to Allowed CORS Origins.
4. Click Add New Allowed Origin.
5. Enter the domain where the web client is hosted.

# Install and Configure the Library

You must install and configure the Client JS Library as described in MIRACL Trust Client JS Library.

# Check if a Device Is Registered

To check if the device has already been registered, use the list method of the users storage object:

const allUsers = mcl.users.list();
console.log(allUsers);

Depending on your requirements, you can allow only one end user on the device or present the end user with an option to choose one of the registered User IDs.

# Authentication

MIRACL Trust Client JS Library offers two options:

• Authenticate users on the same application
• Authenticate users on another application

# Authenticate users on the same application

The authenticate method generates a JWT authentication token for а registered user.

Promise:

try {
  const result = await mcl.authenticate(userId, pin);
  console.log(result.jwt);
} catch (err) {
  // Handle any potential errors
}

Callback:

mcl.authenticate(userId, pin, function callback(err, result) {
  if (err) {
    // Handle any potential errors
  }

  // The JWT in the result needs to be verified by your back end
  // to ensure that the authentication was successful
  console.log(result.jwt);
});

After the JWT authentication token is generated, it must be sent to the application server for verification. Then, the application server verifies the token signature using the MIRACL Trust JWKS endpoint and the audience claim, which, in this case, is the application Project ID.

# Authenticate users on another application

When using the library to build a hybrid mobile application, you can use it as an authenticator to authenticate a user on another application or device. There are three options:

• Authenticate with AppLink

  Use the authenticateWithAppLink method:

  try {
    await mcl.authenticateWithAppLink(userId, appLink, pin);
  } catch (err) {
    // Handle any potential errors
  }
  

• Authenticate with QR code

  Use the authenticateWithQRCode method:

  try {
    await mcl.authenticateWithQRCode(userId, qrCode, pin);
  } catch (err) {
    // Handle any potential errors
  }
  

• Authenticate with a push notification

  Use the authenticateWithNotificationPayload method:

  try {
    await mcl.authenticateWithNotificationPayload(pushNotificationPayload, pin);
  } catch (err) {
    // Handle any potential errors
  }
  

For more information about authenticating users on separate applications and devices, see Cross-Device Authentication.

# Security

The authentication client is a standard JavaScript application that runs in the browser. This means it is susceptible to all potential vulnerabilities arising from that. Therefore, when implementing custom clients, it is important to have protection against such vulnerabilities as XSS, CSRF, etc.

# Content Security Policy

If you have Content Security Policy (CSP), add the following in your connect-src:

Content-Security-Policy: connect-src https://*.mpin.io;

This makes it possible for requests to be sent to the MIRACL Trust API https://api.mpin.io. We recommend keeping the * and not replacing it with api in the connect-src, because requests are sent to other subdomains during registration.