排解員工身分聯盟問題

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

檢查 IdP 回應

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

透過瀏覽器登入

如要檢查 IdP 傳回的回應，請使用選擇的工具產生 HAR 檔案。舉例來說，您可以使用 Google Admin Toolbox HAR 分析工具，該工具提供產生 HAR 檔案的操作說明，以及上傳和分析檔案的工具。

重要事項： 如果您是向使用者索取 HAR 檔案，請要求他們先清除 HAR 檔案中的所有個人識別資訊 (PII) 和 Cookie，再傳送檔案。

SAML

如要檢查 SAML IdP 回應，請執行下列步驟：

1. 在針對路徑為 /signin-callback 的網址記錄的 HAR 檔案中，找出 SAMLResponse 要求參數的值。
2. 使用您選擇的工具解碼，例如 Google Admin Toolbox Encode/Decode。

OIDC

如要檢查 OIDC IdP 回應，請執行下列步驟。這個方法不適用於程式碼流程。

1. 在針對路徑為 /signin-callback 的網址記錄的 HAR 檔案中，尋找 id_token 要求參數。
2. 使用您選取的 JWT 偵錯工具解碼。

gcloud CLI

如要使用 gcloud CLI 檢查 IdP 的回應，請複製執行 gcloud iam workforce-pools create-cred-config 指令時，您在 --credential-source-file 標記中傳遞的檔案內容，然後執行下列步驟：

SAML

使用您選擇的工具解碼 SAML IdP 回應，例如 Google Admin Toolbox Encode/Decode。

OIDC

使用您選擇的 JWT 偵錯工具，解碼 OIDC IdP 回應。

查看記錄

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

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

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

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

一般屬性對應錯誤

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

• 檢查 IdP 設定中的屬性 (也稱為權杖附加資訊)。在 Google Cloud 控制台中，確認屬性對應關係如何將 IdP 屬性轉換為 Google Cloud屬性，以及條件如何評估這些屬性，以允許或拒絕存取。

  1. 確認您具備 IAM 工作團隊集區編輯者 (roles/iam.workforcePoolEditor) 角色。
  2. 如要為員工身分聯盟啟用瀏覽器型登入流程，請將 https://auth.cloud.google/signin-callback/locations/global/workforcePools/POOL_ID/providers/PROVIDER_ID 新增至 IdP 的允許重新導向 URI 清單。

  3. 前往 Google Cloud 控制台的「Workforce Identity Pools」(員工身分集區) 頁面。

     前往「Workforce Identity Pools」(員工身分集區) 頁面
  4. 在集區清單中，按一下要驗證的集區名稱。
  5. 在「員工集區詳細資料」頁面中，按一下要驗證的 IdP 名稱。
  6. 在「供應商詳細資料」頁面中，按一下「偵錯 IdP 權杖」。
  7. 在「登入」對話方塊中，以測試使用者身分登入 IdP。

  「驗證提供者屬性」頁面會顯示對應的屬性和屬性條件結果。

  「IdP 權杖中的對應屬性」部分會顯示 Google 屬性 (例如 google.subject) 如何根據對應設定，從 IdP 權杖填入。如果對應不正確，系統會顯示錯誤圖示。

  「屬性條件」部分會顯示條件的布林結果。如果條件評估結果為 false，系統就會封鎖登入作業。

  如要查看完整斷言權杖，請按一下「查看完整權杖」。這會顯示 IdP 的原始 JSON 物件。使用 assertion.PROPERTY_NAME 格式，在對應中參照頂層屬性。

  如要修正錯誤，請編輯設定：

  1. 在「驗證提供者屬性」頁面中，按一下「編輯」圖示 。
  2. 進行必要變更。
  3. 如要開始新的測試並查看更新結果，請按一下「儲存並重新擷取權杖」。

• 檢查從 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 帳戶代表聯絡，要求提高配額。

登入錯誤

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

常見登入錯誤

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

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

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

SAML

'gcp-users' in assertion.attributes.groups

OIDC

'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. 更新屬性對應時，請注意下列事項：

   附註： 只有 google.groups 接受清單。

   • 如果導致錯誤的屬性是清單值，請找出替代的穩定字串值屬性。然後，更新屬性對應，方法是參照第一個項目，藉此使用該屬性。以先前的範例來說，如果 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，且這些對應至 員工身分識別集區供應商中的屬性，登入嘗試可能會失敗。 請管理員限制 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 Cloud 屬性 google.groups。

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

找不到 SCIM 租戶

如果使用者嘗試透過設定為使用 SCIM 的工作團隊身分集區提供者登入，但該提供者未設定任何 SCIM 租戶，就會發生這個錯誤。

