Registration or authentication request handlers
When you call the registerUser or the authenticateUser method on the UserClient, the Android SDK needs some user input in order to finish the process (PIN or fingerprint). For this you need to provide your own implementation of interfaces called request handlers using the OneginiClientBuilder methods.
Registration request handler
The OneginiCreatePinRequestHandler and OneginiPinAuthenticationRequestHandler interfaces are required 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.
The OneginiBrowserRegistrationRequestHandler class is responsible for handling the registration process using an external web browser.
Example OneginiBrowserRegistrationRequestHandler
/**
* Interface to handle user's registration action.
*/
public interface OneginiBrowserRegistrationRequestHandler {
/**
* Method called when user has to authenticate in a web browser.
*
* @param url {@link Uri} url that was opened
* @param registrationCallback instance of {@link OneginiBrowserRegistrationCallback} to send browser response back to the SDK
*/
void startRegistration(Uri url, OneginiBrowserRegistrationCallback registrationCallback);
}
The startRegistration() method is invoked by the Android SDK whenever there is a need to ask for an access grant using a web browser. In such case you should open the provided URL in a separate web browser app and return the result via OneginiBrowserRegistrationCallback.
The OneginiBrowserRegistrationCallback is passed by the Android SDK when a registration in a web browser is requested. When the authentication in a web browser is completed, the IDAAS-core will return a URI that has to be passed in the 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).
Example OneginiBrowserRegistrationCallback
/**
* Interface to handle user registration request.
*/
public interface OneginiBrowserRegistrationCallback {
/**
* Method used to pass the registration callback returned by the web browser
* @param uri the uri that was returned after successful authentication from web browser
*/
void handleRegistrationCallback(final Uri uri);
/**
* Method used to deny the registration action.
*/
void denyRegistration();
}
Authentication request handlers
Request handlers are used by the Android SDK when a user has to authenticate (log in).
Example OneginiCreatePinRequestHandler
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 Android 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 the user hasn't met the PIN policy, the Android 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 Android SDK.
/**
* 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();
}
Example OneginiPinAuthenticationRequestHandler
The OneginiPinAuthenticationRequestHandler class should be implemented by and provided to the OneginiClientBuilder's constructor. The OneginiPinAuthenticationRequestHandler class is responsible for handling PIN authentication requests, its startAuthentication() method will be invoked by the Android SDK whenever there will be a need to authenticate a user. If the PIN provided by the user is incorrect, but the failed attempts limit was not reached yet, the Android SDK will call the onNextAuthenticationAttempt() method with the AuthenticationAttemptCounter object containing information about failed, remaining, and maximum attempt counters. Whenever authentication process is finished, regardless of the outcome (success or error), the Android SDK will call the finishAuthentication() method.
/**
* 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();
}
Example OneginiFingerprintAuthenticationRequestHandler
The OneginiFingerprintAuthenticationRequestHandler class can be implemented and provided to OneginiClient using the OneginiClientBuilder#setFingerprintAuthenticationRequestHandler() method. The OneginiFingerprintAuthenticationRequestHandler class is responsible for handling fingerprint authentication requests. The startAuthentication() method will be invoked by the Android SDK whenever there is a need to authenticate the user using their fingerprint. When the user provides a fingerprint to the scanner, the Android 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 Android SDK will call the onNextAuthenticationAttempt() method. Whenever the authentication process is finished, regardless of the outcome (success or error), the Android SDK will call the finishAuthentication() method.
/**
* 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();
}
Mobile authentication request handlers
This section describes the handlers used by the Android SDK when a user has to handle an incoming mobile authentication request (push message).
Example OneginiMobileAuthWithPushRequestHandler
The OneginiMobileAuthWithPushRequestHandler class can be implemented and 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 Android 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 Android SDK will call the finishAuthentication() method.
/**
* 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();
}
Example OneginiMobileAuthWithPushPinRequestHandler
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 Android SDK will call the startAuthentication() method when a new mobile authentication request was received. If the PIN provided by the user is incorrect, but their failed attempts limit hasn't been reached yet, the Android SDK will call the onNextAuthenticationAttempt() method with the failed, remaining, and maximum attempt counters provided by the AuthenticationAttemptCounter parameter. Whenever authentication is finished, regardless of the outcome (success or error), the Android SDK will call the finishAuthentication() method. When the mobile authentication with push was triggered as a result of a failed mobile authentication request with another authenticator type (such as fingerprint), the startAuthentication() method will also receive a non-null OneginiMobileAuthenticationError object with the error that caused the fallback.
/**
* 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();
}
Example OneginiMobileAuthWithPushFingerprintRequestHandler
The OneginiMobileAuthWithPushFingerprintRequestHandler class can be implemented and provided to the OneginiClient using the OneginiClientBuilder#setMobileAuthWithPushFingerprintRequestHandler() method. The OneginiMobileAuthWithPushFingerprintRequestHandler class is responsible for handling an incoming mobile authentication requests that must be confirmed with fingerprint authentication. The Android 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 Android 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 their fingerprint was captured from the scanner and is now being processed. If the fingerprint provided by the user is incorrect, but their failed attempts limit hasn't been reached yet, the Android SDK will call the onNextAuthenticationAttempt() method. Whenever the authentication process is finished regardless of the outcome (success or error), theAndroid SDK will call the finishAuthentication() method.
/**
* 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();
}
Authentication request callbacks
In order to provide authentication request results back to the Android SDK, all authentication request handlers receive callback objects when the authentication is started.
Note
The callback is sent only in the startAuthentication() method. If the onNextAuthenticationAttempt() method is called, you should keep a reference to the handler for reuse until the finishAuthentication() method is called.
Example OneginiAcceptDenyCallback
The OneginiAcceptDenyCallback is passed by the Android 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.
/**
* 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();
}
Example OneginiPinCallback
The OneginiPinCallback is passed by the Android 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).
/**
* 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();
}
Example OneginiFingerprintCallback
The OneginiFingerprintCallback is passed by the Android SDK when a new authentication with fingerprint or mobile authentication with fingerprint request is received. When the user accepts to provide their 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 the current fingerprint authentication request and starting a new PIN authentication request.
/**
* 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 instead of fingerprint for the authentication.
*/
void fallbackToPin();
}
