在 Microsoft Entra ID 中設定 SCIM

重要事項：SCIM 佈建功能僅適用於 Gemini Enterprise 和 Looker (預先發布版)。

本文說明如何在員工身分集區中設定 SCIM 租戶。如要進一步瞭解 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 旗標，不重複參照員工身分集區提供者中 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. 在輸出內容中，儲存 securityToken 欄位中的 SCIM_TOKEN 值。您必須將這個安全性權杖提供給 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. 在 瀏覽 Microsoft Entra 應用程式庫中，點選 建立您自己的應用程式。
5. 在顯示的「Create your own application」面板中，執行下列操作：
   1. 在「應用程式名稱」部分，輸入應用程式名稱。
   2. 選取「Integrate any other application you don't find in gallery (Non-gallery)」(整合在圖庫中找不到的任何其他應用程式 (非圖庫))。
   3. 點選「建立」，建立應用程式。
6. 在應用程式中執行下列操作：
   1. 在「管理」部分，按一下「佈建」。
   2. 在隨即顯示的右側窗格中，按一下「New Configuration」(新增設定)。

   3. 在「Admin Credentials」下方的「Tenant URL」中，輸入建立 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 設定與員工身分聯盟的連線，請按一下「Test connection」(測試連線)。
   6. 如要儲存設定，請按一下「Create」(建立)。
7. 在「管理」部分執行下列操作：
   1. 按一下「屬性對應」。
   2. 按一下「佈建 Microsoft Entra ID 使用者」。
   3. 在「Attribute Mapping」頁面中，執行下列操作：
      1. 在「屬性對應」表格中，找到 externalId 所在的資料列，然後按一下該列中的「編輯」。 在「Edit attributes」(編輯屬性) 頁面中，執行下列操作：
         1. 在「Source attribute」(來源屬性) 下拉式選單中，選取「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=global \
          --scim-usage=enabled-for-groups
    

更改下列內容：

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

SAML

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

更改下列內容：

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

為使用者和群組啟用 SCIM (Looker) (預先發布版)

OIDC

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

更改下列內容：

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

SAML

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

更改下列內容：

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

如要驗證 SCIM 同步處理，請參閱「驗證 SCIM 同步處理」。

權杖附加資訊對應

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

支援的 Google Cloud 權杖附加資訊對應屬性

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

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 和 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=global \
       --scim-usage=SCIM_USAGE_UNSPECIFIED
   

   更改下列內容：

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

   SAML

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

   更改下列內容：

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

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