發生這種情況時，使用者嘗試登入時會收到下列錯誤訊息：

There was an issue signing in with your identity provider.

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

1. 在 Google Cloud上設定 SCIM 租戶和權杖。
2. 將供應商連結至 SCIM 租戶。

400。發生錯誤

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

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

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

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

額外屬性登入錯誤

本節提供建議，協助修正使用額外屬性時發生的錯誤。

設定額外屬性時登入失敗

如果您已設定額外屬性，任何設定問題 (例如用戶端 ID、用戶端密鑰或簽發者 URI 不正確)，都會導致登入嘗試失敗。

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

1. 描述供應商 並確認用戶端 ID 和簽發者 URI 正確無誤。
2. 確認用戶端密鑰有效且尚未過期。
3. 在 IdP 中，確認應用程式具有必要權限。

系統會忽略 SAML 或 OIDC 聲明中的群組

設定額外屬性後，員工身分聯盟會忽略 SAML 或 OIDC 宣告中直接提供的任何群組資訊。而是只會使用透過反向通道擷取的群組 (例如使用 Microsoft Graph API)。

如果使用者未看到預期群組，請確認群組是否已透過後端通道正確擷取，以及屬性篩選器是否已正確設定。

OIDC 登入錯誤

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

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

如果 OIDC 工作團隊身分集區提供者無法連線至 OIDC 導覽文件或 JWKS URI，就會發生這項錯誤。

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

1. 說明供應商，並檢查已設定的 issuerUri。在核發者 URI 後方附加 /.well-known/openid-configuration，即可建構探索文件 URL。舉例來說，如果 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，IdP 的 SAML 回應中會顯示包含重新導向網址的 Recipient，如下所示：

<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 欄位是否正確。

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

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

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

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

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

注意： 即使您決定將其他屬性對應至屬性對應中的 google.subject，NameID 仍為必要。

請按照「檢查 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。

SCIM 佈建和同步處理錯誤

本節說明如何解決員工身分聯盟中的 SCIM 佈建和同步問題。

SCIM 權杖驗證失敗 (HTTP 401 或 403)

如果身分識別提供者 (IdP) 記錄回報驗證失敗 (HTTP 401 Unauthorized 或 HTTP 403 Forbidden)，就會發生這個錯誤。常見原因包括：

• SCIM 權杖遺失、無效或已過期。
• SCIM 權杖含有多餘的空格。
• 要求缺少 Authorization: Bearer <TOKEN> 標頭。
• SCIM 權杖的權限不足。

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

1. 在 IdP 佈建設定中，確認 SCIM 權杖與 Google Cloud 中產生的密鑰權杖相符，且沒有額外的空白字元。

2. 如果權杖遺失或無效，請產生新的 SCIM 權杖：

   注意： 每個 SCIM 租戶最多支援兩個 SCIM 權杖。如果已有兩個權杖，請先刪除現有權杖，再建立新權杖。詳情請參閱「SCIM 權杖建立失敗」一文。

   gcloud iam workforce-pools providers scim-tenants tokens create SCIM_TOKEN_ID \
       --workforce-pool="WORKFORCE_POOL_ID" \
       --provider="PROVIDER_ID" \
       --scim-tenant="SCIM_TENANT_ID" \
       --location="global"
   

   更改下列內容：

   • SCIM_TOKEN_ID：新 SCIM 權杖的 ID。
   • WORKFORCE_POOL_ID：員工身分集區的 ID。
   • PROVIDER_ID：工作團隊集區提供者的 ID。
   • SCIM_TENANT_ID：SCIM 租戶的 ID。

3. 更新 IdP 設定中的密鑰權杖。

超過速率限制 (HTTP 429 要求數過多)

如果 IdP 要求率超出 SCIM 租戶配額，就會發生這個錯誤。根據預設，每個機構的每個 SCIM 租戶每分鐘最多可發出 3,000 個寫入和讀取要求，相當於每秒 50 次查詢 (QPS)。詳情請參閱「配額與限制」一文。

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

1. 確認 IdP 同步要求比率在配額限制內。
2. 在 Google Cloud 控制台，依序前往「IAM & Admin」(IAM 與管理) >「配額」，然後篩選 iamscim.googleapis.com，即可監控配額用量。
3. 如需提高輸送量，請在 Google Cloud 主控台中申請增加配額。

無法建立 SCIM 租戶

如果 gcloud iam workforce-pools providers scim-tenants create 指令失敗，就會發生這個錯誤。

常見原因包括：

