capacitor-native-biometric无法获取凭证及生物识别登录实现咨询

一、客户端生物识别登录功能实现流程 #

前置配置 #

先完成基础的安装和原生端配置：

• 安装插件：npm install @epicshaggy/capacitor-native-biometric
• 同步Capacitor原生工程：npx cap sync
• 安卓端：在AndroidManifest.xml中添加生物识别权限：

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

• iOS端：在Info.plist中添加FaceID使用说明：

  <key>NSFaceIDUsageDescription</key>
  <string>需要使用FaceID完成身份验证登录</string>
  

核心业务逻辑 #

该插件的verifyIdentity方法仅负责生物特征校验，凭证需要手动存储和读取，完整流程分为两步：

1. 首次账号密码登录成功后存储用户凭证
   只有用户第一次用账号密码登录成功后，再调用存储接口把用户识别信息存在设备本地，后续才能调用生物识别登录：

   import { NativeBiometric } from "@epicshaggy/capacitor-native-biometric";
   
   const saveBiometricCredentials = async (userId: string, biometricSecret: string) => {
     await NativeBiometric.setCredentials({
       // 填服务端可识别的用户唯一标识，比如用户ID、绑定手机号
       username: userId,
       // 可以填用户登录密码，也可以填服务端为该用户单独生成的专属随机密钥，安全性更高
       password: biometricSecret,
       // 必填参数，用于区分不同应用的存储凭证，填你应用的专属标识即可
       server: "com.your.app.biometric",
     });
   };
   

2. 后续生物识别登录逻辑
   用户下次启动App需要登录时，先做生物校验，校验通过后读取本地存储的凭证传给服务端校验即可：

   const biometricLogin = async () => {
     // 先检查设备是否支持生物识别
     const { isAvailable } = await NativeBiometric.isAvailable();
     if (!isAvailable) {
       // 不支持时直接回退到账号密码登录逻辑
       return;
     }
   
     try {
       // 触发生物特征校验
       await NativeBiometric.verifyIdentity({
         reason: "验证身份完成登录",
         title: "生物识别登录",
         subtitle: "请验证指纹或面容",
       });
   
       // 校验通过后读取本地存储的凭证
       const credentials = await NativeBiometric.getCredentials({
         server: "com.your.app.biometric",
       });
   
       // 把凭证传给服务端做校验
       const loginResponse = await fetch("/api/biometric/login", {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
         },
         body: JSON.stringify({
           userId: credentials.username,
           secret: credentials.password,
         }),
       });
   
       // 服务端校验通过后返回登录token，后续按普通登录逻辑处理即可
       const { token } = await loginResponse.json();
       localStorage.setItem("login_token", token);
     } catch (error) {
       // 校验失败、用户取消、凭证不存在时，回退到账号密码登录
       console.log("生物识别登录失败", error);
     }
   };
   

二、服务端识别用户下发token逻辑 #

• 首次账号密码登录成功后，服务端可以选择两种方案：一是直接返回用户的原始登录密码，二是为该用户生成一个专属的、和用户ID绑定的随机生物识别密钥，存在用户表中，再返回给客户端存到插件里，第二种方案不会泄露用户原始密码，安全性更高。
• 客户端生物识别校验通过后，会把用户ID和对应的密钥传给服务端的生物识别登录接口。
• 服务端接收到参数后，校验数据库中对应用户ID的生物识别密钥是否匹配，匹配通过后，和普通账号密码登录逻辑完全一致，生成对应的登录有效期token返回给客户端即可。

注意事项 #

• 如果用户在设备系统中删除、重新录入生物特征，iOS钥匙串和安卓部分机型的本地存储凭证会自动清空，此时读取凭证会失败，直接引导用户走账号密码登录，重新存储凭证即可。

内容的提问来源于stack exchange，提问作者mahen23