Introduction

Biometric authentication (Face ID & Touch ID) offers a seamless and highly secure method to protect sensitive operations within mobile applications. Flutter’s local_auth plugin provides a unified API layer over native biometric frameworks—Android’s BiometricPrompt and iOS’s LocalAuthentication. In this tutorial, we’ll guide you through environment setup, permission configurations, implementation details, and robust error handling strategies. By the end, you’ll be equipped to secure login flows, payment approvals, or any private data access directly in your Flutter app.

Prerequisites

Before you begin, verify your development environment meets these requirements:

• Flutter 2.0+ with Dart null safety enabled.

• Xcode 11.0+ for iOS builds and a physical iOS device or simulator supporting Face ID.

• Android Studio or VS Code with the Android SDK; test on an emulator with fingerprint emulation or on a real Android device.

• CocoaPods installed for iOS dependency management (sudo gem install cocoapods). • Basic understanding of Flutter widgets, asynchronous programming, and pubspec.yaml configuration.

Run flutter doctor to confirm there are no outstanding issues. For iOS, navigate to the ios folder and run pod install. On Android, ensure adb recognizes your test device or emulator. Address any build errors before moving forward.

Configuring the local_auth plugin

Add the local_auth dependency in pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  local_auth

Install packages with:

flutter pub get
cd ios && pod install

Android Setup (android/app/src/main/AndroidManifest.xml):

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

Set minSdkVersion to 23+ in android/app/build.gradle.

iOS Setup (ios/Runner/Info.plist):

<key>NSFaceIDUsageDescription</key>
<string>Access Face ID to secure your data.</string

Rebuild your app with flutter run. If you encounter plugin registration errors, run flutter clean and rebuild. Verify local_auth is detected by checking flutter pub deps.

Implementing Biometric Authentication

Start by importing and instantiating the API:

import 'package:local_auth/local_auth.dart';

final LocalAuthentication auth = LocalAuthentication();

Check device compatibility and enrollment:

Future<bool> hasBiometrics() async {
  bool supported = await auth.isDeviceSupported();
  bool enrolled = (await auth.getAvailableBiometrics()).isNotEmpty;
  return supported && enrolled;
}

Trigger biometric authentication in your UI:

ElevatedButton(
  onPressed: () async {
    if (await hasBiometrics()) {
      bool success = await auth.authenticate(
        localizedReason: 'Authenticate to access sensitive feature',
        options: const AuthenticationOptions(
          biometricOnly: true,
          useErrorDialogs: true,
          stickyAuth: false,
        ),
      );
      if (success) {
        // Grant access or navigate
      }
    } else {
      // Offer PIN/password fallback
    }
  },
  child: Text('Unlock Secure Content'),
)

Use useErrorDialogs to let the system display default error messages. stickyAuth can keep the auth session alive if the app backgrounds.

Error Handling & Fallbacks

Biometric flows may fail due to sensor errors, cancellations, or lockouts. Wrap calls in try/catch to examine PlatformException.code values: • NotAvailable: No hardware present. • NotEnrolled: User has no biometrics enrolled. • LockedOut: Too many failed attempts; requires device PIN unlock.

Example with granular handling:

try {
  bool authenticated = await auth.authenticate(
    localizedReason: 'Verify your identity',
    options: const AuthenticationOptions(biometricOnly: true),
  );
  if (!authenticated) {
    // Prompt for passcode dialog
  }
} on PlatformException catch (e) {
  switch (e.code) {
    case 'NotEnrolled':
      // Guide user to device settings
      break;
    case 'LockedOut':
      // Force PIN-based login
      break;
    default:
      // General fallback
  }
}

Always provide a secure fallback like a PIN or password to ensure accessibility and avoid locking out legitimate users.

Vibe Studio

Vibe Studio, powered by Steve’s advanced AI agents, is a revolutionary no-code, conversational platform that empowers users to quickly and efficiently create full-stack Flutter applications integrated seamlessly with Firebase backend services. Ideal for solo founders, startups, and agile engineering teams, Vibe Studio allows users to visually manage and deploy Flutter apps, greatly accelerating the development process. The intuitive conversational interface simplifies complex development tasks, making app creation accessible even for non-coders.

Conclusion

Implementing biometric authentication in Flutter using the local_auth plugin significantly enhances both security and user convenience. You’ve learned how to configure platform-specific permissions, detect biometric capabilities, invoke authentication prompts, and handle common errors with robust fallbacks. Next, consider integrating secure storage solutions (like flutter_secure_storage) to save tokens post-authentication. Additionally, test across OS versions to handle subtle API differences and provide consistent UX. For advanced scenarios, you can customize authentication prompts or chain biometrics with server-side checks.