WebAuthn集成问题：如何仅启用指纹验证并排除PIN选项？

问题原因分析 #

你设置authenticatorSelection.authenticatorAttachment: "cross-platform"报错，是因为这款USB指纹识别器被Windows Hello识别为平台认证器（platform authenticator），而非跨平台安全密钥（比如独立的YubiKey）。cross-platform会过滤掉平台认证器，导致设备无法被识别。

正确配置步骤 #

要仅显示指纹验证选项，需从用户验证规则和允许的验证方式两个维度调整WebAuthn参数：

1. 调整认证器类型过滤
   移除authenticatorAttachment: "cross-platform"配置，或者显式设置为"platform"，确保你的指纹设备不会被过滤：

   authenticatorSelection: {
     authenticatorAttachment: "platform"
   }
   

2. 强制用户验证并指定生物识别方式
   通过userVerification和uvm扩展，限定仅使用指纹（生物识别）作为验证手段：

   • userVerification: "required"：确保设备必须执行用户验证，跳过无验证流程
   • extensions: { uvm: ["biometric"] }：指定仅允许生物识别类验证方式，直接排除PIN选项

完整配置示例 #

注册凭证时的配置

const publicKeyCreationOpts = {
  rp: { name: "你的Web应用名称" },
  user: {
    id: Uint8Array.from(Buffer.from("用户唯一标识ID", "utf8")),
    name: "user@example.com",
    displayName: "用户名"
  },
  challenge: Uint8Array.from(Buffer.from("随机生成的挑战字符串", "utf8")),
  pubKeyCredParams: [{ type: "public-key", alg: -7 }], // ES256算法，兼容多数设备
  authenticatorSelection: {
    userVerification: "required",
    authenticatorAttachment: "platform"
  },
  extensions: {
    uvm: ["biometric"]
  },
  timeout: 60000
};

// 调用注册API
navigator.credentials.create({ publicKey: publicKeyCreationOpts });

认证时的配置

const publicKeyRequestOpts = {
  challenge: Uint8Array.from(Buffer.from("随机生成的挑战字符串", "utf8")),
  allowCredentials: [/* 填入之前注册的凭证ID对象 */],
  userVerification: "required",
  extensions: {
    uvm: ["biometric"]
  },
  timeout: 60000
};

// 调用认证API
navigator.credentials.get({ publicKey: publicKeyRequestOpts });

额外注意事项 #

• 主流浏览器（Chrome、Edge）对uvm扩展支持较好，若仍出现PIN选项，可检查Windows Hello设置：确保该指纹设备的验证方式仅启用指纹，禁用PIN（此操作是系统层面设置，会影响该设备在其他应用的使用）。
• 确认设备已在Windows Hello中完成指纹注册，且系统允许生物识别验证。

内容的提问来源于stack exchange，提问作者Răzvan Puștea