Implementing registration/authentication request handlers

When you call the registerUser or the authenticateUser method on the UserClient, the SDK needs some user input in order to finish the process (i.e. PIN or fingerprint). For this you need to provide your own implementation of interfaces called "request handlers" using the OneginiClientBuilder methods.

The OneginiRegistrationRequestHandler is used by the SDK to proceed user's registration in external web browser. Please have in mind that registration in external browser might be either authentication or registration. The OneginiCreatePinRequestHandler and OneginiPinAuthenticationRequestHandler interfaces are required in order to perform basic authentication using a PIN. All other handlers are optional and should be provided only when the app actually uses functionalities like fingerprint or mobile authentication.

Registration request handler

OneginiRegistrationRequestHandler

/**
 * Interface to handle user's registration action.
 */
public interface OneginiRegistrationRequestHandler {

  /**
   * Method called when user has to authenticate in a web browser.
   *
   * @param URL {@link Uri} url that was opened
   */
  void startRegistration(Uri URL, OneginiRegistrationCallback registrationCallback);
}

The OneginiRegistrationRequestHandler interface should be implemented by the application developer and provided to the OneginiClientBuilder's constructor. The OneginiRegistrationRequestHandler class is responsible for handling the registration process using an external web browser. It's startRegistration() method will be invoked by the SDK whenever there will be a need to ask for an access grant using web browser. In such case you should open provided Url in a separate web browser app and return the result via OneginiRegistrationCallback.

OneginiRegistrationCallback

/**
 * Interface to handle user registration request.
 */
public interface OneginiRegistrationCallback {

  /**
   * Method used to pass the registration callback returned by the web browser
   * @param uri the uri that was returned by the Token Server after successful authentication from web browser
   */
  void handleRegistrationCallback(final Uri uri);

  /**
   * Method used to deny the registration action.
   */
  void denyRegistration();
}

The OneginiRegistrationCallback is passed by the SDK when a registration in web browser is requested. When the authentication in web browser is completed, the Token Server will return a URI that has to be passed in handleRegistrationCallback method. When the authentication has failed or was aborted, the denyRegistration can be called in order to cancel the registration (which will result in the ACTION_CANCELED error).

Authentication request handlers

Request handlers used by the SDK when a user has to authenticate himself (log in).

OneginiCreatePinRequestHandler

/**
 * Interface to handle PIN creation requests.
 */
public interface OneginiCreatePinRequestHandler {

  /**
   * Method called when new PIN creation request is made.
   *
   * The method will be called only once per PIN creation process.
   *
   * @param userProfile instance of {@link UserProfile} that describes which user creates the PIN
   * @param callback    instance of {@link OneginiPinCallback} to send request's response back to the SDK
   * @param pinLength   instance of {@link int} determine required pin length
   *
   */
  void startPinCreation(UserProfile userProfile, OneginiPinCallback callback, int pinLength);

  /**
   * Method called by the SDK when user provided a PIN that is not valid against pin policy.
   *
   * The method can be called zero or multiple times during PIN creation process.
   *
   * @param error instance of {OneginiPinValidationError} containing PIN validation details
   */
  void onNextPinCreationAttempt(OneginiPinValidationError error);

  /**
   * Method called when the SDK finishes PIN creation process.
   *
   * The method will be called only once, whenever correct PIN was created or the action was cancelled by the user.
   */
  void finishPinCreation();
}

The OneginiCreatePinRequestHandler class should be implemented by the application developer and provided to the OneginiClientBuilder's constructor. The OneginiCreatePinRequestHandler class is responsible for handling the PIN creation process, its startPinCreation() method will be invoked by the SDK whenever there will be a need to create a new PIN (during registration, or during the change pin action). If the PIN provided by user hasn't met PIN policy, the SDK will call the onNextPinCreationAttempt() method with the OneginiPinValidationError object. Whenever the correct PIN was created or the action was canceled by the user, the finishPinCreation() method will be called by the SDK.

OneginiPinAuthenticationRequestHandler

/**
 * Interface to handle PIN authentication request.
 */
public interface OneginiPinAuthenticationRequestHandler {

