排解員工身分聯盟問題

如要診斷及解決員工身分聯盟中的驗證和佈建錯誤,請檢查識別資訊提供者 (IdP) 回應和 Cloud 稽核記錄。這些檢查可協助您找出設定不符的問題,並還原使用者存取權。

檢查 IdP 回應

本節說明如何檢查識別資訊提供者 (IdP) 的回應,排解本文列出的問題。

透過瀏覽器登入

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

SAML

如要檢查 SAML IdP 回應,請按照下列步驟操作:

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

OIDC

如要檢查 OIDC IdP 回應,請按照下列步驟操作。這個方法不適用於程式碼流程。

  1. 在 HAR 檔案中,找出針對路徑為 /signin-callback 的網址記錄的 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 設定中的屬性 (又稱權杖附加資訊)。確認屬性對應如何將 IdP 屬性轉換為 Google Cloud屬性,以及條件如何評估這些屬性,以便在 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. 在「Workforce pool details」(員工集區詳細資料) 頁面中,按一下要驗證的 IdP 名稱。
    6. 在「Provider Details」頁面中,按一下「Debug IdP token」。
    7. 在「Sign in」(登入) 對話方塊中,以測試使用者身分登入 IdP。

    「Validate your provider attributes」(驗證提供者屬性) 頁面會顯示對應的屬性和屬性條件結果。

    「Mapped attributes from your IdP token」(IdP 權杖中的對應屬性) 區段會根據對應設定,顯示 Google 屬性 (例如 google.subject) 如何從 IdP 權杖填入。如果對應不正確,系統會顯示錯誤圖示。

    「Attribute condition」(屬性條件) 區段會顯示條件的布林值結果。如果條件評估結果為 false,系統就會封鎖登入。

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

    如要修正錯誤,請編輯設定:

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

  • 檢查 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 工作團隊身分集區提供者時,正確設定欄位。

超過頻率限制 (HTTP 429)

如果貴組織的工作團隊集區權杖交換配額 (sts.googleapis.com/workforce_requests) 已用盡,就會發生這個錯誤。

這項配額會對每個組織強制執行,預設為每分鐘 1,000 項要求。這項配額由組織中的所有工作團隊集區、供應商、使用者和自動化工作負載共用,因此單一高頻率用戶端可能會導致整個組織 (包括管理員) 發生 HTTP 429 錯誤。詳情請參閱「配額與限制」。

事前準備

如果您透過員工身分聯盟登入,Google Cloud CLI 指令及新的 Google Cloud 控制台登入工作階段可能會受到限制。如要在配額用盡時執行這些步驟,請使用不透過員工身分聯盟驗證的管理員帳戶,例如緊急存取 Cloud Identity 超級管理員帳戶。

步驟 1:確認配額已用盡

在 Google Cloud 控制台中,依序前往「IAM & Admin」(IAM 與管理) >「Quotas」(配額),將資源選取器設為貴組織 (而非專案),然後選取「Workforce Pool token exchange requests」(員工集區權杖交換要求)。

前往「IAM & Admin Quotas」(IAM 與管理員配額) 頁面

步驟 2:找出流量來源

受限制的權杖交換會在憑證驗證前遭到拒絕,因此不會顯示在 Cloud 稽核記錄中。如要找出流量來源,請使用下列其中一種方法:

  • 查看 IdP 登入記錄:在 Okta 系統記錄或 Microsoft Entra ID 登入記錄等識別資訊提供者中,檢查是否有特定應用程式、服務主體或使用者帳戶以異常高的頻率核發權杖。
  • 檢查工作負載設定:檢查自動化工作、CI/CD 管道、Daemon 代理程式,以及使用員工憑證設定檔設定的 GKE 工作負載。

步驟 3:限制流量

請選擇能解決流量問題,且對員工影響最小的選項:

動作對使用者的影響
停止工作負載 (將 Deployment 縮減至零、刪除工作,或撤銷 IdP 中的用戶端) 無,建議在可識別特定工作負載時使用。
停用工作團隊集區的程式輔助登入功能 封鎖集區的所有程式輔助權杖交換,包括真人使用者的 gcloud 和 kubectl。 Google Cloud 控制台登入功能仍可正常運作。

如果無法立即找到工作負載,建議您採取這項做法。
停用集區或提供者 封鎖整個工作團隊集區或提供者的驗證。

如要停用程式輔助登入功能,請按照下列步驟操作:

gcloud iam workforce-pools update WORKFORCE_POOL_ID \
    --location=global \
    --disable-programmatic-signin

停止有問題的工作負載後,請使用 --no-disable-programmatic-signin 旗標執行指令,重新啟用程式輔助登入。

步驟 4:防止問題再次發生

  • 將自動化工作負載遷移至 Workload Identity Federation。
  • 以指數輪詢和抖動方式重試遭節流的要求。緊湊的重試迴圈會加深飽和度,並延長服務中斷時間。
  • 在配額達到 80% 時發出快訊,在配額用盡前發出警告。
  • 如果您的穩定狀態需求經常超出限制,建議您在需要之前,先透過 Cloud Customer Care 申請提高配額。

