将 Amazon Bedrock AgentCore 网关连接到私有 API 的中心检查枢纽-辐射网络

媒体报道 AWS 机器学习 原文语言:英文

本文介绍了在企业中心防火墙环境下,使用 VPC Lattice 资源网关将 Amazon Bedrock AgentCore Gateway 安全地连接到私有 API 与 MCP 服务器的实现方案,提供了六步配置与验证要点。

全文

将 Amazon Bedrock AgentCore 网关连接到中心检查的枢纽-辐射网络中的私有 API

在许多企业中,中央网络团队拥有每个虚拟私有云(VPC)和子网,并且 VPC 之间的每个流量都必须在两个方向上通过中央防火墙。通过 Amazon Bedrock AgentCore 网关(Amazon Bedrock AgentCore 的一项功能)调用内部 REST API 和模型上下文协议(MCP)服务器的代理必须满足相同的两个要求。Amazon Bedrock AgentCore 是一个平台,可在规模上构建、连接和优化代理,支持任何框架或模型。

本文展示了一种满足这两个要求的模式。网络团队保持对每个子网的所有权,网关与您的私有 API 和 MCP 服务器之间的流量在两个方向上都经过中央防火墙。本文涵盖了放置 Amazon VPC Lattice 资源网关的位置,该网关用于让网关访问私有目标。还说明了每个部分的所有者、六项配置决策以及确认该模式有效的检查。

我们在美国东部(弗吉尼亚北部)AWS 区域(us-east-1)的一间实验室中使用三个成员账户和一个 AWS Organizations 管理账户构建并测试了该模式。AWS CloudFormation 模板、测试脚本、测试证据以及参考材料(地址规划、完整验证检查、故障排除、配额)均在伴随的代码库中。请将该模式作为指南,并根据您自己的账户架构进行调整。

本文使用的术语

资源网关:Amazon VPC Lattice 进入 VPC 的入口点:您选择的子网中的弹性网络接口(ENI)。后端将其地址视为每个连接的来源。

资源配置:VPC Lattice 对象,为资源网关后面的一个后端(此处为内部负载均衡器或 VPC 端点 DNS 名称和端口)命名。您可以通过 AWS 资源访问管理器(AWS RAM)与其他账户共享它。

托管模式和自托管模式:网关目标的两种私有端点选项。托管模式下,AgentCore 为您创建资源网关。自托管模式下,您自行创建资源网关并为目标提供资源配置。

何时使用此模式

当且仅当满足以下所有条件时使用此模式:

网络账户拥有每个 VPC、子网和 AWS Transit Gateway 附加,并通过 AWS RAM 共享应用子网。

检查 VPC 中的中央防火墙必须检查进入和离开每个 VPC 的流量。

应用团队仅管理自己的资源和安全组。

否则,表 1 中的其他选项更适合。

表 1:何时其他选项更适合。

您的环境 使用情况

网关账户可以拥有可达您工具的子网 托管模式

网关与工具之间的流量不需要中央检查 如文档所述的自托管模式

工具可通过公共端点访问 标准网关目标

我们还考虑了 AgentCore 拥有的子网中的托管模式、每个工具 VPC 或中心端点 VPC 中的资源网关,以及每个工具的面向互联网的负载均衡器加 AWS WAF。备选方案的说明解释了在这些约束下每种方案为何不足。

集中检查的设计要求

网络账户拥有每个子网。网关和应用账户仅在通过 AWS RAM 共享给它们的子网中构建。

每个 VPC 之间的流量在两个方向上都要经过中央防火墙。检查 VPC 中的中央防火墙检查网关与您的私有 API 和 MCP 服务器之间的流量。

AgentCore 网关通过 VPC Lattice 资源网关访问私有目标,两种私有端点模式的放置位置不同。托管模式在网关账户中创建资源网关,适用于该账户可以拥有其运行子网的环境。自托管模式(如文档所述)将其放置在直接访问后端的子网中,适用于不需要在网关与工具之间进行检查的环境。此环境需要同时满足这两个条件,因此该模式使用自托管模式并进行一次更改。网络账户拥有资源网关并将其放置在通过 AWS Transit Gateway 路由的子网中,从而使每个请求和响应都经过检查 VPC。

