Controla el acceso a las sesiones con las condiciones de IAM

De forma predeterminada, los permisos de Identity and Access Management de las sesiones se encuentran a nivel del proyecto. En este documento, se describe cómo usar las condiciones de IAM para controlar el acceso más detallado a los recursos de las sesiones de Vertex AI Agent Engine.

Descripción general

Las condiciones de IAM te permiten otorgar acceso a los recursos de sesión y eventos de sesión solo si se cumplen las condiciones especificadas. Puedes controlar el acceso a las sesiones según la cadena userId dentro del recurso Session con el atributo de la API aiplatform.googleapis.com/sessionUserId y una expresión escrita en Common Expression Language. El ID de usuario es una cadena arbitraria que se proporciona cuando se crean sesiones, como userId = "userA".

Estas políticas condicionales de Identity and Access Management se crean a nivel del proyecto y se aplican a todos los eventos y sesiones dentro 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 IAM son útiles para otorgar permisos de Identity and Access Management (IAM) a muchos recursos de sesión relacionados de forma simultánea, incluidos los que aún no existen. Puedes restringir el acceso a tus sesiones y eventos para que un usuario solo pueda acceder a su propia información o para que los desarrolladores solo puedan ver ciertos recursos de Session sin permisos especiales.

Antes de comenzar

Para configurar políticas de Identity and Access Management condicionales para sesiones y eventos de sesión, haz lo siguiente:

Revisa las Condiciones de IAM: Familiarízate con la descripción general de las Condiciones de IAM.
Determina los roles necesarios: Identifica qué roles de IAM de sesión especializados son adecuados para tu caso de uso y, así, garantizar el principio de privilegio mínimo.
Identifica a los principales afectados: Identifica quiénes de tu organización deberían recibir qué permisos. Por ejemplo, considera lo siguiente:
- ¿Los usuarios deberían poder ver las sesiones de otros usuarios?
- ¿Los desarrolladores deberían poder ver todas las sesiones?
- ¿Los administradores del proyecto deberían poder ver todas las sesiones?
- ¿Ciertas identidades de agentes deberían poder acceder a ciertas sesiones?
Otorga roles de IAM: Asegúrate de tener los roles necesarios que contengan los permisos que necesitas para realizar las tareas de este documento.
Para obtener los permisos que necesitas para aplicar condiciones de IAM a los recursos de sesión de Vertex AI Agent Engine, pídele a tu administrador que te otorgue los siguientes roles de IAM:
- Para proyectos: Administrador de IAM de proyecto (`roles/resourcemanager.projectIamAdmin`)
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para aplicar condiciones de IAM a los recursos de sesión de Vertex AI Agent Engine. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:
Permisos necesarios

Se requieren los siguientes permisos para aplicar condiciones de IAM a los recursos de sesión de Vertex AI Agent Engine:
- Establece acceso condicional a IAM a nivel del proyecto: `resourcemanager.projects.setIamPolicy`
También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.
Si planeas usar Condiciones de IAM en toda tu organización, también necesitas permisos para administrar las políticas de la organización.

Cómo crear acceso condicional para sesiones

Otorga acceso condicional a las sesiones agregando una condición a una vinculación de política de Identity and Access Management a nivel del 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. Defines un ID de usuario cuando creas una sesión.

Para obtener una guía detallada sobre cómo crear políticas de IAM con condiciones, consulta Condiciones en las políticas de permisos.

Para otorgar una sola función a una principal, sigue estos pasos:

Console

En la consola de Google Cloud , dirígete a la página IAM.

Ir a IAM
Elige tu proyecto.
Selecciona una principal para otorgarle una función:
- Para otorgar un rol a una principal que ya tenga otros roles en el recurso, busca una fila que contenga la principal y haz clic en Editar principal en esa fila y en Agregar otro rol.
  
  Para otorgar un rol a un agente de servicio, selecciona la casilla de verificación Incluir asignaciones de roles proporcionadas porGoogle para ver su dirección de correo electrónico.
  
  Nota: No puedes editar las funciones heredadas cuando administras el acceso a un recurso. Para editar las funciones heredadas, ve al recurso en el que se otorgó la función.
