View a markdown version of this page

Fine-grained controle de acesso para memória - Base da Amazônia AgentCore
Como funciona o controle de acesso refinadoConfigure um controle de acesso refinado para memóriaAções de memória e atributos de solicitaçãoO que você pode aplicarAdote um controle de acesso refinado em uma memória existenteRelação com outras opções de controle de acesso

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Fine-grained controle de acesso para memória

Com o controle de acesso refinado (FGAC) para Amazon Bedrock AgentCore Memory, você pode vincular o acesso à memória à identidade de um chamador. OAuth-authenticated

Quando os chamadores acessam a Memória com credenciais AWS do IAM, você já pode restringir o acesso por ação, por recurso de memória e pelos escopos do ator, da sessão e do namespace da solicitação, usando políticas baseadas em identidade e recursos do IAM com as chaves de condição da Memória. Para esses controles, consulte Organização da memória na AgentCore memória e Resource-based políticas para o Amazon Bedrock AgentCore.

Esses controles do IAM coincidem com o principal do IAM que chama a memória. Eles não podem expressar uma regra digitada em uma OAuth/JWT identidade, porque o OAuth-authenticated chamador não é um diretor do IAM. Isso é importante para aplicativos em que os chamadores se autenticam com OAuth em vez de AWS credenciais — por exemplo, um aplicativo de agente cujos usuários finais fazem login por meio de um provedor OpenID Connect. Nessa arquitetura, o chamador HTTP normalmente é o agente ou back-end, que passa o JWT do usuário final (ou do próprio agente) com cada solicitação; o FGAC avalia as políticas em relação à identidade nesse token. Com o FGAC, você pode criar políticas que comparam um atributo de solicitação às declarações do token, para que você possa aplicar regras como:

  • Um chamador só pode acessar eventos em que a solicitação é actorId igual à reivindicação do JWT. sub

  • Um chamador só pode recuperar registros de memória sob o namespace contido em sua própria reivindicação de token.

  • O acesso é concedido somente aos chamadores que apresentam um client_id OAuth específico.

As políticas do FGAC também podem condicionar os mesmos escopos de ação e atributo de solicitação que o IAM oferece, portanto, uma única política pode combinar quem é o chamador com quais operações e dados eles podem acessar. Memory-resource

O FGAC for Memory é implementado com a política no Amazon Bedrock. AgentCore Você conecta um mecanismo de políticas ao gateway que está na frente do seu recurso de memória e escreve políticas em Cedar, uma linguagem de política de código aberto documentada no site da Cedar Policy. O gateway avalia essas políticas antes de encaminhar uma solicitação para a Memória. A linguagem da política Cedar, os principais tipos, os mecanismos de política e a validação de políticas estão todos documentados em Política no Amazon Bedrock AgentCore — esta página descreve somente o que é específico da Memória: as ações e os atributos de solicitação que o conector de memória expõe e os padrões de política que isolam os dados da memória por chamador.

nota

O FGAC for Memory é construído no conector de AgentCore memória. Configure primeiro um gateway com um conector de memória alvo. Para obter mais informações, consulte Acessar AgentCore memória por meio de um gateway.

Tópicos

Como funciona o controle de acesso refinado

Um mecanismo de políticas mantém um conjunto de políticas do Cedar e as avalia para cada solicitação que flui por meio de um gateway associado. Depois que o gateway autentica o chamador e resolve a solicitação para uma operação de memória, o mecanismo de políticas avalia as políticas em relação ao principal (quem está chamando), à ação (qual operação de memória), ao recurso (qual gateway) e ao contexto (os atributos da solicitação, como parâmetros de caminho e campos de corpo). A avaliação é negada por padrão e substituída. forbid permit

Como o conector de memória disponibiliza cada operação de memória como uma ação Cedar com seus campos de solicitação, suas políticas podem permitir ou negar operações específicas de memória e condicionar seus atributos de solicitação. O modelo genérico do Cedar — estrutura política,permit/forbid, os AgentCore::IamEntity principais tipos, tags AgentCore::OAuthUser e context.input — é descrito em Compreendendo as políticas e os principais conceitos do cedro.

