开发者文档中心

OpenAPI进入控制台

服务端 API 与回调 · 2026-10-31

企业 SSO 与 MFA 身份打通

对接客户 OIDC 身份系统,由客户完成 MFA,云蝠核验身份、企业范围与操作风险。

先选对认证方式

场景协议与权限
管理员、员工和子账户登录OpenID Connect 1.0,Authorization Code + PKCE S256;客户 IdP 完成 MFA
服务端业务接口与远程 MCPAPI Key,绑定企业、创建账号、域名和允许操作;不是 OAuth Client Credentials
网站与小程序访客使用对应 SDK 访客凭据;本 SSO 不会自动认证匿名访客

一次登录怎样完成

  1. 进入企业 SSO

    按管理员登记的企业标识进入 /api/identity-hub/login;云蝠创建一次性 state、nonce 与 PKCE 事务。

  2. 客户完成 MFA

    浏览器跳转可信 IdP;由客户系统完成密码、OTP、硬件密钥等认证因素。

  3. 回调核验

    服务端兑换 code 并验证签名、issuer、audience、nonce、acr、amr、auth_time 和策略版本;客户端传来的 MFA 标记不能代替证据。

  4. 绑定已有账号

    按 issuer + subject 关联已登记的云蝠账号;不按同名邮箱自动合并,不自动提权或创建企业。

  5. 按风险放行

    创建本人会话;每次请求检查企业、权限及 MFA 时效。写入、导出和凭据管理需要更近期认证。

客户与云蝠双方的准备

  1. 客户 IdP 创建 OIDC Web 应用,登记精确回调 URI,并提供 issuer、clientId、客户端认证方式,以及经双方确认的 MFA acr / amr 含义。客户端 secret 仅配置在服务端。
  2. 平台主管理员配置可信 OIDC 连接与企业标识;当前部署共用一个可信 issuer,不支持每家企业任意填写身份源。身份发现及相关端点须满足当前同源校验。
  3. 企业管理员登记本人企业已有员工和子账户的外部 subject;不能仅凭邮箱自动关联。平台主管理员负责认证信任策略,更新需当前密码与 revision 校验。
  4. 先在测试账号核对成功、拒绝、过期、停用、撤销绑定、跨企业和旧会话,再决定是否启用 required。开启前同时核对现有 API Key、CLI 与远程 MCP 依赖。

接口需求

路由用途与认证
GET /api/identity-hub/login浏览器企业 SSO 入口,enterprise 标识由管理员登记;reauth=1 请求重新认证
GET /api/identity-hub/callbackIdP 回调,服务端验证一次性事务并创建会话
GET /api/identity-hub/assurance本人登录会话读取当前认证状态与恢复入口,不提高权限
GET / POST /api/identity-hub/policy企业管理员按权限读取本企业;仅平台主管理员可写策略,需当前密码与 revision
GET / POST /api/identity-hub/bindings本人管理会话维护授权范围的已有账号绑定;写入校验密码及 expectedSubject,解绑撤销相关会话

下载完整接口契约

进入「下载中心 → 企业 SSO / MFA OpenAPI」。该接口使用本人 Cookie 登录会话;写入还需同源 Origin 与服务端权限校验。API Key 不能调用这些 /api 管理路由。契约包含请求字段、错误响应与认证要求。

不同风险如何验证

风险当前策略
普通业务读取required 模式验证可信 MFA 证据与有效期;普通时效配置为 300–28800 秒
写入、导出、凭据管理需更近期 MFA,时效为 60–300 秒且不大于普通时效;过期返回 STEP_UP_REQUIRED
API Key / 远程 MCPrequired 模式下拒绝机器调用、创建及轮换密钥;仍可用合格管理会话查看和撤销。管理员重新登录不能为 API Key 附加 MFA

暂时无法接入 MFA

由平台主管理员明确选择 optional,沿用原有登录与权限控制;optional 不等于 MFA,也不自动变为只读。required 不会在 IdP 故障时自动降级。可由有权限的平台主管理员通过现有密码确认及审计流程恢复配置;目前没有双人审批或自动到期应急授权。

收到认证错误后怎么办

本人会话遇到 MFA_REQUIRED / STEP_UP_REQUIRED 时,经同源 loginUrl 重新认证,再由用户重新确认操作;不能自动重放写请求。API Key 收到 MFA_REQUIRED 时 loginUrl 为 null,应联系管理员核对接入方案,不能靠登录、换密钥或循环重试解除限制。远程 MCP 把同样的信息放在 error.data;普通权限 403 没有这些 MFA code。

当前范围

本能力适用于 SQLite / D1;PostgreSQL 的策略和绑定管理返回 501,不能声称已启用强制 MFA。没有本地 TOTP / WebAuthn 注册、SCIM 自动开通、SLO 或机器身份 MFA 例外。SAML 2.0、LDAP / AD、CAS 可由客户身份代理转换成 OIDC,未实现原生直连。真实 IdP、MFA 因素及浏览器兼容性仍需双方联调。

实现依据 · 仓库内路径
  • docs/ENTERPRISE-MFA-SSO-INTEGRATION.md
  • docs/enterprise-mfa-sso.openapi.json
  • lib/identity/enterprise-assurance.ts
  • database/stores/identity/enterprise-assurance-access.ts
  • backend/services/identity/enterprise-sso-bindings.ts

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。