为应用配置访问权限控制

本页面介绍了 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 权限的用户只能访问和使用该特定应用。这些是用户级权限，不包含管理员功能。

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

准备工作

• 确认您拥有 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 政策

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

重要提示： 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 政策的应用的最佳实践。