• 工作團隊集區中已有 SCIM 租戶。每個工作團隊集區僅支援一個 SCIM 租戶。
• 最近刪除的 SCIM 租戶仍處於 30 天的虛刪除期。
• 您不具備 IAM 工作團隊集區管理員 (roles/iam.workforcePoolAdmin) 角色。
• --claim-mapping 旗標含有不支援的一般運算語言 (CEL) 運算式。

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

1. 確認您具備 IAM 工作團隊集區管理員 (roles/iam.workforcePoolAdmin) 角色。

2. 列出現有的 SCIM 租戶，檢查是否已有租戶：

   gcloud iam workforce-pools providers scim-tenants list \
       --workforce-pool="WORKFORCE_POOL_ID" \
       --provider="PROVIDER_ID" \
       --location="global"
   

   更改下列內容：

   • WORKFORCE_POOL_ID：員工身分集區的 ID。
   • PROVIDER_ID：員工集區供應商的 ID。

3. 如果先前刪除的租戶是軟刪除，請使用 --hard-delete 旗標永久刪除：

   gcloud iam workforce-pools providers scim-tenants delete SCIM_TENANT_ID \
       --workforce-pool="WORKFORCE_POOL_ID" \
       --provider="PROVIDER_ID" \
       --location="global" \
       --hard-delete
   

   將 SCIM_TENANT_ID 替換為 SCIM 租戶的 ID。

4. 請確認 --claim-mapping 只使用支援的 CEL 運算式。詳情請參閱「對應權杖和 SCIM 屬性」。

無法建立 SCIM 權杖

如果 gcloud iam workforce-pools providers scim-tenants tokens create 指令失敗，就會發生這個錯誤。

常見原因包括：

• SCIM 租戶的 SCIM 權杖數量已達上限 (兩個)。
• 您不具備 IAM 工作團隊集區管理員 (roles/iam.workforcePoolAdmin) 角色。

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

1. 確認您具備 IAM 工作團隊集區管理員 (roles/iam.workforcePoolAdmin) 角色。

2. 列出現有 SCIM 權杖，檢查是否已達到兩個權杖的上限：

   gcloud iam workforce-pools providers scim-tenants tokens list \
       --workforce-pool="WORKFORCE_POOL_ID" \
       --provider="PROVIDER_ID" \
       --scim-tenant="SCIM_TENANT_ID" \
       --location="global"
   

   更改下列內容：

   • WORKFORCE_POOL_ID：員工身分集區的 ID。
   • PROVIDER_ID：員工集區供應商的 ID。
   • SCIM_TENANT_ID：SCIM 租戶的 ID。

3. 如果 SCIM 租戶已有兩個權杖，請刪除未使用的權杖或無效權杖：

   gcloud iam workforce-pools providers scim-tenants tokens delete SCIM_TOKEN_ID \
       --workforce-pool="WORKFORCE_POOL_ID" \
       --provider="PROVIDER_ID" \
       --scim-tenant="SCIM_TENANT_ID" \
       --location="global"
   

   將 SCIM_TOKEN_ID 替換為要刪除的 SCIM 權杖 ID。

4. 刪除權杖後，請重試建立新的 SCIM 權杖。

屬性對應重複衝突 (HTTP 409 Conflict)

如果 IdP 傳送的 google.subject 或 google.group 值重複，或 userName 或 displayName 值不唯一，IdP 記錄就會在同步期間回報 HTTP 409 Conflict，導致發生這項錯誤。

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

1. 在 IdP 管理員控制台中，確認對應至 google.subject 和 google.group 的屬性產生不重複的值。
2. 請確保每位使用者都有專屬 userName，且每個群組都有專屬 displayName。

Microsoft Entra ID PATCH 要求失敗

如果 Microsoft Entra ID 的使用者更新或 PATCH 要求失敗，可能是因為租戶網址缺少 ?aadOptscim062020 查詢參數，而 RFC 相容的 PATCH 要求必須包含這個參數。

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

1. 在 Microsoft Entra ID 中，前往企業應用程式，然後依序選取「Provisioning」(佈建) >「Manage provisioning」(管理佈建) >「Admin Credentials」(管理員憑證)。

2. 在「租戶網址」欄位中，將 ?aadOptscim062020 附加至基準 URI：

   https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID?aadOptscim062020
   

   將 SCIM_TENANT_UID 替換為 SCIM 租戶的專屬 ID。

3. 按一下「測試連線」，然後儲存設定。

無法根據使用者或群組授予存取權或分享檔案

