MIRACL Trust Android SDK

The MIRACL Trust Android SDK provides the following functionalities:

• User ID Verification
• Registration
• Authentication
• Signing
• QuickCode

# System Requirements

• Android API 21 or newer

# Installation

# Manual

Contact us at support@miracl.com to get the latest framework version and then import it in your application:

1. Put the downloaded artifact in the libs folder under the project root folder

2. Add the following line to the dependencies section in your module build.gradle

   Kotlin:

   dependencies {
       implementation(fileTree(mapOf("dir" to "libs", "include" to listOf(".jar", ".aar"))))
   }
   

   Groovy:

   dependencies{
       implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
   }
   

# Usage

# SDK Configuration

To configure the SDK:

1. Create an application in the MIRACL Trust platform. For information about how to do it, see the Getting Started guide.
2. Call the configure method with a configuration created by the Configuration.Builder class:

Kotlin:

class YourApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val configuration = Configuration.Builder(YOUR_PROJECT_ID).build()
        MIRACLTrust.configure(applicationContext, configuration)
    }
}

Java:

public class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Configuration configuration = new Configuration.Builder(YOUR_PROJECT_ID).build();
        MIRACLTrust.configure(getApplicationContext(), configuration);
    }
}

Call the configure method as early as possible in the application lifecycle and avoid using the getInstance method before that; otherwise assertion will be triggered.

# Obtain instance of the SDK

To obtain an instance of the SDK, call the getInsatnce method:

Kotlin:

val miraclTrust = MIRACLTrust.getInstance()

Java:

MIRACLTrust miraclTrust = MIRACLTrust.getInstance();

# User ID Verification

To register a new User ID, you need to verify it. MIRACL Trust offers two options for that:

• Custom User Verification

• Built-in Email Verification

  With this type of verification, the end user’s email address serves as the User ID. Currently, MIRACL Trust provides two kinds of built-in email verification methods:

  • Email Link (default)
  • Email Code

  Start the verification by calling of the sendVerificationEmail method:

  Kotlin:

  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.
              }
          }
      }
  )
  

  Java:

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

  Then, a verification email is sent, and a VerificationResponse with backoff and email verification method is returned.

  If the verification method you have chosen for your project is:

  • Email Code:

    You must check the email verification method in the response.

    • If the end user is registering for the first time or resetting their PIN, an email with a verification code will be sent, and the email verification method in the response will be EmailVerificationMethod.Code. Then, ask the user to enter the code in the application.

    • If the end user has already registered another device with the same User ID, a Verification URL will be sent, and the verification method in the response will be EmailVerificationMethod.Link. In this case, proceed as described for the Email Link verification method below.

  • Email Link: Your application must open when the end user follows the Verification URL in the email. To ensure proper deep linking behaviour on mobile applications, use Android’s App Links. To associate your application with the email Verification URL, use the Android association field in Mobile Applications under Configuration in the MIRACL Trust Portal.

# Registration

1. To register the mobile device, get an activation token. This happens in two different ways depending on type of verification.

   • Custom User Verification or Email Link:

     After the application recieves the Verification URL, it must confirm the verification by passing it to the getActivationToken method:

     Kotlin:

     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.
                     }
                 }
             }
         )
     }
     

     Java:

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

   • Email Code:

     When the end user enters the verification code, the application must confirm the verification by passing it to the getActivationToken method:

     Kotlin:

     miraclTrust.getActivationToken(userId, code) { 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.
             }
         }
     }
     

     Java:

     miraclTrust.getActivationToken(userId, code, 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.
         }
     });
     

2. Pass the User ID (email or any string you use for identification), activation token (received from verification), PinProvider and ResultHandler implementations to the register function. When the registration is successful, a ResultHandler callback is returned, passing a MIRACLSuccess together with the registered user as its value. Otherwise, MIRACLError with a RegistrationException is passed in the callback.

   Kotlin:

   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 user due to an error.
               }
           }
       }
   )
   

   Java:

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

   If you call the register method with the same User ID more than once, the User ID will be overridden. Therefore, you can use it when you want to reset your authentication PIN code.

# Authentication

MIRACL Trust SDK offers two options:

• Authenticate users on the mobile application
• Authenticate users on another application

# Authenticate users on the mobile application

The authenticate method generates a JWT authentication token for а registered user.

Use PinProvider the same way it is used during registration.

Kotlin:

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

Java:

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

After the JWT authentication token is generated, it needs to be sent to the application server for verification. Then, the application server verifies the token signature using the MIRACL Trust JWKS endpoint and the audience claim, which in this case is the application Project ID.

# Authenticate users on another application

To authenticate a user on another application, there are three options:

• Authenticate with AppLink

  Use the authenticateWithAppLink method:

  Kotlin:

  intent.data?.let { appLink ->
      miraclTrust.authenticateWithAppLink(
          user = user,
          appLink = appLink,
          pinProvider = pinProvider,
          resultHandler = ResultHandler { result ->
              when (result) {
                  is MIRACLSuccess -> {
                      // user is authenticated
                  }
  
                  is MIRACLError -> {
                      // user is not authenticated
                  }
              }
          }
      )
  }
  

  Java:

  Uri appLink = getIntent().getData();
  if (appLink != null) {
      miraclTrust.authenticateWithAppLink(
          user,
          appLink,
          pinProvider,
          result -> {
              if (result instanceof MIRACLSuccess) {
                  // user is authenticated
              } else {
                  // user is not authenticated
              }
          }
      );
  }
  

• Authenticate with QR code

  Use the authenticateWithQRCode method:

  Kotlin:

  miraclTrust.authenticateWithQRCode(
      user = user,
      qrCode = qrCode,
      pinProvider = pinProvider,
      resultHandler = ResultHandler { result ->
          when (result) {
              is MIRACLSuccess -> {
                  // user is authenticated
              }
              is MIRACLError -> {
                  // user is not authenticated
              }
          }
      }
  )
  

  Java:

  miraclTrust.authenticateWithQRCode(
      user,
      qrCode,
      pinProvider,
      result -> {
          if (result instanceof MIRACLSuccess) {
              // user is authenticated
          } else {
              // user is not authenticated
          }
      }
  );
  

• Authenticate with notification

  Use the authenticateWithNotificationPayload method:

  Kotlin:

  val payload = remoteMessage.data
  miraclTrust.authenticateWithNotificationPayload(
      payload = payload,
      pinProvider = pinProvider,
      resultHandler = ResultHandler { result ->
          when (result) {
              is MIRACLSuccess -> {
                  // user is authenticated
              }
              is MIRACLError -> {
                  // user is not authenticated
              }
          }
      }
  )
  

  Java:

  Map<String, String> payload = remoteMessage.getData();
  miraclTrust.authenticateWithNotificationPayload(
      payload,
      pinProvider,
      result -> {
          if (result instanceof MIRACLSuccess) {
              // user is authenticated
          } else {
              // user is not authenticated
          }
      }
  );
  

For more information about authenticating users on custom applications, see Cross-Device Authentication.

# Signing

DVS stands for Designated Verifier Signature, which is a protocol for cryptographic signing of documents. For more information, see Designated Verifier Signature. In the context of this SDK, we refer to it as ‘Signing’.

To sign a document, use the sign method as follows:

Kotlin:

miraclTrust.sign(
    hashedMessage,
    timestamp,
    user,
    pinProvider
) { result ->
    when (result) {
        is MIRACLSuccess -> {
            val signature = result.value
        }
        is MIRACLError -> {
            val error = result.value
            // Cannot sign the message/document due to an error.
        }
    }
}

Java:

miraclTrust.sign(
        hashedMessage,
        timestamp,
        user,
        pinProvider,
        result -> {
            if (result instanceof MIRACLSuccess) {
               Signature signature =
                       ((MIRACLSuccess<Signature, SigningException>) result).getValue();
            } else {
                MIRACLError<Signature, SigningException> error =
                        (MIRACLError<Signature, SigningException>) result;
                // Cannot sign the message/document due to an error.
            }
        }
);

The signature needs to be verified. This is done when the signature is sent to the application server, which then makes an HTTP call to the POST /dvs/verify endpoint. If the MIRACL Trust platform returns status code 200, the certificate entry in the response body indicates that signing is successful.

# QuickCode

QuickCode is a way to register another device without going through the verification process.

To generate a QuickCode, call the generateQuickCode method with an already registered User object:

Kotlin:

miraclTrust.generateQuickCode(
    user,
    pinProvider
) { result ->
    when (result) {
        is MIRACLSuccess -> {
            val quickCode = result.value
        }
        is MIRACLError -> {
            val error = result.value
            // handle error
        }
    }
}

Java:

miraclTrust.generateQuickCode(
    user,
    pinProvider,
    result -> {
        if (result instanceof MIRACLSuccess) {
            QuickCode quickCode =
                    ((MIRACLSuccess<QuickCode, AuthenticationException>) result).getValue();
        } else {
            MIRACLError<QuickCode, AuthenticationException> error =
                    (MIRACLError<QuickCode, AuthenticationException>) result;
            // handle error
        }
    }
);

# Dependencies

MIRACL Trust SDK Android depends on:

1. GSON
2. Kotlin Coroutines
3. Room Persistence Library
4. SQLCipher

# FAQ

1. How to provide PIN code?

   For security reasons, the PIN code is sent to the SDK at the last possible moment. A PinProvider is responsible for that and when the SDK calls it, the currently executed operation is blocked until a PIN code is provided. Therefore, this is a good place to display some user interface for entering the PIN code. Implement PinProvider and use it to obtain a PIN. Then pass the PIN to the PinConsumer.

   Kotlin:

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

   Java:

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

2. What is Project ID?

   Project ID is a common identifier of applications in the MIRACL Trust platform that share a single owner.

   You can find the Project ID value in the MIRACL Trust Portal:

   1. Go to trust.miracl.cloud.
   2. Log in or create a new User ID.
   3. Select your project.
   4. In the CONFIGURATION section, go to General.
   5. Copy the Project ID value.

# Documentation

• See an overview of the mobile integration at miracl.com/resources/docs/guides/mobile/