我的技术分享

Appearance

WebAuthn API 完整对照表 ​

本文档提供 WebAuthn/Passkeys 开发中所有 API、参数、属性值的完整对照表，方便开发者快速查找和参考。

目录 ​

  1. 注册 API 对照表
  2. 登录 API 对照表
  3. 类型定义对照表
  4. 错误码对照表
  5. 算法标识符对照表
  6. 传输方式对照表
  7. 扩展功能对照表

注册 API 对照表 ​

generateRegistrationOptions() 参数 ​

参数类型必填默认值说明示例值
rpNamestring✅-依赖方名称（用户可见）"我的应用"
rpIDstring✅-依赖方 ID（域名）"example.com"
userIDUint8Array✅-用户唯一标识（二进制）Buffer.from("user-123", "utf8")
userNamestring✅-用户名"user@example.com"
userDisplayNamestring❌""用户显示名称"张三"
challengestring | Uint8Array❌自动生成防重放挑战"random-challenge-string"
timeoutnumber❌60000超时时间（毫秒）120000
attestationTypeAttestationType❌"none"证明类型"none"
excludeCredentialsCredentialDescriptor[]❌[]排除的凭据列表[{id, type, transports}]
authenticatorSelectionAuthenticatorSelectionCriteria❌{}认证器选择条件{residentKey: "required"}
extensionsAuthenticationExtensionsClientInputs❌{}扩展功能配置{credProps: true}
supportedAlgorithmIDsnumber[]❌[-8, -7, -257]支持的算法 ID 列表[-7, -257]

verifyRegistrationResponse() 参数 ​

参数类型必填说明示例值
responseRegistrationResponseJSON✅前端返回的注册响应{id, rawId, type, response}
expectedChallengestring✅期望的挑战值"expected-challenge"
expectedOriginstring✅期望的来源"https://example.com"
expectedRPIDstring✅期望的 RP ID"example.com"
requireUserVerificationboolean❌是否要求用户验证true

注册响应结构 ​

字段类型说明示例值
idstring凭据 ID（字符串形式）"credential-id-string"
rawIdstring凭据 ID（Base64URL 编码）"Y3JlZGVudGlhbC1pZA"
typestring凭据类型"public-key"
response.clientDataJSONstring客户端数据（Base64URL 编码）"eyJ0eXBlIjoi..."
response.attestationObjectstring证明对象（Base64URL 编码）"o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YV..."

登录 API 对照表 ​

generateAuthenticationOptions() 参数 ​

参数类型必填默认值说明示例值
rpIDstring✅-依赖方 ID"example.com"
allowCredentialsCredentialDescriptor[]❌[]允许的凭据列表[{id, type, transports}]
challengestring | Uint8Array❌自动生成防重放挑战"auth-challenge"
timeoutnumber❌60000超时时间（毫秒）120000
userVerificationUserVerificationRequirement❌"preferred"用户验证要求"required"
extensionsAuthenticationExtensionsClientInputs❌{}扩展功能配置{uvm: true}

verifyAuthenticationResponse() 参数 ​

参数类型必填说明示例值
responseAuthenticationResponseJSON✅前端返回的认证响应{id, rawId, type, response}
expectedChallengestring✅期望的挑战值"expected-challenge"
expectedOriginstring✅期望的来源"https://example.com"
expectedRPIDstring✅期望的 RP ID"example.com"
authenticatorAuthenticatorDevice✅存储的认证器信息{credentialID, credentialPublicKey, counter}
requireUserVerificationboolean❌是否要求用户验证true

认证响应结构 ​

字段类型说明示例值
idstring凭据 ID（字符串形式）"credential-id-string"
rawIdstring凭据 ID（Base64URL 编码）"Y3JlZGVudGlhbC1pZA"
typestring凭据类型"public-key"
response.clientDataJSONstring客户端数据（Base64URL 编码）"eyJ0eXBlIjoi..."
response.authenticatorDatastring认证器数据（Base64URL 编码）"SZYN5YgOjGh0NBcPZHZgW4..."
response.signaturestring签名（Base64URL 编码）"MEUCIQDx..."
response.userHandlestring | null用户句柄（Base64URL 编码）"dXNlci0xMjM"

类型定义对照表 ​

基础类型 ​

类型说明可选值示例
AttestationType证明类型"none", "direct", "indirect", "enterprise""none"
UserVerificationRequirement用户验证要求"required", "preferred", "discouraged""preferred"
ResidentKeyRequirement可发现凭据要求"required", "preferred", "discouraged""required"
AuthenticatorAttachment认证器附加方式"platform", "cross-platform""platform"
PublicKeyCredentialType公钥凭据类型"public-key""public-key"

认证器选择条件 ​

字段类型说明示例值
authenticatorAttachmentAuthenticatorAttachment认证器附加方式"platform"
residentKeyResidentKeyRequirement可发现凭据要求"required"
userVerificationUserVerificationRequirement用户验证要求"preferred"
requireResidentKeyboolean是否需要可发现凭据（已废弃）true

凭据描述符 ​

字段类型说明示例值
idUint8Array凭据 ID（二进制）Buffer.from("id", "base64url")
typePublicKeyCredentialType凭据类型"public-key"
transportsAuthenticatorTransport[]传输方式列表["internal", "hybrid"]

错误码对照表 ​

浏览器错误 ​

错误名称说明常见原因解决方案
NotAllowedError操作不被允许用户取消、超时、策略限制提示用户重试或使用其他方式
SecurityError安全错误rpID 不匹配、HTTPS 问题检查域名配置和 HTTPS 设置
NotSupportedError不支持错误浏览器或设备不支持降级到传统认证方式
InvalidStateError无效状态错误认证器状态异常重新初始化认证器
ConstraintError约束错误参数约束不满足检查参数配置
UnknownError未知错误其他未分类错误记录日志并降级处理

服务端验证错误 ​

错误类型说明检查项
ChallengeMismatch挑战值不匹配验证 challenge 是否一致
OriginMismatch来源不匹配验证 origin 是否正确
RPIDMismatchRP ID 不匹配验证 rpId 是否一致
SignatureInvalid签名无效验证签名是否正确
CounterNotIncreased计数器未递增检查 signCount 是否递增
UserVerificationFailed用户验证失败检查 UV 标志位

算法标识符对照表 ​

COSE 算法标识符 ​

ID算法名称说明推荐度兼容性
-7ES256ECDSA w/ SHA-256⭐⭐⭐⭐⭐最广泛支持
-8EdDSAEdDSA 签名算法⭐⭐⭐⭐现代推荐
-257RS256RSA w/ SHA-256⭐⭐⭐兼容性好
-35ES384ECDSA w/ SHA-384⭐⭐部分支持
-36ES512ECDSA w/ SHA-512⭐⭐部分支持
-258RS384RSA w/ SHA-384⭐较少使用
-259RS512RSA w/ SHA-512⭐较少使用
-38PS256RSA-PSS w/ SHA-256⭐⭐现代算法
-39PS384RSA-PSS w/ SHA-384⭐较少使用
-40PS512RSA-PSS w/ SHA-512⭐较少使用

算法选择建议 ​

场景推荐算法说明
生产环境[-7, -257]ES256 + RS256，兼容性最佳
现代应用[-7, -8]ES256 + EdDSA，性能最佳
兼容性优先[-7, -257, -8]包含所有主流算法
安全优先[-7, -8, -38]现代算法组合

传输方式对照表 ​

认证器传输方式 ​

传输方式说明使用场景示例设备
internal平台内置认证器手机指纹、Face ID、Windows HelloiPhone、Android、Windows PC
usbUSB 连接USB 安全钥匙YubiKey、Feitian
nfc近场通信NFC 安全钥匙NFC YubiKey
ble蓝牙低功耗蓝牙安全钥匙蓝牙 YubiKey
hybrid混合传输跨设备认证手机扫码登录
cable有线传输已废弃，被 hybrid 替代-
smart-card智能卡企业环境企业智能卡

传输方式选择策略 ​

场景推荐传输方式说明
移动应用["internal", "hybrid"]优先本机，支持跨设备
桌面应用["internal", "usb", "hybrid"]支持多种方式
企业环境["usb", "nfc", "smart-card"]硬件安全优先
通用场景["internal", "usb", "nfc", "ble", "hybrid"]最大兼容性

扩展功能对照表 ​

注册扩展 ​

扩展名类型说明返回值使用场景
credPropsboolean凭据属性{rk?: boolean}获取可发现凭据信息
largeBlob{support: string}大对象存储{supported: boolean}存储用户数据
prf{eval: object}伪随机函数{enabled: boolean}密钥派生
appidExcludestringU2F 兼容排除{value: boolean}历史迁移

认证扩展 ​

扩展名类型说明返回值使用场景
appidstringU2F 兼容{value: boolean}历史迁移
uvmboolean用户验证方法{uvm: number[][]}风控审计
hmacCreateSecretbooleanHMAC 密钥创建{hmacCreateSecret: boolean}对称加密
minPinLengthboolean最小 PIN 长度{minPinLength: number}PIN 策略

扩展配置示例 ​

typescript
// 注册扩展
const registrationExtensions = {
  credProps: true, // 获取凭据属性
  largeBlob: { support: "preferred" }, // 大对象存储
  prf: { eval: { first: new Uint8Array(32) } }, // 伪随机函数
};