解决方案概述

为资源网关在网络账户中分配专属的 VPC 和子网。不要共享它们,并保持后端不在其中。通过传输网关路由它们,使得 VPC 之间的每个请求和响应都经过防火墙。通过 AWS RAM 与 AgentCore 账户共享每个后端的一个资源配置。图 1 显示了账户、VPC 和流量路径。

图 1:网络账户拥有所有 VPC 和资源网关。其他账户仅拥有它们放置在共享子网中的资源。实线表示双向穿过防火墙的流量。步骤编号对应以下流量路径。

流量路径

代理位于没有互联网路由的共享子网中,调用网关 URL。网关接口端点的私有 DNS 在代理的 VPC 内解析该地址。

如果附加了 AWS WAF,则对请求进行评估。网关检查其资源策略和入站 JSON Web Token(JWT),然后选择目标和工具。

网关为工具账户获取出站 OAuth 令牌,并通过 VPC Lattice 将请求发送到网络账户中的资源网关。

资源网关子网路由到传输网关,传输网关将流量通过检查 VPC 发送到工具账户的内部应用负载均衡器(ALB)或 execute‑api 端点。(穿过防火墙。)

ALB 或 Amazon API Gateway 验证令牌并将请求转发到后端。

响应以相同方式返回。(穿过防火墙。)

网关流量如何在 AgentCore 账户没有传输网关附件的情况下进入网络账户的 VPC?当您创建目标时,AgentCore 将共享资源配置关联到其自己的 VPC Lattice 服务网络。VPC Lattice 随后将来自该服务网络的连接传递到您 VPC 中资源网关的网络接口。AWS 负责此跳转,之后由您的路由和防火墙接管。

此模式不实现的功能。采用之前请将这些限制与您的需求对照:

无负载检查——流量在网关到 ALB 之间采用端到端 TLS,网关验证证书。防火墙只能看到流量元数据和 TLS 服务器名称指示(SNI),看不到负载。请求内容记录在网关、AWS WAF 和 ALB 日志中。

部分链路跳过防火墙——代理到接口端点的链路以及网关到资源网关的链路均不经过防火墙。AgentCore 向每个身份提供商发出的令牌请求也不经过防火墙。

工具端没有终端用户身份——使用客户端凭证授权时,所有到达工具的调用都携带网关的客户端身份。要追踪调用来源,请在网关应用日志中使用入站 JWT 声明。

所有权分配

表 2:各方创建内容。

一次性 新 API 在已连接的 ALB 上 新 ALB 或工具账户

网络团队 资源网关及其 VPC、子网和路由。防火墙规则。工具 VPC 到传输网关的默认路由,用于 ALB 的签名密钥获取。网关接口端点和策略。AWS RAM 共享。无 仅向共享添加一个资源配置。如有新范围则添加防火墙规则

工具团队 为 AgentCore 团队使用的目标主机名匹配的 ALB 证书(包含主题备用名称) 在其 ALB 上的监听规则(带 jwt 验证) 内部 ALB 与安全组,以及用于网关的应用客户端(客户端凭证授权,范围如 tools/invoke)

AgentCore 团队 网关、入站授权器、资源策略、可选 AWS WAF 每个 API 或 MCP 服务器一个网关目标 一个目标,加上用于新身份提供商的 OAuth 凭证提供者

在已有目标上添加新操作或工具无需新目标:使用 UpdateGatewayTarget 更新 OpenAPI 规范,或对 MCP 服务器调用 SynchronizeGatewayTargets。仓库的构建顺序列出了每个账户的步骤以及团队之间传递的值。

先决条件

在 AWS Organizations 中拥有组织,并启用 AWS RAM 的资源共享。

AWS 命令行界面(AWS CLI)2.37.7 或更高版本,或用于 certificateConfigurations 参数的 AWS SDK for Python(Boto3)1.43.106 或更高版本。