登入錯誤

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

常見登入錯誤

指定憑證因屬性條件而遭拒

如果工作團隊身分集區提供者設定的屬性條件不符合,就會發生這項錯誤。

舉例來說,假設有以下屬性條件:

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

如果 SAML 工作團隊身分集區提供者預期錯誤訊息中指定的屬性為單一值的 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 傳回的回應。檢查 IdP 回應中對應至屬性對應中 google.subject 的屬性值。

    如果值為空白或不正確,請登入 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.groups 屬性對應至 Google Cloud 。

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

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,即可建構導覽文件網址。舉例來說,如果 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 中的簽章

如果 SAML 工作團隊身分集區提供者發生這項錯誤,代表系統無法使用您在工作團隊身分集區提供者中設定的 IdP 中繼資料 XML,透過其中提供的任何 X.509 憑證驗證 IdP 回應上的簽章。這項錯誤的常見原因是 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,包含 Destination 的重新導向網址會顯示在 IdP 的 SAML 回應中,如下所示:

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

無效的宣告:缺少 NameID 或 NameID 空白

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

如要解決這個錯誤,請參閱 IdP 說明文件,設定傳送 NameID (SAML 聲明的主體,通常是正在驗證的使用者)。

請按照「檢查 IdP 回應」一節的步驟操作,查看 IdP 傳回的回應和設定的 NameID。

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

如果 IdP 的 SAML 回應中,AudienceRestriction 標記未設定 Audience 標記,且值代表工作團隊身分集區提供者的實體 ID,就會發生這項錯誤。

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

  1. 請參閱 IdP 說明文件,瞭解如何設定 IdP 在 SAML 回應中傳送的 AudienceRestriction 標記目標對象。一般來說,您可以在 IdP 設定中設定 Entity ID 或 Audience 欄位,藉此設定目標對象。請參閱「建立工作團隊身分集區提供者」的 SAML 部分,瞭解應設定的值 SP Entity ID。

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

請按照「檢查 IdP 回應」一節的步驟操作,查看 IdP 傳回的回應和設定的 AudienceRestriction。

SCIM 登入錯誤

本節說明如何解決員工身分聯盟使用者登入時,可能遇到的 SCIM 相關錯誤。

找不到 SCIM 租戶

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

發生這種情況時,使用者嘗試登入會看到以下錯誤訊息:

There was an issue signing in with your identity provider.

如要解決這項錯誤,請對識別資訊提供者執行下列操作:

  1. 在 Google Cloud (Microsoft Entra ID | Okta) 設定 SCIM 租戶和權杖。
  2. 將供應商連結至 SCIM 租戶 (Microsoft Entra ID | Okta)。

為使用者和群組啟用 SCIM 後,登入失敗

如果將 --scim-usage 設為 enabled-for-users-groups,網頁登入和 OAuth 登入嘗試可能會失敗,並顯示下列錯誤訊息:

  • 找不到 SCIM 使用者或使用者未啟用:

    • 錯誤:The workforce identity pool provider is configured to use identity information that is provided using SCIM, but a SCIM User could not be associated with the google.subject from the given credential. 或 ... the SCIM User associated with the google.subject from the given credential is not active.
    • 原因:使用者尚未透過 SCIM 同步至 Google Cloud 、供應商中對應的google.subject與 SCIM 使用者對應不符,或使用者在 IdP 中標示為active: false。
    • 解決方法:在 IdP 中,確認使用者是透過 SCIM 佈建,且狀態為「有效」,並確認 google.subject 的供應商屬性對應和 SCIM 租戶權杖附加資訊對應參照相同身分。
  • CEL 評估或權杖附加資訊對應錯誤:

    • 錯誤:Failed to map attributes from the given credential with SCIM Tenant config.
    • 原因:--claim-mapping 中的 CEL 運算式無效,或在評估期間失敗。
    • 解決方法:檢查 SCIM 租戶的 --claim-mapping 運算式,確保 CEL 語法有效,且支援屬性名稱。
  • 超出對應屬性大小限制:

    • 錯誤:The size of SCIM mapped attribute google.display_name exceeds the 100 bytes limit. 或 The size of entire SCIM mapped attributes exceeds the 16 kB limit.
    • 原因:個別對應屬性超過大小限制 (例如 google.display_name 為 100 個位元組、google.posix_username 為 32 個位元組、google.subject 為 127 個位元組),或序列化對應宣告總計超過 16 kB。
    • 解決方法:調整 SCIM 租戶權杖附加資訊對應,或更新 IdP 屬性值,使其符合允許的限制。

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 權杖:

    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 次要求,相當於每秒查詢次數 (QPS)。詳情請參閱「配額與限制」一文。