  /**
   * Method called when new PIN authentication request is made.
   *
   * The method will be called only once per PIN authentication process.
   *
   * @param userProfile     instance of {@link UserProfile} that describes which user has to authenticate with the PIN
   * @param callback        instance of {@link OneginiPinCallback} to send request's response back to the SDK
   * @param attemptCounter  instance of {@link AuthenticationAttemptCounter} holding information about failed, remaining and max PIN attempts
   */
  void startAuthentication(UserProfile userProfile, OneginiPinCallback callback, AuthenticationAttemptCounter attemptCounter);

  /**
   * Method called by the SDK when user provided an incorrect PIN, but his failed attempts limit was not reached yet.
   *
   * The method can be called zero or multiple times (but not more than maximum pin attempts limit) during PIN authentication process.
   *
   * @param attemptCounter object containing information about failed, remaining and max PIN attempts
   */
  void onNextAuthenticationAttempt(AuthenticationAttemptCounter attemptCounter);

  /**
   * Method called when the SDK finishes PIN authentication process.
   *
   * The method will be called only once, whenever authentication is finished with success or error.
   */
  void finishAuthentication();
}

The OneginiPinAuthenticationRequestHandler class should be implemented by and provided to OneginiClientBuilder's constructor. The OneginiPinAuthenticationRequestHandler class is responsible for handling PIN authentication requests, its startAuthentication() method will be invoked by the SDK whenever there will be a need to authenticate a user. If the PIN provided by user is incorrect, but his failed attempts limit was not been reached yet, the SDK will call the onNextAuthenticationAttempt() method with the AuthenticationAttemptCounter object containing information about failed, remaining and maximum attempts counters. Whenever authentication process is finished regardless of the outcome (success or error), the SDK will call finishAuthentication() method.

OneginiFingerprintAuthenticationRequestHandler


/**
 * Interface to handle fingerprint authentication request.
 */
public interface OneginiFingerprintAuthenticationRequestHandler {

  /**
   * Method called when new fingerprint authentication request is made.
   *
   * The method will be called only once per fingerprint authentication process.
   *
   * @param userProfile instance of {@link UserProfile} that describes which user has to authenticate with the fingerprint
   * @param callback    instance of {@link OneginiFingerprintCallback} to send request's response back to the SDK
   */
  void startAuthentication(UserProfile userProfile, OneginiFingerprintCallback callback);

  /**
   * Method called by the SDK when user provided an incorrect fingerprint, but his failed attempts limit hasn't been reached yet.
   *
   * The method can be called zero or multiple times during fingerprint authentication process.
   */
  void onNextAuthenticationAttempt();

  /**
   * Method called by the SDK when user puts his finger on the scanner.
   *
   * At this point the fingerprint hasn't been validated yet, but you can use this method to inform the user that his fingerprint was captured from the scanner and
   * is now being processed.
   */
  void onFingerprintCaptured();

  /**
   * Method called when the SDK finishes fingerprint authentication process.
   *
   * The method will be called only once, whenever authentication is finished with success or error.
   */
  void finishAuthentication();
}

The OneginiFingerprintAuthenticationRequestHandler class can be implemented and provided to OneginiClient using the OneginiClientBuilder#setFingerprintAuthenticatioRequestHandler() method. The OneginiFingerprintAuthenticationRequestHandler class is responsible for handling fingerprint authentication requests. The startAuthentication() method will be invoked by the SDK whenever there is a need to authenticate the user using his/her Fingprint. When the user provides a fingerprint to the scanner, the SDK will call the onFingerprintCaptured() method. At this point the fingerprint hasn't been validated yet, but you can use this method to inform the user that his fingerprint was captured from the scanner and is now being processed. If the fingerprint provided by the user is incorrect, but his failed attempts limit hasn't been reached yet, the SDK will call the onNextAuthenticationAttempt() method. Whenever authentication process is finished regardless of the outcome (success or error), the SDK will call the finishAuthentication() method.

Mobile authentication request handlers

This paragraph describes the Handlers used by the SDK when a user has to handle an incoming mobile authentication request (push message).

OneginiMobileAuthWithPushRequestHandler

/**
 * Interface to handle mobile authentication requests.
 */
public interface OneginiMobileAuthWithPushRequestHandler {

  /**
   * Method called when new mobile authentication request is made.
   *
   * @param mobileAuthenticationRequest instance of {@link OneginiMobileAuthenticationRequest} containing request's details
   * @param callback                    instance of {@link OneginiAcceptDenyCallback} to send request's response back to the SDK
   */
  void startAuthentication(OneginiMobileAuthenticationRequest mobileAuthenticationRequest, OneginiAcceptDenyCallback callback);