对于创建 Gateway 目标的角色:vpc-lattice:GetResourceConfiguration、vpc-lattice:CreateServiceNetworkResourceAssociation、vpc-lattice:GetServiceNetworkResourceAssociation、vpc-lattice:ListServiceNetworkResourceAssociations 和 vpc-lattice:AssociateViaAWSService,以及 bedrock-agentcore 目标操作。如果您的组织目前未使用 VPC Lattice,请检查您的服务控制策略 (SCP)。

一个位于中央检查 VPC 中的防火墙,该 VPC 连接到启用了设备模式的传输网关(transit gateway)。

关键设计决策

这些代码片段是实验模板的摘录,并使用了实验的地址规划。RGW_NET 是资源网关子网(10.0.1.0/24–10.0.3.0/24),TOOL_NET 是工具 VPC(10.12.0.0/16),ALB_NET 是其中的 ALB 子网。

决策 1:将资源网关放在网络账户中的专用 VPC 内

在网络账户中为资源网关创建一个专用 VPC,使用不共享的子网,且没有中央端点或后端。将这些子网路由到传输网关。每个信任域保留一个资源网关。

ResourceGateway: Type: AWS::VpcLattice::ResourceGateway Properties: Name: hub-resource-gateway VpcIdentifier: !Ref ResourceGatewayVpc SubnetIds: [!Ref RgwSubnetA, !Ref RgwSubnetB, !Ref RgwSubnetC] SecurityGroupIds: [!Ref RgwSg] # egress 443 to application ranges only IpAddressType: IPV4 RgwRouteToTgw: Type: AWS::EC2::Route Properties: RouteTableId: !Ref RgwRouteTable DestinationCidrBlock: 10.0.0.0/8 # internal ranges go to the transit gateway TransitGatewayId: !Ref Tgw

仅与 AgentCore 一起使用时,资源网关每个子网消耗一个 IP 地址,因此小子网就足够了。创建后有两个设置无法更改:Ipv4AddressesPerEni 和 ResourceConfigDnsResolution,因此请提前选择。使用 VPC Lattice 和您的 AgentCore 功能支持的可用区 ID。实验布局列出了 us-east-1 的这些可用区。

决策 2:为每个负载均衡器创建一个资源配置,并通过 AWS RAM 进行共享

将资源配置指向内部 ALB DNS 名称,并将其与 AgentCore 账户共享。名称不要以 rcfg- 开头,该前缀由 VPC Lattice 保留。

ToolsResourceConfig: Type: AWS::VpcLattice::ResourceConfiguration Properties: Name: tools-account-a ResourceConfigurationType: SINGLE ResourceGatewayId: !Ref ResourceGateway ProtocolType: TCP PortRanges: ["443"] ResourceConfigurationDefinition: DnsResource: DomainName: internal-tools-alb-1234567890.us-east-1.elb.amazonaws.com IpAddressType: IPV4 ShareToAgentCore: Type: AWS::RAM::ResourceShare Properties: Name: agentcore-resource-configs AllowExternalPrincipals: false Principals: [""] ResourceArns: [!GetAtt ToolsResourceConfig.Arn]

VPC Lattice 提供到资源配置域的连接。AgentCore 发送目标 URL 的主机名(例如 tools.example.internal)作为 SNI,并针对该主机名检查 ALB 证书。证书的主题备用名称必须与该主机名匹配。该主机名不需要在 DNS 中解析。

对于私有 API Gateway REST API,将一个资源配置指向网络账户的 execute-api 接口端点。每个 API 的目标使用其自己的 URL,并且每个 API 的资源策略必须通过 aws:SourceVpce 允许该端点。在我们的测试中,另一个账户中的第二个 API 通过相同的资源配置正常工作,而无需进行任何网络更改。

决策 3:仅通过防火墙传递所需的数据流

您的防火墙需要两个有状态的允许规则:从资源网关子网到工具 VPC 的 443 端口,以及从 ALB 子网到身份提供商主机名的 443 端口。基于会话的防火墙会传递允许的数据流的回复。在实验中,我们使用了带有严格规则顺序以及默认操作 Drop established 和 Alert established 的 AWS Network Firewall。使用这些默认值时,防火墙会丢弃没有任何规则放行的客户端到服务器数据包,并放行回复,除非规则将其丢弃。规则顺序说明解释了其语义。

