AWS bedrock-agentcore high security documentation change

Service: bedrock-agentcore · 2025-10-01 · Security-related high

File: bedrock-agentcore/latest/devguide/get-workload-access-token.md

Summary

Added comprehensive documentation about workload access tokens including security controls, token management, and API restrictions

Security assessment

Documentation adds security controls for token API including service-managed identity restrictions, IAM requirements, and token scoping. Explicitly addresses prevention of token misuse and unauthorized access through security boundaries.

Diff

diff --git a/bedrock-agentcore/latest/devguide/get-workload-access-token.md b/bedrock-agentcore/latest/devguide/get-workload-access-token.md
index b9a364b39..b2ada551f 100644
--- a//bedrock-agentcore/latest/devguide/get-workload-access-token.md
+++ b//bedrock-agentcore/latest/devguide/get-workload-access-token.md
@@ -4,0 +5,2 @@
+What is a workload access token?How Runtime and Gateway automatically obtain tokensHow to manually retrieve workload access tokensSecurity controls for GetWorkloadAccessTokenForUserId API
+
@@ -8,0 +11,53 @@ Amazon Bedrock AgentCore is in preview release and is subject to change.
+Understanding what workload access tokens are, how to obtain them, and the security aspects of working with them is essential for building secure agent applications. This section covers the key concepts and implementation patterns you need to know.
+
+###### Topics
+
+  * What is a workload access token?
+
+  * How Runtime and Gateway automatically obtain tokens
+
+  * How to manually retrieve workload access tokens
+
+  * Security controls for GetWorkloadAccessTokenForUserId API
+
+
+
+
+## What is a workload access token?
+
+A workload access token is an AWS-signed opaque access token that enables agents to access first-party AgentCore services, such as outbound credential providers. Runtime automatically delivers workload access tokens to agent execution instances as payload headers, eliminating the need for manual token management in most scenarios.
+
+**Key characteristics:**
+
+  * **First-party services only:** Workload access tokens are exclusively for accessing AWS first-party AgentCore services and cannot be used for external services
+
+  * **Automatic delivery:** Runtime and Gateway automatically provide these tokens to agents during execution
+
+  * **Security by design:** Runtime-managed agent identities cannot retrieve workload access tokens directly, preventing token extraction and misuse
+
+  * **User and agent identity binding:** Tokens contain both user identity and agent identity information for secure credential access
+
+
+
+
+## How Runtime and Gateway automatically obtain tokens
+
+When an agent is invoked through AgentCore Runtime or Gateway with inbound authentication, the service automatically handles workload access token generation:
+
+  1. Runtime validates the inbound identity provider OAuth token (issuer, signature)
+
+  2. Runtime extracts issuer and sub claims from the OAuth token representing user identity
+
+  3. Runtime fetches the associated workload identity of the agent
+
+  4. Runtime invokes `GetWorkloadAccessTokenForJWT` with both user identity and agent workload identity
+
+  5. Runtime passes the workload access token to agent code as part of the invocation payload header
+
+
+
+
+This automatic process ensures agents receive properly scoped tokens without manual intervention.
+
+## How to manually retrieve workload access tokens
+
@@ -28,0 +84,19 @@ The examples below illustrate using the AgentCore SDK to retrieve a workload acc
+## Security controls for `GetWorkloadAccessTokenForUserId` API
+
+The `GetWorkloadAccessTokenForUserId` API implements several security controls to prevent unauthorized access:
+
+  * **Workload identity validation:** The API verifies that the requesting identity has permission to act on behalf of the specified workload identity
+
+  * **Service-managed identity restriction:** Runtime-managed and Gateway-managed workload identities cannot retrieve tokens directly. This prevents agents from extracting tokens for misuse
+
+  * **IAM permission requirements:** Callers must have appropriate IAM permissions including `GetWorkloadAccessToken`, `GetWorkloadAccessTokenForUserId`, and `GetWorkloadAccessTokenForJWT`
+
+  * **Token scoping:** Tokens are scoped to the specific user-agent pair, ensuring credentials stored under one user cannot be accessed by another
+
+
+
+
+If you encounter the error "WorkloadIdentity is linked to a service and cannot retrieve an access token by the caller," this indicates the workload identity is managed by Runtime or Gateway and cannot retrieve tokens directly. This restriction helps maintain security boundaries and prevents unauthorized token access.
+
+For additional security controls, you can implement fine-grained access policies to restrict which workload identities can access specific credential providers. For more information, see [Scope down access to credential providers by workload identity](./scope-credential-provider-access.html).
+