Biometric Authentication

A framework-agnostic biometric authentication library for React, Vue, Angular, or vanilla JavaScript. No providers required!

Documentation

• AI Integration Guide - Complete full-stack integration with backend package
• Backend Package - Server-side WebAuthn implementation

Features

• Zero Dependencies - Works without any specific framework (Capacitor optional)
• Provider-less - Direct API like Zustand, no Context/Providers needed
• Multi-Platform - Web (WebAuthn), iOS, Android, Electron support
• Framework Agnostic - Works with React, Vue, Angular, Vanilla JS
• TypeScript First - Full type safety and IntelliSense
• Secure by Default - Platform-specific secure storage
• Tiny Bundle - Tree-shakeable with dynamic imports
• Backward Compatible - Works as a Capacitor plugin too

Installation

npm install capacitor-biometric-authentication
# or
yarn add capacitor-biometric-authentication

Quick Start

import BiometricAuth from 'capacitor-biometric-authentication';

// Check availability
const isAvailable = await BiometricAuth.isAvailable();

// Authenticate
const result = await BiometricAuth.authenticate({
  reason: 'Please authenticate to continue',
});

if (result.success) {
  console.log('Authentication successful!');
}

Production Integration Guide

This section provides step-by-step instructions for integrating this plugin into a production Capacitor app.

Prerequisites

• Node.js 20+
• Capacitor 8.x
• For iOS: Xcode 15+, CocoaPods
• For Android: Android Studio, JDK 17

Step 1: Install the Plugin

npm install capacitor-biometric-authentication

Step 2: Sync Native Projects

npx cap sync

Step 3: Platform-Specific Configuration

Android Configuration

Minimum Requirements:

• minSdkVersion: 23 (Android 6.0)
• compileSdkVersion: 35
• Java 17

The plugin automatically includes required permissions in its AndroidManifest.xml:

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

Verify Gradle Settings (android/app/build.gradle):

android {
    compileSdkVersion 35

    defaultConfig {
        minSdkVersion 23
        targetSdkVersion 35
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

iOS Configuration

Minimum Requirements:

• iOS 13.0+
• Swift 5.1+

Required Info.plist Entry:

Add to ios/App/App/Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>We use Face ID to securely authenticate you</string>

Note: This key is required for Face ID devices. Without it, your app will crash when attempting Face ID authentication.

Web Configuration

Requirements:

• HTTPS (or localhost for development)
• Browser with WebAuthn support (Chrome 67+, Safari 14+, Firefox 60+, Edge 79+)
• Platform authenticator (TouchID, Windows Hello, etc.)

Development:

npm run dev  # localhost works without HTTPS

Production: Ensure your site uses HTTPS. WebAuthn will not work on non-secure origins.

Step 4: Use the Plugin

import BiometricAuth from 'capacitor-biometric-authentication';

// Check if biometrics are available
const available = await BiometricAuth.isAvailable();

if (available) {
  // Configure session duration (in seconds)
  BiometricAuth.configure({
    sessionDuration: 3600, // 1 hour
  });

  // Authenticate
  const result = await BiometricAuth.authenticate({
    reason: 'Authenticate to access your account',
    fallbackTitle: 'Use Passcode',
  });

  if (result.success) {
    console.log('Authenticated!');
  } else {
    console.error('Auth failed:', result.error?.message);
  }
}

Step 5: Build and Run

Web:

npm run build
npm run preview

Android:

npx cap sync android
npx cap run android
# or open in Android Studio:
npx cap open android

iOS:

npx cap sync ios
cd ios && pod install && cd ..
npx cap run ios
# or open in Xcode:
npx cap open ios

Framework Examples

React Example

import { useState, useEffect } from 'react';
import BiometricAuth from 'capacitor-biometric-authentication';

function SecureComponent() {
  const [isAuthenticated, setIsAuthenticated] = useState(false);

  useEffect(() => {
    const unsubscribe = BiometricAuth.subscribe((state) => {
      setIsAuthenticated(state.isAuthenticated);
    });
    return unsubscribe;
  }, []);

  const handleLogin = async () => {
    const result = await BiometricAuth.authenticate({
      reason: 'Access your account',
    });
    if (!result.success) console.error('Auth failed:', result.error);
  };

  return isAuthenticated ? (
    <h1>Welcome back!</h1>
  ) : (
    <button onClick={handleLogin}>Login with Biometrics</button>
  );
}

Vue Example

<template>
  <button
    v-if="!isAuthenticated"
    @click="authenticate"
  >
    Login with Biometrics
  </button>
  <div v-else>Welcome back!</div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import BiometricAuth from 'capacitor-biometric-authentication';

const isAuthenticated = ref(false);
let unsubscribe;

onMounted(() => {
  unsubscribe = BiometricAuth.subscribe((state) => {
    isAuthenticated.value = state.isAuthenticated;
  });
});

onUnmounted(() => unsubscribe?.());

const authenticate = () =>
  BiometricAuth.authenticate({ reason: 'Access your account' });
</script>

Vanilla JavaScript

<script type="module">
  import BiometricAuth from 'https://unpkg.com/capacitor-biometric-authentication/dist/web.js';

  document.getElementById('auth-btn').addEventListener('click', async () => {
    const result = await BiometricAuth.authenticate({
      reason: 'Please authenticate',
    });
    if (result.success)
      document.getElementById('status').textContent = 'Authenticated!';
  });
</script>
<button id="auth-btn">Authenticate</button>
<div id="status"></div>

API Reference

Core Methods

| Method | Description | | -------------------------- | ------------------------------------ | | isAvailable() | Check if biometric auth is available | | getSupportedBiometrics() | Get available biometric types | | authenticate(options?) | Perform authentication | | deleteCredentials() | Clear stored credentials | | configure(config) | Set plugin configuration | | logout() | Clear authentication session |

State Management

| Method | Description | | --------------------- | -------------------------------- | | subscribe(callback) | Subscribe to auth state changes | | getState() | Get current auth state | | isAuthenticated() | Check if currently authenticated |

Utility Methods

| Method | Description | | ------------------------------------------- | --------------------------- | | requireAuthentication(callback, options?) | Execute callback after auth | | withAuthentication(callback, options?) | Wrap operation with auth |

Configuration Options

BiometricAuth.configure({
  sessionDuration: 3600, // Session duration in SECONDS (default: 300)
  debug: false, // Enable debug logging
});

Authentication Options

await BiometricAuth.authenticate({
  reason: 'Authentication Required', // Displayed to user
  title: 'Biometric Login', // Android dialog title
  subtitle: 'Log in to your account', // Android dialog subtitle
  fallbackTitle: 'Use Passcode', // Fallback button text
  cancelTitle: 'Cancel', // Cancel button text
  disableDeviceCredential: false, // Disable passcode fallback
  maxAttempts: 3, // Max failed attempts before lockout
  saveCredentials: true, // Store credentials for future use
});

Platform Support

| Platform | Technology | Min Version | Status | | ------------------ | ------------------ | ----------- | ------ | | Web | WebAuthn API | Chrome 67+ | ✅ | | iOS | Touch ID / Face ID | iOS 13.0 | ✅ | | Android | BiometricPrompt | API 23 | ✅ | | Electron (macOS) | Touch ID | - | ✅ | | Electron (Windows) | Windows Hello | Windows 10 | ✅ |

Browser Support

• Chrome/Edge 67+ (Windows Hello, Touch ID)
• Safari 14+ (Touch ID, Face ID)
• Firefox 60+ (Windows Hello)

Windows Hello Support (Electron)

The plugin supports Windows Hello on Electron for Windows platforms. When running on Windows (win32), the ElectronAdapter automatically uses the WebAuthn API to interface with Windows Hello.

Requirements:

• Windows 10 or later
• Windows Hello configured in Windows Settings
• Electron with WebAuthn support

Usage: The same API works across all platforms:

// Works on macOS (Touch ID) and Windows (Windows Hello)
const result = await BiometricAuth.authenticate({
  reason: 'Authenticate with Windows Hello',
});

Error Handling

import BiometricAuth, {
  BiometricErrorCode,
} from 'capacitor-biometric-authentication';

const result = await BiometricAuth.authenticate();

if (!result.success) {
  switch (result.error?.code) {
    case BiometricErrorCode.USER_CANCELLED:
      console.log('User cancelled');
      break;
    case BiometricErrorCode.AUTHENTICATION_FAILED:
      console.log('Biometric not recognized');
      break;
    case BiometricErrorCode.BIOMETRIC_UNAVAILABLE:
      console.log('Biometric not available');
      break;
    case BiometricErrorCode.LOCKOUT:
      console.log('Too many failed attempts');
      break;
    case BiometricErrorCode.NOT_ENROLLED:
      console.log('No biometrics enrolled');
      break;
    default:
      console.log('Unknown error:', result.error?.message);
  }
}

Troubleshooting

For build failures and common integration issues, see the comprehensive Troubleshooting Guide.

Common issues covered:

• Android Gradle/SDK version mismatches
• iOS Info.plist missing entries
• Pod installation failures
• WebAuthn HTTPS requirements
• Plugin registration issues

Development

# Install dependencies
yarn install

# Build plugin
yarn build

# Watch mode
yarn watch

# Lint & format
yarn lint
yarn prettier

# Test in example app
cd example
yarn install
yarn dev           # Web development
yarn cap:sync      # Sync native platforms
yarn cap:ios:run   # Run on iOS
yarn cap:android:run  # Run on Android

Project Structure

├── src/                  # TypeScript source
│   ├── definitions.ts    # API interfaces
│   ├── index.ts          # Plugin entry
│   ├── web.ts            # Web implementation
│   ├── core/             # Core logic
│   ├── adapters/         # Platform adapters
│   └── utils/            # Utilities
├── android/              # Android native (BiometricPrompt)
├── ios/                  # iOS native (LocalAuthentication)
├── example/              # React example app
└── docs/                 # Documentation

Plugin Metadata

| Property | Value | | ----------------- | --------------------------------------- | | Package Name | capacitor-biometric-authentication | | Plugin ID | BiometricAuth | | Android Package | com.aoneahsan.capacitor.biometricauth | | iOS Class | BiometricAuthPlugin | | Capacitor Version | 8.x |

Documentation

Full documentation in docs/:

• Installation Guide
• Quick Start
• Platform Guides - iOS, Android, Web
• API Reference
• FAQ

Contributing

See Contributing Guide for details.

Support

• Troubleshooting Guide
• GitHub Issues
• Email

Changelog

See CHANGELOG.md for release history.

License

MIT © Ahsan Mahmood