在 OIDC 或 SAML IdP 中設定 SCIM

重要事項：SCIM 佈建僅適用於 Gemini Enterprise 和 Looker (搶先版)。

本文說明如何在員工身分集區中設定 SCIM 租戶。如要進一步瞭解 SCIM，請參閱「員工身分聯盟的 SCIM 佈建」。

每個員工身分集區僅支援一個 SCIM 租戶。如要在已有一個 SCIM 租戶的集區中設定新的租戶，請先強制刪除現有租戶。

SCIM 租戶的 --claim-mapping 旗標只能包含特定的一般運算語言 (CEL) 運算式。如要瞭解支援哪些運算式，請參閱「聲明對應」。

請確認 IdP 為對應至 google.subject 和 google.group 的屬性提供不重複的非空白值。同步處理重複值會失敗，並顯示 HTTP 409 Conflict 錯誤；同步處理空值或空白值會失敗，並顯示 HTTP 400 Bad Request 錯誤。詳情請參閱「SCIM 支援」。

如要設定跨網域身分識別管理系統 (SCIM)，請按照下列步驟操作：

1. 在 Google Cloud 中設定 SCIM 租戶和權杖
2. 在 OIDC 或 SAML IdP 中設定 SCIM
3. 更新供應商以啟用 SCIM
4. 驗證 SCIM 同步處理

在 Google Cloud中設定 SCIM 租戶和權杖

如要在 Google Cloud中設定 SCIM 租戶，請按照下列步驟操作：

1. 建立 SCIM 租戶。

       gcloud iam workforce-pools providers scim-tenants create SCIM_TENANT_ID \
           --workforce-pool="WORKFORCE_POOL_ID" \
           --provider="PROVIDER_ID" \
           --display-name="SCIM_TENANT_DISPLAY_NAME" \
           --description="SCIM_TENANT_DESCRIPTION" \
           --claim-mapping="CLAIM_MAPPING" \
           --location="global"
       

   更改下列內容：

   • SCIM_TENANT_ID：SCIM 租戶的 ID。
   • WORKFORCE_POOL_ID：您在本文件中先前建立的員工集區 ID。
   • PROVIDER_ID：您在本文件中稍早建立的員工身分集區提供者 ID。
   • SCIM_TENANT_DISPLAY_NAME：SCIM 租戶的顯示名稱。
   • SCIM_TENANT_DESCRIPTION：SCIM 租戶的說明。
   • CLAIM_MAPPING：以半形逗號分隔的屬性對應清單。如需擴充的對應屬性清單，請參閱「聲明對應」。建議您為 Gemini Enterprise 採用下列對應：

     google.subject=user.emails[0].value.lowerAscii(),google.group=group.externalId

     您在 SCIM 租戶中對應的 google.subject 屬性，必須使用 --attribute-mapping 旗標，在 workforce identity pool 提供者中，以 google.subject 屬性對應至相同身分。SCIM 租戶建立完成後，您就無法更新聲明對應。如要替換，可以強制刪除 SCIM 租戶，然後立即建立新的租戶。如要進一步瞭解使用 SCIM 的注意事項，請參閱「SCIM 支援」。

2. 指令完成後，請執行下列操作：

   1. 在輸出內容的 baseUri 欄位中，儲存整個 URI，格式為 https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID。您需要將這個 URI 提供給 IdP。
   2. 此外，請只從 URI 儲存 SCIM_TENANT_UID。 您需要這個 UID，才能在本文件的後續部分中，對 SCIM 租戶設定 IAM 允許政策。

3. 建立 SCIM 權杖：

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

   更改下列內容：

   • SCIM_TOKEN_ID：SCIM 權杖的 ID
   • DISPLAY_NAME：SCIM 權杖的顯示名稱
   • WORKFORCE_POOL_ID：工作團隊集區的 ID
   • SCIM_TENANT_ID：SCIM 租戶的 ID
   • PROVIDER_ID：工作團隊身分集區提供者的 ID

4. gcloud iam workforce-pools providers scim-tenants tokens create 指令完成後，請執行下列操作：

   1. 在輸出中，將 SCIM_TOKEN 的值儲存至 securityToken 欄位。您需要將這個安全權杖提供給 IdP。安全權杖只會顯示在這個輸出內容中，如果遺失，就必須建立新的 SCIM 權杖。

   2. 如要檢查 SCIM_TOKEN 是否遭貴機構的組織政策拒絕，請執行下列指令：

      curl -v -H "Authorization: Bearer SCIM_TOKEN"  https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users

      如果指令失敗並顯示權限相關錯誤，請執行後續步驟所述的 gcloud organizations add-iam-policy-binding。如果指令成功，可以略過該步驟。

