View a markdown version of this page

Fine-grained control de acceso para memoria - Base amazónica AgentCore
Cómo funciona el control de acceso detalladoConfigure un control de acceso detallado para la memoriaMemoriza las acciones y los atributos de solicitudQué puede hacer cumplirAdopte un control de acceso detallado en una memoria existenteRelación con otras opciones de control de acceso

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Fine-grained control de acceso para memoria

Con el control de acceso detallado (FGAC) para Amazon Bedrock AgentCore Memory, puede vincular el acceso a la memoria a la identidad de la persona que llama. OAuth-authenticated

Cuando las personas que llaman llegan a Memory con credenciales de AWS IAM, ya puede restringir el acceso por acción, por recurso de memoria y por los ámbitos de actor, sesión y espacio de nombres de la solicitud, mediante políticas de IAM basadas en la identidad y en los recursos con las claves de condición de Memory. Para ver estos controles, consulte la organización de la memoria en Memory y las políticas de Amazon Bedrock. AgentCore Resource-based AgentCore

Estos controles de IAM coinciden con el principal de IAM que llama a Memory. No pueden expresar una regla basada en una OAuth/JWT identidad, porque la persona que OAuth-authenticated llama no es un principal de IAM. Esto es importante para las aplicaciones en las que las personas que llaman se autentican con OAuth en lugar de con AWS credenciales, por ejemplo, una aplicación de agente cuyos usuarios finales inician sesión a través de un proveedor de OpenID Connect. En esa arquitectura, la persona que llama mediante HTTP suele ser el agente o el backend, que pasa el JWT del usuario final (o del propio agente) con cada solicitud; el FGAC evalúa las políticas en función de la identidad de ese token. Con el FGAC, puedes elaborar políticas que comparen el atributo de una solicitud con las afirmaciones del token, de modo que puedas aplicar reglas como las siguientes:

  • La persona que llama solo puede acceder a los eventos en los que la solicitud actorId sea igual a la que afirma en JWT. sub

  • La persona que llama solo puede recuperar los registros de memoria del espacio de nombres incluido en su propia solicitud de token.

  • El acceso solo se concede a las personas que llaman y presentan un OAuth específico. client_id

Las políticas del FGAC también pueden condicionar los mismos alcances de acción y atributos de solicitud que ofrece IAM Memory-resource, de modo que una sola política puede combinar quién es la persona que llama con las operaciones y los datos a los que puede acceder.

El FGAC for Memory se implementa con la política de Amazon Bedrock. AgentCore Conecta un motor de políticas a la puerta de enlace que administra sus recursos de memoria y redacta las políticas en Cedar, un lenguaje de políticas de código abierto documentado en el sitio web de Cedar Policy. La pasarela evalúa estas políticas antes de enviar una solicitud a Memory. El lenguaje de políticas de Cedar, los tipos principales, los motores de políticas y la validación de las políticas están todos documentados en Policy in Amazon Bedrock AgentCore. En esta página solo se describe lo que es específico de Memory: las acciones y los atributos de solicitud que expone el conector de memoria y los patrones de políticas que aíslan los datos de la memoria por persona que llama.

nota

El FGAC for Memory se basa en el conector de memoria. AgentCore Configure primero una puerta de enlace con un conector de memoria como objetivo. Para obtener más información, consulte Acceder a AgentCore la memoria a través de una puerta de enlace.

Temas

Cómo funciona el control de acceso detallado

Un motor de políticas contiene un conjunto de políticas de Cedar y las evalúa para cada solicitud que pasa por una puerta de enlace asociada. Una vez que la puerta de enlace autentica a la persona que llama y convierte la solicitud en una operación de memoria, el motor de políticas evalúa las políticas comparándolas con el principal (quién llama), la acción (qué operación de memoria), el recurso (qué puerta de enlace) y el contexto (los atributos de la solicitud, como los parámetros de ruta y los campos del cuerpo). La evaluación se deniega de forma predeterminada y se anula. forbid permit

Como el conector de memoria hace que cada operación de memoria esté disponible como una acción de Cedar con sus campos de solicitud, sus políticas pueden permitir o denegar operaciones de memoria específicas y condicionar sus atributos de solicitud. El modelo genérico de Cedar (estructura de políticasforbid,permit/, los AgentCore::OAuthUser tipos AgentCore::IamEntity principales, etiquetas ycontext.input) se describe en Comprender las políticas y los conceptos básicos de Cedar.

Configure un control de acceso detallado para la memoria

nota

Puede configurar un control de acceso detallado a la memoria a través de la consola de AWS administración, el AWS SDK y la interfaz de línea de AWS comandos (CLI).AWS

