View a markdown version of this page

Fine-grained contrôle d'accès pour Memory - Base rocheuse de l'Amazonie AgentCore
Comment fonctionne le contrôle d'accès précisConfigurez un contrôle d'accès précis pour la mémoireActions de mémoire et attributs de requêteCe que vous pouvez faire appliquerAdoptez un contrôle d'accès précis sur une mémoire existanteRelation avec les autres options de contrôle d'accès

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Fine-grained contrôle d'accès pour Memory

Grâce au contrôle d'accès précis (FGAC) pour Amazon Bedrock AgentCore Memory, vous pouvez associer l'accès à la mémoire à l'identité de l'appelant. OAuth-authenticated

Lorsque les appelants atteignent Memory avec des informations d'identification AWS IAM, vous pouvez déjà restreindre l'accès par action, par ressource mémoire et par étendue d'acteur, de session et d'espace de noms de la demande, en utilisant des politiques IAM basées sur l'identité et les ressources avec les clés de condition de Memory. Pour ces contrôles, consultez la section Organisation de la AgentCore mémoire dans Memory et Resource-based les politiques d'Amazon Bedrock AgentCore.

Ces contrôles IAM correspondent au principal IAM qui appelle Memory. Ils ne peuvent pas exprimer une règle basée sur une OAuth/JWT identité, car l' OAuth-authenticated appelant n'est pas un principal IAM. Cela est important pour les applications dans lesquelles les appelants s'authentifient avec OAuth plutôt qu'avec des AWS informations d'identification, par exemple, une application d'agent dont les utilisateurs finaux se connectent via un fournisseur OpenID Connect. Dans cette architecture, l'appelant HTTP est généralement l'agent ou le backend, qui transmet le JWT de l'utilisateur final (ou du propre agent) à chaque demande ; le FGAC évalue les politiques en fonction de l'identité de ce jeton. Avec le FGAC, vous pouvez rédiger des politiques qui comparent un attribut de requête aux revendications du jeton, afin de pouvoir appliquer des règles telles que :

  • Un appelant ne peut accéder qu'aux événements où la valeur de la demande est actorId égale à sa réclamation JWTsub.

  • Un appelant ne peut récupérer les enregistrements de mémoire que dans l'espace de noms indiqué dans sa propre demande de jeton.

  • L'accès n'est accordé qu'aux appelants présentant un client_id OAuth spécifique.

Les politiques FGAC peuvent également dépendre des mêmes champs d'action et d'attributs de demande que ceux proposés par IAM, de sorte qu'une politique unique peut combiner l'identité de l'appelant avec les opérations et les données auxquelles il peut accéder. Memory-resource

FGAC for Memory est implémenté avec Policy dans Amazon AgentCore Bedrock. Vous attachez un moteur de politiques à la passerelle qui fait face à votre ressource de mémoire et vous rédigez des politiques dans Cedar, un langage de politique open source documenté sur le site Web de Cedar Policy. La passerelle évalue ces politiques avant de transmettre une demande à Memory. Le langage de politique, les principaux types, les moteurs de politique et la validation des politiques de Cedar sont tous documentés dans Policy in Amazon Bedrock AgentCore. Cette page décrit uniquement ce qui est spécifique à la mémoire : les actions et les attributs de demande exposés par le connecteur de mémoire, ainsi que les modèles de politique qui isolent les données de mémoire par appelant.

Note

Le FGAC pour la mémoire est intégré au connecteur de AgentCore mémoire. Configurez d'abord une passerelle avec une cible de connecteur de mémoire. Pour plus d'informations, voir Accès à AgentCore la mémoire via une passerelle.

Rubriques

Comment fonctionne le contrôle d'accès précis

Un moteur de politiques contient un ensemble de politiques Cedar et les évalue pour chaque demande qui passe par une passerelle associée. Une fois que la passerelle a authentifié l'appelant et résolu la demande en une opération de mémoire, le moteur de politiques évalue les politiques par rapport au principal (qui appelle), à l'action (quelle opération mémoire), à la ressource (quelle passerelle) et au contexte (les attributs de la demande, tels que les paramètres de chemin et les champs de corps). L'évaluation est refusée par défaut et remplacée. forbid permit

Étant donné que le connecteur de mémoire rend chaque opération de mémoire disponible sous la forme d'une action Cedar avec ses champs de demande, vos politiques peuvent autoriser ou refuser des opérations de mémoire spécifiques et conditionner leurs attributs de demande. Le modèle générique de Cedar — structure des politiquesforbid,permit/, les AgentCore::OAuthUser AgentCore::IamEntity principaux types, balises et context.input — est décrit dans Understanding Cedar policies and Core concepts.

