修复 SSO 登录问题
Clevera 中每一条单点登录消息的含义、原因及解决方法：在登录页面、身份提供商返回后、保存设置时、运行测试时以及注销时。
本文列出了 Clevera 显示的每一条关于单点登录 (SSO) 的消息、其产生原因及解决方法：在登录页面、身份提供商 (IdP) 将用户重定向回 Clevera 后、保存设置时以及在 Run test 中。
大多数登录问题源于以下五个原因之一：用户的电子邮件域不在你的列表中、他们已经在你的工作区之外拥有一个 Clevera 账户、IdP 仅对 SAML 响应的一部分进行了签名、某个值复制错误，或者登录操作并非从 Clevera 登录页面开始。
快速检查
| 检查项 | 位置 |
|---|---|
| Enable SSO 已开启且状态显示为 Active | Team settings → Security |
| 用户的确切电子邮件域位于 Allowed email domains 中（子域需单独计算） | Team settings → Security |
| 该用户已在你的 IdP 中被分配到此应用 | 你的 IdP |
| 该用户是你的工作区成员，或者尚未拥有 Clevera 账户 | Team settings → Members |
| 他们是从 Clevera 登录页面开始并输入工作邮箱的，而不是点击了 IdP 仪表板上的磁贴 | 登录页面 |
| 工作区仍处于 Custom 计划中 | Billing |
登录页面未提供 SSO 选项
当用户输入电子邮件时，如果登录页面识别出该域，会显示“Your organization uses Okta”（你的提供商名称，或自定义提供商显示为“SSO”）以及一个 Continue with 按钮。如果该选项未出现：
- 该域不在 Allowed email domains 中，或者电子邮件拼写有误。
- Enable SSO 已关闭，或者配置未完成。
- 工作区不再处于包含 SSO 的计划中。
点击 IdP 中的 Clevera 磁贴无法登录
Clevera 仅接受从 Clevera 登录页面发起的登录。当用户点击 Okta 仪表板、Microsoft My Apps 或 Google 应用菜单中的 Clevera 磁贴时，IdP 会发送一个 Clevera 从未请求过的响应。Clevera 会拒绝该响应并显示其登录页面，提示“SSO session expired. Please try again.”
这是有意设计的：每个 SAML 登录都绑定到发起它的浏览器，且只能使用一次，以防止他人将自己的登录信息植入他人的浏览器中。请让用户前往 Clevera 登录页面，输入他们的工作邮箱并点击 Continue with 你的提供商。你可以在 IdP 中隐藏该磁贴，以免他人尝试使用。
登录页面上的消息
| 消息 | 原因 | 解决方法 |
|---|---|---|
| "No SSO sign-in is available for this email address. Use your regular sign-in method instead." | 没有活跃的 SSO 连接涵盖此电子邮件的域。 | 检查域并确保 Enable SSO 已开启。 |
| "SSO is not available for this team. The team subscription may have changed." | 工作区的计划不再包含 SSO。 | 联系我们了解你的 Custom 计划。在此期间，成员可使用密码或 Forgot password?。 |
| "Please enter a valid email address." | 电子邮件字段不是有效的地址。 | 重新输入。 |
| "Failed to initiate SSO login. Please try again or use email/password." | Clevera 无法构建登录请求，通常是因为 OIDC 发现 URL 目前无法加载。 | 点击 Run test。检查 Discovery URL 是否公开且正确。 |
| "We couldn't start single sign-on. Try again." | 请求失败或一分钟内尝试次数过多。 | 等待一分钟后再试。 |
| "We couldn't reach Clevera. Check your connection and try again." | 无法连接到 Clevera。 | 检查网络或 VPN。 |
| "Your organization requires Single Sign-On. Use the SSO button to continue." | 成员在 Require SSO 开启时尝试使用密码登录。 | 使用 Continue with 你的提供商。 |
| "Your organization requires Single Sign-On. Please use the SSO option on the login page." | 成员或域内的新用户在 Require SSO 开启时尝试使用 Continue with Google。 | 输入工作邮箱并使用 SSO 按钮。 |
当 Require SSO 开启时，登录页面还会为属于你域名的地址隐藏 Create an account 选项。
在注册页面上
| 消息 | 原因 | 解决方法 |
|---|---|---|
| "Your organization signs in with single sign-on (SSO). Go to Sign in, enter this email and choose Continue with SSO." | 处于 Require SSO 开启域下的用户尝试使用密码创建账户。 | 前往登录页面，输入工作邮箱并点击 Continue with 你的提供商。如果 Create accounts on first sign-in 已开启，账户将在首次 SSO 登录时创建；否则，需先由所有者邀请。 |
身份提供商返回后的消息
当 IdP 将用户重定向回 Clevera 时，这些消息会出现在 Clevera 登录页面的顶部。
| 消息 | 原因 | 解决方法 |
|---|---|---|
| "SSO session expired. Please try again." | Clevera 无法将响应与它发起的登录匹配。通常是因为用户点击了 IdP 仪表板上的 Clevera 磁贴、切换了浏览器、使用了后退按钮、刷新页面以重新发送登录请求，或在 IdP 处停留超过 10 分钟。 | 在同一浏览器中从 Clevera 登录页面重新开始。参阅 点击 Clevera 磁贴。 |
| "SSO session validation failed. Please try again." | 仅限 OIDC。响应属于不同的登录尝试，例如在使用后退按钮或在两个标签页中登录后。 | 关闭其他 Clevera 登录标签页并重新开始。 |
| "SSO authentication was cancelled or denied. Please try again." | 仅限 OIDC。IdP 返回了错误：用户取消了操作、未被分配到该应用，或拒绝了授权。 | 在你的 IdP 中将他们分配到该应用；然后重试。 |
| "No authorization code received." | 仅限 OIDC。IdP 返回时未携带登录代码。 | 检查应用是否设置为 Authorization Code 授权。 |
| "SSO configuration not found or disabled." | 用户登录时 SSO 被关闭或移除。 | 重新开启 Enable SSO。 |
| "Your email domain is not authorized for this team's SSO." | IdP 发送的电子邮件使用的域不在 Allowed email domains 中。常见于别名、辅助域或登录名与电子邮件不一致的情况。 | 添加该域，或更改 IdP 发送的电子邮件（Name ID 或 email 声明）。 |
| "This account is no longer available." | 账户正在被删除。 | 无法再次登录。请使用其他电子邮件。 |
| "SSO authentication failed. Please contact your team administrator or use another sign-in method." | 响应被拒绝。参阅 下方原因。 | 按照下方的列表逐一排查。 |
"SSO authentication failed"
此消息涵盖了 Clevera 拒绝响应的所有情况，请按顺序检查以下内容：
| 原因 | 解决方法 |
|---|---|
| 用户已有 Clevera 账户但不是你工作区的成员。SSO 不会接管外部账户。 | 邀请他们。一旦他们接受，SSO 即可生效。 |
| 用户没有账户且 Create accounts on first sign-in 已关闭。 | 邀请他们，或开启该设置。 |
| 所有者通过他人保存的连接进行登录（例如在 所有权转移 之后）。 | 当前所有者打开 Edit 并保存一次连接。在此之前，请使用密码登录。 |
| SAML：仅断言（或仅响应）被签名。 | 让 IdP 对两者都进行签名。 |
| SAML：Clevera 中的证书不是 IdP 当前的签名证书。 | 粘贴当前证书 (Edit → 第 2 步) 并保存。 |
| SAML：IdP 的受众或接收者不匹配。 | 受众必须完全匹配 Clevera 的 Entity ID / Audience URI，且接收者或目的地必须完全匹配 https://app.clevera.ai/sso/saml/callback。 |
| SAML：断言已加密。 | 关闭断言加密。 |
SAML：没有电子邮件。Name ID 不是电子邮件且没有 email 属性。 |
将 Name ID 格式设置为 EmailAddress 并包含用户的电子邮件。 |
| SAML：Clevera 中的 IdP Entity ID 与响应中的颁发者不匹配。 | 从 IdP 重新复制颁发者。 |
| OIDC：客户端密钥错误或过期，或者重定向 URI 不匹配。 | 粘贴新密钥 (Edit)；重定向 URI 必须与设置对话框中显示的 Redirect URI (callback URL) 完全一致，即 https://app.clevera.ai/sso/oidc/callback。 |
OIDC：在 email、 preferred_username 或 upn 声明中没有有效的电子邮件。 |
在你的 IdP 中添加电子邮件声明，或为用户提供电子邮件地址。 |
| OIDC：颁发者与发现 URL 不匹配，例如多租户 URL。 | 使用你租户自己的发现 URL。 |
当你的 IdP 轮换其 OIDC 签名密钥时，Clevera 会在拒绝登录前获取一次新密钥，因此仅轮换密钥不会导致此消息。
如果以上方法均无效，请联系支持团队，并提供出现问题的电子邮件地址和尝试登录的时间。我们可以在日志中查看具体原因。
设置时的消息
| 消息 | 修复方法 |
|---|---|
| "SSO is available on the Custom plan." | 当工作区未处于 Custom 计划时保存会显示此消息，例如在页面打开期间计划发生了变更。联系我们以添加 SSO。 |
| "Identity provider Entity ID is required." / "Identity Provider Entity ID is required." | 填写 IdP Entity ID。 |
| "SSO sign-in URL is required." / "Identity Provider SSO URL is required." | 填写 SSO sign-in URL。 |
| "SSO sign-in URL must be a valid URL." / "Logout URL must be a valid URL." | 粘贴完整地址，以 https:// 开头。 |
| "X.509 certificate is required." / "An IdP certificate is required." | 粘贴 IdP 的签名证书。 |
| "Client ID is required." / "OIDC Client ID is required." | 填写 Client ID。 |
| "Client secret is required." / "OIDC Client Secret is required." | 填写 Client secret。 |
| "A valid authorization URL is required." / "A valid token URL is required." | 填写端点，或改用 Discovery URL。 |
| "Discovery URL must be a valid URL." / "UserInfo URL must be a valid URL." | 粘贴完整地址。 |
| "Add at least one allowed domain." | 在 Allowed email domains 下添加一个域名。 |
| "Enter a company domain such as example.com." | 仅输入域名，例如 acme.example。 |
| "This domain is already on the list." | 该域名已被添加。 |
| "The domain acme.example is already assigned to another team." | 其他 Clevera 工作区正在使用该域名。如果是你的域名，请联系支持团队。 |
| "Automatically provisioned users cannot be granted the Administrator role by default." | 选择 编辑者 或 内容创作者，或关闭 Create accounts on first sign-in。 |
| "Fix the highlighted fields before saving." | 对话框会跳转到出现问题的步骤。 |
| "Finish the SSO configuration before enabling sign-in for your team." | 完成必填字段，然后开启 Enable SSO。 |
| "SSO must be enabled before enforcement can be turned on." | 请先开启 Enable SSO。 |
| "Only the team owner can change SSO settings." | 请咨询所有者。管理员无法更改 SSO 设置。 |
| "SSO settings did not load" | 点击 重试，或刷新页面。 |
| "Copying is blocked here. Select the value instead." | 你的浏览器阻止了复制按钮。请手动选中并复制文本。 |
运行测试结果
Run test 会检查已保存的设置，而非进行实际登录。它会显示“SSO configuration is valid and ready to use.”（SSO 配置有效且可使用）或“SSO configuration has issues that need to be resolved.”（SSO 配置存在需要解决的问题），并列出以下问题：
| 问题 | 修复方法 |
|---|---|
| "IdP Entity ID is required." / "IdP SSO URL is required." / "IdP X.509 certificate is required." | 填写缺失的 SAML 字段。 |
| "IdP SSO URL is not a valid URL." | 粘贴完整的登录 URL。 |
| "IdP certificate is not a valid X.509 certificate." | 粘贴证书的 Base64 (PEM) 文本，而非二进制文件或指纹。 |
| "IdP certificate has expired." | 获取 IdP 当前的签名证书并粘贴。 |
| "OIDC Client ID is required." / "OIDC Client Secret is required." | 填写缺失的 OIDC 字段。 |
| "Either a Discovery URL or manual endpoint URLs are required." | 添加 Discovery URL 或端点。 |
| "Discovery URL is not a valid URL." | 粘贴完整地址。 |
| "Could not load the OIDC discovery document. Check that the URL is correct and publicly reachable over HTTPS." | 在浏览器中打开该 URL；它应该显示 JSON。它必须能从互联网访问，而不仅仅是在你的网络内部。 |
| "Discovery document does not contain an authorization endpoint." | 该 URL 不是 OpenID 配置。请使用以 /.well-known/openid-configuration 结尾的 URL。 |
| "No SSO configuration found. Please configure SSO first." | 请先保存配置。 |
| "The test could not run." | 检查你的连接并重试。 |
登出
| 消息 | 含义 |
|---|---|
| "You have been signed out via SSO." | 你的 IdP 已将你从 Clevera 登出（SAML 单点登出）。 |
| "Single Logout is not available for this session." | IdP 发送了登出请求，但你的工作区未设置 SAML 单点登出（没有 Logout URL）。 |
| "Single Logout could not be completed." | 无法验证登出请求。请直接在 Clevera 中登出。 |
其他情况
你在 IdP 中移除的人员仍处于登录状态。 Clevera 不会从你的 IdP 同步用户，且 SSO 会话会保持登录状态，直到该人员主动登出。请在 团队设置 → 成员 中移除他们。
你域名下的某人在加入前使用密码注册了账号。 他们的账号不在你的工作区内，因此 SSO 会拒绝该账号。请邀请他们；在他们接受邀请后，SSO 即可生效，且在开启 Require SSO 后，他们的密码将失效。
通过 SSO 加入的新成员是编辑者，而非内容创作者。 你的默认角色是 内容创作者，但当他们首次登录时，所有创作者席位已满，因此他们以编辑者身份加入。请增加席位，然后在 团队设置 → 成员 中更改他们的角色。
通过 SSO 创建的成员需要密码（SSO 已关闭，或你的计划已变更）。他们可以在登录页面点击 忘记密码？ 来设置密码。
使用 SSO 登录桌面端应用。 桌面端应用会在你的浏览器中打开登录页面。输入你的工作邮箱，点击 Continue with 你的提供商并在 IdP 处登录：浏览器随后会将你带回应用。如果未跳转，请在应用中重新开始登录；由于浏览器已处于登录状态，它会直接连接。请参阅 登录桌面端应用。