MFA SDK - Mobile (Android)

TrustBuilder Safe-T SDK for mobile enables the integration of MFA capabilities into a mobile app.

It provides a set of functions that allow applications to manage authentication and transaction confirmation flows.

The SDK exposes the following functionalities:

Validate an authentication request
Confirm a transaction
Retrieve pending operations requiring user action
Reject an operation
Register a secure token for a given login
Generate an activation code to register a new secure token
Update the push notification identifier (Push ID) of the device
Retrieve secure tokens stored locally on the device
Change secret code
Reset a blocked secret code
Generate a reset code
Change the display name of a secure token

The SDK also provides in-app MFA interactions, allowing authentication and transaction flows to be handled directly within the application UI:

Request authorization for authentication or transaction confirmation within the app
Validate an authentication request in-app
Confirm a transaction in-app
Register biometric authentication as a secure factor

This integration guide uses specific terms:

Device
The device represents the possession factor of the user. It refers to the mobile device on which the application and secure token are installed.

Secure Token
A cryptographic object stored on a registered device that enables authentication.

Transaction confirmation
A process where the user explicitly approves a transaction in its specific context. The generated authentication code binds the transaction context to the user’s credentials, making it unforgeable and usable as a proof of consent.

Requirements

Download TrustBuilder sample app for Android
Latest version of Android Studio
JDK 17 or later
Minimum SDK : Android API 26 (Android 8.0 Oreo) or higher
Target SDK: Android API 35
The mobile application must be registered as a custom application in TrustBuilder administration console. You should provide Service Account JSON and Application ID to administrator. Once the application is registered in the TrustBuilder system an App Alias is automatically generated. It is required during SDK initialization.

Installation

Gradle dependency: in your app-level build.gradle, add the TrustBuilder MFA library to your dependencies:
CODE
```
dependencies {
    implementation 'io.trustbuilder.mfa:trustbuilder-mfa-lib:latest.integration'
}
```
Sample application configuration: create a local.properties file at the project root:
CODE
```
appAlias=<your_app_alias>
appName=<your_app_name>
appId=com.xxxx.xxxxxxx
```
- appAlias -> the unique identifier of the custom application declared in TrustBuilder console (See Requirements)
- appName -> the display name of the application.
- appId → the Android application ID.

Security Best Practices

The following practices are implemented in the sample application and are strongly recommended.

Source: Android developers security best practices

Click to read the security best practices

Restrict activity access

All the activities implemented in the application, except the launcher, cannot be launched by anything but the application itself.

This can be achieved by adding “exported=false” in the activity tag in the manifest as follow :

JAVA

<activity
 android:name=".MenuActivity"
 android:exported="false" />

More information about android:exported

Network Security Configuration

The Network Security Configuration feature lets apps customize their network security settings in a safe, declarative configuration file without modifying app code. These settings can be configured for specific domains and for a specific app.

In the sample application, in our Network Security Configuration, we declared the domain http://www.myinwebo.com, with the option cleartextTrafficPermitted set to false to force HTTPS when contacting the TrustBuilder web services. This protects sensitive traffic from hostile networks.

JAVA

<network-security-config>
 <domain-config cleartextTrafficPermitted="false">
 <domain includeSubdomains="false">www.myinwebo.com</domain>
 </domain-config>
</network-security-config>

More information about Network security configuration

Biometric security

Biometric authentication uses BIOMETRIC_STRONG (API level 29+). The key pair is stored in the StrongBox (when available) and is invalidated if biometrics are added or removed from the device.

More information about biometric authentication.

Prevent screenshots

In Android, we can manage the application’s default behavior and user interactions handling with “flags”. Those flags are part of the WindowManager.LayoutParams class.

Apply FLAG_SECURE to the activity window to block screenshots and screen recording:

CODE

super.getWindow().setFlags(
    WindowManager.LayoutParams.FLAG_SECURE,
    WindowManager.LayoutParams.FLAG_SECURE
);