# Policy: RuleOrder STRICT_ORDER, StatefulDefaultActions [aws:drop_established, aws:alert_established] pass tcp $RGW_NET any -> $TOOL_NET 443 (msg:"resource gateway to tool VPC"; flow:to_server; sid:100001; rev:4;) pass tls $ALB_NET any -> any 443 (msg:"ALB to identity provider JWKS"; tls.sni; content:"cognito-idp.us-east-1.amazonaws.com"; nocase; startswith; endswith; flow:to_server; sid:100010; rev:2;)

第一条规则仅允许资源网关子网通过 443 端口访问工具 VPC。第二条规则允许 ALB 仅从 ALB 子网向身份提供商的主机名获取其身份提供商的签名密钥(JSON Web 密钥集,即 JWKS)。工具 VPC 需要一条通往传输网关的默认路由,以便此获取操作能够到达中央出口。如果您的身份提供商不是 Amazon Cognito,请替换主机名。在我们的测试中,如果没有这条规则,ALB 会返回 HTTP 500,并且代理会收到 MCP 调用失败的提示。

为了证明应答穿过了防火墙,我们在通行规则之前为应答方向添加了一条丢弃规则:

drop tcp $TOOL_NET 443 -> $RGW_NET any (msg:"PROOF return path blocked"; flow:to_client; sid:100098; rev:2;)

随后,工具调用一直挂起直至超时,防火墙记录了针对 sid 100098 的 to_client 丢弃信息。移除该规则后,调用恢复正常。请在您自己的防火墙上运行相同的测试。

决策 4:在内部 ALB 或私有 API 上验证工具账户的令牌

工具账户保留自己的身份提供商(实验中的 Amazon Cognito),并为网关创建一个应用客户端。在通往后端的每条路径上验证该客户端的令牌。

内部 ALB – 将侦听器的默认操作设为固定响应,并在每个转发规则上放置 jwt-validation 操作。将 client_id 锁定到网关的应用客户端,以便拒绝同一用户池中的其他客户端。

McpRule: Type: AWS::ElasticLoadBalancingV2::ListenerRule Properties: ListenerArn: !Ref Listener # default action: fixed-response 404 Priority: 10 Conditions: [{Field: path-pattern, PathPatternConfig: {Values: [/mcp]}}] Actions: - Type: jwt-validation Order: 1 JwtValidationConfig: Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${ToolPool} JwksEndpoint: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${ToolPool}/.well-known/jwks.json AdditionalClaims: - {Format: space-separated-values, Name: scope, Values: [tools/invoke]} - {Format: single-string, Name: client_id, Values: [!Ref GatewayAppClient]} - Type: forward Order: 2 TargetGroupArn: !Ref ToolsTargetGroup

在我们的测试中,没有令牌的目标、带有另一个身份提供商令牌的目标以及带有不同应用客户端令牌的目标,在后端运行之前都被 HTTP 401 拒绝。代理只能看到发生内部错误(An internal error occurred),因此请使用 ALB 访问日志来诊断令牌问题。

私有 REST API – API 密钥不会对调用者进行身份验证,因此请为每个方法添加一个授权方,例如具有所需作用域的 Cognito 用户池授权方(如实验中所示)。同时,将端点策略附加到 execute-api 端点,将其限制为批准账户拥有的 API。它控制端点可以访问哪些 API,而不是谁来调用它。授权方则用于控制调用者。

{"Statement": [{"Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": ["arn:aws:execute-api:us-east-1::*"]}]}

ALB 或端点安全组仅允许资源网关子网访问,因此资源网关是唯一的入站网络路径。如果您的防火墙应用了源 NAT,则安全组必须改为允许防火墙的地址,然后它会接受防火墙转发的任何内容。防火墙规则和令牌验证成为控制手段。

决策 5:创建引用共享资源配置的网关目标

创建一个带有 JWT 授权方的网关,并可选择创建一个 AWS WAF Web 访问控制列表(Web ACL),用于检查每个目标的工具调用参数。默认情况下,AWS WAF 仅检查正文的前 16 KB(可调整为 64 KB),因此请决定每个规则如何处理更大的正文。将 AWSManagedRulesSQLiRuleSet 添加到常用规则集中。请参阅 AWS WAF 说明。

除非配置了拦截器函数,否则具有私有端点的网关目标不能将 NO_AUTH 用于入站授权。

每个目标都需要一个 OAuth 凭据提供商,其中包含工具账户的应用客户端 ID 和密钥以及身份提供商的发现 URL:

# provider.json保存了客户端密钥,因此它不会出现在命令行和Shell历史记录中: # {"name": "tools-account-a", "credentialProviderVendor": "CustomOauth2", # "oauth2ProviderConfigInput": {"customOauth2ProviderConfig": { # "clientId": "", "clientSecret": "", # "oauthDiscovery": {"discoveryUrl": "https://cognito-idp..amazonaws.com//.well-known/openid-configuration"}}}} chmod 600 provider.json aws bedrock-agentcore-control create-oauth2-credential-provider --cli-input-json file://provider.json rm provider.json

如果ALB使用的是来自私有证书颁发机构(CA)的证书,还要将CA证书作为PEM字符串存储在AWS Secrets Manager密钥中。网关执行角色(你在创建网关时授予它的AWS身份和访问管理(IAM)角色)需要权限来读取该密钥以及凭据提供程序。

import boto3 agentcore = boto3.client("bedrock-agentcore-control", region_name="us-east-1") agentcore.create_gateway_target( gatewayIdentifier="", name="classifier", targetConfiguration={"mcp": {"mcpServer": {"endpoint": "https://tools.example.internal/mcp"}}}, credentialProviderConfigurations=[{ "credentialProviderType": "OAUTH", "credentialProvider": {"oauthCredentialProvider": { "providerArn": "", "scopes": ["tools/invoke"], "grantType": "CLIENT_CREDENTIALS"}}}], # 通过AWS RAM从网络账户共享 privateEndpoint={"selfManagedLatticeResource": { "resourceConfigurationIdentifier": ""}}, # 信任发布ALB证书的私有CA certificateConfigurations=[{"secretsManager": {"secretArn": ""}}], )

OpenAPI目标使用相同的代码块,但用openApiSchema替代mcpServer。若要轮换CA,请更新密钥并调用UpdateGatewayTarget。现有连接可以保留旧的信任材料最多15分钟。

保持网关作为共享资源配置的唯一消费者。AWS RAM的AWS托管权限还会授予ec2:CreateVpcEndpoint权限,因此AgentCore账户可以通过其自己的资源VPC终端节点或服务网络访问后端。客户托管权限无法解决此问题:AWS RAM会在其中一个中拒绝vpc-lattice:AssociateViaAWSService,并且没有它,网关目标将会失败。请改为向AgentCore账户附加SCP:

{"Version": "2012-10-17", "Statement": [ {"Sid": "NoOwnEndpointsToSharedResourceConfigurations", "Effect": "Deny", "Action": "ec2:CreateVpcEndpoint", "Resource": "arn:aws:vpc-lattice:*:*:resourceconfiguration/*"}, {"Sid": "ServiceNetworkAssociationsOnlyThroughAwsServices", "Effect": "Deny", "Action": "vpc-lattice:CreateServiceNetworkResourceAssociation", "Resource": "*", "Condition": {"BoolIfExists": {"aws:ViaAWSService": "false"}}}]}

通过此SCP,我们尝试创建自己的资源VPC终端节点和服务网络关联遭到拒绝,而新的网关目标仍然达到了READY状态。SCP不适用于管理账户,因此请勿在其中运行AgentCore。在网络账户中,使用匹配AWS CloudTrail事件CreateServiceNetworkResourceAssociationBySharee的Amazon EventBridge规则对意外关联进行告警。

通过首先删除网关目标(或服务网络资源关联),然后从共享中移除资源配置来撤销访问权限。仅从共享中移除它并不会删除现有的关联。

决策6:以私有方式访问网关,并关闭公共终端节点

在启用了私有DNS的共享代理VPC中创建网关接口终端节点,并附加一个列出已批准网关的终端节点策略。主体(principal)必须是*,因为网关使用承载令牌(bearer tokens)对调用者进行身份验证。资源列表是控制项。

{"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Principal": "*", "Action": "bedrock-agentcore:InvokeGateway", "Resource": ["arn:aws:bedrock-agentcore:us-east-1::gateway/"]}]}

