AWS bedrock-agentcore documentation change
Summary
Major restructuring and expansion of VPC egress documentation. Reordered sections, added detailed configuration for MCP targets (both self-hosted and AgentCore Runtime), OpenAPI targets with private endpoints, and a new Smithy target section. Added new sections for workarounds for private identity providers and limitations/considerations. Updated API Gateway integration guidance and removed outdated content.
Security assessment
The changes primarily document new VPC egress capabilities and configurations using VPC Lattice for private connectivity. While it emphasizes security best practices (like principle of least privilege for Lambda, OAuth authentication, and avoiding unnecessary network hops), there is no concrete evidence of a specific security vulnerability, weakness, or incident being addressed. The changes are feature documentation and architectural guidance.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-vpc-egress.md b/bedrock-agentcore/latest/devguide/gateway-vpc-egress.md index 88165978a..e28fa5e82 100644 --- a//bedrock-agentcore/latest/devguide/gateway-vpc-egress.md +++ b//bedrock-agentcore/latest/devguide/gateway-vpc-egress.md @@ -5 +5 @@ -LambdaAPI GatewayMCPOpen API targetOther targets/configurations +MCPOpen API targetSmithy targetAPI GatewayLambdaWorkaround for private identity providersLimitations and considerations @@ -11 +11,111 @@ The AgentCore Gateway service provides secure and controlled egress traffic mana -## Lambda +## MCP + +AgentCore Gateway supports Model Context Protocol (MCP) servers as target endpoints, providing flexible deployment options to meet various customer requirements. MCP servers can be configured in multiple ways depending on your infrastructure needs and security requirements. + +Your MCP targets could be of two types, not hosted on AgentCore, or hosted on AgentCore Runtime or Gateway. We discuss both below. + +### MCPs not hosted on AgentCore + +AgentCore Gateway supports connecting to self-hosted MCP servers running inside your VPC using private endpoints powered by Amazon VPC Lattice. You can configure a `privateEndpoint` on your gateway target to route traffic privately to your MCP server without exposing it to the public internet. + +###### Important + +VPC egress with private endpoints is made available as a "Beta Service" as defined in the AWS Service Terms. + +The following example creates a private MCP server target using managed Lattice: + + + { + "name": "my-private-mcp-target", + "privateEndpoint": { + "managedLatticeResource": { + "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" + } + } + } + } + +If your MCP server uses a domain that is not publicly resolvable (for example, a private hosted zone in Route 53), you must also specify a `routingDomain`. For more information, see [Workaround for private DNS support: routing domain](./vpc-egress-private-endpoints.html#lattice-vpc-egress-routing-domain). + +If your MCP server uses a TLS certificate issued by a private certificate authority, you can place an internal Application Load Balancer with a public ACM certificate in front of it. For more information, see [Workaround for private certificates: ALB](./vpc-egress-private-endpoints.html#lattice-vpc-egress-private-certs). + +For self-managed Lattice, cross-account setups, and advanced configurations, see [Connect to private resources in your VPC using VPC Lattice](./vpc-egress-private-endpoints.html). + +### AgentCore Runtime or Gateway + +AgentCore Runtime provides native support for communicating with resources within your VPC through a managed infrastructure approach. All communication between AgentCore Gateway and AgentCore Runtime stays on the AWS backbone, ensuring your data never traverses the public internet (except for cross-region calls to China datacenters). For more information, see the [Connectivity](https://aws.amazon.com/vpc/faqs/#connectivity) section in the Amazon VPC FAQs. For detailed setup instructions on connecting AgentCore Runtime to your VPC, refer to the [Configure Amazon Bedrock AgentCore Runtime and tools for VPC](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html) + +For outbound authorization from AgentCore Gateway to AgentCore Runtime, two authentication methods are supported: no authorization (not recommended for production use) and OAuth with client credentials grant (for machine-to-machine authentication). When no authorization is configured, the request from AgentCore Gateway to AgentCore Runtime has no auth tokens. This architecture provides a seamless connection pathway while maintaining security isolation. As a security best practice, configure restrictive authentication and authorization permissions for both AgentCore Runtime and AgentCore Gateway, limiting access to only the necessary resources and operations required for your specific use case. To configure an OAuth Identity to be used by AgentCore Gateway for egress and ingress for AgentCore Runtime use the following documents: + + * [Configure an OAuth client](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-oauth-client.html) + + * [Specify the authorization type and credentials to access the gateway target](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets-authorization.html) + + * [Authenticate and authorize with Inbound Auth and Outbound Auth](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-oauth.html) + + + + + + +###### Example CreateGatewayTarget with AgentCore Runtime as a the target + +The following example shows how to create a gateway target with 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>" + } + } + } + } + +###### Note + +Avoid using a VPC endpoint (VPCE) URL with `privateEndpoint` to prevent an unnecessary extra network hop. Use the direct AgentCore Runtime endpoint instead, with which traffic remains on the AWS backbone. + +## Open API target + +### API Gateway endpoint via Open API Target + +If your API Gateway can't be directly added as a target, you can always export the resource as an OpenAPI spec and import the spec into AgentCore Gateway as a OpenAPI target. + + * [Export a REST API from API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html) + + * [OpenAPI schema targets](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-schema-openapi.html) + @@ -13 +123,43 @@ The AgentCore Gateway service provides secure and controlled egress traffic mana -AgentCore Gateway supports Lambda targets as one of it target types, allowing seamless invocation of Lambda functions that can communicate with resources within your VPC. This functionality is available out-of-the-box and requires no additional configuration from customers - the gateway can immediately invoke Lambda functions that have been configured with VPC access to reach your internal resources such as databases, APIs, or other services. To maintain security best practices, it's strongly recommended to configure the AgentCore Gateway execution role with minimal permissions, specifically limiting it to invoke only the intended Lambda function rather than granting broad Lambda execution permissions. This principle of least privilege ensures that the gateway, or any other caller using the same role, cannot inadvertently invoke unintended Lambda functions, thereby reducing your security attack surface and maintaining strict access controls within your AWS environment. + + +If you have Private REST APIs in API Gateway, follow the instructions here: Private REST APIs in API Gateway. + +### Other endpoints + +You can configure Open API targets to reach private endpoints inside your VPC using the `privateEndpoint` configuration. AgentCore Gateway uses Amazon VPC Lattice to establish private connectivity to your endpoint without exposing it to the public internet. + +###### Important + +VPC egress with private endpoints is made available as a "Beta Service" as defined in the AWS Service Terms. + +The following example creates a private OpenAPI target using managed Lattice: + + + { + "name": "my-private-openapi-target", + "privateEndpoint": { + "managedLatticeResource": { + "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>" + } + } + } + } + +If your endpoint uses a domain that is not publicly resolvable, you must also specify a `routingDomain`. For more information, see [Workaround for private DNS support: routing domain](./vpc-egress-private-endpoints.html#lattice-vpc-egress-routing-domain). + +If your endpoint uses a TLS certificate issued by a private certificate authority, you can place an internal Application Load Balancer with a public ACM certificate in front of it. For more information, see [Workaround for private certificates: ALB](./vpc-egress-private-endpoints.html#lattice-vpc-egress-private-certs). + +For self-managed Lattice, cross-account setups, and advanced configurations, see [Connect to private resources in your VPC using VPC Lattice](./vpc-egress-private-endpoints.html). + +## Smithy target + +Private endpoint (`privateEndpoint`) configuration is not currently supported for Smithy targets. @@ -97,29 +249 @@ The following trust policy allows AgentCore Gateway to assume the execution role -#### I already have Private REST APIs in API Gateway - -In this case you can clone it (or migrate it if AgentCore Gateway is the only customer) to a regional endpoint and then setup the API Gateway Resource Policy Locked Down to AgentCore Gateway as discussed above. - - - -This is equivalent from a security posture to the AgentCore Gateway getting into the VPC and then hitting the API Gateway VPC endpoint and reduces any unnecessary network hops. - - - -## MCP - -AgentCore Gateway supports Model Context Protocol (MCP) servers as target endpoints, providing flexible deployment options to meet various customer requirements. MCP servers can be configured in multiple ways depending on your infrastructure needs and security requirements. - -Your MCP targets could be of two types, hosted on AgentCore Runtime in the VPC, or self-hosted. We discuss both below. - -### AgentCore Runtime - -AgentCore Runtime provides native support for communicating with resources within your VPC through a managed infrastructure approach. All communication between AgentCore Gateway and AgentCore Runtime will happen over the AWS backbone, as guaranteed by the EC2 team, ensuring your data never traverses the public internet (except for cross-region calls to China datacenters). For detailed setup instructions on connecting AgentCore Runtime to your VPC, refer to the [Configure Amazon Bedrock AgentCore Runtime and tools for VPC](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html) - -For outbound authorization from AgentCore Gateway to AgentCore Runtime, two authentication methods are supported: no authorization (not recommended for production use) and OAuth with client credentials grant (for machine-to-machine authentication). When no authorization is configured, the request from AgentCore Gateway to AgentCore Runtime has no auth tokens. This architecture provides a seamless connection pathway while maintaining security isolation. As a security best practice, configure restrictive authentication and authorization permissions for both AgentCore Runtime and AgentCore Gateway, limiting access to only the necessary resources and operations required for your specific use case. To configure an OAuth Identity to be used by AgentCore Gateway for egress and ingress for AgentCore Runtime use the following documents: - - * [Configure an OAuth client](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-oauth-client.html) - - * [Specify the authorization type and credentials to access the gateway target](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets-authorization.html) - - * [Authenticate and authorize with Inbound Auth and Outbound Auth](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-oauth.html) - - +#### Private REST APIs in API Gateway @@ -127,6 +251 @@ For outbound authorization from AgentCore Gateway to AgentCore Runtime, two auth - - -