員工身分聯盟的 SCIM 佈建

如果您的識別資訊提供者 (IdP) 支援跨網域身分管理系統 (SCIM)，您可以設定該系統，在 Google Cloud中佈建及管理使用者和群組。

功能

員工身分聯盟 SCIM 支援功能提供下列功能：

  • 身分同步：將外部 IdP 的使用者和群組同步到 Google Cloud ，全面掌握員工身分。
  • 聲明的主要來源：為員工供應商啟用 SCIM 後， Google Cloud 會將同步的 SCIM 使用者和群組做為 IAM 政策評估的使用者屬性和群組成員資格的可靠來源。
  • 身分自動完成：在 Gemini Enterprise 中授予存取權及共用資源 (例如 Notebook 和 Agent) 時，啟用這項功能可自動完成使用者和群組身分。

注意事項

使用員工身分聯盟 SCIM 支援時，請注意下列事項：

  • 設定 SCIM 租戶前，請務必先設定工作團隊身分集區和提供者。
  • 每個員工身分集區僅支援一個 SCIM 租戶，且只能連結至單一供應商。您無法在同一個集區中的任何其他供應商啟用 SCIM 用法 (--scim-usage)。如要在同一個員工身分集區中設定新的 SCIM 租戶，請先刪除現有租戶。如要刪除 SCIM 租戶，請使用下列其中一種方法：
    • 虛刪除 (預設)：刪除 SCIM 租戶會啟動 30 天的虛刪除期。在這段期間，系統會隱藏租戶，且無法使用，您也無法在相同的工作團隊身分識別集區中建立新的 SCIM 租戶。
    • 強制刪除：如要永久刪除 SCIM 租戶，請在刪除指令中使用 --hard-delete 旗標。這項動作無法復原，您可立即在同一個員工身分集區中建立新的 SCIM 租戶，不必等待 30 天的保留期限。或者，您也可以建立新的工作團隊身分集區和新的 SCIM 租戶，或使用先前未設定 SCIM 租戶的工作團隊身分集區。
  • SCIM 使用模式 (--scim-usage)：
    • enabled-for-groups (Gemini Enterprise)：使用 SCIM 同步群組進行 IAM 授權和政策評估。系統會繼續從登入權杖取得使用者屬性。系統只會評估 google.subject 和 google.group 對應關係。
    • enabled-for-users-groups (Looker) (預覽版)：使用 SCIM 同步處理的使用者和群組資料，做為 IAM 授權和 OAuth 登入工作流程的聲明來源。評估 google.subject、google.group 和所有已設定的使用者聲明 (例如 google.display_name、google.profile_photo、google.email、google.posix_username 和自訂 attribute.KEY)。
  • 互斥：設定 --scim-usage=enabled-for-users-groups (預覽) 與額外屬性 (extra_attributes_oauth2_client) 和擴充屬性 (extended_attributes_oauth2_client) 互斥。
  • 使用 SCIM 時，您需要對應員工身分集區供應商和 SCIM 租戶中的屬性。google.subject 屬性必須唯一參照相同身分。您可以使用 --attribute-mapping 旗標，在 工作團隊身分集區提供者中指定 google.subject，並使用 --claim-mapping 旗標 在 SCIM 租戶中指定。對應非專屬身分識別值可能會導致 Google Cloud 將不同的 IdP 身分識別視為相同身分。因此，授予某位使用者或群組身分的存取權可能會擴及其他使用者，但撤銷其中一項存取權可能不會移除所有存取權。
  • 如果啟用供應商的 SCIM 用法，但未附加 SCIM 租戶，登入嘗試會失敗，因為 Google Cloud 找不到該供應商的 SCIM 租戶。
  • 強制執行唯一性： Google Cloud 驗證並強制執行對應至 SCIM 租戶中 google.subject (使用者) 和 google.group (群組) 的屬性唯一性。如果 IdP 佈建的對應屬性在同步處理期間，導致 google.subject 或 google.group 的值重複，佈建就會失敗並顯示 HTTP 409 Conflict 錯誤。如果對應的屬性評估結果為空值或空白，系統會因 HTTP 400 Bad Request 錯誤而無法佈建。
  • 屬性大小限制：序列化對應使用者屬性 (不含 google.group) 的大小上限為 16 KB。如果對應的屬性超過這個上限，登入嘗試就會失敗。
  • SCIM 權杖限制：每個 SCIM 租戶最多支援兩個 SCIM 權杖 (例如，支援零停機時間權杖輪替)。如果已有兩個權杖，請先刪除現有權杖，再建立新權杖。
  • SCIM API (iamscim.googleapis.com) 的速率配額與標準 IAM 資源 API 配額不同。根據預設，每個機構每分鐘每個 SCIM 租戶的寫入和讀取要求上限為 3,000 項。詳情請參閱「配額與限制」。

聲明對應

設定 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 個半形字元。

根據提供者 SCIM 用量 (--scim-usage) 的行為

SCIM 宣告對應的評估方式取決於工作團隊身分集區提供者設定的 --scim-usage 模式：

  • enabled-for-groups (Gemini Enterprise)：系統只會評估 google.subject 和 google.group 對應。系統會忽略 --claim-mapping 中的任何其他使用者聲明對應。
  • enabled-for-users-groups (Looker) (預覽版)：評估 google.subject、google.group 和所有已設定的使用者聲明 (例如 google.display_name、google.profile_photo、google.email、google.posix_username 和自訂 attribute.<var>KEY</var>)。

主題一致性的對應範例

如「支援的宣告對應屬性」所述，用於填入 google.subject 的基礎 IdP 屬性，在供應商對應 (--attribute-mapping) 和 SCIM 租戶 (--claim-mapping) 中必須完全相同。下表提供參考範例：

Google 屬性 工作團隊身分集區提供者對應 SCIM 租戶對應 (SCIM)
google.subject assertion.oid (Entra ID) user.externalId
google.subject assertion.sub (Okta) user.externalId
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 通訊協定端點：

  • /Users：管理使用者資源。支援的作業：Create、Get、Update、Delete、Patch 和 Put。

  • /Groups：管理群組資源。支援的作業：Create、Get、Update、Delete 和 Patch。群組不支援 PUT 方法。

  • /Schemas：擷取結構定義資訊。

  • /ServiceProviderConfig：擷取服務供應商設定。

系統不支援下列 SCIM 通訊協定端點：

  • /Me

  • /Bulk

  • /Search

  • /ResourceTypes

限制

以下各節說明員工身分聯盟 SCIM 實作項目與 SCIM 規格 (RFC 7643 和 7644) 的限制和差異。

通訊協定功能限制

  • 篩選器支援：使用 /Users 或 /Groups 端點列出使用者或群組時，篩選器運算式只支援 eq (等於) 運算子。你可以組合多個 eq 篩選器和 and。系統不支援其他 SCIM 篩選運算子，例如 co (包含) 或 sw (開頭為)。

  • 分頁：IAM SCIM API 不支援標準分頁功能，因此無法列出使用者或群組。

    • startIndex：這個參數一律為 1。無論您為 startIndex 提供的值為何，API 最多都會傳回 100 個結果。

    • itemsPerPage：單一回應中傳回的資源數量上限為 100。

    • totalResults：API 不會傳回相符資源的實際總數。回應中的 totalResults 欄位一律等於該回應中傳回的項目數量，最多為 100 個。

  • 取得群組及列出不含篩選器的群組： GetGroup 和 ListGroups API 會傳回空白的成員清單。如要擷取特定群組的成員，請使用 ListGroups API 和成員篩選器。

  • 含有無效權杖的違規 JSON 回應：含有無效 API 權杖的要求會從 Google Cloud傳回 HTTP 401 狀態碼。回覆不是 SCIM 規格規定的有效 JSON。

SCIM 行為限制

  • 不可變更的 ID：系統會將對應至 google.subject 或 google.group 的 SCIM 屬性值視為 Google Cloud內不可變更的 ID。如要變更這些值，您必須從 IdP 永久刪除使用者或群組，然後使用新值重新建立。

  • 專屬且不得為空白的 ID： Google Cloud 強制在 SCIM 租戶中，對應至 google.subject 和 google.group 的值必須是專屬值。 如果對應屬性同步處理後，google.subject 或 google.group 的值重複，就會失敗並顯示 HTTP 409 Conflict 錯誤。如果對應屬性的評估結果為空值，就會失敗並顯示 HTTP 400 Bad Request 錯誤。

  • 單一電子郵件地址規定：如要順利完成 SCIM 同步，每位使用者都必須擁有一個 work 類型的電子郵件地址。如果 IdP 傳送多封電子郵件，或提供的單一電子郵件不是 work 類型，系統就會無法佈建或更新。

  • 不區分大小寫的轉換：SCIM 權杖附加資訊對應支援有限的一般運算語言 (CEL) 轉換。不區分大小寫的比較僅支援 .lowerAscii()，適用於 user.userName 和 user.emails[0].value。

屬性限制

以下各節說明使用者、群組和企業使用者結構定義擴充功能的屬性支援。

使用者屬性

下表列出使用者屬性，以及這些屬性在員工身分聯盟聲明中的可用性：

屬性 子屬性 SCIM 佈建功能支援 限制 支援使用以下發布途徑：--claim-mapping
userName 不適用 是 不適用 是
name formatted、familyName、givenName、middleName、honorificPrefix、honorificSuffix 是 不適用 是
displayName 不適用 是 不適用 是
nickName 不適用 是 不適用 是
profileUrl 不適用 是 不適用 是
title 不適用 是 不適用 是
userType 不適用 是 不適用 是
preferredLanguage 不適用 是 不適用 是
locale 不適用 是 不適用 是
timezone 不適用 是 不適用 是
active 不適用 是 不適用 是
password 不適用 否 不適用 否
emails display、type、value、primary 是 僅支援 work 電子郵件類型。 是
phoneNumbers display、type、value、primary 是 不適用 是
ims display、type、value 是 不適用 是
photos display、type、value 是 不適用 是
addresses formatted、streetAddress、locality、region、postalCode、country 是 不適用 是
groups 不適用 否 不適用 否
entitlements display、type、value 是 不適用 是
roles type、value 是 系統並不支援 display。 是
x509Certificates type、value 是 系統並不支援 display。 否

群組屬性

下表列出群組屬性，以及這些屬性在 Workforce Identity Federation 聲明中的可用性：

屬性 支援的子屬性 支援使用以下發布途徑：--claim-mapping
displayName 不適用 是
externalId 不適用 是
members value、type、$ref、display 否

企業使用者結構定義擴充屬性

下表詳細列出企業使用者結構定義擴充功能的支援情形：

屬性 支援的子屬性 支援使用以下發布途徑：--claim-mapping
employeeNumber 不適用 是
costCenter 不適用 是
organization 不適用 是
division 不適用 是
department 不適用 是
manager value、$ref、displayName 是 (SCIM 佈建僅支援 $ref，不支援 --claim-mapping)

後續步驟