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.
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
To read more about retrieving the list of registered
OneginiAuthenticators please see the
Registered/deregistered authenticators section of the
When the user is authenticated, the SDK will call the
onSuccess(UserProfile userProfile, CustomInfo customInfo) method from
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
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
1 2 3 4 5 6 7 8 9 10 11 12
Example code - authentication of already created user profile using a specific authenticator
1 2 3 4 5 6 7 8 9 10 11 12
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14