User authentication

The UserClient exposes the authenticateUser:authenticator:delegate: method for authenticating. This method required three arguments.

• Authenticator (Authenticator): The authenticator you want to use to authentication. If nil is provided, the iOS SDK will pick a preferred authenticator. It must be registered for the given UserProfile.
• userProfile (UserProfile): The user profile for which authentication must be performed. It contains an identifier that tells the iOS SDK for which user profile you want to initiate authentication.
• 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 the AuthenticationDelegate class.

If the user is already logged in, calling authenticateUserWith(profile:authenticator:delegate:) will log out 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 iOS SDK will call the following methods on it:

• userClient(_:didStartAuthenticationForUser:authenticator:) is the method called when authentication is started.
• userClient(_:didReceivePinChallenge:) is the method called when authentication requires a PIN to continue.
• userClient(_:didReceiveBiometricChallenge:) is the method called when authentication requires a biometric prompt to continue.
• userClient(_:didReceiveCustomAuthFinishAuthenticationChallenge:) is the method called when authentication requires custom authenticator data to continue.
• userClient(_:didAuthenticateUser:authenticator:info:) is the method called when authenticator registration is completed with success.
• userClient(_:didFailToAuthenticateUser:authenticator:error:) is the method called when authenticator registration failed with an error.

Provide PIN authentication

When the user needs to be asked to provide their PIN, the iOS 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) is the user client that is performing the authentication.
• challenge (CreatePinChallenge) is the PIN challenge used to complete authentication.

The challenge object represents the authenticate with PIN challenge. It provides all information about the challenge and the sender waiting for the response:

• userProfile (UserProfile) is the user profile for which the authenticate with PIN challenge was sent.
• authenticator (Authenticator) is the authenticator used for user authentication.
• maxFailureCount (UInt) is the maximum allowed PIN attempts for the user.
• previousFailureCount (UInt) is the PIN attempts used by the user on this device.
• remainingFailureCount (UInt) is the available PIN attempts left for the user on this device.
• error (Error) describes the cause of failure of the previous challenge response. Possible error domains are ONGPinAuthenticationErrorDomain, ONGGenericErrorDomain.
• sender (CreatePinChallengeSender) is the sender waiting for a response to the authenticate with PIN challenge.

Response to the authenticate with PIN challenge is sent using the respondWithPin:challenge: method of the challenge sender. In case the provided PIN is invalid, the iOS 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 iOS 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 IDAAS-core to ensure the token is invalidated on both the client and the server side.

The logoutUser: method requires one argument:

• completion ((UserProfile?, Error?) -> Void) the completion block that notifies the caller about the result of the logout action.

Example: Trigger user logout:

    SharedUserClient.instance.logoutUser(logoutCompletiont)

    [[ONGUserClient sharedInstance] logoutUser:logoutCompletiont];

Based on the outcome of the logout, action completion can be handled:

    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 iOS 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 iOS SDK and on the server side. The maximum number of PIN retries must be configured in the application configuration in the IDAAS-core 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. After the refresh token is removed as part of the authentication flow, the user will be asked to choose a new PIN.