單點登入故障排除

在配置或使用單點登入 (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-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 格式。