The M-PIN protocol involves cryptographic operations over stored cryptographic material on the client side. That’s why the MIRACL Trust service provides a browser client for its authentication that handles all of that, as well as enrolment, identity management and much more.
# Enable Custom Authentication Clients
To enable custom authentication clients, you must allow cross-origin resource sharing (CORS) requests. To do this:
- Go to your project’s settings in the MIRACL Trust Portal.
- Set the Allowed CORS Origins property to the domain where the web client is hosted.
# What is CORS
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 same domain the application is running on. 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.
# Custom Authentication Page
The MIRACL Trust platform supports custom web authentication clients. This gives you the freedom to implement it the way it best suits your use case. MIRACL Trust provides a JavaScript library that aids the development of custom authentication clients - MIRACL Trust Client JS Library.
# Install the Library
To install the JavaScript Library:
npm install --save @miracl/client-js
You can include the library in your build toolchain or use the pre-built browser version located in the /dist/client.min.js directory. You can find the reference for the library here.
# Configure an Instance of the MIRACL Trust Client
Use this code to configure your MIRACL Trust Client:
const mcl = new MIRACLTrust({
projectId: "<YOUR_PROJECT_ID>",
seed: hexSeed,
userStorage: localStorage,
deviceName: deviceName,
cors: true,
});
# Verify an End User
To generate a verification link, use the POST /verification endpoint of the MIRACL Trust platform:
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
The response looks like this:
{
"verificationURL": "https://yourdomain.com/verification/confirmation?userId=alice@miracl.com&code=theVerificationCode"
}
# Register a Device
To register the browser, get an activation token using the getActivationToken method of the library and the received verification URL:
mcl.getActivationToken(
"https://yourdomain.com/verification/confirmation?userId=alice@miracl.com&code=theVerificationCode",
function callback(err, result) {
if (err) {
// Handle any potential errors
}
console.log(result.actToken);
},
);
To finish the registration, call the register method using the received activation token (actToken):
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);
},
function callback(err) {
if (err) {
// Handle any potential errors
}
},
);
# 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.
# Authenticate
To authenticate, call the authenticate method:
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);
});
In the response, you get a signed JWT, which must be verified using the keys published in https://api.mpin.io/.well-known/jwks.
# Sign
Use the following code to produce a signature:
mcl.sign(
userId,
pin,
documentHash,
documentTimestamp,
function callback(err, signature) {
if (err) {
// Handle any potential errors
return;
}
console.log(signature);
},
);
# 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.