AWS bedrock-agentcore documentation change
Summary
Added legacy vs new agent permission requirements based on creation date
Security assessment
Clarifies security configuration requirements for different agent versions but does not address an active vulnerability. Helps maintain secure configurations during transition periods.
Diff
diff --git a/bedrock-agentcore/latest/devguide/runtime-oauth.md b/bedrock-agentcore/latest/devguide/runtime-oauth.md index bb312adc7..8d37ef241 100644 --- a//bedrock-agentcore/latest/devguide/runtime-oauth.md +++ b//bedrock-agentcore/latest/devguide/runtime-oauth.md @@ -23,0 +24,2 @@ The default authentication and authorization mechanism that works automatically +**X-Amzn-Bedrock-AgentCore-Runtime-User-Id Header** + @@ -25,0 +28,12 @@ If your solution requires the hosted agent to retrieve OAuth tokens on behalf of +###### Note + +Invoking InvokeAgentRuntime with the `X-Amzn-Bedrock-AgentCore-Runtime-User-Id header` will require a new IAM action: `bedrock-agentcore:InvokeAgentRuntimeForUser`, in addition to the existing `bedrock-agentcore:InvokeAgentRuntime` action. + +**Security Best Practices for X-Amzn-Bedrock-AgentCore-Runtime-User-Id Header** + +While IAM authentication secures the API access, the `X-Amzn-Bedrock-AgentCore-Runtime-User-Id` header requires additional security considerations. Only trusted principals with the `bedrock-agentcore:InvokeAgentRuntimeForUser` permission should be allowed to set this header. The user-id value should ideally be derived from the authenticated principal’s context (for example, IAM context or user token) rather than accepting arbitrary values. This prevents scenarios where an authenticated user could potentially impersonate another user by manually specifying a different `user-id`. + +Implement audit logging to track the relationship between the authenticated principal and the `user-id` being passed. + +Remember that Amazon Bedrock AgentCore treats this header value as an opaque identifier and relies on your application's logic to maintain the security boundary between authenticated users and their corresponding `user-id` values. + @@ -224,0 +239,34 @@ This script creates a Cognito user pool, a user pool client, adds a user, and ge +###### Service-Linked Role Change - Effective October 13, 2025 + +Starting **October 13, 2025** , Amazon Bedrock AgentCore uses a Service-Linked Role (SLR) for workload identity permissions instead of requiring manual IAM policy configuration for new agents. + +The Service-Linked Role details: + + * **Name:** `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity` + + * **Service Principal:** `runtime-identity.bedrock-agentcore.amazonaws.com` + + * **Purpose:** Manages workload identity access tokens and OAuth credentials + + + + +Ensure the role you use to invoke AgentCore Control APIs has permission to create the Service-Linked Role: + + + { + "Sid": "CreateBedrockAgentCoreIdentityServiceLinkedRolePermissions", + "Effect": "Allow", + "Action": "iam:CreateServiceLinkedRole", + "Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity", + "Condition": { + "StringEquals": { + "iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com" + } + } + } + +**Benefit** : The Service-Linked Role automatically provides the necessary permissions for workload identity access without requiring manual policy configuration. + +For detailed information about the service-linked role, see [Identity service-linked role](./service-linked-roles.html#identity-service-linked-role). + @@ -299 +347,3 @@ Now that your agent is deployed with JWT authorization, you can invoke it using -Make sure your agent’s execution role has permissions to access the workload identity. +###### Legacy Agent Permissions + +**Important for existing users** : Agents created **before October 13, 2025** will continue to use the agent execution role for identity permissions and **require** the above policy to be attached to the agent's execution role. @@ -300,0 +351 @@ Make sure your agent’s execution role has permissions to access the workload i +**New agents** : For agents created **on or after October 13, 2025** , this policy is **not required** as permissions are handled automatically by the Service-Linked Role. @@ -301,0 +353,2 @@ Make sure your agent’s execution role has permissions to access the workload i + + { @@ -316,0 +370,2 @@ Make sure your agent’s execution role has permissions to access the workload i +**Invoke the agent** + @@ -326,0 +382,2 @@ Fetch a bearer token for the user you created with Amazon Cognito. +Proceed to invoke the agent with the rest of the following instructions. +