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.

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

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