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.

The API is used to authenticate the user with configurable system UI.

NOTE: Call the kony.localAuthentication.authenticate API only if the kony.localAuthentication.getStatusForAuthenticationMode API returns the success status code (5000).

Syntax

kony.localAuthentication.authenticate(authenticationMode, statusCallback, configMap);

Input Parameters

Parameter Description
authenticationMode

Specifies the biometric authentication mode for which the status is requested. The data type is constant. For the authentication modes, see Authentication Modes.
statusCallBack (status, message, info)

A callback function that conveys the status of the authentication with an appropriate status code, message, and an info object that contains more information about the authentication. The default value is nil. For status code, see the Status Codes section.

info: An object that contains more information about the authentication. The info object uses the following key:

  • authenticationType: Provides information about the type of authentication (either biometrics or device credentials) that the user has configured for authentication. The authenticationType parameter returns one of the following constants:

    • kony.localAuthentication.AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL: The user has authenticated by using device credentials (such as PIN/PATTERN/PASSWORD) as the authentication mode.

    • kony.localAuthentication.AUTHENTICATION_RESULT_TYPE_BIOMETRIC: The user has authenticated by using biometrics( such as FACE/FINGERPRINT/IRIS) as the authentication mode.

    • kony.localAuthentication.AUTHENTICATION_RESULT_TYPE_UNKNOWN: The authentication type that is returned when the user has used an unknown method for authentication. This value may be returned on older versions of Android due to partial incompatibility with a newer API.
      It does not necessarily imply that the user has used an authentication method other than those represented by AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL and AUTHENTICATION_RESULT_TYPE_BIOMETRIC.

    If the authentication fails, the authenticationType parameter returns a null value.
configMap

Specifies the configuration dictionary for the system authentication UI. The configMap parameter uses the following keys:

  • promptMessage: Message to be displayed on the screen. This key is used to set title in the System UI, applicable for both the iOS and the Android platforms. This is a mandatory key.
  • fallbackTitle: Allows you to edit the default text, "Enter Password" on the native pop-up, which is displayed when user authentication fails using Touch ID or Face ID. This is applicable only for the iOS platform. This is a mandatory key.
  • policy: Use this key to set the local authentication policy. This is applicable only for the iOS platform. The value of this key is set to constants.LOCAL_AUTHENTICATION_POLICY_DEV_OWNER_AUTH_WITH_BIOMETRICS, by default. This is an optional key.

    Depending on the type of local authentication policy, the policy key can have the following values:

    • constants.LOCAL_AUTHENTICATION_POLICY_DEV_OWNER_AUTH_WITH_BIOMETRICS
    • constants.LOCAL_AUTHENTICATION_POLICY_DEV_OWNER_AUTH
  • subTitle: Use this key to set a subtitle in the System UI. This is an optional key applicable only for the Android platform.

  • deviceCredentialAllowed: Use this key to enable device credentials in the System UI. This is an optional key applicable only for the Android platform. The default value is false.

    NOTE:
    • This key has been deprecated. Instead of using the deviceCredentialAllowed key, you can specify DEVICE_CREDENTIAL as the value for the authenticators key.
    • When you configure the authenticators key, the device ignores the deviceCredentialAllowed property.
    • When you set the deviceCredentialAllowed key, the negativeButtonText property is ignored, and the cancelAuthentication() API does not cancel an authentication in progress. This property allows the user to authenticate even with the device credentials (PIN/PASSWORD, PATTERN) which the user registered in the device settings.

  • authenticators: Use this key to specify the type of authenticators required in the device. You can also specify multiple (a combination of) authenticators as a list. The system prompt displays the supported authenticators. If no authenticators are specified, the device picks the default value for the authenticator, BIOMETRIC_WEAK. This is an optional key applicable only for the Android platform.

    NOTE: When you configure the authenticators key, the device ignores the deviceCredentialAllowed property.

  • confirmationRequired: After a user has been authenticated successfully, use this key to enable the Confirmation button.

    This key acts as a hint to the system to request for a confirmation from the user after a biometric authentication. For example, the Face and Iris authentication are passive implicit modalities that do not require a user action to be performed for execution.

    NOTE: As this key acts as a hint to the system, the system may choose to ignore this flag. If the system chooses to ignore this flag, it will require confirmation, by default.
    For example, if you disable implicit authentication in the settings, or if it does not apply to a modality (e.g. Fingerprint), the System may choose to ignore this key.

    A typical use case for not requiring confirmation would be low-risk transactions, such as re-authenticating a recently authenticated application. Likewise, A typical use case for requiring confirmation would be for authorizing a purchase.

    This is an optional key applicable only for devices running on Android Q and later versions.

  • negativeButtonText: Use this key to set the text for the negative button in the System UI. The default value for this key is Negative Button. This is an optional key applicable only for the Android platform.

    The negative button typically works as a Cancel button, but can be used as an alternate method to request authentication. For example, it can be used to request for a back up password. This key can be used to implement custom authentication.

    NOTE: When you select the negative button, the callback of the authenticate() API returns the 5003 error code.

    NOTE: When you set the deviceCredentialsAllowed key or specify DEVICE_CREDENTIAL as the value for the authenticators key, the negativeButtonText property is ignored,

