Mobile integration

The MIRACL Trust Authentication platform provides facilities for a variety of mobile application integrations.

MIRACL Trust Authenticator

The MIRACL Trust Authenticator is a mobile application that allows utilisation of the MIRACL Trust authentication technology with a minimum amount of integration into the application the user is trying to authenticate to. The MIRACL Trust Authenticator can be used to authenticate to a mobile application or a web application regardless of where it is accessed from.

Web application

Authentication to a web application integrated with the MIRACL Trust OIDC Authentication using the MIRACL Trust Authenticator does not need any integration on the mobile side.

Using desktop browser

In this case, the authentication is facilitated using a QR Code. When scanned by the mobile device, the MIRACL Trust Authenticator is launched if it is installed and the authentication is facilitated by the application. If the application is not installed - the user is prompted to install it from the corresponding App Store.

Using mobile browser

When the MIRACL Trust Authorization page is opened, the user has the option to launch the Authenticator and finish the flow there or to use the MIRACL Trust Browser login.

Mobile application

Authentication to a mobile application using the MIRACL Trust Authenticator is done using deep linking. Deep linking on a mobile platform (Android, iOS) is a technology that allows an application to call a functionality of another application passing some parameters in the process. With this integration the authentication flow starts from the application consuming the authentication but the authentication itself happens with the MIRACL Trust Authenticator application. The authentication can be started both from a web page and a mobile application. The deep link that the user needs to be navigated to is https://mcl.mpin.io/. When opened, it will either start the MIRACL Trust Authenticator application if it is available and initiate the authentication routine or open a page prompting the user to install the application. The entire authentication is facilitated by the MIRACL Trust Authenticator application including both user registration and user persistence.

MIRACL Trust Mobile SDK (Android, iOS)

The MIRACL Trust Mobile SDK is designed to allow integration of the MIRACL Trust Authentication into a mobile application. The goal of the SDK is to make the integration as simple as possible by abstracting the protocol and the cryptography. The SDK supports all major languages for mobile development for the two main platforms (Java, Objective-C, Swift, Kotlin).

Integration

The diagram below illustrates a simple integration of a mobile application (Mobile App) with the MIRACL Trust Platform using the MIRACL Trust Mobile SDK. The flow shows that the integration consists of three main calls to the SDK - Configure(ProjectID), Register(UserID, ActivationCode) and Authenticate(User, AccessID). Depending on the platform and the preferred language, these can look slightly different, but they are functionally the same.

register details

Configure(ProjectID)

Configuration configuration =
        new Configuration.Builder("PROJECT ID")
                // To set custom [HttpRequestExecutor] implementation
                .httpRequestExecutor(yourHttpRequestExecutor)
                // To set custom [UserStorage] implementation
                .userStorage(yourUserStorage)
                .build();

public class YourApplication extends Application {
    ...
    @Override
    public void onCreate() {
        super.onCreate();
        ...
        MiraclTrust.configure(getApplicationContext(), configuration);
        ...
    }
    ...
}
val configuration =
    Configuration.Builder("PROJECT ID")
        // To set custom [HttpRequestExecutor] implementation
        .httpRequestExecutor(yourHttpRequestExecutor)
        // To set custom [UserStorage] implementation
        .userStorage(yourUserStorage)
        .build()

class YourApplication : Application() {
    ...
    override fun onCreate() {
        super.onCreate()
        ...
        MiraclTrust.configure(applicationContext, configuration)
        ...
    }
    ...
}
NSString *projectId = "PROJECT ID";
NSError *configurationError;

ConfigurationBuilder *configurationBuilder =
    [[ConfigurationBuilder alloc] initWithProjectId:projectId];
[configurationBuilder userStorageWith:yourUserStorage];
Configuration *configuration =
    [configurationBuilder buildAndReturnError:&configurationError];

if (configurationError == nil) {
    [MIRACLTrust configureWith:configuration
                         error:&configurationError];

    if (configurationError != nil) {
        NSLog(@"Error %@", configurationError.localizedDescription);
    }
}
let projectId = "PROJECT ID"

do {
    let configuration = try Configuration.Builder(projectId: projectId)
        .userStorage(userStorage: YourUserStorage)
        .build()
    try MIRACLTrust.configure(with: configuration)
} catch {
    print(error)
}

Register(UserID,AuthorizationCode)

MiraclTrust miraclTrust = MiraclTrust.getInstance();

PinProvider pinProvider =
    pinConsumer -> {
        String pin = /* user pin */
        pinConsumer.consume(pin);
    };

miraclTrust.register(
    USER_ID,
    activationCode,
    accessId,
    pinProvider,
    result -> {
        if (result instanceof MiraclSuccess) {
           User user = (User) ((MiraclSuccess) result).getValue();
        } else {
            MiraclError error = (MiraclError) result;
            String errorMessage = ((Error) error.getValue()).getMessage();
            // handle error
        }
    }
);
val miraclTrust = MiraclTrust.getInstance()

val pinProvider =
    PinProvider { pinConsumer ->
        val pin = /* user pin */
        pinConsumer.consume(pin)
    }

miraclTrust.register(
    userId = USER_ID,
    activationCode = activationCode,
    accessId = accessId,
    pinProvider = pinProvider,
    resultHandler = ResultHandler { result ->
        when (result) {
            is MiraclSuccess -> {
                user = result.value
            }
            is MiraclError -> {
                val errorMessage = registerResult.value.message
                // handle error
        }
    }
)
[MIRACLTrust registerFor:self.userId
          activationCode:self.activationCode
                accessId:self.accessId
    didRequestPinHandler:^(void (^ _Nonnull processPinHandler)(int32_t)) {
        // Present your UI for entering pin code here
} completionHandler:^(User * _Nullable user, NSError * _Nullable error) {
}];
MIRACLTrust.register(for: userId,
                     activationCode: activationCode,
                     accessId: accessId,
                     didRequestPinHandler: { pinProcessor in
    // Present your UI for entering pin code here
}, completionHandler: { user, error in
})

Authenticate(User,AccessID)

MiraclTrust miraclTrust = MiraclTrust.getInstance();
miraclTrust.authenticate(
    USER_ID,
    accessId,
    pinProvider,
    result -> {
        if (result instanceof MiraclSuccess) {
            // user is authenticated
        } else {
            // user is not authenticated
        }
    }
);
val miraclTrust = MiraclTrust.getInstance()
miraclTrust.authenticate(
    userId = USER_ID,
    accessId = accessId,
    pinProvider = pinProvider
    resultHandler = ResultHandler { result ->
        when (result) {
            is MiraclSuccess -> {
                // user is authenticated
            }
            is MiraclError -> {
                // user is not authenticated
            }
        }
    }
)
[MIRACLTrust authenticateFor:user
                    accessId:self.accessId
        didRequestPinHandler:^(void (^ _Nonnull pinHandler)(int32_t)) {
            //Present your UI for entering pin code here.
} completionHandler:^(BOOL isAuthenticated, NSError * _Nullable error) {
}];
MIRACLTrust.authenticate(for: user,
                         accessId: self.accessId,
                         didRequestPinHandler: { pinHandler in
                         // Present your UI for entering pin code here
}, completionHandler: { (isAuthenticated, error) in
})

Biometrics integration

Mobile platforms offer a way to secure data using the secure storage area of the device. MIRACL Trust can be integrated with those mechanisms in several ways. Below are examples of different integrations.

Access the MPin Token after biometric authentication

The MPin Token, that is stored on the device, can be protected with the biometric authentication of the device which essentially makes the biometric authentication an additional factor in the authentication process.

By implementing this integration the security of the end product is increased. The flow will require successful biometric authentication to receive the MPin Token from the device secure storage and the user PIN to facilitate successful authentication. We call this 2-step 2-factor authentication.

Access the MPin Client Secret after biometric authentication

By default, the MIRACL Trust MPin protocol protects the Client Secret by splitting it into an MPin Token and a PIN. This makes the solution Multi-Factor. It would be possible to store the entire Client Secret (Token + PIN) in the device secure storage area.  This essentially makes the authentication Multi-Step rather than Multi-Factor, and it should be noted that anyone who successfully by-passes the biometric authentication into the secure area and can retrieve the entire Client Secret, can use it to authenticate to MIRACL Trust.

Step-up authentication

An app developer integrating with MIRACL Trust could choose to implement step-up authentication. This would involve the implementation of two separate authentication flows. For example:

  • The first could protect the entire Client Secret in the secure storage, allowing authentication using only a biometric to access such Client Secret. This would be used for low-security, or perhaps read-only access.
  • The second could protect the MPin Token in the secure storage, requiring both a biometric authentication to get the Token, and then the combination of that Token with the users’ PIN to achieve full authentication.  Such could be used for a higher-security authentication requirement.

An example of such flow in the context of banking can be an implementation of only biometrics flow for passive banking and biometrics and PIN for active banking.