MIRACL Trust implements email verification flow as its built-in user verification. This implementation is meant to be generic so it can work for the widest spectrum of use cases but it is not a golden bullet. Often clients need to extend it with additional steps to accommodate specific needs or even create an entirely different flow. The way to accomplish this is to use the Custom User Verification mechanism which allows the creation of any bespoke verification flow.
# Good Practices
The verification process is usually the first experience users have with any system integrated with MIRACL Trust so it is extremely important that it is seamless. It should be almost transparent for the user. Email verification in particular is relatively known to users but it still has some important specifics that can be taken into consideration during the implementation.
# Enrolled Device
The end goal of the email verification is to enrol the device where the email is opened with an M-PIN ID. This device can be a desktop browser or a mobile application. It is important that the user understands what device they are enrolling and that they need that enrolment to be able to authenticate.
# Considerations
-
Have the name of the identity and the name of the device in a prominent place in the email so then it is clear for the end user which device is going to be enrolled and with what identity.
-
Have an explanation about the nature of the enrolment and the fact that authentication is possible only from enrolled devices.
-
Have instructions on what should be done in case a mobile email client is used.
Mobile clients usually open emails in web view. In that case, the verification is successful but the enrolment is stored in the local storage of the web view. Usually, this storage is not shared with the default browser and it may be cleaned between uses. A possible solution for this problem is to add instructions for the end user to open the link in their default browser.
# Verification URL Handling
End-user verification is of paramount importance for the security of the entire solution so it should be secured itself.
# Considerations
-
Make invitations link expire.
-
Invalidate the verification links after use.
Many messaging applications try to open links to be able to show a preview of the content of the link. This is true even for some mail clients. Some mail clients try to proxy those links via some system to scan the content and protect the end user from malicious links (Safe Links). This behavior can break the verification flow as the link is consumed before the end user has a chance to open it.
One solution for this problem is to use javascript to handle the verification request rather than making GET request directly. This prevents most of those applications to consume the actual invitation as they are not evaluating the javascript.
Example implementation:
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Verification</title>
<script>
var request = new XMLHttpRequest();
var doneState = 4;
var okStatus = 200;
request.onreadystatechange = function () {
if (request.readyState === doneState) {
try {
if (request.status !== okStatus) {
throw new Error("Verification request failed");
}
var response = JSON.parse(request.responseText);
if (!response.verificationRedirectUrl) {
throw new Error("Missing verificationRedirectUrl");
}
window.location.href = response.verificationRedirectUrl;
} catch (err) {
alert(err.message);
}
}
};
request.open("POST", window.location.href, true);
request.send();
</script>
</head>
<body></body>
</html>
