Capacitor Native Biometric

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

Use biometrics confirm device owner presence or authenticate users. A couple of methods are provided to handle user credentials. These are securely stored using Keychain (iOS) and Keystore (Android).

Why Native Biometric?

A free, comprehensive biometric authentication plugin with secure credential storage:

• All biometric types - Face ID, Touch ID, Fingerprint, Face Authentication, Iris, and Device Credentials (PIN, pattern, password)
• Secure credential storage - Keychain (iOS) and Keystore (Android) integration
• Flexible fallback - Optional passcode fallback when biometrics unavailable
• Customizable UI - Full control over prompts, titles, descriptions, button text
• Detailed error codes - Unified error handling across iOS and Android
• Resume listener - Detect biometry availability changes when app returns from background
• Modern package management - Supports both Swift Package Manager (SPM) and CocoaPods (SPM-ready for Capacitor 8)

Perfect for banking apps, password managers, authentication flows, and any app requiring secure user verification.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/native-biometric/

⚠️ Security Considerations

Important: verifyIdentity() Can Be Bypassed on Rooted/Jailbroken Devices

The verifyIdentity() method should not be used as the sole authentication mechanism for sensitive operations. On rooted Android devices or jailbroken iOS devices, attackers can use tools like Frida, Xposed, or similar frameworks to:

• Hook the JavaScript bridge and force verifyIdentity() to return success
• Intercept native method calls and bypass biometric authentication
• Modify the app's runtime behavior to skip authentication checks

Recommended Security Practices

1. Use Root/Jailbreak Detection: Protect your app by detecting compromised devices. We recommend using the @capgo/capacitor-is-root plugin to detect rooted/jailbroken devices:

import { IsRoot } from '@capgo/capacitor-is-root';

async function checkDeviceSecurity() {
  const { result } = await IsRoot.isRooted();
  
  if (result) {
    // Handle rooted device - show warning, restrict features, or block access
    console.warn('Device security compromised');
    return false;
  }
  return true;
}

2. Never Store Sensitive Data Client-Side: Don't rely on locally stored credentials for critical authentication. Use verifyIdentity() as a convenience feature, not a security boundary.

3. Server-Side Verification: Always validate authentication on your backend server. Biometric authentication should be used for user convenience, with the real authentication happening server-side.

4. Implement Additional Security Layers:

   • Use certificate pinning for API calls
   • Implement server-side session management
   • Use short-lived tokens that expire after biometric auth
   • Add anti-tampering checks

Secure Usage Pattern

import { NativeBiometric } from "@capgo/capacitor-native-biometric";
import { IsRoot } from '@capgo/capacitor-is-root';

async function secureAuthentication() {
  // 1. Check device security first
  const { result } = await IsRoot.isRooted();
  if (result) {
    // Handle rooted device appropriately
    // Example: showSecurityWarning() could display an alert to the user
    showSecurityWarning();
    // Optionally: disable biometric login, require re-authentication, etc.
  }

  // 2. Perform biometric authentication
  try {
    await NativeBiometric.verifyIdentity({
      reason: "Authenticate to access your account",
      title: "Biometric Login",
    });
  } catch (error) {
    console.error("Biometric authentication failed");
    return false;
  }

  // 3. Get stored credentials (if needed for convenience)
  const credentials = await NativeBiometric.getCredentials({
    server: "www.example.com",
  });

  // 4. CRITICAL: Validate credentials with your backend server
  // Example: validateWithServer() should send credentials to your API
  // and verify them server-side before granting access
  const isValid = await validateWithServer(credentials.username, credentials.password);
  
  return isValid;
}

What This Plugin Provides

This plugin provides:

• ✅ Convenient local biometric authentication UI
• ✅ Secure credential storage using Keychain (iOS) and Keystore (Android)
• ✅ Protection against casual unauthorized access

This plugin does NOT provide:

• ❌ Protection against determined attackers on compromised devices
• ❌ Server-side authentication or validation
• ❌ Root/jailbreak detection (use @capgo/capacitor-is-root)

Recent Security Improvements (v8.2.0+)

