設定應用程式的存取控管機制

本頁面說明 Gemini Enterprise 管理員如何使用 API，管理個別 Gemini Enterprise 應用程式的精細存取控管。

如要為應用程式和資料儲存庫設定精細的資源層級存取控管，請參閱「為應用程式和資料儲存庫設定精細的存取控管」。

根據預設，IAM 權限通常是在專案層級管理。應用程式層級的 IAM 可提供更精細的控制選項，讓管理員執行下列操作：

• 限制使用者存取同一 Google Cloud 專案中的特定應用程式。
• 根據機構需求和資料孤島，調整 Gemini Enterprise 部署作業的權限。

重要事項： 專案層級的 IAM 權限優先於應用程式層級政策。如果使用者在專案層級獲派 Gemini Enterprise 企業版使用者 (roles/discoveryengine.agentspaceUser) 角色，就能存取該專案中的所有應用程式，不受任何應用程式層級權限限制。如要限制使用者只能存取特定應用程式，請將其專案層級的 Gemini Enterprise 使用者角色，替換為 Gemini Enterprise 受限使用者 (roles/discoveryengine.agentspaceRestrictedUser) 角色，然後在他們需要存取的每個應用程式，授予 Gemini Enterprise 使用者角色。

注意： 如果使用者具備 Gemini Enterprise 應用程式的應用程式層級 IAM 權限，就只能存取及使用該應用程式。這些是使用者層級權限，不含管理員功能。

舉例來說，假設某機構有人資應用程式和全公司適用的應用程式。具備專案層級權限的人資團隊成員可以存取這兩個應用程式。相較之下，如果使用應用程式層級 IAM 政策，您可以只授予銷售團隊成員全公司應用程式的存取權，防止他們存取人資應用程式。

事前準備

• 確認您具備 Gemini Enterprise 管理員 (roles/discoveryengine.agentspaceAdmin) 角色。

• 確認所有 Gemini Enterprise 使用者都有有效授權，且在專案層級獲派 Gemini Enterprise 受限使用者 (roles/discoveryengine.agentspaceRestrictedUser) 角色。如需操作說明，請參閱「授予使用者權限」一文。

  這個角色本身不會授予任何應用程式的存取權。提供使用者所需的專案層級存取權，然後授予個別應用程式的存取權。如果您使用自訂專案層級角色，而非預先定義的 roles/discoveryengine.agentspaceRestrictedUser 角色，請確認自訂角色包含 discoveryengine.locations.buildAuthorizationUrl、discoveryengine.dataStores.get、discoveryengine.collections.get 和 discoveryengine.devToolsConfigs.get 權限。如果省略 discoveryengine.devToolsConfigs.get，當網頁應用程式檢查 devToolsConfig 時，Cloud 稽核記錄會發生 403 PERMISSION_DENIED 錯誤。

從專案層級存取權轉換為應用程式層級存取權

如要限制使用者只能存取特定應用程式，請將他們的專案層級 Gemini Enterprise 使用者角色，替換為 Gemini Enterprise 受限使用者角色，然後在個別應用程式層級授予 Gemini Enterprise 使用者角色。

如要將使用者的專案層級存取權轉換為應用程式層級存取權，請按照下列步驟操作。您可以使用 Google Cloud 控制台進行專案層級的變更，並使用 API 授予應用程式層級的權限，因為 Google Cloud 控制台不支援這項操作。

1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。
2. 找出使用者，並從專案層級權限中移除 Gemini Enterprise 企業版使用者 (roles/discoveryengine.agentspaceUser) 角色。
3. 如果尚未授予使用者專案層級的 Gemini Enterprise 受限使用者 (roles/discoveryengine.agentspaceRestrictedUser) 角色，請先執行這項操作。
4. 使用 setIamPolicy 方法，為使用者授予 Gemini Enterprise 企業版使用者 (roles/discoveryengine.agentspaceUser) 角色，讓他們存取所需的特定應用程式。詳情請參閱「管理應用程式的 IAM 政策」。

管理應用程式的 IAM 政策

如要管理 Gemini Enterprise 應用程式的存取權，可以使用 getIamPolicy 和 setIamPolicy API 方法。

下列步驟說明如何擷取目前的政策，然後更新政策以授予或撤銷使用者存取權。

取得應用程式 IAM 政策

使用 getIamPolicy 方法，取得應用程式目前的 IAM 政策。建議您先擷取現有政策，以免覆寫任何現有權限。

REST

重要詞彙：在 Gemini Enterprise 中，應用程式一詞與 API 內容中的引擎一詞可互換使用。Gemini Enterprise 引擎是一般搜尋引擎，其 app_type 欄位設為 APP_TYPE_INTRANET。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID:getIamPolicy"

更改下列內容：

• PROJECT_ID：專案的 ID。
• ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
  • us 適用於美國多區域
  • eu 代表歐盟多區域
  • global 適用於全域位置
  詳情請參閱「為資料儲存庫指定多區域」。
• LOCATION：資料儲存庫的多區域：global、us 或 eu

• APP_ID：要設定的應用程式 ID。

  注意： 從回應中複製 etag 值。必須提供這個值，才能更新 IAM 政策。etag 值會隨著每次政策更新而變更。

指令與結果範例

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://global-discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app:getIamPolicy"

{
  "version": 1,
  "etag": "1234567890"
}
  

更新應用程式 IAM 政策

如要授予或撤銷使用者對應用程式的存取權，請使用 setIamPolicy 方法更新應用程式的 IAM 政策。

重要事項： setIamPolicy 方法會取代現有政策。為避免移除現有權限，除了任何新增或修改的繫結，您的要求也必須包含所有要保留的政策繫結。

IAM 政策會使用 Gemini Enterprise 使用者 (roles/discoveryengine.agentspaceUser) 角色，直接授予使用者應用程式存取權。

注意： 變更 IAM 政策 (例如使用 setIamPolicy 進行變更) 時，可能會有傳播延遲。權限可能需要幾分鐘才會全面生效。詳情請參閱「IAM 傳播延遲」。

REST

重要詞彙：在 Gemini Enterprise 中，應用程式一詞與 API 內容中的引擎一詞可互換使用。Gemini Enterprise 引擎是一般搜尋引擎，其 app_type 欄位設為 APP_TYPE_INTRANET。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
      "policy": {
         "etag": "ETAG",
         "bindings": [
          {
            "role": "roles/discoveryengine.agentspaceUser",
            "members": [
              "user:USER_EMAIL",
              "group:GROUP_EMAIL",
              "principal://iam.googleapis.com/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ID",
              "principalSet://iam.googleapis.com/locations/global/workloadIdentityPools/POOL_ID/attribute.NAME/VALUE"
            ]
          }
        ]
      }
    }' \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID:setIamPolicy"

更改下列內容：

• ETAG：使用 getIamPolicy 方法時，做為回應取得的 etag 值。

• USER_EMAIL、GROUP_EMAIL： 一或多個使用者或群組的電子郵件地址。除了 user 和 group 之外，principal 和 principalSet 也是 Workload Identity Federation 的有效成員類型。

  • 如要授予存取權，請將主體新增至 members 陣列。例如 "user:[e-mail]" 或 "group:[e-mail]"。

    注意： 請勿在電子郵件地址前後加上多餘空格。

  • 如要撤銷存取權，請從 members 陣列中移除主體。

• POOL_ID：Workload Identity Pool 的 ID。

• SUBJECT_ID：特定身分的主體 ID。

• NAME：屬性名稱。

• VALUE：屬性的值。

• PROJECT_ID：專案 ID。

• ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：

  • us 適用於美國多區域
  • eu 代表歐盟多區域
  • global 適用於全域位置
  詳情請參閱「為資料儲存庫指定多區域」。

• LOCATION：資料儲存庫的多區域：global、us 或 eu。

• APP_ID：要設定的應用程式 ID。

  注意： etag 值會隨著每次政策更新而變更。如要再次更新政策，請先按照「取得應用程式 IAM 政策」一文的說明，取得新的 etag。

指令與結果範例

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
      "policy": {
         "etag": "1234567890",
         "bindings": [
          {
            "role": "roles/discoveryengine.user",
            "members": [
              "user:[e-mail]",
              "group:[e-mail]"
            ]
          }
        ]
      }
    }' \
"https://global-discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app:setIamPolicy"

{
  "version": 1,
  "etag": "2345678901",
  "bindings": [
    {
      "role": "roles/discoveryengine.user",
      "members": [
        "user:cloudysanfrancisco.com",
        "group:[e-mail]"
      ]
    }
  ]
}
  

後續步驟

如要刪除具有 IAM 政策的應用程式，可以先從政策中移除使用者，再刪除應用程式。詳情請參閱「刪除具有 IAM 政策的應用程式的最佳做法」。