  /**
   * Method called when the SDK finishes mobile authentication process.
   *
   * The method will be called only once, whenever authentication is finished with success or error.
   */
  void finishAuthentication();
}

The OneginiMobileAuthWithPushRequestHandler class can be implemented provided to the OneginiClient using the OneginiClientBuilder#setMobileAuthWithPushRequestHandler() method. The OneginiMobileAuthWithPushRequestHandler class is responsible for handling an incoming mobile authentication request (simple authentication with "Accept" and "Deny" options). The SDK will call the startAuthentication() method when a new mobile authentication request has been received. Whenever authentication is finished regardless of the outcome (success or error), the SDK will call the finishAuthentication() method.

OneginiMobileAuthWithPushPinRequestHandler

/**
 * Interface to handle mobile authentication PIN requests.
 */
public interface OneginiMobileAuthWithPushPinRequestHandler {

  /**
   * Method called when new mobile authentication PIN request is made.
   *
   * The method will be called only once per mobile authentication process.
   *
   * @param mobileAuthenticationRequest       instance of {@link OneginiMobileAuthenticationRequest} containing request's details
   * @param callback                          instance of {@link OneginiPinCallback} to send request's response back to the SDK
   * @param attemptCounter                    instance of {@link AuthenticationAttemptCounter} holding information about failed, remaining and max PIN attempts
   * @param oneginiMobileAuthenticationError  instance of {@link OneginiMobileAuthenticationError} if fallback from other authenticator was triggered
   */
  void startAuthentication(OneginiMobileAuthenticationRequest mobileAuthenticationRequest, OneginiPinCallback callback,
                           AuthenticationAttemptCounter attemptCounter, OneginiMobileAuthenticationError oneginiMobileAuthenticationError);
  /**
   * Method called by the SDK when user have provided an incorrect PIN, but his failed attempts limit hasn't been reached yet.
   *
   * The method can be called zero or multiple times (but not more than maximum pin attempts limit) during PIN authentication process.
   *
   * @param attemptCounter object containing information about failed, remaining and max PIN attempts
   */
  void onNextAuthenticationAttempt(AuthenticationAttemptCounter attemptCounter);

  /**
   * Method called when the SDK finishes mobile authentication process.
   *
   * The method will be called only once, whenever authentication is finished with success or error.
   */
  void finishAuthentication();
}

The OneginiMobileAuthWithPushPinRequestHandler class can be implemented and provided to OneginiClient using the OneginiClientBuilder#setMobileAuthWithPushPinRequestHandler() method. The OneginiMobileAuthWithPushPinRequestHandler class is responsible for handling an incoming mobile authentication request which needs to be confirmed with PIN authentication. The SDK will call the startAuthentication() method when a new mobile authentication request was received. If the PIN provided by the user is incorrect, but his failed attempts limit hasn't been reached yet, the SDK will call the onNextAuthenticationAttempt() method with the failed, remaining and maximum attempts counters provided by AuthenticationAttemptCounter param. Whenever authentication is finished regardless of the outcome (success or error), the SDK will call the finishAuthentication() method. In case when the mobile authentication with push was triggered as a result of a failed mobile authentication request with other authenticator type (i.e. fingerprint), the startAuthentication() method will also receive a non-null OneginiMobileAuthenticationError object with the error that caused the fallback.

OneginiMobileAuthWithPushFingerprintRequestHandler

/**
 * Interface to handle mobile authentication fingerprint requests.
 */
public interface OneginiMobileAuthWithPushFingerprintRequestHandler {

  /**
   * Method called when new mobile authentication fingerprint request is made.
   *
   * The method will be called only once per fingerprint authentication process.
   *
   * @param mobileAuthenticationRequest instance of {@link OneginiMobileAuthenticationRequest} containing request's details
   * @param callback                    instance of {@link OneginiFingerprintCallback} to send request's response back to the SDK
   */
  void startAuthentication(OneginiMobileAuthenticationRequest mobileAuthenticationRequest, OneginiFingerprintCallback callback);

  /**
   * Method called by the SDK when user provided an incorrect fingerprint, but his failed attempts limit hasn't been reached yet.
   *
   * The method can be called zero or multiple times during fingerprint authentication process.
   */
  void onNextAuthenticationAttempt();

