排解 Workforce Identity 聯盟問題

本頁面說明如何解決員工身分聯盟的常見問題。

檢查 IdP 回應

本節說明如何檢查身分識別提供者 (IdP) 的回應，以排解本文列出的問題。

查看記錄

如要判斷 Google Cloud 是否與 IdP 通訊，以及查看交易資訊，您可以檢查 Cloud 稽核記錄。

如要查看記錄範例，請參閱稽核記錄範例。

工作團隊集區和提供者管理錯誤

本節提供建議，協助修正管理集區和供應商時可能遇到的常見錯誤。

一般屬性對應錯誤

如要排解工作團隊身分集區提供者屬性對應問題，請執行下列操作：

• 檢查 IdP 設定中的屬性 (也稱為聲明)。
• 檢查 IdP 產生的權杖。如要瞭解如何從 IdP 產生權杖，請參閱 IdP 的說明文件。
• 在 Cloud 稽核記錄中，查看員工身分聯盟的詳細稽核記錄。

詳細稽核記錄會記錄驗證和授權錯誤，以及員工身分聯盟收到的聲明。

建立員工身分識別集區供應商時，可以啟用詳細稽核記錄。如要啟用詳細稽核記錄，請在建立工作團隊身分集區提供者時新增 --detailed-audit-logging 旗標。

權限遭拒

如果嘗試設定工作團隊身分聯盟的使用者沒有 IAM 工作團隊集區管理員角色 (roles/iam.workforcePoolAdmin)，就會發生這個錯誤。

INVALID_ARGUMENT：缺少 OIDC 網頁單一登入設定

建立 OIDC 工作團隊身分集區提供者時，如果未設定 web-sso-response-type 和 web-sso-assertion-claims-behavior 欄位，就會發生下列錯誤：

ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) INVALID_ARGUMENT: Missing OIDC web single sign-on config.

如要解決這項錯誤，請按照「建立供應商」一節中的步驟，在建立 OIDC 工作團隊身分集區供應商時，適當設定欄位。

超過頻率限制，請稍後再試

當工作團隊集區資源達到配額上限時，就會發生這個錯誤。請與 Google Cloud 帳戶代表聯絡，要求提高配額。

登入錯誤

本節提供建議，協助修正員工身分聯盟使用者登入時可能遇到的常見錯誤。

常見登入錯誤

屬性條件拒絕使用指定憑證

如果未符合工作團隊身分識別集區提供者設定的屬性條件，就會發生這個錯誤。

舉例來說，請考量下列屬性條件：

'gcp-users' in assertion.attributes.groups

'gcp-users' in assertion.groups

在這種情況下，如果 IdP 在 groups 屬性中傳送的群組清單不包含 gcp-users，您就會看到錯誤訊息。

如要解決這項錯誤，請按照下列步驟操作：

1. 說明用於登入的供應商，並確認 attributeCondition 正確無誤。如要瞭解條件中支援的作業，請參閱語言定義。

2. 請按照「檢查 IdP 回應」一文中的步驟，查看 IdP 傳回的屬性，並確認屬性條件格式正確且準確。

3. 登入 IdP 管理控制台，檢查屬性條件中參照的 IdP 屬性是否設定正確。如有需要，請參閱 IdP 的說明文件。

對應的屬性必須為 STRING 類型

如果錯誤訊息中指定的屬性應為單一值的 STRING，但對應至屬性對應中的清單，就會發生這個錯誤。

舉例來說，假設 SAML 工作團隊身分集區提供者具有屬性對應 attribute.role=assertion.attributes.userRole。在 SAML 判斷中，Attribute 可以有多個 AttributeValue 標記，如下列範例所示。因此，所有 SAML 屬性都會視為清單，因此 assertion.attributes.userRole 是清單。

<saml:Attribute Name="userRole">
    <saml:AttributeValue>
      security-admin
    </saml:AttributeValue>
    <saml:AttributeValue>
      user
    </saml:AttributeValue>
</saml:Attribute>

在本例中，您可能會看到下列錯誤：

The mapped attribute 'attribute.role' must be of type STRING

如要解決這個問題，請按照下列步驟操作：

1. 說明用於登入的供應商，並找出 attributeMapping 中設定的 IdP 屬性。請根據錯誤訊息中顯示的屬性檢查屬性。在上述範例中，名為 userRole 的 IdP 屬性會對應至 role 屬性，而 role 屬性會顯示在上述錯誤範例中。

