Email Link

Verification with an email link is the default built-in verification method. When an end user starts registering, a link is sent to their email address. They must open it on the device that they want to register. If they start the verification on a device and try to finish it on another one, they will receive a warning. If they choose to continue with the registration, they will be registered only on the second device. Note that every browser is considered a separate device.

However, if the device where the registration starts is a mobile application (e.g. the MIRACL Trust Authenticator or your mobile application), but the end user opens the email link in a desktop browser, a QR code will be displayed that they will have to scan to continue with the registration on the mobile device.

# Configure the Email Link Verification

To use Email Link as a verification method, you must set it up in the MIRACL Trust Portal. To do so:

Go to your project in the MIRACL Trust Portal.
Select User Verification under Configuration.
Use the Verification Method dropdown list to select the Email Link option.

# Integrate in Your Application

MIRACL Trust’s built-in verification can be integrated directly into your applications through the platform’s Mobile SDKs and Client JS Library, which enable the implementation of verification flows.

Note that no integration is needed if you use the MIRACL Trust Authenticator.

The verification starts by calling the sendVerificationEmail method of the MIRACL Trust Android SDK, MIRACL Trust iOS SDK or MIRACL Trust Client JS Library.

Kotlin
Java
Swift
Objective-C
JavaScript


miraclTrust.sendVerificationEmail(
    userId = USER_ID,
    resultHandler = ResultHandler { result ->
        when (result) {
            is MIRACLSuccess -> {
                // Verification email is sent.
            }
            is MIRACLError -> {
                val error = result.value
                // Verification email is not sent due to an error.
            }
        }
    }
)

miraclTrust.sendVerificationEmail(
    USER_ID,
    result -> {
        if (result instanceof MIRACLSuccess) {
            // Verification email is sent.
        } else {
            MIRACLError<VerificationResponse, VerificationException> error =
                    (MIRACLError<VerificationResponse, VerificationException>)
                            result;
            // Verification email is not sent due to an error.
        }
    }
);

    MIRACLTrust.getInstance().sendVerificationEmail(
        userId: <#Unique user identifier (any string, i.e. email)#>
    ) { (verificationResponse, error) in
        // Check here if verification email is sent and handle any verification errors.
    }

    [[MIRACLTrust getInstance]
        sendVerificationEmailWithUserId: <#Unique user identifier#>
            authenticationSessionDetails: nil
                    completionHandler: ^(VerificationResponse *verificationResponse, NSError * _Nullable error) {
                        // Check here if verification email
                        // is sent and handle any verification errors.
                    }];

mcl.sendVerificationEmail(userId, function (error, result) {
  if (error) {
    // Handle any potential errors
    console.error(error);

    return;
  }

  console.log(result);
});

Then, an email with a Verification URL is sent, and a verification response with backoff is returned. A backoff is the period you must wait before making a new verification request; otherwise, you will receive a backoff error.

Your application must open when the end user follows the Verification URL. To ensure proper deep linking behaviour on mobile applications, use Android’s App Links or Apple’s Universal Links. To associate your application with the email Verification URL, use the Android association and iOS app association fields in Mobile Applications under Configuration in the MIRACL Trust Portal.

After the application receives the Verification URL, it must confirm the verification by calling the getActivationToken method of the MIRACL Trust Android SDK, MIRACL Trust iOS SDK or MIRACL Trust Client JS Library:

Kotlin
Java
Swift
Objective-C
JavaScript

intent?.data?.let { verificationUri ->
    miraclTrust.getActivationToken(
        verificationUri,
        resultHandler = { result ->
            when (result) {
                is MIRACLSuccess -> {
                    val userId = result.value.userId
                    val activationToken = result.value.activationToken

                    // Use the activation token and the User ID to register the user.
                }

                is MIRACLError -> {
                    val error = result.value
                    // Cannot obtain activation token due to an error.
                }
            }
        }
    )
}