  /**
   * Method called by the SDK when user puts his fingerprint on the scanner.
   *
   * At this point the fingerprint hasn't been validated yet, but you can use this method to inform the user that his fingerprint was captured from the scanner and
   * is now being processed.
   */
  void onFingerprintCaptured();

  /**
   * Method called when the SDK finishes fingerprint mobile authentication process.
   *
   * The method will be called only once, whenever authentication is finished with success or error.
   */
  void finishAuthentication();
}

The OneginiMobileAuthWithPushFingerprintRequestHandler class can be implemented and provided to OneginiClient using the OneginiClientBuilder#setMobileAuthWithPushFingerprintRequestHandler() method. The OneginiMobileAuthWithPushFingerprintRequestHandler class is responsible for handling an incoming mobile authentication request which must be confirmed with fingerprint authentication. The SDK will call the startAuthentication() method when a new mobile authentication request has been received. When a user provides a fingerprint to the scanner, the SDK will call the onFingerprintCaptured() method. At this point the fingerprint hasn't been validated yet, but you can use this method to inform the user that his fingerprint was captured from the scanner and is now being processed. If the fingerprint provided by the user is incorrect, but his failed attempts limit hasn't been reached yet, the SDK will call the onNextAuthenticationAttempt() method. Whenever the authentication process is finished regardless of the outcome (success or error), the SDK will call the finishAuthentication() method.

Authentication request callbacks

In order to provide authentication request results back to the SDK all authentication request handlers receive callback objects when the authentication is started.

Note: please note that the callback is send only in startAuthentication() method. If the onNextAuthenticationAttempt() method is called you should reuse the same handler, so it means that you should keep a reference to it until finishAuthentication() method is called.

OneginiAcceptDenyCallback

/**
 * Callback interface used by mobile authentication to pass mobile authentication result back to the SDK.
 */
public interface OneginiAcceptDenyCallback {

  /**
   * The method that has to be called when user accepts received mobile authentication request.
   */
  void acceptAuthenticationRequest();

  /**
   * The method that has to be called when user denies received mobile authentication request.
   */
  void denyAuthenticationRequest();
}
  • the OneginiAcceptDenyCallback is passed by the SDK when a new mobile authentication process request is received. When a user accepts the request, the acceptAuthenticationRequest() method has to be called. If the user denies the request, the denyAuthenticationRequest() method has to be called.

OneginiPinCallback

/**
 * Callback interface used by PIN authentication requests to pass PIN authentication result back to the SDK.
 */
public interface OneginiPinCallback {

  /**
   * The method that has to be called when user accepts received PIN authentication request.
   *
   * @param pin the PIN provided by the user
   */
  void acceptAuthenticationRequest(char[] pin);

  /**
   * The method that has to be called when user denies received PIN authentication request.
   */
  void denyAuthenticationRequest();
}

The OneginiPinCallback is passed by the SDK when a new authentication with PIN or mobile authentication with PIN request is made. When the user accepts the request and provides his PIN, the acceptAuthenticationRequest() method has to be called. If the user denies the request, the denyAuthenticationRequest() method has to be called (which will result in the ACTION_CANCELED error).

OneginiFingerprintCallback

/**
 * Callback interface used by fingerprint authentication requests to pass fingerprint authentication result back to the SDK.
 */
public interface OneginiFingerprintCallback {

  /**
   * The method that has to be called when user accepts received fingerprint authentication request.
   *
   * When called the SDK will start listening for the fingerprint using fingerprint scanner.
   */
  void acceptAuthenticationRequest();

  /**
   * The method that has to be called when user denies received fingerprint authentication request.
   */
  void denyAuthenticationRequest();

  /**
   * The method that has to be called when user wants to use his PIN instad of fingerprint for the authentication.
   */
  void fallbackToPin();
}

The OneginiFingerprintCallback is passed by the SDK when a new authentication with fingerprint or mobile authentication with fingerprint request is received. When the user accepts to provide his fingerprint, the acceptAuthenticationRequest() method has to be called. If the user denies the request, the denyAuthenticationRequest() method has to be called (which will result in the ACTION_CANCELED error). If the user wants to use his PIN instead, the fallbackToPin() method has to be called, which will result in finishing current fingerprint authentication request and starting a new PIN authentication request.