View a markdown version of this page

記憶體的精細存取控制 - Amazon Bedrock AgentCore
精細存取控制的運作方式設定記憶體的精細存取控制記憶體動作和請求屬性您可以強制執行的項目在現有記憶體上採用精細存取控制與其他存取控制選項的關係

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

記憶體的精細存取控制

透過 Amazon Bedrock AgentCore 記憶體的精細存取控制 (FGAC)，您可以將記憶體存取繫結至 OAuth 驗證的發起人身分。

當呼叫者使用 IAM AWS 登入資料到達記憶體時，您可以使用具有記憶體條件索引鍵的 IAM 身分型和資源型政策，依動作、記憶體資源和請求的演員、工作階段和命名空間範圍來限制存取。如需這些控制項，請參閱 Amazon Bedrock AgentCore 的 AgentCore 記憶體和資源型政策中的記憶體組織。 AgentCore

這些 IAM 控制項與呼叫記憶體的 IAM 主體相符。他們無法對 OAuth/JWT 身分表示鍵控的規則，因為 OAuth 驗證的發起人不是 IAM 主體。這對於呼叫者使用 OAuth 而非 AWS 登入資料進行身分驗證的應用程式來說很重要，例如，最終使用者透過 OpenID Connect 提供者登入的客服人員應用程式。在該架構中，HTTP 呼叫者通常是代理程式或後端，它會在每次請求時傳遞最終使用者的 （或代理程式自己的） JWT；FGAC 會根據該字符中的身分評估政策。使用 FGAC，您可以撰寫將請求屬性與字符宣告進行比較的政策，以便強制執行規則，例如：

  • 呼叫者只能存取請求actorId等於其 JWT sub宣告的事件。

  • 發起人只能在自己的權杖宣告中攜帶的命名空間下擷取記憶體記錄。

  • 只會將存取權授予呈現特定 OAuth 的發起人client_id。

FGAC 政策也可以以 IAM 提供的相同動作、記憶體資源和請求屬性範圍為條件，因此單一政策可以結合發起人與他們可以存取的操作和資料。

FGAC for Memory 是使用 Amazon Bedrock AgentCore 中的政策實作。您可以將政策引擎連接至位於記憶體資源前方的閘道，並在 Cedar 政策網站上記錄的開放原始碼政策語言 Cedar 中撰寫政策。閘道會在轉送請求至記憶體之前評估這些政策。Cedar 政策語言、主體類型、政策引擎和政策驗證都記錄在 Amazon Bedrock AgentCore 中的政策中 — 此頁面僅描述記憶體的特定內容：記憶體連接器公開的動作和請求屬性，以及依發起人隔離記憶體資料的政策模式。

注意

FGAC for Memory 是建置在 AgentCore Memory 連接器上。首先設定具有記憶體連接器目標的閘道。如需詳細資訊，請參閱透過閘道存取 AgentCore 記憶體。

主題

精細存取控制的運作方式

政策引擎會保留一組 Cedar 政策，並針對每個流經相關聯閘道的請求進行評估。在閘道驗證發起人並將請求解析為記憶體操作後，政策引擎會根據請求的委託人 （呼叫者）、動作 （記憶體操作）、資源 （閘道） 和內容 （請求的屬性，例如路徑參數和內文欄位） 來評估政策。評估預設為deny-by-default，並forbid覆寫 permit。

由於記憶體連接器可將每個記憶體操作作為 Cedar 動作及其請求欄位，因此您的政策可以允許或拒絕其請求屬性的特定記憶體操作和條件。了解 Cedar 政策和核心概念中描述了一般 Cedar 模型 — 政策結構forbid、permit/、 AgentCore::OAuthUser和 AgentCore::IamEntity 委託人類型、標籤和 context.input 。

設定記憶體的精細存取控制

注意

您可以透過 AWS 管理主控台、 AWS SDK 和 AWS 命令列界面 (AWS CLI) 設定記憶體的精細存取控制。

在您擁有具有記憶體連接器目標的閘道之後 （請參閱透過閘道存取 AgentCore 記憶體)：

  1. 建立政策引擎並新增您的 Cedar 政策。如需這些步驟，請參閱建立政策引擎和建立政策。如需要寫入的政策，請參閱記憶體的政策範例。

  2. 透過設定閘道的 ，將政策引擎與記憶體資源前方的閘道建立關聯policyEngineConfiguration。您可以在使用 CreateGateway 建立閘道時設定它，或稍後使用 UpdateGateway 新增它。

政策引擎mode控制政策是否強制執行 (ENFORCE) 或僅評估和記錄，而不會封鎖流量 (LOG_ONLY)。在 中測試您的政策，LOG_ONLY然後再切換至 ENFORCE ，以避免意外拒絕。如需強制執行模式、政策驗證和測試，請參閱驗證和測試政策和使用政策。

記憶體動作和請求屬性

本節是撰寫政策的記憶體特定參考：每個記憶體操作的 Cedar 動作 ID，以及 下可用的請求屬性context.input。

記憶體動作 ID

每個記憶體操作都是名為 的 Cedar 動作<target-name>___<METHOD>:<uri-template>，其中 <target-name>是您連接器目標的名稱。URI 會保留其路徑參數預留位置，而不會以具體值取代。在下表中，<target-name>將 取代為連接器目標的名稱。

記憶體操作 Cedar 動作 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

不支援動作 ID 萬用字元；若要在一個政策中授予多個操作，請使用 列出它們action in […​]。

注意

記憶體批次操作 (BatchCreateMemoryRecords、 和 BatchDeleteMemoryRecords) 無法做為 Cedar 動作使用BatchUpdateMemoryRecords，也無法受精細存取控制控制。每個 會在單一請求中攜帶多個記錄，政策引擎無法個別評估，因此無法套用每個記錄或每個命名空間條件。

您仍然可以使用 IAM 身分型和資源型政策 （例如，允許或拒絕bedrock-agentcore:BatchCreateMemoryRecords動作） 來允許或拒絕批次操作。缺少的只是每筆記錄的精細程度：在精細存取控制層中，批次操作是all-or-nothing。

請求內容欄位

閘道會在 下公開每個請求的屬性context.input，結合路徑參數和請求內文欄位。讀取每個欄位has之前，請先使用 保護它 （例如，context has input && context.input has actorId)。

路徑參數 （來自 URI)：

  • context.input.memoryId

  • context.input.actorId

  • context.input.sessionId

  • context.input.eventId

  • context.input.memoryRecordId

請求主體欄位 （依操作而定，來自請求承載）：

  • context.input.namespace

  • context.input.namespacePath

  • context.input.metadata

  • context.input.filter

  • context.input.payload

  • 和每個操作結構描述定義的其他內文欄位

可用的欄位會因 操作而有所不同。一個操作承載的欄位 （例如，在 actorId上ListEvents) 可能不會出現在相同政策相符的另一個操作上。

警告

參考內容欄位的政策會根據其範圍內動作的結構描述進行驗證，但並非針對請求在執行時間可能達到的每個操作進行驗證。如果政策參考傳入請求未承載的欄位，則可以成功建立政策並到達 ACTIVE，但在政策引擎評估請求時以403回應拒絕請求，因為參考欄位遺失。當您建立政策時，不會報告此條件。

若要避免意外拒絕：

  • 將每個政策範圍限定為請求攜帶政策參考欄位的特定動作，並根據記憶體動作 ID 資料表中的每個操作確認這些欄位。

  • 使用 保護每個欄位存取 has（例如，context has input && context.input has actorId)，讓permit條件在欄位不存在時可預測地評估。

  • 在強制執行政策之前，在 LOG_ONLY 模式下測試政策，以便您可以觀察評估結果，而不會拒絕即時流量。如需詳細資訊，請參閱設定記憶體的精細存取控制。

您可以強制執行的項目

透過記憶體連接器的 FGAC 強制執行可在所有閘道的傳入身分驗證模式中使用。使用上述動作和屬性，您可以強制執行：

  • 委託人類型閘道 — 範圍限定為僅限 OAuth 或僅限 IAM 的呼叫者符合或拒絕呼叫者類別的政策。

  • 依身分隔離 — actorId 可能需要 等請求屬性，才能等於 JWT 中已驗證使用者或代理程式的sub宣告，允許擁有者並拒絕其他使用者。

  • 命名空間隔離 — 比較請求的 namespace或 namespacePath與常值，或與權杖宣告中攜帶的命名空間路徑， 會限制發起人可以擷取的記錄。

  • 動作範圍：可以允許單一動作、一組動作或任何動作；不允許的動作會遭到拒絕。

  • 路徑參數條件 — 路徑參數，例如 memoryId、 actorId和 sessionId。

  • Request-body 條件 — 內文欄位，例如 metadata和 namespacePath。

  • 資源鎖定 — 允許相符的閘道 ARN；拒絕不同的 ARN。

  • JWT 宣告條件 — 字符宣告，例如 sub和 client_id 閘道存取 (OAuth 傳入）。

  • IAM 身分條件 — 發起人的 IAM ARN 可以根據模式 (IAM 傳入） 進行比對。

如需實作這些政策的政策，請參閱記憶體的政策範例。

在現有記憶體上採用精細存取控制

主要隔離模式要求請求actorId上的 等於發起人的 JWT sub宣告 (context.input.actorId == principal.getTag("sub"))。現有的部署通常會使用內部使用者 ID 做為與其身分提供者sub的值不相符actorId的 。如果您的actorId值已經等於提供者的 sub，則不需要變更。否則，請選擇下列其中一種方法：

符合自訂 JWT 宣告

如果您的身分提供者可以發出已持有內部使用者 ID 的宣告 （例如，反映您actorId配置的自訂宣告），請將 與該宣告進行比較，而不是 sub - 例如 context.input.actorId == principal.getTag("custom:app_user_id")。hasTag 請先保護它。這可避免變更任何儲存的資料。

依命名空間隔離，而非 actorId

如果您的長期記憶體記錄組織成每個使用者命名空間，請在命名空間上強制執行隔離，而不是在 上actorId。讓您的身分提供者發出保留發起人完整命名空間路徑的宣告，並將請求namespacePath與該宣告進行比較。如需命名空間隔離模式，請參閱記憶體的政策範例。

actorId與 對齊 sub

如果您想要使用預設actorId == sub模式，請遷移新的事件和記錄，以使用提供者的 sub做為 actorId。由於 AgentCore Memory 會將事件和記錄存放在actorId您提供的 下，因此這通常適用於未來，而不是重寫歷史資料；規劃兩個方案都可能存在的轉換期間。

提示

您可以先在 LOG_ONLY 模式中連接政策並檢閱評估日誌，在不影響即時流量的情況下驗證任何這些方法。請參閱設定記憶體的精細存取控制。

與其他存取控制選項的關係

政策引擎評估的 Cedar 政策是透過閘道的記憶體流量的身分感知、每個請求授權層。它們補充且可以與閘道的其他存取控制選項結合：