Registration/authentication request handlers
Implementing registration/authentication request handlers
When you call the registerUser
or the authenticateUser
method on the UserClient
, the SDK needs some user input in order to finish the process (i.e. PIN or
fingerprint). For this you need to provide your own implementation of interfaces called "request handlers" using the OneginiClientBuilder
methods.
The OneginiCreatePinRequestHandler
andOneginiPinAuthenticationRequestHandler
interfaces are required in order to perform basic authentication using a PIN.
All other handlers are optional and should be provided only when the app actually uses functionalities like fingerprint or mobile authentication.
Registration request handler
OneginiBrowserRegistrationRequestHandler
The OneginiBrowserRegistrationRequestHandler
class is responsible for handling the registration process using an external web browser. It's
startRegistration()
method will be invoked by the SDK whenever there will be a need to ask for an access grant using web browser. In such case you should open
provided Url in a separate web browser app and return the result via OneginiBrowserRegistrationCallback
.
OneginiBrowserRegistrationCallback
The OneginiBrowserRegistrationCallback
is passed by the SDK when a registration in web browser is requested.
When the authentication in web browser is completed, the Token Server will return a URI that has to be passed in handleRegistrationCallback
method.
When the authentication has failed or was aborted, the denyRegistration
can be called in order to cancel the registration (which will result in the
ACTION_CANCELED
error).
Authentication request handlers
Request handlers used by the SDK when a user has to authenticate himself (log in).
OneginiCreatePinRequestHandler
The OneginiCreatePinRequestHandler
class should be implemented by the application developer and provided to the OneginiClientBuilder's constructor.
The OneginiCreatePinRequestHandler
class is responsible for handling the PIN creation process, its startPinCreation()
method will be invoked by the SDK
whenever there will be a need to create a new PIN (during registration, or during the change pin action). If the PIN provided by user
hasn't met PIN policy, the SDK will call the onNextPinCreationAttempt()
method with the OneginiPinValidationError
object. Whenever the correct PIN was
created or the action was canceled by the user, the finishPinCreation()
method will be called by the SDK.
OneginiPinAuthenticationRequestHandler
The OneginiPinAuthenticationRequestHandler
class should be implemented by and provided to OneginiClientBuilder's constructor.
The OneginiPinAuthenticationRequestHandler
class is responsible for handling PIN authentication requests, its startAuthentication()
method will be invoked
by the SDK whenever there will be a need to authenticate a user. If the PIN provided by user is incorrect, but his failed attempts limit was not been
reached yet, the SDK will call the onNextAuthenticationAttempt()
method with the AuthenticationAttemptCounter
object containing information about failed,
remaining and maximum attempts counters. Whenever authentication process is finished regardless of the outcome (success or error), the SDK will call
finishAuthentication()
method.
OneginiFingerprintAuthenticationRequestHandler
The OneginiFingerprintAuthenticationRequestHandler
class can be implemented and provided to OneginiClient using the
OneginiClientBuilder#setFingerprintAuthenticationRequestHandler()
method. The OneginiFingerprintAuthenticationRequestHandler
class is responsible for
handling fingerprint authentication requests. The startAuthentication()
method will be invoked by the SDK whenever there is a need to authenticate the user
using his/her Fingprint. When the user provides a fingerprint to the scanner, the SDK will call the onFingerprintCaptured()
method. At this point
the fingerprint hasn't been validated yet, but you can use this method to inform the user that his fingerprint was captured from the scanner and is now being
processed. If the fingerprint provided by the user is incorrect, but his failed attempts limit hasn't been reached yet, the SDK will call the
onNextAuthenticationAttempt()
method. Whenever authentication process is finished regardless of the outcome (success or error), the SDK will call the
finishAuthentication()
method.
Mobile authentication request handlers
This paragraph describes the Handlers used by the SDK when a user has to handle an incoming mobile authentication request (push message).
OneginiMobileAuthWithPushRequestHandler
The OneginiMobileAuthWithPushRequestHandler
class can be implemented provided to the OneginiClient using the
OneginiClientBuilder#setMobileAuthWithPushRequestHandler()
method. The OneginiMobileAuthWithPushRequestHandler
class is responsible for handling an
incoming mobile authentication request (simple authentication with "Accept" and "Deny" options). The SDK will call the startAuthentication()
method when a
new mobile authentication request has been received. Whenever authentication is finished regardless of the outcome (success or error), the SDK will call the
finishAuthentication()
method.
OneginiMobileAuthWithPushPinRequestHandler
The OneginiMobileAuthWithPushPinRequestHandler
class can be implemented and provided to OneginiClient using the
OneginiClientBuilder#setMobileAuthWithPushPinRequestHandler()
method. The OneginiMobileAuthWithPushPinRequestHandler
class is responsible for handling
an incoming mobile authentication request which needs to be confirmed with PIN authentication. The SDK will call the startAuthentication()
method when a new
mobile authentication request was received. If the PIN provided by the user is incorrect, but his failed attempts limit hasn't been reached yet, the SDK will
call the onNextAuthenticationAttempt()
method with the failed, remaining and maximum attempts counters provided by AuthenticationAttemptCounter
param.
Whenever authentication is finished regardless of the outcome (success or error), the SDK will call the finishAuthentication()
method. In case when the mobile
authentication with push was triggered as a result of a failed mobile authentication request with other authenticator type (i.e. fingerprint), the
startAuthentication()
method will also receive a non-null OneginiMobileAuthenticationError
object with the error that caused the fallback.
OneginiMobileAuthWithPushFingerprintRequestHandler
The OneginiMobileAuthWithPushFingerprintRequestHandler
class can be implemented and provided to OneginiClient using the
OneginiClientBuilder#setMobileAuthWithPushFingerprintRequestHandler()
method. The OneginiMobileAuthWithPushFingerprintRequestHandler
class is
responsible for handling an incoming mobile authentication request which must be confirmed with fingerprint authentication. The SDK will call the
startAuthentication()
method when a new mobile authentication request has been received. When a user provides a fingerprint to the scanner, the SDK will
call the onFingerprintCaptured()
method. At this point the fingerprint hasn't been validated yet, but you can use this method to inform the user that his
fingerprint was captured from the scanner and is now being processed. If the fingerprint provided by the user is incorrect, but his failed attempts limit
hasn't been reached yet, the SDK will call the onNextAuthenticationAttempt()
method. Whenever the authentication process is finished regardless of the outcome
(success or error), the SDK will call the finishAuthentication()
method.
Authentication request callbacks
In order to provide authentication request results back to the SDK all authentication request handlers receive callback objects when the authentication is started.
Note: please note that the callback is send only in startAuthentication()
method. If the onNextAuthenticationAttempt()
method is called you should reuse
the same handler, so it means that you should keep a reference to it until finishAuthentication()
method is called.
OneginiAcceptDenyCallback
- the
OneginiAcceptDenyCallback
is passed by the SDK when a new mobile authentication process request is received. When a user accepts the request, theacceptAuthenticationRequest()
method has to be called. If the user denies the request, thedenyAuthenticationRequest()
method has to be called.
OneginiPinCallback
The OneginiPinCallback
is passed by the SDK when a new authentication with PIN or mobile authentication with PIN request is made. When the user accepts the
request and provides his PIN, the acceptAuthenticationRequest()
method has to be called. If the user denies the request, the denyAuthenticationRequest()
method has to be called (which will result in the ACTION_CANCELED
error).
OneginiFingerprintCallback
The OneginiFingerprintCallback
is passed by the SDK when a new authentication with fingerprint or mobile authentication with fingerprint request is received.
When the user accepts to provide his fingerprint, the acceptAuthenticationRequest()
method has to be called. If the user denies the request, the
denyAuthenticationRequest()
method has to be called (which will result in the ACTION_CANCELED
error). If the user wants to use his PIN instead, the
fallbackToPin()
method has to be called, which will result in finishing current fingerprint authentication request and starting a new PIN authentication
request.