Configurez un contrôle d'accès précis pour la mémoire

Note

Vous pouvez configurer un contrôle d'accès précis pour la mémoire via la console de AWS gestion, le AWS SDK et l'interface de ligne de AWS commande (AWS CLI).

Une fois que vous disposez d'une passerelle avec une cible de connecteur de mémoire (voir Accès à AgentCore la mémoire via une passerelle) :

  1. Créez un moteur de politiques et ajoutez vos politiques Cedar. Pour les étapes à suivre, consultez les sections Création d'un moteur de politiques et Création d'une stratégie. Pour les politiques à écrire, voir Exemples de politiques pour la mémoire.

  2. Associez le moteur de politique à la passerelle qui gère votre ressource mémoire, en définissant celle de la passerellepolicyEngineConfiguration. Vous pouvez le définir lorsque vous créez la passerelle avec CreateGateway, ou l'ajouter ultérieurement avec UpdateGateway.

Le moteur de politiques mode contrôle si les politiques sont appliquées (ENFORCE) ou uniquement évaluées et enregistrées sans bloquer le trafic (LOG_ONLY). Testez vos politiques LOG_ONLY avant de passer à la version précédente ENFORCE pour éviter tout refus involontaire. Pour les modes d'application, la validation des politiques et les tests, voir Valider et tester les politiques et Utiliser les politiques.

Actions de mémoire et attributs de requête

Cette section est la Memory-specific référence pour la rédaction de politiques : l'identifiant d'action Cedar pour chaque opération de mémoire et les attributs de requête disponibles souscontext.input.

ID d'action de la mémoire

Chaque opération de mémoire est une action Cedar nommée<target-name>___<METHOD>:<uri-template>, où se <target-name> trouve le nom de la cible de votre connecteur. L'URI conserve ses espaces réservés aux paramètres de chemin ; ils ne sont pas remplacés par des valeurs concrètes. Dans le tableau suivant, remplacez <target-name> par le nom de la cible de votre connecteur.

Fonctionnement de la mémoire Clé d'action en cèdre

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 les caractères génériques ne sont pas pris en charge ; pour accorder plusieurs opérations dans une seule politique, listez-les avecaction in […​].

Note

Les opérations par lots de mémoire (BatchCreateMemoryRecordsBatchUpdateMemoryRecords, etBatchDeleteMemoryRecords) ne sont pas disponibles en tant qu'actions Cedar et ne peuvent pas être régies par un contrôle d'accès précis. Chacun contient plusieurs enregistrements dans une seule demande, que le moteur de politiques ne peut pas évaluer individuellement. Les conditions par enregistrement ou par espace de noms ne peuvent donc pas leur être appliquées.

Vous pouvez toujours autoriser ou refuser une opération par lots dans son ensemble grâce aux politiques IAM basées sur l'identité et les ressources (par exemple, en autorisant ou en refusant l'action). bedrock-agentcore:BatchCreateMemoryRecords Il ne manque que la granularité par enregistrement : au niveau de la couche de contrôle d'accès fine, une opération par lots est tout ou rien.

Champs contextuels de la demande

La passerelle expose les attributs de chaque demande ci-dessouscontext.input, en combinant les paramètres de chemin et les champs du corps de la demande. Surveillez chaque champ has avant de le lire (par exemple,context has input && context.input has actorId).