More information about FLAG_SECURE.

PIN code in memory

Avoid storing the PIN as a String. Use char[] or byte[] and clear the buffer immediately after use. The sample application implements a PinEditable class that overrides Editable to prevent the PIN from being stored in a String object.

OTP clipboard protection

Do not allow the generated OTP to be copied to the device clipboard.

Set data encryption

In the sample application, the encryption is handled by the CryptographyManager. The CryptographyManager is implemented as a Singleton to avoid Thread concurrency when accessing the AndroidKeyStore.

It must be instantiated like this:

JAVA

CryptographyManager cm = CryptographyManager.getInstance();

The algorithm used for encryption is the AES-GCM algorithm (Advanced Encryption Standard - Galois/Counter Mode), a block cipher mode of operation using hash (learn more: https://datatracker.ietf.org/doc/html/rfc7714).

The ciphers used for encryption and decryption come from the core of the JCE (Java Cryptographic Extension) framework. These ciphers are instantiated with the algorithm that we talked about just above, and initialized with a SecretKey. A SecretKey is a symmetric key constructed by the KeyGenerator through the KeyGeneratorSpi. Once generated, this SecretKey is safely stored in the AndroidKeyStore and can be reused indefinitely. The purpose of the Android Keystore is to keep the key material outside of the Android operating system entirely, and in a secure location referred to as the Trusted Execution Environment (TEE). Note that if the Cipher is intended to be used with the Biometric prompt, the SecretKey must be instantiated with parameter mUserAuthenticationRequired set to true.

Here is an example of how to create an encryption cipher:

JAVA

// Retrieving an AES-GCM algorithm Cipher
Cipher cipher = getCipher();

// Retrieving the SecretKey stored in the Android KeyStore
SecretKey secretKey = getOrCreateSecretKey(keyName,
usingUserAuthentication);

// Initializing Cipher in Encrypt Mode
cipher.init(Cipher.ENCRYPT_MODE, secretKey);

Once the Cipher is initialized with this SecretKey and the Encryption or Decryption mode, it can be used for Encryption or Decryption. A Cipher can be used indefinitely but for one purpose only. To decrypt an encrypted data, the initialization vector returned by the Cipher when encrypting must be the same as the one used for decryption. Otherwise, the cipher won’t be able to decrypt whatsoever. In case of an Encryption or Decryption exception, a CryptographyException is raised.

Keep reading to know how cryptography handling is used for Biometrics purposes.

Root security

In the sample application, in order to verify that the current device is rooted, we are using multiple methods :

Test-Keys checks: Test-Keys has to do with how the kernel is signed when it is compiled. By default, stock Android ROMs from Google are built with release-keys tags. Test-Keys means it is signed with a custom key generated by a third-party developer. This can be accomplished by checking in build properties(“android.os.Build.TAGS”) for test-keys.
JAVA
```
String buildTags = android.os.Build.TAGS;
return buildTags != null && buildTags.contains("test-keys");
```
“su” command check: Su binary check is to identify the superuser in the device. This binary is installed when trying to root a phone. These files are necessary so that one can root their phone and become a superuser. This can be accomplished by executing commands like ‘/system/xbin/which su’ or ‘su’. If the command can be executed, then the device is rooted.
JAVA
```
return canExecuteCommand("/system/xbin/which su") ||
canExecuteCommand("su");
```

Looking for binary paths: the paths checked can reveal that the device has been rooted. Only one of those found will trigger the root check.

JAVA

String[] paths = {
 "/system/app/Superuser.apk",
 "/sbin/su",
 "/system/bin/su",
 "/system/xbin/su",
 "/data/local/xbin/su",
 "/data/local/bin/su",
 "/system/sd/xbin/su",
 "/system/bin/failsafe/su",
 "/data/local/su",
 "/su/bin/su"
 };
 for (String path : paths) {
 if (new File(path).exists()) {
 return true;
 }
 }
 return false;
 }

