Mobile authentication with OTP

Introduction

The Onegini Mobile Security Platform offers an ability of mobile authentication with a One Time Password (OTP). Mobile authentication with OTP provides users an easy and secure way for two factor authentication or single factor authentication where no passwords are required. A good use case is for example letting a user login to your web application using his/her mobile device by scanning a QR code displayed within a browser. This essentially allows the user to authenticate using his/her mobile device. It is also not relying on third party services like APNs. All of the communication stays between App, web application and Mobile Security Platform.

An Example implementation could work like this: A web application fetches the OTP from the Token Server and displays it on the login page in the form of a QR code. Then user opens your mobile application and scans the QR code with his camera and is automatically logged in into your website. Of course it's up to you to choose how to implement it, the above scenario is just an example.

Configuration

OTP mobile authentication requires configuration on the Token Server side. Please follow the Mobile authentication configuration guide in order to setup the OTP mobile authentication type.

Enrollment

It's only required to enroll for mobile authentication to use OTP. To verify if the user was already enrolled, you should use the isUserEnrolledForMobileAuth: method on the ONGUserClient. If the user was not enrolled, you can perform enrollment by following the Mobile Authentication Enrollment guide.

Request handling

The entire push mobile authentication process from can be described as follows. In this flow we call the initiator of the mobile authentication request 'portal':

1.  Portal -> Token Server: Initialize a mobile authentication.  
2.  Token Server -> Portal: Identifier of the initialized mobile authentication transaction and 
    base64 encoded OTP (which includes the transaction is and OTPcode).
3.  Portal -> APP: Request containing transactionId and OTP code.
4.  APP -> SDK: Delegate handling of the request to the SDK.
5.  SDK -> Token Server: Fetch PGP encrypted message from the server.
6.  Token Server -> SDK: Base64 encoded PGP encrypted authentication data.
7.  SDK -> APP: The mobile auth message is decrypted and the SDK triggers a delegate so the app 
        can show a dialogue to the end-user.
8.  APP -> SDK: The application responds with the authentication result.
9.  SDK -> Token Server: The authentication result is sent encrypted to the Token Server.
10. Token Server -> Portal: A callback is sent to inform the portal about the mobile 
        authentication result.

As you can see from the diagram above, the application has the following responsibilities:

  1. Passing mobile authentication request received from initiator to Onegini SDK
  2. Responding to the confirmation challenge
    1. (optionally) Displaying a dialog to the end-user when his confirmation is required
    2. Sending the end-user response back to the SDK
  3. Handling completion

The Following paragraphs explain those steps and shows how these can be implemented.

Passing the OTP request to the SDK

Before handling the request its recommended to verify if the request can be handled by Onegini SDK. It can be done by calling the canHandleOTPMobileAuthRequest: method. In case the request can be handled this method returns YES.

Once you verified the mobile authentication request you can handle it by calling the handleOTPMobileAuthRequest:delegate: method on the ONGUserClient instance. The request must be the OTP string(encoded in base64) retrieved from the Token Server. This string contains an otp code and the transaction_id in JSON format encoded with UTF8. 

if ([[ONGUserClient sharedInstance] canHandleOTPMobileAuthRequest:otpRequest]) {
    [[ONGUserClient sharedInstance] handleOTPMobileAuthRequest:otpRequest delegate:delegate];
}

Please keep in mind that the a user must be authenticated (logged in into your app) before you can trigger handling an OTP mobile authentication request. If no user is authenticated the SDK will trigger the didFailToHandleMobileAuthRequest selector on the delegate containing a user not authenticated error.

If all of the requirements are met the SDK will start the mobile authentication request processing and will inform your ONGMobileAuthRequestDelegate about the received confirmation challenge.

Responding to a challenge

After you have passed the mobile authentication request to the SDK, the SDK will request the app to let the user either confirm or deny the request.

The SDK will delegate control back to the provided ONGMobileAuthRequestDelegate implementation. Hence, the application must contain a class that implements the methods specified below.