// 认证扩展
const authenticationExtensions = {
  uvm: true, // 用户验证方法
  appid: "https://example.com/u2f-app-id.json", // U2F 兼容
  hmacCreateSecret: true, // HMAC 密钥创建
};

常用配置模板 ​

标准 Passkey 配置 ​

typescript
// 注册配置
const standardRegistration = {
  rpName: "我的应用",
  rpID: "example.com",
  userID: Buffer.from(userId, "utf8"),
  userName: userEmail,
  userDisplayName: userDisplayName,
  supportedAlgorithmIDs: [-7, -257],
  authenticatorSelection: {
    residentKey: "required",
    userVerification: "preferred",
  },
  attestationType: "none",
  extensions: { credProps: true },
  timeout: 120000,
};

// 认证配置
const standardAuthentication = {
  rpID: "example.com",
  userVerification: "preferred",
  timeout: 120000,
  // allowCredentials 留空支持可发现凭据
};

高安全配置 ​

typescript
// 高安全注册配置
const secureRegistration = {
  rpName: "企业后台",
  rpID: "admin.example.com",
  userID: Buffer.from(userId, "utf8"),
  userName: userEmail,
  userDisplayName: userDisplayName,
  supportedAlgorithmIDs: [-7, -8],
  authenticatorSelection: {
    residentKey: "required",
    userVerification: "required",
    authenticatorAttachment: "platform",
  },
  attestationType: "direct",
  extensions: { credProps: true },
  timeout: 60000,
};

// 高安全认证配置
const secureAuthentication = {
  rpID: "admin.example.com",
  userVerification: "required",
  timeout: 60000,
  extensions: { uvm: true },
};

兼容性配置 ​

typescript
// 兼容性优先配置
const compatibilityRegistration = {
  rpName: "通用应用",
  rpID: "example.com",
  userID: Buffer.from(userId, "utf8"),
  userName: userEmail,
  userDisplayName: userDisplayName,
  supportedAlgorithmIDs: [-7, -257, -8],
  authenticatorSelection: {
    residentKey: "preferred",
    userVerification: "preferred",
  },
  attestationType: "none",
  extensions: { credProps: true },
  timeout: 180000,
};

设备识别对照表 ​

AAGUID 映射表 ​

AAGUID设备/服务说明
ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4Google Password ManagerAndroid 设备
adce0002-35bc-c60a-648b-0b25f1f05503Chrome on MacmacOS Chrome
08987058-cadc-4b81-b6e1-30de50dcbe96Windows HelloWindows 10/11
9ddd1817-af5a-4672-a2b9-3e3dd95000a9Windows HelloWindows 10/11
6028b017-b1d4-4c02-b4b3-afcdafc96bb2Windows HelloWindows 10/11
fbfc3007-154e-4ecc-8c0b-6e020557d7bdiCloud KeychainiOS/macOS
00000000-0000-0000-0000-000000000000Apple/UnknowniOS/macOS（隐私模式）
bada5566-a7aa-401f-bd96-45619a55120d1Password第三方密码管理器
d548826e-79b4-db40-a3d8-11116f7e8349Bitwarden第三方密码管理器
531126d6-e717-415c-9320-3d9aa6981239Dashlane第三方密码管理器

设备识别函数 ​

typescript
function identifyDevice(aaguid: string): string {
  const deviceMap: Record<string, string> = {
    "ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4": "Google Password Manager",
    "adce0002-35bc-c60a-648b-0b25f1f05503": "Chrome on Mac",
    "08987058-cadc-4b81-b6e1-30de50dcbe96": "Windows Hello",
    "9ddd1817-af5a-4672-a2b9-3e3dd95000a9": "Windows Hello",
    "6028b017-b1d4-4c02-b4b3-afcdafc96bb2": "Windows Hello",
    "fbfc3007-154e-4ecc-8c0b-6e020557d7bd": "iCloud Keychain",
    "00000000-0000-0000-0000-000000000000": "Apple/Unknown",
    "bada5566-a7aa-401f-bd96-45619a55120d": "1Password",
    "d548826e-79b4-db40-a3d8-11116f7e8349": "Bitwarden",
    "531126d6-e717-415c-9320-3d9aa6981239": "Dashlane",
  };

  return deviceMap[aaguid] || "Unknown Device";
}

总结 ​

本对照表涵盖了 WebAuthn/Passkeys 开发中的主要 API、参数和配置选项。在实际开发中，建议：

  1. 根据场景选择合适的配置：不同应用场景需要不同的安全级别和兼容性要求
  2. 实现完整的错误处理：覆盖所有可能的错误情况，提供用户友好的提示
  3. 进行充分的测试：在不同设备、浏览器和网络环境下测试
  4. 监控和优化：收集性能数据，持续优化用户体验

通过合理使用这些 API 和配置，可以构建安全、便捷的通行密钥认证系统。

本站总访问 — 次