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

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

本指南提供了使用带有策略的 Amazon Bedrock G AgentCore ateway 所需的 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 操作，而资源管理角色需要在资源中配置和管理 Amazon Bedrock AgentCore Gateway 和策略的 AgentCore 权限。

网关执行角色

网关执行角色由 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，并且默认情况下，即使您配置了许可策略，所有工具调用也将被拒绝。

信任策略

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

重要

替换以下占位符：

us-east-1与该 Amazon 地区合作
123456789012使用 Amazon 账户 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:*"
        }
      }
    }
  ]
}

权限策略

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

重要

替换以下占位符：

us-east-1与该 Amazon 地区合作
123456789012使用 Amazon 账户 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>"
      ]
    }
  ]
}

注意

网关目标除此之外还需要自己的权限，而且这些权限因目标类型而异。有关每种类型所需的权限，请参阅访问 Amazon 资源的权限。
在生产环境中，使用特定的资源 ID 替换占位符，例如policy-engine/my_policy_engine-a1b2c3d4e5代替policy-engine/<policy-engine-id>，以遵循最低权限原则。仅在您打算允许该类型的所有资源的地方使用通配符 (*)。

临时策略的 IAM 权限

临时策略要求网关通过铸造工作负载访问令牌 (WAT) 在请求中传播调用者的会话身份。在 Amazon 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>*"
  ]
}

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

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

资源管理角色

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

重要

除了列表之外，还授予四个摘要操作并获取操作：ListPolicyEngineSummariesGetPolicyEngineSummary、ListPolicySummaries、和GetPolicySummary。这些操作允许您在客户托管密钥不可用时枚举策略引擎和策略。提前给予他们是使这种恢复成为可能的原因。有关更多信息，请参阅密钥不可用：您无法列出或阅读您的政策。

有关授予完全访问权限的托管策略 AgentCore，请参阅 Amazon Bedrock AgentCore 的Amazon 托管策略。有关加密策略引擎额外需要的 Amazon KMS 权限，请参阅自定义策略引擎的加密。

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

此角色独立于网关执行角色，只有在 AgentCore 配置中设置或修改 Amazon Bedrock AgentCore Gateway 和策略时才需要。

权限策略

重要

替换以下占位符：

us-east-1与该 Amazon 地区合作
123456789012使用 Amazon 账户 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",
        "bedrock-agentcore:ListPolicyEngineSummaries",
        "bedrock-agentcore:GetPolicyEngineSummary"
      ],
      "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",
        "bedrock-agentcore:ListPolicySummaries",
        "bedrock-agentcore:GetPolicySummary"
      ],
      "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 策略范围的授权检查。

注意

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

什么时候需要更新角色？

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

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

状态：需要操作

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

场景 2：自定义执行角色

状态：需要操作

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

场景 3：生产 Least-Privilege 配置

状态：需要操作

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

问题排查

本节介绍使用策略为 Amazon 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 w Insufficient permissions to call gateway with ID <gateway-id> ith，即使网关执行角色具有AuthorizeActionPartiallyAuthorizeActions、和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>"
  ]
}

仅限日志模式下的静默失败

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

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

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

未找到策略引擎错误

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

注意

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

调试技巧

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

示例：创建两个 IAM 角色

以下示例演示如何使用 Amazon 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 AgentCore Gateway 目标（Lambda、API Gateway 等）添加其他权限。

步骤 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。请参阅浏览器的帮助页面以了解相关说明。

核心概念

创建策略引擎