Capacitor Native Biometric

Add Face ID, Touch ID and fingerprint login to your Capacitor app, and keep credentials safe in the iOS Keychain and Android Keystore.

Key features

• Biometric check: isAvailable() returns the biometry type, with optional device credential fallback.
• Authenticate: verifyIdentity() shows the native biometric prompt.
• Credentials: setCredentials(), getCredentials(), getSecureCredentials() and deleteCredentials() per server.
• Secure data: setData(), getData() and getSecureData() store any string value.
• Change events: the biometryChange listener runs when the app resumes, so you can detect enrollment changes made while it was in the background.
• Platforms: iOS, Android and Web. Web provides mocks for development.

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.

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Installation (Only supports Capacitor 7)

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-native-biometric` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

• 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, set as part of isAvailable(), or returned from getSecureCredentials() and getSecureData() when no biometric-protected item exists for the requested server or key. It consolidates Android and iOS specific authentication error codes into one combined error list.

Code 21 (getSecureCredentials, getSecureData), Stable, expected rejection when no biometric-protected credentials or data exist (for example after deletion, a fresh install, or items invalidated by biometric enrollment changes). Platform messages differ slightly:

• getSecureCredentials()
  • Android: No protected credentials found
  • iOS: No protected credentials found for server
• getSecureData()
  • Android: No protected data found
  • iOS: No protected data found for key

isCredentialsSaved() and isDataSaved() return true when any credentials or data exist for the server or key (protected or unprotected), so they do not guarantee that getSecureCredentials() or getSecureData() will succeed. Handle code 21 in your catch block, or only call after storing with accessControl BIOMETRY_CURRENT_SET or BIOMETRY_ANY. See getSecureCredentials() and getSecureData() for details.

• isAvailable(...)
• addListener('biometryChange', ...)
• verifyIdentity(...)
• getCredentials(...)
• setCredentials(...)
• deleteCredentials(...)
• getSecureCredentials(...)
• isCredentialsSaved(...)
• setData(...)
• getData(...)
• getSecureData(...)
• deleteData(...)
• isDataSaved(...)
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

isAvailable(...)

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

Checks if biometric authentication hardware is available.

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).

Returns: Promise<PluginListenerHandle>

Since: 7.6.0

verifyIdentity(...)

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

Prompts the user to authenticate with biometrics.

Since: 1.0.0

getCredentials(...)

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

Gets the stored credentials for a given server.

Returns: Promise<Credentials>

Since: 1.0.0

setCredentials(...)

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

Stores the given credentials for a given server.

Since: 1.0.0

deleteCredentials(...)

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

Deletes the stored credentials for a given server.

Since: 1.0.0

getSecureCredentials(...)

getSecureCredentials(options: GetSecureCredentialsOptions) => Promise<Credentials>

Gets the stored credentials for a given server, requiring biometric authentication. Credentials must have been stored with accessControl set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY.

On iOS, the system automatically shows the biometric prompt when accessing the protected Keychain item. On Android, BiometricPrompt is shown with a CryptoObject bound to the credential decryption key.

If no protected credentials exist for the server, the promise rejects with code 21 (BiometricAuthError.NO_PROTECTED_CREDENTIALS_FOUND). This is stable, expected behavior — for example when credentials were never saved with biometric protection, were deleted, or were invalidated after biometric enrollment changes. isCredentialsSaved() returns true when any credentials (protected or unprotected) exist, so it does not guarantee a biometric-protected entry is present — handle code 21 in your catch block or only call after storing with accessControl BIOMETRY_CURRENT_SET or BIOMETRY_ANY. Platform messages: Android No protected credentials found, iOS No protected credentials found for server.

Returns: Promise<Credentials>

Since: 8.4.0

isCredentialsSaved(...)

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

Checks if credentials are already saved for a given server.

Returns: Promise<IsCredentialsSavedResult>

Since: 7.3.0

setData(...)

setData(options: SetDataOptions) => Promise<void>

Stores an arbitrary string value under the given key. Values are encrypted at rest using the platform secure storage backend (Android Keystore + SharedPreferences, iOS Keychain).

For biometric-protected storage, set accessControl and retrieve the value with getSecureData(). Credential helpers remain available for username/password flows.

Since: 8.6.0

getData(...)

getData(options: GetDataOptions) => Promise<StoredData>

Gets a previously stored value for the given key. Only returns values stored without biometric accessControl.

Returns: Promise<StoredData>

Since: 8.6.0

getSecureData(...)

getSecureData(options: GetSecureDataOptions) => Promise<StoredData>

Gets a biometric-protected value for the given key. The value must have been stored with accessControl set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY.

Returns: Promise<StoredData>

Since: 8.6.0

deleteData(...)

deleteData(options: DeleteDataOptions) => Promise<void>

Deletes the stored value for the given key (protected and unprotected).

Since: 8.6.0

isDataSaved(...)

isDataSaved(options: IsDataSavedOptions) => Promise<IsDataSavedResult>

Checks whether a value is already saved for the given key.

Returns: Promise<IsDataSavedResult>

Since: 8.6.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.

IsAvailableOptions

PluginListenerHandle

BiometricOptions

Credentials

GetCredentialOptions

SetCredentialOptions

DeleteCredentialOptions

GetSecureCredentialsOptions

IsCredentialsSavedResult

IsCredentialsSavedOptions

SetDataOptions

StoredData

GetDataOptions

GetSecureDataOptions

DeleteDataOptions

IsDataSavedResult

IsDataSavedOptions

Type Aliases

BiometryChangeListener

Callback type for biometry change listener

(result: AvailableResult): void

Enums

AuthenticationStrength

BiometryType

BiometricAuthError