单点登录故障排除
在配置或使用单点登录 (SSO) 时，您可能会遇到问题，这些问题可能源于您的身份提供者 (IdP) 或 Docker 配置。以下章节描述了一些常见的 SSO 错误及可能的解决方案。
检查错误
如果您遇到 SSO 问题，请首先检查 Docker Admin Console 和您的身份提供者 (IdP) 中是否存在错误。
检查 Docker 错误日志
- 登录到 Admin Console 并选择您的组织。
- 选择 SSO 和 SCIM。
- 在 SSO 连接表中，选择操作菜单，然后选择查看错误日志。
- 要查看特定错误的更多详细信息，请在错误消息旁边选择查看错误详情。
- 记下您在此页面上看到的任何错误，以便进行进一步的故障排除。
检查您的 IdP 中的错误
- 检查您的 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可能原因
- 用户未分配给组织：如果 Just-in-Time (JIT) 用户配置已禁用，用户可能未分配给您的组织。
- 用户未被邀请加入组织：如果 JIT 已禁用且您不想启用它，用户必须手动邀请。
- SCIM 用户配置配置错误：如果您使用 SCIM 进行用户配置，它可能未正确同步您的 IdP 中的用户。
解决方案
启用 JIT 用户配置
启用 SSO 时，JIT 默认启用。如果您已禁用 JIT 并需要重新启用它
- 登录到 Admin Console 并选择您的组织。
- 选择 SSO 和 SCIM。
- 在 SSO 连接表中，选择操作菜单，然后选择启用 JIT 用户配置。
- 选择启用进行确认。
手动邀请用户
禁用 JIT 后，用户通过 SSO 身份验证时不会自动添加到您的组织。要手动邀请用户，请参阅邀请成员
配置 SCIM 用户配置
如果您已启用 SCIM，请按照以下步骤对 SCIM 连接进行故障排除
- 登录到 Admin Console 并选择您的组织。
- 选择 SSO 和 SCIM。
- 在 SSO 连接表中，选择操作菜单，然后选择查看错误日志。要查看特定错误的更多详细信息，请在错误消息旁边选择查看错误详情。记下您在此页面上看到的任何错误。
- 导航回 Admin Console 的 SSO 和 SCIM 页面，并验证您的 SCIM 配置
- 确保您的 IdP 中的 SCIM Base URL 和 API 令牌与 Docker Admin Console 中提供的一致。
- 验证 SCIM 在 Docker 和您的 IdP 中均已启用。
- 确保从您的 IdP 同步的属性与 Docker 支持的 SCIM 属性匹配。
- 尝试通过您的 IdP 配置一个测试用户来测试用户配置，并验证他们是否出现在 Docker 中。
连接未启用 IdP 发起的登录
错误消息
出现此问题时，常见的错误消息如下
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.可能原因
当通过 Just-in-Time (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 格式。