cordova-plugin-biometric-auth

Biometric authentication with optional KeyguardManager API for Cordova.

Platforms

• Android 5+
• Browser (filler)

Features

• AndroidX ready
• Authenticate with BiometricManager (fingerprint, iris, face, device credentials) since API 23
• Authenticate with KeyguardManager (pin, pattern, password, biometric if enrolled) since API 21
• Auto fallback to KeyguardManager when no biometric enrolled or supported
• Supports all authentication modes (WEAK, STRONG, DEVICE CREDENTIALS)
• Supports API level 21 and over

Installation

Install latest version from NPM

  cordova plugin add cordova-plugin-biometric-auth

Methods

isAvailable

Checks if the user can authenticate with either biometrics, fallback PIN, pattern or password. Biometric requires at least one biometric sensor to be present, enrolled, and available on the device.

cordova.plugins.BiometricAuth.isAvailable(successCallback, errorCallback, [optionalParams])

| optionalParams | | | --- | --- | | authenticators | int: An optional bit field representing the types of Authenticators that may be used for authentication on Android. Omit or use 0 to check for either biometrics or device credentials. Use 1 to check for KeyguardManager authentication. |

Android quirks

Not all combinations of authenticator types are supported prior to Android 11 (API 30). Specifically, DEVICE_CREDENTIAL alone is unsupported prior to API 30, and BIOMETRIC_STRONG | DEVICE_CREDENTIAL is unsupported on API 28-29.

Browser quirks

This filler platform always returns BIOMETRIC_SUCCESS and does not check nor use a real biometric device.

successCallback return values

• BIOMETRIC_SUCCESS: The user can authenticate with the requested method(s).
• KEYGUARD_MANAGER: Returned on API 21-22, or when biometric is not enrolled and authenticators value passed is 0 or 1: The user can authenticate with KeyuardManager methods.

errorCallback return values

• BIOMETRIC_ERROR_HW_UNAVAILABLE
• BIOMETRIC_ERROR_NONE_ENROLLED
• BIOMETRIC_ERROR_NO_HARDWARE
• BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED
• BIOMETRIC_ERROR_UNSUPPORTED
• BIOMETRIC_STATUS_UNKNOWN

Example 1

Check for any biometric enrolled, PIN, pattern or password availability.

var onSuccess = function (strSuccess) {
	console.log(strSuccess);
};
var onError = function (strError) {
	console.warn(strError);
};
cordova.plugins.BiometricAuth.isAvailable(onSuccess, onError);

Example 2

Check for any biometric (e.g. fingerprint, iris, or face) on the device that meets or exceeds the requirements for Class 2. Requires at least API 23 (Android 6).

var Authenticators = {
	KEYGUARD_MANAGER: 1,
	BIOMETRIC_STRONG: 15,
	BIOMETRIC_WEAK: 255,
	DEVICE_CREDENTIAL: 32768
};
var onSuccess = function (strSuccess) {
	console.log(strSuccess);
};
var onError = function (strError) {
	console.warn(strError);
};
var optionalParams = {
	authenticators = Authenticators.BIOMETRIC_WEAK;
};
cordova.plugins.BiometricAuth.isAvailable(onSuccess, onError, optionalParams);

authenticate

Shows the biometric prompt or the fallback device credential dialog for authentication.

cordova.plugins.BiometricAuth.authenticate(successCallback, errorCallback, [optionalParams])

| optionalParams | | | --- | --- | | title | string: The title to be displayed on the prompt. Defaults to Enter unlock credentials. | | subtitle | string: The subtitle to be displayed on the prompt. | | disableBackup | boolean: Removes the backup option from the prompt. Defaults to false. | | Android-specific | | | authenticators | int: A bit field representing all valid authenticator types that may be invoked by the prompt. Use 0 to allow either biometrics or device credentials. Use 1 to invoke KeyguardManager PIN, pattern, password or biometric if enrolled authentication. | | negativeButtonText | string: Sets the text for the cancel button on the prompt. Required whenever fallback is disabled. |

Android quirks

Not all combinations of authenticator types are supported prior to Android 11 (API 30). Specifically, DEVICE_CREDENTIAL alone is unsupported prior to API 30, and BIOMETRIC_STRONG | DEVICE_CREDENTIAL is unsupported on API 28-29.

Browser quirks

Browser platforms shows a dialog to manually select either of these results and does not perform any actual biometric check:

• AUTHENTICATION_FAILED
• BIOMETRIC_DISMISSED
• BIOMETRIC_SUCCESS

successCallback return values

• AUTHENTICATION_SUCCEEDED

errorCallback return values

• AUTHENTICATION_FAILED
• Please test demo app provided for other values.

Example

Prompt the user for biometric, PIN, pattern or password credentials.

var onSuccess = function (strSuccess) {
	console.log(strSuccess);
};
var onError = function (strError) {
	console.warn(strError);
};
var optionalParams = {
	title = "Confirm operation",
	subtitle = "Verify with biometrics to continue",
};
cordova.plugins.BiometricAuth.authenticate(onSuccess, onError, optionalParams);

Remarks

• Do not use BIOMETRIC_STRONG without checking its availability with isAvailable first.
• Do not use DEVICE_CREDENTIALS alone prior to API 30.
• Do not use BIOMETRIC_STRONG + DEVICE_CREDENTIAL on API 28-29.
• To force usage of KeyguardManager instead of BiometricManager, set 1 to the authenticators param.
• Using an authenticators value other than 0 or 1 will discard the disableBackup option.
• Always provide a negativeButtonText when using disableBackup or not using DEVICE_CREDENTIAL authenticator.
• Android 5 will use the KeyguardManager PIN, pattern or password regardless of any options.

Plugin demo app

• Compiled debug APK and reference
• Source code for www folder

Contributing

Please report any issue with this plugin in GitHub by providing detailed context and sample code. PRs to improve and add new features or platforms are always welcome.

• PR to add iOS platform is welcome