JSDoc: Class: LocalAuthenticationFlow

Class: LocalAuthenticationFlow

LocalAuthenticationFlow

This class represents local authentication flow object which can be used for performing local authentications. This class is not directly instantiated. Instance of this class can be obtained when the promise returned from init resolves, when using properties from LocalAuthPropertiesBuilder. Setting up and using a local authentication flow is explained in the builder documentation.

Multiple types of local authentications are supported by this flow. App can provide a configuration area where user can enable / disable the local authentication types that app wants to support. App should use the manager instance for enabling and disabling local authentications. While enabling PIN authentication, pin challenge callback will be invoked. Note that Fingerprint or Biometric cannot be enabled unless PIN is already enabled. Also, PIN cannot be disabled when Fingerprint or Biometric is enabled. App UI can take care of this in the UI by manipulating the UI controls. For PIN based authentication, app can provide an option for the user to change pin. App should invoke manager instance's changePin method for doing this. Pin challenge callback will be invoked at this time.

For a given LocalAuthenticationFlow there is always a primary authentication, the one that was enabled by the user last. So, if user enabled PIN, then that is the primary authentication. If user enabled Fingerprint or Biometric, then that is the primary authentication. Even though PIN is still active, it becomes secondary authentication. Local authentication can be triggered by invoking LocalAuthenticationFlow#login. This will trigger the primary authentication. When PIN authentication is triggered, pin challenge callback will be invoked. When Fingerprint or Biometric authentication is triggered, then the device prompts the user to provide the relevant biometric. User will have an option to fallback on the secondary authentication, which is PIN, as per the device's policies. This is a standard mechanism provided by devices to help user to access the app even when user is unable to provide biometric.

There is no concept of logging out in case of local auth. So LocalAuthenticationFlow#logout is a noop.

Often local authentication is used in conjunction with a remote authentication. The objective is to have user log in once and not to prompt user for credentials, until needed due to session expiry or server policy. In this usecase, user logs in for the first time with the credentials and configures / authorizes app to use fingerprint or biometric login. This has to be implemented by the app as a setting or on the login screen. Once fingerprint or biometric authentication is allowed / enabled by the user, app should seek fingerprint or biometric whenever user login is needed. App should perform remote login transparently in the background. This can be achieved by chaining local authentication with remote authentication.

More specifically, to implement this use case, app has to trigger login on LocalAuthenticationFlow first and after that is successful, trigger login on RemoteAuthenticationFlow. If the RemoteAuthenticationFlow is able to do login transparently, without user credentials, we have the desired outcome. For this, RemoteAuthenticationFlow should support auto login as HttpBasicAuthPropertiesBuilder does or support refresh tokens as OAuthPropertiesBuilder or OpenIDConnectPropertiesBuilder does.

Another common use case with local authentication is to prompt user to provide fingerprint or biometric when app is relaunched or comes to foreground from background. This can be done by invoking LocalAuthenticationFlow#login in the resume listener / on startup as appropriate. LocalAuthenticationFlow#login can be invoked any time after LocalAuthenticationFlow is initialized and any number of times as needed. Each time user will be challenged.

Source:

IdmAuthFlows.js, line 2134

Extends

AuthenticationFlow

Methods

getManager() → {LocalAuthenticationFlowManager}

Returns the local auth manager associated with this flow.

Source:

IdmAuthFlows.js, line 2229

Returns:

Type: LocalAuthenticationFlowManager

isAuthenticated() → {Promise.<boolean>}

This method is used for checking if the user is authenticated or not.

Overrides:

AuthenticationFlow#isAuthenticated

Source:

IdmAuthFlows.js, line 2324

Returns:

Type: Promise.<boolean>

This method is used to login.

The promise is resolved when login succeeds. The user can be redirected to the app once this happens.

The promise gets rejected with an AuthError object which contains information on the reason of failure. This information can be used to shown the reason why login did not succeed. App keep track of these failures and implement specific policies related to maximum attempts and steps to do after multiple failures here.

Sample usage:

cordova.plugins.IdmAuthFlows.init(authProps).then(
  function(authenticationFlow) {
    var loginPromise = authenticationFlow.login();
    loginPromise.then(...);
    loginPromise.catch(...);
  }
);

In case of PIN authentication, PIN challenge callback will be invoked. App should show UI for collecting PIN from the user and pass it back to the plugin via callback as explained in LocalAuthPropertiesBuilder documentation.

In case of fingerprint or biometric based local authentication, the device native UI for collecting biometric will be provided to the user. This UI can be customized by the app as explained in LocalAuthPropertiesBuilder documentation. User will have a way to fall back on to PIN based authentication as per device policies. In this case the PIN authentication flow will kick in.

Overrides: