Push mobile authentication Handler

Introduction

When a user is enrolled for push mobile authentication, they are able to receive and respond to mobile authentication requests. After receiving a push notification containing such a request, the Onegini Cordova Plugin needs to know how to handle it. This is done via a PushMobileAuthHandler object, which can be used to register callbacks which will be called when certain mobile authentication steps are required.

Example: When a mobile authentication request of type push is received, the onConfirmationRequest callback will be called.

When onConfirmationRequest is called, the user should be prompted to either accept or deny the mobile authentication request. Once the user has made a choice, it can be supplied to the Onegini Cordova Plugin by calling an action, in this case accept or deny. The UI to do this is left up to the developer. The following example shows the general strategy to do this.

onPinRequest

This method is called on a mobile authentication request with the push with PIN method. It can also be called on the push with fingerprint method, in case of PIN fallback. The request can either be accepted using actions.accept taking the PIN as argument, or denied using actions.deny.

Unlike onPinRequest, this method will only be called once. Touch ID on iOS uses its own native UI to provide feedback to users, and the whole process is atomic. On Android, onFingerprintFailed will be called if the user needs to scan their fingerprint again.

onFingerprintCaptured

This method is called when the fingerprint sensor detects that a finger has been placed on the sensor. At this point, the fingerprint authenticity has not yet been determined. This method can be used to provide feedback to the user so that they are aware the device has detected their finger.

Note that this method is not available on iOS. TouchID on iOS uses its own native UI to provide feedback to users.

onFingerprintFailed

This method is called when the fingerprint previously detected was not recognized as the correct fingerprint. This method can be used to provide feedback to the user so they are aware the device did not recognize their fingerprint, and that they need to try again.

onSuccess

This method is called when the user has successfully accepted the mobile authentication request. At this point, the authentication request is considered completed, and another push notification can be handled.

onError

This method is called when the user has denied the mobile authentication request, the user has failed to authenticate themselves, or an error has occurred. At this point, the authentication request is considered completed, albeit failed. Another push notification can be handled.