在我们的测试中,通过同一终端节点调用的第二个网关返回了JSON-RPC错误-32002 Insufficient permissions,但其公共终端节点仍然进行了响应。

接口终端节点并不会关闭网关的公共终端节点。附加一个资源策略:仅当aws:SourceVpce是你的终端节点时才允许bedrock-agentcore:InvokeGateway,否则拒绝(完整策略在代码仓库中)。在我们的测试中,应用该策略约30秒后,互联网调用返回了-32002错误,而终端节点调用继续正常工作。AWS指出策略更改最多可能需要15分钟生效。

没有互联网路由的代理仍然需要其入站 JWT。为其提供通往其身份提供商令牌端点的路径,例如通往中转网关的路由以及范围类似于决策 3 中 JWKS 规则的防火墙规则。或者,使用私有身份提供商。

在您的环境中验证该模式

在依赖该模式之前,请在网络账户的非生产副本中使用您自己的防火墙运行这些检查。完整的 14 项检查清单、每项检查的运行方法以及我们看到的运行结果都位于代码库中,同时还包含每个跃点的日志源。

请求来自资源网关 – ALB 访问日志显示源 IP 位于资源网关范围内(如果应用了源 NAT,则位于防火墙范围内)。

请求穿过防火墙 – 防火墙流日志显示从资源网关地址到工具账户上 443 端口的 TLS 流。

回复穿过防火墙 – 在实施了回复方向丢弃规则(决策 3)的情况下,调用会失败,并且防火墙会记录 to_client 丢弃。

ALB 和私有 API 是令牌边界 – 没有令牌或带有其他客户端令牌的目标会收到 HTTP 401 且不会调用后端。

公共网关端点已关闭 – 附加资源策略后,互联网调用会收到 -32002 且端点调用会成功。

如果检查失败或代理收到通用错误,故障排除指南会将每个症状映射到显示原因的日志。

注意事项

成本:每个 VPC Lattice 服务网络资源关联都会产生按小时计算的费用以及数据处理费。请参阅 VPC Lattice 定价。请按每个目标一个关联进行规划。要查看您的目标创建了多少关联,请比较 GetGatewayTarget 为每个目标返回的 resourceAssociationArn,并且每个 API 或 MCP 服务器最好只对应一个目标,而不是许多小型目标。

流向公共端点的流量:有三个调用离开私有路径:ALB 的 JWKS 获取、代理的入站令牌请求,以及 AgentCore 发往每个身份提供商的出站 OAuth 令牌请求。

账户布局与配额:网关工具调用配额既适用于每个账户,也适用于每个网关。每个环境使用一个 AgentCore Account,并在达到限制之前,按域或代理组拆分网关。VPC Lattice 会关闭空闲连接,因此对于长寿命的 MCP 流,请使用保持活动(keepalive)机制。代码库中列出了其他配额。

我们的测试范围:我们使用了 AWS Network Firewall、无源 NAT,并且仅限 us-east-1。源 NAT、多区域、私有身份提供商和 OpenAPI 限制在其他注意事项中进行了介绍。

结论

当您的网络团队拥有每个子网,并且 VPC 之间的每个流都必须通过中央防火墙时,请将 VPC Lattice 资源网关放置在网络账户中,并将其子网通过中转网关进行路由。网络团队只需设置一次入口点,并为每个后端负载均衡器添加一个资源配置。应用程序团队只需继续拥有其负载均衡器、安全组、身份提供商和网关目标,并且 AWS WAF 可以从每个工具的公有负载均衡器转移到网关。在依赖该模式之前,请在您自己的环境中运行验证检查。

正文为 AI 译文。

参考来源

← 返回每日AI报告