We can also check if certain apps are installed on the device.

CODE

private static boolean isAnyDangerousAppInstalled(Context context,
String[] packages) {
    boolean result = false;
    PackageManager pm = context.getPackageManager();
    for (String packageName : packages) {
        try {
            pm.getPackageInfo(packageName, 0);
            result = true;
        } catch (PackageManager.NameNotFoundException e) {
        }
    }
    return result;
}

Then we need to provide a list of apps that should be verified. This list needs to be updated when new dangerous apps appear.

We can sort these app in different categories:

Apps used to root the device
Apps used to hide the fact that the device is rooted
Dangerous App

For example:

CODE

private static final String[] knownRootAppsPackages = {
        "com.noshufou.android.su",
        "com.noshufou.android.su.elite",
        "eu.chainfire.supersu",
        "com.koushikdutta.superuser",
        "com.thirdparty.superuser",
        "com.yellowes.su",
        "com.zachspong.temprootremovejb",
        "com.ramdroid.appquarantine",
        "eu.chainfire.supersu"
};

public static final String[] knownDangerousAppsPackages = {
        "com.koushikdutta.rommanager",
        "com.koushikdutta.rommanager.license",
        "com.dimonvideo.luckypatcher",
        "com.chelpus.lackypatch",
        "com.ramdroid.appquarantine",
        "com.ramdroid.appquarantinepro"
};

public static final String[] knownRootCloakingPackages = {
        "com.devadvance.rootcloak",
        "com.devadvance.rootcloakplus",
        "de.robv.android.xposed.installer",
        "com.saurik.substrate",
        "com.zachspong.temprootremovejb",
        "com.amphoras.hidemyroot",
        "com.amphoras.hidemyrootadfree",
        "com.formyhm.hiderootPremium",
        "com.formyhm.hideroot"
};

Push notifications (Firebase Cloud Messaging)

Firebase Messaging is a solution used to send remote push notifications across Android, iOS and web devices. It allows both background and in-app notifications.

Firebase project setup

Create a project at https://console.firebase.google.com.
Add your Android application (with its package name).
If your app uses many different package names you should create one for each.
Download the google-services.json file and place it in your app/ module.
Check thatgoogle() is listed in your top-level build.gradle repositories.

Firebase dependency

You should add the Firebase dependencies in your build.gradle file:

CODE

// Top-level build.gradle
plugins {
    id 'com.google.gms.google-services' version '...' apply false
}

// app/build.gradle
plugins {
    id 'com.google.gms.google-services'
}

dependencies {
    implementation platform('com.google.firebase:firebase-bom:34.2.0')
    implementation 'com.google.firebase:firebase-messaging'
}

Handling notifications

In-app notifications → You should create a class that will extend FirebaseMessagingService and implement the onMessageReceived method. It will be the entry point for every notifications received when the app is in foreground. Then add the service in the AndroidManifest.xml.
Background notifications → To handle background notifications, you should use the data messages only. The data messages are handle within the service extending FirebaseMessagingService. Note that if you use notification messages or messages with both notification and data payload, the onMessageReceived method will not handle the background notifications (more information).

See how FirebaseMessagingService extension is implemented in the sample app we provide:

CODE

public class PushNotificationReceiveService extends FirebaseMessagingService {
    private static final MutableLiveData<Map<String, String>> IN_APP_MESSAGE = new MutableLiveData<>();
    private static final MutableLiveData<String> TOKEN = new MutableLiveData<>();

    public static MutableLiveData<Map<String, String>> getInAppMessage() { return IN_APP_MESSAGE; }
    public static MutableLiveData<String> getNewToken() { return TOKEN; }

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        IN_APP_MESSAGE.postValue(remoteMessage.getData());
    }

    @Override
    public void onNewToken(@NonNull String token) {
        super.onNewToken(token);
        TOKEN.postValue(token);
    }
}

CODE

<service
    android:name=".utils.PushNotificationReceiveService"
    android:enabled="true"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Runtime permission (Android 13+)

For your app to send non-exempt notifications, the user must grant this permission to your app.
More information

Declare the following permission in your app’s AndroidManifest file:
CODE
```
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

Request it at runtime in onResume:

CODE

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS)
            != PackageManager.PERMISSION_GRANTED) {
        requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
    }
}

Create and show the notification

In your app’s MainActivity file, set the notification content, the notification channel and show the notification (more information). In our sample app, this is implemented in the showNotification method.

FCM token refresh

Implement an FCM token change observer to detect a possible PushID change (in-case of user’s device change for example).

CODE

PushNotificationReceiveService.getNewToken().observe(this, token -> {
    if (token != null) {
        // Call pushIdRegistration use case with the new token
    }
});

Initialization

There are two interfaces to implement:

Implementing IHost interface
IHostdescribes general properties of the host application and device:

CODE

public class ConfigHost implements IHost {
    @Override public String getSerial()       { return Settings.Secure.ANDROID_ID; }
    @Override public String getName()         { return BuildConfig.APPLICATION_NAME; }
    @Override public SecureTokenTypeEnum getTknType() { return SecureTokenTypeEnum.MOBILE; }
    @Override public String getAppAlias()     { return BuildConfig.APP_ALIAS; }
    @Override public ApplicationInfo getAppInfo() {
        return ApplicationInfo.builder()
                .id(BuildConfig.APPLICATION_ID)
                .name(BuildConfig.APPLICATION_NAME)
                .version(BuildConfig.VERSION_NAME)
                .type(BuildConfig.BUILD_TYPE)
                .build();
    }
    @Override public OsInfo getOsInfo() {
        return OsInfo.builder()
                .name("Android")
                .version(String.valueOf(Build.VERSION.RELEASE))
                .build();
    }
}

serial: Hardware serial (use Settings.Secure.ANDROID_ID)
name: Display name of the application
type: Token type - always SecureTokenTypeEnum.MOBILE for Android
appAlias: Custom application alias (see Requirements)
appInfo.id: application ID
appInfo.name: Name of the application
appInfo.version: Version of the application
appInfo.type: Build type (debug / release)
osInfo.name: OS name ("Android")
osInfo.version: Android version string

Implementing ISecureTokenStorage interface
ISecureTokenStorage provides save, retrieve, list and remove operations for SecureToken objects. The sample application stores tokens as AES-GCM encrypted JSON files in the app's internal storage (context.getFilesDir()), with the initialization vector stored in SharedPreferences.

Function	Input	Returns	Description
`save`	`SecureToken`	—	Backup of the secure token
`get`	`tknAlias`	`SecureToken`	Retrieves one secure token by alias
`getAll`	—	`List<SecureToken>`	Returns all stored tokens
`remove`	`tknAlias`	`boolean`	Deletes a token

Creating the library instance
The TrustBuilderMfaLib instance should be a singleton, created once and reused across activities:

CODE

public class TrustBuilderMfaLibHolder {
    private static TrustBuilderMfaLib instance;

    public static TrustBuilderMfaLib getInstance(Activity activity) {
        if (instance == null) {
            ConfigHost host = ConfigHost.getInstance();
            ConfigSecureTokenStorage storage = ConfigSecureTokenStorage.getInstance(activity);
            instance = new TrustBuilderMfaLib(host, storage);
        }
        return instance;
    }
}

General principles

Use Case pattern

The SDK exposes its features as use cases. There are two types:

<SingleUseCase> → one-step use case: it exposes a single execute function to process it.
<UseCase> → two-step use case: it exposes two functions setup and execute to process it. This allows the management of data to be entered or read by the user (typically user credentials management).

The naming format of the methods exposed by the TrustBuilder MFA library looks like this:

JAVA

TrustBuilderMfaLib mfaLib = TrustBuilderMfaLibHolder.getInstance(activity);

// SingleUseCase example
MyUseCase usecase = mfaLib.startMyUseCase(params);
MyUseCaseResult result = usecase.execute();

// UseCase example
MyUseCase usecase = mfaLib.startMyUseCase(params);
MyUseCaseSetupResult setupResult = usecase.setup();
// → collect credential from user 
MyUseCaseResult result = usecase.execute();

Authentication flow

There are two authentication flows:

Out-Of-Band → the authentication request is initiated from a web channel and validated on the mobile.
In-App → the authentication request is initiated from the current application and validated in the current application.

Some exposed methods are different depending on the flow type.

Features implementation

This section describes the features implemented in the sample application available in the TrustBuilder MFA Android SDK.

Validate an authentication request

Out-Of-Band authentication

Use case name	authentication
Use case type	Use case
Description	Authenticate a user: this generates a One-Time-Password and calls TrustBuilder server to validate it.
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used `cnxAlias` (string) → the connector alias of the connector from which the user is authenticated `sessionId` (string) → the identifier of the authentication session or sealing session `scope` (AuthScope) → the scope of use of the generated challenge and the OTP. `sessionData` → the data protected by the OTP
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_AVAILABLE_AUTH_METHOD_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_AUTH_SESSION_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `Authentication authentication = clientLib.StartAuthentication(AuthenticationParams params); AuthenticationSetupResult setupres = authentication.setup(); //Display CredentialProvider AuthenticationResult res = authentication.execute();` See the source code of the sample application

