Step-by-step guide to adding Face ID and fingerprint authentication to Ionic apps using Capacitor plugins. Secure your Ionic app with biometric login for better UX.

 

Learn How to Add Biometric Authentication (Face ID & Fingerprint) to Your Ionic App with Capacitor

Biometric authentication—Face ID, Touch ID, and fingerprint scanning—is now the gold standard for securing apps. For Ionic developers, integrating biometrics has become easy thanks to Capacitor’s plugin ecosystem. In this guide, you’ll learn to add Face ID and fingerprint login to your Ionic app, improving both security and user experience.

Why Add Biometric Authentication?

• Enhanced Security: Biometrics use hardware-level encryption, making unauthorized access nearly impossible.
• User Convenience: No more typing passwords; users can log in instantly.
• User Trust: Modern apps are expected to support secure, frictionless login.

Prerequisites

• Ionic CLI installed
• Capacitor project set up
• Node.js LTS installed
• A test device with Face ID (iOS) or fingerprint unlock (Android)

Step 1: Create an Ionic + Capacitor App

If you don’t have a project yet, create one:

npm install -g @ionic/cli

ionic start biometric-demo blank --type=angular

cd biometric-demo

Add a Capacitor to the project:

ionic capacitor add ios

ionic capacitor add android 

Step 2: Install the Biometric Plugin

Capacitor provides a community-maintained plugin for fingerprint and Face ID:

npm install @capacitor-fingerprint-auth

npx cap sync

Step 3: Configure Platform Permissions

iOS Setup

Open your project in Xcode:

npx cap open ios

 Enable Face ID under Signing & Capabilities.

Add a usage description in Info.plist:

<key>NSFaceIDUsageDescription</key>

<string>This app uses Face ID for secure authentication.</string>

Android Setup

No additional configuration is required. Ensure your device has fingerprint or face unlock enabled.

Step 4: Implement Biometric Authentication

Open home.page.ts and add: 

 import { Component } from '@angular/core';

import { FingerprintAuth } from '@capacitor-fingerprint-auth';

@Component({

  selector: 'app-home',

  templateUrl: 'home.page.html',

})

export class HomePage {

  async authenticate() {

    const result = await FingerprintAuth.authenticate({

      reason: 'Please authenticate to access your account',

      description: 'Use your fingerprint or Face ID to log in',

    });

    if (result.verified) {

      console.log('Authentication successful!');

      // Navigate to your app’s secure area

    } else {

      console.log('Authentication failed or was cancelled.');

    }

  }

}

And update home.page.html:

<ion-content class="ion-padding">

  <ion-button expand="full" (click)="authenticate()">

    Login with Biometrics

  </ion-button>

</ion-content>

Step 5: Test on Real Devices

• iOS: Face ID requires real hardware; simulators do not support it.
• Android: Use any device with fingerprint/face unlock set up.

Run:

ionic capacitor run ios

ionic capacitor run android

Step 6: Best Practices

• Always Offer a Fallback – Provide password or PIN login if biometrics fail.
• Use Biometrics Sparingly – Prompt users only when necessary.
• Secure Tokens in Storage – Store sensitive data in Capacitor Secure Storage or native Keychain/Keystore.

Troubleshooting

• Plugin not recognized: Ensure npx cap sync was run after installation.
• Face ID prompt not showing: Check NSFaceIDUsageDescription is set correctly in Info.plist.
• Authentication fails on Android: Ensure fingerprint is set up in device security settings.

Conclusion

With just a few steps, you’ve integrated Face ID and fingerprint authentication into your Ionic app using Capacitor. This enhances security, improves UX, and builds user trust. You can expand further by combining biometrics with secure token storage, PIN fallback, and session timeouts for enterprise-grade security.