Controlar el acceso a las sesiones con las condiciones de gestión de identidades y accesos

De forma predeterminada, los permisos de gestión de identidades y accesos de las sesiones son a nivel de proyecto. En este documento se describe cómo usar las condiciones de gestión de identidades y accesos para controlar el acceso de forma más granular a los recursos de sesiones de Vertex AI Agent Engine.

Información general

Las condiciones de IAM te permiten conceder acceso a recursos de sesiones y eventos de sesiones solo si se cumplen las condiciones especificadas. Puedes controlar el acceso a las sesiones en función de la cadena userId del recurso Session mediante el atributo de la API aiplatform.googleapis.com/sessionUserId con una expresión escrita en lenguaje de expresión común. El ID de usuario es una cadena arbitraria que se proporciona al crear sesiones, como userId = "userA".

Estas políticas condicionales de Gestión de Identidades y Accesos se crean a nivel de proyecto y se aplican a todas las sesiones y eventos de sesión de un proyecto. Puedes aplicar condiciones de IAM a todo tipo de principales, incluidos los usuarios de tu proyecto y las cuentas de servicio.

Las condiciones de gestión de identidades y accesos (IAM) son útiles para conceder permisos de IAM a muchos recursos de sesión relacionados simultáneamente, incluidos los que aún no existen. Puede restringir el acceso a sus sesiones y eventos para que un usuario solo pueda acceder a su propia información o para que los desarrolladores solo puedan ver determinados recursos de Session sin permisos especiales.

Antes de empezar

Para configurar políticas de gestión de identidades y accesos condicionales para sesiones y eventos de sesión, haga lo siguiente:

• Revisa las condiciones de gestión de identidades y accesos: familiarízate con el resumen de las condiciones de gestión de identidades y accesos.
• Determina los roles necesarios: identifica qué roles de gestión de identidades y accesos de sesión especializados son adecuados para tu caso de uso con el fin de aplicar el principio de mínimos accesos.
• Identifica las entidades afectadas: determina qué personas de tu organización deben recibir qué permisos. Por ejemplo, supongamos que se da la siguiente situación:
  • ¿Los usuarios deberían poder ver las sesiones de otros usuarios?
  • ¿Deberían los desarrolladores poder ver todas las sesiones?
  • ¿Los administradores de proyectos deberían poder ver todas las sesiones?
  • ¿Deberían poder acceder a determinadas sesiones ciertas identidades de agente?
• Concede roles de gestión de identidades y accesos: asegúrate de tener los roles necesarios que contengan los permisos que necesitas para realizar las tareas descritas en este documento.

  Para obtener los permisos que necesitas para aplicar condiciones de gestión de identidades y accesos a los recursos de sesión de Vertex AI Agent Engine, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

  • En el caso de los proyectos: Administrador de gestión de identidades y accesos de proyectos (`roles/resourcemanager.projectIamAdmin`)

  Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

  Estos roles predefinidos contienen los permisos necesarios para aplicar condiciones de gestión de identidades y accesos a los recursos de sesión de Vertex AI Agent Engine. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

  Permisos obligatorios

  Se necesitan los siguientes permisos para aplicar condiciones de IAM a los recursos de sesión de Vertex AI Agent Engine:

  • Define el acceso condicional de gestión de identidades y accesos a nivel de proyecto: `resourcemanager.projects.setIamPolicy`

  También puedes obtener estos permisos con roles personalizados u otros roles predefinidos.

  Si tienes previsto usar las condiciones de gestión de identidades y accesos en toda tu organización, también necesitas permisos para gestionar las políticas de la organización.

Crear acceso condicional para sesiones

Concede acceso condicional a las sesiones añadiendo una condición a un enlace de política de gestión de identidades y accesos a nivel de proyecto. La condición usa la función api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") para inspeccionar el ID de usuario del recurso de sesión. El ID de usuario se define al crear una sesión.

Para obtener una guía detallada sobre cómo crear políticas de gestión de identidades y accesos con condiciones, consulta Condiciones en las políticas de permiso.

Para conceder un solo rol a una entidad, sigue estos pasos:

Consola

1. En la consola de Google Cloud , ve a la página Gestión de identidades y accesos.

   Ir a IAM

2. Selecciona el proyecto.