Example


function statusCB(status, message, info) {  
    if (status == 5000)    {     
        kony.ui.Alert({
            message: "AUTHENTICATION SUCCESSFULL" + info.authenticationType,
            alertType: constants.ALERT_TYPE_INFO,
            yesLabel: "Close"
        }, {});   
    }  
    else    {     
        var messg = status + message;     
        kony.ui.Alert({
            message: messg,
            alertType: constants.ALERT_TYPE_INFO,
            yesLabel: "Close"
        }, {});  
    }
}
function authUsingTouchID() {  
    var configMap = {
        "promptMessage": "PLEASE AUTHENTICATE USING YOUR TOUCH ID",
        "fallbackTitle": "Please enter your Password"
        "description": "Description",
        "policy": constants.LOCAL_AUTHENTICATION_POLICY_DEV_OWNER_AUTH_WITH_BIOMETRICS,
        "subTitle": "sub title",
        "deviceCredentialAllowed": true,
        "confirmationRequired": true,
        "negativeButtonText": "Negative"
        "authenticators": [kony.localAuthentication.BIOMETRIC_WEAK, kony.localAuthentication.DEVICE_CREDENTIAL]
    };  
    kony.localAuthentication.authenticate(constants.LOCAL_AUTHENTICATION_MODE_BIOMETRICS, statusCB, configMap);
}

NOTE: The fallbackTitle and policy keys are only available for the iOS platform. The subTitle, deviceCredentialAllowed, confirmationRequired, and negativeButtonText keys are only available for the Android platform.

Return Values

No

Remarks

NOTE: For iOS devices, depending on the type of biometric authentication available, the promptMessage is either PLEASE AUTHENTICATE USING YOUR TOUCH ID or PLEASE AUTHENTICATE USING YOUR FACE ID. You can know the type of biometric authentication available using the getBiometyType API.

NOTE: If you assign an empty string, “ ” to the fallbackTitle key, the Enter Password button will be hidden. If the fallbackTitle key is not defined in the configMap parameter, the default (Enter Password) value is displayed.

Platform Availability

  • iOS
  • Android

The API cancels the current authentication process.

NOTE: This API won't work if the deviceCredentialAllowed key in the authenticate() is set to true.

Syntax

kony.localAuthentication.cancelAuthentication();

Example


var cancelButton = kony.ui.Button({
    onClick: btnOnClick
});
function btnOnClick() {
    kony.localAuthentication.cancelAuthentication()
}

Return Values

Return Value Description
status The 5004 status code is returned indicating the authentication is canceled.
 

Remarks

The API is available only for the Android platform.

Platform Availability

  • Android

The checkFeatureAvailability API provides information about the availability of local authentication-related system features in the device.

This API only indicates whether the device supports the specified feature. It does not indicate whether the feature is enabled or if the corresponding authentication data is registered with the device.

Syntax

kony.localAuthentication.checkFeatureAvailability();

Input Parameters

One or more values of face, fingerprint, iris as a list.

Example


var result = kony.localAuthentication.checkFeatureAvailability(["face", "fingerprint", "iris"]);
if (result.fingerprint == kony.localAuthentication.FEATURE_AVAILABLE) {
    alert("Fingerprint system feature is present in the device");
}

Return Values

A key-value pair in a JS object. The key is any of the face, fingerprint, or iris values. The value is any of the following constants:

Return Value Description
kony.localAuthentication.FEATURE_AVAILABLE The API returns this constant when the device supports the specified system feature.
kony.localAuthentication.FEATURE_NOT_AVAILABLE The API returns this constant when the device does not support the specified system feature.
kony.localAuthentication.FEATURE_UNKNOWN

The API returns this constant if the specified feature is unsupported on the device,

The API can detect support for the face and iris features in devices that run on Android 10 (API level 29), and later versions. Support to detect the fingerprint feature is present in Android 6 (and later) devices.
 

Remarks

This API behaves in accordance to the native Android packageManager.hasSystemFeature() API.

Platform Availability

  • Android

This API differentiates whether a device supports either the Touch ID or Face ID feature. The kony.localAuthentication.getBiometryType API is available from iOS 11.

Syntax

kony.localAuthentication.getBiometryType();

Example


function getBiometryTypeOfDevice() {
    var promptMessage = "Sign in with ";
    switch (kony.localAuthentication.getBiometryType()) {
        case constants.BIOMETRY_TYPE_NONE:
            // Handle the case if the device doesn't support any biometryType
            break;
        case constants.BIOMETRY_TYPE_TOUCHID:
            promptMessage += "TouchID";
            break;
        case constants.BIOMETRY_TYPE_FACEID:
            promptMessage += "FaceID";
            break;
        case constants.BIOMETRY_TYPE_UNDEFINED:
            // Handle the case if the device is not a iOS11 device or later
            break;
    }
}

Return Values

Return Value Description
constants.BIOMETRY_TYPE_NONE If there is no biometric authentication in the device.
constants.BIOMETRY_TYPE_TOUCHID If the device supports Touch ID authentication.
constants.BIOMETRY_TYPE_FACEID If the device supports Face ID authentication.
constants.BIOMETRY_TYPE_UNDEFINED If this API is called on the device with OS earlier than iOS11.
 

Remarks

Face ID is the new biometric authentication that Apple has introduced with iPhoneX. This API will help to customize the prompt message in kony.localAuthentication.authenticate. Depending on the type of authentication available, the prompt message is Sign in with FaceID or Sign in with TouchID.

Platform Availability

  • iOS

The API returns the usability status of the authentication.

NOTE: For information about how to detect whether a device supports either the Touch ID or Face ID biometrics, refer the getBiometryType API.

Syntax

kony.localAuthentication.getStatusForAuthenticationMode(authenticationMode, configMap);

Input Parameters

Parameter Description
authenticationMode

Specifies the authentication mode for which the status is requested. The data type is constant. For the authentication modes, see Authentication Modes.

NOTE: If LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS is specified as the authenticationMode, the system ignores the authenticators specified as part of the configMap parameter.
configMap - Optional

The configMap parameter uses the following keys:

  • authenticators: Use this key to specify the type of authenticators required in the device. If no authenticators are specified, the device picks the default value for the authenticator, BIOMETRIC_WEAK. You can also specify a combination of multiple authenticators as a list.

    When you invoke the API with the authenticators specified, if any of the authenticators is present, enrolled and available on the device, the API invokes a successcallback with the 5000 status code.

    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.

    NOTE: The configMap parameter is only available on Android devices.
 

Example


function isAuthUsingTouchSupported() {  
    var status = kony.localAuthentication.getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_TOUCH_ID);  
    if (status == 5000)    {     
        kony.ui.Alert({
            message: "AUTHENTICATION BY TOUCHID SUPPORTED",
            alertType: constants.ALERT_TYPE_INFO,
            yesLabel: "Close"
        }, {});   
    }  
    else    {     
        var msg = "TOUCHID AUTHENTICATION RETURNED THE STATUS ::" + status;     
        kony.ui.Alert({
            message: status,
            alertType: constants.ALERT_TYPE_INFO,
            yesLabel: "Close"
        }, {});   
    }
}

Return Values

Return ValueDescription
status

A status code is returned indicating the usability status of authentication.
For status codes, see the Status Codes section.