2. 請按照下列指引更新屬性對應：

   • 如果造成錯誤的屬性是清單值，請找出替代的穩定字串值屬性。然後，更新屬性對應，方法是參照第一個項目，藉此使用該項目。以前述範例為例， 如果 myRole 識別為替代的單一值 IdP 屬性， 則屬性對應會是：

     attribute.role=assertion.attributes.myRole[0]
     

   • 或者，如果屬性已知為單一值，請更新屬性對應，使用清單中的第一個項目。以前述範例來說，如果 userRole 只包含一個角色，您可以採用下列對應：

     attribute.role=assertion.attributes.userRole[0]
     

   • 如要從清單中取得單一值且穩定的 ID，請參閱「語言定義」，並據此更新屬性對應。

請參閱「檢查 IdP 回應」一節，查看 IdP 傳回的回應。

無法從指定憑證取得 google.subject 的值

如果無法使用您在工作團隊身分集區提供者設定中設定的屬性對應，對應必要聲明 google.subject，就會發生這項錯誤。

如要解決這項錯誤，請按照下列步驟操作：

1. 描述提供者，並檢查 attributeMapping。找出為 google.subject 設定的對應。如果對應不正確，請更新工作團隊身分識別集區提供者。

2. 請參閱「檢查 IdP 回應」一節，查看 IdP 傳回的回應。檢查屬性對應中對應至 google.subject 的 IdP 回應屬性值。

   如果值為空白或不正確，請登入 IdP 的管理控制台，並檢查已設定的屬性。請檢查受影響的使用者在 IdP 中是否具有對應的屬性資料。更新 IdP 設定，以相應修正屬性或使用者資訊。

3. 重新嘗試登入。

對應屬性的大小超過上限

當同盟使用者嘗試登入時，發生下列錯誤：

The size of the entire mapped attributes exceeds the 16 KB limit.

如要解決這個問題，請要求 IdP 管理員減少 IdP 發出的屬性數量。您的 IdP 只需要發出將使用者聯合至 Google Cloud所需的屬性。如要進一步瞭解屬性對應限制，請參閱屬性對應。

舉例來說，如果 IdP 發出大量 google.groups，且這些 google.groups 對應至員工身分識別集區供應商中的屬性，登入嘗試可能會失敗。請管理員限制 IdP 發出的群組數量。

群組數量超過上限

當同盟使用者嘗試登入時，發生下列錯誤：

The current count of GROUPS_COUNT mapped attribute google.groups exceeds the GROUPS_COUNT_LIMIT count limit. Either modify your attribute mapping or the incoming assertion to produce a mapped attribute that has fewer than GROUPS_COUNT_LIMIT groups.

這個錯誤包含下列值：

• GROUPS_COUNT：IdP 發出的群組數量

• GROUPS_COUNT_LIMIT： Google Cloud的群組數量上限

當 IdP 發出的群組數量超過Google Cloud的限制時，就會發生這項錯誤。群組會使用 google.groups 屬性對應至 Google Cloud 。

如要解決這個問題，請要求管理員減少 IdP 發出的群組數量。您的 IdP 只需要發出用於將使用者同盟至 Google Cloud的群組。進一步瞭解屬性對應中的群組相關限制。

400。發生錯誤

如果系統未如預期收到要求，或要求格式有誤，就會發生這項錯誤。

如要解決這項錯誤，請按照下列步驟操作：

1. 請按照「告知使用者如何登入」一節中的步驟操作，確認您是否按照正確步驟登入。

2. 比較工作團隊身分集區提供者設定與 IdP 設定。

OIDC 登入錯誤

本節提供建議，協助修正員工身分聯盟使用者登入時可能遇到的 OIDC 特定錯誤。

連線至指定憑證核發機構時發生錯誤

如果 OIDC 工作團隊身分集區提供者無法存取 OIDC 探索文件或 JWKS URI，就會發生這個錯誤。

如要解決這項錯誤，請按照下列步驟操作：

1. 描述供應商，並檢查已設定的 issuerUri。在核發者 URI 後方附加 /.well-known/openid-configuration，即可建構探索文件網址。舉例來說，如果 issuerUri 為 https://example.com，則探索文件網址為 https://example.com/.well-known/openid-configuration。

2. 在無痕瀏覽視窗中開啟探索文件網址。

   1. 如果網址無法開啟，或瀏覽器顯示 404 錯誤，請參閱 IdP 的說明文件，找出正確的簽發者 URI。如有必要，請更新工作團隊身分集區提供者中的 issuerUri。

      如果 IdP 是在本機執行，請參閱 IdP 的說明文件，瞭解如何佈建 IdP，以便透過網際網路存取。

   2. 如果網址可以開啟，請檢查下列情況：

      1. 在放送探索文件前，請確認網址不會重新導向太多次。如果確實如此，請諮詢 IdP 管理員，以解決問題。
      2. 檢查 IdP 回應時間。請洽詢 IdP 管理員，以縮短回應延遲時間。
      3. 開啟的探索文件應為 JSON 格式。

      4. 在 JSON 中尋找 jwks_uri 欄位。

         1. 確認相關聯的網址值也會開啟。
         2. 確認網址符合本指南稍早所述的條件。

   3. 重新嘗試登入。

