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 Custom Authenticators. 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. Biometric and Custom Authenticator 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, Biometric or Custom Authenticator.
  • 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:info: - method called when authenticator registration is completed with success.
  • userClient:didFailToRegisterAuthenticator:forUser:error: - method called when authenticator registration failed with an error.
  • userClient:didReceivePinChallenge:forUser: - method called when authenticator registration requires a PIN to continue.
  • userClient:didReceiveCustomAuthenticatorRegistrationFinishChallenge:forUser: - method called during registeration of a custom authenticator.

Registering an authenticator might require the user to authenticate (in case of Biometric). 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 can 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

Authentication is described in the Authenticate User section.

Authenticator deregistration

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

  • authenticator (ONGAuthenticator) - the authenticator to be deregistered
  • delegate (id<ONGAuthenticatorDeregistrationDelegate>) - deregistration delegate

Object passed as the delegate should conform to ONGAuthenticatorDeregistrationDelegate. Following methods are called by the SDK:

  • userClient:didStartDeregisteringAuthenticator:forUser: - method called when deregistration is started
  • userClient:didReceiveCustomAuthenticatorDeregistrationChallenge: - method called only during custom authenticator deregistration
  • userClient:didDeregisterAuthenticator:forUser: - method called when authenticator deregistration succeeded
  • userClient:didFailToDeregisterAuthenticator:forUser:error: - method called when authenticator deregistration failed

Example implementation:

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

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

results matching ""

    No results matching ""