AWS bedrock-agentcore documentation change
Summary
Updated documentation to focus on AgentCore Gateway service role permissions, added detailed guidance for configuring trust policies, outbound authorization, and AWS resource access permissions. Includes examples for Lambda and DynamoDB permissions.
Security assessment
The changes add detailed security documentation about IAM role trust policies, cross-account access controls, and least-privilege permissions for service roles. While these are security best practices, there's no evidence they address a specific existing vulnerability. The note about adding Condition fields with aws:SourceArn/Account in trust policies improves security posture by implementing resource-based constraints.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-prerequisites-permissions.md b/bedrock-agentcore/latest/devguide/gateway-prerequisites-permissions.md index 40a606a03..a9c37218b 100644 --- a//bedrock-agentcore/latest/devguide/gateway-prerequisites-permissions.md +++ b//bedrock-agentcore/latest/devguide/gateway-prerequisites-permissions.md @@ -5 +5 @@ -Gateway Management PermissionsGateway Access Permissions or Inbound Auth ConfigurationGateway Execution Permissions or Outbound Authorization configurationBest practices for Gateway permissions +Gateway Management PermissionsGateway Access Permissions or Inbound Auth ConfigurationAgentCore Gateway service role permissionsBest practices for Gateway permissions @@ -7,3 +7 @@ Gateway Management PermissionsGateway Access Permissions or Inbound Auth Configu -Amazon Bedrock AgentCore is in preview release and is subject to change. - -# Prerequisites to set up a gateway +# Set up permissions for AgentCore Gateway @@ -15 +13 @@ When working with Gateways, there are three main categories of permissions to co - 1. Gateway Management Permissions \- Permissions needed to create and manage Gateways + 1. Gateway management permissions \- Permissions needed to create and manage Gateways @@ -19 +17,12 @@ When working with Gateways, there are three main categories of permissions to co - 3. Gateway Execution Permissions or Outbound Authorization configuration \- Permissions that a Gateway needs to perform actions on other resources and services + 3. Gateway execution permissions \- Permissions provided to a service role to allow the Amazon Bedrock AgentCore service to perform actions on behalf of the identity that invokes the gateway. + + + + +###### Topics + + * Gateway Management Permissions + + * Gateway Access Permissions or Inbound Auth Configuration + + * AgentCore Gateway service role permissions @@ -20,0 +30 @@ When working with Gateways, there are three main categories of permissions to co + * Best practices for Gateway permissions @@ -24 +33,0 @@ When working with Gateways, there are three main categories of permissions to co -You'll configure Gateway Access Permissions when [Creating gateways](./create-gateway.html) in the next section, and Gateway Execution Permissions when [Adding targets](./gateway-building-adding-targets.html). @@ -100 +109,12 @@ Unlike other AWS services, which use standard AWS IAM mechanisms for access cont -You'll configure these permissions when [Creating gateways](./create-gateway.html) in the next section. +You'll configure these permissions when [Creating gateways](./gateway-create.html) in the next section. + +## AgentCore Gateway service role permissions + +When creating a gateway, you need a service role that has permissions to assume an IAM role and to access AWS resources and external services on the IAM role's behalf. You can create the service role in the following ways: + + * If you create a gateway in the AWS Management Console or through the AgentCore starter toolkit, you can choose to let AgentCore automatically create a service role for you with the necessary permissions. If you prefer this method, you can skip this prerequisite. + + * If you prefer to create your own service role for greater customization, you'll need to configure the role with the permissions outlined in this topic. To learn how to create a service role and attach permissions to it, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html). + + + @@ -102 +122 @@ You'll configure these permissions when [Creating gateways](./create-gateway.htm -## Gateway Execution Permissions or Outbound Authorization configuration +The required permissions for a service role are in the following topics: @@ -104 +124 @@ You'll configure these permissions when [Creating gateways](./create-gateway.htm -When creating a Gateway, you need to provide an execution role that will be used by the Gateway to access AWS resources or external services. This role defines the permissions that the Gateway has when making requests to other services. Based on the type of target, the role would either have permissions to access the AWS resources configured for the target, or for external resources, the role would have permissions to acquire the needed authorization to invoke the external resources. You will configure these after you have setup your gateway while [Adding targets](./gateway-building-adding-targets.html). +###### Topics @@ -106 +126,14 @@ When creating a Gateway, you need to provide an execution role that will be used -At the very least, whatever type of target is being configured, the execution role must have a trust policy that allows the Amazon Bedrock AgentCore service to assume the role: + * Trust permissions + + * Outbound authorization permissions + + * Permissions to access AWS resources + + + + +### Trust permissions + +A service role must have a [trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#term_trust_policy) attached that allows the AgentCore service to assume an IAM identity and carry out actions on its behalf. + +The following is an example of a trust policy that you can use. @@ -138 +171,158 @@ JSON -For AWS resources as targets like Lambda functions, don't forget to give the Gateway permissions to access it in that resource's (ex. Lambda's) policy as well. +###### Note + +Because you won't know the gateway ARN before you create it, you can omit the `Condition` field when you first create the service role. After you create the gateway, add the `Condition` field back to the policy as a best security practice and do the following: + + * Replace the `aws:SourceAccount` condition key value with the ID of the account that the gateway belongs to. + + * Replace the `aws:SourceArn` condition key with the ARN of the gateway. + + + + +### Outbound authorization permissions + +Depending on the type of outbound authorization you use for your gateway targets, you need to add permissions to the service role to allow it to invoke the target. These permissions allow the gateway service role to retrieve authorization credentials for invoking the target. You can do this in the process of [setting up outbound authorization](./gateway-outbound-auth.html). + +### Permissions to access AWS resources + +Depending on your gateway setup or the targets that you choose to add to the gateway, you might need to add permissions to the gateway service role to allow it to access AWS resources. The following topics cover some resources that your gateway service role might need access to: + +If you attach a Lambda target to your gateway, you need to add permissions for the AgentCore Gateway service role to be able to invoke the function by doing the following: + + * Attach an identity-based policy to the AgentCore Gateway service role that allows the `lambda:InvokeFunction` action on the Lambda function resource. + + * (If the function is in a different account from the gateway service role) Attach a resource-based policy to the Lambda function that allows the gateway service role principal to perform the `lambda:InvokeFunction` action on the Lambda function resource. + + + + +Select a topic to learn how to set up the permissions: + +###### Topics + + * Attach an identity-based policy to the gateway service role + + * (If function is in another account) Attach a resource-based policy to the Lambda function + + + + +##### Attach an identity-based policy to the gateway service role + +To allow the gateway service role to access a Lambda target, attach the following identity-based policy to your AgentCore Gateway service role by choosing the topic at [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) that pertains to your use case and following the steps.. + + + { + "Version": "2012-10-17", + "Statement": [{ + "Sid": "AmazonBedrockAgentCoreGatewayLambdaProd", + "Effect": "Allow", + "Action": [ + "lambda:InvokeFunction" + ], + "Resource": [ + "arn:aws:lambda:us-east-1:123456789012:function:FunctionName" + ] + }] + } + +Replace the ARN in the `Resource` field with the ARN of your Lambda function gateway target. If your gateway has multiple Lambda targets, you can add the ARN of each function to the `Resource` list. + +##### (If function is in another account) Attach a resource-based policy to the Lambda function + +If the Lambda function target is in a different account from the gateway service role, you need to attach a resource-based policy to allow the gateway service role to access it. The following is an example policy that you can use: + + + { + "Version":"2012-10-17", + "Statement": [ + { + "Sid": "LambdaAllowGatewayServiceRoleMyFunction", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::123456789012:role/MyGatewayExecutionRole" + }, + "Action": "lambda:InvokeFunction", + "Resource": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction" + } + ] + } + +Replace the values of the following fields: + + * `AWS` – Use the ARN of your gateway service role. + + * `Resource` – Use the ARN of your Lambda function. + + + + +To learn how to attach a resource-based policy to the Lambda function that allows your gateway service role to access the function, select one of the following methods:: + +Console + + +###### To attach a resource-based policy to your Lambda function in the AWS Management Console + + 1. Follow the steps in the **Console** tab at [Viewing resource-based IAM policies in Lambda](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html). + + 2. In the **Resource-based policy statements** section, choose **Add permissions**. + + 3. Select **AWS account** and fill out the following fields: + + * **Statement ID** – A unique identifier for the the statement providing permissions for the gateway service role to access the function. + + * **Principal** – Specify the ARN of your gateway service role. + + * **Action** – Select `lambda:InvokeFunction`. + + + + +CLI + + +To attach a resource-based policy to your Lambda function using the AWS CLI, follow the steps at [Granting Lambda function access to AWS services](https://docs.aws.amazon.com/lambda/latest/dg/permissions-function-services.html) and specify your gateway service role as the `principal`. + +You can run the following code in a terminal to add permissions for your gateway service role to access the function in `us-east-1`: + + + aws lambda add-permission \ + --function-name "MyFunction" \ + --statement-id "GatewayInvoke" \ + --action "lambda:InvokeFunction" \ + --principal "arn:aws:iam::123456789012:role/MyGatewayServiceRole" + --region us-east-1 + +If you plan to add a Smithy target, you need to add permissions for the gateway service role to access AWS services that your Smithy models refer to. To determine which permissions need to be attached to the service role, refer to that service's documentation. + +You can add permissions to the service role by choosing the topic at [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) that pertains to your use case and following the steps.