Android Encryption Enhancement: The Android implementation now uses properly randomized Initialization Vectors (IVs) for AES-GCM encryption of stored credentials. Previous versions used a fixed IV, which is a cryptographic vulnerability.

Automatic Migration: The plugin automatically handles credentials encrypted with the older method:

• When reading credentials, it first attempts the new secure format, then falls back to the legacy format if needed
• When saving credentials, they are always encrypted using the new secure format
• No action required from users - migration happens transparently on first credential save after update

Recommendation: After updating to v8.2.0+, users should re-save their credentials to ensure they're encrypted with the improved format. This happens automatically when users authenticate and save credentials again.

Installation (Only supports Capacitor 7)

• npm i @capgo/capacitor-native-biometric

Usage

⚠️ Important: Before implementing biometric authentication, review the Security Considerations section to understand limitations and best practices for secure implementation.

import { NativeBiometric, BiometryType } from "@capgo/capacitor-native-biometric";

async performBiometricVerification(){
  const result = await NativeBiometric.isAvailable();

  if(!result.isAvailable) return;

  // Check the biometry type for display purposes
  // IMPORTANT: Always use isAvailable for logic decisions, not biometryType
  const isFaceID = result.biometryType == BiometryType.FACE_ID;

  // Check if device has PIN/pattern/password set
  console.log('Device is secure:', result.deviceIsSecure);

  // Check if strong biometry (Face ID, Touch ID, fingerprint) is available
  console.log('Strong biometry available:', result.strongBiometryIsAvailable);

  const verified = await NativeBiometric.verifyIdentity({
    reason: "For easy log in",
    title: "Log in",
    subtitle: "Maybe add subtitle here?",
    description: "Maybe a description too?",
  })
    .then(() => true)
    .catch(() => false);

  if(!verified) return;

  const credentials = await NativeBiometric.getCredentials({
    server: "www.example.com",
  });
  
  // IMPORTANT: Always validate credentials with your backend server
  // Do not trust client-side verification alone
}

// Save user's credentials
NativeBiometric.setCredentials({
  username: "username",
  password: "password",
  server: "www.example.com",
}).then();

// Check if credentials are already saved
const isSaved = await NativeBiometric.isCredentialsSaved({
  server: "www.example.com",
});
console.log('Credentials saved:', isSaved.isSaved);

// Delete user's credentials
NativeBiometric.deleteCredentials({
  server: "www.example.com",
}).then();

// Listen for biometry availability changes when app resumes from background
const handle = await NativeBiometric.addListener('biometryChange', (result) => {
  console.log('Biometry availability changed:', result.isAvailable);
  console.log('Biometry type:', result.biometryType);
});

// To remove the listener when no longer needed:
// await handle.remove();

Complete Login Flow Example

This example shows how to use isCredentialsSaved() to check if credentials are already saved before showing a "save credentials" popup:

// After successful login
async handleLoginSuccess(username: string, password: string) {
  // Check if biometric authentication is available
  const result = await NativeBiometric.isAvailable({ useFallback: true });
  
  if (!result.isAvailable) {
    // Biometrics not available - go to home page directly
    this.navigateToHome();
    return;
  }
  
  // Check if credentials are already saved
  const checkCredentials = await NativeBiometric.isCredentialsSaved({
    server: "www.example.com"
  });
  
  if (checkCredentials.isSaved) {
    // Credentials already saved - go to home page
    this.navigateToHome();
  } else {
    // No credentials saved - show save credentials popup
    this.showSaveCredentialsPopup(username, password);
  }
}

// Save credentials when user confirms
async saveCredentials(username: string, password: string) {
  await NativeBiometric.setCredentials({
    username: username,
    password: password,
    server: "www.example.com",
  });
  this.navigateToHome();
}

Biometric Auth Errors

This is a plugin specific list of error codes that can be thrown on verifyIdentity failure, or set as a part of isAvailable. It consolidates Android and iOS specific Authentication Error codes into one combined error list.

