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":

sequenceDiagram
    autonumber
    Note over Portal,Token Server: The portal wants to initialise<br/> mobile authentication with OTP
    Portal ->> Token Server: Mobile authentication request.  
    Token Server ->> Portal: ID of the initialized request<br/> and Base64 encoded OTP.
    Portal ->> App: Request ID and OTP code.
    App ->> SDK: Request ID<br/> and OTP code.
    SDK ->> Token Server: Request for encrypted message.
    Token Server ->> SDK: Base64 encoded and PGP encrypted<br/> authentication data.
    SDK ->> SDK: The message is decrypted
    Note over App,SDK: SDK triggers a request handler so the app<br/> can show a custom dialogue to the end-user.
    SDK ->> App: Trigger a request handler.
    App ->> SDK: The authentication result.
    SDK ->> SDK: Encrypt authentication result.
    SDK ->> Token Server: The encrypted authentication result.
    Token Server ->> Portal: The mobile authentication result.

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

Passing the mobile authentication request received from the initiator to the SDK
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
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

1
2
3

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);