TsgcWSAPIServer_WebAuthn 组件是一个 Delphi/FPC 服务器模块，通过 HTTPS 实现 WebAuthn 协议的依赖方。它与 TsgcWebSocketHTTPServer 或 TsgcWebSocketServer 集成，并公开类 REST 的端点用于注册和身份验证。
端点机制
默认情况下，组件在 /sgcWebAuthn 下注册路由：
| 用途 | 默认端点 | 描述 |
|---|---|---|
| 注册选项 | /Registration/Options | 客户端在调用 navigator.credentials.create 之前请求挑战和依赖方信息 |
| 注册验证 | /Registration/Verify | 浏览器提交新凭据、认证对象和客户端数据以进行服务器验证 |
| 身份验证选项 | /Authentication/Options | 服务器提供允许的凭据 ID 列表和挑战 |
| 身份验证验证 | /Authentication/Verify | 浏览器提交断言（authenticatorData + 签名）以进行验证 |
| JavaScript 辅助脚本 | /Webauthn | 提供封装标准 WebAuthn 浏览器调用的辅助脚本 |
| 测试页面 | /Test | 用于开发阶段测试 API 的快速 HTML 页面 |
端点可以通过 EndpointOptions 重新映射以适应现有路由方案。
核心属性
- RelyingParty（RPID / RPName） — 必填的 DNS 名称，用于标识凭据的逻辑域。确保其与应用程序的有效域名匹配。
- Origins 与 TopOrigins — 分号分隔的有效来源列表。
Origins涵盖主要域名；TopOrigins用于在 iframe 中嵌入时的场景。 - AllowCrossOrigins — 如果设为
True，跨域 iframe 可以请求身份验证。这需要仔细维护TopOrigins并进行服务器端验证。 - Algorithms — 支持的 COSE 算法标识符（例如
ES256、RS256、EdDSA）。控制服务器接受哪些类型的公钥。 - TimeoutMS — 向客户端建议的完成 WebAuthn 操作的超时时间。
- UserVerification — 用户验证策略（
preferred、required、discouraged）。 - Attestation — 指定认证方式：无、间接或直接。直接认证需要验证认证证书链。
- 元数据服务（MDS） — 启用后，组件将查询 FIDO 元数据服务文件以确认验证器型号的可信度。相关字段：
MDS_FileName— 本地缓存的 JSON 元数据（从 FIDO 下载）。RootCert_FileName— 用于验证元数据签名的根证书。
- ChallengeOptions — 允许自定义生成挑战的长度和随机性来源。
- CredentialStorage — 虽然不是直接属性，但组件要求应用程序持久化凭据公钥、签名计数器和用户句柄。
事件生命周期
注册
OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response)：检查用户名，若无效则中止，或提供用户信息。OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response)：在发送给客户端之前修改挑战或设置验证器选择标准。OnWebAuthnRegistrationVerify(Sender, Credential, var Success)：执行自定义认证检查或否决注册。OnWebAuthnRegistrationSuccessful(Sender, Credential)：将凭据 ID、公钥、签名计数器和用户句柄存储到数据库中。OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg)：记录日志或返回更具描述性的错误信息。
身份验证
OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response)：查找用户名对应的凭据 ID，决定允许的传输方式（USB、NFC、BLE、内置）。OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response)：自定义UserVerification，调整挑战长度，或嵌入额外元数据。OnWebAuthnAuthenticationVerify(Sender, Credential, var Success)：验证签名计数器的递增，执行账户状态检查。OnWebAuthnAuthenticationSuccessful(Sender, Credential)：更新签名计数器并生成会话令牌。OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg)：实现速率限制、锁定策略和审计功能。
这些事件允许对协议的每个步骤进行精细控制，从生成选项到处理断言。