Cuando tenga una puerta de enlace con un objetivo de conector de memoria (consulte Acceso a la AgentCore memoria a través de una puerta de enlace):

  1. Cree un motor de políticas y añada sus políticas de Cedar. Para ver los pasos, consulte Crear un motor de políticas y Crear una política. Para conocer las políticas que debes escribir, consulta Ejemplos de políticas para la memoria.

  2. Asocie el motor de políticas a la puerta de enlace que contiene su recurso de memoria configurando la puerta de enlacepolicyEngineConfiguration. Puede configurarlo al crear la puerta de enlace con CreateGateway o agregarla más adelante con UpdateGateway.

El motor de políticas mode controla si las políticas se aplican (ENFORCE) o si solo se evalúan y registran sin bloquear el tráfico (LOG_ONLY). Pon a prueba tus políticas LOG_ONLY antes de cambiarte ENFORCE para evitar denegaciones involuntarias. Para ver los modos de aplicación, la validación de políticas y las pruebas, consulta Validar y probar las políticas y las políticas de uso.

Memoriza las acciones y los atributos de solicitud

Esta sección es la Memory-specific referencia para escribir políticas: el identificador de acción de Cedar para cada operación de memoria y los atributos de solicitud disponibles encontext.input.

Identificadores de acción de memoria

Cada operación de memoria es una acción de Cedar denominada<target-name>___<METHOD>:<uri-template>, donde <target-name> es el nombre del objetivo del conector. La URI conserva los marcadores de posición de los parámetros de ruta; no se sustituyen por valores concretos. En la tabla siguiente, sustitúyalos por el <target-name> nombre del objetivo del conector.

Operación de memoria Cedar action id

ListEvents

<target-name>___POST:/memories/{memoryId}/actor/{actorId}/sessions/{sessionId}

CreateEvent

<target-name>___POST:/memories/{memoryId}/events

GetEvent

<target-name>___GET:/memories/{memoryId}/actor/{actorId}/sessions/{sessionId}/events/{eventId}

DeleteEvent

<target-name>___DELETE:/memories/{memoryId}/actor/{actorId}/sessions/{sessionId}/events/{eventId}

ListSessions

<target-name>___POST:/memories/{memoryId}/actor/{actorId}/sessions

ListActors

<target-name>___POST:/memories/{memoryId}/actors

RetrieveMemoryRecords

<target-name>___POST:/memories/{memoryId}/retrieve

ListMemoryRecords

<target-name>___POST:/memories/{memoryId}/memoryRecords

GetMemoryRecord

<target-name>___GET:/memories/{memoryId}/memoryRecord/{memoryRecordId}

DeleteMemoryRecord

<target-name>___DELETE:/memories/{memoryId}/memoryRecords/{memoryRecordId}

ListMemoryExtractionJobs

<target-name>___POST:/memories/{memoryId}/extractionJobs

StartMemoryExtractionJob

<target-name>___POST:/memories/{memoryId}/extractionJobs/start

Action-id No se admiten caracteres comodín; para conceder varias operaciones en una política, indíquelas conaction in […​].

nota

Las operaciones por lotes de memoria (BatchCreateMemoryRecords,BatchUpdateMemoryRecords, yBatchDeleteMemoryRecords) no están disponibles como acciones de Cedar y no se pueden controlar mediante un control de acceso detallado. Cada una contiene varios registros en una sola solicitud, que el motor de políticas no puede evaluar de forma individual, por lo que no se les pueden aplicar condiciones por registro o por espacio de nombres.

Puedes seguir permitiendo o denegando una operación por lotes en su conjunto con políticas de IAM basadas en la identidad y en los recursos (por ejemplo, permitiendo o denegando la acción). bedrock-agentcore:BatchCreateMemoryRecords Lo único que falta es la granularidad por registro: en el nivel de control de acceso más detallado, una operación por lotes es de todo o nada.

Campos de contexto de solicitud

La pasarela expone los atributos de cada solicitud en esta seccióncontext.input, combinando los parámetros de ruta y los campos del cuerpo de la solicitud. Proteja cada campo has antes de leerlo (por ejemplo,). context has input && context.input has actorId

Parámetros de ruta (del URI):

  • context.input.memoryId

  • context.input.actorId

  • context.input.sessionId

  • context.input.eventId

  • context.input.memoryRecordId

Request-body campos (dependen de la operación, de la carga útil de la solicitud):

  • context.input.namespace

  • context.input.namespacePath

  • context.input.metadata

  • context.input.filter

  • context.input.payload

  • y otros campos del cuerpo definidos por el esquema de cada operación

Los campos disponibles varían según la operación. Es posible que un campo incluido en una operación (por ejemplo, actorId enListEvents) no esté presente en otra operación que coincida con la misma política.

aviso

Una política que hace referencia a un campo de contexto se valida según el esquema para las acciones incluidas en su ámbito, pero no para todas las operaciones a las que pueda acceder la solicitud en tiempo de ejecución. Si una política hace referencia a un campo que la solicitud entrante no contiene, la política se puede crear correctamente y alcanzar la solicitudACTIVE, pero rechazarla con una 403 respuesta cuando el motor de políticas la evalúe, porque falta el campo al que se hace referencia. Esta condición no se informa al crear la política.

