Cómo configurar los controles de acceso para las apps

En esta página, se explica cómo un administrador de Gemini Enterprise puede usar la API para administrar el control de acceso detallado para apps individuales de Gemini Enterprise.

Si necesitas configurar controles de acceso detallados a nivel de recursos en apps y almacenes de datos, consulta Configura controles de acceso detallados para apps y almacenes de datos.

De forma predeterminada, los permisos de IAM suelen administrarse a nivel de proyecto. IAM a nivel de la app permite un control más detallado, lo que permite a los administradores hacer lo siguiente:

• Restringir el acceso de los usuarios a apps específicas dentro del mismo Google Cloud proyecto.
• Alinear los permisos con las necesidades organizacionales y los silos de datos para tus implementaciones de Gemini Enterprise.

Importante: Los permisos de IAM a nivel de proyecto tienen prioridad sobre las políticas a nivel de la app. Si a un usuario se le otorga el rol de Usuario de Gemini Enterprise (roles/discoveryengine.agentspaceUser) a nivel de proyecto, puede acceder a todas las apps de ese proyecto, independientemente de los permisos a nivel de la app. Para restringir un usuario a apps específicas, reemplaza su rol de Usuario de Gemini Enterprise a nivel de proyecto por el rol de Usuario restringido de Gemini Enterprise (roles/discoveryengine.agentspaceRestrictedUser) y, luego, otorga el rol de Usuario de Gemini Enterprise en cada app a la que necesite acceder.

Nota: Los usuarios con permisos de IAM a nivel de la app para una app de Gemini Enterprise pueden acceder y usar solo esa app específica. Estos son permisos a nivel de usuario que no incluyen capacidades de administrador.

Por ejemplo, considera una organización con una app de RR.HH. y una app para toda la empresa. Un miembro del equipo de RR.HH. con permisos a nivel de proyecto puede acceder a ambas apps. Por el contrario, con una política de IAM a nivel de la app, puedes otorgar a un miembro del equipo de ventas acceso solo a la app de toda la empresa, lo que impide que acceda a la app de RR.HH.

Antes de comenzar

• Confirma que tienes el rol de Administrador de Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).

• Confirma que todos los usuarios empresariales de Gemini Enterprise tengan una licencia válida y que se les otorgue el rol de Usuario restringido de Gemini Enterprise (roles/discoveryengine.agentspaceRestrictedUser) a nivel de proyecto. Para obtener instrucciones, consulta Otorga permisos a tus usuarios.

  Este rol no otorga acceso a ninguna app por sí solo. Proporciona el acceso a nivel de proyecto que necesitan los usuarios y, luego, les otorgas acceso a apps individuales. Si usas un rol personalizado a nivel de proyecto en lugar del rol roles/discoveryengine.agentspaceRestrictedUser predefinido, asegúrate de que tu rol personalizado incluya los permisos discoveryengine.locations.buildAuthorizationUrl, discoveryengine.dataStores.get, discoveryengine.collections.get y discoveryengine.devToolsConfigs.get. Si omites discoveryengine.devToolsConfigs.get, se produce un error 403 PERMISSION_DENIED en Registros de auditoría de Cloud cuando la app web verifica devToolsConfig.

Transición del acceso a nivel de proyecto al acceso a nivel de la app

Para restringir a los usuarios a apps específicas, debes reemplazar su rol de Usuario de Gemini Enterprise a nivel de proyecto por el rol de Usuario restringido de Gemini Enterprise y, luego, otorgar el rol de Usuario de Gemini Enterprise a nivel de la app individual.

Para hacer la transición de un usuario del acceso a nivel de proyecto al acceso a nivel de la app, sigue estos pasos. Usas la Google Cloud console para los cambios a nivel de proyecto, y la API para el otorgamiento a nivel de la app, que la Google Cloud console no admite.

1. En la Google Cloud console, ve a la página IAM.
2. Busca al usuario y quita el rol de Usuario de Gemini Enterprise (roles/discoveryengine.agentspaceUser) de sus permisos a nivel de proyecto.
3. Si aún no lo hiciste, otorga al usuario el rol de Usuario restringido de Gemini Enterprise (roles/discoveryengine.agentspaceRestrictedUser) a nivel de proyecto.
4. Usa el método setIamPolicy para otorgar al usuario el rol de Usuario de Gemini Enterprise (roles/discoveryengine.agentspaceUser) para cada app específica a la que necesite acceder. Para obtener más información, consulta Administra las políticas de IAM para apps.

