文章目录生物认证能力概览权限与配置指纹认证人脸认证认证结果处理降级方案密码兜底写在最后生物认证能力概览你有没有这种感觉——每次输密码都像在受刑6 位数字密码要输半天手势密码画错了还得重来关键是旁边有人看的时候还不安全。指纹一按、脸一扫2 秒搞定认证体验根本不在一个量级。HarmonyOS7 把生物认证做成了系统能力用UserAuthenticationKit统一封装了指纹、人脸、锁屏密码三种认证方式。不需要自己画 UI不需要对接各种传感器调个接口就完事。今天就来聊聊怎么把生物认证接到你的 App 里。HarmonyOS7 的生物认证体系长这样认证方式安全等级典型场景用户体验2D 人脸ATL1-ATL2设备解锁、个性化推荐快但安全性一般3D 人脸ATL3-ATL4支付验证、高安全登录快且安全指纹ATL3应用登录、敏感操作快需物理接触|锁屏密码| ATL3-ATL4 | 生物认证失败兜底 | 慢但最可靠 |划重点认证可信等级ATL从 1 到 4 递增。ATL1 最松ATL4 最严。支付场景至少要 ATL3登录场景 ATL2 就够。权限与配置用生物认证之前权限得先配上。在module.json5里加{requestPermissions:[{name:ohos.permission.ACCESS_BIOMETRIC,reason:$string:biometric_reason,usedScene:{abilities:[EntryAbility],when:inuse}}]}ohos.permission.ACCESS_BIOMETRIC—— 生物认证专用权限必须申请reason—— 给用户看的权限说明写清楚为什么需要还需要确保设备已经录入了指纹/人脸凭据没录入的话认证会直接报错指纹认证先看最常用的指纹认证import{userAuth}fromkit.UserAuthenticationKit;import{cryptoFramework}fromkit.CryptoArchitectureKit;import{BusinessError}fromkit.BasicServicesKit;EntryComponentstruct FingerprintAuthDemo{StateauthResult:string等待认证;startFingerprintAuth(){try{// 1. 生成随机 challenge 值constrandcryptoFramework.createRandom();constrandDatarand.generateRandomSync(16).data;// 2. 构建认证参数constauthParam:userAuth.AuthParam{challenge:randData,authType:[userAuth.UserAuthType.FINGERPRINT],// 指纹认证authTrustLevel:userAuth.AuthTrustLevel.ATL3,// 要求 ATL3};// 3. 配置认证控件 UIconstwidgetParam:userAuth.WidgetParam{title:请验证指纹,};// 4. 获取认证实例constauthInstanceuserAuth.getUserAuthInstance(authParam,widgetParam);// 5. 注册认证结果回调authInstance.on(result,{onResult(result:userAuth.UserAuthResult){switch(result.result){caseuserAuth.UserAuthResultCode.SUCCESS:console.info(指纹认证成功);// result.authType 可以知道具体用了哪种认证方式// result.token 包含认证令牌break;caseuserAuth.UserAuthResultCode.CANCELED:console.info(用户取消认证);break;default:console.error(认证失败:${result.result});}authInstance.off(result);// 别忘了取消订阅}});// 6. 启动认证authInstance.start();}catch(error){consterrerrorasBusinessError;console.error(认证异常:${err.code}-${err.message});}}build(){Column(){Text(this.authResult).fontSize(20).margin({bottom:20})Button(指纹认证).onClick(()this.startFingerprintAuth())}}}关键代码讲解challenge—— 随机挑战值防重放攻击。每次认证生成不同的随机数确保上次的认证结果不能被重复使用authType: [userAuth.UserAuthType.FINGERPRINT]—— 指定只用指纹也支持传数组指定多种方式authTrustLevel: ATL3—— 期望的最低安全等级2D 人脸达不到 ATL3 会被自动跳过widgetParam.title—— 认证弹窗的标题文字系统自带 UI 控件不能自定义界面authInstance.start()—— 启动认证后系统会弹出指纹识别界面认证结束必须调authInstance.off(result)—— 不然会内存泄漏认证失败不会触发result回调只有成功和取消才会。中间过程的失败比如手指放歪只体现在系统 UI 上不回传给应用。这个设计很多人搞不清楚。人脸认证人脸认证跟指纹的套路一模一样就改个authTypestartFaceAuth(){try{constrandcryptoFramework.createRandom();constrandDatarand.generateRandomSync(16).data;constauthParam:userAuth.AuthParam{challenge:randData,authType:[userAuth.UserAuthType.FACE_RECOGNITION],// 人脸认证authTrustLevel:userAuth.AuthTrustLevel.ATL3,};constwidgetParam:userAuth.WidgetParam{title:请进行人脸识别,};constauthInstanceuserAuth.getUserAuthInstance(authParam,widgetParam);authInstance.on(result,{onResult(result:userAuth.UserAuthResult){if(result.resultuserAuth.UserAuthResultCode.SUCCESS){console.info(人脸认证成功);}authInstance.off(result);}});authInstance.start();}catch(error){console.error(人脸认证异常:${(errorasBusinessError).message});}}跟指纹唯一的区别就是authType换成了FACE_RECOGNITION。系统会根据authTrustLevel自动选择 2D 还是 3D 人脸——要求 ATL3 以上就用 3D。更实用的做法是组合认证constauthParam:userAuth.AuthParam{challenge:randData,authType:[userAuth.UserAuthType.FINGERPRINT,userAuth.UserAuthType.FACE_RECOGNITION,userAuth.UserAuthType.PIN// 锁屏密码作为兜底],authTrustLevel:userAuth.AuthTrustLevel.ATL3,};传三种authType系统会按设备支持的类型依次弹出——有指纹弹指纹没有就弹人脸都没有就弹密码输入。用户自己选体验最好。认证结果处理认证回调的result.result是个状态码完整含义如下状态码值含义处理方式SUCCESS12500000认证成功放行操作取 token 提交业务CANCELED12500002用户主动取消回到认证前状态不报错FAIL12500001认证失败引导重试或降级LOCKED12500007认证锁定提示等待解锁或用密码NOT_ENROLLED12500009未录入凭据引导去系统设置录入TIMEOUT12500010认证超时提示重试重点说三个SUCCESS—— 成功后result.token里是 AuthToken传给后端验证身份NOT_ENROLLED—— 设备没录入指纹/人脸这个要提前检查别等用户点了才报错CANCELED—— 用户取消是正常行为别弹错误提示提前检查凭据是否可用asynccheckAuthAvailability():Promiseboolean{try{constresultawaituserAuth.getAvailableStatus(userAuth.UserAuthType.FINGERPRINT,userAuth.AuthTrustLevel.ATL3);returnresultuserAuth.UserAuth.AvailableStatus.AVAILABLE;}catch{returnfalse;// 没有指纹或安全等级不够}}降级方案密码兜底生物认证不是万能的——手指湿了指纹不灵、戴口罩人脸识别不了、设备根本没指纹传感器。必须要有降级方案。我的做法是生物认证 → 失败 → 密码输入 → 还是失败 → 限制操作。StateauthStep:idle|biometric|passwordidle;asyncstartAuth(){// 1. 先检查设备是否支持生物认证constavailableawaitthis.checkAuthAvailability();if(available){this.authStepbiometric;this.startBiometricAuth();}else{// 直接走密码this.authSteppassword;this.showPasswordDialog();}}onBiometricFail(){// 生物认证失败降级到密码this.authSteppassword;this.showPasswordDialog();}showPasswordDialog(){// 弹出密码输入弹窗promptAction.showDialog({title:请输入密码,message:生物认证不可用请输入登录密码验证身份,buttons:[{text:取消,color:#999999},{text:确认,color:#007aff}]});}千万别只做生物认证不做密码兜底。不然用户的指纹传感器坏了你的 App 就成了一块砖。写在最后生物认证接入真的不难核心就五步申请ACCESS_BIOMETRIC权限生成challenge随机值构建AuthParam指定认证类型和等级注册result回调处理结果调start()启动认证最容易忘的两件事提前检查凭据是否可用和密码兜底方案。这两点做好了生物认证就是加分项做不好就是用户骂你的理由。有问题欢迎评论区交流。