- Para otorgar un rol a una principal que aún no tenga otros roles en el recurso, haz clic en Otorgar acceso y, luego, ingresa un identificador de principal (por ejemplo, my-user@example.com o //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com).
Elige un rol para otorgar de la lista desplegable. Para una mejor seguridad, elige una función que incluya solo los permisos que necesita tu principal. Puedes elegir uno de los roles de IAM de sesión especializados.
Agrega una condición al rol con aiplatform.googleapis.com/sessionUserId como atributo de la API. Consulta los siguientes ejemplos para ver algunas posibles declaraciones de condición.
Haz clic en Guardar. A la principal se le otorga la función en el recurso.

gcloud

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.
El comando add-iam-policy-binding te permite otorgar un rol a una principal con rapidez.

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
- PROJECT_ID: Es el ID del proyecto de Google Cloud . Los IDs de proyecto son alfanuméricos, como my-project.
- PRINCIPAL: Un identificador para la principal o el miembro, que suele tener el siguiente formato: PRINCIPAL_TYPE:ID. Por ejemplo, user:my-user@example.com o principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Si deseas obtener una lista completa de los valores que PRINCIPAL puede tener, consulta Identificadores de principal.
  
  Para el tipo de principal user, el nombre de dominio en el identificador debe ser un dominio de Google Workspace o de Cloud Identity. Para obtener información sobre cómo configurar un dominio de Cloud Identity, consulta la descripción general de Cloud Identity.
- ROLE_NAME: El nombre del rol que deseas revocar. Usa uno de los siguientes formatos:
  - Roles predefinidos: roles/aiplatform.IDENTIFIER
  - Roles personalizados a nivel de proyecto: projects/PROJECT_ID/roles/IDENTIFIER
  Elige un rol para otorgar de la lista desplegable. Para una mayor seguridad, elige un rol que incluya solo los permisos que necesita la principal. Puedes elegir uno de los roles de IAM de sesión especializados.
- CONDITION: Agrega una condición al rol con aiplatform.googleapis.com/sessionUserId como atributo de la API. Consulta los siguientes ejemplos para ver algunas posibles declaraciones 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 IAM actualizada.

Terraform

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform. Para obtener más información, consulta la documentación de referencia del proveedor de Terraform.

Si usas Terraform para establecer tus políticas de IAM, 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"
  }
}

Reemplaza las siguientes variables:

PROJECT_ID: Es el ID del proyecto de Google Cloud . Los IDs de proyecto son alfanuméricos, como my-project.
ROLE: Es el rol de IAM que se otorgará, por ejemplo, roles/aiplatform.sessionEditor.
MEMBER: Es el principal al que se le otorgará el rol, por ejemplo, user:developerA@corp.com. Si deseas obtener una lista completa de los valores que MEMBER puede tener, consulta Identificadores de principal.
CONDITION: Es tu instrucción de condición de IAM que usa aiplatform.googleapis.com/sessionUserId como el atributo de la API. Consulta los siguientes ejemplos para ver algunas posibles declaraciones de condición.

Prácticas recomendadas para los permisos a nivel del ID de usuario

Cuando crees condiciones para las sesiones, usa las siguientes prácticas recomendadas:

