Authentication

Using the authentication operation, you can verify the identity of the user using an already registered authenticator.

tip

To do an authentication operation, configure and initialize the SDK to obtain a MobileAuthenticationClient _{java, swift, objc, flutter, react native}.

Depending on the use case, there are two types of authentication: in-app authentication and out-of-band authentication.

For more information, see Authentication.

In-app authentication

For the application to trigger the authentication, provide the name of the user to authenticate to an Authentication _{java, swift, objc, flutter, react native}, and trigger an in-app authentication.

Username

In Authentication Cloud, the name refers to the technical username, specifically the userId attribute of the Authentication Cloud API.

The LocalData.accounts _{java, swift, objc, flutter, react native} method retrieves the registered accounts, and the Account.username() _{java, swift, objc, flutter, react native} method retrieves the (technical) username of each account, which should be used for authentication instead of the login identifier (e.g., the user`s email address).

Provide an authenticator selector, which returns the authenticator to be used.

Depending on the authenticator used to authenticate, provide any of the corresponding user verifiers: PIN user verifier, password user verifier, biometric user verifier, device passcode user verifier, or fingerprint user verifier.

Android/Kotlin

Authentication

Android/Java

Authentication

iOS/Swift

Authentication

iOS/Objective-C

Authentication

Flutter/Dart

Authentication

React Native/TypeScript

Authentication

Out-of-band authentication

When the authentication is initiated in another device or application, the information required to process the operation is transmitted through a QR code or a link. An example of out-of-band authentication is the case where the user wants to do a bank transfer using a web application in a laptop, and the server sends a push notification to the application asking for authentication.

The out-of-band authentication is done in three phases:

1. The payload obtained from the QR code or the link is provided to an OutOfBandPayloadDecode _{java, swift, objc, flutter, react native} to obtain an OutOfBandPayload _{java, swift, objc, flutter, react native} object. The payload to be provided is of type:

{
    "nma_data" : {
        "token" : "b4b07559-f934-4597-a1c5-44d89f691e8f",
        "redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication"
    },
    "nma_data_content_type" : "application/json",
    "nma_data_version" : "1"
}

For more information on how to obtain the OutOfBandPayload, see Obtain an out-of-band payload.

2. Provide the OutOfBandPayload to an OutOfBandOperation _{java, swift, objc, flutter, react native}. When building the OutOfBandOperation, invoke the OutOfBandOperation.onAuthentication method with an object taking an OutOfBandAuthentication.

3. Invoke OutOfBandOperation.execute. If the provided payload is successfully redeemed in the server, and it corresponds to an authentication, the object provided in OutOfBandOperation.onAuthentication is invoked with an OutOfBandAuthentication _{java, swift, objc, flutter, react native}.

4. Provide an authenticator selector, and the required user verifiers to the OutOfBandAuthentication.

5. Invoke OutOfBandAuthentication.execute to continue with the operation.

Android/Kotlin

Out-of-Band Authentication

Android/Java

Out-of-Band Authentication

iOS/Swift

Out-of-Band Authentication

iOS/Objective-C

Out-of-Band Authentication

Flutter/Dart

Out-of-Band Authentication

React Native/TypeScript

Out-of-Band Authentication

Usernameless authentication

You can start an out-of-band authentication without a username in the initial request. In this scenario, the operation allows to authenticate with different accounts. To support the scenario, provide an Account Selector.

tip

If you do not need to support usernameless authentication, or if your application only supports one account, you do not need to provide the AccountSelector.

Transaction confirmation

There are cases when specific information is to be presented to the user during the user verification process, known as transaction confirmation in the FIDO UAF protocol.

In case of transaction confirmation, the AuthenticatorSelectionContext _{java, swift, objc, flutter, react native} and the AccountSelectionContext _{java, swift, objc, flutter, react native} contain a byte array with the transaction information. The byte array corresponds to the content attribute.

Android/Kotlin

Transaction Confirmation

Android/Java

Transaction Confirmation

iOS/Swift

Transaction Confirmation

iOS/Objective-C

Transaction Confirmation

Flutter/Dart

Transaction Confirmation

React Native/TypeScript

Transaction Confirmation

Lifecycle

1. The authentication is started by calling the execute method.
2. In case of out-of-band authentication, where an Account Selector is to be provided, the SDK invokes the account selector. If the AccountSelectionContext contains transaction confirmation information, the contents of the transaction confirmation are presented to the user for validation.
3. The SDK invokes the Authenticator Selector. If the AuthenticatorSelectionContext contains transaction confirmation information and the contents are not presented previously, the contents of the transaction confirmation are presented to the user for validation. Depending on the selected authenticator, the SDK does the following:
   • Invoke the PIN user verifier, if PIN is selected.
   • Invoke the password user verifier, if password is selected.
   • Invoke the biometric user verifier, if a biometric authenticator (biometric authenticator in Android, FaceID or TouchID authenticator in iOS) is selected.
   • Invoke the device passcode user verifier, if the device passcode authenticator is selected.
   • Invoke the fingerprint user verifier, only applicable when running on an Android device, when the fingerprint authenticator is selected.
4. When the operation is completed, the SDK does the following:
   • Invoke the object provided to Authentication.onSuccess _{java, swift, objc, flutter, react native}, if the operation is completed successfully.
   • Invoke the object provided to Authentication.onError_{java, swift, objc, flutter, react native} with the error, if the operation is completed with an error.

In-app authentication

Out-of-band authentication

Account selector

To support usernameless authentication and multiple accounts, define an AccountSelector _{java, swift, objc, flutter, react native}, and if using the OutOfBandAuthentication.accountSelector _{java, swift, objc, flutter, react native} method.

Select an account

The AccountSelector is called by the SDK to select an account used for the out-of-band authentication. It is the responsibility of the application to decide whether to ask the user to perform the selection, or to do it directly without user intervention.

1. The user initiates an action that requires to select an account, like scanning an authentication QR code.
2. The application invokes Operations _{java, swift, objc, flutter, react native} to build the operation. The application provides the AccountSelector to the operation built.
3. The SDK calls the AccountSelector.selectAccount _{java, swift, objc, flutter, react native} method. The AccountSelectionContext _{java, swift, objc, flutter, react native} contains a list of accounts and authenticator objects to identify which accounts can be used with which authenticator.
4. The application shows the list of available accounts to the user.
   1. The user selects an account.
   2. The application provides the username of the account invoking the AccountSelectionHandler.username _{java, swift, objc, flutter, react native} method.

The SDK can now continue the out-of-band authentication using the selected account.

Authenticator selector

The Nevis Mobile Authentication SDK needs to know which is the authenticator used for the operation. The developer has to provide an AuthenticatorSelector _{java, swift, objc, flutter, react native} when building the operation.

Performing authenticator "eligibility" checks

It is very important that the authenticator selector performs the necessary checks to determine whether an authenticator is "usable" or not, otherwise the operation will fail.

Checks that need to be done are:

• Is the authenticator policy compliant _{java, swift, objc, flutter, react native}
• Is the authenticator supported by the mobile device hardware
• Is the authenticator not registered (registration) or registered (authentication) for the given user

The JavaDoc contains example code of these checks.

Select an authenticator

The AuthenticatorSelector is called by the SDK to select an authenticator used for the operation. It is the responsibility of the application to decide whether to ask the user to perform the selection, or to do it directly without user intervention.

1. The user initiates an action that requires to select an authenticator, like registration or authentication.
2. The application invokes Operations _{java, swift, objc, flutter, react native} to build the operation. The application provides the AuthenticatorSelector to the operation being built.
3. The SDK calls the AuthenticatorSelector.selectAuthenticator _{java, swift, objc, flutter, react native} method. The AuthenticatorSelectionContext _{java, swift, objc, flutter, react native} contains a list of authenticator objects, including AAIDs, which uniquely identify each authenticator.
4. The application shows the list of available authenticators to the user.
   1. The user selects an authenticator.
   2. The application provides the AAID of the authenticator invoking the AuthenticatorSelectionHandler.aaid _{java, swift, objc, flutter, react native} method.

The SDK can now continue the operation started by using the selected authenticator.

PIN user verifier

When authentication with PIN is required, the developer has to provide a PinUserVerifier _{java, swift, objc, flutter, react native} when building the operation. The PinUserVerifier is in charge of displaying a user interface asking the user to provide the PIN and to display the recoverable errors during authentication, for example, if the user provided an invalid PIN.

PIN user verification

The PinUserVerifier is called by the SDK to ask the user to provide a PIN.

1. The SDK calls the PinUserVerifier.verifyPin _{java, swift, objc, flutter, react native} method.
2. The application asks the user to provide a PIN. For example, the application displays a textbox where the user provides a PIN.
3. The user provides the PIN.
4. The application provides the PIN invoking the PinUserVerificationHandler.verifyPin _{java, swift, objc, flutter, react native} method.
5. The SDK validates whether the provided PIN is valid.
6. If the provided PIN is not valid, and the PIN authenticator is not locked, the SDK invokes PinUserVerifier.verifyPin again and the PinUserVerificationContext _{java, swift, objc, flutter, react native} contains a recoverable error.
7. If the provided PIN is not valid, and too many failed attempts occurred, the PIN authenticator is locked, and the operation fails. The object managing the error provided in the onError method when building the operation is invoked. For more information on PIN lockout, see Brute force attack prevention.
8. On Android, Flutter and React Native, if the provided credentials are valid, the PinUserVerifier.onValidCredentialsProvided _{java, flutter, react native} method is invoked.

Cool-down Mode

After certain number of failed attempts, the PIN authenticator will enter the cool-down mode. When in cool-down mode, providing a PIN (valid or invalid) will be ignored, and the SDK will invoke again PinUserVerifier.verifyPin without changing the number of remaining retries. This implies that the PIN authenticator cannot be locked when it is in cool-down mode.

Thus, providing a PIN when in cool-down mode will just generate unnecessary processing, and it is recommended to avoid it.

Password user verifier

When authentication with password is required, the developer has to provide a PasswordUserVerifier _{java, swift, objc, flutter, react-native} when building the operation. The PasswordUserVerifier is in charge of displaying a user interface asking the user to provide the password and to display the recoverable errors during authentication, for example, if the user provided an invalid password.

Password user verification

The PasswordUserVerifier is called by the SDK to ask the user to provide a password.

1. The SDK calls the PasswordUserVerifier.verifyPassword _{java, swift, objc, flutter, react-native} method.
2. The application asks the user to provide a password. For example, the application displays a textbox where the user provides a password.
3. The user provides the password.
4. The application provides the password invoking the PasswordUserVerificationHandler.verifyPassword _{java, swift, objc, flutter, react-native} method.
5. The SDK validates whether the provided password is valid.
6. If the provided password is not valid, and the password authenticator is not locked, the SDK invokes PasswordUserVerifier.verifyPassword again and the PasswordUserVerificationContext _{java, swift, objc, flutter, react-native} contains a recoverable error.
7. If the provided password is not valid, and too many failed attempts occurred, the password authenticator is locked, and the operation fails. The object managing the error provided in the onError method when building the operation is invoked. For more information on password lockout, see Brute force attack prevention.
8. On Android, Flutter and React Native, if the provided credentials are valid, the PasswordUserVerifier.onValidCredentialsProvided _{java, flutter, react-native} method is invoked.

Cool-down Mode

After certain number of failed attempts, the password authenticator will enter the cool-down mode. When in cool-down mode, providing a password (valid or invalid) will be ignored, and the SDK will invoke again PasswordUserVerifier.verifyPassword without changing the number of remaining retries. This implies that the password authenticator cannot be locked when it is in cool-down mode.

Thus, providing a password when in cool-down mode will just generate unnecessary processing, and it is recommended to avoid it.

Biometric user verifier

info

The biometric authenticator is specific to Android devices. For iOS please refer to the FaceID or TouchID authenticator.

When authentication using the biometric authenticator is required, the developer has to provide a BiometricUserVerifier _{java, swift, objc, flutter, react native} when building the operation. The BiometricUserVerifier does not need to implement the user interface asking for biometric credentials, as this is handled by the SDK.

Biometric user verification

The BiometricUserVerifier is called by the SDK to ask the user to provide fingerprint credentials.

1. The SDK calls the BiometricUserVerifier.verifyBiometric _{java, swift, objc, flutter, react native} method.
2. On Android, Flutter and React Native, the application invokes BiometricUserVerificationHandler.listenForOsCredentials _{java, flutter, react native} so that the SDK starts listening for biometric credentials.
3. On iOS, the application invokes the BiometricUserVerificationHandler.verify _{swift, objc} method.
4. The SDK displays a user interface asking the user to provide credentials.
5. The user provides biometric credentials.
6. The operating system validates the provided credentials.
7. If the provided biometric credentials are not valid, the operating system displays an error to inform the user. If supported by the OS version and enabled during registration, it also proposes the user to provide device credentials as fallback: PIN, gestures, or password.
8. If the provided biometric information is not valid, and too many failed attempts occurred, then the operation fails, and the object managing the error provided in the onError method when building the operation is invoked.
9. On Android, Flutter and React Native, if the provided credentials are valid, the BiometricUserVerifier.onValidCredentialsProvided _{java, flutter, react native} method is invoked.

Biometric prompt customization

On Android the biometric prompt shown to users is customizable by providing a BiometricPromptOptions _{java, flutter, react native} object when invoking the BiometricUserVerificationHandler.listenForOsCredentials _{java, flutter, react native} method. The BiometricPromptOptions allows you to set properties such as the prompt title, description, and the text for the cancel button. This enables you to tailor the user experience to your application's branding and requirements.

Android/Kotlin

val options = BiometricPromptOptions.builder()
    .title("Verification")
    .description("Please verify your identity")
    .cancelButtonText("Cancel")
    .build()
handler.listenForOsCredentials(options)

Android/Java

BiometricPromptOptions options = BiometricPromptOptions.Builder()
    .title("Verification")
    .description("Please verify your identity")
    .cancelButtonText("Cancel")
    .build();
handler.listenForOsCredentials(options);

Flutter/Dart

final options = BiometricPromptOptions(
    title: "Verification",
    description: "Please verify your identity",
    cancelButtonText: "Cancel",
)
await handler.listenForOsCredentials(options)

React Native/TypeScript

const options = BiometricPromptOptions.create(
    "Verification",
    "Please verify your identity",
    "Cancel");
await handler.listenForOsCredentials(options)

To customize biometric prompt messages on iOS (including Flutter and React Native apps), add a string catalog or a Localizable.strings file to your iOS project if it does not exist. Then, define the following keys to control the prompt messages:

Key	Default Value
face_recognition_authenticator_register_operation_prompt_message	Use Face ID to register for Mobile Authentication
fingerprint_authenticator_register_operation_prompt_message	Provide your fingerprint to register for Mobile Authentication
face_recognition_authenticator_authenticate_operation_prompt_message	Authenticate using Face ID
fingerprint_authenticator_authenticate_operation_prompt_message	Authenticate with your fingerprint

Device passcode user verifier

When authentication using the device passcode authenticator is required, the developer has to provide a DevicePasscodeUserVerifier _{java, swift, objc, flutter, react native} when building the operation. The DevicePasscodeUserVerifier does not need to implement the user interface asking for device passcode credentials, as this is handled by the SDK.

Device passcode user verification

The DevicePasscodeUserVerifier is called by the SDK to ask the user to provide device passcode credentials.

1. The SDK calls the DevicePasscodeUserVerifier.verifyDevicePasscode _{java, swift, objc, flutter, react native} method.
2. On Android, Flutter and React Native, the application invokes DevicePasscodeUserVerificationHandler.listenForOsCredentials _{java, flutter, react native} so that the SDK starts listening for device passcode credentials.
3. On iOS, the application invokes the DevicePasscodeUserVerificationHandler.verify _{swift, objc} method.
4. The SDK invokes the operating system to display a user interface asking the user to provide credentials.
5. The user provides device passcode credentials.
6. The operating system validates the provided credentials.
7. If the provided device passcode credentials are not valid, the operating system displays an error to inform the user.
8. If the provided device passcode information is not valid, and too many failed attempts occurred, then the operation fails, and the object managing the error provided in the onError method when building the operation is invoked.
9. On Android, Flutter and React Native, if the provided credentials are valid, the DevicePasscodeUserVerifier.onValidCredentialsProvided _{java, flutter, react native} method is invoked.

Device Passcode prompt customization

On Android the device passcode prompt shown to users is customizable by providing a DevicePasscodePromptOptions _{java, flutter, react native} object when invoking the DevicePasscodeUserVerificationHandler.listenForOsCredentials _{java, flutter, react native} method. The DevicePasscodePromptOptions allows you to set the prompt title and the description. This enables you to tailor the user experience to your application's branding and requirements.

Android/Kotlin

val options = DevicePasscodePromptOptions.builder()
    .title("Verification")
    .description("Please verify your identity")
    .build()
handler.listenForOsCredentials(options)

Android/Java

DevicePasscodePromptOptions options = DevicePasscodePromptOptions.Builder()
    .title("Verification")
    .description("Please verify your identity")
    .build();
handler.listenForOsCredentials(options);

Flutter/Dart

final options = DevicePasscodePromptOptions(
    title: "Verification",
    description: "Please verify your identity",
)
await handler.listenForOsCredentials(options)

React Native/TypeScript

const options = DevicePasscodePromptOptions.create(
    "Verification",
    "Please verify your identity");
await handler.listenForOsCredentials(options)

To customize device passcode prompt message on iOS (including Flutter and React Native apps), add a string catalog or a Localizable.strings file to your iOS project if it does not exist. Then, define the following keys to control the prompt message:

Key	Default value
device_passcode_authenticator_register_operation_prompt_message	Authenticate with Device Passcode
device_passcode_authenticator_authenticate_operation_prompt_message	Authenticate using device Passcode

Fingerprint user verifier

info

The fingerprint authenticator is supported only on Android devices. The SDK supports the fingerprint authenticator to handle older Android OS versions that do not support the biometric authentication. If the biometric authenticator is supported by the operating system, we recommend to use that authenticator, and not to allow class 2 sensors for maximum security. This means that only the fingerprint will be available as an authentication method of the biometric authenticator.

When authentication with fingerprint is required, the developer has to provide a FingerprintUserVerifier _{java, flutter, react native} when building the operation. The FingerprintUserVerifier is in charge of displaying a user interface asking the user to provide fingerprints, and to display the recoverable errors during authentication. For example, if the user moved the finger too quickly.

Fingerprint user verification

The FingerprintUserVerifier is called by the SDK to ask the user to provide fingerprint credentials.

1. The SDK calls the FingerprintUserVerifier.verifyFingerprint _{java, flutter, react native} method.
2. The application invokes FingerprintUserVerificationHandler.listenForOsCredentials _{java, flutter, react native} so that the SDK starts listening for fingerprint credentials. The SDK does not automatically display relevant UI.
3. The application asks the user to provide fingerprint credentials, for example, by displaying a screen with an image of a fingerprint.
4. The user provides fingerprint credentials.
5. The SDK validates that the provided fingerprints are valid.
6. If the provided fingerprints are not valid, the SDK invokes FingerprintUserVerifier.verifyFingerprint again, and the FingerprintUserVerificationContext _{java, flutter, react native} contains a recoverable error.
7. If the provided fingerprints are not valid, and too many failed attempts occurred, then the operation fails and the object managing the error that was provided in the onError method when building the operation is invoked.
8. If the provided credentials are valid, the FingerprintUserVerifier.onValidCredentialsProvided _{java, flutter, react native} method is invoked.