Para evitar denegaciones inesperadas:

  • Limite cada política a las acciones específicas cuyas solicitudes contengan los campos a los que hace referencia la política y confirme esos campos para cada operación en la tabla de identificadores de acciones de memoria.

  • Proteja todos los campos de acceso con has (por ejemplo,context has input && context.input has actorId) para que una permit condición se evalúe de manera predecible cuando un campo esté ausente.

  • Pruebe las políticas en LOG_ONLY modo antes de aplicarlas, de modo que pueda observar los resultados de las evaluaciones sin denegar el tráfico en tiempo real. Para obtener más información, consulte Configurar un control de acceso detallado para la memoria.

Qué puede hacer cumplir

La aplicación del FGAC a través del conector de memoria está disponible en todos los modos de autenticación entrante de la puerta de enlace. Con las acciones y los atributos anteriores, puede hacer cumplir lo siguiente:

  • Principal-type bloqueo: las políticas que se aplican a las personas que IAM-only llaman coinciden OAuth-only o rechazan según la clase de persona que llama.

  • Per-identity aislamiento: un atributo de solicitud, como el que actorId puede exigirse para igualar la sub reclamación del usuario o agente autenticado en el JWT, permitiendo al propietario y denegando a otros.

  • El aislamiento del espacio de nombres: al comparar la solicitud con una ruta literal namespace o namespacePath con la ruta de un espacio de nombres incluida en una reclamación simbólica, se restringe el número de registros que puede recuperar la persona que llama.

  • Alcance de la acción: se puede permitir una sola acción, un conjunto de acciones o cualquier acción; las acciones no permitidas se deniegan.

  • Path-parameter condiciones: parámetros de ruta como memoryIdactorId, y. sessionId

  • Request-body condiciones: campos corporales como metadata ynamespacePath.

  • Fijación de recursos: se permite un ARN de puerta de enlace coincidente; se deniega un ARN diferente.

  • Condiciones de reclamación de JWT: solicitudes de tokens, como el acceso de client_id puerta (subOAuth entrante).

  • Condiciones de identidad de IAM: el ARN de IAM de la persona que llama puede coincidir según un patrón (IAM entrante).

Para ver las políticas que las implementan, consulta los ejemplos de políticas para Memory. Ejemplos de políticas para la memoria

Adopte un control de acceso detallado en una memoria existente

El patrón de aislamiento principal requiere que el actorId valor de una solicitud sea igual al JWT sub claim () de la persona que llama. context.input.actorId == principal.getTag("sub") Las implementaciones existentes suelen utilizar un identificador de usuario interno actorId que no coincide con el sub valor de su proveedor de identidad. Si sus actorId valores ya son iguales a los de su proveedorsub, no es necesario hacer ningún cambio. De lo contrario, elija uno de los siguientes enfoques:

Coincide con una reclamación personalizada de JWT

Si tu proveedor de identidad puede emitir una reclamación que ya contenga tu seudónimo interno (por ejemplo, una reclamación personalizada que refleje tu actorId estrategia), compárala con esa afirmación en lugar desub, por ejemplo, context.input.actorId == principal.getTag("custom:app_user_id") con esa afirmación. Protégelo hasTag primero. Esto evita cambiar los datos almacenados.

Aísle por espacio de nombres en lugar de actorId

Si sus registros de memoria a largo plazo están organizados en espacios de nombres por usuario, aplique el aislamiento en el espacio de nombres en lugar de hacerlo en uno. actorId Pide a tu proveedor de identidad que emita una reclamación que contenga la ruta completa del espacio de nombres de la persona que llama y compara la solicitud con esa afirmación. namespacePath Para ver el patrón de aislamiento del espacio de nombres, consulta los ejemplos de políticas para la memoria.

Alinee con actorId sub

Si desea utilizar el actorId == sub patrón predeterminado, migre los nuevos eventos y registros para usar el del proveedor sub comoactorId. Dado que la AgentCore memoria almacena los eventos y los registros según lo actorId que usted proporciona, esto suele aplicarse de ahora en adelante en lugar de reescribir los datos históricos; planifique un período de transición en el que ambos esquemas puedan estar presentes.

sugerencia

Para validar cualquiera de estos enfoques sin afectar al tráfico en tiempo real, primero debe adjuntar la política en LOG_ONLY modo y revisar los registros de evaluación. Consulte Configurar un control de acceso detallado para la memoria.

Relación con otras opciones de control de acceso

Las políticas de Cedar evaluadas por el motor de políticas son la capa de autorización por solicitud que reconoce la identidad para el tráfico de memoria a través de una puerta de enlace. Complementan las demás opciones de control de acceso de la pasarela y se pueden combinar con ellas: