Authenticate user with fingerprint
Introduction
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
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
authenticator.
Please note that CustomInfo is an optional param that will be always null during fingerprint authenticator registration.
Authentication handlers
The SDK provides two interfaces (OneginiFingerprintAuthenticationRequestHandler
and OneginiMobileAuthWithPushFingerprintRequestHandler
for
respectively: regular and push authentication) that you can implement in your application to use the fingerprint authentication. Later you will need to provide
them to OneginiClientBuilder
instance as shown below:
Example code for supplying fingerprint auth request handlers to the SDK
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 anUserProfile
object 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 startAuthentication()
method,
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
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,denyAuthenticationRequest
which should be triggered when user denies the fingerprint authentication request, which can be done by calling theOneginiFingerprintCallback#denyAuthenticationRequest
method.fallbackToPin
that 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.