Configure um controle de acesso refinado para memória

nota

Você pode configurar um controle de acesso refinado para a memória por meio do console de AWS gerenciamento, do AWS SDK e da interface de linha de AWS comando (CLI).AWS

Depois de ter um gateway com um destino de conector de memória (consulte Acessar AgentCore memória por meio de um gateway):

  1. Crie um mecanismo de políticas e adicione suas políticas do Cedar. Para ver as etapas, consulte Criar um mecanismo de política e Criar uma política. Para as políticas a serem escritas, consulte Exemplos de políticas para memória.

  2. Associe o mecanismo de políticas ao gateway que está na frente do seu recurso de memória, definindo o gateway. policyEngineConfiguration Você pode configurá-lo ao criar o gateway com CreateGateway ou adicioná-lo posteriormente com UpdateGateway.

O mecanismo de políticas mode controla se as políticas são aplicadas (ENFORCE) ou somente avaliadas e registradas sem bloquear o tráfego ()LOG_ONLY. Teste suas políticas LOG_ONLY antes de mudar para elas ENFORCE para evitar negações não intencionais. Para modos de imposição, validação de políticas e testes, consulte Validar e testar políticas e Usar políticas.

Ações de memória e atributos de solicitação

Esta seção é a Memory-specific referência para escrever políticas: o ID da ação Cedar para cada operação de memória e os atributos de solicitação disponíveis emcontext.input.

IDs de ação de memória

Cada operação de memória é uma ação de Cedar chamada<target-name>___<METHOD>:<uri-template>, onde <target-name> está o nome do seu conector alvo. O URI mantém seus espaços reservados para parâmetros de caminho — eles não são substituídos por valores concretos. Na tabela a seguir, <target-name> substitua pelo nome do seu conector alvo.

Operação de memória ID de ação do cedro

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 Não há suporte para curingas; para conceder várias operações em uma política, liste-as comaction in […​].

nota

As operações de lote de memória (BatchCreateMemoryRecords,BatchUpdateMemoryRecords, eBatchDeleteMemoryRecords) não estão disponíveis como ações do Cedar e não podem ser controladas por um controle de acesso refinado. Cada um carrega vários registros em uma única solicitação, que o mecanismo de políticas não pode avaliar individualmente — portanto, as condições por registro ou por namespace não podem ser aplicadas a eles.

Você ainda pode permitir ou negar uma operação em lote como um todo com políticas do IAM baseadas em identidade e recursos (por exemplo, permitindo ou negando a ação). bedrock-agentcore:BatchCreateMemoryRecords O que falta é apenas a granularidade por registro: na camada de controle de acesso refinada, uma operação em lote é tudo ou nada.

Campos de contexto da solicitação

O gateway expõe os atributos de cada solicitação abaixocontext.input, combinando parâmetros de caminho e campos do corpo da solicitação. Proteja cada campo has antes de lê-lo (por exemplo,context has input && context.input has actorId).

Parâmetros do caminho (do URI):

  • context.input.memoryId

  • context.input.actorId

  • context.input.sessionId

  • context.input.eventId

  • context.input.memoryRecordId

Request-body campos (dependentes da operação, da carga útil da solicitação):

  • context.input.namespace

  • context.input.namespacePath

  • context.input.metadata

  • context.input.filter

  • context.input.payload

  • e outros campos corporais definidos pelo esquema de cada operação

Os campos disponíveis variam de acordo com a operação. Um campo que uma operação carrega (por exemplo, actorId ativadoListEvents) pode não estar presente em outra operação que corresponda à mesma política.

Atenção

Uma política que faz referência a um campo de contexto é validada em relação ao esquema para as ações em seu escopo, mas não em relação a todas as operações que a solicitação possa alcançar em tempo de execução. Se uma política fizer referência a um campo que a solicitação recebida não carrega, a política poderá ser criada com êxito e alcançadaACTIVE, mas negar a solicitação com uma 403 resposta quando o mecanismo de política a avaliar, porque o campo referenciado está ausente. Essa condição não é relatada quando você cria a política.

