通行密钥方向

Web 功能： Web 身份验证

本指南提供高密度、以行动为导向的指导，帮助您在现代 Web 应用中实现安全、不依赖框架的通行密钥身份验证和凭证管理。

1. 通行密钥的核心前提条件

通行密钥依赖于 Web Authentication API (WebAuthn)，该 API 施加了严格的跨领域安全限制，在尝试任何实现之前必须满足这些限制：

  • 安全上下文：WebAuthn 方法（navigator.credentials.create 和 navigator.credentials.get）严格受安全上下文限制。应用必须在生产环境中的 https:// 上运行，或在本地开发环境中的 http://localhost 上运行。
  • 依赖方 (RP) ID：每个凭证都与一个 RP ID（本质上是应用的域名）相关联。在服务器端选项中传递的 RP ID 必须与当前来源的域名匹配，或者是当前来源域名的有效后缀（例如，example.com 对 login.example.com 有效）。不匹配会导致客户端出现 SecurityError 异常。

2. AAGUID 用户体验注意事项

Authenticator Attestation Globally Unique Identifier (AAGUID) 是注册认证数据中返回的 128 位唯一标识符，用于表示身份验证器的型号/提供商（例如 Google 密码管理工具、iCloud 钥匙串、1Password）。

  • 仅限用户体验提示：依赖方必须仅将 AAGUID 用于用户体验提示（例如在管理列表中呈现通行密钥提供商名称和图标，以帮助用户）。
  • 无安全依赖项：应用不得将 AAGUID 用于加密安全或访问决策。平台通行密钥目前不为其 AAGUID 提供加密认证，这意味着 AAGUID 可能会被用户代理更改或模拟。

3. 解耦库建议

对于后端 FIDO2/WebAuthn 选项生成和签名验证，开发者必须依赖于每种语言经过审核的开源库，而不是手动编写加密代码：

  • JavaScript/TypeScript：SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
  • Python：py_webauthn (github.com/duo-labs/py_webauthn)
  • Java：Java WebAuthn Server (github.com/Yubico/java-webauthn-server)、WebAuthn4J (github.com/webauthn4j/webauthn4j)
  • .NET：适用于 FIDO2 的 .NET 库 (github.com/abergs/fido2-net-lib)
  • Go：WebAuthn Go 库 (github.com/go-webauthn/webauthn)
  • Ruby：WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
  • PHP：WebAuthn 框架 (github.com/web-auth/webauthn-framework)

4. 应用场景参考矩阵

请在下方找到匹配的使用场景，并获取其完整的实现指南。每个用例都有关键 API（PublicKeyCredential.parseCreationOptionsFromJSON、parseRequestOptionsFromJSON、signalAllAcceptedCredentials、signalCurrentUserDetails、signalUnknownCredential、条件中介、AAGUID 处理等），这些 API 仅在每个用例的指南中进行了说明。请勿跳过此检索步骤，也不要在客户端上替换第三方库封装容器（例如 SimpleWebAuthn 的 startAuthentication/startRegistration），而是直接调用原生 WebAuthn 浏览器 API。第 3 部分中的库建议仅适用于服务器端（后端 FIDO2 验证）。

具体的通行密钥和 WebAuthn 实现细节已映射到以下指南：