Fingerprint authentication allows users to perform biometric authentication by the use of Android's Fingerprint API introduced in Android Marshmallow (6.0). The biggest gain of enabling Fingerprint Authentication is the improved end-users experience. Users are now enabled to access their sensitive data or authenticate transactions using Android's common fingerprint validation.
The fingerprint data is stored on a device securely and should never leave a device. Google has very strict guidelines for device manufacturers about how fingerprint data should be stored and handled on the device:
- Capturing and recognizing your fingerprint must happen in a secure part of the device hardware known as a Trusted Execution Environment (TEE). Hardware access must be limited to the TEE and protected by an SELinux policy.
- Fingerprint data must be secured within sensor hardware or trusted memory so that images of your fingerprint are inaccessible.
- Only the encrypted form of the fingerprint data can be stored on the file system, even if the file system itself is encrypted.
- Fingerprint data must be removed from the device when a user is removed.
- Rooting of a device must not compromise fingerprint data.
However, there are a couple of things, that you should keep in mind when using fingerprint authentication:
- Using the fingerprint may be less secure than a strong PIN because with fingerprint authentication the actual authentication step is performed solely on the mobile device, whereas the PIN authentication is done server side.
- The Android OS assumes that all fingerprints registered on a device belong to the same person. If this is not the case (for example a parent and a child have both registered their fingerprints on the same device) then the Onegini SDK cannot distinguish whether the parent or the child performed fingerprint authentication.
- A physical copy of your fingerprint could be used to unlock your phone. You leave fingerprints on many things you touch, including your phone.
A User can enable fingerprint authentication only if all of the following requirements are met:
- the device is running Android Marshmallow (6.0, API Level 23) or greater
- the device is not rooted
- the device has hardware fingerprint reader
- the user has already registered at least one fingerprint
- the client configuration on the Token Server allows use of fingerprint authentication
Enabling Fingerprint Authentication¶
To enable fingerprint authentication the user is required to enter his PIN. If the entered PIN is valid, fingerprint authentication is enabled. After enabling fingerprint authentication the user will be able to access his mobile application by scanning his fingerprint.
In order to register fingerprint authenticator you need to make sure that the authenticator is available for registration by calling
Set<OneginiAuthenticator> getNotRegisteredAuthenticators(final UserProfile userProfile) method on the
UserClient instance. When the authenticator is available for registration, you can register it with
OneginiAuthenticatorRegistrationHandlerinstance to get a callback about successful registration or report reason of error that could occur during registration:
1 2 3 4 5 6 7 8
To cancel enabling fingerprint authentication before the user enters a PIN use the
OneginiPinCallback#denyAuthenticationRequest method, you can read more
about this callback in the create PIN request handler section.
Please note that the CustomInfo is an optional parameter that will be always null in case of fingerprint authentication.
Authenticate using Fingerprint Authentication¶
Whenever fingerprint authentication is enabled and the device is not rooted the user will be prompt to scan his/her finger instead of providing his/her PIN in
order to authenticate. The SDK will use
OneginiFingerprintAuthenticationRequestHandler interface to ask for a fingerprint. The handler should show a view that
includes a common Android's fingerprint icon, as described on Android Developers
Due to the fact that fingerprint scanning is not perfect (e.g. the user may have wet or dirty hands, also the temperature may impact the scan result) the user
can always choose to fallback on PIN authentication. This can be done by calling
Also, after failing to scan a fingerprint for the allowed number of times, the SDK will automatically fallback on the PIN authentication method. If the user will not be able to provide a valid PIN within the allowed number of times, he will be deregistered.
Disabling Fingerprint Authentication¶
To disable fingerprint authentication for currently authenticated user profile call
disableFingerprintAuthentication() on the
The method will revoke user's fingerprint refresh token on both client and server side. User will still be able to login using his PIN.
The root detection check is applied during the fingerprint authentication, even if root detection is disabled for the application itself. The reason is that rooted devices are more vulnerable, as the application sandbox as well as AndroidKeystore can be violated. The situation is even more serious for clients who are not using tampering protection.
As explained in google docs keys stored in the AndroidKeyStore will become permanently invalidated once a new fingerprint is enrolled or all fingerprints are disenrolled. In such case, the SDK will deregister fingerprint authenticator and the user will have to enroll for fingerprint authentication again.
Using fingerprint authentication with multiple user profiles¶
The Onegini Android SDK v5.03.00 introduced support for multiple user profiles. When this feature is implemented by you, an end-user will be able to create and use different accounts (profiles) on the same device. Each profile has it's own separated PIN, push notification support and other features. However, as stated above the Android Fingerprint API was designed with the assumption that a device is being used by only one person. This person can register multiple fingerprints, but from the API perspective they all belong to the same person. In particular, if a device is being shared between multiple people and all of them will register one or more fingerprints, the API is not able to distinguish whom of them performed authentication.
Because of this, if the application supports both the multiple profiles feature and fingerprint authentication, you should keep in mind, that it has some (potential) drawbacks. Let's assume that Bob is the owner of a device, but he shares it with his wife Alice. They have both registered their fingerprints and they both created profile in the ExampleApp.
- When the ExampleApp asks Bob for a fingerprint for login or to confirm a transaction, any valid (registered) fingerprint will be accepted. Because of that Alice can login to Bob's account using her fingerprint.
- When Bob tries to authenticate with a fingerprint but the exceeds number of failed attempts, the Android Fingerprint API can be blocked automatically for some amount of time (around 15-30 seconds). If Alice will try to log in to her account shortly after that, she might not be able to do so before the API will be unblocked.
- When the Token Server detects improper usage of a fingerprint refresh token that indicates a corrupted or modified fingerprint keystore - all fingerprint refresh tokens on this device will be revoked on the server side.