排除单点登录故障

故障排除
目录

在配置或使用单点登录 (SSO) 时，您可能会遇到一些问题，这些问题可能源于您的身份提供商 (IdP) 或 Docker 配置。以下部分介绍了如何在 Docker 管理员控制台中查看错误消息以及一些常见错误和可能的解决方案。您还可以查看身份提供商的文档，了解是否可以在其服务中查看错误日志。

查看 SSO 和 SCIM 错误日志

  1. 登录 管理员控制台。

  2. 在左侧导航下拉菜单中选择您的组织或公司，然后选择 **SSO 和 SCIM**。

    注意

    当组织是公司的一部分时，您必须选择公司并在公司级别查看该组织的 SSO 连接。

  3. 在 SSO 连接表中，选择 **操作** 图标和 **查看错误日志**。将显示 **连接错误** 页面，其中列出了过去 7 天内发生的错误。

  4. 在 **连接错误** 页面中，选择错误消息旁边的 **查看错误详情** 以获取更多详细信息。将出现一个包含更多详细信息的 JSON 对象的模态窗口。

常见的 SSO 错误和解决方案

查看 SSO 和 SCIM 错误日志，然后使用以下部分来解决常见的配置错误。

未为连接启用 IdP 发起的登录

此问题的错误日志中会出现类似于以下内容的错误消息。

IdP-Initiated sign in is not enabled for connection '$ssoConnection'.

Docker 不支持 IdP 发起的 SAML 流。当用户尝试从 IdP 进行身份验证时，例如使用仪表板上的 Docker SSO 应用磁贴，可能会发生此错误。

可能的解决方案

  • 用户必须从 Docker 应用（Hub、Desktop 等）启动身份验证。用户需要输入他们的电子邮件地址，他们将被重定向到其域配置的 SSO IdP。
  • （可选）将 Docker SSO 应用配置为在您的 IdP 上对用户不可见，以便用户不会尝试从那里启动身份验证。

组织中席位不足

此问题的错误日志中会出现类似于以下内容的错误消息。

Not enough seats in organization '$orgName'. Add more seats or contact your administrator.

当尝试通过 SSO 即时配置或 SCIM 将用户配置到组织中，但组织没有可用的用户席位时，可能会发生此错误。

可能的解决方案

  • 向组织添加更多 Docker Business 订阅席位。有关详细信息，请参阅 向您的订阅添加席位。
  • 从您的组织中移除一些用户或未决邀请以腾出更多席位。有关详细信息，请参阅 管理组织成员。

未验证用于 SSO 连接的域名

此问题的错误日志中会出现类似于以下内容的错误消息。

Domain '$emailDomain' is not verified for your SSO connection. Contact your company administrator. TraceID: XXXXXXXXXXXXXX

如果 IdP 通过 SSO 对用户进行了身份验证，并且返回给 Docker 的 UPN 与 Docker 中配置的 SSO 连接关联的任何已验证域名都不匹配，则会发生此错误。

可能的解决方案

  • 确保 IdP SSO 连接正在作为断言属性的一部分返回正确的 UPN 值（属性映射）。
  • 添加并验证 IdP 用作 UPN 的所有域名和子域名，并将它们与您的 Docker SSO 连接关联。有关详细信息，请参阅 配置单点登录。

找不到会话

此问题的错误日志中会出现类似于以下内容的错误消息。

We couldn't find your session. You may have pressed the back button, refreshed the page, opened too many sign-in dialogs, or there is some issue with cookies. Try signing in again. If the issue persists, contact your administrator.

此错误通常在用户按下浏览器的后退或刷新按钮时在身份验证流程中发生。这会导致登录流程丢失初始身份验证请求的跟踪，而此请求是完成所有身份验证流程所必需的。

可能的解决方案

  • 登录期间避免按下后退或刷新按钮。
  • 关闭浏览器的标签页，并从应用（Docker Desktop、Hub 等）重新开始身份验证流程。

用户未分配给组织

此问题的错误日志中会出现类似于以下内容的错误消息。

User '$username' is not assigned to this SSO organization. Contact your administrator. TraceID: XXXXXXXXXXXXX

如果禁用了 SSO 即时 (JIT) 配置，则会发生此错误。JIT 配置确保用户在通过 SSO 进行身份验证后添加到组织中。可以可选地禁用 JIT 配置，以防止用户自动占用组织中的席位，或者当 SCIM 用作用户配置的唯一选项时。

可能的解决方案

  • 查看您的 SSO 连接配置，并启用 JIT 配置以在通过 SSO 进行身份验证后将所有用户添加到组织中。有关详细信息，请参阅 即时配置。
  • 如果要保持 JIT 配置禁用，则通过手动邀请将用户添加到组织。下次用户通过 SSO 进行身份验证时，他们将被添加到组织，因为他们已被邀请。更多详情，请参见 管理组织成员。
  • 如果 SCIM 应该配置用户，请确保控制 SCIM 配置的 IdP 已正确配置为在用户被分配到应用程序后立即与 Docker 同步用户。更多详情，请参阅您的身份提供商的文档。

Name ID 不是电子邮件地址

此问题的错误日志中会出现类似于以下内容的错误消息。

The name ID sent by the identity provider is not an email address. Contact your company administrator.

此错误可能发生在 SAML 身份验证期间，当您的 IdP 发送回的名称 ID (UPN) 不符合所需电子邮件地址格式时。Docker SSO 应用程序要求名称标识符是用户的首要电子邮件地址。

可能的解决方案

  • 确保名称 ID 属性格式为 EmailAddress。