Mobile authentication requests are represented by the ONGMobileAuthRequest class. Objects of this class are passed to every ONGMobileAuthRequestDelegate method. From those objects you can get the following information about the current mobile authentication request:

  • userProfile - instance of ONGUserProfile for which the request has been received.
  • type - string representing the type of notification which is configured in the Token Server admin panel. The type can be used to distinguish between different business functionality. For example, mobile authentication can be used for logging in or transaction approval.
  • message - message specified by the initiator when initiating the mobile authentication request. This field represents the secure_message parameter sent while initiating the mobile authentication request. The message length is not limited.
  • transactionId - A unique identifier for each Mobile Authentication request.

When a confirmation challenge is received you can display UI containing information from the ONGMobileAuthRequest and options to confirm or deny the request. After a response from the user is received you should send it back to the SDK by calling the confirmation block.

- (void)userClient:(ONGUserClient *)userClient 
        didReceiveConfirmationChallenge:(void (^)(BOOL confirmRequest))confirmation 
                             forRequest:(ONGMobileAuthRequest *)request 
{
    // Code to display your mobile authentication confirmation view here..

    // Once the user has answered the confirmation, call the confirm method specifying whether 
    // the user confirms or denies the request
    confirmation(YES);
}

Completion

Once the mobile authentication request has been handled there are two callbacks on the ONGMobileAuthRequestDelegate that might be called: userClient:didHandleMobileAuthenticationRequest:authenticator:info: and userClient:didFailToHandleMobileAuthenticationRequest:authenticator:error: for success and failure correspondingly. Both methods are optional.

For the success callback you may want to refresh your App's data or hide the view that was used to display the mobile authentication request confirmation screen:

- (void)userClient:(ONGUserClient *)userClient 
        didHandleMobileAuthenticationRequest:(ONGMobileAuthRequest *)request
                               authenticator:(ONGAuthenticator *_Nullable)authenticator
                                        info:(ONGCustomInfo *_Nullable)customAuthenticatorInfo
{
    // Hide the view, update application data, etc
}

For the failure callback, the situation is a bit more complex. It is strongly recommended to implement error handling. The SDK may deliver important errors such as user (server-side) deregistration which requires special handling such as user logout, unwinding the UI to the login page, etc.

- (void)userClient:(ONGUserClient *)userClient 
        didFailToHandleMobileAuthenticationRequest:(ONGMobileAuthRequest *)request 
                                     authenticator:(ONGAuthenticator *_Nullable)authenticator
                                             error:(NSError *)error
{
    switch (error.code) {
        case ONGGenericErrorDeviceDeregistered:
            // The device registration was removed from the Token Server. All locally stored data 
            // is removed from the device and the user needs to register again.
            break;
        case ONGGenericErrorUserDeregistered:
            // The user account is deregistered from the device. The user supplied the wrong PIN 
            // for too many times. All local data associated with the user profile has been removed.
            break;
        case ONGGenericErrorNetworkConnectivityFailure:
        case ONGGenericErrorServerNotReachable:
            // Networking issues.
            break;
        case ONGMobileAuthRequestErrorNotFound:
            // Mobile request was not found on the TS. We can either notify user or ignore it.
            break;
        case ONGMobileAuthRequestErrorNotHandleable:
            // Mobile request cannot be handled by the Onegini SDK.
            break;
        case ONGMobileAuthRequestErrorUserDisenrolled:
            // User is disenrolled for mobile authentication for security reasons. You have to enroll the user again before he can perform mobile 
            // authentication again
            break;
        case ONGMobileAuthRequestErrorNotEnrolled:
            // The user is not enrolled for mobile authentication.
            break;
        case ONGMobileAuthRequestErrorUserNotAuthenticated:
            // No user is currently authenticated, possibly due to the fact that the access token 
            // has expired. A user must be authenticated in order to enroll for mobile 
            // authentication.
            break;
        default:
            // Other errors
            break;
    }
}

results matching ""

    No results matching ""