Controla el acceso a Memory Bank con condiciones de IAM

De forma predeterminada, los permisos de Identity and Access Management de la memoria 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 Memory Bank de Vertex AI Agent Engine.

Descripción general

Las condiciones de IAM te permiten otorgar acceso a los recursos de memoria y revisión de memoria solo si se cumplen las condiciones especificadas. Puedes controlar el acceso a los recuerdos según el campo scope dentro de un recurso de recuerdo con el atributo de API "aiplatform.googleapis.com/memoryScope" y una expresión escrita en Common Expression Language. El alcance es un diccionario arbitrario que se proporciona cuando se crean o generan recuerdos, como {'user_id': '123'}, que te permite organizar qué recuerdos pertenecen a qué grupo.

Estas políticas condicionales de Identity and Access Management se crean a nivel del proyecto y se aplican a todos los recuerdos 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 relacionados de Memory Bank de forma simultánea, 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 ciertos recursos de Memory Bank sin permisos especiales.

Antes de comenzar

Para configurar políticas de IAM condicionales para recuerdos y revisiones de recuerdos, 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 especializados de IAM de Memory Bank 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:
- Indica si los desarrolladores deben poder ver todos los recuerdos.
- Indica si los administradores del proyecto deben poder ver todos los recuerdos.
- Indica si ciertas identidades de agentes solo pueden acceder a ciertos recuerdos.
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 Memory Bank de Vertex AI Agent Engine, pídele a tu administrador que te otorgue los siguientes roles de IAM:
- Para proyectos: Administrador de IAM del 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 Memory Bank 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 del banco de memoria 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 los recuerdos

El acceso condicional a los recuerdos se otorga agregando una condición a una vinculación de política de IAM a nivel del proyecto. La condición usa la función api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) para inspeccionar el mapa de alcance de un recurso de memoria. Defines el alcance cuando creas o generas un recuerdo.

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 especializados de Memory Bank.
Agrega una condición al rol con aiplatform.googleapis.com/memoryScope 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 especializados de Memory Bank.
- CONDITION: Agrega una condición al rol con aiplatform.googleapis.com/memoryScope 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 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"
  }
}

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.memoryEditor.
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/memoryScope 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 alcance

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

Usa roles especializados de Memory Bank: Las condiciones de IAM de Memory Bank solo se deben usar para los roles que se aplican a los recuerdos y las revisiones de recuerdos. Puedes usar roles especializados, como aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor y aiplatform.googleapis.com/memoryUser, para evitar el acceso demasiado permisivo. Consulta los roles de IAM de Specialized Memory Bank para obtener más detalles.
Usa condiciones positivas: Te recomendamos que uses condiciones positivas (como verificaciones de igualdad o la presencia de pares clave-valor) en aiplatform.googleapis.com/memoryScope para obtener una mayor precisión. Dado que los tipos y servicios no admitidos se representan con un alcance 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 la concesión inesperada 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 evita que se produzcan estas limitaciones de IAM. Consulta Limitaciones para obtener más detalles. Por ejemplo, puedes omitir la verificació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' y usar la instrucción más corta api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' en su lugar. Si falta la clave user_id, la expresión más larga se evalúa como false, mientras que la expresión más corta genera un error. Dado que los errores en las expresiones de condición de IAM provocan que se deniegue el acceso, ambas expresiones producen el mismo resultado.

Roles de IAM especializados de Memory Bank

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

Nombre del rol	Descripción	Permisos incluidos
`roles/aiplatform.memoryViewer`	Otorga acceso 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`	Otorga acceso de escritura y generación a los recuerdos, y acceso de reversión a las revisiones de la memoria.	`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`	Otorga acceso completo a los recuerdos y las revisiones, incluidos todos los permisos de visualizador y editor.	Incluye todos los permisos de `memoryEditor` y `memoryViewer`.

Usa condiciones de IAM con Memory Bank

En esta sección, se abarcan los siguientes ejemplos del uso de las Condiciones de IAM con Memory Bank:

Otorga acceso de lectura a los recuerdos con concordancia de alcance exacto.
Otorga acceso de escritura a recuerdos con un alcance que contiene un par clave-valor específico.
Otorga acceso completo a los recuerdos con un alcance que contiene claves específicas.
Otorga acceso completo a los recuerdos con un alcance que contiene un prefijo específico.
Otorga acceso completo a los recuerdos con el alcance de la clave y un conjunto de valores permitidos.

Otorga acceso de lectura a los recuerdos con concordancia exacta del alcance

La siguiente condición otorga al individuo userA@gmail.com acceso de visualización solo a los recuerdos que tienen el alcance exacto {"userId": "userA"}.

Esto significa que el miembro tiene la capacidad de obtener y recuperar recuerdos, además de enumerar y obtener las revisiones de esos recuerdos, siempre y cuando el alcance sea exactamente {"userId": "userA"}. El usuario no tiene acceso a recuerdos con alcance, 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'}"
  }
}

Otorga acceso de escritura a recuerdos con un alcance que contiene un par clave-valor específico

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

Esto significa que el usuario tiene la capacidad de crear, actualizar, borrar y generar recuerdos, y crear y revertir las revisiones de esos recuerdos, con alcances 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'"
  }
}

Otorga acceso completo a los recuerdos con un alcance que contiene claves específicas

La siguiente condición otorga al grupo group:engineering@corp.com acceso de usuario (lector y editor) a los recuerdos que tienen 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 permisos 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', {}))"
  }
}

Otorga acceso completo a los recuerdos con un alcance que contiene un prefijo específico

La siguiente condición otorga al usuario del grupo group:engineering@corp.com (visualizador y editor) acceso a los recuerdos que tienen la clave 'userId' con un valor que comienza con 'user'.Puedes usar 'startsWith' para la verificación de prefijos y 'endsWith' para la verificación de sufijos.

Esto significa que los miembros del grupo tienen acceso completo de lectura y escritura a los recuerdos con permisos 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')"
  }
}

Otorga acceso completo a los recuerdos con el alcance de la clave y un conjunto de valores permitidos

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