AWS bedrock-agentcore documentation change
Summary
Complete restructuring of OpenAPI target documentation with added details about required permissions, security configurations, authentication methods, and operational limitations. Removed outdated examples and added IAM policy requirements for credential access.
Security assessment
The changes add documentation about required IAM permissions for API Key/OAuth credential providers and Secrets Manager access, which are security-related configurations. However, there's no evidence of addressing a specific security vulnerability.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-schema-openapi.md b/bedrock-agentcore/latest/devguide/gateway-schema-openapi.md index 998a73b11..cb69241e8 100644 --- a//bedrock-agentcore/latest/devguide/gateway-schema-openapi.md +++ b//bedrock-agentcore/latest/devguide/gateway-schema-openapi.md @@ -5 +5 @@ -Supported OpenAPI featuresKey considerationsTesting your OpenAPI targetAdvanced OpenAPI target configurationsCreate an OpenAPI targetExampleOpenAPI specifications +Understanding OpenAPI TargetsRequired PermissionsKey considerations and limitationsOpenAPI Specification and Feature SupportCreating an OpenAPI targetUpdating an OpenAPI targetTesting your OpenAPI targetInline OpenAPI specifications @@ -13 +13 @@ OpenAPI (formerly known as Swagger) is a widely used standard for describing RES -## Supported OpenAPI features +## Understanding OpenAPI Targets @@ -15 +15 @@ OpenAPI (formerly known as Swagger) is a widely used standard for describing RES -Gateway supports the following OpenAPI features: +OpenAPI targets connect your Gateway to REST APIs defined using OpenAPI specifications. The Gateway translates incoming MCP requests into HTTP requests to these APIs and handles the response formatting. @@ -17 +17 @@ Gateway supports the following OpenAPI features: - * **Paths and operations** : Define endpoints and HTTP methods (GET, POST, PUT, DELETE, etc.) +Key components of OpenAPI targets include: @@ -19 +19 @@ Gateway supports the following OpenAPI features: - * **Parameters** : Path, query, header, and cookie parameters + * **OpenAPI Schema** : The OpenAPI specification that describes the REST API @@ -21 +21 @@ Gateway supports the following OpenAPI features: - * **Request bodies** : JSON, form data, and multipart requests + * **Credential Provider** : Configuration for how the Gateway authenticates with the API @@ -23 +23 @@ Gateway supports the following OpenAPI features: - * **Responses** : Status codes, response bodies, and headers + * **Outbound Auth** : Configuration for authentication with external services @@ -25 +24,0 @@ Gateway supports the following OpenAPI features: - * **Authentication** : API keys, OAuth2, and custom authentication schemes @@ -27 +25,0 @@ Gateway supports the following OpenAPI features: - * **Schemas** : JSON Schema for request and response validation @@ -29,0 +28 @@ Gateway supports the following OpenAPI features: +## Required Permissions @@ -30,0 +30 @@ Gateway supports the following OpenAPI features: +For OpenAPI targets that use API Key or OAuth authentication, your Gateway's execution role needs permissions to access the credential provider: @@ -32,49 +31,0 @@ Gateway supports the following OpenAPI features: -## Key considerations - -###### Important - -The OpenAPI specification must include `operationId` fields for all operations that you want to expose as tools. The operationId is used as the tool name in the MCP interface. - -When using OpenAPI targets, keep in mind the following requirements and limitations: - - * OpenAPI versions 3.0 and 3.1 are supported (Swagger 2.0 is not supported) - - * The OpenAPI file must be free of semantic errors - - * The server attribute needs to have a valid URL of the actual endpoint - - * Only application/json content type is fully supported - - * Complex schema features like oneOf, anyOf, and allOf are not supported - - * Path parameter serializers and parameter serializers for query, header, and cookie parameters are not supported - - - - -## Testing your OpenAPI target - -After adding an OpenAPI target to your Gateway, you can test it by making requests to the Gateway endpoint: - - * **Obtain an access token** from your identity provider (as described in the "Set Up Gateway" guide) - - * **Make a request to the Gateway endpoint** : - - curl -sS -X POST https://{gatewayId}.gateway.{region}.amazonaws.com/mcp \ - --header 'Content-Type: application/json' \ - --header "Authorization: Bearer {access_token}" \ - --data '{ - "jsonrpc": "2.0", - "id": 1, - "method": "tools/call", - "params": { - "name": "searchContent", - "arguments": { - "query": "example search", - "limit": 5 - } - } - }' - - - * **Verify the response** from the API: @@ -83,9 +34,2 @@ After adding an OpenAPI target to your Gateway, you can test it by making reques - "jsonrpc": "2.0", - "id": 1, - "result": { - "results": [ - { - "title": "Example Result 1", - "url": "https://example.com/result1", - "snippet": "This is an example search result" - }, + "Version": "2012-10-17", + "Statement": [ @@ -93,4 +37,4 @@ After adding an OpenAPI target to your Gateway, you can test it by making reques - "title": "Example Result 2", - "url": "https://example.com/result2", - "snippet": "Another example search result" - } + "Sid": "GetResourceApiKey", + "Effect": "Allow", + "Action": [ + "bedrock-agentcore:GetResourceApiKey" @@ -98 +42,3 @@ After adding an OpenAPI target to your Gateway, you can test it by making reques - "total": 2 + "Resource": [ + "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/apikeycredentialprovider/abcdefghijk" + ] @@ -99,0 +46 @@ After adding an OpenAPI target to your Gateway, you can test it by making reques + ] @@ -102,0 +50 @@ After adding an OpenAPI target to your Gateway, you can test it by making reques +For OAuth authentication: @@ -105,24 +52,0 @@ After adding an OpenAPI target to your Gateway, you can test it by making reques - -## Advanced OpenAPI target configurations - -### Inline OpenAPI specifications - -For small OpenAPI specifications, you can provide the specification inline when creating the target: - - - target = gateway_client.create_mcp_gateway_target( - gateway=gateway, - target_type="openApiSchema", - target_payload={ - "inlinePayload": """ - { - "openapi": "3.0.0", - "info": { - "title": "Simple API", - "version": "1.0.0" - }, - "paths": { - "/hello": { - "get": { - "operationId": "sayHello", - "parameters": [ @@ -130,6 +54,4 @@ For small OpenAPI specifications, you can provide the specification inline when - "name": "name", - "in": "query", - "schema": { - "type": "string" - } - } + "Sid": "GetResourceOauth2Token", + "Effect": "Allow", + "Action": [ + "bedrock-agentcore:GetResourceOauth2Token" @@ -137,22 +59,3 @@ For small OpenAPI specifications, you can provide the specification inline when - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - } - } - } - } - } - } - """ + "Resource": [ + "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/oauth2credentialprovider/abcdefghijk" + ] @@ -160 +62,0 @@ For small OpenAPI specifications, you can provide the specification inline when - ) @@ -163,3 +65 @@ For small OpenAPI specifications, you can provide the specification inline when -### Updating an OpenAPI target - -You can update an existing OpenAPI target using the `UpdateGatewayTarget` API: +If the credentials are stored in AWS Secrets Manager, the execution role also needs permission to access those secrets: @@ -168,14 +67,0 @@ You can update an existing OpenAPI target using the `UpdateGatewayTarget` API: - updated_target = agentcore_client.update_gateway_target( - gatewayIdentifier="your-gateway-id", - targetId="your-target-id", - name="UpdatedSearchAPITarget", - targetConfiguration={ - "mcp": { - "openApiSchema": { - "s3": { - "uri": "s3://your-bucket/path/to/updated-open-api-spec.json" - } - } - } - }, - credentialProviderConfigurations=[ @@ -183,9 +69,7 @@ You can update an existing OpenAPI target using the `UpdateGatewayTarget` API: - "credentialProviderType": "API_KEY", - "credentialProvider": {