User authentication

• Introduction
• Initializing authentication
• Logout a user

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

OneginiSDK.getOneginiClient(this).getUserClient().authenticateUser(userProfile, new OneginiAuthenticationHandler() {
    @Override
    public void onSuccess(final UserProfile userProfile, final CustomInfo customInfo) {
      // show user is authenticated
    }

    @Override
    public void onError(final OneginiAuthenticationError error) {
      // check error reason and handle it or explain it to the user
    }
  }
}

Example code - authentication of already created user profile using a specific authenticator

OneginiSDK.getOneginiClient(this).getUserClient().authenticateUser(userProfile, oneginiAuthenticator, new OneginiAuthenticationHandler() {
    @Override
    public void onSuccess(final UserProfile userProfile, final CustomInfo customInfo) {
      // show user is authenticated
    }

    @Override
    public void onError(final OneginiAuthenticationError error) {
      // check error reason and handle it or explain it to the user
    }
  }
}

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

OneginiClient.getInstance().getUserClient().logout(

  new OneginiLogoutHandler() {
   @Override
   public void onSuccess() {
     // Go to home screen
   }

   @Override
   public void onError(final LogoutError error) {
     // Handle the error or simply ignore and return to home screen
   }
 }
);