請按照下列步驟解決這個問題:

  1. 確認 IdP 同步處理要求率在配額限制內。
  2. 在 Google Cloud 控制台,依序前往「IAM & Admin」(IAM 與管理) >「Quotas」(配額),然後篩選iamscim.googleapis.com,監控配額用量。
  3. 如需更高的處理量,請在 Google Cloud 控制台要求提高配額。

無法建立 SCIM 租戶

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

常見原因包括:

  • 工作團隊集區中已有 SCIM 租戶。每個工作團隊集區僅支援一個 SCIM 租戶。
  • 最近刪除的 SCIM 租戶仍處於 30 天的虛刪除期間。
  • 您不具備身分與存取權管理工作團隊集區管理員 (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 權杖

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

常見原因包括:

  • SCIM 租戶的 SCIM 權杖數量已達上限 (兩個)。
  • 您不具備身分與存取權管理工作團隊集區管理員 (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 衝突)

如果識別資訊提供者 (IdP) 記錄在同步處理期間回報 HTTP 409 Conflict,就會發生這項錯誤,因為 IdP 傳送了重複的 google.subject 或 google.group 值,或不重複的 userName 或 displayName 值。

請按照下列步驟解決這個問題:

  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. 在「Tenant URL」欄位中,將 ?aadOptscim062020 附加至基準 URI:

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

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

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

無法根據使用者或群組授予存取權或共用

如果同步處理的使用者無法存取 Google Cloud資源,或無法在 Gemini Notebook for Business 中共用筆記本,或無法在 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 更新群組。

供應商更新失敗,設定互斥

如果建立或更新供應商失敗,並顯示下列其中一則訊息,就會發生這項錯誤:

  • Select one of scim_usage - ENABLED_FOR_USERS_GROUPS or extra_attributes_oauth2_client, but not both.
  • Select one of scim_usage or extended_attributes_oauth2_client, but not both.

--scim-usage=enabled-for-users-groups 設定與額外屬性 (extra_attributes_oauth2_client) 和擴充屬性 (extended_attributes_oauth2_client) 互斥。

如要解決這個問題,請從供應商移除衝突的額外或擴充屬性設定,或變更 --scim-usage 設定。

Cloud OAuth API 權杖交換錯誤

如果權杖交換要求失敗,Cloud OAuth API 會傳回 HTTP 400 Bad Request 或 401 Unauthorized 狀態,以及 OAuth 2.0 錯誤 JSON 回應 (RFC 6749)。error 欄位會指出下列其中一個錯誤代碼:

錯誤代碼 說明 修復
invalid_request 要求缺少必要參數、包含無效的參數值、包含重複的參數,或格式有誤。 確認已提供所有必要的網址編碼參數 (grant_type、code 或 refresh_token、redirect_uri)。
invalid_client 用戶端驗證失敗。 確認註冊的 OAuth client_id 和 client_secret 相符、員工身分集區已啟用 OAuth 用戶端,且 Authorization: Basic 標頭已正確採用 Base64 編碼。
invalid_grant 提供的授權碼或更新權杖無效、已過期、已撤銷、與授權要求中使用的重新導向 URI 不符,或已核發給其他用戶端。 確認代碼或權杖尚未過期或先前未兌換。
unauthorized_client 通過驗證的 OAuth 用戶端未獲授權,無法使用要求的 grant_type。 確認 OAuth 用戶端註冊允許授權碼或更新權杖授權。
unsupported_grant_type 授權伺服器不支援授權類型。 將 grant_type 設為 authorization_code 或 refresh_token。
invalid_scope 要求的範圍無效、不明、格式錯誤,或超出資源擁有者授予的範圍。 請確認要求的範圍與 OAuth 用戶端設定的範圍相符,且適用於您的應用程式。
resource_exhausted 要求超出 Cloud OAuth API 權杖交換配額。 請前往 Google Cloud 控制台查看 API 用量,或要求提高配額。

Cloud OAuth 使用者資訊和群組錯誤

如果對 /userinfo 或 /groups 端點的要求失敗,Cloud OAuth API 會傳回 HTTP 400 Bad Request、401 Unauthorized 或 403 Forbidden 狀態,並附上 OAuth 2.0 不記名權杖錯誤回應 (RFC 6750/OpenID Connect Core)。error 欄位會顯示下列其中一個錯誤代碼:

錯誤代碼 HTTP 狀態 說明 修復
invalid_request 400 Bad Request/401 Unauthorized 要求缺少必要的 Authorization 標頭,或標頭格式不正確 (例如開頭不是 Bearer)。 確認 Authorization: Bearer ACCESS_TOKEN 標頭格式正確。
invalid_token 401 Unauthorized 提供的存取權杖無效、已過期或已撤銷。 使用 refresh_token 授權更新存取權杖,或重複授權碼流程。
insufficient_scope 403 Forbidden 存取權杖缺少必要的 openid 範圍,或權杖的租用戶與組織範圍端點網址中指定的組織不符。 確認權杖是使用必要的 openid 範圍要求,且您呼叫的是正確的端點。