AWS bedrock-agentcore documentation change
Summary
Restructured documentation to clearly differentiate between JWT-based and UserId-based token retrieval patterns. Added security warnings, recommended controls, and explicit tradeoffs for UserId-based method.
Security assessment
The changes emphasize security differences between token retrieval methods. They explicitly warn that UserId-based tokens lack verification and add recommended security controls (IAM restrictions, audit logging, source validation) without referencing any specific vulnerability or incident.
Diff
diff --git a/bedrock-agentcore/latest/devguide/get-workload-access-token.md b/bedrock-agentcore/latest/devguide/get-workload-access-token.md index 1e15e8861..7e24dc9cf 100644 --- a//bedrock-agentcore/latest/devguide/get-workload-access-token.md +++ b//bedrock-agentcore/latest/devguide/get-workload-access-token.md @@ -66 +66 @@ There are two patterns to use to retrieve the workload access token depending on - * If the agent’s caller has a JWT identifying the end user, request a workload access token based on the agent’s identity and the end-user JWT. When you provide a JWT, AgentCore Identity will validate the JWT to ensure it is correctly signed and unexpired, and it will use its “iss” and “sub” claims to uniquely identify the user. Credentials stored by the agent on behalf of the user will be associated with this information, and future retrievals by the agent will require a valid workload access token containing the same information. +### Pattern 1: JWT-based identification (recommended for production) @@ -68 +68 @@ There are two patterns to use to retrieve the workload access token depending on - * If the agent’s caller does not have a JWT identifying the end user, request a workload access token based on the agent’s identity and a unique string identifying the user. +If the agent’s caller has a JWT issued by an identity provider for the end user, request a workload access token using `GetWorkloadAccessTokenForJWT`. When you provide a JWT, AgentCore Identity validates the token to ensure it is correctly signed and unexpired, and uses its “iss” and “sub” claims to uniquely identify the user. Credentials stored by the agent on behalf of the user are associated with this cryptographically verified identity, and future retrievals require a valid workload access token carrying the same identity. @@ -69,0 +70 @@ There are two patterns to use to retrieve the workload access token depending on +**Use this pattern when:** @@ -70,0 +72 @@ There are two patterns to use to retrieve the workload access token depending on + * Your application integrates with an identity provider (Cognito, Auth0, Okta, etc.) @@ -71,0 +74,25 @@ There are two patterns to use to retrieve the workload access token depending on + * You need cryptographic proof of the end user’s identity + + * You are deploying to production + + + + +### Pattern 2: UserId-based identification + +If the agent’s caller does not have a JWT identifying the end user, request a workload access token using `GetWorkloadAccessTokenForUserId` with a unique string identifying the user. + +**Use this pattern when:** + + * Your application manages its own user identifiers and you need to pass customer-managed userId strings to AgentCore Identity + + * You are in a development or quickstart scenario where an IdP token is not yet available + + * Your enterprise architecture resolves user identity upstream and passes a trusted identifier to the agent workload + + + + +**Tradeoff:** The platform treats the userId as an opaque string and cannot verify it against an authenticated end-user identity. The security binding relies on the calling workload passing the correct userId and on IAM policies being scoped appropriately. See Security controls for GetWorkloadAccessTokenForUserId API for recommended controls. + +### Code examples @@ -78,5 +105,5 @@ The examples below illustrate using the AgentCore SDK to retrieve a workload acc - identity_client= IdentityClient("us-east-1")# Obtain a token using the IAM identity of the caller to authenticate the agent and providing a JWT containing the identity of the end user. - # This is the recommended pattern whenever a JWT is available for the user. - workload_access_token= identity_client.get_workload_access_token(workload_name= "my-demo-agent", user_token= "insert-jwt-here")# Obtain a token using the IAM identity of the caller to authenticate the agent and providing a string representing the identity of the end user. - # Use this pattern when a JWT is not available for the user. - workload_access_token= identity_client.get_workload_access_token(workload_name= "my-demo-agent", user_id= "insert-user-name-or-identifier") + identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user. + # AgentCore Identity validates the JWT signature, issuer, and expiry. + workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user. + # Use this when a JWT is not available. The platform does not verify this string. + workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”) @@ -85,0 +113,6 @@ The examples below illustrate using the AgentCore SDK to retrieve a workload acc +The `GetWorkloadAccessTokenForUserId` API accepts a caller-supplied user identifier string and issues a workload access token scoped to that user-agent pair. This API is designed to support enterprise customers who need to pass customer-managed userId strings and builders who don’t have Identity Provider (IdP) tokens available during development. + +###### Important + +When you use `GetWorkloadAccessTokenForUserId`, the platform treats the `userId` value as an opaque string and does not verify it against an authenticated end-user identity. The security binding relies entirely on the calling workload passing the correct userId and on your IAM policies being scoped appropriately. If your application has access to a JWT identifying the end user, use `GetWorkloadAccessTokenForJWT` instead, which validates the token’s issuer, signature, and expiry before issuing a workload access token. + @@ -100,0 +134,28 @@ The `GetWorkloadAccessTokenForUserId` API implements several security controls t +### Recommended security controls + +Because the platform cannot verify the userId string, you are responsible for ensuring the integrity of the value passed to this API. Apply the following controls: + + * **Prefer`GetWorkloadAccessTokenForJWT` when a JWT is available** – The JWT-based path validates the token’s issuer and signature, providing cryptographic proof of the user’s identity. Use `GetWorkloadAccessTokenForUserId` only when a JWT is unavailable. + + * **Derive the userId from a trusted source** – The userId value should be derived from the authenticated principal’s context (for example, IAM caller identity, session attributes, or an upstream identity resolution layer) rather than accepting arbitrary client-supplied values. This prevents an authenticated caller from impersonating another user. + + * **Restrict the IAM permission** – Only trusted principals should have the `bedrock-agentcore:GetWorkloadAccessTokenForUserId` permission. Scope this permission to specific workload identity resources. Do not grant it broadly via managed policies or wildcard resource statements. + + * **Deny`GetWorkloadAccessTokenForUserId` where it is not needed** – For workloads that always have a JWT available, explicitly deny the action in IAM policies to prevent the userId path from being used: + + { + "Statement": [ + { + "Sid": "DenyForUserIdAccess", + "Effect": "Deny", + "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId", + "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default" + } + ] + } + + * **Implement audit logging** – Log the relationship between the authenticated IAM principal and the userId value being passed. Use AWS CloudTrail to monitor `GetWorkloadAccessTokenForUserId` calls and detect unexpected userId values. + + + +