Mobile authentication

Introduction

With mobile authentication the Onegini mobile platform offers a two factor authentication mechanism in a user friendly and secure way. You can take advantage of the mobile authentication to add a second factor authentication for your product, that can be used to improve security of selected actions like logging into your website or accepting a payment transaction.

The mobile authentication feature is an extensive feature that has a number of different possibilities. E.g. there are different ways that mobile authentication is triggered / received on a mobile device:

  • With push notifications; The user gets a push notification on his phone to alert him that a mobile authentication transaction is pending.
  • With an One-Time-Password (OTP); The user provides an OTP in order to confirm a mobile authentication transaction. Since the OTP is long it is likely that the OTP is transformed into a QR code and the user scans this code with his mobile device.

The mobile authentication with Push mechanism offers different ways of user authentication so you can ask your users for additional verification when accepting a mobile authentication request.

Configuration

Before mobile authentication can be used, you should configure the Token Server to support this functionality. Please follow Mobile authentication configuration guide to set it up.

When the Token Server is configured, you can enroll and handle mobile authentication requests using the Onegini SDK.

Each user of the app has to perform the enrollment in order to enable the functionality for him/herself. This functionality is not strictly related with push notifications and can be used without Google Play Services.

Enrollment

During the mobile authentication enrollment step the user is registered for mobile authentication. The enrollment is split up into two different steps:

  • Mobile authentication enrollment; enables the basic mobile authentication feature that allows handling OTP requests.
  • Push mobile authentication enrollment; enables mobile authentication using push messages.

The first enrollment step, general mobile authentication enrollment is explained below for mobile authentication with push enrollment please refer to the mobile authentication with push topic guide.

During the enrollment process the SDK generates and exchanges PGP keys with the Token Server. This allows to secure and authenticate all mobile authentication related communication. This step is required upfront whenever the users would like to use mobile authentication using OTP or push.

To check if a particular user profile has already enrolled for the mobile authentication (and his PGP keys are stored on the device) the SDK exposes the method: UserClient#isUserEnrolledForMobileAuth(UserProfile userProfile). Please note, that at some point after the successful enrollment the PGP keys can be revoked by the SDK if they are malformed or any kind of security issue is discovered. Because of that, it's a safe approach to check if the user is still enrolled for mobile authentication using the provided method, rather than storing information on the app side that enrollment was done in the past.

Example code to initialize mobile authentication enrollment for the currently authenticated user

  public void enrollMobileAuthentication() {
    final OneginiMobileAuthEnrollmentHandler mobileAuthEnrollmentHandler = new OneginiMobileAuthEnrollmentHandler() {
      @Override
      public void onSuccess() {
        showToast("Mobile authentication enabled");
      }

      @Override
      public void onError(final OneginiMobileAuthEnrollmentError error) {
        @OneginiMobileAuthEnrollmentError.MobileAuthEnrollmentErrorType final int errorType = error.getErrorType();
        if (errorType == OneginiMobileAuthEnrollmentError.DEVICE_DEREGISTERED) {
          new DeregistrationUtil(SettingsActivity.this).onDeviceDeregistered();
        }

        showToast("Mobile authentication error - " + error.getMessage());
      }
    };
    OneginiSDK.getOneginiClient(this).getUserClient().enrollUserForMobileAuth(mobileAuthEnrollmentHandler);
  }

Request handling

In order to handle mobile authentication request the user needs to be enrolled for mobile authentication. To verify if the user is already enrolled, you should use the UserClient#isUserEnrolledForMobileAuth(UserProfile userProfile) method.

The SDK is capable of handling two types of mobile authentication requests. For more information on handling each mobile authentication type, please refer to the corresponding request handling guides.