排查单点登录故障

本页描述了常见的单点登录 (SSO) 错误及其解决方案。问题可能源于身份提供商 (IdP) 配置或 Docker 设置。

检查错误

如果您遇到 SSO 问题，请首先检查 Docker 和您的身份提供商是否有错误。

检查 Docker 错误日志

登录 Docker Home 并选择您的组织。
选择管理控制台，然后选择SSO 和 SCIM。
在 SSO 连接表中，选择 Action 菜单，然后选择 View error logs。
有关特定错误的更多详细信息，请在错误消息旁边选择 View error details。
记录此页面上看到的任何错误以供进一步排查。

检查身份提供商错误

查看 IdP 的日志或审计跟踪，了解任何失败的身份验证或配置尝试。
确认您的 IdP 的 SSO 设置与 Docker 中提供的值匹配。
如果适用，确认您已正确配置用户配置并在 IdP 中启用。
如果适用，验证您的 IdP 是否正确映射了 Docker 所需的用户属性。
尝试从您的 IdP 配置一个测试用户，并验证他们是否出现在 Docker 中。

如需进一步排查，请查阅您的 IdP 文档或联系其支持团队。

组格式不正确

错误信息

当出现此问题时，常见的错误消息如下：

Some of the groups assigned to the user are not formatted as '<organization name>:<team name>'. Directory groups will be ignored and user will be provisioned into the default organization and team.

原因

您的身份提供商 (IdP) 中的组名称格式不正确：Docker 要求组遵循 <organization>:<team> 格式。如果分配给用户的组不遵循此格式，它们将被忽略。
IdP 和 Docker 组织之间的组不匹配：如果您的 IdP 中的组在 Docker 中没有相应的团队，它将无法识别，并且用户将被放置在默认组织和团队中。

受影响的环境

使用 Okta 或 Azure AD 等 IdP 设置 Docker 单点登录
在 Docker 中使用基于组的角色分配的组织

重现步骤

要重现此问题

尝试使用 SSO 登录 Docker。
用户在 IdP 中分配了组，但未放置到预期的 Docker 团队中。
查看 Docker 日志或 IdP 日志以查找错误消息。

解决方案

更新 IdP 中的组名称

前往您的 IdP 的组管理部分。
检查分配给受影响用户的组。
确保每个组都遵循所需的格式：<organization>:<team>
更新任何格式不正确的组以匹配此模式。
保存更改并重试使用 SSO 登录。

用户未分配到组织

错误信息

当出现此问题时，常见的错误消息如下：

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

原因

用户未分配到组织：如果即时 (JIT) 预配已禁用，则用户可能未分配到您的组织。
用户未被邀请加入组织：如果 JIT 已禁用且您不想启用它，则必须手动邀请用户。
SCIM 预配配置错误：如果您使用 SCIM 进行用户预配，它可能无法正确同步您的 IdP 中的用户。

解决方案

启用 JIT 预配

启用 SSO 后，JIT 默认启用。如果您已禁用 JIT 且需要重新启用它

登录 Docker Home 并选择您的组织。
选择管理控制台，然后选择SSO 和 SCIM。
在 SSO 连接表中，选择 Action 菜单，然后选择 Enable JIT provisioning。
选择 Enable 确认。

手动邀请用户

当 JIT 禁用时，用户通过 SSO 身份验证时不会自动添加到您的组织。要手动邀请用户，请参阅邀请成员

配置 SCIM 预配

如果您已启用 SCIM，请按照以下步骤排查 SCIM 连接故障

登录 Docker Home 并选择您的组织。
选择管理控制台，然后选择SSO 和 SCIM。
在 SSO 连接表中，选择 Action 菜单，然后选择 View error logs。有关特定错误的更多详细信息，请在错误消息旁边选择 View error details。记录此页面上看到的任何错误。
导航回管理控制台的 SSO 和 SCIM 页面，并验证您的 SCIM 配置
- 确保您的 IdP 中的 SCIM 基本 URL 和 API 令牌与 Docker 管理控制台中提供的一致。
- 验证 Docker 和您的 IdP 中是否都启用了 SCIM。
确保从您的 IdP 同步的属性与 Docker 的 SCIM 支持属性匹配。
通过尝试从您的 IdP 预配测试用户来测试用户预配，并验证他们是否出现在 Docker 中。

错误信息

当出现此问题时，常见的错误消息如下：

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

原因

Docker 不支持 IdP 发起的 SAML 流程。当用户尝试从您的 IdP 进行身份验证时，例如使用登录页面上的 Docker SSO 应用程序磁贴，就会发生此错误。

解决方案

从 Docker 应用程序进行身份验证

用户必须从 Docker 应用程序（Hub、Desktop 等）发起身份验证。用户需要在 Docker 应用程序中输入他们的电子邮件地址，然后他们将被重定向到为其域配置的 SSO IdP。

隐藏 Docker SSO 应用程序

您可以从 IdP 中的用户隐藏 Docker SSO 应用程序。这可以防止用户尝试从 IdP 仪表板开始身份验证。您必须在 IdP 中隐藏和配置此功能。

组织中席位不足

错误信息

当出现此问题时，常见的错误消息如下：

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

原因

当组织通过即时 (JIT) 预配或 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 连接关联的任何已验证域不匹配，则会发生此错误。

解决方案

验证 UPN 属性映射

确保 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 等）重新开始身份验证流程。

Name ID 不是电子邮件地址

错误信息

当出现此问题时，常见的错误消息如下：

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

原因

以下原因可能会导致此问题

IdP 发送的 Name ID (UPN) 不符合 Docker 要求的电子邮件格式。
Docker SSO 要求 Name ID 为用户的主电子邮件地址。

解决方案

在您的 IdP 中，确保 Name ID 属性格式正确

验证您的 IdP 中的 Name ID 属性格式是否设置为 EmailAddress。
调整您的 IdP 设置以返回正确的 Name ID 格式。