概述网关执行角色资源管理角色何时需要更新角色？问题排查示例：创建两个 IAM 角色最佳实践

AgentCore AgentCore IAM 权限中的网关和策略

本指南提供了使用 Amazon Bedrock G AgentCore ateway 和 Policy 中的 IAM 权限来使用 Cedar 策略 AgentCore 进行细粒度的授权控制。

概述

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

网关执行角色 -Amazon Bedrock AgentCore Gateway 在运行时为调用目标和评估 Cedar 策略而承担的 IAM 角色
资源管理角色 -管理员用于在资源中创建和管理 Amazon Bedrock AgentCore Gateway 和策略的 IAM 角色 AgentCore

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

网关执行角色

网关执行角色由亚马逊基岩 AgentCore 网关服务在处理请求时代替。此角色需要以下权限：

通过政策评估雪松政策 AgentCore
调用 Lambda 函数和 API 网关终端节点等目标
将日志和跟踪写入 CloudWatch 和 X-Ray
身份验证配置的访问密钥

重要

执行角色必须包含这三项权限才能在以下位置使用带有策略的亚马逊基岩 AgentCore 网关 AgentCore：。bedrock-agentcore:AuthorizeAction-评估授权决策的 Cedar 政策。bedrock-agentcore:PartiallyAuthorizeActions-列出来电者有权调用的工具。bedrock-agentcore:GetPolicyEngine-检索策略引擎配置如果没有这些权限，网关将无法执行策略授权。这表现为两种方式：将策略引擎连接到现有网关将导致，默认情况下 InternalServerException，即使您配置了许可策略，所有工具调用也将被拒绝。

信任策略

网关执行角色必须信任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:*"
        }
      }
    }
  ]
}

权限策略

该政策授予亚马逊 Bedrock AgentCore Gateway 通过中的 AgentCore政策评估 Cedar 政策所需的权限。按照最低权限原则，权限分为两个语句。

重要

将以下占位符替换：* us-east-1 使用 AWS 区域 * 123456789012 使用 AWS 账户 ID * <gateway-id> 和网关 ID（或对所有网关使用 *）* <policy-engine-id> 替换为策略引擎 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>）以遵循最低权限原则，或使用通配符 (*) 来允许访问该类型的所有资源。

临时策略的 IAM 权限

临时策略要求网关通过铸造工作负载访问令牌 (WAT) 在请求中传播调用者的会话身份。在 AWS IAM的入站流量上，这是 mint 调用GetWorkloadAccessToken。授予网关执行角色bedrock-agentcore:GetWorkloadAccessToken，范围限于网关的工作负载身份目录。除了本页已记录的三种策略权限（AuthorizeAction、PartiallyAuthorizeActions、GetPolicyEngine）外，还要添加此权限。仅当临时策略处于活动状态（提供策略会话 ID 并连接策略引擎）时，才需要此权限；禁用临时策略时不需要此权限。

将以下语句添加到网关执行角色权限策略中：


{
  "Sid": "PolicySessionWorkloadIdentity",
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:GetWorkloadAccessToken"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/<gatewayId>*"
  ]
}

如果没有此权限，启用临时策略后，工具调用将在代币铸造步骤（开AccessDenied启GetWorkloadAccessToken）失败。对于生产环境，请<gatewayId>使用特定的网关 ID 替换，以遵循最低权限原则。

有关临时策略注意事项背景下此要求的概述，请参阅所需的 IAM 权限。

资源管理角色

管理员使用资源管理角色在 AgentCore 资源中创建和管理 Amazon Bedrock AgentCore Gateway 和策略。此角色需要以下权限：

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

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

权限策略

重要

将以下占位符：* 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 策略，而不仅仅是在运行时调用网关。CreatePolicy并UpdatePolicy验证您在 Cedar 声明中针对网关的操作，该操作已在 Gateway ARN InvokeGateway 上获得授权。没有它，政策就会过渡到 CREATE_FAILED with Insufficient permissions to call gateway with ID <gateway-id>。

