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 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. El IAM a nivel de la app permite un control más detallado, lo que les permite a los administradores hacer lo siguiente:

• Restringe 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 del 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 del proyecto, puede acceder a todas las apps de ese proyecto, independientemente de los permisos a nivel de la app. Para restringir el acceso de 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, otórgale 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 solo pueden acceder a esa app específica y usarla. Estos son permisos a nivel del 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 del proyecto puede acceder a ambas apps. Por el contrario, si usas 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 y, de esta manera, impedir 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 de Gemini Enterprise tengan una licencia válida y que se les haya otorgado el rol de Usuario restringido de Gemini Enterprise (roles/discoveryengine.agentspaceRestrictedUser) a nivel del proyecto. Para obtener instrucciones, consulta Cómo otorgar 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 las apps individuales. Si usas un rol personalizado a nivel del 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 se omite discoveryengine.devToolsConfigs.get, se produce 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 del proyecto al acceso a nivel de la app

Para restringir el acceso de los usuarios a apps específicas, debes reemplazar su rol de Usuario de Gemini Enterprise a nivel del 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 cambiar el acceso de un usuario del nivel del proyecto al nivel de la app, sigue estos pasos. Usas la consola de Google Cloud para los cambios a nivel del proyecto y la API para el otorgamiento a nivel de la 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 quítale 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 otorgarle 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 políticas de IAM para apps.

Administra políticas de IAM para 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 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 método getIamPolicy. Se recomienda recuperar la política existente primero 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 región múltiple 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 región múltiple 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 permisos existentes, tu solicitud debe incluir todas las vinculaciones de políticas que desees 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 retrasos en la propagación. Los permisos pueden tardar varios minutos en propagarse por completo. Para obtener más información, consulta Retraso en la 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: Son 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 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: 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 región múltiple 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 región múltiple 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 de 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 Cómo obtener 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.