配置单点登录

SSO 由超级管理员在站点设置 → SSO 中管理：先打开全局开关，再逐个添加提供商。每个提供商的协议配置是一段 JSON，字段随协议不同；保存前先准备好身份提供商的回调地址、客户端凭据与证书。

回调地址

注册到身份提供商的回调地址格式为：

{BACKEND_ORIGIN}/api/v1/sso/callback/{provider_name}

BACKEND_ORIGIN 取请求本身的对外来源地址——即浏览器实际访问到后端的那一个域名（经反向代理时使用代理转发的对外地址）。这里的 :3000 会被自动改写成 :8000。它不是 API_BASE_URL（服务内部地址），也不受 FRONTEND_URL 影响：用错会导致回调 404 或跳回错误域名。

{provider_name} 必须与 Clouisle 中登记的提供商名称完全一致，大小写敏感。回调地址不匹配是 SSO 登录失败最常见的原因。

添加提供商

在站点设置 → SSO 点击添加提供商，对话框分为基本信息 / 配置 / 属性映射三个标签：

协议配置

配置标签是一段自由 JSON 文本，切换协议时会填入该协议的模板。字段名必须与下表一致，拼写错误不会报错，只会在登录时抛出配置异常。

OAuth2 / OIDC

登录使用授权码 + PKCE（S256）流程，并生成 nonce。常见提供商的端点：

{
  "client_id": "your-github-client-id",
  "client_secret": "your-github-client-secret",
  "authorization_url": "https://github.com/login/oauth/authorize",
  "token_url": "https://github.com/login/oauth/access_token",
  "userinfo_url": "https://api.github.com/user",
  "scopes": "read:user user:email"
}

SAML 2.0

{
  "sp_entity_id": "clouisle",
  "idp_entity_id": "https://idp.example.com/metadata",
  "sso_url": "https://idp.example.com/sso",
  "x509_cert": "MIIC...省略...",
  "acs_url": "https://your-domain.com/api/v1/sso/callback/azure-ad"
}

strict 模式开启，SAML 响应必须通过签名校验；IdP 与 Clouisle 的时钟偏差过大会直接判定失败。

CAS

CAS 用户标识取自校验响应中的 <cas:user>；版本 3 还会读取 <cas:attributes> 中的属性供属性映射使用。

属性映射

属性映射标签同样是一段 JSON，把提供商返回的数据映射到 Clouisle 需要的字段：

两种路径写法：

• 点号路径（默认）：{"email": "email", "username": "profile.name"} 读取嵌套对象。
• JSONPath：以 $ 开头，适合数组或过滤，{"email": "$.emails[0].value"}；多个匹配时取第一个。

添加提供商时的默认值：

{
  "email": "email",
  "username": "name",
  "avatar_url": "picture"
}

GitHub 的返回字段与 OIDC 标准不同，需要改成 {"email": "email", "username": "login", "avatar_url": "avatar_url"}。

测试连接

列表中的测试连接调用 POST /api/v1/admin/sso/providers/{id}/test：

• 它在服务端仅本地构造一次授权地址（用一个占位回调地址），验证配置里必需的键是否齐全，然后返回该地址的前 100 个字符。
• 它不会访问身份提供商，因此 client secret 错误、回调地址不匹配、证书过期这类问题它都测不出来——必须用真实登录验证。
• 返回 status: error 只说明键缺失或值无法构造授权地址。

管理权限与 API

通用流程

1. 在站点设置中启用 SSO，并按需调整全局策略（允许密码登录、自动创建、需要审批、按邮箱匹配）。
2. 添加提供商：填写基本信息，选择协议。
3. 在配置标签填入该协议的 JSON。
4. 在属性映射标签把邮箱、用户名、头像对应到提供商字段。
5. 保存后，把 Clouisle 展示的回调地址填入身份提供商的白名单/重定向地址。
6. 用隐身窗口验证三种情况：新用户、已存在用户、错误回调。

用户生命周期

全局设置与提供商开关是或的关系，最终判定如下：

新建的 SSO 用户具有以下特征：

• 没有本地密码（hashed_password 为空字符串），因此无法用密码登录。
• 邮箱直接标记为已验证（信任提供商的邮箱）。
• 用户名取映射出的 username；缺失时用邮箱 @ 前的部分，再缺失时用 user_<提供商用户标识前 8 位>；重名会自动追加数字后缀。
• 角色取提供商的 default_role_id（仅 API 可设置，界面上没有该字段），未设置时回退到全局默认角色；随后按 default_team_id 加入默认团队。

常见错误

回调失败时后端会重定向到 /sso-callback?error=...，其中 error 可能是 sso_provider_not_found、sso_session_expired、sso_login_failed，账户被停用或待审批时分别是 inactive、pending_approval。

故障排除

登录页没有 SSO 按钮

1. 检查 sso_enabled 是否为 true。
2. 检查该提供商是否启用。
3. 直接请求 GET /api/v1/sso/providers 确认返回内容（为空则前端不会渲染按钮）。

回调报错 / 停在同一页面

1. 核对回调地址的域名与提供商名称是否与配置完全一致。
2. 确认 BACKEND_URL 或反向代理转发的对外地址是身份提供商可达的公网地址。
3. 检查授权码是否已过期（用户停留过久 → 6301）。
4. 查看审计日志中的 sso_login_failed 记录与错误信息。

登录成功但字段错位

1. 按属性映射确认路径写法（点号 vs $ JSONPath）。
2. 注意同名原始字段会覆盖映射值。
3. GitHub 等非 OIDC 标准字段需显式映射（login、avatar_url）。

SAML 校验失败

1. 证书必须是 PEM 内容且去掉头尾行。
2. 确认 IdP 与服务器时间同步（偏差过大会被判定为无效响应）。
3. 确认 idp_entity_id 与 IdP 元数据中的 Entity ID 完全一致。

关闭密码登录后无人能进后台

这是把站点切成 SSO-only 的典型事故：请先确认至少一个超级管理员已绑定 SSO；若已锁死，可在服务端直接把 sso_allow_password_login 改回 true 后重启。

相关文档

• SSO API — 端点、请求体与响应字段
• 登录与账户安全 — 登录保护与 SSO 首次登录行为
• 个人账户设置 — 解除关联与防自锁保护
• 站点设置参考 — sso_* 键的默认值
• 环境变量 — FRONTEND_URL、PUBLIC_API_URL 与 API_V1_STR 的作用与区别