AWS bedrock-agentcore documentation change
Summary
Added comprehensive documentation for OAuth Authorization Code flow support, expanded authorization strategies (NoAuth, OAuth, IAM SigV4), added IAM compatibility details, and included new IAM permissions for security operations
Security assessment
This change adds extensive security documentation including OAuth Authorization Code flow (three-legged OAuth), IAM SigV4 authentication details, URL session binding to prevent authorization hijacking, and new required IAM permissions. It documents security features but doesn't indicate it's addressing a specific security vulnerability or incident. The URL session binding specifically mentions preventing scenarios where authorization URLs are accidentally shared, which is a security improvement but presented as a feature enhancement rather than a fix.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.md b/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.md index 5fc4fe8a0..0b4d93298 100644 --- a//bedrock-agentcore/latest/devguide/gateway-target-MCPservers.md +++ b//bedrock-agentcore/latest/devguide/gateway-target-MCPservers.md @@ -5 +5 @@ -Key considerations and limitationsConfiguring permissions +Key considerations and limitationsConnecting to an OAuth-protected MCP server using Authorization Code flowConfiguring permissions @@ -11 +11 @@ MCP servers provide local tools, data access, or custom functions for your inter -MCP servers host tools which agents can discover and invoke. In Bedrock AgentCore, you use a gateway to associate targets to tools to connect to your agent runtime. You connect with external MCP servers through the `SynchronizeGatewayTargets` API that performs protocol handshakes and indexes available tools. For more information about installing and using MCP servers, see [Amazon Bedrock AgentCore MCP Server: Vibe coding with your coding assistant](./mcp-getting-started.html). +MCP servers host tools that agents can discover and invoke. In Bedrock AgentCore, you use a gateway to associate targets with tools and connect them to your agent runtime. You connect with external MCP servers through the `SynchronizeGatewayTargets` API that performs protocol handshakes and indexes available tools. For more information about installing and using MCP servers, see [Amazon Bedrock AgentCore MCP Server: Vibe coding with your coding assistant](./mcp-getting-started.html). @@ -16,0 +17,2 @@ MCP servers host tools which agents can discover and invoke. In Bedrock AgentCor + * Connecting to an OAuth-protected MCP server using Authorization Code flow + @@ -28 +30 @@ Tool discovery is managed through the synchronization operation provided by the -Implicity synchronization is the automatic tool discovery and indexing that occurs during `CreateGatewayTarget` and `UpdateGatewayTarget` operations. Gateway immediately calls the MCP server's tools/list capability to fetch available tools and make tools available in the unified catalog without requiring separate user action. +Implicit synchronization is the automatic tool discovery and indexing that occurs during `CreateGatewayTarget` and `UpdateGatewayTarget` operations. Gateway immediately calls the MCP server's tools/list capability to fetch available tools and make tools available in the unified catalog without requiring separate user action. @@ -32 +34 @@ Implicity synchronization is the automatic tool discovery and indexing that occu -Manual tool catalog refresh triggered by calling the `SynchronizeGatewayTargets` API. Invoke this when the MCP server has changed its tool definitions. The API performs discovery process on-demand operation, allowing users to control when Gateway updates its view of available tools. +Manual tool catalog refresh triggered by calling the `SynchronizeGatewayTargets` API. Invoke this when the MCP server has changed its tool definitions. The API performs the discovery process on-demand, allowing users to control when Gateway updates its view of available tools. @@ -34 +36 @@ Manual tool catalog refresh triggered by calling the `SynchronizeGatewayTargets` -Synchronization is a critical mechanisms for maintaining accurate tool catalogs when integrating MCP servers. Implicit synchronization occurs automatically during target creation and updates, where Gateway immediately discovers and indexes tools from the MCP server to ensure tools are available for semantic search and unified listing. Explicit synchronization is performed on-demand through the `SynchronizeGatewayTargets` API, allowing discovery of MCP tool catalog when MCP servers independently modify their capabilities. +Synchronization is a critical mechanism for maintaining accurate tool catalogs when integrating MCP servers. Implicit synchronization occurs automatically during target creation and updates, where Gateway immediately discovers and indexes tools from the MCP server to ensure tools are available for semantic search and unified listing. Explicit synchronization is performed on-demand through the `SynchronizeGatewayTargets` API, allowing discovery of the MCP tool catalog when MCP servers independently modify their capabilities. @@ -46 +48,12 @@ Make a PUT request to /gateways/{gatewayIdentifier}/synchronize with the target -Two types of the authorization strategy are supported. +The following types of the authorization strategy are supported. + + * No authorization – The gateway invokes the MCP server without preconfigured authorization. This approach is not recommended. + + * OAuth – The gateway supports both two-legged OAuth (Client Credentials grant type) and three-legged OAuth (Authorization Code grant type). You configure the authorization provider in Amazon Bedrock AgentCore Identity in the same account and Region for the gateway to make calls to the MCP server. + + * IAM ([AWS Signature Version 4 (Sig V4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)) – The gateway signs requests to the MCP server using SigV4 with the gateway service role credentials. You configure an `IamCredentialProvider` with a required service name for SigV4 signing and an optional Region (defaults to the gateway Region). + + + + +###### Important @@ -48 +61 @@ Two types of the authorization strategy are supported. - * NoAuth - Gateway will invoke the MCP server's tool capabilities without preconfigured Auth. This is not the recommended approach. +IAM (SigV4) outbound authorization requires that the MCP server is hosted behind an AWS service that natively supports IAM authentication. The gateway signs outbound requests with SigV4 but does not modify the authentication configuration on the target. The target service must be able to verify SigV4 signatures. @@ -50 +63 @@ Two types of the authorization strategy are supported. - * OAuth2 - Gateway supports two-legged OAuth. You configure the authorization provider in AgentCore Identity in the same account and Region for the Gateway to be able to make calls to the MCP server. +The following AWS services natively support IAM authentication and are compatible with IAM outbound authorization for MCP server targets: @@ -51,0 +65 @@ Two types of the authorization strategy are supported. + * Amazon Bedrock AgentCore Gateway @@ -52,0 +67 @@ Two types of the authorization strategy are supported. + * Amazon Bedrock AgentCore Runtime (see [Deploy MCP servers in AgentCore Runtime](./runtime-mcp.html)) @@ -53,0 +69 @@ Two types of the authorization strategy are supported. + * Amazon API Gateway @@ -55 +71,10 @@ Two types of the authorization strategy are supported. -**Configuration considerations** For the MCP servers target type, the following must be configured. + * Lambda Function URLs + + + + +Services that do not natively verify SigV4 signatures, such as Application Load Balancer or direct Amazon EC2 endpoints, are not compatible with IAM outbound authorization. If your MCP server is hosted behind one of these services, use OAuth or API key authorization instead. + +**Configuration considerations for MCP server targets** + +The following must be configured. @@ -59 +84 @@ Two types of the authorization strategy are supported. - 2. Supported MCP protocol versions are - **2025-06-18** and **2025-03-26**. + 2. Supported MCP protocol versions are - **2025-06-18** , **2025-03-26** , and **2025-11-25**. @@ -67,0 +93,30 @@ Two types of the authorization strategy are supported. +## Connecting to an OAuth-protected MCP server using Authorization Code flow + +To support the Authorization Code grant type (three-legged OAuth) with MCP server targets, Amazon Bedrock AgentCore Gateway provides two methods for target creation. + +**Implicit sync during MCP server target creation** + +With this method, the admin user completes the authorization code flow during `CreateGatewayTarget`, `UpdateGatewayTarget`, or `SynchronizeGatewayTargets` operations using the authorization URL returned in the response. This allows Amazon Bedrock AgentCore Gateway to discover and cache the MCP server's tools upfront. + +###### Note + +You cannot delete, update, or synchronize a target that is in a pending authorization state (`CREATE_PENDING_AUTH`, `UPDATE_PENDING_AUTH`, or `SYNCHRONIZE_PENDING_AUTH`). Wait for the authorization to complete or fail before performing further operations on the target. + +**Provide schema upfront during MCP server target creation** + +With this method, admin users provide the tool schema directly during `CreateGatewayTarget` or `UpdateGatewayTarget` operations using the `mcpToolSchema` field, rather than Amazon Bedrock AgentCore Gateway fetching them dynamically from the MCP server. Amazon Bedrock AgentCore Gateway parses the provided schema and caches the tool definitions. + +###### Note + +You cannot synchronize a target that has a static tool schema (`mcpToolSchema`) configured. Remove the static schema through an `UpdateGatewayTarget` call to enable dynamic tool synchronization. + +**URL Session Binding** + +[OAuth 2.0 authorization URL session binding](./oauth2-authorization-url-session-binding.html) verifies that the user who initiated the OAuth authorization request is the same user who granted consent. After the user completes consent, the browser redirects back to a return URL configured on the target with a unique session URI. The application is then responsible for calling the [CompleteResourceTokenAuth](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CompleteResourceTokenAuth.html) API, presenting both the user's identity and the session URI. Amazon Bedrock AgentCore Identity validates that the user who started the flow is the same user who completed it before exchanging the authorization code for an access token. + +This prevents a scenario where a user accidentally shares the authorization URL and someone else completes the consent, which would grant access tokens to the wrong party. The authorization URL and session URI are only valid for 10 minutes, further limiting the window for misuse. Session binding applies during target creation (implicit sync) and during tool invocation. + +###### Note + +When performing target operations (Create, Update, or Synchronize) and authorization through the AWS Management Console, the [CompleteResourceTokenAuth](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CompleteResourceTokenAuth.html) call is made on behalf of the resource owner, requiring no further action after authorization. + @@ -92,0 +148 @@ The IAM role which you use to create, update or synchronize MCP servers targets + "bedrock-agentcore:GetWorkloadAccessTokenForUserId", @@ -93,0 +150 @@ The IAM role which you use to create, update or synchronize MCP servers targets + "bedrock-agentcore:CompleteResourceTokenAuth",