User authentication
Introduction
This topic guide explains all the steps required to add user authentication to your app. In case you didn't add user registration functionality to your application project yet, please follow the steps in the User registration topic guide.
Initializing authentication
The UserClient exposes the authenticateUser method UserClient#authenticateUser()
that takes a specific UserProfile
object as a parameter to support
multiple user profiles for the same mobile client and uses a preferred authenticator to log the user in. A list (Set<UserProfile>
) of registered user
profiles can be checked by calling UserClient#getUserProfiles()
. Optionally, to log in with a different authenticator you can use an overload of the
UserClient#authenticateUser()
method, that takes the UserProfile
object and the OneginiAuthenticator
as parameters. The OneginiAuthenticator
you want
to use must be registered for the given UserProfile
.
To read more about retrieving the list of registered OneginiAuthenticators
please see the Registered/deregistered authenticators
section of the Authenticators chapter.
When the user is authenticated, the SDK will call the onSuccess(UserProfile userProfile, CustomInfo customInfo)
method from
the OneginiAuthenticationHandler
to return the authenticated UserProfile
value object and CustomInfo
object, which isn't null only is case
of authenticating user with custom authenticator. The same value object of the currently authenticated user can be accessed via
the UserClient#getAuthenticatedUserProfile()
method. Calling UserClient#authenticateUser()
for an already authenticated user will result in logging the user
out and re-authentication.
In case of a user authentication failure, the SDK will call the onError(OneginiAuthenticationError error)
method with the specific error. This method will
also be called when the user denies an authentication request.
The result of authentication is an access token with optionally a refresh token. When a refresh token is available in the authentication flow the SDK will use the refresh token to authenticate. As the refresh token is stored encrypted on the device, the user has to provide his PIN (or a fingerprint) via the specified authentication request handler to decrypt it. In case of the fingerprint authentication, the android system is responsible for recognizing the correct fingerprint - the refresh token will not be accessible when the wrong fingerprint will be provided. In case of the PIN authentication, the decrypted refresh token will be sent to the Token Server to validate the user's pin. When the wrong pin was entered for too many times the SDK will remove the stored refresh token. If the device was used for mobile authentication this won't be possible anymore from this point.
Example code - authentication of already created user profile with preferred authenticator
Example code - authentication of already created user profile using a specific authenticator
Logout a user
In the SDK a user is treated as logged in as long as the user has an access token for the operation to be executed. To log the user out the access token
should be removed. This can be done by calling the logout function on the UserClient
. The SDK will also send a request to the Token Server to remove the
access token to ensure the token is invalidated both on the client as server side. If a refresh token is available it will still be available after
the logout action. To find out more about the logout action please read the Logging out chapter.
Example code to log out a user