Para evitar negações inesperadas:

  • Defina o escopo de cada política para as ações específicas cujas solicitações contêm os campos que a política faz referência e confirme esses campos em relação a cada operação na tabela IDs de ações de memória.

  • Proteja cada acesso ao campo com has (por exemplo,context has input && context.input has actorId) para que uma permit condição seja avaliada de forma previsível quando um campo está ausente.

  • Teste as políticas no LOG_ONLY modo antes de aplicá-las, para que você possa observar os resultados da avaliação sem negar o tráfego ao vivo. Para obter mais informações, consulte Configurar controle de acesso refinado para memória.

O que você pode aplicar

A aplicação do FGAC por meio do conector de memória está disponível em todos os modos de autenticação de entrada do gateway. Usando as ações e os atributos acima, você pode aplicar:

  • Principal-type bloqueio — políticas com escopo definido ou que IAM-only os chamadores combinam OAuth-only ou negam por classe de chamador.

  • Per-identity isolamento — um atributo de solicitação, como o que actorId pode ser exigido, para sub igualar a reivindicação do usuário ou agente autenticado no JWT, permitindo o proprietário e negando outros.

  • Isolamento de namespace — comparar a solicitação com um caminho literal ou com um namespace transportado em uma reivindicação de token restringe quais registros um chamador pode recuperar. namespace namespacePath

  • Escopo da ação — uma única ação, um conjunto de ações ou qualquer ação pode ser permitida; ações não permitidas são negadas.

  • Path-parameter condições — parâmetros do caminhomemoryId, comoactorId, sessionId e.

  • Request-body condições — campos corporais como metadata namespacePath e.

  • Fixação de recursos — um ARN de gateway correspondente é permitido; um ARN diferente é negado.

  • Condições de reivindicação do JWT — reivindicações de token, como sub acesso ao client_id portão (entrada OAuth).

  • Condições de identidade do IAM — o ARN do IAM do chamador pode ser correspondido por padrão (entrada do IAM).

Para políticas que as implementam, consulte Exemplos de políticas para memória.

Adote um controle de acesso refinado em uma memória existente

O padrão de isolamento primário exige que a actorId solicitação seja igual à sub declaração JWT () context.input.actorId == principal.getTag("sub") do chamador. As implantações existentes geralmente usam um ID de usuário interno, pois não corresponde ao sub valor do provedor de identidade. actorId Se seus actorId valores já forem iguais aos do seu provedorsub, nenhuma alteração será necessária. Caso contrário, escolha uma das seguintes abordagens:

Combine uma reivindicação personalizada da JWT

Se seu provedor de identidade puder emitir uma reivindicação que já contenha seu ID de usuário interno (por exemplo, uma declaração personalizada que reflete seu actorId esquema), compare com essa afirmação em vez de sub — por exemplo,context.input.actorId == principal.getTag("custom:app_user_id"). Proteja-o hasTag primeiro. Isso evita alterar os dados armazenados.

Isole por namespace em vez de actorId

Se seus registros de memória de longo prazo estiverem organizados em namespaces por usuário, imponha o isolamento no namespace em vez de no namespace. actorId Faça com que seu provedor de identidade emita uma declaração que contenha o caminho completo do namespace do chamador e compare a solicitação com essa afirmação. namespacePath Para o padrão de isolamento de namespace, consulte Exemplos de políticas para memória.

Alinhe com actorId sub

Se você quiser usar o padrão actorId == sub padrão, migre novos eventos e registros para usar os do provedor sub como o. actorId Como o AgentCore Memory armazena eventos e registros sob o actorId que você fornece, isso normalmente se aplica no futuro, em vez de reescrever dados históricos; planeje um período de transição no qual os dois esquemas possam estar presentes.

dica

Você pode validar qualquer uma dessas abordagens sem afetar o tráfego ao vivo anexando primeiro a política no LOG_ONLY modo e revisando os registros de avaliação. Consulte Configurar controle de acesso refinado para memória.

Relação com outras opções de controle de acesso

As políticas do Cedar avaliadas pelo mecanismo de políticas são a camada de autorização por solicitação com reconhecimento de identidade para o tráfego de memória por meio de um gateway. Eles complementam e podem ser combinados com as outras opções de controle de acesso do gateway: