DEV Community

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

Posted on

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

#flutter #dart #security #opensource

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
Enter fullscreen mode Exit fullscreen mode

Then run:

flutter pub get
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode

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" />
Enter fullscreen mode Exit fullscreen mode

3. Set Minimum SDK

In build.gradle:

android {
  defaultConfig {
    minSdkVersion 23
  }
}
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

2. Set Minimum Deployment Target

In Podfile:

platform :ios, '13.0'
Enter fullscreen mode Exit fullscreen mode

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);
}
Enter fullscreen mode Exit fullscreen mode

BiometricGuard — Widget-Level Protection 

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

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(),
)
Enter fullscreen mode Exit fullscreen mode

BiometricRoute — Route-Level Protection 

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

Biometric-Only Mode 

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

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();
Enter fullscreen mode Exit fullscreen mode

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),
    };
  },
)
Enter fullscreen mode Exit fullscreen mode

SessionLockIndicator 

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

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;
}
Enter fullscreen mode Exit fullscreen mode

Convenience getters:

result.isSuccess
result.isCanceled
result.isLockedOut
Enter fullscreen mode Exit fullscreen mode

Resume Authentication on Foreground 

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

Useful for:

  • Banking apps
  • Healthcare apps
  • Enterprise applications

Testing Support 

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

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();
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)