Paramètres du chemin (depuis l'URI) :

  • context.input.memoryId

  • context.input.actorId

  • context.input.sessionId

  • context.input.eventId

  • context.input.memoryRecordId

Request-body champs (en fonction de l'opération, à partir de la charge utile de la demande) :

  • context.input.namespace

  • context.input.namespacePath

  • context.input.metadata

  • context.input.filter

  • context.input.payload

  • et d'autres champs corporels définis par le schéma de chaque opération

Les champs disponibles varient en fonction de l'opération. Un champ associé à une opération (par exemple, actorId activéListEvents) peut ne pas être présent sur une autre opération correspondant à la même politique.

Avertissement

Une politique qui fait référence à un champ de contexte est validée par rapport au schéma des actions de son périmètre, mais pas par rapport à chaque opération que la demande peut atteindre au moment de l'exécution. Si une politique fait référence à un champ que la demande entrante ne contient pas, la politique peut être créée avec succès et atteindre la demandeACTIVE, tout en refusant une 403 réponse lorsque le moteur de politique l'évalue, car le champ référencé est manquant. Cette condition n'est pas signalée lors de la création de la politique.

Pour éviter tout refus inattendu :

  • Étendez chaque politique aux actions spécifiques dont les demandes contiennent les champs auxquels la politique fait référence, et confirmez ces champs pour chaque opération dans le tableau des identifiants d'actions de mémoire.

  • Protégez l'accès à chaque champ avec has (par exemplecontext has input && context.input has actorId) afin qu'une permit condition soit évaluée de manière prévisible lorsqu'un champ est absent.

  • Testez les politiques en LOG_ONLY mode avant de les appliquer, afin de pouvoir observer les résultats de l'évaluation sans empêcher le trafic réel. Pour plus d'informations, consultez la section Configuration d'un contrôle d'accès précis pour la mémoire.

Ce que vous pouvez faire appliquer

L'application du FGAC via le connecteur de mémoire est disponible dans tous les modes d'authentification entrants de la passerelle. À l'aide des actions et attributs ci-dessus, vous pouvez appliquer :

  • Principal-type blocage  : politiques définies ou identiques OAuth-only ou refusées par classe d' IAM-only appelants.

  • Per-identity isolation  : un attribut de demande tel que celui qui actorId peut être requis pour égaler la sub réclamation de l'utilisateur ou de l'agent authentifié dans le JWT, en autorisant le propriétaire et en refusant les autres.

  • Isolation de l'espace de noms  : la comparaison de namespace la requête avec un littéral, ou avec un chemin d'espace de noms contenu dans une réclamation de jeton, limite les enregistrements qu'un appelant peut récupérer. namespacePath

  • Étendue des actions  : une action unique, un ensemble d'actions ou n'importe quelle action peut être autorisée ; les actions non autorisées sont refusées.

  • Path-parameter conditions  : paramètres de chemin tels que memoryIdactorId, etsessionId.

  • Request-body conditions — champs corporels tels que metadata etnamespacePath.

  • Resource pinning  : un ARN de passerelle correspondant est autorisé ; un autre ARN est refusé.

  • Conditions de réclamation JWT  : réclamations relatives à des jetons, telles que l'subaccès à une client_id porte d'entrée (OAuth entrant).

  • Conditions d'identité IAM  : l'ARN IAM de l'appelant peut être mis en correspondance par un modèle (IAM entrant).

Pour les politiques qui les implémentent, voir Exemples de politiques pour la mémoire.

Adoptez un contrôle d'accès précis sur une mémoire existante

Le modèle d'isolation principal exige que la valeur « actorId on » d'une requête soit égale à la sub réclamation JWT de l'appelant ()context.input.actorId == principal.getTag("sub"). Les déploiements existants utilisent souvent un identifiant utilisateur interne actorId qui ne correspond pas à la sub valeur de leur fournisseur d'identité. Si vos actorId valeurs sont déjà égales à celles de votre fournisseursub, aucune modification n'est nécessaire. Sinon, choisissez l'une des approches suivantes :

Correspondance sur une réclamation JWT personnalisée

Si votre fournisseur d'identité peut émettre une réclamation contenant déjà votre identifiant d'utilisateur interne (par exemple, une réclamation personnalisée qui reflète votre actorId schéma), comparez avec cette réclamation plutôt que, par exemple,context.input.actorId == principal.getTag("custom:app_user_id"). sub Protégez-le d'hasTagabord. Cela permet d'éviter de modifier les données stockées.

Isolez par espace de noms au lieu de actorId

Si vos enregistrements de mémoire à long terme sont organisés en espaces de noms par utilisateur, appliquez l'isolation à l'espace de noms plutôt qu'à l'inverse. actorId Demandez à votre fournisseur d'identité d'émettre une réclamation contenant le chemin complet de l'espace de noms de l'appelant et de comparer la demande à cette namespacePath réclamation. Pour le modèle d'isolation des espaces de noms, voir Exemples de politiques pour la mémoire.

Aligner actorId avec sub

Si vous souhaitez utiliser le actorId == sub modèle par défaut, migrez les nouveaux événements et enregistrements pour utiliser celui du fournisseur sub commeactorId. Étant donné que AgentCore Memory stocke les événements et les enregistrements dans le cadre que actorId vous fournissez, cela s'applique généralement à l'avenir plutôt qu'à la réécriture des données historiques ; prévoyez une période de transition au cours de laquelle les deux schémas pourraient être présents.

Astuce

Vous pouvez valider n'importe laquelle de ces approches sans affecter le trafic réel en associant d'abord la politique en LOG_ONLY mode et en consultant les journaux d'évaluation. Consultez la section Configuration d'un contrôle d'accès précis pour la mémoire.

Relation avec les autres options de contrôle d'accès

Les politiques Cedar évaluées par le moteur de politiques constituent la couche d'autorisation sensible à l'identité, par demande, pour le trafic mémoire via une passerelle. Elles complètent et peuvent être combinées avec les autres options de contrôle d'accès de la passerelle :