账号认证模式

目的

让读者查询或修改自然人账号的登录方式（口令、混合、仅 SSO），并理解变更会撤销全部旧会话。查询成功返回 mode 与 version；修改成功返回更新后的投影，失败时保留原策略且不泄漏已回滚内容。

前置条件

schema v26 已迁移，API 已启动。租户侧需要 auth-mode:read / auth-mode:write 及保留 tenant_admin 角色（写入时）；平台侧需要 platform:auth-mode:*。修改须提交当前操作者口令 operatorPassword 做再鉴别。

schema v26 为平台、租户后台和会员账号提供三种登录方式。升级后的历史账号及新账号默认 hybrid，保留原有入口行为。服务账号继续使用独立机器凭据，不使用本页策略。Vben 已接入实际SSO登录与恢复，本页说明认证模式管理。

选择登录方式

模式	口令登录	已验证 OIDC 登录
password（仅口令登录）	允许	拒绝
hybrid（口令或 SSO 登录）	允许	允许
sso_only（仅 SSO 登录）	拒绝	允许

表中“允许”仍须满足当前账号、租户、客户端、绑定和安全策略。未知或损坏的模式一律拒绝。仅 SSO 登录关闭的是口令登录入口，仍保留本地敏感操作的口令再鉴别，以及锁定、必须改密和密码有效期约束；它不是没有本地凭据的账号。必须改密的 OIDC 会话只可完成受限改密，成功后须重新 SSO 登录。

查看与修改

先显式迁移到 v26 并启动真实 API。租户管理员在“账号认证模式”选择后台或会员类型，输入本租户账号 ID 后查询；平台管理员在“平台认证模式”只能查询平台账号。页面只返回 ID、模式、状态和版本，不返回密码、外部主体或完整个人资料。

读取权限为 auth-mode:read，平台为 platform:auth-mode:read。修改另需对应 :write、当前管理员身份和本人的管理员口令；租户写入要求真实保留 tenant_admin 角色。只读角色不显示修改按钮，直接调用接口仍由服务端拒绝。

打开“更改登录方式”，选择不同模式并输入本人口令。取消、失败或身份切换会清除本次输入。提交使用查询时的账号版本；版本冲突时关闭弹窗，重新查询再决定，不能自动覆盖。修改本人成功后页面清理内存身份并返回当前域登录页。

实际变更在同一事务内推进账号版本与凭据版本，撤销该账号所有客户端的旧会话，清空相关 OIDC 加密材料并写入审计；任一步失败全部回滚。恢复口令模式也不会恢复旧 access、refresh 或缓存身份。重复提交同一模式仅在版本及再鉴别通过后作为无变化操作，不重复推进版本。

最后入口与恢复管理员

切换到 sso_only 前，账号必须启用且当前未锁定，并存在当前启用、部署批准、能够路由到正式回调的客户端、提供方和绑定。按精确 issuer/sub 判断，同 issuer 的其他已批准提供方也可使用绑定，不能只看最初的来源 provider ID。该检查在事务内读取当前结构，不探测外部网络，不保证 IdP 在线。

有效的仅 SSO 账号不能计划解绑最后一个结构性入口。若全部入口已因故障或紧急关闭失效，可以清理坏绑定，但账号仍不能口令登录。平台可紧急停用最后提供方或客户端，系统保持拒绝，不自动降级。

租户必须保留至少一名启用、未注销、具有真实保留 tenant_admin 角色并允许口令登录的管理员；平台必须保留至少一名启用且 role_code=platform_admin 的口令管理员。模式切换、租户管理员启停、删除与角色替换共同遵守这一不变量。临时锁定、密码到期、租户不可用或紧急关闭口令客户端仍可能暂时阻止恢复，系统不会自动放宽这些保护。

IdP 故障时，由现有口令恢复管理员从本地入口登录，核对目标后显式恢复 hybrid 或 password；没有自动回退或通用应急密码。恢复命令仍要求再鉴别、当前版本及审计。

接口与边界

• 租户：GET/PUT /api/admin/v1/identity/authentication-modes/{id}。
• 平台：GET/PUT /api/platform/v1/identity/authentication-modes/{id}。
• GET 只接受一个 realm 查询项；PUT 在正文中传 realm、mode、version、operatorPassword，禁止额外查询参数、租户替代或未知字段。

读取租户后台账号（realm=admin）：

GET /api/admin/v1/identity/authentication-modes/1001?realm=admin
Origin: http://127.0.0.1:5174
X-App-Request: admin
Authorization: Bearer <access>

{
  "code": 0,
  "data": {
    "realm": "admin",
    "tenantId": "1",
    "subjectId": "1001",
    "mode": "hybrid",
    "status": "enabled",
    "version": 3
  },
  "message": "ok",
  "requestId": "req_example"
}

修改为仅 SSO（须满足本页「最后入口」规则，且 version 与查询一致）：

PUT /api/admin/v1/identity/authentication-modes/1001
Origin: http://127.0.0.1:5174
X-App-Request: admin
Authorization: Bearer <access>
Content-Type: application/json

{
  "realm": "admin",
  "mode": "sso_only",
  "version": 3,
  "operatorPassword": "<操作者提供>"
}

版本冲突返回 409001；违反最后入口或恢复管理员约束返回 409003：

{
  "code": 409003,
  "message": "当前状态不允许此操作",
  "requestId": "req_example"
}

接口沿用统一 JSON/JWE、Origin、认证和当前权限校验。口令不写入审计、错误属性或日志；对外只返回公开提示和业务码。依赖故障拒绝本次操作，不自动重试敏感事务。

关联

相关配置见 OIDC管理，浏览器入口见 浏览器单点登录，阶段证据见 M5实施记录。达梦目前只有 v26 迁移源码，未认证；本地结果不代表生产或容量支持。