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 end 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.

# Authenticate to a 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.

# Authenticate 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.

# Authenticate 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.

# Authenticate to a 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 end-user registration and end-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).

# Integrate the MIRACL Trust Mobile SDK into a Mobile Application

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.

sequenceDiagram actor Alice participant App as Mobile App participant SDK as MIRACL Trust Mobile SDK Alice->>App: Open activate App App->>SDK: Configure(projectID) activate SDK SDK-->>App: OK deactivate SDK alt scanning a QR URL App->>SDK: GetAuthenticationSessionDetails(qrCode) activate SDK SDK-->>App: session deactivate SDK else opening a Deep Link App->>SDK: GetAuthenticationSessionDetails(deepLink) activate SDK SDK-->>App: session deactivate SDK else opening a Push Notification App->>SDK: GetAuthenticationSessionDetails(pushNotificationPayload) activate SDK SDK-->>App: session deactivate SDK end opt if device is not registered Note over App,SDK: Identity Verification Flow App->>SDK: VerifyDevice(userID, accessID) activate SDK SDK-->>Alice: verificationLink deactivate SDK Alice->>App: OpenVerificationLink(verificationLink) Note over App,SDK: Device Registration Flow App->>SDK: GetActivationToken(verificationLink) activate SDK SDK-->>App: activationToken deactivate SDK App->>SDK: Register(userID, activationToken) activate SDK SDK->>Alice: request PIN Alice-->>SDK: pin SDK-->>App: user deactivate SDK end Note over App,SDK: Authentication Flow alt scanning а QR URL App->>SDK: Authenticate(qrCode, user) activate SDK SDK->>Alice: request PIN Alice-->>SDK: pin SDK-->>App: OK deactivate SDK else opening a Deep Link App->>SDK: Authenticate(deepLink, user) activate SDK SDK->>Alice: request PIN Alice-->>SDK: pin SDK-->>App: OK deactivate SDK else opening a Push Notification App->>SDK: Authenticate(pushNotificationPayload, user) activate SDK SDK->>Alice: request PIN Alice-->>SDK: pin SDK-->>App: OK deactivate SDK end App-->>Alice: SuccessScreen() deactivate App

# Configure(ProjectID)

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)

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)

MiraclTrust miraclTrust = MiraclTrust.getInstance();
miraclTrust.authenticate(
    <USER_ID>,
    pinProvider,
    result -> {
        if (result instanceof MiraclSuccess) {
            // The user is authenticated.
        } else {
            // The 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 M-PIN Token After Biometric Authentication

The M-PIN 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 requires successful biometric authentication to receive the M-PIN token from the device’s secure storage and the end user’s PIN to facilitate successful authentication. We call this 2-step 2-factor authentication.

# Access the M-PIN Client Secret After Biometric Authentication

By default, the MIRACL Trust M-PIN protocol protects the Client Secret by splitting it into an M-PIN token and a PIN. This makes the solution Multi-Factor. It is possible to store the entire Client Secret (Token + PIN) in the device’s 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.

# Implement 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 M-PIN token in the secure storage, requiring both a biometric authentication to get the token, and then the combination of that token with the end 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.