Skip to content

fix(android): report weak-only biometrics as unavailable for strong auth #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Lukhaas25 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

fix(android): report weak-only biometrics as unavailable for strong auth #91

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2db47cf
Fix Android weak biometric availability result
May 20, 2026
c5ff15b
docs(definitions): clarify IsAvailableOptions.useFallback Android sem…
Lukhaas25 May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions .github/scripts/verify-packed-example.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,17 @@ bun run build

case "$platform" in
android)
bunx cap add android
if [ ! -d android ]; then
bunx cap add android
fi
bunx cap sync android
cd android
./gradlew build test
;;
ios)
bunx cap add ios
if [ ! -d ios ]; then
bunx cap add ios
fi
bunx cap sync ios
xcodebuild -project ios/App/App.xcodeproj -scheme App -destination generic/platform=iOS CODE_SIGNING_ALLOWED=NO
;;
Expand Down
22 changes: 11 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -470,21 +470,21 @@ Get the native Capacitor plugin version.

Result from isAvailable() method indicating biometric authentication availability.

| Prop | Type | Description |
| ------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`isAvailable`** | <code>boolean</code> | Whether authentication is available (biometric or fallback if useFallback is true) |
| **`authenticationStrength`** | <code><a href="#authenticationstrength">AuthenticationStrength</a></code> | The strength of available authentication method (STRONG, WEAK, or NONE) |
| **`biometryType`** | <code><a href="#biometrytype">BiometryType</a></code> | The primary biometry type available on the device. On Android devices with multiple biometry types, this returns MULTIPLE. Use this for display purposes only - always use isAvailable for logic decisions. |
| **`deviceIsSecure`** | <code>boolean</code> | Whether the device has a secure lock screen (PIN, pattern, or password). This is independent of biometric enrollment. |
| **`strongBiometryIsAvailable`** | <code>boolean</code> | Whether strong biometry (Face ID, Touch ID, or fingerprint on devices that consider it strong) is specifically available, separate from weak biometry or device credentials. |
| **`errorCode`** | <code><a href="#biometricautherror">BiometricAuthError</a></code> | Error code from <a href="#biometricautherror">BiometricAuthError</a> enum. Only present when isAvailable is false. Indicates why biometric authentication is not available. |
| Prop | Type | Description |
| ------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`isAvailable`** | <code>boolean</code> | Whether authentication is available. On Android, `verifyIdentity()` uses a `CryptoObject` backed by `BIOMETRIC_STRONG`, so weak-only biometric methods such as some face unlock implementations are reported via `biometryType`/`authenticationStrength` but do not make this value `true`. If `useFallback` is true, PIN/pattern/password can make this value true. |
| **`authenticationStrength`** | <code><a href="#authenticationstrength">AuthenticationStrength</a></code> | The strength of available authentication method (STRONG, WEAK, or NONE) |
| **`biometryType`** | <code><a href="#biometrytype">BiometryType</a></code> | The primary biometry type available on the device. On Android devices with multiple biometry types, this returns MULTIPLE. Use this for display purposes only - always use isAvailable for logic decisions. |
| **`deviceIsSecure`** | <code>boolean</code> | Whether the device has a secure lock screen (PIN, pattern, or password). This is independent of biometric enrollment. |
| **`strongBiometryIsAvailable`** | <code>boolean</code> | Whether strong biometry (Face ID, Touch ID, or fingerprint on devices that consider it strong) is specifically available, separate from weak biometry or device credentials. |
| **`errorCode`** | <code><a href="#biometricautherror">BiometricAuthError</a></code> | Error code from <a href="#biometricautherror">BiometricAuthError</a> enum. Only present when isAvailable is false. Indicates why biometric authentication is not available. |


#### IsAvailableOptions

| Prop | Type | Description |
| ----------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`useFallback`** | <code>boolean</code> | Only for iOS. Specifies if should fallback to passcode authentication if biometric authentication is not available. On Android, this parameter is ignored due to BiometricPrompt API constraints: DEVICE_CREDENTIAL authenticator and negative button (cancel) are mutually exclusive. |
| Prop | Type | Description |
| ----------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`useFallback`** | <code>boolean</code> | Specifies if passcode or device credentials should be considered when biometric authentication is not available. On Android, this can make `isAvailable()` return true when the device has a secure lock screen. The `verifyIdentity()` flow still ignores this option on Android due to BiometricPrompt API constraints: DEVICE_CREDENTIAL authenticator and negative button (cancel) are mutually exclusive. |


#### PluginListenerHandle
Expand Down
3 changes: 0 additions & 3 deletions android/src/main/java/ee/forgr/biometric/NativeBiometric.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,9 +129,6 @@ private JSObject checkBiometryAvailability(boolean useFallback) {
if (hasStrongBiometric) {
authenticationStrength = AUTH_STRENGTH_STRONG;
isAvailable = true;
} else if (hasWeakBiometric) {
authenticationStrength = AUTH_STRENGTH_WEAK;
isAvailable = true;
} else if (fallbackAvailable) {
authenticationStrength = AUTH_STRENGTH_WEAK;
isAvailable = true;
Expand Down
8 changes: 4 additions & 4 deletions example-app/bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions example-app/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@
"rebuild:android": "npm run build && cap sync android"
},
"dependencies": {
"@capacitor/camera": "latest",
"@capacitor/camera": "^8.2.0",
"@capacitor/core": "^8.0.0",
"@capacitor/splash-screen": "latest",
"@capacitor/splash-screen": "^8.0.1",
"@capgo/capacitor-native-biometric": "file:../"
},
"devDependencies": {
Expand Down
22 changes: 17 additions & 5 deletions src/definitions.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,16 @@ export interface Credentials {

export interface IsAvailableOptions {
/**
* Only for iOS.
* Specifies if should fallback to passcode authentication if biometric authentication is not available.
* On Android, this parameter is ignored due to BiometricPrompt API constraints:
* DEVICE_CREDENTIAL authenticator and negative button (cancel) are mutually exclusive.
* Whether passcode or device credentials should count toward biometric availability
* when no biometric is enrolled or available.
*
* - On iOS, this affects both `isAvailable()` and `verifyIdentity()`.
* - On Android, this is honored by `isAvailable()` only — the native check computes
* `fallbackAvailable = useFallback && deviceIsSecure` and reports availability
* accordingly. The `verifyIdentity()` flow ignores this option on Android due to
* BiometricPrompt API constraints (DEVICE_CREDENTIAL authenticator and negative
* button are mutually exclusive); use `BiometricOptions.useFallback` (iOS-only) to
* control the auth-dialog fallback there.
*/
useFallback: boolean;
}
Expand All @@ -76,7 +82,13 @@ export interface IsAvailableOptions {
*/
export interface AvailableResult {
/**
* Whether authentication is available (biometric or fallback if useFallback is true)
* Whether authentication is available.
*
* On Android, `verifyIdentity()` uses a `CryptoObject` backed by
* `BIOMETRIC_STRONG`, so weak-only biometric methods such as some face unlock
* implementations are reported via `biometryType`/`authenticationStrength`
* but do not make this value `true`.
* If `useFallback` is true, PIN/pattern/password can make this value true.
*/
Comment thread
coderabbitai[bot] marked this conversation as resolved.
isAvailable: boolean;
/**
Expand Down