3. Selecciona una cuenta principal a la que quieras asignar un rol:

   • Para asignar un rol a una entidad de seguridad que ya tiene otros roles en el recurso, busca una fila que contenga la entidad de seguridad, haz clic en Editar entidad de seguridad en esa fila y, a continuación, en Añadir otro rol.

     Para conceder un rol a un agente de servicio, marca la casilla Incluir Google-provided role grants para ver su dirección de correo electrónico.

     Nota: No puedes editar los roles heredados al gestionar el acceso a un recurso. Para editar los roles heredados, ve al recurso en el que se concedió el rol.

   • Para asignar un rol a un principal que no tenga ningún rol en el recurso, haz clic en Conceder acceso y, a continuación, introduce un identificador de principal (por ejemplo, [e-mail] o //iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail]).

4. Seleccione un rol en la lista desplegable para concederlo. Para seguir las prácticas recomendadas de seguridad, elige un rol que incluya solo los permisos que necesite tu principal. Puedes elegir uno de los roles de gestión de identidades y accesos de sesión especializados.

5. Añade una condición al rol usando aiplatform.googleapis.com/sessionUserId como atributo de API. Consulta los ejemplos que se muestran a continuación para ver algunas posibles instrucciones de condición.

6. Haz clic en Guardar. Se concede el rol a la entidad principal en el recurso.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. El comando add-iam-policy-binding te permite asignar rápidamente un rol a una cuenta principal.

   Antes de usar cualquiera de los datos de los comandos que se indican a continuación, haz las siguientes sustituciones:

   • PROJECT_ID: tu ID de proyecto Google Cloud . Los IDs de proyecto son alfanuméricos, como my-project.

   • PRINCIPAL: identificador de la entidad principal o del miembro, que suele tener el siguiente formato: PRINCIPAL_TYPE:ID. Por ejemplo, user:[e-mail] o principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail]. Para ver una lista completa de los valores que puede tener PRINCIPAL, consulta Identificadores principales.

     En el caso del tipo de principal user, el nombre de dominio del identificador debe ser un dominio de Google Workspace o de Cloud Identity. Para saber cómo configurar un dominio de Cloud Identity, consulta la descripción general de Cloud Identity.

   • ROLE_NAME: el nombre del rol que quieres revocar. Se debe utilizar uno de los formatos indicados a continuación.

     • Roles predefinidos: roles/aiplatform.IDENTIFIER
     • Roles personalizados a nivel de proyecto: projects/PROJECT_ID/roles/IDENTIFIER

     Seleccione un rol en la lista desplegable para concederlo. Para seguir las prácticas recomendadas de seguridad, elige un rol que incluya solo los permisos que necesite tu principal. Puedes elegir uno de los roles de gestión de identidades y accesos de sesión especializados.

   • CONDITION: añade una condición al rol con aiplatform.googleapis.com/sessionUserId como atributo de la API. Consulta los ejemplos que se muestran a continuación para ver algunas posibles instrucciones de condición.

   Ejecuta el siguiente comando:

   Linux, macOS o Cloud Shell

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=PRINCIPAL --role=ROLE_NAME \
       --condition=CONDITION

   Windows (PowerShell)

   gcloud projects add-iam-policy-binding PROJECT_ID `
       --member=PRINCIPAL --role=ROLE_NAME `
       --condition=CONDITION

   Windows (cmd.exe)

   gcloud projects add-iam-policy-binding PROJECT_ID ^
       --member=PRINCIPAL --role=ROLE_NAME ^
       --condition=CONDITION

   La respuesta contiene la política de gestión de identidades y accesos actualizada.

Terraform

Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de Terraform. Para obtener más información, consulta la documentación de referencia del proveedor Terraform.

Si usas Terraform para definir tus políticas de gestión de identidades y accesos, puedes incluir una condición en el recurso google_project_iam_member para restringir el acceso de un miembro a las sesiones.

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Session Access Condition"
    description = "IAM condition for Session"
    expression  = "CONDITION"
  }
}

Sustituye las siguientes variables:

• PROJECT_ID: tu ID de proyecto Google Cloud . Los IDs de proyecto son alfanuméricos, como my-project.

• ROLE: el rol de gestión de identidades y accesos que se va a conceder. Por ejemplo, roles/aiplatform.sessionEditor.

• MEMBER: la entidad a la que se le va a conceder el rol. Por ejemplo, user:[e-mail]. Para ver una lista completa de los valores que puede tener MEMBER, consulta Identificadores principales.

• CONDITION: tu instrucción de condición de gestión de identidades y accesos que usa aiplatform.googleapis.com/sessionUserId como atributo de la API. Consulta los ejemplos que se muestran a continuación para ver algunas posibles instrucciones de condición.

Prácticas recomendadas para los permisos a nivel de User-ID

Cuando cree condiciones para las sesiones, siga estas prácticas recomendadas:

1. Usar roles de gestión de identidades y accesos de sesión especializados: las condiciones de gestión de identidades y accesos de sesión solo se deben usar en roles que se apliquen a sesiones y eventos de sesión. Puedes usar roles especializados, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor y aiplatform.googleapis.com/sessionUser, para evitar que se conceda un acceso excesivo. Para obtener más información, consulta la sección Roles de gestión de identidades y accesos de sesiones especializadas.
2. Usa condiciones positivas: te recomendamos que uses condiciones positivas (como comprobaciones de igualdad o la presencia de prefijos) en aiplatform.googleapis.com/sessionUserId para aumentar la precisión. Como los tipos y servicios no admitidos se representan con un ID de usuario vacío, las condiciones negativas (como las comprobaciones de desigualdad) pueden coincidir inadvertidamente con una amplia gama de recursos, lo que puede ser demasiado permisivo y permitir que se concedan permisos de forma inesperada.
3. Acorta las condiciones si es posible: te recomendamos que uses la lógica más breve y sencilla en tus expresiones de condición de IAM, sobre todo si tienes previsto usar una gran cantidad de condiciones. Las políticas de permiso de gestión de identidades y accesos tienen un límite de tamaño, por lo que simplificar las condiciones evitará que se alcancen los límites de gestión de identidades y accesos. Para obtener más información, consulta Limitaciones. Por ejemplo, puede simplificar la comprobación de dos IDs de usuario diferentes combinando la instrucción compuesta api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB', ya que da el mismo resultado que la instrucción más corta api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Roles de gestión de identidades y accesos de sesión especializados

Es fundamental evitar que las políticas de gestión de identidades y accesos sean demasiado permisivas al usar las condiciones de IAM. En la siguiente tabla se indican los roles especializados que puedes usar al conceder roles de IAM condicionales para las APIs de sesión:

Nombre de función	Descripción	Permisos incluidos
roles/aiplatform.sessionViewer	Da acceso de solo lectura a las sesiones y a los eventos de ficha.	aiplatform.googleapis.com/sessions.get aiplatform.googleapis.com/sessions.list aiplatform.googleapis.com/sessionEvents.list
roles/aiplatform.sessionEditor	Da acceso de escritura a las sesiones y a los eventos añadidos.	aiplatform.googleapis.com/sessions.create aiplatform.googleapis.com/sessions.update aiplatform.googleapis.com/sessions.delete aiplatform.googleapis.com/sessionEvents.append
roles/aiplatform.sessionUser	Concede acceso completo a las sesiones y los eventos, incluidos todos los permisos de lector y editor.	Incluye todos los permisos de sessionEditor y sessionViewer.

Usar condiciones de gestión de identidades y accesos con sesiones

En esta sección se incluyen los siguientes ejemplos de uso de las condiciones de gestión de identidades y accesos con sesiones:

1. Concede acceso de lectura a las sesiones con una coincidencia exacta del ID de usuario.
2. Concede acceso de escritura a las sesiones que contengan un prefijo específico en el ID de usuario.
3. Conceder acceso completo a las sesiones que contengan uno de los dos IDs de usuario.

Concede acceso de lectura a las sesiones con una concordancia exacta del ID de usuario

La siguiente condición concede a la vista [e-mail] acceso solo a las sesiones que tengan el ID de usuario userA.

Esto significa que el individuo puede obtener sesiones y enumerar los eventos de sesión, siempre que el ID de usuario sea exactamente userA. El usuario no tiene acceso a las sesiones con el ID de usuario userB.

{
  "members": ["user:[e-mail]"],
  "role": "roles/aiplatform.sessionViewer",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'userA'"
  }
}

Conceder acceso de escritura a las sesiones que contengan un prefijo específico en el ID de usuario

La siguiente condición concede a [e-mail] acceso de edición a cualquier sesión que contenga el ID de usuario que empiece por user. Puedes usar startsWith para comprobar los prefijos y endsWith para comprobar los sufijos.

Esto significa que el desarrollador puede crear, actualizar y eliminar sesiones, así como añadir eventos, con IDs de usuario como userA o user1234.

{
  "members": ["user:[e-mail]"],
  "role": "roles/aiplatform.sessionEditor",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '').startsWith('user')"
  }
}

Conceder acceso completo a las sesiones que contengan uno de los dos IDs de usuario

La siguiente condición concede al grupo group:[e-mail] (lector y editor) acceso a las sesiones que solo tienen los IDs de usuario userA o user123.

{
  "members": ["group:[e-mail]"],
  "role": "roles/aiplatform.sessionUser",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['userA', 'user123']"
  }
}

Limitaciones

1. Límite de principales: las políticas de gestión de identidades y accesos están limitadas a 1500 principales únicos. Este límite se puede gestionar mediante Grupos de Google. Consulta más información en Límites de todas las entidades principales.
2. Compatibilidad con la API ListSessions: la API ListSessions no admite condiciones de IAM. Para conceder permisos de ListSessions, debes asignar al principal un rol incondicional, como aiplatform.googleapis.com/sessionViewer o aiplatform.googleapis.com/sessionUser, o un rol de Vertex AI incondicional pertinente.