Remarks

  • Using the API, you can verify whether local authentication is supported on the device.
  • If you invoke the getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS) API, it provides information about whether the device uses device credentials (PIN/PATTERN/PASSWORD) as the authentication mode. Whereas, if you invoke the getStatusForAuthenticationMode API with only the DEVICE_CREDENTIAL authenticator, the API provides information about whether you can display a system prompt with the device credentials. You can only invoke the getStatusForAuthenticationMode API with the DEVICE_CREDENTIAL authenticator on Android 11 (API level 30, or later) devices.
  • On devices that use versions prior to Android 11 (API level 30), you can display a system prompt with the device credentials only if biometrics are not registered on the device. To do so, you must invoke the kony.localAuthentication.authenticate API with no authenticators, and the value of the deviceCredentialAllowed set as true. This approach is usually used when the kony.localAuthentication.getStatusForAuthenticationMode API returns the 5007(ERROR_NO_BIOMETRICS) status code.

  • Even when the getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_BIOMETRICS) API returns a 5005 status code (biometrics not set on the device), you can display a System Authentication prompt with either PIN, PATTERN, or PASSWORD by following these steps:

    1. Check if device credentials are configured for the device by invoking the getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS) API.
    2. If the credentials are configured, invoke the authenticate API with the deviceCredentialAllowed parameter set to True.

Platform Availability

  • iOS
  • Android

When biometrics are not enrolled on the device, and you invoke the authenticate() API, the 5007 (Authentication does not start because biometrics are not enrolled on the device) error code is returned. In such cases, developers can use the requestBiometricsEnroll API to direct app users to the device settings page, where they can enroll for biometrics and setup device credentials such as PIN/Pattern/Password, if necessary.

Syntax

kony.localAuthentication.requestBiometricsEnroll(statusCallback,configMap);

Input Parameters

Parameter Description
statusCallBack (status, message, info) [function]

A callback function that conveys the status of the authentication with an appropriate status code. The API returns one of the following status codes:

  • 5018: This is returned when any of the specified authenticators is already enrolled.
  • 5019: This is returned when all the specified authenticators are not supported.
  • 5020: This is returned on successful enrollment of the given authenticator.
  • 5021: This is returned on failure in the enrollment of the given authenticator.
configMap [dictionary]

Specifies the configuration dictionary for the API. The configMap parameter uses the following keys:

  • authenticators: Use this key to specify the type of authenticators required in the device. You can also specify multiple (a combination of) authenticators as a list. When the specified authenticators are present in the device but the device has not been enrolled for biometrics, the system displays the biometric enrollment settings screen to the user.

    If authenticators are not specified, the device picks the default value for the authenticator, DEVICE_CREDENTIAL. This is an optional key applicable only for the Android platform.

NOTE:
  • On Android 11 (API level 30, or later) devices, the API supports the kony.localAuthentication.BIOMETRIC_STRONG, kony.localAuthentication.BIOMETRIC_WEAK, and the kony.localAuthentication.DEVICE_CREDENTIAL authenticators.
  • On Android 9 and Android 10 (API level 28 and 29) devices, the API supports the kony.localAuthentication.BIOMETRIC_WEAK and the kony.localAuthentication.DEVICE_CREDENTIAL authenticators.
  • On devices that use Android versions prior to Android 8.1 (API level 27), the API supports only the kony.localAuthentication.DEVICE_CREDENTIAL authenticator.

Example


resultCallback: function(info) {
      alert("status code : "+ info.status);
},
enrommBiometric : function(){
      var configMap = {
          "authenticators": [kony.localAuthentication.BIOMETRIC_WEAK, kony.localAuthentication.DEVICE_CREDENTIAL],
          "callback" : this.resultCallback
      };
      kony.localAuthentication.enrollBiometrics(configMap);
}

Return Values

None

 

API Behavior

Based on the authenticator specified in the configMap parameter, and the configuration status of device credentials, the behavior of the API varies as follows:

Input AuthenticatorOutput Behavior when Device Credentials are not set Output Behavior when Device Credentials are already set
[kony.localAuthentication.DEVICE_CREDENTIAL]

The user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.

The API returns the 5018 status code.

[kony.localAuthentication.BIOMETRIC_WEAK]

In devices that use Android API levels less than or equal to 27 (<= 27), the API returns the 5019 status code.

In devices that use Android API levels greater than or equal to 28 (>=28), the following system prompt appears.

