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 de las apps individuales de Gemini Enterprise.

Si necesitas configurar controles de acceso detallados a nivel de los recursos en las apps y los 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 del proyecto. La 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 proyecto de Google Cloud
• Alinea los permisos con las necesidades de la organización 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 empresarial 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 app. Para restringir a un usuario a apps específicas, reemplaza su rol de usuario de Gemini Enterprise a nivel del 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 deba acceder.

Nota: Los usuarios con permisos de IAM a nivel de la app para una app de Gemini Enterprise solo pueden acceder a esa app específica y usarla. Estos son permisos a nivel del usuario que no incluyen funciones 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 del proyecto puede acceder a ambas apps. Por el contrario, con una política de IAM a nivel de la app, puedes otorgar acceso a un miembro del equipo de ventas solo a la app de toda la empresa, lo que evita 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 se les otorgue el rol de Usuario restringido de Gemini Enterprise (roles/discoveryengine.agentspaceRestrictedUser) a nivel del 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 del proyecto que necesitan los usuarios y, luego, otorgas acceso a apps individuales. Si usas un rol personalizado a nivel de proyecto en lugar del rol predefinido roles/discoveryengine.agentspaceRestrictedUser, asegúrate de que tu rol personalizado incluya los permisos discoveryengine.locations.buildAuthorizationUrl, discoveryengine.dataStores.get, discoveryengine.collections.get y discoveryengine.devToolsConfigs.get. Omitir discoveryengine.devToolsConfigs.get provoca un error 403 PERMISSION_DENIED en los 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 app individual.

Para cambiar el acceso de un usuario del nivel de proyecto al nivel de app, sigue estos pasos. Usa la consola de Google Cloud para los cambios a nivel de proyecto y la API para el otorgamiento a nivel de app, que la consola de Google Cloud no admite.

1. En la consola de Google Cloud , dirígete 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 del proyecto.
3. Si aún no lo hiciste, otorga al usuario el rol de Usuario restringido de Gemini Enterprise (roles/discoveryengine.agentspaceRestrictedUser) a nivel del proyecto.
4. Usa el método setIamPolicy para otorgar al usuario el rol de usuario empresarial 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 las apps.

Administra las políticas de IAM para las apps

Para administrar el acceso a tu app de Gemini Enterprise, puedes usar los métodos de la API de 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 de los usuarios.

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

Obtén la política de IAM actual de tu app con el método getIamPolicy. Se recomienda recuperar primero la política existente para evitar reemplazar 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: Es 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 Cómo especificar una multirregión para tu almacén de datos.
• LOCATION: Es la multirregión de tu almacén de datos: global, us o eu.

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

  Nota: Copia el valor de etag de la respuesta. Este valor es obligatorio para actualizar la política de IAM. El valor de 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 de los usuarios a la app, actualiza la política de IAM de la app con el método setIamPolicy.

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 otorgarles 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 retrasos en la propagación. Los permisos pueden tardar varios minutos en propagarse por completo. Para obtener más información, consulta Retraso 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: Es el valor de etag que obtuviste como respuesta cuando usaste el método getIamPolicy.

• USER_EMAIL, GROUP_EMAIL: Es una o más direcciones de correo electrónico de usuarios o grupos. 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 dejar 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: Es el ID de tu grupo de identidades para cargas de trabajo.

• SUBJECT_ID: Es el identificador del sujeto para una identidad específica.

• NAME: Es el nombre de un atributo.

• VALUE: Es el valor de un atributo.

• PROJECT_ID: el ID de tu proyecto.

• ENDPOINT_LOCATION: Es 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 Cómo especificar una multirregión para tu almacén de datos.

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

• APP_ID: Es 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 los pasos que se indican en 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 quieres 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.