Uri verificationUri = intent.getData();
if (verificationUri != null) {
    miraclTrust.getActivationToken(verificationUri, result -> {
        if (result instanceof MIRACLSuccess) {
            ActivationTokenResponse response =
                    ((MIRACLSuccess<ActivationTokenResponse, ActivationTokenException>)
                            result).getValue();

            String userId = response.getUserId();
            String activationToken = response.getActivationToken();

            // Use the activation token and the User ID to register the user.
        } else {
            MIRACLError<ActivationTokenResponse,
                    ActivationTokenException> error =
                    (MIRACLError<ActivationTokenResponse, ActivationTokenException>)
                            result;
            // Cannot obtain activation token due to an error.
        }
    });
}

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard let verificationURL = userActivity.webpageURL else {
        return
    }

    MIRACLTrust
        .getInstance()
        .getActivationToken(verificationURL: verificationURL) { activationTokenResponse, error in
                // Pass the activation token to the `register` method.
        }
}

-(void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity
{
    if(userActivity.webpageURL == nil) {
        return;
    }

    NSURL *verificationURL = userActivity.webpageURL;

    [[MIRACLTrust getInstance]
        getActivationTokenWithVerificationURL:verificationURL
        completionHandler: ^(ActivationTokenResponse * _Nullable activationTokenResponse,
                            NSError * _Nullable error) {
                            // Pass the activation token to the `register` method.
        }];
}

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);
  },
);

The result of the verification confirmation is an activation token. Use it to call the register method of the MIRACL Trust Android SDK, MIRACL Trust iOS SDK or MIRACL Trust Client JS Library. When a PIN is requested, prompt the end user to enter one.

Kotlin
Java
Swift
Objective-C
JavaScript

miraclTrust.register(
    userId = USER_ID,
    activationToken = activationToken,
    pinProvider = { pinConsumer ->
        // Ask the user to create a PIN code for their new User ID.
        // Then pass the PIN code to the PinConsumer.
        pinConsumer.consume(userPin)
    },
    resultHandler = { result ->
        when (result) {
            is MIRACLSuccess -> {
                val user = result.value
            }

            is MIRACLError -> {
                val error = result.value
                // Cannot register a user due to an error.
            }
        }
    }
)

miraclTrust.register(
    USER_ID,
    activationToken,
    pinConsumer -> {
        // Ask the user to create a PIN code for their new User ID.
        // Then pass the PIN code to the PinConsumer.
        pinConsumer.consume(userPin);
    },
    result -> {
        if (result instanceof MIRACLSuccess) {
            User user = ((MIRACLSuccess<User, RegistrationException>) result).getValue();
        } else {
            MIRACLError<User, RegistrationException> error =
                    (MIRACLError<User, RegistrationException>) result;
            // Cannot register user due to an error.
        }
    }
);

MIRACLTrust.getInstance().register(
    for: <#Unique user identifier (any string, i.e. email)#>,
    activationToken: <#Activation token#>,
    didRequestPinHandler: { pinProcessor in
        // Here the user creates a PIN code for their new User ID.

        pinProcessor(<#Provide your PIN code here#>)
    },
    completionHandler: { user, error in
    // Get the user object or handle the error appropriately.
    }
)

[[MIRACLTrust getInstance] registerFor:<#Unique user identifier (any string, i.e. email)#>
                    activationToken:<#Activation token#>
                pushNotificationsToken:<#Push notifications token#>
                didRequestPinHandler:^(void (^ _Nonnull pinProcessor)(NSString *)) {
                    // Here the user creates a PIN code for their new User ID.

                    pinProcessor(<#Provide your PIN code here#>)
                } completionHandler:^(User * _Nullable user, NSError * _Nullable error) {
                    // Get the user object or handle the error appropriately.
                }];

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
    }
  },
);

If the registration is successful, the enrolment process is completed. End users can now authenticate using the PIN chosen for the device. They can go through the verification process for each device they want to use for authentication or use QuickCode, if enabled, to enrol additional devices using the already enrolled one.