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:
|
configMap |
Specifies the configuration dictionary for the system authentication UI. The configMap parameter uses the following keys:
|
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:
|
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 Value | Description |
---|---|
status | A status code is returned indicating the usability status of authentication. |
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 thegetStatusForAuthenticationMode
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 thegetStatusForAuthenticationMode
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:- Check if device credentials are configured for the device by invoking the
getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS)
API. - If the credentials are configured, invoke the
authenticate
API with thedeviceCredentialAllowed
parameter set to True.
- Check if device credentials are configured for the device by invoking the
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:
|
configMap [dictionary] |
Specifies the configuration dictionary for the API. The configMap parameter uses the following keys:
NOTE:
|
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 Authenticator | Output 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.
|
5003 |
Authentication is canceled.
|
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.