In-App authentication

Use case name	inAppAuthentication
Use case type	UseCase
Description	Authenticate a user in the current application. This generates a token if the authentication is successful. IN-APP
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used `sessionId` (string) → the identifier of the authentication session or sealing session `cnxAlias` (string) → the connector alias of the connector from which the user is authenticated `scope` (AuthScope) → the scope of use of the generated challenge and the OTP.
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_ACCESS_ERR IW_USR_HAS_NO_AVAILABLE_AUTH_METHOD_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_AUTH_SESSION_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `InAppAuthentication inAppAuthentication = clientLib.startInAppAuthentication(InAppAuthenticationParams param) InAppAuthenticationSetupResult setupres = inAppAuthentication.setup(); //Display CredentialProvider InAppAuthenticationResult res = inAppauthentication.execute();` See the source code of the sample application

Activate a Secure Token

Use case name	secureTokenEnrollment
Use case type	Use case
Description	Activate a Secure Token for a given login (enrollment process)
Input parameter(s)	`code` (string) → the activation code
Errors	IW_FORBIDDEN_ERR IW_INVALID_SECRET_CODE_FORMAT IW_CORE_CNX_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `SecureTokenEnrollment secureTokenEnrollment = clientLib.startSecureTokenEnrollment(SecureTokenEnrollmentParams params); SecureTokenEnrollmentSetupResult setupres = secureTokenEnrollment.setup(); //Display CredentialProvider SecureTokenEnrollmentResult res = secureTokenEnrollment.execute();` See the source code of the sample application

Retrieve all Secure Tokens

Use case name	secureTokensListing
Use case type	SingleUseCase
Description	Retrieve the secure tokens stocked in the local storage
Input parameter(s)	/
Errors	IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `SecureTokenListing secureTokenListing = clientLib.startSecureTokenListing(); SecureTokenListingResult res = secureTokenListing.execute();` See the source code of the sample application

Retrieve the pending operations

Use case name	pendingAuthSessionsRetrieval
Use case type	SingleUseCase
Description	Retrieve the pending operations
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `PendingAuthSessionsRetrieval pendingAuthSessionsRetrieval = clientLib.startPendingAuthSessionsRetrieval(PendingAuthSessionsRetrievalParams params); PendingAuthSessionsRetrievalResult res = pendingAuthSessionsRetrieval.execute();` See the source code of the sample application

Reject an operation

Use case name	authSessionCancellation
Use case type	SingleUseCase
Description	Reject an authentication request or a transaction confirmation request
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used `sessionId` (string) → the identifier of the authentication session or sealing session `reason` (CancelReason) → reason for cancellation (`"NONE", "DUPLICATE", "FRAUDULENT", "ABANDONED"`)
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_AUTH_SESSION_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `AuthSessionCancellation authSessionCancellation = clientLib.startAuthSessionCancellation(AuthSessionCancellationParams params); AuthSessionCancellationResult res = authSessionCancellation.execute();` See the source code of the sample application

Confirm a transaction

Out-Of-Band transaction

Use case name	sealing
Use case type	UseCase
Description	Confirm an electronic transaction on top of authentication. This displays the business data provided by the Service Provider. Then this generates One-Time-Password and calls TrustBuilder server to validate it.
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used `cnxAlias` (string) → the connector alias of the connector from which the user is authenticated `sessionId` (string) → the identifier of the authentication session or sealing session
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_AVAILABLE_AUTH_METHOD_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_AUTH_SESSION_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_BUSINESS_DATA_IS_EMPTY_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `Sealing sealing = clientLib.startSealing(SealingParams params); SealingSetupResult setupres = sealing.setup(); //Display CredentialProvider SealingResult res = sealing.execute();` See the source code of the sample application

In-App transaction

Use case name	inAppSealing
Use case type	UseCase
Description	Confirm an electronic transaction on top of authentication in the current application. This generates a token if the authentication is successful. IN-APP
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used `cnxAlias` (string) → the connector alias of the connector from which the user is authenticated `scope` (AuthScope) → the scope of use of the generated challenge and the OTP. `sessionId` (string) → the identifier of the authentication session or sealing session
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_AVAILABLE_AUTH_METHOD_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_AUTH_SESSION_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_BUSINESS_DATA_IS_EMPTY_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `InAppSealing inAppSealing = clientLib.startInAppSealing(InAppSealingParams params); InAppSealingSetupResult setupres = inAppSealing.setup(); //Display CredentialProvider InAppSealingResult res = inAppSealing.execute();` See the source code of the sample application

Request an authorization

Use case name	authorizeRequest
Use case type	SingleUseCase
Description	Request an authorization for an in-app authentication or for an in-app transaction confirmation. It will provide a sessionId to execute the requested operation. IN-APP
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used `cnxAlias` (string) → the connector alias of the connector from which the user is authenticated `sealData` (SealBusinessData)→ (only if `Authorizescope`=SEAL) the business data to seal `scope` (AuthorizeScope) → the scope of the authorization request
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_ACCESS_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_CNX_IS_UNKNOWN_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `AuthorizeRequest authorizeRequest = clientLib.startAuthorizeRequest(AuthorizeRequestParams params); AuthorizeRequestResult res = authorizeRequest.execute();` See the source code of the sample application

Generate an activation code

Use case name	activationCodeGeneration
Use case type	UseCase
Description	Generate an activation code to activate a new Secure Token
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `ActivationCodeGeneration activationCodeGeneration = clientLib.startActivationCodeGeneration(ActivationCodeGenerationParams params); ActivationCodeGenerationSetupResult setupres = activationCodeGeneration.setup(); //Display CredentialProvider ActivationCodeGenerationResult res = activationCodeGeneration.execute();` See the source code of the sample application

Change Secret Code

Use case name	secretCodeChange
Use case type	UseCase
Description	Change a secret code (the user knows the current secret code but wants to change its value)
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `SecretCodeChange secretCodeChange = clientLib.startSecretCodeChange(SecretCodeChangeParams params); SecretCodeChangeSetupResult setupres = secretCodeChange.setup(); //Display CredentialProvider SecretCodeChangeResult res = secretCodeChange.execute();` See the source code of the sample application

Reset a Secret code

