Flet 本地认证实战：用 flet-local-auth 为 Python 应用集成生物识别与设备凭证认证

前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载flet-local-auth是 Flet 官方的本地认证服务扩展包它通过 Flutter 的local_auth插件让纯 Python 编写的 Flet 应用能够直接在用户设备上发起生物识别指纹、人脸、虹膜或 PIN、密码、图案等设备凭证认证无需任何前端经验。读完本文你将掌握如何安装配置该服务、调用能力检测与认证 API、定制各平台认证对话框文案以及如何解析认证失败的错误码并正确处理异常。服务概览与平台支持LocalAuthentication是 Flet 服务体系Service中的一个控制类核心定位是在设备本地完成身份认证不涉及任何服务器或第三方服务。它适合用于解锁应用内敏感功能、确认支付操作等场景如果需要存储受生物识别保护的密钥等机密数据官方文档建议配合SecureStorage使用。从源码可以看出该服务由 Python 端封装、Flutter 端桥接两层构成Python 端LocalAuthentication 类 继承自flet.controls.services.service.Service通过control(LocalAuthentication)注册为 Flet 控制所有认证逻辑均以_invoke_method异步调用方式下发到客户端。Flutter 端LocalAuthenticationService 在 Dart 侧实例化LocalAuthentication插件对象并通过control.addInvokeMethodListener监听 Python 端发来的方法调用由 extension.dart 中的Extension.createService按控制类型LocalAuthentication完成服务创建与分发。平台支持矩阵根据官方文档 LocalAuthentication 与源码注释local_auth.py中明确声明 Not supported on Linux or Web平台WindowsmacOSLinuxiOSAndroidWeb支持情况✅✅❌✅✅❌需要特别注意的是LocalAuthentication.before_update中会在page.web为真或平台为ft.PagePlatform.LINUX时主动抛出FletUnsupportedPlatformException提示 LocalAuthentication is not supported on Linux or Web platforms因此在不支持的平台上应用会直接报错而非静默失败。安装与平台配置添加依赖flet-local-auth已发布为独立的 Python 包其 pyproject.toml 中requires-python 3.10运行时依赖仅有flet。安装方式有两种# 方式一使用 uv uv add flet-local-auth # 方式二使用 pip pip install flet-local-auth注意使用pip install后需要手动将该包加入项目的requirements.txt或pyproject.toml以保证依赖可复现。iOS / macOS声明 Face ID 权限在 iOS 与 macOS 上使用生物识别必须在应用描述中声明 Face ID 用途说明。官方文档推荐使用 Flet 预置的跨平台权限包biometric在项目的pyproject.toml中写入[tool.flet] permissions [biometric]也可以改用[tool.flet.ios.info]/[tool.flet.macos.info]显式写入用途描述字符串。官方示例 extensions/local_auth 的 pyproject.toml 正是采用permissions [biometric]的写法并声明了platforms [ios, android, windows, macos]。Android自动合并权限USE_BIOMETRIC权限由local_auth插件自动声明并合并到最终 APK无需在 Flet 端手工配置。Flet 应用默认使用FlutterFragmentActivity以及 AppCompat 的LaunchTheme/NormalTheme与插件要求兼容。核心 API 详解LocalAuthentication的所有方法都是async异步方法必须配合 Flet 的异步事件处理器使用。完整的 API 定义见 local_auth.py。设备能力检测在发起认证前建议先探测设备能力以便在不同设备上优雅降级async def check_capabilities(local_auth): supported await local_auth.is_device_supported() # 设备是否支持认证 can_check await local_auth.can_check_biometrics() # 是否有可用生物识别硬件 biometrics await local_auth.get_available_biometrics() # 已录入的生物识别类型列表 print(supported, can_check, [b.value for b in biometrics])is_device_supported()返回布尔值表示设备是否能进行生物识别或凭证认证对应 Flutter 端isDeviceSupported()。can_check_biometrics()返回设备是否存在可用生物识别硬件对应canCheckBiometrics。get_available_biometrics()返回当前设备上已录入的生物识别类型列表元素为BiometricType枚举。发起认证authenticate()是核心方法签名与默认值如下见 local_auth.pyasync def authenticate( self, reason: str, *, biometric_only: bool False, sensitive_transaction: bool True, persist_across_backgrounding: bool False, android_messages: Optional[AndroidAuthMessages] None, ios_messages: Optional[IOSAuthMessages] None, windows_messages: Optional[WindowsAuthMessages] None, ) - bool:参数类型默认值含义reasonstr必填系统认证对话框中展示给用户的提示文案biometric_onlyboolFalse是否只允许生物识别为True时禁用 PIN/密码等凭证回退sensitive_transactionboolTrue是否将本次认证视为敏感交易影响系统安全策略persist_across_backgroundingboolFalse认证过程中若应用被切到后台回到前台时是否自动重试android_messagesAndroidAuthMessagesNoneAndroid 对话框文案定制ios_messagesIOSAuthMessagesNoneiOS 对话框文案定制windows_messagesWindowsAuthMessagesNoneWindows 对话框文案定制当前为占位返回值认证成功返回True认证失败或被用户取消时抛出LocalAuthException。取消认证cancelled await local_auth.stop_authentication() # 返回 True 表示成功取消stop_authentication()用于取消正在进行的认证提示对应 Flutter 端stopAuthentication()。完整示例能力检测 认证仓库中的官方示例 extensions/local_auth/local_auth/main.py 演示了完整用法核心逻辑如下import flet as ft import flet_local_auth as auth def main(page: ft.Page): status ft.Text(theme_styleft.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 ( fDevice supported: {supported}\n fBiometric hardware: {can_check}\n fEnrolled biometrics: {, .join(b.value for b in biometrics) or none} ) async def authenticate(_): try: ok await local_auth.authenticate( Authenticate to continue, android_messagesauth.AndroidAuthMessages( sign_in_titleUnlock, cancel_buttonNot now, ), ) status.value fAuthenticated: {ok} except auth.LocalAuthException as e: status.value fAuthentication failed: {e.code.value} page.add( ft.SafeArea( contentft.Column( spacing16, controls[ ft.Container( bgcolorft.Colors.SURFACE_CONTAINER_HIGHEST, border_radius12, padding16, contentstatus, ), ft.Button(Check capabilities, on_clickrefresh_capabilities), ft.Button(Authenticate, on_clickauthenticate), ], ), ) ) if __name__ __main__: ft.run(main)运行方式与普通 Flet 应用一致python main.py该示例使用SafeAreaColumnButtonText组织了一个检查能力 / 发起认证的极简界面其中两个回调均为async函数这是调用所有LocalAuthenticationAPI 的前提。对话框文案定制不同平台的系统认证对话框文案可以通过消息类定制这些类均以ft.value标记是 Flet 的值类型AndroidAuthMessages定义于 types.py字段类型默认值含义sign_in_hintstr?None登录提示文案cancel_buttonstr?None取消按钮文案sign_in_titlestr?None登录标题文案IOSAuthMessages字段类型默认值含义cancel_buttonstr?None取消按钮文案localized_fallback_titlestr?None本地化的回退标题文案WindowsAuthMessages当前为占位类types.py因为local_auth3.x 尚未开放 Windows 端对话框字符串的定制接口。在 Flutter 端utils/local_auth.dart 的parseWindowsAuthMessages收到参数时也只返回const WindowsAuthMessages()不读取任何字段。值得一提的是Flutter 端在解析认证消息时遵循未传即用默认值的合并策略parseAuthMessages只有当三个平台消息都为None时才整体使用默认消息列表否则逐平台用传入值替换对应默认项。这意味着你可以在一次调用中只定制 Android 文案iOS 与 Windows 仍使用系统默认文案。错误码与异常处理认证失败时Python 端会抛出LocalAuthException继承自ft.FletException其内部包含codeLocalAuthErrorCode枚举与可选的description字段str(异常)优先展示 description缺省时回退为错误码字符串。完整的错误码枚举定义见 types.py错误码值典型含义AUTH_IN_PROGRESSauthInProgress已有认证正在进行UI_UNAVAILABLEuiUnavailable认证界面当前不可用USER_CANCELEDuserCanceled用户主动取消认证TIMEOUTtimeout认证超时SYSTEM_CANCELEDsystemCanceled系统取消认证如来电打断NO_CREDENTIALS_SETnoCredentialsSet设备未设置任何凭证NO_BIOMETRICS_ENROLLEDnoBiometricsEnrolled未录入生物识别信息NO_BIOMETRIC_HARDWAREnoBiometricHardware设备无生物识别硬件BIOMETRIC_HARDWARE_TEMPORARILY_UNAVAILABLEbiometricHardwareTemporarilyUnavailable生物识别硬件暂时不可用TEMPORARY_LOCKOUTtemporaryLockout临时锁定BIOMETRIC_LOCKOUTbiometricLockout生物识别被锁定多次失败USER_REQUESTED_FALLBACKuserRequestedFallback用户请求回退到凭证认证DEVICE_ERRORdeviceError设备级错误UNKNOWN_ERRORunknownError未知错误推荐的异常处理模式如下try: ok await local_auth.authenticate(请验证身份以继续) if ok: # 解锁受保护功能 pass except auth.LocalAuthException as e: if e.code auth.LocalAuthErrorCode.USER_CANCELED: # 用户取消静默处理 pass elif e.code auth.LocalAuthErrorCode.BIOMETRIC_LOCKOUT: # 提示用户稍后重试或使用 PIN 回退 pass else: print(f认证失败{e.description or e.code.value})错误映射的底层实现错误从 Flutter 插件传递回 Python 端的链路值得关注Flutter 端在authenticate分支捕获LocalAuthException通过 utils/local_auth.dart 的localAuthErrorMap将其转换为{error_code: ..., error_description: ...}字典返回Python 端_raise_for_errorlocal_auth.py收到含error_code键的字典后将字符串映射回LocalAuthErrorCode枚举若遇到无法识别的值则回退为LocalAuthErrorCode.UNKNOWN_ERROR并抛出LocalAuthException。Flutter 端配套的 enum_mapping_test.dart 对上述映射逻辑做了单元验证测试逐一断言所有BiometricType与LocalAuthExceptionCode的名称映射正确并验证未知错误码回退到unknownError的兜底行为保证了前后端枚举的一致性。服务调用链路小结将整个过程串起来一次认证的完整链路为Python 侧创建LocalAuthentication()控制并调用await authenticate(...)_invoke_method将方法名与参数reason、biometric_only等编码后发送给 Flutter 客户端Flutter 端LocalAuthenticationService._invokeMethod的switch分支匹配到authenticate调用插件对象的authenticate见 local_auth.dart系统弹出认证对话框用户在设备上完成指纹 / 人脸 / PIN 等操作成功则返回True失败则经localAuthErrorMap转为错误字典回传Python 端最终抛出LocalAuthException供业务代码捕获。基于这条链路开发者可以确信flet-local-auth是一个完整可用的端到端本地认证方案无需搭建后端、无需处理平台原生代码只需在 Python 侧按异步方式调用即可非常适合为 Flet 桌面与移动应用快速接入设备级身份验证能力。赞分享前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载相关推荐Flet BiometricType 详解识别设备可用生物识别能力与本地认证实践Flet BiometricType 详解识别设备可用生物识别能力与本地认证实践 本篇技术指南围绕 Flet flet local auth 扩展中的 Bio前端跨平台桌面应用移动开发Flet LocalAuthentication 服务指南用 Python 在 iOS、Android、macOS 与 Windows 上实现生物识别与设备凭据认证Flet LocalAuthentication 服务指南用 Python 在 iOS、Android、macOS 与 Windows 上实现生物识别与设备凭前端跨平台桌面应用移动开发Flet 本地认证 AndroidAuthMessages 详解定制 Android 生物识别认证对话框文案Flet 本地认证 AndroidAuthMessages 详解定制 Android 生物识别认证对话框文案 在 Flet 的本地认证Local Authe前端跨平台桌面应用移动开发上一篇TypeGraphQL输入类型继承复用输入结构的技巧下一篇终极Binance Spot API调用教程使用binance-api-postman实现交易自动化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考