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

# Principal-scoped 政策
<a name="example-policies-principal"></a>

本节中的政策取决于**谁在打电话**。它们在委托人（JWT 身份或 IAM 调用者）上进行匹配，并使操作和输入不受约束或仅受到宽松约束。

使用这些模式来表示网关为谁服务：哪些角色可以访问哪类工具，哪个账户被排除在外，以及哪个代理获得清单的哪个子集。有关启用所调用**内容****或其携带的值**的规则，请参阅[操作和资源范围的策略](example-policies-action-resource.md)。

每个示例都对[示例资源配置中描述的网关进行](example-policies-reference.md)授权。这些政策仅使用在 Dogwood 和 Cedar 中均有效的结构。

**注意**  
您编写的资源取决于您是否命名了特定的操作。命名一项或多项特定操作的策略必须使用带有的特定网关 ARN。`resource ==`使操作不受限制的策略必须使用类型测试。`resource is AgentCore::Gateway`使资源完全不受约束的策略在您创建时会被拒绝。有关详细信息，请参阅[资源特异性要求。](policy-scope.md#policy-resource-specificity)

## OAuth 校长
<a name="example-policies-principal-oauth"></a>

当您的网关使用 JWT 授权方时，这些模式适用，因此委托人是。`AgentCore::OAuthUser`实体 ID 是令牌的`sub`声明，令牌的其他声明可用作标签。

**重要**  
每个 JWT 声明都将成为委托人上的**字符串**标签，无论其在令牌中的类型如何。诸如之类的数字声明`exp`变为字符串`"1735689600"`，布尔变为布尔值`"true"`。数组或对象声明变为其 JSON 文本，因此数组值的`scope`声明变为字符串。`["insurance:claim","insurance:view"]`将标签与字符串运算符进行比较，将多值声明与`like`而不是`.contains()`进行匹配。值为的声明根本不`null`生成任何标签，因此会`hasTag`返回`false`该标签。

### 需要 OAuth 作用域
<a name="example-policies-principal-scope-claim"></a>

 **意图：**仅允许索赔包含`insurance:claim`以下内容的委托人提出`scope`索赔。

`hasTag`在读取标签之前使用进行测试`getTag`；读取不存在的标签是拒绝请求的错误。`like`运算符将范围与声明中出现的任何位置进行匹配，这正是您想要的，因为`scope`声明包含多个值。无论令牌是以空格分隔还是以 JSON 数组的形式传送，这都成立。

```
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___file_claim",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
)
when {
  principal.hasTag("scope") &&
  principal.getTag("scope") like "*insurance:claim*"
};
```

因为`like`匹配子字符串，所以请谨慎选择模式：`*insurance:claim*`也匹配`insurance:claim:admin`。如果你需要一个精确的值，也可以匹配分隔符。

### 允许特定用户
<a name="example-policies-principal-username"></a>

 **意图：**`clare`允许用户更新覆盖范围。

如果您要匹配的身份是令牌主体，请`principal == AgentCore::OAuthUser::"<sub>"`改为将策略范围内的实体直接与之匹配。这根本不需要任何条件，而且评估起来也更便宜。

```
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___update_coverage",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
)
when {
  principal.hasTag("username") &&
  principal.getTag("username") == "clare"
};
```

### 允许使用一组角色
<a name="example-policies-principal-role-permit"></a>

 **意图：**仅允许管理员和经理删除索赔。

```
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___delete_claim",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
)
when {
  principal.hasTag("role") &&
  (principal.getTag("role") == "admin" || principal.getTag("role") == "manager")
};
```

### 禁止除一组角色之外的所有人进入
<a name="example-policies-principal-role-forbid"></a>

 **意图：**除非委托人是高级理算师或经理，否则封锁覆盖范围的更新。

这通过相反的途径得出的结果与前面的示例类似，差异很重要。A `permit` 授予其他人`permit`也可以独立授予的访问权限。A `forbid …​ unless` 拒绝任何人`permit`无法恢复的访问权限，因为`forbid`永远是赢家。`forbid …​ unless`用于无论引擎包含什么其他策略都要保留的限制。

```
forbid(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___update_coverage",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
)
unless {
  principal.hasTag("role") &&
  (principal.getTag("role") == "senior-adjuster" || principal.getTag("role") == "manager")
};
```

### 在网关上的任何地方屏蔽用户
<a name="example-policies-principal-block-user"></a>

 **意图：**立即撤销已暂停账户的所有访问权限。

由于操作不受限制，因此资源是作为类型测试`resource is AgentCore::Gateway`而不是特定的 ARN 编写的。此策略适用于策略引擎所连接的每个网关及其上的每种目标类型，包括 MCP 工具、运行时调用和推理调用。

```
forbid(
  principal is AgentCore::OAuthUser,
  action,
  resource is AgentCore::Gateway
)
when {
  principal.hasTag("username") &&
  principal.getTag("username") == "suspended-user"
};
```

## IAM 主体
<a name="example-policies-principal-iam"></a>

当您的网关使用时，这些模式适用`AWS_IAM`，因此主体是`AgentCore::IamEntity`。实体 ID 是呼叫者的 ARN，删除了会话名称，这会使代入的角色显示为`arn:aws:sts::<account>:assumed-role/<role-name>`并允许您在会话之间可靠地匹配该角色。

### 允许任何 IAM 呼叫者
<a name="example-policies-principal-iam-any"></a>

 **意图：**允许任何 IAM-authenticated 来电者阅读合同。

只有在进行身份验证时才使用此选项，因为任何 IAM 身份都足以做出授权决定。网关的资源策略及其执行角色已经限制了谁可以访问它。

```
permit(
  principal is AgentCore::IamEntity,
  action == AgentCore::Action::"InsuranceAPI___get_contract",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
);
```

### 允许一个特定的 IAM 角色
<a name="example-policies-principal-iam-role"></a>

 **意图：**仅允许索赔处理服务支付款项。

在策略范围`principal ==`中与匹配是最精确的形式，不需要任何条件。写入不带会话名称的 ARN；服务会在评估之前删除会话名称。

```
permit(
  principal == AgentCore::IamEntity::"arn:aws:sts::123456789012:assumed-role/ClaimsProcessorRole",
  action == AgentCore::Action::"InsuranceAPI___disburse_payment",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
);
```

### 匹配 IAM 角色系列
<a name="example-policies-principal-iam-pattern"></a>

 **意图：**允许任何账户中的任何索赔处理角色读取索赔状态。

`principal.id like`当一个策略必须涵盖多个角色时使用。另外两个有用的模式：
+  `principal.id like "arn:aws:sts::123456789012:assumed-role/*"`匹配一个账户中的任何角色。
+  `principal.id like "*:123456789012:*"`匹配来自一个账户的任何 IAM ARN，无论其形式如何。

```
permit(
  principal is AgentCore::IamEntity,
  action == AgentCore::Action::"InsuranceAPI___get_claim_status",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
)
when {
  principal.id like "arn:aws:sts::*:assumed-role/ClaimsProcessor*"
};
```

没有通配符的`like`模式等同于`principal ==`但会消耗一个条件，因此最好使用`principal ==`单个角色。

### 禁止开设账户
<a name="example-policies-principal-iam-forbid-account"></a>

 **意图：**阻止供应商账户在网关上执行每项操作。

该模式以 IAM 调用者可以采用的任何形式`*:444455556666:*`匹配包含该账户 ID 的任何 ARN。因为`forbid`胜过每一个人`permit`，所以无论引擎允许什么，这都成立。

```
forbid(
  principal is AgentCore::IamEntity,
  action,
  resource is AgentCore::Gateway
)
when {
  principal.id like "*:444455556666:*"
};
```

### 禁止只读角色进行写入操作
<a name="example-policies-principal-iam-forbid-role"></a>

 **意图：**阻止用于读取的角色访问任何改变状态的工具。

列`forbid`出写入操作的 A 只能在一个方向上安全失败。添加新的读取工具无需更改政策。添加新的写入工具需要您扩展列表，否则新工具将失去保护。如果你更喜欢相反的偏见，`permit`可以改为写一个列出读取操作的，这样新添加的工具就会被拒绝，除非你故意允许它。

```
forbid(
  principal == AgentCore::IamEntity::"arn:aws:sts::123456789012:assumed-role/ReadOnlyAgentRole",
  action in [
    AgentCore::Action::"InsuranceAPI___file_claim",
    AgentCore::Action::"InsuranceAPI___update_coverage",
    AgentCore::Action::"InsuranceAPI___approve_claim",
    AgentCore::Action::"InsuranceAPI___disburse_payment",
    AgentCore::Action::"InsuranceAPI___delete_claim"
  ],
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
);
```

### 为每个代理提供自己的工具集
<a name="example-policies-principal-iam-multi-agent"></a>

 **意图：**让分流代理读取索赔，而处理代理则读取和付款。

多个代理可以共享一个网关和一个策略引擎，同时看到不同的工具。每个代理的`tools/list`回复仅包含其委托人有权调用的工具，因此不会告知代理无法使用的工具。

```
// Triage agent: read only
permit(
  principal == AgentCore::IamEntity::"arn:aws:sts::123456789012:assumed-role/TriageAgentRole",
  action in [
    AgentCore::Action::"InsuranceAPI___get_contract",
    AgentCore::Action::"InsuranceAPI___get_claim_status"
  ],
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
);

// Processing agent: read, approve, and disburse
permit(
  principal == AgentCore::IamEntity::"arn:aws:sts::123456789012:assumed-role/ProcessingAgentRole",
  action in [
    AgentCore::Action::"InsuranceAPI___get_contract",
    AgentCore::Action::"InsuranceAPI___get_claim_status",
    AgentCore::Action::"InsuranceAPI___approve_claim",
    AgentCore::Action::"InsuranceAPI___disburse_payment"
  ],
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5"
);
```