AWS bedrock-agentcore documentation change
Summary
Expanded session stickiness documentation to include HTTP passthrough targets with custom session identifiers and configurable timeouts.
Security assessment
The change adds documentation for configurable session management features (custom identifiers/timeouts), which are security-related controls for session affinity. However, there is no evidence this addresses a specific existing vulnerability.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-rules-session-stickiness.md b/bedrock-agentcore/latest/devguide/gateway-rules-session-stickiness.md index 7c76fff4d..9f1999ab2 100644 --- a//bedrock-agentcore/latest/devguide/gateway-rules-session-stickiness.md +++ b//bedrock-agentcore/latest/devguide/gateway-rules-session-stickiness.md @@ -7 +7 @@ -How session stickiness worksImportant behaviors +How session stickiness worksConfigure session stickiness for passthrough targetsImportant behaviors @@ -17,5 +17 @@ To solve this, the gateway supports session stickiness. When you include a sessi -The gateway uses the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header to identify sessions. The header value must be a minimum of 33 characters. - -You do not need to send this header on the first request. If the header is absent, the agent runtime auto-generates a session ID. The gateway uses that auto-generated session ID for stickiness on subsequent requests if you include it. - -The stickiness flow works as follows: +The gateway identifies a session by extracting a session ID from each request. The stickiness flow works as follows: @@ -31,0 +28,55 @@ The stickiness flow works as follows: +How the gateway determines the session ID depends on the target type: + + * **AgentCore Runtime targets** – The gateway uses the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header. The header value must be a minimum of 33 characters. You do not need to send this header on the first request. If the header is absent, the agent runtime auto-generates a session ID, and the gateway uses that auto-generated session ID for stickiness on subsequent requests if you include it. + + * **HTTP passthrough targets** – By default, the gateway uses the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header. You can also configure a custom session identifier and timeout on the target, so passthrough clients that use their own session header do not have to adopt the runtime session header. For more information, see Configure session stickiness for passthrough targets. + + + + +## Configure session stickiness for passthrough targets + +For HTTP passthrough targets, you can set an optional `stickinessConfiguration` in the target configuration to control how the gateway identifies sessions and how long session affinity lasts. This is useful when your clients already send their own session header and you don’t want to require them to also send the standard runtime session header. + +The `stickinessConfiguration` object contains: + + * **identifier** (required) – An expression that tells the gateway where to find the session ID in the request. Currently, the gateway can resolve the session ID only from a request header. You can specify the header in either of these forms: + + * A plain HTTP header name, such as `x-session-id`. The gateway reads the session ID from that request header. + + * A context path expression of the form `$.AMZN_AC_GW_CONTEXT.headers.{header-name}`, such as `$.AMZN_AC_GW_CONTEXT.headers.x-session-id`. + +Only the `headers` source is supported today. Other sources (for example, a JWT claim) are not currently available. + + * **timeout** (optional) – The session affinity timeout, in seconds, from 1 to 86400 (24 hours). After this duration of inactivity, the session affinity expires. The window resets on each request (sliding window). + + + + +When a target has a `stickinessConfiguration`, the gateway resolves the session ID from the configured `identifier`. + +The following example creates a passthrough target with a `stickinessConfiguration` that extracts the session ID from a custom `x-session-id` header and expires session affinity after 8 hours (28800 seconds): + + + aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ + "gatewayIdentifier": "GATEWAY_ID", + "name": "my-passthrough-target", + "targetConfiguration": { + "http": { + "passthrough": { + "endpoint": "https://my-service.example.com", + "protocolType": "CUSTOM", + "stickinessConfiguration": { + "identifier": "$.AMZN_AC_GW_CONTEXT.headers.x-session-id", + "timeout": 28800 + } + } + } + }, + "credentialProviderConfigurations": [ + {"credentialProviderType": "GATEWAY_IAM_ROLE"} + ] + }' + +For more information about passthrough targets, see [HTTP passthrough targets](./gateway-target-http-passthrough.html). + @@ -36 +87 @@ The stickiness flow works as follows: -**Sessions expire after 15 days of inactivity.** The expiration window resets on each request (sliding window). After a session expires, use a new session ID for new sessions to avoid unexpected routing behavior. We recommend that you do not reuse expired session IDs. +**Sessions expire after a period of inactivity.** The expiration window resets on each request (sliding window). For AgentCore Runtime targets, sessions expire after 15 days of inactivity. For HTTP passthrough targets, the expiration window is the `timeout` you set in the target’s `stickinessConfiguration` (1 to 86400 seconds); if you don’t set a timeout, the default applies. After a session expires, use a new session ID for new sessions to avoid unexpected routing behavior. We recommend that you do not reuse expired session IDs. @@ -40 +91 @@ The stickiness flow works as follows: -**Supported for HTTP proxy targets only.** Session stickiness is not supported for MCP targets. +**Supported for AgentCore Runtime and HTTP passthrough targets.** Session stickiness is not supported for MCP targets.