Administra las políticas de IAM para apps

Para administrar el acceso a tu app de Gemini Enterprise, puedes usar los métodos de la API getIamPolicy y setIamPolicy.

En los siguientes pasos, se muestra cómo recuperar la política actual y, luego, actualizarla para otorgar o revocar el acceso del usuario.

Obtén la política de IAM de la app

Obtén la política de IAM actual de tu app con el getIamPolicy método. Se recomienda recuperar primero la política existente para evitar anular los permisos actuales.

REST

Término clave: En Gemini Enterprise, el término app se puede usar indistintamente con el término motor en el contexto de las APIs. Un motor de Gemini Enterprise es un motor de búsqueda genérico en el que el campo app_type se establece en 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"

Reemplaza lo siguiente:

• PROJECT_ID: el ID de tu proyecto.
• ENDPOINT_LOCATION: la multirregión para tu solicitud a la API. Especifica uno de los siguientes valores:
  • us para la multirregión de EE.UU.
  • eu para la multirregión de la UE
  • global para la ubicación global
  Para obtener más información, consulta Especifica una multirregión para tu almacén de datos.
• LOCATION: la multirregión de tu almacén de datos: global, us o eu

• APP_ID: el ID de la app que deseas configurar.

  Nota: Copia el valor etag de la respuesta. Este valor es obligatorio para actualizar la política de IAM. El valor etag cambia con cada actualización de la política.

Ejemplo de comando y resultado

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"
}
  

Actualiza la política de IAM de la app

Para otorgar o revocar el acceso del usuario a la app, actualiza la política de IAM de la app con el setIamPolicy método.

Importante: El método setIamPolicy reemplaza la política existente. Para evitar quitar los permisos existentes, tu solicitud debe incluir todas las vinculaciones de políticas que deseas conservar, además de las vinculaciones nuevas o modificadas.

La política de IAM usa el rol de Usuario de Gemini Enterprise (roles/discoveryengine.agentspaceUser) para otorgar a los usuarios acceso directo a la app.

Nota: Los cambios en las políticas de IAM, como los que se realizan con setIamPolicy, están sujetos a demoras de propagación. Los permisos pueden tardar varios minutos en propagarse por completo. Para obtener más información, consulta Demora de propagación de IAM.

REST

Término clave: En Gemini Enterprise, el término app se puede usar indistintamente con el término motor en el contexto de las APIs. Un motor de Gemini Enterprise es un motor de búsqueda genérico en el que el campo app_type se establece en 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"

Reemplaza lo siguiente:

• ETAG: el valor etag que obtuviste como respuesta cuando usaste el método getIamPolicy.

• USER_EMAIL, GROUP_EMAIL: una o más direcciones de correo electrónico de usuario o grupo. Además de user y group, principal y principalSet son tipos de miembros válidos para la Federación de Workload Identity.

  • Para otorgar acceso, agrega principales al array members. Por ejemplo, "user:[e-mail]" o "group:[e-mail]".

    Nota: Evita los espacios adicionales antes o después de la dirección de correo electrónico.

  • Para revocar el acceso, quita las principales del array members.

• POOL_ID: El ID de tu grupo de identidades para cargas de trabajo.

• SUBJECT_ID: El identificador de asunto para una identidad específica.

• NAME: El nombre de un atributo.

• VALUE: El valor de un atributo.

• PROJECT_ID: el ID de tu proyecto.

• ENDPOINT_LOCATION: la multirregión para tu solicitud a la API. Especifica uno de los siguientes valores:

  • us para la multirregión de EE.UU.
  • eu para la multirregión de la UE
  • global para la ubicación global
  Para obtener más información, consulta Especifica una multirregión para tu almacén de datos.

• LOCATION: la multirregión de tu almacén de datos: global, us o eu.

• APP_ID: el ID de la app que deseas configurar.

  Nota: El valor etag cambia con cada actualización de la política. Para volver a actualizar la política, primero debes obtener el nuevo etag siguiendo Obtén la política de IAM de la app.

Ejemplo de comando y resultado

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]"
      ]
    }
  ]
}
  

Próximos pasos

Si deseas borrar una app con una política de IAM, puedes quitar a los usuarios de la política antes de borrar la app. Para obtener más información, consulta Prácticas recomendadas para borrar una app con una política de IAM.