Mobile SDK

As a preliminary step, you must set up the Mobile SDK as described in MIRACL Trust Android SDK and MIRACL Trust iOS SDK.

The MIRACL Trust SDK offers two authentication options:

Authenticate on your mobile application
Authenticate on another device using your mobile application as an authenticator

# Authenticate on your mobile application

То authenticate users on the mobile application, call MIRACL Trust SDK’s authenticate method. If the authentication is successful, a JWT authentication token is generated. Then the token should be sent to the application server for verification.

Kotlin
Java
Swift
Objective-C

miraclTrust.authenticate(
    user = user,
    pinProvider = pinProvider,
    resultHandler = ResultHandler { result ->
        when (result) {
            is MIRACLSuccess -> {
                // user is authenticated
                val jwt = result.value
            }
            is MIRACLError -> {
                // user is not authenticated
            }
        }
    }
)

miraclTrust.authenticate(
    user,
    pinProvider,
    result -> {
        if (result instanceof MIRACLSuccess) {
            // user is authenticated
            String jwt = ((MIRACLSuccess<String, AuthenticationException>) result).getValue();
        } else {
            // user is not authenticated
        }
    }
);

    MIRACLTrust.getInstance().authenticate(
        for: <#Already registered user object#>
    ) { pinHandler in
        // Here the user provides their current User ID's PIN code.

        pinHandler(<#Provide your PIN here#>)
    } completionHandler: { jwt, error in
        // Get the JWT or handle the error appropriately.
    }

[[MIRACLTrust getInstance] authenticate:<#Already registered user object#>
                   didRequestPinHandler:^(void (^ _Nonnull pinHandler)(NSString * _Nullable)) {
                         pinHandler(<#Provide your PIN here#>);
                    } completionHandler:^(NSString * _Nullable jwt, NSError * _Nullable error) {
                          // Get the JWT or handle the error appropriately.
                    }];

When the application server receives the token, it must verify the token signature. For this verification, you need to use a JWT library that is suitable for your backend. To verify the token signature, use the MIRACL Trust JSON Web Key Set (JWKS) endpoint. The keys should be cached for subsequent requests, so you might need to fetch them again periodically to ensure they are up to date or to request them again if a token arrives with an unknown key ID. Make sure your implementation does not assume the keys don’t change as they will be periodically rotated.

See an example of a request and response when checking the validity of a key here.

For security reasons, it is very important that you validate the claims of the token. These are:

aud (audience) - must contain the Project ID.
exp (expiration) - the token must not have expired. The expiration claim is a Unix timestamp.
iss (issuer) - must be https://api.mpin.io.

After the token is verified, the application server can create an application session for the user with the appropriate authorisation.

# Authenticate on another device using your mobile application as an authenticator

The MIRACL Trust SDKs let you use your mobile application instead of the MIRACL Trust Authenticator to authenticate on another app or device. This can be done via a QR code, push notification or AppLink/Universal Link. This is described in detail in Cross-Device Authentication.

# Additional information

For additional information, see: