# AgentCore AgentCore IAM 权限中的网关和策略
<a name="policy-permissions"></a>

本指南提供了使用带有策略的 Amazon Bedrock G AgentCore ateway 所需的 IAM 权限，以便使用 Cedar 策略 AgentCore 进行精细的授权控制。

## 概述
<a name="policy-permissions-overview"></a>

将 Amazon Bedrock AgentCore Gateway 与中的策略集成时 AgentCore，需要两个不同的 IAM 角色：

1.  **网关执行角色**-Amazon Bedrock AgentCore Gateway 在运行时扮演的用于调用目标和评估 Cedar 策略的 IAM 角色

1.  **资源管理角色**-管理员用于在资源中创建和管理 Amazon Bedrock AgentCore Gateway 和策略的 IAM 角色 AgentCore 

这两个角色的用途不同，需要特定的权限。网关执行角色需要权限才能运行 Amazon Bedrock AgentCore Gateway 操作，而资源管理角色需要在资源中配置和管理 Amazon Bedrock AgentCore Gateway 和策略的 AgentCore 权限。

## 网关执行角色
<a name="policy-permissions-execution-role"></a>

网关执行角色由 Amazon Bedrock AgentCore Gateway 服务在处理请求时担任。此角色需要以下权限：
+ 通过政策评估 Cedar 的政策 AgentCore
+ 调用 Lambda 函数和 API Gateway 终端节点等目标
+ 向和写入日志 CloudWatch 和跟踪 X-Ray
+ 身份验证配置的访问密钥

**重要**  
执行角色必须包含这三种权限才能使用带有策略的 Amazon Bedrock AgentCore Gateway AgentCore:。 `bedrock-agentcore:AuthorizeAction`-评估 Cedar 的授权决策政策。 `bedrock-agentcore:PartiallyAuthorizeActions`-列出呼叫者有权调用的工具。 `bedrock-agentcore:GetPolicyEngine`-检索策略引擎配置如果没有这些权限，网关将无法执行策略授权。这有两种表现形式：将策略引擎附加到现有网关将导致 InternalServerException，并且默认情况下，即使您配置了许可策略，所有工具调用也将被拒绝。

### 信任策略
<a name="policy-permissions-execution-trust"></a>

网关执行角色必须信任`bedrock-agentcore.amazonaws.com`服务主体。

**重要**  
将以下占位符替换：\* {{us-east-1}} 用 AWS 区域 \* {{123456789012}} 替换为 AWS 账户 ID

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "AllowBedrockAgentCoreAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}
```

### 权限策略
<a name="policy-permissions-execution-permissions"></a>

该政策授予 Amazon Bedrock AgentCore Gateway 通过中的政策评估 Cedar 政策的 AgentCore必要权限。按照最低权限原则，权限分为两个语句。

**重要**  
将以下占位符：\* {{us-east-1}} 替换为 AWS 区域 \* {{123456789012}} 使用 AWS 账户 ID \* 和网关 ID（或{{<gateway-id>}}使用\* 表示所有网关）\* 和策略引擎 ID（或{{<policy-engine-id>}}使用\* 表示所有策略引擎）\*（或使用\* 表示所有策略引擎）

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
      ]
    }
  ]
}
```

**注意**  
\* 可能需要额外的权限，具体取决于亚马逊 Bedrock AgentCore Gateway 集成类型（例如 Lambda 函数、API 网关终端节点）。此处不包括这些权限，因为它们因具体的集成而异。\* 用于生产：将占位符替换为特定的资源 ID（例如，`policy-engine/my-policy-engine-id`而不是`policy-engine/<policy-engine-id>`），以遵循最低权限原则，或者使用通配符 (\*) 允许访问该类型的所有资源。

## 资源管理角色
<a name="policy-permissions-management-role"></a>

管理员使用资源管理角色在 AgentCore 资源中创建和管理 Amazon Bedrock AgentCore Gateway 和策略。此角色需要以下权限：
+ 创建、更新和删除网关和网关目标
+ 创建、更新和删除策略引擎和 Cedar 策略
+ 在策略创建期间调用 Gateway (`InvokeGateway`)，这样中的策略 AgentCore 就可以根据目标网关的功能验证 Cedar 语句中的操作
+ 在创建过程中将网关执行角色传递给 Amazon Bedrock AgentCore Gateway 资源
+ 为组织和管理资源添加标签
+ 阅读 IAM 角色信息以验证执行角色配置

此角色与网关执行角色是分开的，只有在 AgentCore 配置中设置或修改 Amazon Bedrock AgentCore Gateway 和策略时才需要。

### 权限策略
<a name="policy-permissions-management-permissions"></a>

**重要**  
将以下占位符替换：\* {{us-east-1}} 用 AWS 区域 \* {{123456789012}} 替换为 AWS 账户 ID

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "GatewayManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateGateway",
        "bedrock-agentcore:UpdateGateway",
        "bedrock-agentcore:GetGateway",
        "bedrock-agentcore:DeleteGateway",
        "bedrock-agentcore:ListGateways",
        "bedrock-agentcore:InvokeGateway",
        "bedrock-agentcore:CreateGatewayTarget",
        "bedrock-agentcore:UpdateGatewayTarget",
        "bedrock-agentcore:GetGatewayTarget",
        "bedrock-agentcore:DeleteGatewayTarget",
        "bedrock-agentcore:ListGatewayTargets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    },
    {
      "Sid": "PolicyEngineManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicyEngine",
        "bedrock-agentcore:UpdatePolicyEngine",
        "bedrock-agentcore:GetPolicyEngine",
        "bedrock-agentcore:DeletePolicyEngine",
        "bedrock-agentcore:ListPolicyEngines"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicy",
        "bedrock-agentcore:UpdatePolicy",
        "bedrock-agentcore:GetPolicy",
        "bedrock-agentcore:DeletePolicy",
        "bedrock-agentcore:ListPolicies"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy/*"
      ]
    },
    {
      "Sid": "PolicyGeneration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:StartPolicyGeneration",
        "bedrock-agentcore:GetPolicyGeneration",
        "bedrock-agentcore:ListPolicyGenerations",
        "bedrock-agentcore:ListPolicyGenerationAssets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy-generation/*"
      ]
    },
    {
      "Sid": "IAMPassRole",
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*BedrockAgentCore*"
      ],
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "bedrock-agentcore.amazonaws.com"
        }
      }
    },
    {
      "Sid": "IAMReadAccess",
      "Effect": "Allow",
      "Action": [
        "iam:GetRole",
        "iam:GetRolePolicy",
        "iam:ListAttachedRolePolicies",
        "iam:ListRolePolicies"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*"
      ]
    },
    {
      "Sid": "PolicyScopeManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:ManageResourceScopedPolicy",
        "bedrock-agentcore:ManageAdminPolicy"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}
```

**重要**  
 `bedrock-agentcore:InvokeGateway`是创建或更新 Cedar 策略所必需的，而不仅仅是在运行时调用 Gateway。 `CreatePolicy`并`UpdatePolicy`验证您的 Cedar 声明中针对网关的操作，该操作已在 Gateway ARN `InvokeGateway` 上获得授权。没有它，策略就会过渡到 wit `CREATE_FAILED` h `Insufficient permissions to call gateway with ID <gateway-id>`。

**重要**  
`ManageResourceScopedPolicy`和`ManageAdminPolicy`操作是仅限权限的门户，用于控制管理员可以创建哪些类型的 Cedar 策略：\* `ManageResourceScopedPolicy`-授予创建针对特定网关 ARN 的 Cedar 策略的权限（例如，应用于的策略`gateway/my-gateway-123`）\* `ManageAdminPolicy`-授予使用通配符创建 Cedar 策略的权限（例如，应用于网关的策略/\*）这两个权限都是完全策略管理功能所必需的。这些不是 API 操作，而是确定可以通过策略管理 API 创建的 Cedar 策略范围的授权检查。

**注意**  
虽然为了保持一致性而包含了 “资源” 字段，但这些仅限权限的操作主要是在操作级别而不是资源级别限制能力。

## 什么时候需要更新角色？
<a name="policy-permissions-when-required"></a>

根据亚马逊 Bedrock AgentCore Gateway 的创建方式，确定是否需要将 AgentCore 权限策略添加到 Amazon Bedrock AgentCore Gateway 执行角色中。

 **场景 1： AgentCore 使用 CLI 创建网关**   
 **状态：**需要操作  
 AgentCore CLI 创建一个网关执行角色，该角色具有目标调用和出站身份验证的限定权限，但权限中 AgentCore 不包含策略。您必须手动将本指南中记录的`AuthorizeAction``PartiallyAuthorizeActions`、和`GetPolicyEngine`权限添加到网关执行角色中。

 **场景 2：自定义执行角色**   
 **状态：**需要操作  
自定义 IAM 角色需要手动添加本指南中记录的 AgentCore 权限策略。请遵循上述部分中的权限政策。

 **场景 3：生产 Least-Privilege 配置**   
 **状态：**需要操作  
对于生产环境，将策略范围限定为对特定资源 ARN 的 AgentCore 权限，而不是使用通配符。将策略引擎/\* 和 gateway/\* 替换为权限策略中的特定策略引擎和网关 ID。

## 问题排查
<a name="policy-permissions-troubleshooting"></a>

本节介绍使用策略为 Amazon Bedrock AgentCore Gateway 配置 IAM 权限时的常见问题。 AgentCore

### InternalServerException 在政策评估期间
<a name="policy-permissions-error-403"></a>

 **症状：**将策略引擎连接到现有网关`InternalServerException - Policy evaluation failed`时，网关会返回，默认情况下，即使配置了许可策略，所有工具调用也会被拒绝。

 **根本原因：**网关执行角色在 AgentCore 权限中缺少所需的策略。没有这些权限，网关就无法执行策略授权。

 **解决方案：**确保网关执行角色包含以下三个权限：

```
{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:PartiallyAuthorizeActions",
    "bedrock-agentcore:AuthorizeAction",
    "bedrock-agentcore:GetPolicyEngine"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:policy-engine/*",
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:gateway/*"
  ]
}
```

**注意**  
如果您使用策略引擎控制台将策略引擎附加到现有网关，则 IAM 权限可能不会自动更新。您必须手动将这些权限添加到网关的 Service-Linked 角色中。

### “呼叫网关的权限不足” 开启 CreatePolicy
<a name="policy-permissions-error-create-policy-invoke"></a>

 **症状：**`CreatePolicy`返回 a`policyId`，但策略随后会转换为 `CREATE_FAILED` w `Insufficient permissions to call gateway with ID <gateway-id>` ith，即使网关执行角色具有`AuthorizeAction``PartiallyAuthorizeActions`、和`GetPolicyEngine`。

 **根本原因：**差距在于调用的资源管理角色`CreatePolicy`，而不是网关执行角色。策略验证调用网关（授权为`bedrock-agentcore:InvokeGateway`）；错误命名为网关，但修复方法在于策略创建角色。

 **解决方案：**将`bedrock-agentcore:InvokeGateway`（范围限定为网关 ARN）添加到资源管理角色：

```
{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:InvokeGateway"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
  ]
}
```

### 仅限日志模式下的静默失败
<a name="policy-permissions-error-silent"></a>

 **症状：**策略引擎似乎在 LOG\_ONLY 模式下运行，但在没有正确错误消息的情况下静默失败。

 **根本原因：**缺少`bedrock-agentcore:GetPolicyEngine`权限会导致静默失败，只有在切换到强制模式时才会出现这种故障。

 **解决方案：**即使使用 LOG\_ONLY 模式进行测试，也要始终包含`bedrock-agentcore:GetPolicyEngine`在网关执行角色中。

### 未找到策略引擎错误
<a name="policy-permissions-error-not-found"></a>

 **症状：**Amazon Bedrock AgentCore Gateway 返回错误，表明它无法找到或访问策略引擎。

 **根本原因：**网关执行角色的策略使用了错误的 ARN 模式或缺少策略引擎资源。

 **解决方案：**确保策略引擎和网关 ARN 都包含在资源阵列中：

```
"Resource": [
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
]
```

**注意**  
两者都`AuthorizeAction``PartiallyAuthorizeActions`需要访问策略引擎和网关资源。

### 调试技巧
<a name="policy-permissions-debugging-tips"></a>

1.  **启用 CloudWatch 日志**-为 Amazon Bedrock AgentCore Gateway 配置详细日志以捕获策略评估详细信息

1.  **查看 X-Ray 跟踪**-检查 AWS X-Ray 跟踪以确定授权检查失败的地方

1.  从 **LOG\_ONLY 模式开始**-最初使用 LOG\_ONLY 模式在不阻塞请求的情况下测试 Cedar 策略

1.  **验证所有四个权限**-确保`AuthorizeAction``PartiallyAuthorizeActions`、和 AN `GetPolicyEngine` D 都存在

1.  **切换到强制模式**-仅在 LOG\_ONLY 模式下验证所有权限均有效后，才切换到强制模式

## 示例：创建两个 IAM 角色
<a name="policy-permissions-example"></a>

以下示例演示如何使用 AWS CLI 创建两个必需的 IAM 角色。

### 步骤 1：创建网关执行角色
<a name="policy-permissions-example-execution"></a>

```
# Create the trust policy file
cat > gateway-trust-policy.json <<EOF
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}
EOF

# Create the IAM role
aws iam create-role \
  --role-name MyGatewayExecutionRole \
  --assume-role-policy-document file://gateway-trust-policy.json
```

### 步骤 2：为网关执行角色添加权限
<a name="policy-permissions-example-attach"></a>

```
# Create the permission policy file
cat > gateway-permissions.json <<EOF
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}
EOF

# Attach the policy to the role
aws iam put-role-policy \
  --role-name MyGatewayExecutionRole \
  --policy-name GatewayPolicyEnginePermissions \
  --policy-document file://gateway-permissions.json
```

**注意**  
此示例仅显示 AgentCore 权限中的策略。应根据您的特定集成要求为亚马逊 Bedrock AgentCore Gateway 目标（Lambda、API Gateway 等）添加其他权限。

### 步骤 3：后续步骤
<a name="policy-permissions-example-next"></a>

使用所需的策略 AgentCore 权限配置执行角色后，继续创建和配置策略资源。有关详细指导，请参阅：
+ 创建策略引擎-请参阅[创建策略引擎](policy-create-engine.md) 
+ 撰写 Cedar 政策——参见 [Cedar 政策语言参考](https://docs.cedarpolicy.com) 

## 最佳实践
<a name="policy-permissions-best-practices"></a>

1.  **使用单独的角色**-为 Amazon Bedrock AgentCore Gateway 的执行和资源管理保持不同的角色

1.  **应用最低权限**-从特定的资源 ARN 开始，而不是在生产环境中使用通配符

1.  **使用 LOG\_ONLY 模式进行测试**-在实施策略之前，请务必在 LOG\_ONLY 模式下测试策略引擎集成

1.  **启用监控**-为故障排除和可观察性配置 CloudWatch 日志和 X-Ray 跟踪

1.  **版本控制策略-将** Cedar 策略与基础架构代码一起存储在版本控制中

1.  **使用资源标签**-应用标签来组织和管理资源中的 AgentCore Amazon Bedrock AgentCore Gateway 和策略

1.  **定期安全审计**-定期审查 IAM 政策，确保它们遵循最低权限原则