How to Add Biometric Authentication in FlutterFlow

Open the Custom Code panel (</> icon in the left sidebar). Click the 'pubspec.yaml' tab at the top of the panel. Under the 'dependencies' section, add a new line: 'local_auth: ^2.2.0'. After typing the dependency, tap the 'Get Packages' button and wait for the success message. This installs the local_auth package into your FlutterFlow project's build environment. The local_auth package is maintained by the Flutter team and supports fingerprint, Face ID, and iris authentication on both iOS and Android. Do not proceed to write Custom Actions until Get Packages completes successfully.

In the Custom Code panel, open the 'Custom Actions' tab and tap '+' to create a new action. Name it 'checkBiometrics'. This action will check whether the device supports biometrics and which types are available — it does not authenticate yet. Add no parameters. Set the return type to 'Boolean'. In the code editor, write the logic that instantiates LocalAuthentication, calls canCheckBiometrics, and calls getAvailableBiometrics() to get the list. Return true only if biometrics are both supported and enrolled. Tap Compile and confirm no errors. This step is critical — calling authenticate() on a device with no enrolled biometrics throws an error, so you must always check first.

1import 'package:local_auth/local_auth.dart';
2
3Future<bool> checkBiometrics() async {
4  final LocalAuthentication auth = LocalAuthentication();
5  try {
6    final bool canCheck = await auth.canCheckBiometrics;
7    if (!canCheck) return false;
8    final List<BiometricType> available =
9        await auth.getAvailableBiometrics();
10    return available.isNotEmpty;
11  } catch (e) {
12    debugPrint('checkBiometrics error: $e');
13    return false;
14  }
15}

Still in the Custom Actions tab, tap '+' to create a second action named 'authenticateWithBiometrics'. This action performs the actual biometric prompt. Add one String parameter named 'reason' — this is the message shown to the user in the system biometric dialog (e.g., 'Verify your identity to continue'). Set the return type to Boolean. Write the Dart body that calls auth.authenticate() with the localizedReason, stickyAuth set to true (keeps the prompt alive if the user switches apps briefly), and biometricOnly set to true (disables PIN/password fallback if you want pure biometric-only). Return the result directly. Tap Compile.

1import 'package:local_auth/local_auth.dart';
2import 'package:local_auth/error_codes.dart' as auth_error;
3import 'package:flutter/services.dart';
4
5Future<bool> authenticateWithBiometrics(String reason) async {
6  final LocalAuthentication auth = LocalAuthentication();
7  try {
8    return await auth.authenticate(
9      localizedReason: reason,
10      options: const AuthenticationOptions(
11        stickyAuth: true,
12        biometricOnly: false, // false = allow PIN fallback
13        useErrorDialogs: true,
14      ),
15    );
16  } on PlatformException catch (e) {
17    if (e.code == auth_error.notEnrolled) {
18      debugPrint('No biometrics enrolled on this device.');
19    } else if (e.code == auth_error.lockedOut) {
20      debugPrint('Biometrics locked out — too many failed attempts.');
21    } else {
22      debugPrint('authenticateWithBiometrics error: ${e.code} ${e.message}');
23    }
24    return false;
25  }
26}

Biometric APIs require platform-level permissions that must be declared in the iOS Info.plist and AndroidManifest.xml. In FlutterFlow, go to Settings (gear icon) → App Details → Permissions. Enable the 'Face ID Usage' permission for iOS — this adds the NSFaceIDUsageDescription key to Info.plist automatically. For Android, the local_auth package's own AndroidManifest additions are usually handled automatically when you add the package. If you are using Code Export (Pro plan), verify that android/app/src/main/AndroidManifest.xml contains the USE_BIOMETRIC and USE_FINGERPRINT permissions, and that ios/Runner/Info.plist contains NSFaceIDUsageDescription with a user-visible string.

Navigate to your Login page and find the Login button. Open its Action Flow editor. You should already have a 'Log In' action (Firebase Auth) as the first step. After the Log In action, add a conditional: tap '+' → 'Conditional Action' → set the condition to check the current user's 'biometricEnabled' Firestore field. In the TRUE branch, add a 'Custom Action' step and choose 'checkBiometrics'. After checkBiometrics, add another conditional checking its output (true/false). In the TRUE branch of that, add 'Custom Action' → 'authenticateWithBiometrics', set the reason parameter to 'Verify your identity to sign in'. Add a final conditional on the auth result — TRUE branch navigates to the home screen, FALSE branch shows a Snackbar error and signs the user out via the Sign Out action.

Biometric authentication does not work in the FlutterFlow canvas preview or in iOS Simulator / Android emulators without special configuration. Tap 'Run' in the FlutterFlow toolbar to build and run the app on a connected physical device. On iOS, connect your iPhone via USB and select it as the run target. On Android, enable Developer Mode and USB Debugging in phone settings then connect via USB. Go through the login flow: sign in with a test account that has biometricEnabled set to true in Firestore. The system biometric dialog should appear. Test both success (valid fingerprint/face) and failure (cancel or wrong finger) paths to verify the Action Flow branches work correctly.