Authenticate user with PIN
Determine if we can login user
The UserClient
contains the getUserProfiles
method which returns set of all registered UserProfile value objects. You can check size of that set to
determine if there is need to register new user or if there is possibility to login.
If the method isRegisteredAtLeastOneUser
from the example below will return false
you can assume that no user is authenticated on the device. In that case
user have to register before logging in.
Example code
You can also use UserClient#isUserRegistered()
method in order to check if specified user is registered on the device.
Login registered user
When at least one user has already registered there is possibility to log in that user using authenticateUser
method from the UserClient
. This method
requires two arguments:
UserProfile
the UserProfile ValueObject that we want to authenticate,OneginiAuthenticationHandler
the authentication handler to return the authentication result to.
The result of authentication is an access token with optionally a refresh token. The authentication handler contains:
- an
onSuccess
method which lets you know that authentication was finished successfully - at this point, you can request data on behalf of the user, - an
onError
method which is called in every other case.
You can find more information about authentication in User authentication section.
PIN request handlers
At this point the app would crash with a NullPointerException
due to the lack of PIN request handlers for creating and verifying a PIN. To prevent that you
need to provide your own authentication request handlers using the OneginiClientBuilder
methods. The OneginiCreatePinRequestHandler
and
OneginiPinAuthenticationRequestHandler
are required in order to perform authentication flows with a PIN.
Example
Create PIN request handler
The OneginiCreatePinRequestHandler
interface is responsible for handling the PIN creation process. Create a class that implements this interface and overrides
the following methods:
startPinCreation(final UserProfile userProfile, final OneginiPinCallback oneginiPinCallback, final int pinLength)
- this 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). You have to callOneginiPinCallback#acceptAuthenticationRequest(pinEnteredByUser)
in order to successfully finish PIN creation process. ThepinLength
parameter determines the required pin length. In order to cancel the PIN creation process you can call theOneginiPinCallback#denyAuthenticationRequest()
method.onNextPinCreationAttempt(final OneginiPinValidationError oneginiPinValidationError)
- this method will be called when the PIN provided by user hasn't met the PIN policy. You can check the exact error by comparing theOneginiPinValidationError#getErrorType()
value with theOneginiPinValidationError
's static fields. Please note that there are also theOneginiPinValidationError#getMessage()
andOneginiPinValidationError#getCause()
methods which can return more information about the error.finishPinCreation()
is called whenever correct PIN was created or the action was canceled by the user. Below is sample code for creating a custom PIN request handler. In this example we created an additionalPinWithConfirmationHandler
to support the PIN verification step. You can feel free to skip this step if it's not relevant for your use-case. You can check the full solution in our Example App which is available on GitHub.
Example code
For more info on error handling see the Error handling topic guide.
PIN authentication request handler
Create a class that implements the OneginiPinAuthenticationRequestHandler
interface, which is responsible for handling PIN authentication requests, and
override the following methods:
startAuthentication(final UserProfile userProfile, final OneginiPinCallback oneginiPinCallback, final AuthenticationAttemptCounter attemptCounter)
- this method will be invoked by the SDK whenever there will be a to need authenticate the user. You have to callOneginiPinCallback#acceptAuthenticationRequest(pinEnteredByUser)
in order to successfully finish the PIN creation process orOneginiPinCallback#denyAuthenticationRequest()
to cancel it.onNextAuthenticationAttempt(final AuthenticationAttemptCounter attemptCounter)
- this method is called when the PIN that is provided by the user is incorrect, but his failed attempts limit hasn't been reached yet. The method's parameter isAuthenticationAttemptCounter
object providing information about number of failed attempts, remaining attempts and maximum attempts counters.finishAuthentication()
- this method is called whenever the authentication process is finished regardless whether it was successful or failed.
Example code
For more info on error handling see the Error handling topic guide.