本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 通过网关访问 AgentCore 内存
<a name="memory-gateway-connector"></a>

默认情况下，应用程序直接调用亚马逊基岩 AgentCore 内存数据平面，并且每个请求都使用 Amazon 签名版本 4 (SigV4) 进行身份验证。您可以使用基于 IAM 身份和基于资源的策略来控制这种访问权限。当你的后端服务代表所有用户调用 Memory 并且不需要在内存层强制每位用户隔离时，这种方法效果很好。

当您的后端为许多用户调用 Memory 时，Memory 只能看到您的后端的 IAM 角色。它无法验证请求针对的是哪个最终用户。您的应用程序代码必须在每个请求上设置正确的`actorId`命名空间，以将一个用户的数据与另一个用户的数据隔离开来。

使用[位于 AgentCore 内存前面的](gateway.md)AgentCore 网关，您可以将该强制措施从应用程序代码中移出到基础架构中。网关成为内存流量的单一安全入口点。它对每个调用者进行身份验证，评估访问控制策略，并将允许的请求转发到 Memory。带网关的前置内存为您提供了两个直接访问不具备的功能：

 **最终用户的 OAuth 身份验证 **   
内存的数据平面是 SigV4-only。将网关配置为 OAuth (JWT) 入站身份验证后，您的最终用户可以向标准 OpenID Connect 提供商进行身份验证，并且您的应用程序不会向他们分发 Amazon 证书。有关更多信息，请参阅[使用 OAuth ](memory-gateway-oauth.md) 对最终用户进行内存身份验证。

 **Fine-grained 访问控制 **   
网关可以评估限制调用者使用自己的参与者、自己的命名空间或一组特定的内存操作的策略，包括针对通过 OAuth 进行身份验证的调用者。有关更多信息，请参阅内存的[Fine-grained 访问控制](memory-gateway-fgac.md)。  
Fine-grained 内存批处理操作（`BatchCreateMemoryRecords``BatchUpdateMemoryRecords`、和`BatchDeleteMemoryRecords`）不支持访问控制。这些操作中的每一项都在单个请求中携带多条记录，策略引擎无法单独评估这些记录。

这两个功能都建立在本页描述的 AgentCore 内存连接器之上。设置连接器是任何一个的先决条件。

**Topics**
+ [AgentCore 存储器连接器](#memory-gateway-connector-what)
+ [请求如何流经网关](#memory-gateway-connector-flow)
+ [入站和出站身份验证模式](#memory-gateway-connector-auth-modes)
+ [出站凭证模式如何影响内存访问控制](#memory-gateway-connector-credential-modes)
+ [使用内存连接器目标设置网关](memory-gateway-setup.md)
+ [使用控制台创建内存连接器](memory-gateway-connector-console.md)
+ [使用 OAuth 对内存中的最终用户进行身份验证](memory-gateway-oauth.md)
+ [Fine-grained 内存访问控制](memory-gateway-fgac.md)
+ [限制直接访问内存](memory-gateway-restrict-access.md)

## AgentCore 存储器连接器
<a name="memory-gateway-connector-what"></a>

 AgentCore 内存连接器 (`agentcore-memory`) 是一个托管网关连接器，用于将[网关目标](gateway-core-concepts.md)连接到 AgentCore 内存数据平面。连接器是一种内置的目标类型：与其创建 API 架构和自己管理端点布线，不如创建连接器类型的目标并仅提供连接器 ID 和目标参数。

创建内存连接器目标时，需要提供：
+ 连接器 ID (`agentcore-memory`)，以及
+ 目标参数，尤其是目标前端`memoryId`的内存资源的参数。

然后连接器：

 **解析内存端点 **   
它为目标的内存资源确定正确的内存数据平面端点。

 **将支持的内存操作作为 Cedar 操作提供 **   
该连接器使以下内存数据平面操作作为 Cedar 操作可用，每个操作都有它接受的请求字段：`ListEvents``CreateEvent``GetEvent`、、`DeleteEvent`、`ListSessions`、`ListActors`、`RetrieveMemoryRecords`、`ListMemoryRecords`、`GetMemoryRecord`、、`DeleteMemoryRecord``ListMemoryExtractionJobs`、和`StartMemoryExtractionJob`。这就是允许细粒度的访问控制策略允许或拒绝特定内存操作及其请求属性的条件的原因。有关操作 ID 和请求属性，请参阅内存的[Fine-grained 访问控制](memory-gateway-fgac.md)。  
精细访问控制不支持内存批量操作（`BatchCreateMemoryRecords``BatchUpdateMemoryRecords`、和`BatchDeleteMemoryRecords`）。这些操作中的每一项都在单个请求中携带多条记录，策略引擎无法单独评估这些记录。

 **转发请求 **   
它使用目标配置的出站凭据模式将每个允许的请求转发到内存数据平面。

由于连接器提供了开箱即用的内存模型，因此您无需手动编写架构或管理端点布线。

## 请求如何流经网关
<a name="memory-gateway-connector-flow"></a>

当客户端通过网关调用 Memory 时，网关分四个步骤处理请求：

1.  **入站身份验证 ** — 网关根据其入站授权方类型对调用者进行验证：OAuth (JWT) 持有者令牌、 Amazon SigV4 或未经身份验证的请求。请参阅[入站和出站身份验证模式](#memory-gateway-connector-auth-modes)。

1.  **操作解析 ** ——网关将传入的 HTTP 请求（方法和路径）映射到调用者正在尝试的内存操作的 Cedar 操作。路径参数和请求正文字段被提取到请求上下文对象中。

1.  **策略评估 ** — 如果网关附有策略引擎，它将根据请求评估配置的访问控制策略。默认情况下，评估是拒绝的。参见内存的[Fine-grained 访问控制](memory-gateway-fgac.md)。

1.  **出站身份验证 ** — 如果允许请求，则网关使用目标的出站凭据模式将其转发到内存数据平面。请参阅[出站凭证模式](#memory-gateway-connector-outbound)。

## 入站和出站身份验证模式
<a name="memory-gateway-connector-auth-modes"></a>

网关具有控制其对呼叫者进行身份验证的*入站*授权方类型，并且每个 Memory 连接器目标都有一个*出站*凭据模式，用于控制网关调用 Memory 时使用的身份。大多数部署使用以下两种组合之一：

 **OAuth 最终用户（主要的细粒度访问控制路径）**   
 `CUSTOM_JWT`入站和`GATEWAY_IAM_ROLE`出站。您的用户或代理向 OpenID Connect 提供商进行身份验证，网关以自己的网关执行角色调用 Memory。当您希望对不是 IAM 委托人的呼叫者进行按用户隔离时，可使用此组合。有关更多信息，请参阅[使用 OAuth ](memory-gateway-oauth.md) 对最终用户进行内存身份验证。

 **具有身份传递功能的 IAM 后端服务 **   
 `AWS_IAM`入站和`CALLER_IAM_CREDENTIALS`出站。网关将每个调用者自己的 IAM 身份转发到 Memory，因此 Memory 会评估调用者的 IAM 权限，您可以对网关转发的流量进行源头固定。当您的调用者已经是 IAM 委托人并且您希望 Memory 直接向他们授权时，请使用此方法。

特殊场景支持其他组合，例如`AWS_IAM`针对 IAM 呼叫者的集中式 Cedar 执法或开发和测试。`NONE` `GATEWAY_IAM_ROLE`有关完整套装，请参见[兼容性矩阵](#memory-gateway-connector-compatibility)。

### 入站授权者类型
<a name="memory-gateway-connector-inbound"></a>

在创建网关时，您可以选择入站授权方。内存连接器支持 AgentCore Gateway 支持的所有入站授权方类型。有关更多信息，请参阅亚马逊基岩 AgentCore 网关[的](gateway-core-concepts.md)核心概念。
+  `CUSTOM_JWT`(OAuth/JWT) — 精细访问控制的主要路径。使调用者的 JWT 声明可用于访问控制策略，并为最终用户启用 OAuth 身份验证。请参阅[使用 OAuth ](memory-gateway-oauth.md) 对最终用户进行内存身份验证。
+  `AWS_IAM`(SigV4) — 向访问控制策略提供呼叫者的 IAM 身份。将其用于 IAM-authenticated 后端调用者、集中式 Cedar 执法或源代码固定。
+  `AUTHENTICATE_ONLY`— 需要有效的签名请求，但不为基于身份的策略规则公开键入的来电者身份。
+  `NONE`— 没有授权。仅用于开发和测试；请勿将其用于生产内存访问。

### 出站凭证模式
<a name="memory-gateway-connector-outbound"></a>

出站凭据模式决定内存数据平面看到的身份。规则很简单：
+ 如果您的入站身份验证为`CUSTOM_JWT`或`NONE`，则网关将始终使用 `GATEWAY_IAM_ROLE` ——它以其网关执行角色调用 Memory。没有其他有效的选项，也没有什么可选择的。
+ 如果您的入站身份验证为`AWS_IAM`或`AUTHENTICATE_ONLY`，您还可以选择`CALLER_IAM_CREDENTIALS`将调用者自己的 IAM 身份转发到 Memory，而不是使用网关执行角色。


| 出站模式 | 网关如何调用内存 | 
| --- | --- | 
|  `GATEWAY_IAM_ROLE`  | 网关在其网关执行角色下调用内存（第一方调用）。适用于所有入站类型。 | 
|  `CALLER_IAM_CREDENTIALS`  | 网关将调用者自己的 IAM 身份转发到 Memory（委托访问权限）。需要`AWS_IAM`或`AUTHENTICATE_ONLY`入站，因为它需要呼叫方 IAM 身份才能转发。 | 

#### 兼容性矩阵
<a name="memory-gateway-connector-compatibility"></a>

下表列出了内存连接器目标上支持的入站授权方和出站凭据模式的所有组合。


| 入站 |  `GATEWAY_IAM_ROLE`  |  `CALLER_IAM_CREDENTIALS`  | 
| --- | --- | --- | 
|  `CUSTOM_JWT`  | 支持 | 创建目标时被拒绝 | 
|  `AWS_IAM`  | 支持 | 支持 | 
|  `NONE`  | 支持 | 创建目标时被拒绝 | 
|  `AUTHENTICATE_ONLY`  | 支持 | 支持 | 

## 出站凭证模式如何影响内存访问控制
<a name="memory-gateway-connector-credential-modes"></a>

出站凭证模式决定内存授权哪个身份，因此适用于调用者的 IAM 策略在每种模式下的行为都不同。它还决定如何使用基于内存[资源的策略限制网关转发的流量。](resource-based-policies.md)

 ** `GATEWAY_IAM_ROLE` **   
网关在其网关执行角色下调用 Memory，因此 Memory 将请求授权为该角色。要限制对该网关的访问，您可以对网关执行角色 ARN 使用`aws:PrincipalArn`条件，并将该角色的身份策略仅限于网关所需的内存操作。网关转发的请求还带有设置到网关 ARN 的`aws:SourceArn`条件密钥（参见以下模式）。

 ** `CALLER_IAM_CREDENTIALS` **   
网关将调用者的 IAM 身份转发到 Memory，因此 Memory 以调用者的身份对请求进行授权。由于主体是调用方而不是网关，因此使用`aws:SourceArn`条件来限制对网关转发流量的访问。

在两种出站模式下，网关都使用转发请求的网关的 ARN 标记`aws:SourceArn`条件密钥。因此，无论出站凭据模式如何，[基于内存资源的策略](resource-based-policies.md)都可以通过匹配网关 ARN 来限制`aws:SourceArn`对特定网关的访问。

**重要**  
由于出站凭证模式会更改身份内存授权的内容，因此适用于调用者的 IAM 策略的行为有所不同：  
使用`CALLER_IAM_CREDENTIALS`，Memory 可以看到调用者自己的 IAM 身份。引用调用方（包括特定`actorId`密钥或内存条件密钥，例如和）的基于身份`bedrock-agentcore:namespace`和`bedrock-agentcore:namespacePath`资源的 IAM 策略将针对该调用者进行评估。`Deny`
使用`GATEWAY_IAM_ROLE`时，内存只能看到网关执行角色。每个调用者的请求都会以该单一角色到达内存，因此，仅限于个人来电者身份（例如特定来电者身份`actorId`）的 IAM 策略**不会针对原始调用者**进行评估，也不会生效。`Deny`在此模式下，不要依赖调用者范围的 IAM 策略强制每个呼叫者访问。
如果您使用`GATEWAY_IAM_ROLE`并需要每个呼叫者的访问控制（例如，将调用者限制在自己的`actorId`或命名空间内），请在网关上使用细粒度的访问控制（Cedar 策略）来强制执行，而不是使用呼叫者范围的 IAM 策略。这是主要的细粒度访问控制路径。有关更多信息，请参阅内存的[Fine-grained 访问控制](memory-gateway-fgac.md)。

有关基于资源的策略条件密钥和 JSON 策略示例，请参阅 Amazon Bedro AgentCore [ ck 的](resource-based-policies.md)Resource-based 政策。