SSO 与 SCIM
通过公司账户（IdP）登录并自动同步用户的设置顺序。
将公司使用的 IdP（Okta、Microsoft Entra ID、Google Workspace 等）与 Keural 连接后，员工即可使用公司账户登录，并在首次登录时自动加入组织。
IdP 管理员和开发者的详细规范请参见 SSO·SCIM 对接规范。
准备事项
| 项目 | 原因 |
|---|---|
| Keural 组织的所有者账户 | 只有所有者可以更改 SSO 设置。 |
| IdP 管理员权限 | 在 IdP 中创建 Keural 应用。 |
| 公司域名的 DNS 管理权限 | 通过 TXT 记录验证域名所有权。 |
支持的方式
| 方式 | 用途 |
|---|---|
| OpenID Connect（OIDC） | 使用公司账户登录 |
| SAML 2.0 | 使用公司账户登录。认证请求使用 Redirect，响应通过 HTTP-POST 接收。 |
| SCIM 2.0 | 在 IdP 中添加或停用用户时，自动同步到 Keural 账户 |
在 OIDC 和 SAML 中任选其一。若 IdP 同时支持两者，建议选择设置更简单的 OIDC。
设置顺序
所有设置均在 组织管理 → SSO 设置 中进行。
1. 验证公司域名
先验证用于 SSO 的邮箱域名的所有权。未验证的域名在第 3 步中无法保存。
在 组织域名 中输入公司域名（例如 acme.com），然后点击 添加域名。
点击该域名所在行的验证。在验证域名窗口中复制显示的 TXT 记录值（keural-verify=…）。
在 DNS 管理页面中，为该域名添加一条 TXT 记录，并粘贴复制的值。主机（名称）为域名本身（通常为 @）。
返回 Keural，点击确认验证。显示已验证即表示完成。DNS 生效可能需要几十分钟，若失败请稍后再次点击。
若有多个公司域名，请分别添加并验证。gmail.com 等公共邮箱域名无法使用。
2. 在 IdP 中创建应用
在 SSO 设置 顶部的协议中选择 OpenID Connect (OIDC) 或 SAML 2.0，即会显示需要在 IdP 中登记的 Keural 值。将其输入 IdP 应用，并复制 IdP 发放的值备用。
| 方向 | 项目 | 内容 |
|---|---|---|
| Keural → IdP | 回调 URI | 填入 IdP 应用的重定向 URI。 |
| IdP → Keural | Issuer URL | IdP 的颁发者地址。 |
| IdP → Keural | Client ID · Client Secret | 创建 IdP 应用后发放的值。 |
需要 IdP 设置为发送用户邮箱，才能完成登录。
| IdP | 创建位置 | 填写回调 URI 的位置 | Issuer URL |
|---|---|---|---|
| Okta | Applications → Create App Integration → OIDC · Web Application | Sign-in redirect URIs | https://<Okta 域名> |
| Microsoft Entra ID | App registrations → New registration | Redirect URI（Web） | https://login.microsoftonline.com/<租户 ID>/v2.0 |
| Google Workspace | Google Cloud 控制台 → API 和服务 → 凭据 → OAuth 客户端 ID（Web 应用） | 已授权的重定向 URI | https://accounts.google.com |
- Microsoft Entra ID：Client Secret 是在 Certificates & secrets 中新建的密钥值（Value）。在 Token configuration 中，为 ID 令牌添加
email可选声明。 - Okta：在应用的 Assignments 中，指定可以使用 Keural 的用户或群组。
3. 在 Keural 中填写值并保存
- 填入第 2 步从 IdP 获得的值。
- 在 邮箱域名 中填入第 1 步验证过的域名，多个域名以逗号分隔。使用该域名的邮箱登录时，会跳转到公司登录页面。
- 设置 首次登录时自动创建用户（JIT）。开启后，没有 Keural 账户的员工在首次 SSO 登录时将自动创建账户；关闭后，仅已有账户的人员可以登录。
- 点击 保存。
若使用 OIDC 且 IdP 未提供标准地址（discovery），请在打开高级设置中直接填写端点。大多数 IdP 留空即可。
4. 开启 SSO 并测试登录
- 开启 启用 SSO，然后点击 保存。
- 点击测试登录。新窗口中将打开公司登录页面。
- 使用公司账户登录并返回 Keural，即表示连接完成。
测试登录只有在 SSO 开启时才能使用。若出现问题，请关闭 启用 SSO 并保存。在此期间，该域名的员工将使用邮件链接登录。
员工登录
- 在 Keural 登录页面输入公司邮箱，将跳转到公司登录页面，登录后返回 Keural。
- 在桌面应用中，请使用邮件链接登录，而非公司登录页面。
- 首次通过 SSO 登录的员工以 成员 身份加入组织。管理员角色在组织管理中指定。
在以下情况下，虽然可以登录，但不会自动加入组织。
- 组织购买的席位已全部占满。
- 该账户已属于其他组织。
5. 连接 SCIM（可选）
连接 SCIM 后，在 IdP 中添加或停用用户时，将立即反映到 Keural 账户中。完成 SSO 连接后再进行设置。
在 SCIM 自动配置 中，开启 启用 SCIM 自动配置。
点击生成令牌并复制令牌。令牌仅在此时显示一次。
在 IdP 的自动配置设置中，填入 SCIM Base URL（Tenant URL）和令牌。认证方式为 Bearer 令牌。
| IdP | 输入位置 |
|---|---|
| Okta | 应用 → Provisioning → SCIM connector base URL。Authentication Mode 选择 HTTP Header |
| Microsoft Entra ID | Enterprise application → Provisioning → Automatic → Tenant URL · Secret Token |
IdP 中的操作将按以下方式反映到 Keural 中。
| 在 IdP 中 | 在 Keural 中 |
|---|---|
| 分配用户 | 创建账户并加入组织。用户名为邮箱地址。 |
| 停用用户或取消分配 | 停用账户，阻止登录。数据不会被删除。 |
| 重新启用 | 解除停用。 |
| 添加到或移出 Keural Admins 群组 | 升为管理员或降为成员。所有者不会改变。 |
若丢失令牌，请点击重新生成令牌，并将新令牌填入 IdP。原有令牌将立即失效。
故障排除
| 症状 | 处理方法 |
|---|---|
| 邮箱域名无法保存 | 确认是否已完成第 1 步的域名验证，且该域名不是公共邮箱域名。 |
| 域名验证失败 | 确认 TXT 值已从 keural-verify= 开始完整填写，等待 DNS 生效后再重新点击。 |
| 点击测试登录后，公司登录页面没有打开 | 确认已开启 启用 SSO 并已保存。 |
| 公司登录后返回 Keural 登录页面 | OIDC 请重新检查回调 URI、Issuer URL、Client Secret 以及邮箱声明；SAML 请重新检查 SP EntityID、ACS URL、证书以及邮箱属性。 |
| 提示没有账户，登录被拒绝 | 首次登录时自动创建用户（JIT）已关闭。请开启，或先邀请该员工。 |
| 可以登录，但看不到组织工作区 | 确认是否还有剩余席位，以及该账户是否已属于其他组织。 |
| 从 IdP 门户点击应用后登录失败（SAML） | 请从 Keural 登录页面使用公司邮箱开始登录。 |
| SCIM 连接测试失败 | 重新填写 Base URL 和令牌。若已重新生成令牌，请替换为新令牌。 |