Skip to content

Fingerprint authentication


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.

Fingerprint security

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 registerAuthenticator() method:

void registerAuthenticator(final OneginiAuthenticator authenticator, final OneginiAuthenticatorRegistrationHandler handler);
The first parameter indicates the authenticator you're about to register (one of authenticators returned in previous step). The second parameters is OneginiAuthenticatorRegistrationHandler instance to get a callback about successful registration or report reason of error that could occur during registration:
 public interface OneginiAuthenticatorRegistrationHandler {

   // Registration was successful
   void onSuccess(CustomInfo customInfo);

   // Registration failed for any reason
   void onError(OneginiAuthenticatorRegistrationError error);

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

Fingerprint icon

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 OneginiFingerprintCallback#fallbackToPin() method.

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 UserClient instance. 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.

Root detection

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.

Fingerprint changes

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.