OneginiAuthentication

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 authentication (default), fingerprint authentication and FIDO authentication.

OneginiAuthenticator interface

public interface OneginiAuthenticator {

  int PIN = 0;
  int FINGERPRINT = 1;
  int FIDO = 2;

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

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

  /**
   * Returns the authenticator type (PIN, FINGERPRINT)
   * @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();
}

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, FIDO
  • getId() - this method should be used to distinguish different FIDO authenticators. When multiple FIDO authenticators are registered within the device/app, the type is not enough to distinguish between them (since all of them have FIDO 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 FIDO 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.
  • FIDO - authenticators that are compatible with FIDO (Fast Identity Online) specifications. During initialization the Onegini SDK performs a discovery of all FIDO authenticators that are installed in the device or in the application and are also enabled in the client configuration it the Token Server. Please note, that Onegini SDK doesn't provide any FIDO authenticators, but uses FIDO authenticators provided by the app or device developers. For example new Samsung's devices are usually shipped with a FIDO-compliant "Samsung fingerprint" authenticator that can be discovered and used by Onegini SDK.

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 (unles the user itself gets deregistered). Other types of authenticators (FINGERPRINT and FIDO) 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 authenticators 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.