Controlar el acceso a Memory Bank con condiciones de gestión de identidades y accesos

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

Información general

Las condiciones de IAM te permiten conceder acceso a recursos de memoria y de revisión de memoria solo si se cumplen las condiciones especificadas. Puedes controlar el acceso a los recuerdos en función del campo scope de un recurso de recuerdo mediante el atributo de API "aiplatform.googleapis.com/memoryScope" con una expresión escrita en lenguaje de expresión común. El ámbito es un diccionario arbitrario que se proporciona al crear o generar recuerdos, como {'user_id': '123'}, que te permite organizar qué recuerdos pertenecen a qué grupo.

Estas políticas de gestión de identidades y accesos condicionales se crean a nivel de proyecto y se aplican a todos los recuerdos 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 relacionados de Memory Bank simultáneamente, incluidos los que aún no existen. Puedes restringir el acceso a tus recuerdos y revisiones para que un usuario solo pueda acceder a su propia información o para que los desarrolladores solo puedan ver determinados recursos de Memory Bank sin permisos especiales.

Antes de empezar

Para configurar políticas de gestión de identidades y accesos condicionales para recuerdos y revisiones de recuerdos, sigue estos pasos:

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 Memory Bank especializados son adecuados para tu caso práctico 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:
- Indica si los desarrolladores deben poder ver todos los recuerdos.
- Si los administradores del proyecto deben poder ver todos los recuerdos.
- Si determinadas identidades de agente solo pueden acceder a determinados recuerdos.
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 Memory Bank 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 Memory Bank de Vertex AI Agent Engine. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:
Permisos obligatorios

Para aplicar condiciones de gestión de identidades y accesos a los recursos de Memory Bank de Vertex AI Agent Engine, se necesitan los siguientes permisos:
- 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 los recuerdos

El acceso condicional a los recuerdos se concede 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/memoryScope', {}) para inspeccionar el mapa de ámbito de un recurso de memoria. El ámbito se define al crear o generar un recuerdo.

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

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

Ir a IAM
Selecciona el proyecto.
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, my-user@example.com o //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com).
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 especializados de Memory Bank.
Añade una condición al rol usando aiplatform.googleapis.com/memoryScope como atributo de API. Consulta los ejemplos que se muestran a continuación para ver algunas posibles instrucciones de condición.
Haz clic en Guardar. Se concede el rol a la entidad principal 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 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:my-user@example.com o principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. 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 especializados de Memory Bank.
- CONDITION: añade una condición al rol con aiplatform.googleapis.com/memoryScope 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 los recuerdos.

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Memory Access Condition"
    description = "IAM condition for Memory Bank"
    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.memoryEditor.
MEMBER: la entidad a la que se le va a asignar el rol. Por ejemplo, user:developerA@corp.com. 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/memoryScope 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 ámbito

Cuando crees condiciones para Memory Bank, sigue estas prácticas recomendadas:

Usar roles especializados de Memory Bank: las condiciones de gestión de identidades y accesos de Memory Bank solo se deben usar en roles que se apliquen a recuerdos y revisiones de recuerdos. Puedes usar roles especializados, como aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor y aiplatform.googleapis.com/memoryUser, para evitar que se conceda un acceso excesivo. Para obtener más información, consulta los roles de gestión de identidades y accesos de Memory Bank especializado.
Usa condiciones positivas: te recomendamos que uses condiciones positivas (como comprobaciones de igualdad o la presencia de pares clave-valor) en aiplatform.googleapis.com/memoryScope para aumentar la precisión. Como los tipos y servicios no admitidos se representan mediante un ámbito 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.
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 IAM tienen un límite de tamaño, por lo que simplificar las condiciones evita que se alcancen estos límites. Para obtener más información, consulta Limitaciones. Por ejemplo, puedes omitir la comprobación de la presencia de una clave en la expresión 'user_id' in "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA', ya que se evalúa con el mismo resultado que la instrucción más corta api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'.

Roles de gestión de identidades y accesos especializados de Memory Bank

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 Memory Bank:

