Authenticators

Introduction

OneginiAuthenticator interface allows you to take a control over all authentication possibilities offered by the device. Currently the Onegini SDK supports three different types of user authentication: PIN (default), fingerprint and custom authentication.

OneginiAuthenticator interface

public interface OneginiAuthenticator {

  int PIN = 0;
  int FINGERPRINT = 1;
  @Deprecated int FIDO = 2;
  int CUSTOM = 3;

  @IntDef({
      PIN,
      FINGERPRINT,
      CUSTOM
  })
  @Retention(RetentionPolicy.RUNTIME)
  @interface OneginiAuthenticatorType {}

    /**
     * Returns the ID of the authenticator
     * @return String ID
     */
    String getId();

    /**
     * Returns the authenticator type (PIN, FINGERPRINT, CUSTOM)
     * @return int authenticator type
     */
    @OneginiAuthenticatorType
    int getType();

    /**
     * Returns a name of the authenticator
     * @return String name
     */
    String getName();

    /**
     * Returns if the authenticator is registered for usage
     * @return TRUE if the authenticator is registered
     */
    boolean isRegistered();

    /**
     * Returns if the authenticator was set as preferred one for authentication.
     * @return TRUE if the authenticator is preferred
     */
    boolean isPreferred();

    /**
     * Returns the UserProfile associated with the authenticator
     * @return UserProfile userProfile
     */
    UserProfile getUserProfile();
}

The OneginiAuthenticator interface presents following methods

  • getType() - this method should be used to distinguish all types of authentication. Currently all possible authentication types are: PIN, FINGERPRINT, CUSTOM
  • getId() - this method should be used to distinguish different CUSTOM authenticators. When multiple CUSTOM authenticators are registered within the device/app, the type is not enough to distinguish between them (since all of them have CUSTOM type). In such case the ID should be used. This is the ID that's provided by the authenticator developers. Please note that for PIN and FINGERPRINT authenticators this value (while not empty) doesn't have much value.
  • getName() - returns name of the authenticator. For PIN and FINGERPRINT authenticators names are predefined (PIN and Fingerprint). For CUSTOM authenticators the name is set in the client configuration provided by the Token Server.
  • isRegistered() - indicates if the authenticator was already registered for the user in the app. In particular it will be always TRUE for PIN authenticator for any registered user.
  • isPreferred() - indicates if the authenticator was set as the preferred by the user. Only one (registered) authenticator can be set as preferred.

Authentication types

Currently the Onegini SDK offers three methods for user authentication:

  • PIN - a default type of user authentication where user has to provide set of digits in order to authenticate. This method of authenticator has to be registered during user's registration and can't be deregistered even when other authenticators are registered. When user can't (or he doesn't want to) authenticate with other method (i.e. fingerprint), the SDK allows him to use his PIN instead.
  • FINGERPRINT - a "native" android fingerprint authentication (using Android API). In order to use it on a device, all requirements have to be met.
  • CUSTOM - all 3rd party custom authenticators that are added to the app by the app developer. In order to use such authenticators, app developer needs to enable the custom authenticator functionality in the Token Server, provide proper scripts in the Extension Engine and interface implementations in the Onegini SDK. Please check this topic for more information.

Registered/deregistered authenticators

In order to enable/disable each authenticator, the user has to register/deregister authenticator. In case when multiple user profiles are registered in the app, each user profile has it's own set of registered authenticators, which means that if first user profile (Alice) registers fingerprint authenticator, the other registered user profile (Bob) doesn't have it registered (unless he does the same). The PIN authenticator is registered (created) during user's registration. This type of authenticator can't be deregistered (unless the user itself gets deregistered). Other types of authenticators (FINGERPRINT and CUSTOM) can be registered and deregistred only by currently authenticated user.

In order to fetch a Set containing all possible authenticators for the user on current device, you can use UserClient#getAllAuthenticators(final UserProfile userProfile) method. The set will contain all registered and deregistered authenticators, that are supported by the device and are enabled in the Token Server configuration. You can also use UserClientc#getRegisteredAuthenticators(final UserProfile userProfile) and UserClient#getNotRegisteredAuthenticators(final UserProfile userProfile) methods in order to fetch only registered or not registered authenticators.

When user is authenticated you can use one of those authenticators in UserClient#registerAuthenticator(final OneginiAuthenticator authenticator, final OneginiAuthenticatorRegistrationHandler handler) or UserClient#deregisterAuthenticator(final OneginiAuthenticator authenticator, final OneginiAuthenticatorDeregistrationHandler handler) methods in order to register or deregister the authenticator.

Preferred authenticator

When user has registered multiple authenticators, he can choose the preferred one. The preferred authenticator is used by Onegini SDK during regular authentication. For example, when user sets the FINGERPRINT authenticator as preferred, the SDK will ask for his fingerprint during authentication. User can then use the fingerprint, or choose to use PIN authentication instead. If user won't set preferred authenticator or when preferred authenticator gets deregistered, the PIN authenticator is set as preferred. In order to set the preferred authenticator for currently authenticated user, please use UserClient#setPreferredAuthenticator(final OneginiAuthenticator authenticator) method.

You should also remember that:

  • Only registered authenticator should be set as preferred (when not-registered authenticator is set as preferred, the SDK will use PIN instead)
  • Only one authenticator can be set as preferred, multiple calls to setPreferredAuthenticator() method will override the preferred authenticator
  • Mobile authentication request specifies the authenticator that has to be used. In such case the preferred authenticator setting is not used.