Authenticators

The Onegini SDK offers multiple ways of authentication. Except for the default PIN authenticator you can also register and use a fingerprint authenticator and any of the FIDO authenticators included in your application. It's up to you if you want to enable them for users.

Authenticator availability

In order for an authenticator to be available it needs to meet a few requirements that are specific to the authenticator type. PIN is always available for a registered user. Fingerprint and FIDO availability requirements are defined in their corresponding topic guides.

When all the requirements are met the authenticator can be used. The ONGUserClient has three methods of returning authenticators:

  • nonRegisteredAuthenticatorsForUser: - returns a set of authenticators which are supported both, client and server side, and are not yet registered.
  • registeredAuthenticatorsForUser: - returns a set of registered authenticators.
  • allAuthenticatorsForUser:- returns a set of both registered and not registered authenticators.
ONGUserProfile *userProfile = [[ONGUserClient sharedInstance] authenticatedUserProfile];
NSSet<ONGAuthenticator *> *authenticators = [ONGUserClient shadedInstance] nonRegisteredAuthenticatorsForUser: userProfile];

ONGUserProfile *userProfile = [[ONGUserClient sharedInstance] authenticatedUserProfile];
NSSet<ONGAuthenticator *> *authenticators = [ONGUserClient shadedInstance] registeredAuthenticatorsForUser: userProfile];

ONGUserProfile *userProfile = [[ONGUserClient sharedInstance] authenticatedUserProfile];
NSSet<ONGAuthenticator *> *authenticators = [ONGUserClient shadedInstance] allAuthenticatorsForUser: userProfile];

The Class representing an authenticator is called ONGAuthenticator. Objects of that class are DTOs, once returned by the SDK their property values (including registered and prefered) will not be changed or updated. ONGAuthenticator has the following properties:

  • identifier (NSString) - unique authenticator identifier defined by its vendor
  • name (NSString) - human-readable authenticator name defined in the Token Server admin panel.
  • type (ONGAuthenticatorType) - type of the authenticator: PIN, Fingerprint or FIDO.
  • registered (BOOL) - indicates if this authenticator is registered for the user for which it was fetched.
  • preferred (BOOL) - indicates if this authenticator is set as preferred for the user for which it was fetched.

Authenticator registration

Registration is done by calling the registerAuthenticator:delegate: method of the ONGUserClient which requires two arguments:

  • authenticator (ONGAuthenticator) - authenticator to be registered.
  • delegate (id<ONGAuthenticatorRegistrationDelegate>) - authentication delegate.

The object passed as the delegate must conform to the ONGAuthenticatorRegistrationDelegate protocol. The Onegini SDK will call the following methods on it:

  • userClient:didStartRegisteringAuthenticator:forUser: - method called when authenticator registration is started.
  • userClient:didRegisterAuthenticator:forUser: - method called when authenticator registration is completed with success.
  • userClient:didFailToRegisterAuthenticator:forUser: - method called when authenticator registration failed with an error.
  • userClient:didReceivePinChallenge:forUser: - method called when authenticator registration requires a PIN to continue.

Registering an authenticator might require the user to authenticate (in case of Fingerprint). After successful authenticator registration you can set an authenticator as preferred, which means it will by used for authentication by default. The User will also be able to receive push notifications which can be confirmed using that authenticator.

The example below shows you how to register a fingerprint authenticator. Let the calling class also implement the required delegate:

ONGUserProfile *userProfile = [[ONGUserClient sharedInstance] authenticatedUserProfile];
NSSet<ONGAuthenticator *> *authenticators = [ONGUserClient shadedInstance] nonRegisteredAuthenticatorsForUser:userProfile];
ONGAuthenticator *yourAuthenticator = [authenticators filteredSetUsingPredicate:yourPredicate].anyObject;

[[ONGUserClient sharedInstance] registerAuthenticator:yourAuthenticator delegate:self];

After the authenticator is registered it still needs to be set as preferred. Without doing so the SDK will still use PIN authentication by default. To set an authenticator as preferred use the setPreferredAuthenticator method of the ONGUserClient. You can do this by following the example below:

ONGUserProfile *userProfile = [[ONGUserClient sharedInstance] authenticatedUserProfile];
NSSet<ONGAuthenticator *> *authenticators = [ONGUserClient shadedInstance] registeredAuthenticatorsForUser:userProfile];
ONGAuthenticator *yourAuthenticator = [authenticators filteredSetUsingPredicate:yourPredicate].anyObject;

[ONGUserClient sharedInstance].preferredAuthenticator = yourAuthenticator;

Authentication

Whenever a user is authenticated, the preferred authenticator is used. Every authenticator has an option to fallback to PIN in case of issues. Also, after failing to authenticate for the allowed number of times, the SDK will automatically fallback to the PIN authentication method. If the user will not be able to provide a valid PIN within the allowed number of times, he will be deregistered.

Authenticator deregistration

Authenticators can be deregistered for the currently authenticated user by using deregisterAuthenticator:completion: which takes two parameters:

  • authenticator (ONGAuthenticator) - the authenticator to be deregistered
  • completion (void (^)(BOOL deregistered, NSError * _Nullable error)) - block returning the result of the deregistration action and any encountered error

Example implementation:

ONGUserProfile *userProfile = [[ONGUserClient sharedInstance] authenticatedUserProfile];
NSSet<ONGAuthenticator *> *authenticators = [[ONGUserClient sharedInstance] registeredAuthenticatorsForUser:userProfile];
ONGAuthenticator *yourAuthenticator = [authenticators filteredSetUsingPredicate:yourPredicate].anyObject;

[[ONGUserClient sharedInstance] deregisterAuthenticator:yourAuthenticator completion:^(BOOL deregistered, NSError *error) {
    if (error != nil) {
    // Display an error to the user.
    }
}];