Nombre de función	Descripción	Permisos incluidos
`roles/aiplatform.memoryViewer`	Permite acceder de solo lectura a los recuerdos y a las revisiones de recuerdos.	`aiplatform.googleapis.com/memories.get` `aiplatform.googleapis.com/memories.list` `aiplatform.googleapis.com/memories.retrieve` `aiplatform.googleapis.com/memoryRevisions.list` `aiplatform.googleapis.com/memoryRevisions.get`
`roles/aiplatform.memoryEditor`	Concede acceso de escritura y generación a los recuerdos, así como acceso de reversión a las revisiones de los recuerdos.	`aiplatform.googleapis.com/memories.create` `aiplatform.googleapis.com/memories.update` `aiplatform.googleapis.com/memories.delete` `aiplatform.googleapis.com/memories.generate` `aiplatform.googleapis.com/memoryRevisions.rollback`
`roles/aiplatform.memoryUser`	Concede acceso completo a los recuerdos y las revisiones, incluidos todos los permisos de lector y editor.	Incluye todos los permisos de `memoryEditor` y `memoryViewer`.

Usar las condiciones de gestión de identidades y accesos con Memory Bank

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

Concede acceso de lectura a los recuerdos con una coincidencia de ámbito exacta.
Concede acceso de escritura a recuerdos con un ámbito que contenga un par clave-valor específico.
Concede acceso completo a los recuerdos con un ámbito que contenga claves específicas.
Concede acceso completo a los recuerdos con un ámbito que contenga un prefijo específico.
Concede acceso completo a los recuerdos con el ámbito de la clave y un conjunto de valores permitidos.

Concede acceso de lectura a los recuerdos con una coincidencia de ámbito exacta

La siguiente condición concede al usuario userA@gmail.com acceso de lectura solo a los recuerdos que tengan el ámbito exacto {"userId": "userA"}.

Esto significa que el miembro puede obtener y recuperar recuerdos, así como enumerar y obtener las revisiones de esos recuerdos, siempre que el ámbito sea exactamente {"userId": "userA"}. El usuario no tiene acceso a los recuerdos con ámbitos como {'userId': 'userA', 'source': 'ADK'}.

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

Concede acceso de escritura a los recuerdos con un ámbito que contenga un par clave-valor específico

La siguiente condición concede a la persona developerA@corp.com acceso de edición a cualquier recuerdo que contenga el par clave-valor 'userId': 'userA'.

Esto significa que el usuario puede crear, actualizar, eliminar y generar recuerdos, así como crear y restaurar las revisiones de esos recuerdos, con ámbitos como {'userId': 'userA'} y {'userId': 'userA', 'source': 'ADK'}.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.memoryEditor",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] == 'userA'"
  }
}

Conceder acceso completo a los recuerdos con un ámbito que contenga claves específicas

La siguiente condición concede al grupo group:engineering@corp.com (lector y editor) acceso a los recuerdos que tengan la clave 'admin_override' o 'public_access_flag'.

Esto significa que los miembros del grupo tienen acceso completo de lectura y escritura a los recuerdos con ámbitos como {'admin_override': 'true'}, {'admin_override': 'true', 'public_access_flag': 'false'} y {'userId': 'userA', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "('admin_override' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {})) || ('public_access_flag' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}))"
  }
}

Conceder acceso completo a los recuerdos con un ámbito que contenga un prefijo específico

La siguiente condición concede al usuario group:engineering@corp.com (lector y editor) acceso a los recuerdos que tienen la clave 'userId' con un valor que empieza por 'user'.Puedes usar 'startsWith' para comprobar el prefijo y 'endsWith' para comprobar el sufijo.

Esto significa que los miembros del grupo tienen acceso completo de lectura y escritura a los recuerdos con ámbitos como {'userId': 'userA'} y {'userId': 'userB', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'].startsWith('user')"
  }
}

Concede acceso completo a los recuerdos con el ámbito de la clave y un conjunto de valores permitidos.

La siguiente condición concede al grupo group:engineering@corp.com (lector y editor) acceso a los recuerdos que tienen la clave 'userId' con los valores 'userA' o 'userB'.