Use case name	secretCodeReset
Use case type	UseCase
Description	Reset a blocked secret code
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used `code` (string) → the Reset Code encoded in Base32
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_CODE_ERR IW_INVALID_SECRET_CODE_FORMAT IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `secretCodeReset secretCodeReset = clientLib.startsecretCodeReset(secretCodeResetParams params); secretCodeResetSetupResult setupres = secretCodeReset.setup(); //Display CredentialProvider secretCodeResetResult res = secretCodeReset.execute();` See the source code of the sample application

Generate a Reset code

Use case name	resetCodeGeneration
Use case type	SingleUseCase
Description	Generate a reset code and send it by email to the user An error is returned: if the tenant security policy prevents this action. if the user does not have an email address associated to his profile
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_FORBIDDEN_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `ResetCodeGeneration resetCodeGeneration = clientLib.startResetCodeGeneration(ResetCodeGenerationParams params); ResetCodeGenerationResult res = resetCodeGeneration.execute();` See the source code of the sample application

Change the Secure token name

Use case name	secureTokenFriendlyNameUpdate
Use case type	SingleUseCase
Description	Update the name of the secure token
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used `tknName` (string) → the current secure token name to update
Errors	IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `SecureTokenFriendlyNameUpdate secureTokenFriendlyNameUpdate = clientLib.startsecureTokenFriendlyNameUpdate(SecureTokenFriendlyNameUpdateParams params); SecureTokenFriendlyNameUpdateResult res = secureTokenFriendlyNameUpdate.execute();` See the source code of the sample application

Update the push ID

Use case name	pushIdRegistration
Use case type	SingleUseCase
Description	Update the push ID generated for the host application
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used `tknPushId` (string) → the current push notifications ID to update
Errors	IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `PushIdRegistration pushIdRegistration= clientLib.startPushIdRegistration(PushIdRegistrationParams params); PushIdRegistrationResult res = pushIdRegistration.execute();` See the source code of the sample application

Register a biometric factor

Use case name	BiokeyRegistration
Use case type	UseCase
Description	Register biometric data. A key pair is generated in the keystore to be used on a successful biometric matching on the trusted device. The public key is provided to the back-end for verifications of challenges signature during authentication.
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_FORBIDDEN_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_BIOKEY_IS_ALREADY_REGISTERED_ERR IW_CHALLENGE_SIGNATURE_IS_NOT_VERIFIED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `BiokeyRegistration BiokeyRegistration = clientLib.startBiokeyRegistration(BiokeyRegistrationParams params); BiokeyRegistrationSetupResult setupres = BiokeyRegistration.setup(); //Display Disclaimer //Display CredentialProvider // Generate RSA key pair in <Secure Element> BiokeyRegistrationResult res = BiokeyRegistration.execute();` See the source code of the sample application

Data Types

Data	Description	Parameters
CredentialProvider	Object containing the information needed to request a credential from the user	credMode: NEW \| EXISTING NEW: request to define credential EXISTING: request to enter the credential for validation credType: <CredType> see CredType below credProperties SecretCodeFormat: format of the requested secret code BioChallenge: challenge to be signed by the private key of the <SecureElement>
CredValue	Object containing the credential data	value: credential value credType: <CredType> see CredType below
CredType	Credential type	SECRET_CODE \| BIO SECRET_CODE: request to enter a secret code BIO: request to enter the bio (Face, finger, ...)
BoolResult	Object encapsulating a Boolean	result: Boolean
SecureToken	Data of a secure token exposed by the library	tntAlias: alias of the tenant to which the secure token belongs login: login of the user to which the secure token belongs alias: identifier of the secure token
AuthSession	Data of an authentication session or a sealing session	tntAlias: alias of the tenant linked to the session login: login of the user linked to the session cnxAlias: alias of the connector on which the user must authenticate created: creation date of the session expired: expiry date of the session sessionId: session identifier scope: scope of use of the session. type <Scope> authenticationMethods: list of authorized authentication methods
AuthorizeScope	Enumeration describing the use of the authorization request	Possible values: AUTH SEAL API SESSION
AuthScope	Enumeration describing the scope of an authentication	Possible values: AUTH API SESSION