Authenticators
The 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 authenticator and Custom authenticator availability requirements are defined in their corresponding topic guides.
When all the requirements are met the authenticator can be used. The UserClient
has three types AuthenticatorsType
of returning authenticators:
nonRegistered
- returns a set of authenticators which are supported both, client and server side, and are not yet registered.registered
- returns a set of registered authenticators.all
- returns a set of both registered and not registered authenticators.
The Class representing an authenticator is called Authenticator
. Objects of that class are DTOs, once returned by the SDK their property values
(including registered
and prefered
) will not be changed or updated.
Authenticator
has the following properties:
- identifier (
String
) - unique authenticator identifier defined by its vendor - name (
String
) - human-readable authenticator name defined in the Token Server admin panel. - type (
AuthenticatorType
) - type of the authenticator: PIN authenticator, Biometric authenticator or Custom authenticator. - isRegistered (
Bool
) - indicates if this authenticator is registered for the user for which it was fetched. - isPreferred (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 UserClient
which requires two arguments:
- authenticator (
Authenticator
) - authenticator to be registered. - delegate (
AuthenticatorRegistrationDelegate
) - authentication delegate.
The object passed as the delegate must conform to the AuthenticatorRegistrationDelegate
protocol. The SDK will call the following methods on it:
userClient(_:didStartRegistering:for:)
- method called when authenticator registration is started.userClient(_:didRegister:for:info:)
- method called when authenticator registration is completed with success.userClient(_:didFailToRegister:for:error:)
- method called when authenticator registration failed with an error.userClient(_:didReceivePinChallenge:for:)
- method called when authenticator registration requires a PIN to continue.userClient(_:didReceiveCustomAuthFinishRegistrationChallenge:for:)
- 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:
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 UserClient
. You can do this by following the example below:
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 (
Authenticator
) - the authenticator to be deregistered - delegate (
AuthenticatorDeregistrationDelegate
) - deregistration delegate
Object passed as the delegate should conform to AuthenticatorDeregistrationDelegate
. Following methods are called by the SDK:
userClient(_:didStartDeregistering:for:)
- method called when deregistration is starteduserClient(_:didReceiveCustomAuthDeregistrationChallenge:)
- method called only during custom authenticator deregistrationuserClient(_:didDeregister:for:)
- method called when authenticator deregistration succeededuserClient(_:didFailToDeregister:for:error:)
- method called when authenticator deregistration failed
Example implementation: