排查單點登入故障

本頁描述了常見的單點登入 (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 格式。