本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
为 AgentCore 网关目标配置 Amazon Bedrock Gateway VPC 出口
AgentCore 网关服务为您的应用程序提供安全和可控的出口流量管理,从而实现与虚拟私有云 (VPC) 内资源的无缝通信。本文档概述了出口流量如何通过 AgentCore 网关流向 VPC 资源。您将通过 AgentCore 运行时了解支持的网关目标类型(Lambda、API Gateway 和 MCP 服务器)、它们的配置要求以及每种目标类型支持的身份验证方法。本指南涵盖了在保持网络隔离和在整个架构中遵循最低权限原则的同时实现正确的出口流量所需的安全注意事项、路由机制和最佳实践。
MCP
AgentCore Gateway 支持将模型上下文协议 (MCP) 服务器作为目标端点,提供灵活的部署选项以满足各种客户需求。MCP 服务器可以通过多种方式进行配置,具体取决于您的基础架构需求和安全要求。
你的 MCP 目标可能有两种类型,不是托管在 AgentCore AgentCore 运行时或网关上托管。我们将在下面讨论这两个问题。
MCP 未托管在 AgentCore
AgentCore Gateway 支持使用由 Amazon VPC Lattice 提供支持的私有终端节点连接到在您的 VPC 内运行的自托管 MCP 服务器。您可以在网关目标privateEndpoint上配置,以私密方式将流量路由到您的 MCP 服务器,而无需将其暴露给公共互联网。
以下示例使用托管莱迪思创建私有 MCP 服务器目标:
{ "name": "my-private-mcp-target", "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0abc123def456", "subnetIds": ["subnet-0abc123", "subnet-0def456"], "endpointIpAddressType": "IPV4", "securityGroupIds": ["sg-0abc123def"] } }, "targetConfiguration": { "mcp": { "mcpServer": { "endpoint": "https://my-mcp-server.internal.example.com/mcp" } } } }
如果您想通过 VPC 终端节点或内部负载均衡器等中间组件路由流量,则可以指定routingDomain。有关更多信息,请参阅通过中间域路由流量。
如果您的 MCP 服务器使用私有证书颁发机构颁发的 TLS 证书,则可以将网关配置为直接信任该 CA。有关更多信息,请参阅 Connect 到使用私有证书颁发机构的目标。
有关莱迪思自我管理、跨账户设置和高级配置,请参阅使用 VPC Lattice 连接您的 VPC 中的私有资源。
AgentCore 运行时或网关
AgentCore Runtime 为通过托管基础设施方法与 VPC 内的资源进行通信提供原生支持。 AgentCore Gateway 和 AgentCore Runtime 之间的所有通信都保持在 Amazon 主干网上,确保您的数据永远不会通过公共互联网(对中国数据中心的跨区域呼叫除外)。有关更多信息,请参阅 Amazon VPC 常见问题中的连接
对于从 AgentCore Gateway 到 AgentCore Runtime 的出站授权,支持两种身份验证方法:无授权(不建议用于生产用途)和使用客户端凭据授予的 OAuth(用于机器对机器身份验证)。如果未配置授权,则从 AgentCore Gateway 到 AgentCore Runtime 的请求没有身份验证令牌。这种架构提供了无缝连接路径,同时保持了安全隔离。作为安全最佳实践,请为 AgentCore Runtime 和 AgentCore Gateway 配置限制性的身份验证和授权权限,将访问权限限制为仅访问特定用例所需的必要资源和操作。要将 OAuth 身份配置为由 AgentCore Gateway 用于出站和 AgentCore 运行时入口,请使用以下文档:
CreateGatewayTarget 以 AgentCore Runtime 为目标的示例
以下示例说明如何使用 AgentCore Runtime 创建网关目标:
POST /gateways/gatewayIdentifier/targets/ HTTP/1.1 Content-type: application/json { "clientToken": "string", "credentialProviderConfigurations": [ { "credentialProvider": { "oauthCredentialProvider": { "providerArn": "string", "scopes": [ "string" ], ... } }, "credentialProviderType": "OAUTH" } ], "description": "string", "metadataConfiguration": { "allowedQueryParameters": [ "string" ], "allowedRequestHeaders": [ "string" ], "allowedResponseHeaders": [ "string" ] }, "name": "string", "targetConfiguration": { "mcp": { "mcpServer": { "endpoint": "https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<runtime-id>/invocations?qualifier=DEFAULT&accountId=<account-id>" } } } }
注意
避免将 VPC 终端节点 (VPCE) URL 与一起使用privateEndpoint,以防止不必要的额外网络跳跃。改用直接 AgentCore Runtime 端点,流量保持在 Amazon 主干网上。
开放 API 目标
通过 Open API 目标的 API Gateway 端点
如果您的 API 网关无法直接添加为目标,则可以随时将资源导出为 OpenAPI 规范,并将该规范作为 OpenAPI 目标导入 AgentCore 网关。
如果你在 API Gateway 中有私有 REST API,请按照以下说明进行操作:API G ateway 中的私有 REST API。
其他端点
您可以使用配置将 Open API 目标privateEndpoint配置为访问您的 VPC 内的私有终端节点。 AgentCore Gateway 使用 Amazon VPC Lattice 与您的终端节点建立私有连接,而无需将其暴露给公共互联网。
以下示例使用托管莱迪思创建了一个私有的 OpenAPI 目标:
{ "name": "my-private-openapi-target", "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0abc123def456", "subnetIds": ["subnet-0abc123", "subnet-0def456"], "endpointIpAddressType": "IPV4", "securityGroupIds": ["sg-0abc123def"] } }, "targetConfiguration": { "mcp": { "openApiSchema": { "inlinePayload": "<your OpenAPI spec JSON with server URL pointing to your private endpoint>" } } } }
如果您想通过 VPC 终端节点或内部负载均衡器等中间组件路由流量,则可以指定routingDomain。有关更多信息,请参阅通过中间域路由流量。
如果您的终端节点使用私有证书颁发机构颁发的 TLS 证书,则可以将网关配置为直接信任该 CA。有关更多信息,请参阅 Connect 到使用私有证书颁发机构的目标。
有关莱迪思自我管理、跨账户设置和高级配置,请参阅使用 VPC Lattice 连接您的 VPC 中的私有资源。
注意
该privateEndpoint配置适用于您的 OpenAPI 架构中的单个域。如果您的架构引用了具有不同域的多个服务器端点,请提交 S Amazon upport 案例privateEndpointOverrides。
Smithy 的目标
Smithy 目标目前不支持私有端点 (privateEndpoint) 配置。如果您的 Smithy 目标需要私有连接,请打开 Su Amazon pport 案例
API Gateway
AgentCore Gateway 支持 API Gateway 作为目标类型,它可以用作访问 VPC 资源的中间层。 AgentCore 网关特别支持仅使用区域端点配置的 REST API 网关。虽然目前无法通过网关进行直接 VPC 通信(此功能计划在将来的版本中推出),但网关通过 Amazon 主干网与 API Gateway 通信,确保流量永远不会通过公共互联网(对中国数据中心的跨区域调用除外)。然后,API Gateway 可以使用 VPC Link 与资源通信,从而为 AgentCore 网关创建一条在保持网络隔离的同时访问内部服务的安全路径。
要实施安全最佳实践,请将您的 API Gateway 配置为仅限 AgentCore 网关服务主体或配置的 API 密钥的入站流量,从而防止来自其他来源的未经授权的访问。对于从 AgentCore 网关到 API Gateway 的出站授权,仅支持两种 IAM-based 身份验证方法:身份验证(使用网关服务角色使用 Amazon 签名版本 4 进行身份验证)和 API 密钥身份验证(由 AgentCore 网关管理);API 网关目标不支持 OAuth-based 授权和跨账户 API 网关,请通过 Open API 目标使用 API 网关终端节点。将 AgentCore 网关执行角色权限限制为仅调用所需的特定 API Gateway 端点,而不是授予广泛的 API 网关访问权限,从而确保网关无法与意外的 API 资源进行交互,并在整个架构中保持最低权限原则。
Amazon API Gateway REST API 阶段作为目标
使用 IAM 身份验证集成 API Gateway 的权限
API Gateway 资源策略已锁定到 AgentCore 网关
以下资源策略限制 API Gateway 对网 AgentCore 关的访问:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "bedrock-agentcore.amazonaws.com" }, "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-west-2:111122223333:rest-api-id/api-stage/*/*" ], "Condition": { "ArnEquals": { "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/my-gateway-d4jrgkaske" } } } ] }
AgentCore 网关执行角色策略
以下策略向网关授予调用 API Gateway 的权限:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-west-2:111122223333:abcd123/prod/*/*" ] } ] }
AgentCore 网关执行角色信任策略
以下信任策略允许 AgentCore Gateway 担任执行角色:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "bedrock-agentcore.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnLike": { "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/*" } } } ] }
API Gateway 中的私有 REST API
本机不支持带有私有终端节点的 API Gateway 目标。但是,您可以将私有 API Gateway 导出为 OpenAPI 架构,然后使用带有该架构的开放 API 目标,配置为。privateEndpoint将设置为您的 routingDomain API Gateway VPC 终端节点 (VPCE) DNS 名称,并确保 OpenAPI 架构服务器 URL 使用的域名与您的公有 TLS 证书相匹配。
{ "name": "my-private-apigw-target", "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0123456789abcdef0", "subnetIds": ["subnet-0123456789abcdef0", "subnet-0abcdef1234567890"], "endpointIpAddressType": "IPV4", "routingDomain": "<vpce-id>.execute-api.<region>.vpce.amazonaws.com" } }, "targetConfiguration": { "mcp": { "openApiSchema": { "inlinePayload": "<OpenAPI spec JSON with server URL matching the public certificate domain for your API Gateway, for example https://<api-id>.execute-api.<region>.amazonaws.com>" } } } }
有关私有终端节点配置的更多详细信息,请参阅使用 VPC Lattice 连接您的 VPC 中的私有资源。
Lambda
AgentCore Gateway 支持 Lambda 目标作为其目标类型之一,从而允许无缝调用可与您的 VPC 内的资源通信的 Lambda 函数。此功能开箱即用,无需客户进行额外配置,网关可以立即调用已配置为 VPC 访问权限的 Lambda 函数来访问您的内部资源,例如数据库、API 或其他服务。为了维护安全最佳实践,强烈建议使用最低权限配置 AgentCore Gateway 执行角色,特别是将其限制为仅调用预期的 Lambda 函数,而不是授予广泛的 Lambda 执行权限。这种最低权限原则可确保网关或使用相同角色的任何其他调用方不会无意中调用意外的 Lambda 函数,从而减少您的安全攻击面并在您的环境中保持严格的访问控制。 Amazon
Connect 连接到使用私有证书颁发机构的目标
AgentCore 网关通过 TLS 出站连接到网关目标。默认情况下,网关仅信任公共证书颁发机构 (CA) 颁发的服务器证书。如果您的目标提供了私有(自定义)CA 颁发的 TLS 服务器证书,则可以向目标注册该私有 CA 证书。有关更多信息,请参阅先决条件和证书要求。然后,网关在连接到该目标时信任私有 CA。这是原生方法,因此您无需在目标前面放置内部 Application Load Balancer。
在创建或更新目标时,您可以将对 CA 证书的引用(而不是证书内容本身)附加到单个目标。这意味着证书内容永远不会出现在 API 请求中。相反,您可以引用存储在 PEM-encoded Amazon S3 或 S Amazon ecrets Manager 中的 CA 证书。当您创建或更新目标时,网关会获取、验证和加密 CA 证书。然后,它使用该证书作为该目标的出站 TLS 的信任锚点。
先决条件
在目标上注册私有 CA 证书之前,请确保满足以下条件:
-
目标使用由 Amazon VPC Lattice 提供支持的私有终端节点 (
privateEndpoint)。莱迪思托管和自行管理的VPC资源均符合资格。有关更多信息,请参阅使用 VPC Lattice 连接您的 VPC 中的私有资源。 -
目标为以下支持的类型之一:
-
MCP 服务器目标 ()
targetConfiguration.mcp.mcpServer -
OpenAPI 目标 ()
targetConfiguration.mcp.openApiSchema -
HTTP 代理(直通)目标 (
targetConfiguration.http.passthrough)
-
-
CA 证书符合证书要求中描述的要求。
证书要求
您注册的 CA 证书必须满足以下要求:
-
它必须是 PEM-encoded X.509 证书。
-
它必须是 CA 证书,并将 X.509 基本限制扩展设置为
CA:TRUE。网关拒绝叶子(终端实体)证书。 -
它必须在其有效期内。网关会在创建和更新时在目标验证期间检查证书的有效性。由于此验证是异步的,因此过期的证书会导致目标进入
FAILED状态(创建)或UPDATE_UNSUCCESSFUL状态(更新),而不是立即导致错误。有关更多信息,请参阅验证和行为。 -
PEM 文件(包括完整证书链)不得大于 16 KB。
-
如果您将证书存储在 Amazon S3 中,则 S3 对象必须与网关位于同一 Amazon 区域。
网关接受包含证书链的 PEM 文件。网关会记录文件中所有证书的最早到期时间 (notAfter)。
提供 CA 证书
您可以通过CreateGatewayTarget和UpdateGatewayTarget操作上的certificateConfigurations字段引用 CA 证书。该certificateConfigurations数组必须只包含一个条目。该条目必须正好设置以下来源之一。
-
s3 -
引用您存储在 Amazon S3 中的 PEM CA 证书。
-
uri(必需) -
证书对象的 S3 URI,格式为
s3://bucket/key.pem。 -
bucketOwnerAccountId(可选) -
存储桶所有者的 12 位 Amazon 账户 ID。Amazon S3 使用存储桶拥有者条件对照存储桶拥有者验证此值,因此该值必须与拥有该存储桶的账户相匹配。有关更多信息,请参阅《 Amazon 亚马逊简单存储服务用户指南》中的使用存储桶拥有者条件验证存储桶所有权。
-
-
secretsManager -
引用您存储在 S Amazon ecrets Manager 中的 PEM CA 证书。
-
secretArn(必需) -
密钥的 ARN。密钥必须是字符串密钥,而不是二进制密钥。
-
IAM 和 KMS 权限
网关使用网关执行角色获取 CA 证书。为该角色授予以下权限:
-
执行角色信任策略必须允许 AgentCore Gateway 服务代入该角色。
-
对于 Amazon S3 来源,请授予
s3:GetObjectCA 证书对象。 -
对于 S Amazon ecrets Manager 来源,请授予
secretsmanager:GetSecretValue该密钥。 -
如果 S3 对象或密钥使用密钥管理服务 (Amazon KMS) 中的客户托管密 Amazon 钥加密,则还要向执行角色授予使用该源密钥进行解密的权限。
网关获取并验证证书后,在存储证书之前,会使用自己的网关 Amazon KMS 密钥对证书进行加密。
示例请求
以下示例创建一个 MCP 服务器目标并引用您存储在 Amazon S3 中的 CA 证书。可选bucketOwnerAccountId标识拥有存储桶的账户。
{ "name": "my-private-mcp-target", "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0abc123def456", "subnetIds": ["subnet-0abc123", "subnet-0def456"], "endpointIpAddressType": "IPV4", "securityGroupIds": ["sg-0abc123def"] } }, "targetConfiguration": { "mcp": { "mcpServer": { "endpoint": "https://my-mcp-server.internal.example.com/mcp" } } }, "certificateConfigurations": [ { "s3": { "uri": "s3://my-ca-bucket/private-ca.pem", "bucketOwnerAccountId": "111122223333" } } ] }
以下示例创建了一个 OpenAPI 目标并引用了您存储在 S Amazon ecrets Manager 中的 CA 证书。
{ "name": "my-private-openapi-target", "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0abc123def456", "subnetIds": ["subnet-0abc123", "subnet-0def456"], "endpointIpAddressType": "IPV4", "securityGroupIds": ["sg-0abc123def"] } }, "targetConfiguration": { "mcp": { "openApiSchema": { "inlinePayload": "<your OpenAPI spec JSON with server URL pointing to your private endpoint>" } } }, "certificateConfigurations": [ { "secretsManager": { "secretArn": "arn:aws:secretsmanager:us-west-2:111122223333:secret:private-ca-AbCdEf" } } ] }
要替换现有目标上的 CA 证书,请调用UpdateGatewayTarget。您可以将网关和目标标识符指定为路径参数 (PUT /gateways/{gatewayIdentifier}/targets/{targetId});请求正文包含目标配置。以下示例将证书替换为存储在 S Amazon ecrets Manager 中的证书。
{ "name": "my-private-mcp-target", "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0abc123def456", "subnetIds": ["subnet-0abc123", "subnet-0def456"], "endpointIpAddressType": "IPV4", "securityGroupIds": ["sg-0abc123def"] } }, "targetConfiguration": { "mcp": { "mcpServer": { "endpoint": "https://my-mcp-server.internal.example.com/mcp" } } }, "certificateConfigurations": [ { "secretsManager": { "secretArn": "arn:aws:secretsmanager:us-west-2:111122223333:secret:private-ca-AbCdEf" } } ] }
要删除 CA 证书并将目标恢复为公共 CA 信任,请调用UpdateGatewayTarget并certificateConfigurations从请求中省略。您可以将网关和目标标识符指定为路径参数 (PUT /gateways/{gatewayIdentifier}/targets/{targetId});请求正文包含目标配置。以下示例通过省略certificateConfigurations来删除证书。
{ "name": "my-private-mcp-target", "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0abc123def456", "subnetIds": ["subnet-0abc123", "subnet-0def456"], "endpointIpAddressType": "IPV4", "securityGroupIds": ["sg-0abc123def"] } }, "targetConfiguration": { "mcp": { "mcpServer": { "endpoint": "https://my-mcp-server.internal.example.com/mcp" } } } }
验证和行为
大多数证书验证是异步的。当您使用证书创建或更新目标时,网关会接受请求,然后在目标工作流程中对证书进行验证。如果验证成功,则目标将进入READY状态并可以接收流量。如果验证失败,则目标将进入FAILED状态(用于创建)或UPDATE_UNSUCCESSFUL状态(用于更新),该statusReasons字段描述了问题。常见原因包括以下几点:
-
目标不使用私有端点。
-
不支持目标类型。
-
网关找不到 S3 对象或密钥。
-
证书已过期、不是 CA 证书或超过大小限制。
只有以下检查是同步的,当其中一个检查失败时,网关会立即拒绝请求:
-
每个
certificateConfigurations条目都恰好设置了s3或中的一个secretsManager。 -
字段格式(S3 URI、机密 ARN 和账户 ID)有效。
更新失败不会替换目标已在使用的证书。目标继续使用其现有的有效证书为请求提供服务。
证书吊销
AgentCore Gateway 不执行证书吊销检查。它不检查证书吊销列表 (CRL),也不使用在线证书状态协议 (OCSP)。网关信任任何链接到已配置的私有 CA、在其有效期内且与目标主机匹配的服务器证书。网关会继续信任 CA 吊销的证书,直到该证书过期。
要停止信任已吊销的证书,请更新目标的信任材料。您可以通过下列方式之一来执行该操作:
-
调用
UpdateGatewayTarget并提供一个新的 CA 证书 (PEM)certificateConfigurations,该证书不包含或不再链接到已吊销的证书。有关示例,请参阅示例请求中的替换证书的请求。 -
致电
UpdateGatewayTarget并省略certificateConfigurations以删除私有 CA。这会将目标恢复为公共 CA 信任。有关示例,请参阅示例请求中的删除证书的请求。
即使你更新了信任材料,现有的开放连接也可以继续使用以前的证书,直到网关回收它们。有关更多信息,请参阅运行时行为和疑难解答。
监控证书到期时间
AgentCore Gateway 会发布一个EarliestCertificateDaysToExpiry针对使用私有证书颁发机构的目标命名的 Amazon CloudWatch 指标。网关仅对配置了私有证书的目标发出此指标。该指标报告已配置的 CA 中证书中距离最早到期 (notAfter) 的剩余天数。负值表示证书已经过期。
证书到期会使目标无法访问
配置的证书过期后,网关无法再完成与目标的出站 TLS 握手。目标变得无法访问,并且对它的工具调用失败。有关握手失败的更多信息,请参阅运行时行为和疑难解答。
我们建议您监控EarliestCertificateDaysToExpiry指标并创建 CloudWatch 警报,当该值接近零时触发。此警报让您有时间在证书过期之前替换证书。要替换证书,请调UpdateGatewayTarget用新证书。有关示例,请参阅示例请求中的替换证书的请求。要停止信任已吊销的证书,请参阅证书吊销。
运行时行为和疑难解答
在调用时,目标的服务器证书必须由您配置的私有 CA 颁发,并且必须在其有效期内,并且其主机名必须与目标主机匹配。目标服务器证书的主题备用名称 (SAN) 必须与目标主机匹配。
如果服务器证书不是由配置的私有 CA 颁发的、已过期或与目标主机不匹配,则 TLS 握手会失败。网关返回的是客户端配置错误,而不是服务故障。要解决此错误,请验证目标服务器证书是否由注册的私有 CA 颁发,是否为最新证书,并且包含与目标主机匹配的 SAN。
AgentCore 网关重复使用与目标建立的 TLS 连接。网关在 TLS 握手期间验证证书的信任和有效性。它不会对通过已打开的连接发送的每个请求重新验证证书。在证书有效期间网关打开的连接可以在该连接的生命周期内继续为请求提供服务。此使用寿命长达 900 秒(15 分钟)。即使证书在该时段内过期,连接也可以继续处理请求。当网关在其生命周期结束时回收连接时,它会执行新的 TLS 握手。该握手会根据当前证书重新验证目标。有关相关的网关调用超时,请参阅服务配额。
证书更改将逐渐生效
证书更改最多可能需要 900 秒(15 分钟)才能对机上转机完全生效。这适用于证书到期后,或者使用轮换、替换或删除证书之后UpdateGatewayTarget。现有的开放连接可以继续使用以前的证书和信任材料,直到网关回收它们。新连接会立即使用当前证书。
私人身份提供商
AgentCore 现在支持为入站 JWT 授权和出站 OAuth 凭证提供商连接到私有 OAuth 身份提供商。这使您能够使用自托管服务器 IdPs (例如 Keycloak)或在 VPC 内运行的其他 OIDC-compliant 授权服务器,而无需将其暴露在公共互联网上。 PingFederate
有关详细的配置说明,请参阅 Connect 到您的 VPC 中的私有身份提供商。
或者,您可以使用拦截器 Lambda 函数进行入站身份验证,并覆盖拦截器 Lambda 中的授权标头以用于出站身份验证:
限制和注意事项
-
需要入站授权:除非在网关上配置了拦截器 Lambda,否则配置了
privateEndpoint不能NO_AUTH用作入站授权方类型的网关目标。
有关跨账户连接和 DNS TTL 配置的其他限制,请参阅使用 VPC Lattice 连接到 VPC 中的私有资源中的限制和注意事项。