如果同步處理的使用者無法存取 Google Cloud資源，或是無法在 Gemini Notebook Enterprise 中共用筆記本，或無法在 Gemini Enterprise 應用程式中共用代理程式，就會發生這個問題。

常見原因包括：

• IdP 無聲無息地發生同步處理失敗或延遲。
• 供應商 (--attribute-mapping) 與 SCIM 租戶 (--claim-mapping) 之間的聲明對應不一致。
• IdP 中對應至 google.subject 或 google.group 的屬性發生變更。 Google Cloud 預期對應至這些屬性的值不會變更。
• 供應商未啟用群組的 SCIM 用法。

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

1. 驗證同步處理和成員資格：確認使用者、群組和群組成員資格已成功同步至 Google Cloud：

   • 驗證使用者同步程序：

     curl -G -H "Authorization: Bearer SCIM_TOKEN" \
       "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users" \
       --data-urlencode 'filter=userName eq "USER_NAME"'
     

   • 驗證群組同步程序：

     curl -G -H "Authorization: Bearer SCIM_TOKEN" \
       "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \
       --data-urlencode 'filter=displayName eq "GROUP_NAME"'
     

   • 驗證群組成員資格：確認使用者是否為群組成員：

     curl -G -H "Authorization: Bearer SCIM_TOKEN" \
       "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \
       --data-urlencode 'filter=id eq "GROUP_ID" and members eq "USER_ID"'
     

     如果使用者是群組成員，回應會傳回 totalResults: 1。如果使用者不是成員，回應會傳回 totalResults: 0。

   更改下列內容：

   • SCIM_TOKEN：您的 SCIM 密碼權杖。
   • SCIM_TENANT_UID：SCIM 租戶的專屬 ID。
   • USER_NAME：已同步使用者的使用者名稱。
   • GROUP_NAME：同步群組的顯示名稱。
   • GROUP_ID：同步群組的 SCIM ID，會傳回至群組查詢回應的 id 欄位。
   • USER_ID：同步使用者的 SCIM ID， 在使用者查詢回應的 id 欄位中傳回。

2. 檢查聲明對應：確認供應商中對應至 google.subject 的屬性 (例如 google.subject=assertion.email.lowerAscii())，與 SCIM 租戶中對應的身分 (例如 google.subject=user.emails[0].value.lowerAscii()) 相符。由於聲明對應無法變更，如果對應不一致，請務必硬性刪除 SCIM 租戶，然後使用正確的對應重新建立。

3. 確保 ID 不變：確認對應至 google.subject 和 google.group 的 IdP 屬性未變更。 Google Cloud會將對應至這些屬性的值視為不可變更的 ID。如果 IdP 中的屬性值已變更，請還原 IdP 中的變更，或從 IdP 永久刪除受影響的使用者或群組，然後使用新值重新建立，確保 ID 與 Google Cloud預期相符。

4. 啟用 SCIM 群組使用情形：更新供應商，為群組啟用 SCIM：

   gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
       --workforce-pool="WORKFORCE_POOL_ID" \
       --location="global" \
       --scim-usage="enabled-for-groups"
   

   更改下列內容：

   • PROVIDER_ID：員工集區供應商的 ID。
   • WORKFORCE_POOL_ID：員工身分集區的 ID。

IdP 變更延遲或未反映

如果 IdP 更新使用者、群組成員資格或刪除項目後， Google Cloud中未立即顯示這些變更，就會發生這個問題。

由於 SCIM 採用推送機制，更新作業取決於 IdP 同步時間表。舉例來說，Microsoft Entra ID 大約每 40 分鐘會同步一次。

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

1. 等待 IdP 下一個排定的同步週期。
2. 如要立即套用變更，請在 IdP 管理員控制台中觸發隨選同步。

電子郵件地址格式有誤，導致使用者佈建失敗

如果特定使用者無法同步至 Google Cloud，且身分識別提供者 (IdP) 記錄回報 HTTP 400 Bad Request 錯誤，並顯示 invalidValue SCIM 錯誤，就會發生這個錯誤。

Google Cloud SCIM 規定每位使用者只能有一個工作電子郵件地址。如果 IdP 傳送多封電子郵件，或電子郵件類型不是 work，就會導致佈建失敗。

如要解決這個問題，請設定 IdP 屬性對應，只傳送主要工作電子郵件地址。

群組更新失敗 (不支援 HTTP PUT)

如果用戶端使用不支援的 HTTP PUT，群組更新就會失敗，並顯示這個錯誤。 Google Cloud SCIM API 僅支援 HTTP PATCH，用於更新群組。

如要解決這個問題，請將 IdP 或自訂用戶端設為使用 HTTP PATCH 更新群組。