Usa roles de IAM de sesión especializados: Las condiciones de IAM de sesión solo se deben usar para los roles que se aplican a las sesiones y los eventos de sesión. Puedes usar roles especializados, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor y aiplatform.googleapis.com/sessionUser, para evitar el acceso demasiado permisivo. Consulta la sección Roles de IAM especializados para sesiones para obtener más detalles.
Usa condiciones positivas: Para obtener una mayor precisión, te recomendamos que uses condiciones positivas (como verificaciones de igualdad o la presencia de prefijos) en aiplatform.googleapis.com/sessionUserId. Dado que los tipos y servicios no admitidos se representan con un ID de usuario vacío, las condiciones negativas (como las verificaciones de desigualdad) pueden coincidir de forma involuntaria con una amplia variedad de recursos, lo que puede ser demasiado permisivo y permitir el otorgamiento inesperado de permisos.
Acorta las condiciones si es posible: Te recomendamos que uses la lógica más corta y simple posible en tus expresiones de condiciones de IAM, en especial si planeas tener una gran cantidad de condiciones. Las políticas de permisos de IAM tienen una limitación de tamaño, y simplificar las condiciones evitará que se alcancen las limitaciones de IAM. Consulta Limitaciones para obtener más detalles. Por ejemplo, puedes simplificar la verificación de dos IDs de usuario diferentes combinando la sentencia compuesta: api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB', ya que se evalúa con el mismo resultado que la sentencia más corta api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Roles de IAM de sesión especializados

Es fundamental evitar políticas de IAM demasiado permisivas cuando se usan condiciones de IAM. En la siguiente tabla, se enumeran los roles especializados que puedes usar cuando otorgas roles de IAM condicionales para las APIs de sesión:

Nombre del rol	Descripción	Permisos incluidos
`roles/aiplatform.sessionViewer`	Otorga acceso de solo lectura a las sesiones y los eventos de la ficha.	`aiplatform.googleapis.com/sessions.get` `aiplatform.googleapis.com/sessions.list` `aiplatform.googleapis.com/sessionEvents.list`
`roles/aiplatform.sessionEditor`	Otorga acceso de escritura a las sesiones y a los eventos de anexión.	`aiplatform.googleapis.com/sessions.create` `aiplatform.googleapis.com/sessions.update` `aiplatform.googleapis.com/sessions.delete` `aiplatform.googleapis.com/sessionEvents.append`
`roles/aiplatform.sessionUser`	Otorga acceso completo a las sesiones y los eventos, incluidos todos los permisos de visualizador y editor.	Incluye todos los permisos de `sessionEditor` y `sessionViewer`.

Usa condiciones de IAM con sesiones

En esta sección, se incluyen los siguientes ejemplos de uso de las condiciones de IAM con sesiones:

Otorga acceso de lectura a las sesiones que coinciden exactamente con el ID de usuario.
Otorga acceso de escritura a las sesiones que contienen un prefijo específico en el ID de usuario.
Otorga acceso completo a las sesiones que contienen uno de los dos IDs de usuario.

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

La siguiente condición otorga al individuo userA@gmail.com acceso de visualización solo a las sesiones que tienen el ID de usuario exacto userA.

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

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

Otorga acceso de escritura a las sesiones que contienen un prefijo específico en el ID de usuario.

La siguiente condición otorga al usuario individual developerA@corp.com acceso de edición a cualquier sesión que contenga el ID de usuario que comience con user. Puedes usar startsWith para la verificación de prefijos y endsWith para la verificación de sufijos.

Esto significa que el desarrollador tiene la capacidad de crear, actualizar y borrar sesiones, además de agregar eventos, con IDs de usuarios como userA o user1234.

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

Otorga acceso completo a las sesiones que contienen uno de los dos IDs de usuario

La siguiente condición otorga al grupo group:engineering@corp.com acceso de usuario (visualizador y editor) a las sesiones que solo tienen los IDs de usuario userA o user123.

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

Limitaciones

Límite de principales: Las políticas de IAM se limitan a 1,500 principales únicos. Este límite se puede administrar con grupos de Google. Obtén más información en Límites de todas las principales.
Compatibilidad con la API de ListSessions: La API de ListSessions no admite condiciones de IAM. Para otorgar permisos de ListSessions, debes otorgar a la principal un rol incondicional, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser o un rol incondicional relevante de Vertex AI.