重要

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

注意

虽然为了保持一致性而包括了资源字段，但这些仅限权限的操作主要是在操作级别而不是资源级别上设置权限的。

何时需要更新角色？

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

场景 1：使用 AgentCore CLI 创建的网关

状态：需要采取行动

AgentCore CLI 创建网关执行角色，该角色具有目标调用和出站身份验证的限定权限，但权限中 AgentCore 不包含 Policy。您必须手动将本指南中记录的AuthorizeActionPartiallyAuthorizeActions、和GetPolicyEngine权限添加到网关执行角色中。

场景 2：自定义执行角色

状态：需要采取行动

自定义 IAM 角色需要手动添加本指南中记录的 AgentCore 权限策略。请遵循上述部分中的权限政策。

场景 3：生产 Least-Privilege 配置

状态：需要采取行动

对于生产环境，将策略的范围 AgentCore 限定为特定资源 ARN，而不是使用通配符。将策略引擎/*和网关/*替换为权限策略中的特定策略引擎和网关 ID。

问题排查

本节介绍在策略中为亚马逊 Bedrock AgentCore Gateway 配置 IAM 权限时的常见问题。 AgentCore

InternalServerException 在政策评估期间

症状：将策略引擎连接到现有网关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

症状：CreatePolicy返回 apolicyId，但策略随后会转换CREATE_FAILED为 Insufficient permissions to call gateway with ID <gateway-id> with，即使网关执行角色有AuthorizeActionPartiallyAuthorizeActions、和GetPolicyEngine。

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

解决方案：向资源管理角色添加bedrock-agentcore:InvokeGateway（范围限于网关 ARN）：


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

LOG_ONLY 模式下的静默故障

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

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

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

未找到策略引擎错误

症状：亚马逊 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>"
]

注意

两者都AuthorizeActionPartiallyAuthorizeActions需要访问策略引擎和网关资源。

调试技巧

启用 CloudWatch 日志 -为 Amazon Bedrock AgentCore Gateway 配置详细日志，以捕获策略评估的详细信息
查看 X-Ray 跟踪 -检查 AWS X-Ray 跟踪以确定授权检查失败的地方
从 LOG_ONLY 模式开始 -最初使用 LOG_ONLY 模式在不阻止请求的情况下测试 Cedar 策略
验证所有四个权限 -确保AuthorizeActionPartiallyAuthorizeActions、AN GetPolicyEngine D 都存在
切换到强制模式 -只有在验证所有权限均在 LOG_ONLY 模式下工作后，才切换到强制模式

示例：创建两个 IAM 角色

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

步骤 1：创建网关执行角色


# 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：为网关执行角色附加权限


# 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 Gatew AgentCore ay 目标（Lambda、API 网关等）添加其他权限。

第 3 步：后续步骤

使用所需的策略 AgentCore 权限配置执行角色后，继续创建和配置策略资源。有关详细指导，请参阅：

创建策略引擎-请参阅创建策略引擎
撰写 Cedar 政策-参见 Cedar 政策语言参考

最佳实践

使用单独的角色 -在 Amazon Bedrock AgentCore Gateway 执行和资源管理中保持不同的角色
应用最低权限 -在生产环境中从特定的资源 ARN 开始，而不是通配符
使用 LOG_ONLY 模式进行测试 -在强制执行策略之前，请务必在 LOG_ONLY 模式下测试策略引擎集成
启用监控 -为故障排除和可观察性配置 CloudWatch 日志和 X-Ray 跟踪
版本控制策略 -将 Cedar 策略与基础设施代码一起存储在版本控制中
使用资源标签 -应用标签来组织和管理资源中的 AgentCore Amazon Bedrock AgentCore Gateway 和政策
定期安全审计 -定期审查 IAM 政策，确保它们遵循最低权限原则

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

核心概念

创建策略引擎