User authentication
Authenticate user
The UserClient offers two methods to initialize user authentication for a specific profile. The result of successful invocation of the authentication
process is an access token. With this token the device can communicate with a back-end. In case the user fails to authenticate due to surpassing the maximum
number of allowed PIN attempts the user will be deregistered due to security reasons. The maximum number of failed PIN attempts can be configured in the
application configuration section of the Token Server admin console.
If the authenticateUser:authenticator:delegate: method is used, authentication will be performed using the authenticator specified in
as parameter. This method requires three arguments:
- authenticator (
Authenticator) The authenticator you want to use to authentication, if nil is provided the SDK will pick a preferred authenticator. It must be registered for the givenUserProfile. - userProfile (
UserProfile) The user profile for which authentication must be performed. It contains an identifier that tells the SDK for which user profile you want to initiate authentication. Please read the documentation regarding user registration more carefully to find out what the user profile is for and how to use it. - delegate (
AuthenticationDelegate) The delegate delegates control back to the app in case it needs to do something or in case of a successful or failed authentication attempt. The delegate must implement the methods specified in theAuthenticationDelegateclass.
If the user is already logged in, calling authenticateUserWith(profile:authenticator:delegate:) will logout the currently logged in user and initiate authentication for
the provided user profile.
The example below shows you how to call the authenticateUserWith(profile:authenticator:delegate:) method and let the calling class also implement the required delegate:
SharedUserClient.instance.authenticateUserWith(profile:user,
authenticator: authenticator,
delegate: self)
[[ONGUserClient sharedInstance] authenticateUser:user authenticator:authenticator delegate:self];
The object passed as the delegate must conform to the AuthenticationDelegate protocol. The Onegini SDK will call the following methods on it:
userClient(_:didStartAuthenticationForUser:authenticator:)- method called when authentication is started.userClient(_:didReceivePinChallenge:)- method called when authentication requires a PIN to continue.userClient(_:didReceiveBiometricChallenge:)- method called when authentication requires biometric prompt to continue.userClient(_:didReceiveCustomAuthFinishAuthenticationChallenge:)- method called when authentication requires custom authenticator data to continue.userClient(_:didAuthenticateUser:authenticator:info:)- method called when authenticator registration is completed with success.userClient(_:didFailToAuthenticateUser:authenticator:error:)- method called when authenticator registration failed with an error.
After initializing authentication the user needs to be asked to authenticate. It depends on the preferred or chosen authentication method which one will be initiated. In the example below we consider the default method: PIN. PIN authentication can always be used as the fallback authentication method. This is also the reason why the user must choose a PIN during the registration process.
Provide PIN authentication
When the user needs to be asked to provide his/her PIN the SDK will delegate control back to the application by calling the userClient(_:didReceivePinChallenge:)
method of the class that implements the methods specified in the AuthenticationDelegate.
The userClient(_:didReceivePinChallenge:) method has two parameters:
- userClient (
UserClient) user client performing authentication. - challenge (
CreatePinChallenge) pin challenge used to complete authentication.
Challenge object represents authenticate with PIN challenge. It provides all information about the challenge and the sender awaiting for the response:
- userProfile (
UserProfile) user profile for which authenticate with PIN challenge was sent. - authenticator (
Authenticator) authenticator used for user authentication. - maxFailureCount (
UInt) maximum allowed pin attempts for the user. - previousFailureCount (
UInt) pin attempts used by the user on this device. - remainingFailureCount (
UInt) available pin attempts left for the user on this device. - error (
Error) describing cause of failure of previous challenge response. Possible error domains: ONGPinAuthenticationErrorDomain, ONGGenericErrorDomain. - sender (
CreatePinChallengeSender) sender awaiting for response to the authenticate with PIN challenge.
Response to the authenticate with PIN challenge is sent using respondWithPin:challenge: method of the challenge sender. In case the provided PIN is invalid
SDK will resend the challenge with an error.
Below you can see an example implementation of this method:
func userClient(_ userClient: UserClient, didReceiveCreatePinChallenge challenge: CreatePinChallenge) {
__ Code to display your PIN view here..
if createPinChallenge.error {
__show remaining pin attempts
}
askUserForPin { createdPin in
__ Once the user has entered the PIN call the delegate
createPinChallenge.sender.respond(with: createdPin, to: challenge);
__ Or cancel challenge
createPinChallenge.sender.cancel(challenge)
}
}
- (void)userClient:(ONGUserClient *)userClient didReceivePinChallenge:(ONGPinChallenge *)challenge
{
__ Code to display your PIN view here..
if (challenge.error) {
__show remaining pin attempts
}
[self askUserForPin:^(NSString *pin) {
__ Once the user has entered the PIN call the delegate
[challenge.sender respondWithPin:pin challenge:challenge];
__ Or cancel challenge
[challenge.sender cancelChallenge:challenge];
}];
}
Logout user
In the SDK a user is marked as logged in as long as a valid access token is available within the device memory. To logout, the app calls the
SharedUserClient.instance.logoutUser method. This will clear the access token from the current session and informs the Token Server to ensure the token is invalided
on both client and server side.
The logoutUser: method requires one argument:
- completion (
(UserProfile?, Error?) -> Void) the completion block that notifies caller about result of the logout action.
Example code to trigger user logout:
SharedUserClient.instance.logoutUser(logoutCompletiont)
[[ONGUserClient sharedInstance] logoutUser:logoutCompletiont];
Based on the outcome of the logout action completion can be handled in next way.
SharedUserClient.instance.logoutUser { _, error in
if let error = error {
let mappedError = ErrorMapper().mapError(error)
self.dashboardPresenter?.logoutUserActionFailed(mappedError)
} else {
self.dashboardPresenter?.presentWelcomeView()
}
}
[[ONGUserClient sharedInstance] logoutUser:^(ONGUserProfile *userProfile, NSError *_Nullable error) {
if (error == nil) {
__ Code invoked after the user is logged out..
} else {
__ The access token is not revoked on the server side but the user is logged out locally (on the device) only..
}
}];
Forgot PIN
The SDK does not support a method to recover a PIN for a user account simply because it cannot do so. The refresh token is stored encrypted on the device. For encryption of the refresh token the PIN is used as part of the encryption key. When a user forgets the PIN the existing refresh token used to log in cannot be decrypted and is useless in that sense. After a number of wrong PIN attempts the refresh token is removed automatically on both the SDK and on the server side. The max number of PIN retries must be configured in the application configuration in the Token Server admin console. To provide the user with an option to skip the max number of failed attempts before the refresh token is deleted, the disconnect functionality can be used. Once the refresh token is removed as part of the authentication flow the user will be asked to choose a new PIN.
