How to implement email verification flow?

MIRACL Trust implements email verification flow as its default 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 that is to use the pluggable verification mechanism. Pluggable verification 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.

Enroled 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 enroling 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 user which device is going to be enroled and with what identity.

  • Have an explanation about the nature of the enrolment and the fact that authentication will be possible only from enroled 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 will be successful but the enrolment will be 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 user to open the link in their default browser.

Verification URL handling

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 will 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. Even more, some mail clients will try to proxy those links via some system to scan the content and protect the user from malicious links (Safe Links). This behavior can break the verification flow as the link will be consumed before the 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 will prevent 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>