Code	Description	Platform
0	Unknown Error	Android, iOS
1	Biometrics Unavailable	Android, iOS
2	User Lockout	Android, iOS
3	Biometrics Not Enrolled	Android, iOS
4	User Temporary Lockout	Android (Lockout for 30sec)
10	Authentication Failed	Android, iOS
11	App Cancel	iOS
12	Invalid Context	iOS
13	Not Interactive	iOS
14	Passcode Not Set	Android, iOS
15	System Cancel	Android, iOS
16	User Cancel	Android, iOS
17	User Fallback	Android, iOS

• isAvailable(...)
• addListener('biometryChange', ...)
• verifyIdentity(...)
• getCredentials(...)
• setCredentials(...)
• deleteCredentials(...)
• isCredentialsSaved(...)
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

isAvailable(...)

isAvailable(options?: IsAvailableOptions | undefined) => Promise<AvailableResult>

Checks if biometric authentication hardware is available.

Param	Type
options	IsAvailableOptions

Returns: Promise<AvailableResult>

Since: 1.0.0

---

addListener('biometryChange', ...)

addListener(eventName: 'biometryChange', listener: BiometryChangeListener) => Promise<PluginListenerHandle>

Adds a listener that is called when the app resumes from background. This is useful to detect if biometry availability has changed while the app was in the background (e.g., user enrolled/unenrolled biometrics).

Param	Type	Description
eventName	'biometryChange'	- Must be 'biometryChange'
listener	BiometryChangeListener	- Callback function that receives the updated AvailableResult

Returns: Promise<PluginListenerHandle>

Since: 7.6.0

---

verifyIdentity(...)

verifyIdentity(options?: BiometricOptions | undefined) => Promise<void>

Prompts the user to authenticate with biometrics.

Param	Type
options	BiometricOptions

Since: 1.0.0

---

getCredentials(...)

getCredentials(options: GetCredentialOptions) => Promise<Credentials>

Gets the stored credentials for a given server.

Param	Type
options	GetCredentialOptions

Returns: Promise<Credentials>

Since: 1.0.0

---

setCredentials(...)

setCredentials(options: SetCredentialOptions) => Promise<void>

Stores the given credentials for a given server.

Param	Type
options	SetCredentialOptions

Since: 1.0.0

---

deleteCredentials(...)

deleteCredentials(options: DeleteCredentialOptions) => Promise<void>

Deletes the stored credentials for a given server.

Param	Type
options	DeleteCredentialOptions

Since: 1.0.0

---

isCredentialsSaved(...)

isCredentialsSaved(options: IsCredentialsSavedOptions) => Promise<IsCredentialsSavedResult>

Checks if credentials are already saved for a given server.

Param	Type
options	IsCredentialsSavedOptions

Returns: Promise<IsCredentialsSavedResult>

Since: 7.3.0

---

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

---

Interfaces

AvailableResult

Result from isAvailable() method indicating biometric authentication availability.

Prop	Type	Description
isAvailable	boolean	Whether authentication is available (biometric or fallback if useFallback is true)
authenticationStrength	AuthenticationStrength	The strength of available authentication method (STRONG, WEAK, or NONE)
biometryType	BiometryType	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	boolean	Whether the device has a secure lock screen (PIN, pattern, or password). This is independent of biometric enrollment.
strongBiometryIsAvailable	boolean	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	BiometricAuthError	Error code from BiometricAuthError enum. Only present when isAvailable is false. Indicates why biometric authentication is not available.

IsAvailableOptions

Prop	Type	Description
useFallback	boolean	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.

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

BiometricOptions

Prop	Type	Description	Default
reason	string
title	string
subtitle	string
description	string
negativeButtonText	string
useFallback	boolean	Only for iOS. Specifies if should fallback to passcode authentication if biometric authentication fails. On Android, this parameter is ignored due to BiometricPrompt API constraints: DEVICE_CREDENTIAL authenticator and negative button (cancel) are mutually exclusive.
fallbackTitle	string	Only for iOS. Set the text for the fallback button in the authentication dialog. If this property is not specified, the default text is set by the system.
maxAttempts	number	Only for Android. Set a maximum number of attempts for biometric authentication. The maximum allowed by android is 5.	1
allowedBiometryTypes	BiometryType[]	Only for Android. Specify which biometry types are allowed for authentication. If not specified, all available types will be allowed.

