为应用配置访问权限控制

本页面介绍了 Gemini Enterprise 管理员如何使用 API 来管理各个 Gemini Enterprise 应用的精细访问权限控制。

如果您需要在应用和数据存储区中配置精细的资源级访问权限控制，请参阅为应用和数据存储区配置精细的访问权限控制。

默认情况下，IAM 权限通常在项目级层进行管理。应用级 IAM 可实现更精细的控制，使管理员能够：

• 限制用户对同一 Google Cloud 项目内特定应用的访问权限。
• 根据 Gemini Enterprise 部署的组织需求和数据孤岛调整权限。

重要提示： 项目级 IAM 权限优先于 应用级政策。如果在项目级层向用户授予 Gemini Enterprise User (roles/discoveryengine.agentspaceUser) 角色，则无论应用级权限如何，用户都可以访问该项目中的所有应用。如需将用户限制为只能访问特定应用，请将用户的项目级 Gemini Enterprise User 角色替换为 Gemini Enterprise Restricted User (roles/discoveryengine.agentspaceRestrictedUser) 角色，然后针对用户需要访问的每个应用授予 Gemini Enterprise User 角色。

注意： 拥有 Gemini Enterprise 应用的应用级 IAM 权限的用户只能访问和使用该特定应用。这些是 用户级权限，不包含管理员功能。

例如，假设某个组织有一个人力资源应用和一个公司范围的应用。拥有项目级权限的人力资源团队成员可以访问这两个应用。相比之下，使用应用级 IAM 政策，您可以仅向销售团队成员授予对公司范围应用的访问权限，从而阻止他们访问人力资源应用。

准备工作

• 确认您拥有 Gemini Enterprise Admin (roles/discoveryengine.agentspaceAdmin) 角色。

• 确认所有 Gemini Enterprise 企业用户都拥有有效许可，并且被授予 Gemini Enterprise Restricted User (roles/discoveryengine.agentspaceRestrictedUser) 角色（项目级层）。如需了解相关说明，请参阅向 用户授予权限。

  此角色本身不会授予对任何应用的访问权限。它提供用户所需的项目级访问权限，然后您授予对各个应用的访问权限。如果您使用自定义项目级角色而不是预定义的 roles/discoveryengine.agentspaceRestrictedUser 角色，请确保您的自定义角色包含 discoveryengine.locations.buildAuthorizationUrl、discoveryengine.dataStores.get、discoveryengine.collections.get 和 discoveryengine.devToolsConfigs.get 权限。如果省略 discoveryengine.devToolsConfigs.get，则当 Web 应用检查 devToolsConfig 时，Cloud Audit Logs 中会显示 403 PERMISSION_DENIED 错误 。

从项目级访问权限过渡到应用级访问权限

如需将用户限制为只能访问特定应用，您必须将用户的项目级 Gemini Enterprise User 角色替换为 Gemini Enterprise Restricted User 角色，然后在各个应用级层授予 Gemini Enterprise User 角色。

如需将用户从项目级访问权限过渡到应用级访问权限，请按以下步骤操作。您可以使用 Google Cloud 控制台进行项目级更改， 并使用 API 进行应用级授予， Google Cloud 控制台不支持 应用级授予。

1. 在 Google Cloud 控制台中，前往 IAM 页面。
2. 找到用户，并从其项目级权限中移除 Gemini Enterprise User (roles/discoveryengine.agentspaceUser) 角色。
3. 如果尚未在项目级层向用户授予 Gemini Enterprise Restricted User (roles/discoveryengine.agentspaceRestrictedUser) 角色，请授予该角色。
4. 使用 setIamPolicy 方法向用户授予其需要访问的每个特定应用的 Gemini Enterprise User (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 政策

如需授予或撤消用户对应用的访问权限，请使用应用的 IAM 政策更新 setIamPolicy 方法。

重要提示： setIamPolicy 方法会替换现有政策。为避免移除现有权限，您的请求必须包含您要保留的所有政策绑定，以及任何新的或经过修改的绑定。

IAM 政策使用 Gemini Enterprise User (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 联合的有效成员类型。

  • 如需授予访问权限，请将主账号添加到 members 数组。例如， "user:[e-mail]" 或 "group:[e-mail]"。

    **注意：** 避免在电子邮件地址前后添加多余的空格。

  • 如需撤消访问权限，请从 members 数组中移除主账号。

• POOL_ID：工作负载身份池的 ID。

• SUBJECT_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 政策的应用的最佳实践。