5. 在 SCIM 租戶和權杖上設定 IAM 允許政策。如果上一個步驟的 curl 指令失敗，並顯示權限相關錯誤，請執行下列指令：

       gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
           --member=serviceAccount:SERVICE_AGENT_EMAIL \
           --role roles/iam.scimSyncer
       

   請替換下列項目：

   • ORGANIZATION_ID：組織 ID。
   • SERVICE_AGENT_EMAIL：服務專員的電子郵件地址。電子郵件地址的格式如下：[e-mail]。建立 SCIM 租戶時，系統會傳回 SCIM_TENANT_UID。

在 IdP 中佈建群組時，請確保每個群組的顯示名稱 (在 displayName 欄位中提供) 在 SCIM 租戶中是唯一的。如要進一步瞭解 Microsoft Entra ID 中的群組和 SCIM，請參閱「群組」。

在 OIDC 或 SAML IdP 中設定 SCIM

在 IdP 中，按照 IdP 說明文件所述設定 SCIM。使用上一步取得的 SCIM 網址和 SCIM 權杖。

更新供應商以啟用 SCIM

如要為提供者啟用 SCIM，請根據產品目標設定 --scim-usage 標記：

• 已為群組啟用 (enabled-for-groups)：用於 Gemini Enterprise。使用 SCIM 同步群組進行 IAM 授權和政策評估。系統會繼續從 IdP 登入權杖取得使用者屬性。
• 為使用者和群組啟用 (enabled-for-users-groups)：用於 Looker (預覽版)。使用 SCIM 同步處理的使用者和群組資料，做為 IAM 授權和 OAuth 登入工作流程的主要聲明來源。

為群組啟用 SCIM (Gemini Enterprise)

OIDC

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

請替換下列項目：

• PROVIDER_ID：工作團隊身分集區提供者的 ID
• WORKFORCE_POOL_ID：工作團隊集區的 ID
• LOCATION：工作團隊集區的位置

SAML

      gcloud iam workforce-pools providers update-saml PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-groups
    

請替換下列項目：

• PROVIDER_ID：工作團隊身分集區提供者的 ID
• WORKFORCE_POOL_ID：工作團隊集區的 ID
• LOCATION：工作團隊集區的位置

為使用者和群組啟用 SCIM (Looker) (預覽版)

OIDC

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

請替換下列項目：

• PROVIDER_ID：工作團隊身分集區提供者的 ID
• WORKFORCE_POOL_ID：工作團隊集區的 ID
• LOCATION：工作團隊集區的位置

SAML

      gcloud iam workforce-pools providers update-saml PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-users-groups
    

請替換下列項目：

• PROVIDER_ID：工作團隊身分集區提供者的 ID
• WORKFORCE_POOL_ID：工作團隊集區的 ID
• LOCATION：工作團隊集區的位置

如要驗證 SCIM 同步作業，請參閱「驗證 SCIM 同步作業」。

聲明對應

設定 SCIM 時，您會在 SCIM 租戶中定義權杖附加資訊對應 (--claim-mapping)，將 SCIM 使用者和群組屬性對應至 Google 屬性。

支援用於著作權聲明對應的 Google Cloud 屬性

下表列出您可以在 SCIM 租戶 (--claim-mapping) 中對應的 Google Cloud 屬性，方法是使用一般運算語言 (CEL)：

Google Cloud 屬性	條件	說明	支援的運算式和限制
google.subject	必填	驗證使用者的專屬 ID。 用於填入 google.subject 的基礎 IdP 屬性，在供應商對應 (--attribute-mapping) 和 SCIM 租戶 (--claim-mapping) 中必須完全相同。如果這些對應不一致，使用者可能可以登入，但系統不會將他們視為 SCIM 佈建群組的成員。	僅限下列基本運算式 (或使用 .lowerAscii())： user.externalId user.userName user.emails[0].value 長度上限：127 個位元組。 注意：SCIM 租戶建立後，這項對應關係就無法變更。如要更新，請強制刪除並重新建立 SCIM 租戶。
google.group	SCIM 群組的必要屬性	使用 SCIM 同步處理的群組成員資格專屬 ID。	僅限下列基本運算式 (或使用 .lowerAscii())： group.externalId group.displayName 注意：SCIM 租戶建立後，這項對應關係就無法變更。如要更新，請強制刪除並重新建立 SCIM 租戶。
google.display_name	選用	這個屬性會在 Google Cloud 控制台中設定已登入使用者的名稱。無法用於 IAM 允許政策。	對應至字串屬性 (例如 user.displayName 或 user.name.formatted)。長度上限為 100 個位元組。
google.profile_photo	選用	使用者縮圖相片的網址，這張相片會顯示為 Google Cloud 控制台中的個人資料相片。無法用於 IAM 允許政策。	必須評估為有效的網址字串 (例如 user.photos.filter(p, p.type == 'thumbnail')[0].value 或 user.photos[0].value)。
google.email	選用	這個屬性用於將 IdP 中的電子郵件地址對應至產品，這些產品是透過員工身分聯盟 OAuth 用戶端整合功能整合。無法用於 IAM 允許政策。	對應至電子郵件屬性 (例如 user.emails.filter(e, e.type == 'work')[0].value 或 user.emails[0].value)。
google.posix_username	選用	符合 POSIX 標準的專屬使用者名稱字串，用於透過瀏覽器連線 SSH，以及搭配 Workforce Identity Federation 使用 OS 登入。這項屬性無法用於 IAM 允許政策。	長度上限為 32 個字元。
attribute.KEY	選用	IdP 中的自訂屬性，可用於在 IAM 允許政策中定義授權策略。將 KEY 替換為要使用的屬性名稱。 舉例來說，您可以定義 costcenter = "1234" 等自訂屬性，並使用 principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.costcenter/1234 參照該屬性。授予這個主體 ID 的存取權後，您就能存取 IdP 中設定該成本中心的所有身分。	最多 50 項自訂屬性對應規則。每條規則的大小上限為 256 個半形字元。

