biometric_guard: The Best Flutter Package for Biometric Authentication with Session Management (Android & iOS)

Shahul Hameed — Mon, 11 May 2026 17:08:40 +0000

A complete guide to biometric_guard — a Flutter package for biometric and device-credential authentication with built-in session management, widget guards, route guards, reactive UI state, and lifecycle-safe background/foreground handling.

What Is biometric_guard?

If you've ever used Flutter biometric authentication, you've probably come across local_auth.

While local_auth provides the core authenticate() API, developers still need to build:

Session timeout handling
Route protection
Widget-level guards
Background/foreground lifecycle handling
Reactive UI updates
Testing utilities

biometric_guard brings all of these features together in one clean and easy-to-use API.

Why Use biometric_guard?

Key Features

Session timeout support
BiometricGuard for widget-level protection
BiometricRoute for route-level authentication
SessionStateBuilder for reactive UI
Fingerprint, Face ID, Touch ID, and device credentials
Resume authentication when returning from background
Biometric-only mode
Strongly typed AuthResult
Testing support

Platform Support

Android

Minimum Version: API 23 (Android 6.0)
Supports Fingerprint Authentication
Supports Face Authentication
Supports PIN / Device Credentials
Supports Resume on Foreground

iOS

Minimum Version: iOS 13.0
Supports Touch ID
Supports Face ID
Supports Passcode Authentication
Supports Resume on Foreground

Installation

Add the package to your pubspec.yaml:

dependencies:
  biometric_guard: ^1.0.4

Then run:

flutter pub get

Android Setup

1. Change MainActivity Base Class

Open:

android/app/src/main/kotlin/.../MainActivity.kt

// Before
import io.flutter.embedding.android.FlutterActivity
class MainActivity : FlutterActivity()

// After
import io.flutter.embedding.android.FlutterFragmentActivity
class MainActivity : FlutterFragmentActivity()

Without this change, authentication will fail with AuthResultCode.notFragmentActivity.

2. Add Permissions

In AndroidManifest.xml:

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

3. Set Minimum SDK

In build.gradle:

android {
  defaultConfig {
    minSdkVersion 23
  }
}

iOS Setup

1. Add Face ID Usage Description

In ios/Runner/Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>We use Face ID to verify your identity.</string>

2. Set Minimum Deployment Target

In Podfile:

platform :ios, '13.0'

Quick Start

import 'package:biometric_guard/biometric_guard.dart';

final result = await BiometricSessionManager.instance.authenticate(
  intent: AuthIntent.secure,
);

if (result.isSuccess) {
  print('Authenticated successfully');
} else if (result.isCanceled) {
  print('User cancelled');
} else if (result.isLockedOut) {
  print('Too many failed attempts');
} else {
  print(result.message);
}

BiometricGuard — Widget-Level Protection

BiometricGuard(
  intent: AuthIntent.secure,
  sessionTimeout: const Duration(minutes: 5),
  onSuccess: () => Navigator.pushNamed(context, '/home'),
  onFailure: () => _showAuthErrorDialog(context),
  child: const HomeScreen(),
)

Custom Prompt Strings

BiometricGuard(
  intent: AuthIntent.custom,
  contents: const AuthContents(
    title: 'Unlock Vault',
    subtitle: 'Use your fingerprint or face',
    description: 'Your data is protected by biometric lock',
  ),
  child: const VaultScreen(),
)

BiometricRoute — Route-Level Protection

await Navigator.push(
  context,
  BiometricRoute(
    intent: AuthIntent.payment,
    builder: (_) => const PaymentScreen(),
  ),
);

Biometric-Only Mode

BiometricRoute(
  intent: AuthIntent.payment,
  options: const AuthOptions(
    biometricOnly: true,
  ),
  builder: (_) => const PaymentScreen(),
)

Session Management API

final manager = BiometricSessionManager.instance;

// Check if session is valid
final valid = manager.isSessionValid(
  const Duration(minutes: 5),
);

// Force re-authentication
manager.invalidateSession();

// Check device support
final supported = await manager.isDeviceSupported();

// Get available biometric types
final types = await manager.getAvailableTypes();

// Cancel current prompt
await manager.cancelAuthentication();

Reactive UI with SessionStateBuilder

SessionStateBuilder(
  sessionTimeout: const Duration(minutes: 5),
  builder: (context, state) {
    return switch (state) {
      SessionActive() => const Icon(Icons.lock_open),
      SessionExpired() => const Icon(Icons.lock),
      SessionAuthenticating() => const CircularProgressIndicator(),
      SessionFailed() => const Icon(Icons.error_outline),
    };
  },
)

SessionLockIndicator

SessionLockIndicator(
  sessionTimeout: const Duration(minutes: 5),
  activeChild: const Icon(Icons.lock_open),
  lockedChild: const Icon(Icons.lock),
)

AuthIntent

AuthIntent automatically provides context-specific prompt titles.

Intent	Use Case
`AuthIntent.secure`	Login and sensitive screens
`AuthIntent.payment`	Payments and transfers
`AuthIntent.credentials`	Password managers
`AuthIntent.custom`	Fully customized prompts

AuthResult

class AuthResult {
  final AuthResultCode code;
  final String message;
  final AuthType type;
}

Convenience getters:

result.isSuccess
result.isCanceled
result.isLockedOut

Resume Authentication on Foreground

await BiometricSessionManager.instance.authenticate(
  intent: AuthIntent.secure,
  options: const AuthOptions(
    resumeOnForeground: true,
  ),
);

Useful for:

Banking apps
Healthcare apps
Enterprise applications

Testing Support

final manager = BiometricSessionManager.forTesting(
  _FakeChannel(
    AuthResult(
      code: AuthResultCode.success,
      message: 'ok',
      type: AuthType.biometric,
    ),
  ),
);

Common Errors and Fixes

Problem	Solution
`notFragmentActivity`	Use `FlutterFragmentActivity`
Face ID crash	Add `NSFaceIDUsageDescription`
`noCredentials`	Enroll biometrics or device PIN
`lockedOut`	Wait or unlock device with PIN
Prompt not appearing	Add biometric permissions
Build error	Set `minSdkVersion 23`
Pod install failure	Set iOS deployment target to 12.0

Frequently Asked Questions

Does it work with only PIN or passcode?

Yes. Device credentials are supported even when biometrics are not enrolled.

Is the session persisted across app restarts?

No. Sessions are stored in memory only.

How do I force re-authentication?

BiometricSessionManager.instance.invalidateSession();

Why does iOS sometimes return `deviceCredential`?

When biometricOnly: false, iOS may not report whether Face ID or passcode was used.

Ideal Use Cases

Banking applications
Password managers
Healthcare apps
Enterprise applications
Any app requiring secure access control

Conclusion

biometric_guard is a complete biometric authentication solution for Flutter.

It goes beyond local_auth by providing:

Session management
Widget guards
Route guards
Lifecycle-safe authentication
Reactive UI updates
Testing support

If you're building a secure Flutter application, biometric_guard can significantly reduce boilerplate and improve reliability.

Install It Today

dependencies:
  biometric_guard: ^1.0.4

Pub.dev: https://pub.dev/packages/biometric_guard

GitHub: https://github.com/shahulhameed24/biometric_guard

If this package is useful, consider giving it a ⭐ on GitHub.

Built with ❤️ by Shahul Hameed

DEV Community: Shahul Hameed