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 FCM. 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

In order to use mobile authentication with OTP, you have to set it up in the Token Server. Each user of the app has to perform the mobile authentication enrollment in order to enable the functionality for himself. To learn how to do it please review mobile authentication enrollment section of other topic guide.

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 UserClient#isUserEnrolledForMobileAuth(UserProfile userProfile) method. If the user was not enrolled, you can perform enrollment by following the Mobile Authentication Enrollment guide.

Request handling

The entire OTP 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 startAuthentication in the 
        OneginiMobileAuthOtpRequestHandler 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 the mobile authentication request received from the initiator to the SDK
  2. Responding to the confirmation request
    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 of the mobile authentication request

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

Setting up the OTP request handler

To support mobile authentication with OTP in your app you need to implement the OneginiMobileAuthOtpRequestHandler interface and set its instance during the SDK initialization step by calling setMobileAuthenticationOtpRequestHandler(OneginiMobileAuthOtpRequestHandler handler) method on OneginiClientBuilder. Then you need to handle all interface methods in order to show/hide user interface with (for example) buttons allowing to accept or deny request.

Example how to set the OneginiMobileAuthOtpRequestHandler

new OneginiClientBuilder(applicationContext, createPinRequestHandler, pinAuthenticationRequestHandler)
  .setMobileAuthenticationOtpRequestHandler(new MobileAuthOtpRequestHandler())
  .build();

Example how to implement the OneginiMobileAuthOtpRequestHandler

public class MobileAuthOtpRequestHandler implements OneginiMobileAuthOtpRequestHandler {

  @Override
  public void startAuthentication(final OneginiMobileAuthenticationRequest oneginiMobileAuthenticationRequest,
                                  final OneginiAcceptDenyCallback oneginiAcceptDenyCallback) {
    // You can simply accept the request like we do or use the OneginiMobileAuthenticationRequest object to display some info to the end-user and ask for his permission.
    oneginiAcceptDenyCallback.acceptAuthenticationRequest();
  }

  @Override
  public void finishAuthentication() {
    // In case you displayed a dialog you can close the dialog here.
  }
}

You need to implement both the startAuthentication and finishAuthentication methods:

  • startAuthentication(final OneginiMobileAuthenticationRequest oneginiMobileAuthenticationRequest, final OneginiAcceptDenyCallback oneginiAcceptDenyCallback) is called when a new mobile authentication request is received. The First parameter is the OneginiMobileAuthenticationRequest object which contains the message you can optionally present to the user and the UserProfile object that specifies the profile for which this request is received. The Second parameter is a callback object that you must use when the end-user accepts or denies the request, by calling acceptAuthenticationRequest or denyAuthenticationRequest respectively.
  • finishAuthentication is called when the required interaction with the request delegate is finished. If you use a dialog or activity to interact with the end-user you can use this method to close the dialog or finish the activity.

Passing the OTP request to the SDK

Please keep in mind that to trigger mobile authentication with OTP a user has to be authenticated (logged in to your app). Once that condition is satisfied and the user is enrolled for mobile authentication you can call the OneginiClient#UserClient#handleMobileAuthWithOtp(String otpCode, OneginiMobileAuthWithOtpHandler mobileAuthWithOtpHandler) method. The first argument is the OTP received from your web application (eg. the user scanned a QR code that encodes the OTP). The second argument is the OneginiMobileAuthWithOtpHandler interface which contains two methods you should react to:

  • onSuccess() - called when mobile authentication with OTP succeeded,
  • onError(OneginiMobileAuthWithOtpError error) - called when an error occurred during mobile authentication with OTP. Please check the OneginiMobileAuthWithOtpError error object to learn about the reason of failure. You can check an error type and message by calling respectively the getErrorType() and getMessage() methods on the error object.

Example how to trigger authentication with OTP

final OneginiMobileAuthWithOtpHandler oneginiMobileAuthWithOtpHandler = new OneginiMobileAuthWithOtpHandler() {
  @Override
  public void onSuccess() {
    showToast("Mobile auth with OTP succeeded");
  }

  @Override
  public void onError(final OneginiMobileAuthWithOtpError oneginiMobileAuthWithOtpError) {
    showToast("Mobile auth with OTP error:" + oneginiMobileAuthWithOtpError.getMessage());
  }
};

final UserClient userClient = OneginiSDK.getOneginiClient(activity.getApplicationContext()).getUserClient();
userClient.handleMobileAuthWithOtp(otpCode, oneginiMobileAuthWithOtpHandler);