Authenticate user with fingerprint¶
The SDK allows you to authenticate users with the fingerprint scanner (if available on the device). You can use it for both regular authentication as well as mobile authentication. Users will be able to scan their fingerprint as many times as the Android system will allow them to. If Android fingerprint API will return an error for any reason (for example when too many failed attempts was detected), the SDK will revoke fingerprint authentication and perform a fallback to PIN authentication.
Enabling fingerprint authentication¶
In order to enable fingerprint authentication for user you need to request a list of not yet registered authenticators with
UserClient.getNotRegisteredAuthenticators(final UserProfile userProfile). This method can be used after user is authenticated and will return a set of
OneginiAuthenticator that are possible to register. Then you can register chosen authenticator providing the authenticator's instance to
UserClient.registerAuthenticator(final OneginiAuthenticator authenticator, final OneginiAuthenticatorRegistrationHandler handler) method, along with the
handler that will inform you about success or failure of the registration process. If your device haven't met one of the
requirements, the fingerprint authenticator won't be present on the list of authenticators.
Example code for registering a fingerprint authenticator
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
Note that registering a new authenticator doesn't make it a preferred authenticator to be used. By default preferred authenticator is PIN, so if you want to
change it, you need to inform the SDK about it with
UserClient.setPreferredAuthenticator(final OneginiAuthenticator auth) providing any registered
Please note that CustomInfo is an optional param that will be always null during fingerprint authenticator registration.
The SDK provides two interfaces (
respectively: regular and push authentication) that you can implement in your application to use the fingerprint authentication. Later you will need to provide
OneginiClientBuilder instance as shown below:
Example code for supplying fingerprint auth request handlers to the SDK
1 2 3 4 5 6 7
OneginiFingerprintAuthenticationRequestHandler interface exposes four methods you should use to control the process of scanning the fingerprint and informing
the end user about the progress:
startAuthentication(final UserProfile userProfile, final OneginiFingerprintCallback callback)triggered when a new fingerprint authentication request is made, providing an
UserProfileobject and a fingerprint callback;
onNextAuthenticationAttempt()called when user provided incorrect fingerprint but still haven't reach the failed attempts limit,
onFingerprintCaptured()invoked when user scanned his fingerprint and the fingerprint validation is performed. That's a good moment to show an update on the UI informing user about received attempt,
finishAuthentication()triggered when fingerprint scanning finished either with success or an error.
OneginiMobileAuthWithPushFingerprintRequestHandler works in exactly the same manner with a single change in parameters of
where instead of the
UserProfile you get the
OneginiMobileAuthenticationRequest object containing information about the push request as well as
UserProfile. You can
read more about mobile fingerprint authentication in Mobile authentication topic guide.
Example code for OneginiFingerprintAuthenticationRequestHandler implementation
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
To control the flow of fingerprint authentication you should use provided
OneginiFingerprintCallback callback. It consists of three methods:
acceptAuthenticationRequest()that should be called when user accepts fingerprint authentication request,
denyAuthenticationRequestwhich should be triggered when user denies the fingerprint authentication request, which can be done by calling the
fallbackToPinthat should be invoked when user decides to resign from fingerprint authentication and wants to enter his PIN to finish authentication.
In the example code above you should use the static instance of
OneginiFingerprintCallback in the
FingerprintActivity to react on user actions.