AWS bedrock-agentcore documentation change
Summary
Comprehensive rewrite of gateway creation documentation including added details about authentication methods (JWT/IAM), encryption configuration, service role requirements, and step-by-step console/API instructions
Security assessment
The changes add explicit documentation about security-related configurations including JWT authentication, IAM role requirements, KMS encryption options, and authorization setup. While these are security features, there is no indication this addresses a specific vulnerability or incident.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-create.md b/bedrock-agentcore/latest/devguide/gateway-create.md index dce8007f6..30faebf4b 100644 --- a//bedrock-agentcore/latest/devguide/gateway-create.md +++ b//bedrock-agentcore/latest/devguide/gateway-create.md @@ -5 +5 @@ -Create a gateway with semantic search +Create a gateway (console)Create a gateway (API) @@ -7 +7 @@ Create a gateway with semantic search -Amazon Bedrock AgentCore is in preview release and is subject to change. +# Create an Amazon Bedrock AgentCore gateway @@ -9 +9 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -# Creating your Gateway +This guide walks you through the process of creating and configuring an Amazon Bedrock AgentCore Gateway. The Gateway serves as a unified entry point for agents to access tools and resources through the Model Context Protocol (MCP) and creating it is the first step in building your tool integration platform. When you create a gateway, you create a managed service that handles authentication and invokes callable endpoints as tools. @@ -11 +11 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -Once you have set up your identity provider, you can create your Gateway with the AWS Management Console or with the [CreateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html) API operation. +To create a gateway, you set up inbound authorization and configure invocable targets. Targets establish the connection between your gateway and various tool types, including Lambda functions and REST API services. Each target contains configuration details that specify the tool location, authentication requirements, and any necessary request transformation rules. @@ -13 +13 @@ Once you have set up your identity provider, you can create your Gateway with th -When you create a gateway, you can include the following capabilities: +You can create a gateway in the following ways: @@ -15 +15 @@ When you create a gateway, you can include the following capabilities: - * **Semantic search** – Allows using semantic search to deliver contextually relevant tools. For more information, see Create a gateway with semantic search. + * AWS Management Console – With the console, you can configure authorization, create the gateway, and add targets all on one page. @@ -17 +17 @@ When you create a gateway, you can include the following capabilities: - * **Debug mode** – Allows the return of specific error messages related to the gateway target configuration to help you with debugging. For more information, see [Turn on debugging messages](./gateway-debug-messages.html). + * Amazon Bedrock AgentCore API – You can directly invoke the [CreateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html) API or through the help of a supported tool. If you use the API, you will add targets to your gateway in a separate step. @@ -22 +22 @@ When you create a gateway, you can include the following capabilities: -For more details on a specific method, select a tab: +When creating a gateway, you provide the following required fields: @@ -24 +24 @@ For more details on a specific method, select a tab: -AgentCore SDK + * A name for the gateway. @@ -25,0 +26 @@ AgentCore SDK + * The Amazon Resource Name (ARN) of an [AgentCore service role](./gateway-prerequisites-permissions.html#gateway-execution-permissions) with permissions to make requests to the gateway on your behalf. @@ -27 +28,131 @@ AgentCore SDK -You can create a gateway with the AgentCore SDK: + * The type of authorizer to use for inbound requests to the gateway. AgentCore Gateway supports the following types of authentication: + + * JSON Web Token (JWT) authentication + + * AWS IAM credentials + + * (If you use JWT authentication) An authorizer configuration that specifies how incoming requests to the gateway should be authenticated. + + * The protocol type for the gateway. + + + + +You can optionally provide the following fields: + + * A description of the gateway. + + * A client token value to ensure that a request completes no more than once. If you don't include this token, one is randomly generated for you. If you don't include a value, one is randomly generated for you. For more information, see [Ensuring idempotency](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html). + + + + +###### Gateway features that can be set during creation + +You can activate the following features of the gateway during creation: + + * **Protocol configuration** – Configure how the gateway implements the protocol. + + * **Custom encryption of the gateway** – Specify the Amazon Resource Name (ARN) of a customer-managed AWS KMS key for greater control over the encryption process of your resource. If you don't include one, AWS encrypts the resource with an AWS-managed key. For more information, see [Encrypt your AgentCore gateway with a customer-managed KMS key](./gateway-encryption.html). + + * **Debug mode** – Allow the return of specific error messages during gateway invocation to help you with debugging. For more information, see [Turn on debugging messages](./gateway-debug-messages.html). + + * **Semantic search** – Add the `x_amz_bedrock_agentcore_search` to the gateway so that the target can deliver tools that are relevant to the search query. For more information, see [Search for tools in your AgentCore gateway with a natural language query](./gateway-using-mcp-semantic-search.html). + + + + +Select a topic to learn how to create a gateway using that method: + +###### Topics + + * Create an AgentCore gateway using the AWS Management Console + + * Create an AgentCore gateway using the API + + + + +## Create an AgentCore gateway using the AWS Management Console + +###### To create a gateway using the console + + 1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home#](https://console.aws.amazon.com/bedrock-agentcore/home#). + + 2. From the left navigation pane, select **Gateways**. + + 3. In the **Gateways** section, choose **Create gateway**. + + 4. (Optional) In the **Gateway details** section, do the following: + + 1. Change the generated **Gateway name** + + 2. Expand the **Additional configurations** section and do the following: + + 1. In the **Gateway description** field, provide a description for your gateway. + + 2. In the **Instruction** field, enter any special instructions or context that should be passed to tools when they are invoked. + + 3. To enable a built-in tool for searching tools in the gateway, select **Enable semantic search**. If you enable this tool, you can't disable it later. For more information, see [Search for tools in your AgentCore gateway with a natural language query](./gateway-using-mcp-semantic-search.html). + + 4. To enable detailed debugging messages to be returned in the gateway response, select **Exception level debug**. You can disable debugging messages later. For more information, see [Turn on debugging messages](./gateway-debug-messages.html). + + 5. In the **Inbound Auth configurations** section, select one of the following options: + + * To allow Amazon Cognito to create authorization resources for you, select **Quick create configurations with Cognito**. + + * To use an authorization configuration that you have set up already, select **Use existing identity provider configurations** and then configure the following fields: + + * **Discovery URL** – Enter the discovery URL from your identity provider. + + * **Allowed audiences** – Enter the audience value that your gateway will accept. To add more audiences, choose **Add audience**. + + * **Allowed clients** – Enter the public identifier of the client that your gateway will accept. To add more clients, choose **Add client**. + + 6. In the **Permissions** section, do the following: + + 1. To use an IAM service role to invoke the gateway on the user's behalf, select **Use an IAM service role**. + + 2. (If you use an IAM service role) Choose one of the following options under **IAM role** : + + * To create a service role with the necessary permissions to access your gateway, choose **Create and use a new service role** and optionally change the generated **Service role name**. + + * To use an existing service role, choose **Use an existing service role** and then select a role from the **Service role name** dropdown menu. Make sure that the service role that you choose has the necessary permissions. For more information, see [AgentCore Gateway service role permissions](./gateway-prerequisites-permissions.html#gateway-execution-permissions). + + 7. (Optional) By default, your gateway is encrypted with an AWS managed key. To encrypt your gateway with a custom KMS key, expand the **KMS key** section, select **Customize encryption settings (advanced)** , and choose a customer managed key. For more information, see [Encrypt your AgentCore gateway with a customer-managed KMS key](./gateway-encryption.html). + + 8. In the **Target:`${target-name}`** section, do the following: + + 1. (Optional) Change the generated **Target name**. + + 2. (Optional) Provide a **Target description**. + + 3. For the **Target type** , choose an option. For more information about different target types, see [Add targets to an existing AgentCore gateway](./gateway-building-adding-targets.html). + + 4. Select or enter how the target type is defined. + + 5. For the **Outbound Auth configurations** , select an outbound authorization method. Then, select or provide the necessary details and any optional additional configurations. For more information, see [Set up outbound authorization for your gateway](./gateway-outbound-auth.html). + + 9. To add more targets, choose **Add another target** and repeat the target configuration steps. + + 10. Choose **Create gateway**. + + + + +After creating your gateway, you can view its details, including the endpoint URL and associated targets. + +## Create an AgentCore gateway using the API + +To create a AgentCore gateway using the API, make a [CreateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html) request with one of the [AgentCore control plane endpoints](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html#bedrock_agentcore_cp). + +To see examples of how to create a gateway, expand the section that corresponds to your use case: + +This section provides basic examples of creating a gateway. + +Select one of the following methods: + +AgentCore starter toolkit + + +The AgentCore starter toolkit helps you easily create a gateway with minimal specifications. @@ -35,2 +166,5 @@ You can create a gateway with the AgentCore SDK: - # EZ Auth - automatically sets up Cognito OAuth - cognito_result = client.create_oauth_authorizer_with_cognito("my-gateway") + # Automatically set up Cognito OAuth. Replace with a name of your choice + cognito_result = client.create_oauth_authorizer_with_cognito(gateway_name="my-gateway") + + # Get the authorizer configuration + authorization=cognito_result["authorizer_config"] @@ -38 +172 @@ You can create a gateway with the AgentCore SDK: - # create the gateway. + # Create the gateway. @@ -40 +174 @@ You can create a gateway with the AgentCore SDK: - name=None, # the name of the Gateway - if you don't set one, one will be generated. + name=None, # You can omit this field @@ -84 +218 @@ Console - 1. [https://console.aws.amazon.com/bedrock-agentcore/home#](https://console.aws.amazon.com/bedrock-agentcore/home#) + 1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home#](https://console.aws.amazon.com/bedrock-agentcore/home#). @@ -86 +220 @@ Console - 2. From the left navigation pane, select **Gateways**. + 2. Choose **Gateways**. @@ -160 +294,2 @@ The following Python code shows how to create a gateway with boto3 (AWS SDK for - # create the agentcore client + + # Create the agentcore client @@ -162 +297,2 @@ The following Python code shows how to create a gateway with boto3 (AWS SDK for - # create a gateway + + # Create a gateway @@ -212 +348 @@ The following example creates a Gateway with MCP protocol and JWT authorization: -After creating the gateway, you can call `CreateGatewayTarget` to add targets to the gateway. The operation accepts a gateway identifier in the URI path along with target specifications including the target name and configuration details. +This section provides basic examples of creating a gateway using IAM authorization. With IAM authorization, you don't need an authorizer configuration. @@ -214 +350 @@ After creating the gateway, you can call `CreateGatewayTarget` to add targets to -###### Example request for OpenAPI target +Select one of the following methods: