Skip to main content

Local Authentication

Authenticate users on-device with biometrics, PIN, passcode, or pattern using Flutter's local_auth package.

For storing secrets protected by biometrics, see SecureStorage.

Platform Support​

PlatformWindowsmacOSLinuxiOSAndroidWeb
Supported✅✅❌✅✅❌

Setup​

iOS and macOS​

Add a Face ID usage description using the biometric permission bundle or [tool.flet.ios.info] / [tool.flet.macos.info]:

[tool.flet]
permissions = ["biometric"]

Android​

USE_BIOMETRIC is declared by the local_auth plugin and merged automatically. Flet apps use FlutterFragmentActivity and AppCompat LaunchTheme / NormalTheme by default.

Usage​

Add flet-local-auth to your project dependencies:

uv add flet-local-auth

Example​

Local authentication​

import flet as ft
import flet_local_auth as auth


def main(page: ft.Page):
    status = ft.Text(theme_style=ft.TextThemeStyle.TITLE_MEDIUM)
    local_auth = auth.LocalAuthentication()

    async def refresh_capabilities(_):
        supported = await local_auth.is_device_supported()
        can_check = await local_auth.can_check_biometrics()
        biometrics = await local_auth.get_available_biometrics()
        status.value = (
            f"Device supported: {supported}\n"
            f"Biometric hardware: {can_check}\n"
            f"Enrolled biometrics: {', '.join(b.value for b in biometrics) or 'none'}"
        )

    async def authenticate(_):
        try:
            ok = await local_auth.authenticate(
                "Authenticate to continue",
                android_messages=auth.AndroidAuthMessages(
                    sign_in_title="Unlock",
                    cancel_button="Not now",
                ),
            )
            status.value = f"Authenticated: {ok}"
        except auth.LocalAuthException as e:
            status.value = f"Authentication failed: {e.code.value}"

    page.add(
        ft.SafeArea(
            content=ft.Column(
                spacing=16,
                controls=[
                    ft.Container(
                        bgcolor=ft.Colors.SURFACE_CONTAINER_HIGHEST,
                        border_radius=12,
                        padding=16,
                        content=status,
                    ),
                    ft.Button("Check capabilities", on_click=refresh_capabilities),
                    ft.Button("Authenticate", on_click=authenticate),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Description​

Authenticates the user with on-device biometrics or device credentials.

Platform support

Supported on Android, iOS, macOS, and Windows. Not supported on Linux or Web.

Raises:

Inherits: Service

Methods

Methods​

authenticateasync​

authenticate(
    reason: str,
    biometric_only: bool = False,
    sensitive_transaction: bool = True,
    persist_across_backgrounding: bool = False,
    android_messages: AndroidAuthMessages | None = None,
    ios_messages: IOSAuthMessages | None = None,
    windows_messages: WindowsAuthMessages | None = None,
) -> bool

Prompts the user to authenticate locally.

Parameters:

  • reason (str) - The message shown in the system authentication dialog.
  • biometric_only (bool, default: False) - Whether to allow only biometric authentication.
  • sensitive_transaction (bool, default: True) - Whether to treat the transaction as sensitive.
  • persist_across_backgrounding (bool, default: False) - Whether to retry after the app is foregrounded again if authentication was interrupted.
  • android_messages (AndroidAuthMessages | None, default: None) - Optional Android dialog customization.
  • ios_messages (IOSAuthMessages | None, default: None) - Optional iOS dialog customization.
  • windows_messages (WindowsAuthMessages | None, default: None) - Optional Windows dialog customization.

Returns:

  • bool - True when authentication succeeds.

Raises:

can_check_biometricsasync​

can_check_biometrics() -> bool

Returns whether the device has biometric hardware available.

get_available_biometricsasync​

get_available_biometrics() -> list[BiometricType]

Returns the biometrics currently enrolled on the device.

is_device_supportedasync​

is_device_supported() -> bool

Returns whether the device can authenticate with biometrics or credentials.

stop_authenticationasync​

stop_authentication() -> bool

Cancels any in-progress authentication prompt.

Returns:

  • bool - True if authentication was canceled successfully.