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

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

   1. 在輸出內容的 baseUri 欄位中，儲存格式為 https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID 的完整 URI。您需要將這個 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，請參閱「群組」。

在 Okta 中設定 SCIM

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

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

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

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

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

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

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

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

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

     3. 按一下「新增整合」。

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

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

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

      1. 在「API 權杖」欄位中，輸入從 Google Cloud取得的 SCIM 權杖。
      2. 如要確認 API 權杖是否有效，請按一下「測試憑證」。
      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=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) 中必須完全相同。下表列出 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 確認使用者和群組是否正確同步至 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 支援員工身分聯盟的產品
• 設定使用者對控制台 (聯合) 的存取權