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
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
andFingerprint
). 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 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 SDK. Please check Authenticate user with custom authenticator 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 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.