5 steps to implement Biometric authentication in Android
I recently got a chance to work with the new BiometricPrompt API feature released by Google this year. While fingerprint authentication support has been available since Android 6.0, the new BiometricPrompt promises more accuracy and a consistent level of security across all devices that run our application.
Having implemented biometric authentication in an android app recently, I thought I would highlight some of the basic steps required to implement this feature in an android app.
So let’s begin!
Step 1: Add the required permissions in the AndroidManifest.xml
Step 2: Check if the device supports Biometric authentication
Specifically, we are going to check if the following conditions are met:
- The device is running Android 6.0 or higher
- The device features a fingerprint sensor
- The user has granted your app permission to access the fingerprint sensor.
- The user has registered at least one fingerprint on their device.
We can create a separate util class to check if the above conditions are met:
Step 3: Display BiometricPrompt dialog
Once the above conditions are checked, we can check if the android version in the device is Android P. The Biometric dialog is only supported in Android P. Let’s take a look at that first.
Below code is to display a biometricPrompt dialog:
Using the BiometricPrompt builder we can:
- setTitle() — Set the title to display (Required)
- setSubtitle() — Set the subtitle to display (Optional)
- setDescription() — Set the description to display(Optional)
- setNegativeButton() — Set the text for the negative button(Required). You must also provide an Executor instance and a click listener for the negative button.
Note: You can’t customise the icon or error message that are used within the dialog.
Step 4: Handle authentication Callback
Next we use the BiometricPrompt.AuthenticationCallback to listen for authentication events from the users. It includes 4 methods:
onAuthenticationSucceeded
When the fingerprint is has been successfully matched with one of the fingerprints registered on the device, then this callback will be triggered. An AuthenticationResult object will be passed the the callback.
onAuthenticationFailed
When the fingerprint doesn’t match with any of the fingerprints registered on the device, then this callback will be triggered.
onAuthenticationError
When an unrecoverable error has been encountered and the authentication process has completed without success, then this callback will be triggered. The callback is provided with an error code to identify the cause of the error, along with the error message. The different types of error codes that can occur are:
- BIOMETRIC_ERROR_LOCKOUT —The operation was canceled because the API is locked out due to too many attempts.
- BIOMETRIC_ERROR_LOCKOUT_PERMANENT — The operation was canceled because BIOMETRIC_ERROR_LOCKOUT occurred too many times.
- BIOMETRIC_ERROR_NO_SPACE — The operation cannot be completed because there’s not enough storage remaining to complete the operation.
- BIOMETRIC_ERROR_TIMEOUT — Timeout occur as the current request has been running too long.
- BIOMETRIC_ERROR_UNABLE_TO_PROCESS — The sensor was unable to process the current image.
- BIOMETRIC_ERROR_USER_CANCELED — The user canceled the operation.
- BIOMETRIC_ERROR_VENDOR — If there are conditions that do not fall under one of the above categories.
- BIOMETRIC_ERROR_NO_BIOMETRICS — The user does not have any biometrics registered in the device.
- BIOMETRIC_ERROR_CANCELED — The operation was canceled because the biometric sensor is unavailable.
- BIOMETRIC_ERROR_HW_NOT_PRESENT — The device does not have a biometric sensor.
- BIOMETRIC_ERROR_HW_UNAVAILABLE — The device hardware is unavailable.
onAuthenticationHelp
This method is called when a non-fatal error has occurred during the authentication process. The callback will be provided with an help code to identify the cause of the error, along with a help message. The different types of help codes that can occur are:
- BIOMETRIC_ACQUIRED_IMAGER_DIRTY — The biometric image was too noisy due to suspected dirt on the sensor.
- BIOMETRIC_ACQUIRED_INSUFFICIENT — The biometric image was too noisy to process. This could be because of a variety of reasons but generally this is because the image was not readable.
- BIOMETRIC_ACQUIRED_PARTIAL — Only a partial biometric image was detected.
- BIOMETRIC_ACQUIRED_TOO_FAST — The biometric image was incomplete because the user moved their finger around the sensor too fast.
- BIOMETRIC_ACQUIRED_TOO_SLOW — The biometric image was unreadable due to lack of motion from the user around the sensor.
If you have an Android P device, then that’s it!
But what happens if the device does not support Android P?
So all versions below Android P do not support the BiometricPrompt api. Luckily, we can still use the FingerprintManagerCompat API to authenticate our users. This involves:
- Initialising KeyStore and generating key — The Android keystore allows you to store cryptographic keys in a way that makes them more difficult to extract from the device. It also restricts how and when each key can be used. Once the key is generated, it will be stored securely on device by using KeyStore instance and used for initialising the cipher object in the next step.
2. Initialising the cipher — This initialisation of Cipher object will be used to create CryptoObject instance. While initialising cipher , the generated and the stored key in the keystore container is used. If the cipher is successfully initialised, then we can assume that the previously stored key is not invalidated and it can still be used.
3. Creating a CrytoObject — The fingerprint scanner will use the CryptoObject to help authenticate the results of a fingerprint scan. The CryptoObject is used to ensure that the fingerprint authentication result was not tampered with. In order to create an instance of the CryptoObject:
4. Assigning the CryptoObject to the FingerprintManagerCompat — Instantiate a FingerprintManagerCompat and call the authenticate method.
The authenticate method requires the following parameters:
- cryptoObject
- The second parameter is always zero — The Android documentation identifies this as set of flags and is most likely reserved for future use.
- The third parameter, cancellationSignal — is an object used to turn off the fingerprint scanner and cancel the current request.
- The fourth parameter, AuthenticationCallback class — This will be the same as the BiometricAuthenticationCallback.
- The fifth parameter, optional Handler instance — If a Handler object is provided, the FingerprintManagerCompat will use the Looper from that object when processing the messages from the fingerprint hardware.
5. Creating a UI similar to the BiometricPrompt Dialog — So now that we have enabled the fingerprint authentication in devices above 6.0 and below 8.0, we need to display an user interface to initiate the authentication. I have created a CustomDialog class that replicates the BiometricPrompt dialog (to maintain consistency across devices).
The final output will be like this:
Conclusion
I hope this post was helpful to provide an insight into the new BiometricPrompt API. You can checkout the full code in Github.
I have also developed a small SDK that allows for easy implementation of fingerprint authentication. It can be added to any android app.
Please check it out and let me know your thoughts!
Happy coding!