Credentials

Prop	Type
username	string
password	string

GetCredentialOptions

Prop	Type
server	string

SetCredentialOptions

Prop	Type
username	string
password	string
server	string

DeleteCredentialOptions

Prop	Type
server	string

IsCredentialsSavedResult

Prop	Type
isSaved	boolean

IsCredentialsSavedOptions

Prop	Type
server	string

Type Aliases

BiometryChangeListener

Callback type for biometry change listener

(result: AvailableResult): void

Enums

AuthenticationStrength

Members	Value	Description
NONE	0	No authentication available, even if PIN is available but useFallback = false
STRONG	1	Strong authentication: Face ID on iOS, fingerprints on devices that consider fingerprints strong (Android). Note: PIN/pattern/password is NEVER considered STRONG, even when useFallback = true.
WEAK	2	Weak authentication: Face authentication on Android devices that consider face weak, or PIN/pattern/password if useFallback = true (PIN is always WEAK, never STRONG).

BiometryType

Members	Value
NONE	0
TOUCH_ID	1
FACE_ID	2
FINGERPRINT	3
FACE_AUTHENTICATION	4
IRIS_AUTHENTICATION	5
MULTIPLE	6
DEVICE_CREDENTIAL	7

BiometricAuthError

Members	Value	Description
UNKNOWN_ERROR	0	Unknown error occurred
BIOMETRICS_UNAVAILABLE	1	Biometrics are unavailable (no hardware or hardware error) Platform: Android, iOS
USER_LOCKOUT	2	User has been locked out due to too many failed attempts Platform: Android, iOS
BIOMETRICS_NOT_ENROLLED	3	No biometrics are enrolled on the device Platform: Android, iOS
USER_TEMPORARY_LOCKOUT	4	User is temporarily locked out (Android: 30 second lockout) Platform: Android
AUTHENTICATION_FAILED	10	Authentication failed (user did not authenticate successfully) Platform: Android, iOS
APP_CANCEL	11	App canceled the authentication (iOS only) Platform: iOS
INVALID_CONTEXT	12	Invalid context (iOS only) Platform: iOS
NOT_INTERACTIVE	13	Authentication was not interactive (iOS only) Platform: iOS
PASSCODE_NOT_SET	14	Passcode/PIN is not set on the device Platform: Android, iOS
SYSTEM_CANCEL	15	System canceled the authentication (e.g., due to screen lock) Platform: Android, iOS
USER_CANCEL	16	User canceled the authentication Platform: Android, iOS
USER_FALLBACK	17	User chose to use fallback authentication method Platform: Android, iOS

## Face ID (iOS)

To use FaceID Make sure to provide a value for NSFaceIDUsageDescription, otherwise your app may crash on iOS devices with FaceID.

This value is just the reason for using FaceID. You can add something like the following example to App/info.plist:

<key>NSFaceIDUsageDescription</key>
<string>For an easier and faster log in.</string>

Biometric (Android)

To use android's BiometricPrompt api you must add the following permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.USE_BIOMETRIC">

Important Note About biometryType on Android

The biometryType field indicates what biometric hardware is present, but hardware presence does not guarantee availability. Some Android devices report face authentication hardware but don't make it available to apps.

Always use isAvailable for logic decisions, not biometryType. The biometryType field should only be used for display purposes (e.g., showing "Use Face ID" vs "Use Fingerprint" in your UI).

Web Platform

This plugin provides a dummy implementation for in-browser development and testing. On web:

• isAvailable() returns { isAvailable: true, ... } simulating biometric availability
• addListener() returns a no-op handle
• verifyIdentity() always succeeds (no actual authentication)
• Credential methods use in-memory storage (credentials stored in a Map, cleared on page refresh)

This allows you to develop and test your app in the browser without errors. Note that real biometric authentication is only available on iOS and Android platforms.

Contributors

Jonthia QliQ.dev Brian Weasner Mohamed Diarra

Want to Contribute?

Learn about contributing HERE

Notes

Hasn't been tested on Android API level 22 or lower.