View a markdown version of this page

Fine-grained controllo degli accessi per Memory - Fondamento Amazon AgentCore
Come funziona il controllo granulare degli accessiImposta un controllo granulare degli accessi per la memoriaAzioni di memoria e attributi di richiestaCosa puoi imporreAdotta un controllo di accesso granulare su una memoria esistenteRelazione con altre opzioni di controllo degli accessi

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Fine-grained controllo degli accessi per Memory

Con il controllo granulare degli accessi (FGAC) per Amazon Bedrock AgentCore Memory, puoi associare l'accesso alla memoria all'identità di un chiamante. OAuth-authenticated

Quando i chiamanti raggiungono Memory con le credenziali AWS IAM, puoi già limitare l'accesso in base all'azione, alla risorsa di memoria e agli ambiti dell'attore, della sessione e dello spazio dei nomi della richiesta, utilizzando le policy IAM basate sull'identità e sulle risorse con le chiavi di condizione di Memory. Per questi controlli, consulta Organizzazione della memoria in Memory and policies for Amazon Bedrock. AgentCore Resource-based AgentCore

Questi controlli IAM corrispondono al principale IAM che chiama Memory. Non possono esprimere una regola basata su un'OAuth/JWTidentità, perché un OAuth-authenticated chiamante non è un principale IAM. Ciò è importante per le applicazioni in cui i chiamanti si autenticano con OAuth anziché con AWS le credenziali, ad esempio un'applicazione agente i cui utenti finali accedono tramite un provider OpenID Connect. In tale architettura, il chiamante HTTP è in genere l'agente o il backend, che trasmette il JWT dell'utente finale (o dell'agente) a ogni richiesta; FGAC valuta le politiche rispetto all'identità in quel token. Con FGAC, puoi scrivere policy che confrontino un attributo di richiesta con le affermazioni del token, in modo da poter applicare regole come:

  • Un chiamante può accedere solo agli eventi in cui la richiesta è actorId uguale alla sua dichiarazione JWT. sub

  • Un chiamante può recuperare i record di memoria solo nello spazio dei nomi contenuto nella propria dichiarazione di token.

  • L'accesso è concesso solo ai chiamanti che presentano un OAuth specifico. client_id

Le policy FGAC possono anche condizionare gli stessi ambiti di azione e di attributo di richiesta offerti da IAM, quindi una singola policy può combinare chi è il chiamante a quali operazioni e dati può accedere. Memory-resource

FGAC for Memory è implementato con Policy in Amazon Bedrock. AgentCore Collega un motore di policy al gateway che gestisce la tua risorsa Memory e scrivi le policy in Cedar, un linguaggio di policy open source documentato sul sito web di Cedar Policy. https://www.cedarpolicy.com/ Il gateway valuta queste politiche prima di inoltrare una richiesta a Memory. Il linguaggio delle policy, i tipi principali, i motori delle policy e la convalida delle policy di Cedar sono tutti documentati in Policy in Amazon Bedrock AgentCore. Questa pagina descrive solo ciò che è specifico di Memory: le azioni e gli attributi di richiesta esposti dal connettore di memoria e i modelli di policy che isolano i dati della memoria in base al chiamante.

Nota

FGAC for Memory è basato sul connettore Memory. AgentCore Configura prima un gateway con una destinazione per il connettore di memoria. Per ulteriori informazioni, vedere Accedere alla AgentCore memoria tramite un gateway.

Argomenti

Come funziona il controllo granulare degli accessi

Un motore di policy contiene una serie di policy Cedar e le valuta per ogni richiesta che passa attraverso un gateway associato. Dopo che il gateway ha autenticato il chiamante e risolto la richiesta in un'operazione di memoria, il policy engine valuta le policy in base al principale (chi sta chiamando), all'azione (quale operazione di memoria), alla risorsa (quale gateway) e al contesto (gli attributi della richiesta, come i parametri del percorso e i campi del corpo). La valutazione è negata per impostazione predefinita e viene sostituita. forbid permit

Poiché il connettore di memoria rende ogni operazione di memoria disponibile come azione Cedar con i relativi campi di richiesta, le politiche possono consentire o negare specifiche operazioni e condizioni di memoria sui relativi attributi di richiesta. Il modello generico di Cedar (struttura delle policy,permit/forbid, tipi AgentCore::OAuthUser e AgentCore::IamEntity principali, tag e context.input —) è descritto in Understanding Cedar policies and Core concepts. Concetti principali

Imposta un controllo granulare degli accessi per la memoria

Nota

È possibile configurare un controllo granulare degli accessi per la memoria tramite la console di AWS gestione, l' AWS SDK e l'interfaccia a riga di comando (CLI AWS ).AWS

Dopo aver creato un gateway con una destinazione per il connettore di memoria (vedere Accedere alla AgentCore memoria tramite un gateway):

  1. Crea un motore di policy e aggiungi le tue policy Cedar. Per i passaggi, consulta Creare un motore di policy e Creare una policy. Per le politiche da scrivere, consulta Esempi di policy per la memoria.

  2. Associa il policy engine al gateway che si affaccia sulla tua risorsa di memoria, impostando quello del policyEngineConfiguration gateway. Puoi impostarlo quando crei il gateway con CreateGateway o aggiungerlo in un secondo momento con UpdateGateway.

Il policy engine mode controlla se le policy vengono applicate (ENFORCE) o solo valutate e registrate senza bloccare il traffico (LOG_ONLY). Verifica le tue politiche LOG_ONLY prima di passare a per ENFORCE evitare dinieghi involontari. Per le modalità di applicazione, la convalida delle politiche e il test, consulta Convalida e verifica le politiche e le politiche di utilizzo. Politiche di utilizzo

Azioni di memoria e attributi di richiesta

Questa sezione è il Memory-specific riferimento per la scrittura delle politiche: l'id dell'azione Cedar per ogni operazione di memoria e gli attributi di richiesta disponibili incontext.input.

L'azione di memoria è

Ogni operazione di memoria è denominata un'azione Cedar<target-name>___<METHOD>:<uri-template>, dove <target-name> è il nome della destinazione del connettore. L'URI mantiene i segnaposto relativi ai parametri di percorso, che non vengono sostituiti da valori concreti. Nella tabella seguente, sostituiscili <target-name> con il nome della destinazione del connettore.

Funzionamento in 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 I caratteri jolly non sono supportati; per concedere più operazioni in un'unica policy, elencale con. action in […​]

Nota

Le operazioni batch di memoria (BatchCreateMemoryRecordsBatchUpdateMemoryRecords, eBatchDeleteMemoryRecords) non sono disponibili come azioni Cedar e non possono essere governate da un controllo di accesso granulare. Ciascuna contiene più record in un'unica richiesta, che il policy engine non può valutare singolarmente, pertanto non è possibile applicare ad essi condizioni per record o per namespace.

Puoi comunque consentire o negare un'operazione batch nel suo insieme con le policy IAM basate sull'identità e sulle risorse (ad esempio, autorizzando o negando l'azione). bedrock-agentcore:BatchCreateMemoryRecords Ciò che manca è solo la granularità per record: a livello granulare di controllo degli accessi, un'operazione batch è tutto o niente.

Campi di contesto della richiesta

Il gateway espone gli attributi di ciascuna richiesta incontext.input, combinando i parametri del percorso e i campi del corpo della richiesta. Proteggi ogni campo has prima di leggerlo (ad esempio,). context has input && context.input has actorId

Parametri del percorso (dall'URI):

  • context.input.memoryId

  • context.input.actorId

  • context.input.sessionId

  • context.input.eventId

  • context.input.memoryRecordId

Request-body campi (dipendenti dall'operazione, dal payload della richiesta):

  • context.input.namespace

  • context.input.namespacePath

  • context.input.metadata

  • context.input.filter

  • context.input.payload

  • e altri campi del corpo definiti dallo schema di ciascuna operazione

I campi disponibili differiscono in base all'operazione. Un campo supportato da un'operazione (ad esempio, attivo actorIdListEvents) potrebbe non essere presente in un'altra operazione a cui corrisponde la stessa politica.

avvertimento

Una policy che fa riferimento a un campo di contesto viene convalidata rispetto allo schema per le azioni incluse nel suo ambito, ma non in base a tutte le operazioni che la richiesta potrebbe raggiungere in fase di esecuzione. Se una policy fa riferimento a un campo che la richiesta in arrivo non contiene, la policy può essere creata con successo e raggiungere l'obiettivoACTIVE, ma negare la richiesta con una 403 risposta quando il policy engine la valuta, perché manca il campo di riferimento. Questa condizione non viene segnalata quando si crea la policy.

Per evitare smentite impreviste:

  • Ambita ogni policy alle azioni specifiche le cui richieste contengono i campi a cui fa riferimento la policy e conferma tali campi rispetto a ciascuna operazione nella tabella Memory action ids.

  • Proteggi ogni accesso ai campi con has (ad esempiocontext has input && context.input has actorId) in modo che una permit condizione venga valutata in modo prevedibile quando un campo è assente.

  • Prova le policy in LOG_ONLY modalità prima di applicarle, in modo da poter osservare i risultati della valutazione senza negare il traffico in tempo reale. Per ulteriori informazioni, consulta Configurare il controllo granulare degli accessi per la memoria.

Cosa puoi imporre

L'applicazione del FGAC tramite il connettore di memoria è disponibile in tutte le modalità di autenticazione in ingresso del gateway. Utilizzando le azioni e gli attributi sopra riportati, puoi imporre:

  • Principal-type gating: i criteri assegnati ai chiamanti corrispondono o negano la corrispondenza OAuth-only o la IAM-only negano in base alla classe del chiamante.

  • Per-identity isolamento: un attributo di richiesta che actorId può essere richiesto per eguagliare la sub richiesta dell'utente o dell'agente autenticato nel JWT, autorizzando il proprietario e negando l'autorizzazione ad altri.

  • Isolamento dello spazio dei nomi: confrontando la richiesta con un valore letterale namespace o namespacePath con un percorso dello spazio dei nomi contenuto in una dichiarazione di token, limita i record che un chiamante può recuperare.

  • Ambito delle azioni: può essere consentita una singola azione, un insieme di azioni o qualsiasi azione; le azioni non consentite vengono negate.

  • Path-parameter condizioni: parametri del percorso come memoryIdactorId, e. sessionId

  • Request-body condizioni: campi corporei come metadata enamespacePath.

  • Blocco delle risorse: è consentito un ARN del gateway corrispondente; viene negato un ARN diverso.

  • Condizioni di reclamo JWT: rivendicazioni relative ai token, ad esempio, accesso al client_id gate (OAuth in entrata). sub

  • Condizioni di identità IAM: l'ARN IAM del chiamante può essere abbinato per modello (IAM in entrata).

Per le policy che le implementano, consulta Esempi di policy per la memoria.

Adotta un controllo di accesso granulare su una memoria esistente

Il modello di isolamento primario richiede che actorId on a request sia uguale al claim sub JWT () del chiamante. context.input.actorId == principal.getTag("sub") Le implementazioni esistenti utilizzano spesso un ID utente interno actorId che non corrisponde al sub valore del relativo provider di identità. Se actorId i tuoi valori sono già uguali a quelli del tuo providersub, non sono necessarie modifiche. Altrimenti, scegli uno dei seguenti approcci:

Abbina un claim JWT personalizzato

Se il tuo provider di identità può emettere un claim che contiene già il tuo ID utente interno (ad esempio, un claim personalizzato che rispecchia il tuo actorId schema), confrontalo con quel claim invece disub, ad esempio,context.input.actorId == principal.getTag("custom:app_user_id"). Proteggilo con hasTag First. In questo modo si evita di modificare i dati memorizzati.

Isola per namespace anziché actorId

Se i record di memoria a lungo termine sono organizzati in namespace per utente, imponete l'isolamento sullo spazio dei nomi anziché su. actorId Chiedi al tuo provider di identità di emettere un claim che contenga il percorso completo dello spazio dei nomi del chiamante e confronta la richiesta con tale attestazione. namespacePath Per il modello di isolamento dello spazio dei nomi, vedi Esempi di policy per la memoria.

Allinea con actorId sub

Se desideri utilizzare il actorId == sub modello predefinito, migra nuovi eventi e record per utilizzare quello del provider sub come. actorId Poiché AgentCore Memory memorizza gli eventi e i record in base ai dati forniti, ciò si applica in genere in futuro anziché riscrivere i dati storici; pianifica un periodo di transizione in cui entrambi gli schemi potrebbero essere presenti. actorId

Suggerimento

È possibile convalidare uno qualsiasi di questi approcci senza influire sul traffico in tempo reale collegando prima la policy in LOG_ONLY modalità e controllando i log di valutazione. Vedi Configurare un controllo granulare degli accessi per la memoria.

Relazione con altre opzioni di controllo degli accessi

Le policy Cedar valutate dal policy engine sono il livello di autorizzazione basato sull'identità e su richiesta per il traffico di memoria attraverso un gateway. Completano e possono essere combinati con le altre opzioni di controllo degli accessi del gateway: