Customizing the Biometric UI

Replacing the UI for the Biometric Authenticator

Newer Android devices can have different or multiple biometric sensors. The Android App SDK versions 6.0 and later include an updated Digipass S3 fingerprint authenticator that can be used on Android devices that support alternate biometric authentication. However, this authenticator uses the word “Fingerprint” in the UI, even when no fingerprint sensor is available on a device that supports alternate biometric authentication.

The Digipass S3 Android Biometric Authenticator UI Customization Technical Note contains detailed examples that show the effect of updating strings used by the biometric authenticator.

Contact support for a copy of this technical note.

Authentication Fallback Option

During authentication if the user is unable to successfully scan their fingerprint or chooses not to use the native fingerprint sensor, your app can provide a fallback to a different method of authentication - typically username and password or passcode. This option is supported only when your app uses the FingerprintManager API. The BiometricPrompt API doesn’t support this feature.

The image above shows the UI that the fingerprint authenticator displays to the user in a fallback situation. The end user can tap the button labeled USE ALTERNATE AUTHENTICATION to sign in with the alternate method. You can specify any button label text you want.

To enable this option, create a special extension that the App SDK passes to the fingerprint authenticator. For the definition of extension, see Terminology. The extension contains information that tells the authenticator to change its appearance and behavior when the user's fingerprint doesn't match or if they cancel the fingerprint scan. Create the extension and add it to the list of extensions using the helper class ExtensionList, as shown below. ExtensionList.addFallbackExtension() takes one argument which is the label of the fallback button.

val extensions = ExtensionList()
extensions.addFallbackExtension("USE ALTERNATE AUTHENTICATION")

After you add your extensions to the list, pass the list to appSDKPlus.

appSDKPlus.setExtensions(extensions)

When the user taps the fallback button, either AdaptiveUI.getAuthenticationFragment() or AdaptiveUI.authenticate() returns ResultType.FALLBACK. Your app checks for this result and asks the end user to perform an alternate authentication method.

Working Example in Tutorial App

• Refer to file MainActivity.kt.

Customizing the Biometric Authentication Behavior

You can customize the biometric authenticator to better suit your needs. For example, you can allow face scans to be done without explicit user consent. This section discusses 2 common use cases and describes how you can implement the necessary customizations.

Case 1: Disable Biometric Confirmation

Biometric authentication might require a user's confirmation to complete authentication. For example, if a user authenticates using a face or iris authenticator, they are prompted to confirm after biometric recognition has taken place. This can negatively impact usability.

Use the App SDK's biometric options extension to selectively disable biometric confirmation for registration or authentication. For details, see The Biometric Option Extension.

Case 2: Disable an Extra Fingerprint Scan When Migrating to FIDO Registration

You need to migrate existing end users of your company's apps from non-FIDO fingerprint authentication to FIDO fingerprint authentication. Your end users would need to enter their fingerprint twice: once to login to your app and a second time to complete FIDO registration.

For a better user experience, you can disable the biometric scan to get the following user interaction:

• A customer signs in to your app using their fingerprint with the existing non-FIDO fingerprint authentication.

• Your app initiates a FIDO registration.

• The App SDK processes that registration request without requiring the customer to rescan their fingerprint.

Use the App SDK's biometric options extension to allow FIDO registration to reuse a biometric scan from non-FIDO sign in within a certain time frame. For details, see The Biometric Option Extension.

The Biometric Option Extension

An example biometric option extension with all available fields is shown below. This example disables biometric confirmation. If registration takes place within 30 seconds of a conventional, non-FIDO login, it utilizes a user's scanned biometric from login as their FIDO biometric. Your app passes in this extension, by assigning it to the extras parameter. This can be done for AppSDKPlus.register(), AdaptiveUI.transact(), or AdaptiveUI.authenticate().

{
    "id":"noknok.auth.biometric_options",
    "data":"{\"confirmationRequired\":false,\"duration\":30,\"scan\":false}",
    "fail_if_unknown":false
}

The data fields of this extension are described below. To emulate the behavior of the cases described above:

• Case 1: Assign false to confirmationRequired.

• Case 2: Assign a value to duration and false to scan.

If you wish to disable biometric confirmation and disable an extra fingerprint scan when migrating to FIDO registration, add only one noknok.auth.biometric_options extension and list all the fields in data.

Working Examples in Tutorial App

• To disable confirmation, see the method listed below.

  • ExtensionHelper.java file: Shows how to create the biometric options extension.

  • AuthenticateTask.java file's disableBiometricConfirmation() method: Shows how to pass the extension to an authentication request.

• To disable the extra fingerprint scan when migrating to FIDO registration, see the files listed below.

  • ExtensionHelper.java file: Shows how to create the biometric options extension.

  • RegisterFragment.java file: Shows how to pass the extension to a registration request.