在 Microsoft Entra ID 中設定 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. 在 Microsoft Entra ID 中設定 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，請參閱「群組」。

在 Microsoft Entra ID 中設定 SCIM

如要在 Microsoft Entra ID 中設定 SCIM，請按照下列步驟操作：

1. 開啟 Azure 入口網站，並以具備全域管理員權限的使用者身分登入。
2. 依序選取「Microsoft Entra ID」>「Enterprise Apps」。
3. 按一下「新增應用程式」。
4. 在「Browse Microsoft Entra App gallery」(瀏覽 Microsoft Entra 應用程式庫) 中，點選「Create your own application」(建立自己的應用程式)。
5. 在隨即顯示的「Create your own application」(建立專屬應用程式) 面板中，執行下列操作：
   1. 在「應用程式名稱」部分，輸入應用程式名稱。
   2. 選取「Integrate any other application you don't find in gallery (Non-gallery)」(整合在圖庫中找不到的任何其他應用程式 (非圖庫))。
   3. 點選「建立」，建立應用程式。
6. 在應用程式中，請執行下列操作：
   1. 在「管理」部分，按一下「佈建」。
   2. 在隨即顯示的右側窗格中，按一下「新增設定」。

   3. 在「管理員憑證」下方的「租戶網址」中，輸入建立 SCIM 租戶時取得的 SCIM 網址，並附加 ?aadOptscim062020。 您必須在基礎 URI 結尾附加 ?aadOptscim062020。

      Microsoft Entra ID 必須使用這項查詢參數，確保 SCIM PATCH 要求符合 SCIM RFC 標準。詳情請參閱 Microsoft 說明文件。

      Microsoft Entra ID 中的最終租戶網址應採用下列格式：

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

      將 SCIM_TENANT_UID 替換為 SCIM 租戶 UID。

   4. 在「Secret token」(密鑰權杖) 中，輸入您在建立 SCIM 權杖時取得的密鑰權杖。
   5. 如要測試員工身分聯盟的 SCIM 設定，請按一下「測試連線」。
   6. 如要儲存設定，請按一下「建立」。
7. 在「管理」部分執行下列操作：
   1. 按一下「屬性對應」。
   2. 按一下「Provision Microsoft Entra ID Users」。
   3. 在「屬性對應」頁面中，執行下列操作：
      1. 在「屬性對應」表格中，找出 externalId 所在的資料列，然後按一下該列中的「編輯」。 在「編輯屬性」頁面中執行下列操作：
         1. 在「來源屬性」下拉式清單中，選取「objectId」。
         2. 按一下「確定」。
      2. 如要儲存屬性對應，請按一下「儲存」。

更新供應商以啟用 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) 中必須完全相同。下表列出 Microsoft Entra ID 的參考範例：

Google 屬性	工作團隊身分集區提供者對應	SCIM 租戶對應
google.subject	assertion.oid	user.externalId
google.subject	assertion.attributes['http://schemas.microsoft.com/identity/claims/objectidentifier'][0]	user.externalId
google.subject	assertion.email	user.emails[0].value
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0]	user.emails[0].value
google.subject	assertion.email.lowerAscii()	user.emails[0].value.lowerAscii()
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0].lowerAscii()	user.emails[0].value.lowerAscii()
google.subject	assertion.preferred_username	user.userName
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]	user.userName
google.subject	assertion.preferred_username.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0].lowerAscii()	user.userName.lowerAscii()

驗證 SCIM 同步

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

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

設定 SCIM 後，您可以使用 curl 查詢 IAM SCIM 服務端點 (iamscim.googleapis.com)，並確認使用者和群組是否正在同步至 Google Cloud。這些指令需要有效的 SCIM 權杖和 SCIM 租戶 UID。iamscim.googleapis.com 服務會實作 SCIM 2.0 通訊協定 (RFC 7644)。如要進一步瞭解支援的端點、查詢篩選器和限制，請參閱「支援和不支援的端點」和「通訊協定功能限制」。

驗證使用者同步

如要確認使用者是否已正確同步，請使用下列篩選器搜尋使用者的 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，請在供應商設定中停用：

   OIDC

   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：工作團隊集區的位置

   SAML

   gcloud iam workforce-pools providers update-saml 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 支援員工身分聯盟的產品
• 設定使用者對控制台 (聯合) 的存取權