Skip to content

Fingerprint

Fingerprint and Biometric Usage

Fingerprint and biometric usage involves three screens:

  • Enable screen (EnableFingerprintActivity)
  • Authentication screen (FingerprintActivity)
  • Authentication Error screen (FingerprintErrorActivity).

You only have to use FingerprintActivity. The library takes care of deciding which screen to launch based on the situation.

FingerprintActivity now supports the new androidx.biometric library (part of Android Jetpack), which will display a BiometricPrompt when users have other biometrics (such as face or iris) enrolled. FingerprintActivity also decides which authentication procedure to use (FingerprintManager or BiometricPrompt) so you don't have to.

Note

The library's FingerprintManager is in the process of being deprecated and will soon be superseded (fully) by BiometricPrompt.

Fingerprint Activity

The FingerprintActivity can be started with the standard startActivityResult method of the Activity and you can configure it via the Fingerprintsettings class. There are currently two authentication procedures and each procedure has its own layout:

Fingerprint Authentication Layout

Contains the following elements:

  • Headline label
  • Detailed text (information prompting the user to use their fingerprint to authenticate)
  • Error message label
  • Fallback button

Biometric Authentication Layout

Contains the following elements:

  • Title (same text as the Fingerprint headline label)
  • Subtitle (optional)
  • Description
  • Fallback button (same text and functionality as the Fingerprint Fallback button)

Note

Fingerprint headline label and BiometricPrompt title share the same String object, thus they are equal. Both the Fallback buttons' text also refer to the same String object.

There are simple methods to assign values to all of these elements, as well as default values. Each can be customized via the Settings configuration, that is you can overwrite them via the corresponding set methods of the FingerprintSettings class (the error message label is hidden by default). The FingerprintSettings class can be instantiated with a default constructor. The set methods should be called before calling the saveToIntent method, which saves the configuration into an Intent. Finally, this intent should be used when starting the FingerprintActivity via the startActivityForResult method.

Furthermore, the authentication screen and the BiometricPrompt are extended to support fallback to enter a passcode. Both layouts contain a fallback button (labeled "Fallback button"), allowing the user to fallback to enter a passcode instead. This button is disabled by default and will be enabled only if the fingerprint/biometric passcode screen is configured explicitly to enable it.

Lastly, by default, a confirmation button click is required if a user successfully authenticates using BiometricPrompt. You can disable this confirmation requirement by passing false when setting this option in FingerprintSettings.

Customizing the Fingerprint/Biometric Authentication Screen

You can use the FingerprintSettings object to customize the labels of the authentication screen. The following options are available (each method has a corresponding getter method):

public void setHeadlineLabel(String headlineLabel) {
    this.headlineLabel = headlineLabel;
}

public void setDetailLabel(String detailLabel) {
    this.detailLabel = detailLabel;
}

public void setFallbackButtonTitle(String fallbackButtonTitle) {
    this.fallbackButtonTitle = fallbackButtonTitle;
}

public void setFallbackButtonEnabled(boolean fallbackButtonEnabled) {
    this.fallbackButtonEnabled = fallbackButtonEnabled;
}

 public void setConfirmationRequired(boolean confirmationRequired) {
     this.confirmationRequired = confirmationRequired;
 }

 public void setPromptSubtitle(String promptSubtitle) {
  this.promptSubtitle = promptSubtitle;
 }

 public void setPromptDesc(String promptDesc) {
  this.promptDesc = promptDesc;
 }

EnableFingerprintActivity

The EnableFingerprintActivity is automatically launched when the user enters the authentication screen (FingerprintActivity) when there are no fingerprints/biometrics enrolled on the device, or if the device is not secured. You can configure EnableFingerprintActivity via the EnableFingerprintsettings class.

Enable Fingerprint Screen Layout

Contains the following elements:

  • Headline label
  • Detailed text
  • Error message label
  • Enable Fingerprint button

All of these labels can be customized via the Settings configuration, that is you can overwrite them via the corresponding set methods of the EnableFingerprintsettings class (the error message label is hidden by default). The EnableFingerprintsettings class can be instantiated with a default constructor. The set methods should be called before calling the saveToIntent method, which saves the configuration into an Intent. Finally this intent should be used when starting the FingerprintActivity via the startActivityForResult method.

When the user clicks the Enable Fingerprint button, the Android system settings screen will launch, where a fingerprint or a biometric can be enrolled for authentication use.

The error message is hidden by default. The library makes it visible when the user navigates back from the Android system settings screen after the user has NOT enrolled a fingerprint (or any other biometric), or if the device is still not secured.

FingerprintErrorActivity

After 5 unsuccessful attempts (due to the Android security system), the FingerprintErrorActivity will automatically appear to display feedback and an option to reset the passcode.

Authentication Error Screen Layout

Contains the following elements:

  • Headline label
  • Detailed text
  • Reset button

All these labels can be customized via the Settings configuration, that is you can overwrite them via the corresponding set methods of the FingerprintErrorSettings class (the error message label is hidden by default). The FingerprintErrorSettings class can be instantiated with a default constructor. The set methods should be called before calling the saveToIntent method, which saves the configuration into an Intent. Finally, this intent should be used when starting the FingerprintActivity via the startActivityForResult method.

Customizing the Authentication Error Screen

You can use the FingerprintErrorSettings object to customize the labels of the Authentication Error screen. The following options are available (each method has a corresponding getter method):

     public void setFingerprintErrorHeadlineLabel(String headlineLabel) {
         this.fingerprintErrorHeadlineLabel = headlineLabel;
     }

     public void setFingerprintErrorDetailLabel(String detailLabel) {
         this.fingerprintErrorDetailLabel = detailLabel;
     }

     public void setFingerprintErrorResetButtonTitle(String fingerprintErrorResetButtonTitle) {
         this.fingerprintErrorResetButtonTitle = fingerprintErrorResetButtonTitle;
     }

     public void setFingerprintErrorResetEnabled(boolean fingerprintErrorResetEnabled) {
         this.fingerprintErrorResetEnabled = fingerprintErrorResetEnabled;
     }

Implementation of the Callback Methods

The implementation of these methods will be executed on a dedicated background thread of the caller activity, more precisely the background thread of the headless fragment of the caller activity. This fragment is handed over to the method as parameter. You can access the caller activity via the getActivity() method of this fragment. Please note that the result of the getActivity call might be a null value if there is no active activity in the background, for example due to an ongoing change orientation process.

The callback method waits for responses synchronously, so if you need asynchronous communication, then you must wait on this thread until the asynchronous response arrives. You are allowed block the thread because you are on a dedicated background thread.

As a consequence, you have to be prepared to handle the interrupted flag of the thread. For example: if the user taps the Back button, or if the system destroys the caller fragment, then this thread will be interrupted. If the execution of your callback method was successfully interrupted, that is the normal processing was not completed, then you should throw InterruptedException from your implementation to indicate that the processing was canceled.

The fingerprint/biometric authentication receives the cipher through the getCipher callback. The application developer must create the cipher. This cipher is used by the device sensor for authenticating. The authenticated cipher is passed back to the application with the startDone callback.

The fallback callback, as the name suggests, allows the user to use a passcode if the fingerprint/biometric authentication did not succeed.

With the reset callback the user can reset the passcode.

 public class FingerprintActionHandlerImpl implements FingerprintActionHandler {
     KeyHandler keyHandler;
     @Override
     public Cipher getCipher(Fragment fragment) throws InterruptedException, FingerprintException {
         try {
             ((DemoApplication) fragment.getActivity().getApplication()).delay();
             keyHandler = new KeyHandler();
             keyHandler.getInstanceOfCipher();
             keyHandler.initKeyGenerator();
             keyHandler.loadKeyStore();
             if (KeyHandler.passcodeInputMode == PasscodeInputMode.CREATE) {
                 keyHandler.generateKey();
                 keyHandler.initCipherInEncryptMode();
                 keyHandler.saveIVToPref();
             } else {
                 keyHandler.loadIVFromPref();
                 keyHandler.setSecretKey();
                 keyHandler.initCipherInDecryptMode();
             }

             return keyHandler.cipher;

Add Fingerprint Authentication Screen Activity to Your Manifest File

The FingerprintActivity should be added to the AndroidManifest.xml file in an activity XML tag. You must also specify the action_handler metadata tag.

    <activity
        android:name="com.sap.cloud.mobile.onboarding.fingerprint.FingerprinActivity"
        android:label="@string/app_name"
        android:theme="@style/Theme.AppCompat.Light.NoActionBar"
      <meta-data
          android:name="action_handler"
          android:value="com.sap.cloud.mobile.fiori.demo.onboarding.FingerprintActionHandlerImpl"/>
    </activity>

Last update: August 12, 2020