SAML 登入錯誤

本節提供建議，協助修正員工身分聯盟使用者登入時可能遇到的 SAML 特定錯誤。

無法驗證 SAMLResponse 中的簽章

如果無法使用您在工作團隊身分集區供應商中設定的 IdP 中繼資料 XML 提供的任何 X.509 憑證，驗證 IdP 回應中的簽章，SAML 工作團隊身分集區供應商就會發生這個錯誤。造成這項錯誤的常見原因，是 IdP 上的驗證憑證已輪替，但您未更新工作人員身分集區供應商設定，加入最新的 IdP 中繼資料 XML 檔案。

如要解決這項錯誤，請按照下列步驟操作：

1. 選用：按照「檢查 IdP 回應」一文中的步驟操作，查看 IdP 傳回的回應，並找出其中的 X509Certificate 欄位。說明您用來登入的提供者，並檢查工作團隊身分集區提供者設定的 idpMetadataXml 值中是否有 X509Certificate 欄位。將憑證與 IdP 傳回的回應中顯示的憑證進行比較。憑證必須相符。

2. 登入 IdP 的管理控制台，然後下載最新的中繼資料 XML。

3. 使用下載的 IdP 中繼資料 XML 更新工作團隊身分集區提供者。

4. 重新嘗試登入。

SAML 聲明中的收件者未設為正確的 ACS 網址

如果 IdP 回應的 SubjectConfirmationData 標記中，Recipient 欄位的值不正確，SAML 工作團隊身分集區提供者就會發生這個錯誤。

如要解決這項錯誤，請更新 IdP 設定中的 Recipient URL / Redirect URL 或對等欄位，使用「在 IdP 中設定重新導向網址」一文所述的重新導向網址，然後重試登入。

按照「檢查 IdP 回應」一文中的步驟，查看 IdP 傳回的回應，並確認 Recipient 欄位是否正確。

舉例來說，如果是工作團隊身分集區提供者 locations/global/workforcePools/example-pool/providers/example-provider，包含重新導向網址的 Recipient 會顯示在 IdP 的 SAML 回應中，如下所示：

<SubjectConfirmationData Recipient="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

SAMLResponse 目的地與 RP 回呼網址不符

如果 IdP 回應的 Response 標記中，Destination 欄位的值不正確，SAML 工作團隊身分集區提供者就會發生這個錯誤。

如要解決這項錯誤，請更新 IdP 設定中的 Destination URL / Redirect URL 或對等欄位，改用「在 IdP 中設定重新導向網址」一文所述的重新導向網址。

按照「檢查 IdP 回應」一節中的步驟操作，查看 IdP 傳回的回應，並確認 Destination 欄位是否正確。

舉例來說，如果是工作團隊身分集區提供者 locations/global/workforcePools/example-pool/providers/example-provider，IdP 的 SAML 回應中會顯示包含重新導向網址的 Destination，如下所示：

<Response Destination="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

無效的聲明：缺少或空白的 NameID

如果從 IdP 收到的 SAML 回應不含 NameId 欄位或該欄位的值為空白，就會發生這個錯誤。

如要解決這項錯誤，請參閱 IdP 文件，將 IdP 設定為傳送 NameID，也就是 SAML 聲明的主體，通常是正在驗證的使用者。

請按照「檢查 IdP 回應」一文的步驟操作，查看 IdP 傳回的回應和其中設定的 NameID。

所有 <AudienceRestriction> 都應包含 SAML RP 實體 ID

如果 IdP 傳送的 SAML 回應中的 AudienceRestriction 標記未設定 Audience 標記，且該標記的值代表工作團隊身分識別集區供應商的實體 ID，就會發生這個錯誤。

如要解決這項錯誤，請按照下列步驟操作：

1. 請參閱 IdP 說明文件，瞭解如何在 SAML 回應中傳送的 AudienceRestriction 標記中設定對象。一般來說，設定 IdP 時，會透過設定 Entity ID 或 Audience 欄位來設定目標對象。請參閱「建立工作團隊身分識別集區提供者」的 SAML 專區，瞭解應設定的值 SP Entity ID。

2. 更新 IdP 設定後，請重試登入。

請按照「檢查 IdP 回應」一文的步驟操作，查看 IdP 傳回的回應，以及其中設定的 AudienceRestriction。