在 Okta 中設定 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. 在 Okta 中設定 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.displayName

     您在 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，請參閱「群組」。

在 Okta 中設定 SCIM

如要在 Okta 中設定 SCIM，請在現有的 Okta 應用程式中執行下列操作：

1. 登入 Okta 管理控制台。
2. 依序前往「應用程式」>「應用程式」。

3. 選取或建立應用程式：

   • 如要選取現有應用程式，請按照下列步驟操作：

     1. 按一下您使用 Google Cloud 員工身分聯盟範本建立的應用程式名稱。

     2. 在「一般」分頁中，執行下列操作：

        1. 在「App Settings」(應用程式設定) 窗格中，按一下「Edit」(編輯)。
        2. 在「Tenant」欄位中，輸入從 gcloud CLI 取得的租戶 ID。
        3. 按一下「完成」。

   • 如要建立新的應用程式，請按照下列步驟操作：

     1. 按一下「瀏覽應用程式目錄」。
     2. 在「Search」欄位中輸入 Google Cloud Workforce Identity Federation，然後從結果中選取「Google Cloud Workforce Identity Federation」整合項目。

     3. 按一下「Add Integration」。

        1. 在「Application」欄位中，輸入應用程式名稱。
        2. 在「Tenant」欄位中，輸入從 gcloud CLI 取得的租戶 ID。
        3. 按一下「完成」。

4. 在「Provisioning」(佈建) 分頁中，執行下列操作：

   1. 在「Integration」(整合) 窗格中，按一下「Edit」(編輯)。

      1. 在「API Token」欄位中，輸入從 Google Cloud取得的 SCIM 權杖。
      2. 如要確認 API 權杖是否有效，請按一下「Test Credentials」。
      3. 選取「匯入群組」。
      4. 按一下 [儲存]。

   2. 在「To App」窗格中，按一下「Edit」。

      1. 選取「建立使用者」、「更新使用者屬性」和「停用使用者」。
      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) 中必須相同。下表顯示 Okta 的參考範例：

Google 屬性	員工身分集區提供者對應	SCIM 租戶對應
google.subject	assertion.sub	user.externalId
google.subject	assertion.subject	user.userName
google.subject	assertion.subject.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.preferred_username	user.userName
google.subject	assertion.preferred_username.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.email	user.emails[0].value
google.subject	assertion.email.lowerAscii()	user.emails[0].value.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 產品支援員工身分聯盟
• 設定使用者對控制台 (聯合) 的存取權