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

# Fine-grained 内存访问控制
<a name="memory-gateway-fgac"></a>

借助 Amazon Bedrock Memory 的精细访问控制 (FGAC)，您可以将 AgentCore 内存访问权限绑定到呼叫者的身份。 OAuth-authenticated 

当呼叫者使用 Amazon IAM 凭证访问 Memory 时，您可以使用基于 IAM 身份和基于资源的策略和 Memory 的条件密钥，通过操作、内存资源以及请求的参与者、会话和命名空间范围来限制访问权限。有关这些控件，请参阅[内存中的 AgentCore 内存组织](memory-organization.md)和 [Amazon Bedrock AgentCore 的Resource-based 政策](resource-based-policies.md)。

这些 IAM 控件与调用 Memory *的 IAM 委托*人匹配。他们无法表达以*OAuth/JWT*身份为键的规则，因为 OAuth-authenticated 来电者不是 IAM 委托人。这对于呼叫者使用 OAuth 而不是 Amazon 凭据进行身份验证的应用程序很重要，例如，其最终用户通过 OpenID Connect 提供商登录的代理应用程序。在该架构中，HTTP 调用方通常是代理或后端，它在每个请求中传递最终用户（或代理自己的）JWT；FGAC 根据该令牌中的身份评估策略。借助 FGAC，您可以编写将请求属性与令牌声明进行比较的策略，这样您就可以强制执行以下规则：
+ 调用者只能访问请求`actorId`等于其 JWT `sub` 声明的事件。
+ 调用者只能检索他们自己的令牌声明中携带的命名空间下的内存记录。
+ 仅向出示特定 O `client_id` Auth 的来电者授予访问权限。

FGAC 策略还可以以 IAM 提供的相同操作 Memory-resource、和请求属性范围为条件，因此单个策略可以将调用者的身份与他们可以访问的操作和数据结合起来。