If the device does not support the BIOMETRIC_WEAK authenticator, the API returns the 5019 status code.

In devices that use Android API levels less than or equal to 27 (<= 27), the API returns the 5019 status code.

In devices that use Android API levels greater than or equal to 28 (>=28), the user must first authenticate with the current credential (such as PIN, pattern, or password) used on the device. After confirmation, the user is directed to register for biometrics on the device.

If the device does not support the BIOMETRIC_WEAK authenticator, the API returns the 5019 status code.

[kony.localAuthentication.BIOMETRIC_STRONG]

In devices that use Android API levels less than or equal to 29 (<= 29), the API returns the 5019 status code.

In devices that use Android API levels greater than or equal to 30 (>=30), the following system prompt appears.

If the device does not support the BIOMETRIC_STRONG authenticator, the API returns the 5019 status code.

In devices that use Android API levels less than or equal to 29 (<= 29), the API returns the 5019 status code.

In devices that use Android API levels greater than or equal to 30 (>=30), the user must first authenticate with the current credential (such as PIN, pattern, or password) used on the device. After confirmation, the user is directed to register for biometrics on the device.

If the device does not support the BIOMETRIC_STRONG authenticator, the API returns the 5019 status code.

[kony.localAuthentication.BIOMETRIC_WEAK, kony.localAuthentication.BIOMETRIC_STRONG, kony.localAuthentication.DEVICE_CREDENTIAL]

NOTE: BIOMETRIC_WEAK is a superset of BIOMETRIC_STRONG and is defined such that BIOMETRIC_STRONG | BIOMETRIC_WEAK == BIOMETRIC_WEAK

In devices that use Android API levels less than or equal to 27 (<= 27), the API only considers the DEVICE_CREDENTIAL authenticator.

In devices that use Android API levels greater than or equal to 28 (>=30), the following system prompt appears.

If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.

The API displays the following message:

One of the specified authenticator (kony.localAuthentication.DEVICE_CREDENTIAL) is already enrolled.

If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the API returns the 5018 status code.

[kony.localAuthentication.BIOMETRIC_WEAK, kony.localAuthentication.BIOMETRIC_STRONG]

NOTE: BIOMETRIC_WEAK is a superset of BIOMETRIC_STRONG and is defined such that BIOMETRIC_STRONG | BIOMETRIC_WEAK == BIOMETRIC_WEAK

In devices that use Android API levels less than or equal to 27 (<= 27), the API returns the 5019 status code.

In devices that use Android API levels greater than or equal to 28 (>=28), the following system prompt appears.

If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.

In devices that use Android API levels less than or equal to 27 (<= 27), the API returns the 5019 status code.

In devices that use Android API levels greater than or equal to 28 (>=28), the user must first authenticate with the current credential (such as PIN, pattern, or password) used on the device. After confirmation, the user is directed to register for biometrics on the device.

[kony.localAuthentication.BIOMETRIC_WEAK, kony.localAuthentication.DEVICE_CREDENTIAL]

In devices that use Android API levels less than or equal to 27 (<= 27), the API only considers the DEVICE_CREDENTIAL authenticator.

In devices that use Android API levels greater than or equal to 28 (>=28), the following system prompt appears.

If the device does not support the BIOMETRIC_WEAK authenticator, the user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.

The API displays the following message:

One of the specified authenticator (kony.localAuthentication.DEVICE_CREDENTIAL) is already enrolled.

If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the API returns the 5018 status code.

[kony.localAuthentication.BIOMETRIC_STRONG, kony.localAuthentication.DEVICE_CREDENTIAL]

In devices that use Android API levels less than or equal to 29 (<= 29), the API only considers the DEVICE_CREDENTIAL authenticator.

In devices that use Android API levels greater than or equal to 30 (>=30), the following system prompt appears.

If the device does not support the BIOMETRIC_STRONG authenticator, the user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.

The API displays the following message:

One of the specified authenticator (kony.localAuthentication.DEVICE_CREDENTIAL) is already enrolled.

If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the API returns the 5018 status code.

NOTE: The screens are only for the purpose of illustration, and may differ from device to device.
The screenshots displayed in the table have been captured on an Android emulator that uses Android API level 30.

Platform Availability

  • Android

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.