kony.localAuthentication Namespace

The kony.localAuthentication namespace provides the functions to authenticate, get the status of the authentication, and cancel authentication.

NOTE: Applicable for iOS: For information about how to enable the Face ID feature in your Quantum Visualizer application, click here. For information about how to detect whether a device supports either the Touch ID or Face ID feature or the Iris authentication, refer the getBiometryType API.

IMPORTANT: If you have used the Local authentication API in your Quantum Visualizer V8 projects, before moving your project to the V9 release, ensure that you read the Local Authentication Migration guidelines article on the Base Camp.

This namespace contains the following API elements.

Functions

The kony.localAuthentication namespace provides the following functions.

Authentication Modes

Following are the supported constants for authentication mode.

  • constants.LOCAL_AUTHENTICATION_MODE_TOUCH_ID
    The same constant can be used for any biometric authentication mode, i.e. Fingerprint(TouchID), FaceID, and Iris.

    NOTE: In case of Android, you can use the constant constants.LOCAL_AUTHENTICATION_MODE_BIOMETRICS in place of the constant constants.LOCAL_AUTHENTICATION_MODE_TOUCH_ID. The Biometric constant would support any biometric authentication mode.

  • constants.LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS
    This constant determines whether the device has either PIN, PATTERN, or PASSWORD configured as the authentication mode.

    NOTE: This constant is only available for the getStatusForAuthenticationMode API on the Android platform.

    When the getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS) API is invoked on a device, it returns one of the following status codes:

    • 5000: Indicates that a passcode (either PIN, PATTERN, or PASSWORD) is set on the device.
    • 5005: Indicates that the passcode is not set on the device.

Authenticators

Authenticators specify an acceptable list of authenticator types that the device supports. Authenticators are of the following three types:

  • kony.localAuthentication.BIOMETRIC_STRONG: Authentication by using biometric credentials (such as fingerprint, iris, or face) that satisfy (meets or exceeds) the requirements for the Strong strength level (Class 3) as defined by the Android Compatibility Definition. This is only supported on Android 11 (API level 30, and later) devices.
  • kony.localAuthentication.BIOMETRIC_WEAK: Authentication by using biometric credentials (such as fingerprint, iris, or face) that satisfy (meets or exceeds) the requirements for the Weak strength level (Class 2) as defined by the Android Compatibility Definition.

    This is only supported on Android (API level 28, and later) devices.

    NOTE: BIOMETRIC_WEAK is a superset that can imply either BIOMETRIC_WEAK or BIOMETRIC_STRONG. For more information about Biometric classes , refer Biometric sensors.

  • kony.localAuthentication.DEVICE_CREDENTIAL: Authentication by using non-biometric or device credentials, such as PIN, pattern, or password.

For example, if you specify a combination of the BIOMETRIC_WEAK and DEVICE_CREDENTIAL authenticators, devices that support the BIOMETRIC_WEAK authenticator display a system prompt with the biometric and device credential (PIN/PATTERN/PASSWORD) options. In devices that do not support the BIOMETRIC_WEAK authenticator, the system displays only the device credential (PIN/PATTERN/PASSWORD) options, provided that a device credential (PIN/PATTERN/PASSWORD) is configured on the device.

NOTE: In devices that use Android versions prior to Android 11 (API level 30), a few combinations of authenticators are not supported. For example, using only DEVICE_CREDENTIAL is not supported prior to API level 30, and using BIOMETRIC_STRONG with DEVICE_CREDENTIAL is not supported in API level 28 to 29. If you invoke the API with unsupported authenticators, the API returns an appropriate error code.

Status Codes

The following table provides a list of status codes and their descriptions.

Status Codes Description
5000 No Error
5001 Authentication is not successful because a user fails to provide valid credentials.
5002

Authentication is canceled by a user. The following are the examples for different OS.

  • In case of IOS, when a user taps Cancel in the dialog box.
  • In case of Android, when a user presses the device back button while the system UI is displayed.
5003

Authentication is canceled.

  • iOS: Authentication is canceled because the user tapped the fallback button (Enter Password).
  • Android: Authentication is canceled because the user tapped the negative button.
5004 Authentication is canceled by system.
5005 Authentication does not start because the passcode is not set on the device.
5006 Authentication does not start because biometrics are not available on the device.
5007 Authentication does not start because biometrics are not enrolled on the device.
5008 Authentication does not start because the target device's OS does not support local authentication with biometrics.
5009 Authentication was not successful because there were too many failed user attempts for authentication, and the feature has now been locked. In case of Android, this occurs after 5 failed attempts, and lasts for 30 seconds.
5010 Error state returned when the current request has been running too long. Applicable only for Android platform.
5011 The operation was cancelled because 5009 occurred too many times. Authentication is disabled until the user unlocks with strong authentication (PIN/Pattern/Password). Applicable only for Android platform.
5015 Authentication was not successful because there were unsupported biometric errors.
5016

Authentication was not successful because the system was unable to determine whether the user can authenticate. This status code is returned for the getStatusForAuthenticationMode API. Applicable only for Android platform.

This status code may be returned on older versions of Android, due to partial incompatibility with a newer API. Applications that require biometric authentication to be enabled on affected devices can still invoke the BiometricPrompt#authenticate() API after receiving this status code. However, such applications must be prepared to handle possible errors.

5018 One or more of the specified authenticators is already enrolled.
5019 All of the specified authenticators are not supported.
5020 Enrollment of the device to the specified authenticator is successful.
5021 Enrollment of the device to the specified authenticator has failed.
5022 The API is invoked when the app is running in the background.

NOTE:
Applicable for the Android OS and Devices

Android supports fingerprint, Face ID, and Iris modes of biometric authentication. Availability of the authentication is subject to the support provided by the device. Fingerprint is supported from Android 6 onwards. Face ID and Iris modes are supported from Android 10 onwards.

To support different modes of authentication, a developer need not make any changes to the API configuration. If the device supports multiple biometrics, the developer can specify a default or preferred method in device settings and the API invocation would launch the user preferred authentication flow.

There is no way to know the biometric modes supported by the device. Only the device user knows the biometric authentication supported by the device.