FGAC for Memory 是通过 [Amazon Bedrock 中的政策](policy.md)实施的。 AgentCore您将*策略引擎*附加到面向内存资源的[网关](memory-gateway-connector.md)，并使用 Cedar（一种在 Cedar Policy [网站上记录的开源策略语言）编写策略](https://www.cedarpolicy.com/)。网关在将请求转发到 Memory 之前会评估这些策略。Cedar 策略语言、委托人类型、策略引擎和策略验证都记录[在 Amazon Bedrock AgentCore 的策略](policy.md)中，本页仅描述了内存的特定内容：内存连接器公开的操作和请求属性，以及按调用者隔离内存数据的策略模式。

**注意**  
FGAC for Memory 建立在内存连接 AgentCore 器之上。首先设置带有内存连接器目标的网关。有关更多信息，请参阅[通过网关访问 AgentCore 内存](memory-gateway-connector.md)。

**Topics**
+ [细粒度访问控制的工作原理](#memory-gateway-fgac-how)
+ [为内存设置精细的访问控制](#memory-gateway-fgac-setup)
+ [内存操作和请求属性](#memory-gateway-fgac-reference)
+ [你可以强制执行什么](#memory-gateway-fgac-enforced)
+ [对现有内存采用精细的访问控制](#memory-gateway-fgac-adopting)
+ [与其他访问控制选项的关系](#memory-gateway-fgac-relationship)
+ [内存策略示例](memory-gateway-fgac-policy-examples.md)

## 细粒度访问控制的工作原理
<a name="memory-gateway-fgac-how"></a>

策略引擎拥有一组 Cedar 策略，并针对流经关联网关的每个请求对其进行评估。**在网关对调用者进行身份验证并将请求解析为内存操作后，策略引擎会根据请求**的主**体（谁在调用）、操作（哪个内存操作）、**资源**（哪个网关）和**上下文**（请求的属性，例如路径参数和正文字段）评估策略。**默认情况下，评估是拒绝的，并且会被覆盖。`forbid` `permit`

由于内存连接器使每个内存操作都可用作 Cedar 操作及其请求字段，因此您的策略可以允许或拒绝特定的内存操作及其请求属性的条件。通用的 Cedar 模型（策略结构`forbid`、`permit`/、`AgentCore::OAuthUser`以及`AgentCore::IamEntity`主体类型、标签和`context.input`）在[策略范围](policy-scope.md)和[核心概念](policy-core-concepts.md)中进行了描述。

## 为内存设置精细的访问控制
<a name="memory-gateway-fgac-setup"></a>

**注意**  
您可以通过 Amazon 管理控制台、 Amazon SDK 和 Amazon 命令行界面 (CL Amazon I) 为内存设置精细的访问控制。

有了带有内存连接器目标的网关之后（参见[通过网关访问 AgentCore 内存](memory-gateway-connector.md)）：

1. 创建策略引擎并添加您的 Cedar 策略。有关步骤，请参阅[创建策略引擎](policy-create-engine.md)和[创建策略](policy-create-policies.md)。有关要编写的策略，[请参阅内存策略示例](memory-gateway-fgac-policy-examples.md)。

1. 通过设置网关，将策略引擎与前置内存资源的网关关联起来。`policyEngineConfiguration`您可以在使用创建网关时进行设置 [CreateGateway](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html)，也可以稍后使用添加网关[UpdateGateway](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_UpdateGateway.html)。

策略引擎`mode`控制策略是强制执行 (`ENFORCE`) 还是仅评估和记录而不阻塞流量 (`LOG_ONLY`)。切换到`LOG_ONLY`之前，请先测试您的政策，`ENFORCE`以免出现意外拒绝。有关实施模式、策略验证和测试的信息，请参阅[验证和测试策略](policy-validate-policies.md)和[使用策略](policy-use-policies.md)。

## 内存操作和请求属性
<a name="memory-gateway-fgac-reference"></a>

本节是编写策略的 Memory-specific 参考：每个内存操作的 Cedar 操作 ID 以及下方提供的请求属性`context.input`。

### 记忆动作 ID
<a name="memory-gateway-fgac-action-ids"></a>

每个内存操作都是一个名为 Cedar 的操作`<target-name>___<METHOD>:<uri-template>`，其中`<target-name>`是您的连接器目标的名称。URI 保留其路径参数占位符——它们不会被具体值所取代。在下表中，`<target-name>`替换为连接器目标的名称。


| 内存操作 | 雪松动作 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 不支持通配符；要在一个策略中授予多个操作，请使用`action in […​]`列出它们。

**注意**  
内存批量操作（`BatchCreateMemoryRecords``BatchUpdateMemoryRecords`、和`BatchDeleteMemoryRecords`）不能作为 Cedar 操作使用，也不能由精细的访问控制进行管理。每个记录都在单个请求中携带多条记录，策略引擎无法单独评估这些记录，因此不能将每条记录或每个命名空间的条件应用于它们。  
通过基于 IAM 身份和基于资源的策略（例如，通过允许或拒绝操作），您仍然可以允许或拒绝批量操作。`bedrock-agentcore:BatchCreateMemoryRecords`缺少的只是每条记录的粒度：在细粒度的访问控制层，批量操作要么全有要么全无。

### 请求上下文字段
<a name="memory-gateway-fgac-context-fields"></a>

网关在下面公开了每个请求的属性`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` 

 **Request-body 字段**（取决于操作，来自请求有效负载）：
+  `context.input.namespace` 
+  `context.input.namespacePath` 
+  `context.input.metadata` 
+  `context.input.filter` 
+  `context.input.payload` 
+ 以及由每个操作的架构定义的其他正文字段

可用字段因操作而异。一个操作携带的字段（例如，`actorId`on`ListEvents`）可能不存在于同一策略匹配的另一个操作中。

**警告**  
引用上下文字段的策略会根据其范围内的操作的架构进行验证，但不会针对请求在运行时可能达到的每个操作进行验证。如果策略引用了传入请求未包含的字段，则可以成功创建该策略并到达该策略`ACTIVE`，但在策略引擎评估该请求时会拒绝该请求并提供`403`响应，因为缺少引用的字段。创建策略时不会报告此情况。  
为避免意外拒绝：  
将每个策略的范围限定为其请求中包含策略引用的字段的特定操作，并根据[内存操作 ID](#memory-gateway-fgac-action-ids) 表中的每个操作确认这些字段。
使用`has`（例如`context has input && context.input has actorId`）保护每个字段访问权限，以便在字段不存在时`permit`条件可以预测地进行评估。
在强制执行策略之前，先在`LOG_ONLY`模式下对其进行测试，这样您就可以在不拒绝实时流量的情况下观察评估结果。有关更多信息，请参阅[为内存设置精细访问控制。](#memory-gateway-fgac-setup)

## 你可以强制执行什么
<a name="memory-gateway-fgac-enforced"></a>

通过内存连接器强制执行 FGAC 适用于网关的所有入站身份验证模式。使用上面的操作和属性，您可以强制执行：
+  **Principal-type gating** — 按 IAM-only 呼叫者类别划分的策略范围 OAuth-only 或来电者匹配或拒绝。
+  **Per-identity 隔离** — 一种请求属性，例如`actorId`可以要求等同于 JWT 中经过身份验证的用户或代理的主`sub`张，允许所有者而拒绝其他所有者。
+  **命名空间隔离** — 将请求的 o `namespace` r `namespacePath` 与文字进行比较，或者与令牌声明中包含的命名空间路径进行比较，限制调用者可以检索哪些记录。
+  **操作范围界**定-可以允许单个操作、一组操作或任何操作；不允许的操作将被拒绝。
+  **Path-parameter 条件** — 路径参数`memoryId`，例如`actorId`、和`sessionId`。
+  **Request-body 条件** — 正文场，例如`metadata`和`namespacePath`。
+  **资源固定**-允许匹配的网关 ARN；拒绝不同的 ARN。
+  **JWT 申领条件** — 令牌声明，例如`sub`和`client_id`门禁（OAuth 入站）。
+  **IAM 身份条件** — 调用者的 IAM ARN 可以按模式进行匹配（IAM 入站）。

有关实现这些策略的策略，[请参阅内存策略示例](memory-gateway-fgac-policy-examples.md)。

## 对现有内存采用精细的访问控制
<a name="memory-gateway-fgac-adopting"></a>

主隔离模式要求请求中的`actorId`等于调用方的 JWT `sub` 声明 (`context.input.actorId == principal.getTag("sub")`)。现有部署通常使用与其身份提供商提供的`sub`值不匹配的内部用户 ID。`actorId`如果您的`actorId`值已经等于提供商的值`sub`，则无需进行任何更改。否则，请选择以下方法之一：

 **根据自定义 JWT 声明进行匹配**   
如果您的身份提供商可以发布已经包含您的内部用户 ID 的声明（例如，反映您的`actorId`计划的自定义声明），请与该声明进行比较，而不是，例如`context.input.actorId == principal.getTag("custom:app_user_id")`。`sub``hasTag`先守住它。这样可以避免更改任何存储的数据。

 **按命名空间隔离，而不是 `actorId`**   
如果您的长期内存记录是按用户命名空间组织的，请在命名空间上强制隔离，而不是在命名空间上强制隔离。`actorId`让您的身份提供商发布包含呼叫者完整命名空间路径的声明，并将该请求与该声明进行比较。`namespacePath`有关命名空间隔离模式的信息，[请参阅内存策略示例](memory-gateway-fgac-policy-examples.md)。

 **`actorId`与 “对齐” `sub`**   
如果要使用默认`actorId == sub`模式，请迁移新的事件和记录，以使用提供者的模式`sub`作为`actorId`。由于 Memory 将事件和记录 AgentCore 存储在`actorId`您提供的范围内，因此这通常适用于未来，而不是重写历史数据；计划一个可能同时存在两种方案的过渡期。

**提示**  
您可以先在`LOG_ONLY`模式下附加策略并查看评估日志，从而在不影响实时流量的情况下验证这些方法中的任何一个。请参见[为内存设置精细访问控制。](#memory-gateway-fgac-setup)

## 与其他访问控制选项的关系
<a name="memory-gateway-fgac-relationship"></a>

策略引擎评估的 Cedar 策略是针对通过网关的内存流量的身份感知、按请求分配的授权层。它们补充了网关的其他访问控制选项，并且可以与之组合使用：
+  **网关拦截器**允许您在代码中实现自定义授权逻辑。有关更多信息，请参阅 [Amazon Bedrock AgentCore Gateway 的Fine-grained 访问控制](gateway-fine-grained-access-control.md)。
+  Resource-based 内存资源@@ **策略**使用条件键（如和）控制哪些 IAM 委托人（包括特定网关）可以调用 Memory。`aws:SourceArn` `aws:PrincipalArn`有关更多信息，请参阅 [Amazon Bedrock Resource-based 政策 AgentCore](resource-based-policies.md)以及[出站凭证模式如何影响内存访问控制](memory-gateway-connector.md#memory-gateway-connector-credential-modes)。