Integrate in Mobile Apps

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 minimal 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 require any integration on the mobile side.

# Using Desktop Browser

You have to use the QR code provided in the desktop browser. When you scan it with your mobile device the MIRACL Trust Authenticator is launched (if installed). If it isn’t installed, you are redirected to the corresponding App Store.

# Using Mobile Browser

When the MIRACL Trust Authorization page is opened, you have 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. Authentication can be started both from a web page or a mobile application. The deep link that you are navigated to is https://mcl.mpin.io/. When opened, it starts the MIRACL Trust Authenticator application if it is available and initiates the authentication or prompts you to install the application. The entire authentication is managed by the MIRACL Trust Authenticator application including 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). Depending on the platform and the preferred language, these can look slightly different, but they are functionally the same.

Configuration configuration =
        new Configuration.Builder("<YOUR_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("<YOUR_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 = "<YOUR_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 = "<#YOUR_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)

Java
Kotlin
Objective-C
Swift

MiraclTrust miraclTrust = MiraclTrust.getInstance();

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

miraclTrust.register(
    <USER_ID>,
    <ACTIVATION_CODE>,
    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 = <ACTIVATION_CODE>,
    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
    didRequestPinHandler:^(void (^ _Nonnull processPinHandler)(int32_t)) {
        // Present your UI for entering pin code here
} completionHandler:^(User * _Nullable user, NSError * _Nullable error) {
}];

MIRACLTrust.register(for: <#USER_ID#>,
                     activationCode: <#ACTIVATION_CODE#>,
                     didRequestPinHandler: { pinProcessor in
    // Present your UI for entering pin code here
}, completionHandler: { user, error in
})

# Authenticate(User)

Java
Kotlin
Objective-C
Swift

MiraclTrust miraclTrust = MiraclTrust.getInstance();
miraclTrust.authenticate(
    <USER_ID>,
    pinProvider,
    result -> {
        if (result instanceof MiraclSuccess) {
            // user is authenticated
        } else {
            // user is not authenticated
        }
    }
);

val miraclTrust = MiraclTrust.getInstance()
miraclTrust.authenticate(
    userId = <USER_ID>,
    pinProvider = pinProvider
    resultHandler = ResultHandler { result ->
        when (result) {
            is MiraclSuccess -> {
                // user is authenticated
            }
            is MiraclError -> {
                // user is not authenticated
            }
        }
    }
)

[MIRACLTrust authenticateFor:user
        didRequestPinHandler:^(void (^ _Nonnull pinHandler)(int32_t)) {
            //Present your UI for entering pin code here.
} completionHandler:^(BOOL isAuthenticated, NSError * _Nullable error) {
}];

MIRACLTrust.authenticate(for: user,
                         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. This makes the biometric authentication an additional factor in the authentication process.

By implementing this integration you increase the security of the end product. The flow 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 is 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. Anyone who successfully bypasses the biometric authentication into the secure area can retrieve the entire Client Secret and 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 the implementation of biometrics flow for passive banking and biometrics and PIN for active banking.