主題一致性的對應範例

如「支援的權杖附加資訊對應屬性」一文所述，用於填入 google.subject 的基礎 IdP 屬性，在供應商對應 (--attribute-mapping) 和 SCIM 租戶 (--claim-mapping) 中必須完全相同。下表列出 OIDC 或 SAML IdP 的參考範例：

Google 屬性	工作團隊身分集區提供者對應	SCIM 租戶對應
google.subject	assertion.sub	user.externalId

驗證 SCIM 同步

重要事項：由於 SCIM 是從 IdP 推送資料， Google Cloud 不會主動提取資料或檢查連線健康狀態。如果 IdP 與 Google Cloud 之間的連線無聲中斷，身分資料可能會過時。

在最長 90 天的延長工作階段時間長度 (ESL) 工作流程中，停用的使用者可能會保留存取權，直到下次成功同步或工作階段到期為止。為防止未經授權的存取，請持續監控及稽核 SCIM 同步健康狀態。

設定 SCIM 後，您可以使用 curl 確認使用者和群組是否正確同步至 Google Cloud。這些指令需要有效的 SCIM 權杖和 SCIM 租戶 ID。

驗證使用者同步

如要確認使用者是否已正確同步，請使用下列篩選器搜尋使用者的 userName：

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users?filter=userName%20eq%20%22USER_NAME%22"

回應範例：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "USER_ID",
      "userName": "USER_NAME",
      ...
    }
  ]
}

驗證群組同步

如要確認群組是否正確同步，請使用下列篩選器搜尋群組的 displayName：

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups?filter=displayName%20eq%20%22GROUP_NAME%22"

回應範例：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "GROUP_ID",
      "displayName": "GROUP_NAME",
      ...
    }
  ]
}

驗證群組成員資格

如要確認特定使用者是否為群組成員，請使用同時指定群組 ID 和使用者 ID 的篩選器。

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups?filter=id%20eq%20%22GROUP_ID%22%20and%20members%20eq%20%22USER_ID%22"

如果使用者是會員，回覆範例如下：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "GROUP_ID",
      "displayName": "GROUP_NAME",
      ...
    }
  ]
}

如果使用者不是會員，回覆範例如下：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 0,
  "Resources": []
}

注意：如要取得 GROUP_ID 和 USER_ID，請先使用 displayName 和 userName 篩選器找出群組和使用者。ID 會在回應的 id 欄位中傳回。將 SCIM_TOKEN、SCIM_TENANT_UID、USER_NAME、GROUP_NAME、GROUP_ID 和 USER_ID 替換成實際值。

強制刪除 SCIM 租戶

如要強制刪除 SCIM 租戶，請按照下列步驟操作：

1. 如果供應商已設定 --scim-usage=enabled-for-groups 或 --scim-usage=enabled-for-users-groups，請在供應商設定中停用：

             gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
                 --workforce-pool=WORKFORCE_POOL_ID \
                 --location=LOCATION \
                 --scim-usage=SCIM_USAGE_UNSPECIFIED
           

   請替換下列項目：

   • PROVIDER_ID：工作團隊身分集區提供者的 ID
   • WORKFORCE_POOL_ID：工作團隊集區的 ID
   • LOCATION：工作團隊集區的位置

2. 刪除 SCIM 租戶：

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

   請替換下列項目：

   • SCIM_TENANT_ID：要刪除的 SCIM 租戶 ID
   • WORKFORCE_POOL_ID：工作團隊集區的 ID
   • PROVIDER_ID：工作團隊身分集區提供者的 ID
   如要進一步瞭解 SCIM (包括如何刪除 SCIM 租戶)，請參閱「SCIM 支援」。

後續步驟

• 排解 SCIM 佈建問題
• 刪除員工身分聯盟使用者及其資料
• 瞭解 Google Cloud 支援員工身分聯盟的產品
• 設定使用者對控制台 (聯合) 的存取權