iam-login/docs/webauthn.md

WebAuthn 第二因素

WebAuthn 使用 Spring Security 官方过滤器、WebAuthn4J 校验和 JDBC 仓储。 PostgreSQL 保存 user handle、凭据公钥与签名计数等记录，不保存用户密码或认证器私钥。 AD 仍为用户与组权威；凭据按目录 authority + objectGUID 关联，用户名改名不会换主体。

登录与注册

1. /signin 使用原生表单 POST 验证 AD 密码，建立 FACTOR_PASSWORD。
2. /signin/mfa：没有凭据时注册 passkey；已有凭据时验证 passkey。
3. 注册只保存凭据，必须再次实际验证，才取得 FACTOR_WEBAUTHN。
4. /signin/complete 要求两种因素均在 10 分钟内有效；目前仅显示验证结果，尚不接受 Hydra challenge。

首次注册信任近期 AD 密码验证。已有凭据后的新增注册同时要求密码与 WebAuthn 因素； 本轮 UI 只提供首次注册与验证，不提供新增管理、删除或自助恢复入口。遗失所有 passkey 尚无自助登录途径；生产上线前需要另行确定恢复和初始注册政策，不能把数据库清空作为日常恢复方式。 注册和验证均要求认证器 user verification（例如 PIN 或生物识别）。

Spring Security 负责因素合并、会话轮换、退出和 CSRF。应用仅补目录主体与凭据所有权 限制、首次注册并发检查，以及 challenge 的 5 分钟服务端有效期和单次消费。 没有应用自建登录状态机或认证 Filter。上游 options Filter 位于授权 Filter 前，因而 这些检查在 RelyingPartyOperations 扩展点执行，不能仅靠 URL 授权规则。

本地数据库

# 密码从 shell 或外部权限为 0600 的 env 文件提供；不要写入版本库。
docker compose -p iam-login-dev -f compose.dev.yaml up -d

必须设置 IAM_DEV_DB_PASSWORD。PostgreSQL 仅发布在 127.0.0.1:15432，可用 IAM_DEV_DB_PORT 调整端口；数据保存在 Compose named volume 中。 普通 down 不删数据，不要使用 down -v，否则会删除已注册凭据。

应用额外配置：

iam:
  webauthn:
    enabled: true
    rp-id: laptop.tail7e769.ts.net
    origin: https://laptop.tail7e769.ts.net:18082
spring:
  datasource:
    url: jdbc:postgresql://127.0.0.1:15432/iam_login
    username: iam_login
    password: ${IAM_DEV_DB_PASSWORD}

同时启用并配置 AD。RP ID 不含协议与端口，origin 必须与浏览器实际 HTTPS 入口完全一致；改变 RP 域名后旧凭据不能直接在新域名使用。 凭据 schema 由 Flyway 管理，采用 Spring Security 7.1.1 官方 PostgreSQL 表结构， 增加主体名称唯一约束和凭据所有者索引。未启用 WebAuthn 时不创建 DataSource，AD-only 路径不需要数据库。数据库不可用时 MFA 失败，不降级为仅密码通过。

验证

JVM 回归使用 Testcontainers PostgreSQL 与模拟 AD；不会向真实 AD 提交测试密码。 浏览器用 Chromium 虚拟认证器产生真实注册/断言签名，再交给后端校验：

scripts/gradle-in-docker test
scripts/gradle-in-docker webauthnBrowserFixture
# 另一终端；测试夹具固定监听 localhost:18083，使用测试证书。
IAM_WEBAUTHN_FIXTURE=1 npm --prefix frontend run test:browser -- webauthn.spec.ts

测试专用启动类仅在 test classpath，不进入生产 JAR，也不提供生产调试 API。 真实用户的 passkey 注册、认证器兼容性和 Native 路径仍需独立验收；JVM/虚拟认证器通过 不能代替真实人类或 Native 验收。生产共享 PostgreSQL 的接入留在部署阶段。