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

本頁說明 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 權限，就只能存取及使用該特定應用程式。這些是使用者層級的權限，不包含管理功能。

舉例來說，假設某個機構有 HR 應用程式和全公司適用的應用程式。如果 HR 小組成員擁有專案層級的權限，就能存取這兩個應用程式。相較之下，使用應用程式層級的 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 政策

如要管理 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) 角色，授予使用者應用程式的直接存取權。

注意： 使用 setIamPolicy 等工具變更 IAM 政策後，可能會有傳播延遲問題。權限可能需要幾分鐘才會全面生效。詳情請參閱「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 政策的應用程式的最佳做法」。