AWS bedrock-agentcore high security documentation change
Summary
Restructured documentation to focus on limitations and specifications, removed code examples and IAM permission guidance, added Smithy model implementation details
Security assessment
The diff removes the 'Required Permissions' section that previously provided IAM policy examples for DynamoDB access. This deletion removes security-critical guidance about configuring least-privilege permissions for gateway targets, which could lead to insecure IAM configurations if omitted. The change also removes code examples showing credential provider configurations using GATEWAY_IAM_ROLE.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-building-smithy-targets.md b/bedrock-agentcore/latest/devguide/gateway-building-smithy-targets.md index a8506f572..f93b788f0 100644 --- a//bedrock-agentcore/latest/devguide/gateway-building-smithy-targets.md +++ b//bedrock-agentcore/latest/devguide/gateway-building-smithy-targets.md @@ -5 +5 @@ -Built-in Smithy ModelsUnderstanding Smithy Model TargetsRequired PermissionsSmithy Model TypesSmithy Feature SupportCreating a Smithy targetUpdating a Smithy Model TargetAdvanced Smithy Model Target Configurations +Key considerations and limitationsSmithy model specification @@ -7 +7 @@ Built-in Smithy ModelsUnderstanding Smithy Model TargetsRequired PermissionsSmit -Amazon Bedrock AgentCore is in preview release and is subject to change. +# Smithy model targets @@ -9 +9 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -# Add Smithy targets to your gateway +Smithy is a language for defining services and software development kits (SDKs). Smithy models provide a more structured approach to defining APIs compared to OpenAPI, and are particularly useful for connecting to AWS services, such as AgentCore Gateway. @@ -11 +11 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -Smithy is a language for defining services and SDKs that works well with Gateway. Smithy models provide a more structured approach to defining APIs compared to OpenAPI, and are particularly useful for connecting to AWS services. +Smithy model targets connect your AgentCore gateway to services that are defined using Smithy API models. When you invoke a Smithy model gateway target, the gateway translates incoming MCP requests into API calls that are sent to these services. The gateway also handles the response formatting. @@ -13 +13 @@ Smithy is a language for defining services and SDKs that works well with Gateway -## Built-in Smithy Models +Review the key considerations and limitations, including feature support, to help you decide whether a Smithy target is applicable to your use case. If it is, you can create a schema that follows the specifications and then set up permissions for the gateway to be able to access the target. Select a topic to learn more: @@ -15 +15 @@ Smithy is a language for defining services and SDKs that works well with Gateway -Gateway provides built-in Smithy models for popular AWS services. When you create a Smithy target without specifying a model, it defaults to the DynamoDB model: +###### Topics @@ -16,0 +17 @@ Gateway provides built-in Smithy models for popular AWS services. When you creat + * Key considerations and limitations @@ -18,7 +19 @@ Gateway provides built-in Smithy models for popular AWS services. When you creat - # Create a Smithy target with default DynamoDB model - smithy_target = agentcore_client.create_gateway_target( - gatewayIdentifier=gateway["gatewayId"], - name="DynamoDBTarget", - targetConfiguration={"mcp": {"smithyModel": {}}}, # Empty - uses default DynamoDB model - credentialProviderConfigurations=[{"credentialProviderType": "GATEWAY_IAM_ROLE"}] - ) + * Smithy model specification @@ -27 +21,0 @@ Gateway provides built-in Smithy models for popular AWS services. When you creat -You can find Smithy API models for hundreds of AWS services in the [AWS API Models repository](https://github.com/aws/api-models-aws). Popular services include: @@ -29 +22,0 @@ You can find Smithy API models for hundreds of AWS services in the [AWS API Mode - * DynamoDB (default) @@ -31 +24 @@ You can find Smithy API models for hundreds of AWS services in the [AWS API Mode - * S3 +## Key considerations and limitations @@ -33 +26 @@ You can find Smithy API models for hundreds of AWS services in the [AWS API Mode - * Lambda +When using Smithy models with AgentCore Gateway, be aware of the following limitations: @@ -35,70 +28 @@ You can find Smithy API models for hundreds of AWS services in the [AWS API Mode - * EC2 - - * RDS - - - - -To add a Smithy target, you need: - - * A Smithy model in JSON AST format - - * Optional authentication configuration for accessing the service - - - - -You can provide the Smithy model in two ways: - - * Inline as a JSON string - - * As a reference to an S3 object - - - - -## Understanding Smithy Model Targets - -Smithy model targets connect your Gateway to services defined using Smithy models, such as AWS services like DynamoDB, S3, and more. The Gateway translates incoming MCP requests into API calls to these services and handles the response formatting. - -Key components of Smithy model targets include: - - * **Smithy Model** : The Smithy model definition that describes the service API - - * **Credential Provider** : Configuration for how the Gateway authenticates with the service - - - - -## Required Permissions - -For Smithy model targets that access AWS services, your Gateway's execution role needs permissions to access those services. For example, for a DynamoDB target, your execution role needs permissions to perform DynamoDB operations: - -JSON - - -**** - - - - { - "Version":"2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "dynamodb:GetItem", - "dynamodb:PutItem", - "dynamodb:UpdateItem", - "dynamodb:DeleteItem", - "dynamodb:Query", - "dynamodb:Scan" - ], - "Resource": "arn:aws:dynamodb:*:*:table/*" - } - ] - } - - - -## Smithy Model Types + * Maximum model size: 10MB @@ -106 +30 @@ JSON -AgentCore Gateway supports built-in AWS service models only. Smithy models are restricted to AWS services and custom Smithy models for non-AWS services are not supported. + * Only JSON protocol bindings are fully supported @@ -108 +32 @@ AgentCore Gateway supports built-in AWS service models only. Smithy models are r -AgentCore Gateway provides built-in Smithy models for common AWS services via an AWS provided S3 bucket that hosts the Smithy files. You can pass the Smithy file URIs to the create target API. + * Only RestJson protocol is supported @@ -110 +34 @@ AgentCore Gateway provides built-in Smithy models for common AWS services via an -When you create a Smithy model target without specifying a custom model in the AgentCoreSDK, the Gateway will use the built-in DynamoDB model. + * Complex endpoint creation rule sets are not supported @@ -112 +36 @@ When you create a Smithy model target without specifying a custom model in the A -Here's an example of creating a Smithy model target for DynamoDB: + * Only simple URL parameters like {region} are supported @@ -115,7 +38,0 @@ Here's an example of creating a Smithy model target for DynamoDB: - # Create a Smithy model target for DynamoDB - dynamodb_target = gateway_client.create_mcp_gateway_target( - gateway=gateway, - target_type="smithyModel", - target_name="DynamoDBTarget", - target_description="Target for DynamoDB operations" - ) @@ -124 +41 @@ Here's an example of creating a Smithy model target for DynamoDB: -With this target, your Gateway will expose DynamoDB operations as tools that can be invoked through the MCP interface. +In considering using Smithy models with AgentCore Gateway, review the following feature support table. @@ -126 +43 @@ With this target, your Gateway will expose DynamoDB operations as tools that can -## Smithy Feature Support +### Smithy feature support for AgentCore Gateway @@ -130 +47 @@ The following table outlines the Smithy features that are supported and unsuppor -Smithy Feature Support Supported Features | Unsupported Features +Smithy feature support Supported Features | Unsupported Features @@ -187 +104 @@ Smithy Feature Support Supported Features | Unsupported Features -When using Smithy models with Gateway, be aware of the following limitations: +## Smithy model specification @@ -189 +106 @@ When using Smithy models with Gateway, be aware of the following limitations: - * Maximum model size: 10MB +AgentCore Gateway provides built-in Smithy models for common AWS services via an AWS-provided S3 bucket that hosts the Smithy files. You can pass the Smithy file URIs to the create target API. @@ -191 +108 @@ When using Smithy models with Gateway, be aware of the following limitations: - * Only JSON protocol bindings are fully supported +To see Smithy models for AWS services, see the [AWS API Models repository](https://github.com/aws/api-models-aws). @@ -193 +110 @@ When using Smithy models with Gateway, be aware of the following limitations: - * Only RestJson protocol is supported +After you define your Smithy model, you can do one of the following: @@ -195 +112,3 @@ When using Smithy models with Gateway, be aware of the following limitations: - * Complex endpoint creation rule sets are not supported + * Upload it to an Amazon S3 bucket and refer to the S3 location when you add the target to your gateway. + + * Paste the definition inline when you add the target to your gateway. @@ -197 +115,0 @@ When using Smithy models with Gateway, be aware of the following limitations: - * Only simple URL parameters like {region} are supported @@ -200,0 +119 @@ When using Smithy models with Gateway, be aware of the following limitations: +Expand a section to see examples of supported and unsupported Smithy model specifications: @@ -202 +121 @@ When using Smithy models with Gateway, be aware of the following limitations: -Example of a supported Smithy model for a weather service: +The following example shows a valid Smithy model specification for a weather service: @@ -255,2 +174 @@ Example of a supported Smithy model for a weather service: - -Example of an unsupported endpoint rules configuration: +The following example shows an invalid endpoint rules configuration using Smithy: @@ -271,214 +188,0 @@ Example of an unsupported endpoint rules configuration: - -## Creating a Smithy target - -You can add a Smithy target to your Gateway using one of the following methods: - -Console - - -###### To add a Smithy target to an existing gateway - - 1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home#](https://console.aws.amazon.com/bedrock-agentcore/home#). - - 2. Choose **Gateways**. - - 3. Select the gateway to which you want to add a target. - - 4. Choose the **Targets** tab. - - 5. Choose **Add target**. - - 6. Enter a **Target name**. - - 7. (Optional) Provide an optional **Target description**. - - 8. For **Target type** , choose **REST API**. - - 9. Choose **Smithy schema**.