AWS Security Blog
AWS STS simplifies session token size limits and adds session token size monitoring
AWS Security Token Service (AWS STS) has simplified session token size limits, giving you more room for your session policies and session tags. STS has replaced the packed policy size and the overall session token size limits with a single token size limit of 4,096 bytes. STS now reports session token size in API responses, Amazon CloudWatch metrics, and AWS CloudTrail events. By using STS, you can also generate session tokens of different sizes, so you can find the maximum token size that your infrastructure can support.
The 4,096-byte limit is the current maximum, not a permanent ceiling. AWS might increase the limit as new capabilities are added that require session tokens to carry more information.
In this post, you learn what has changed, what this change means for you, and what to do next.
What has changed
AWS STS session-vending APIs, such as AssumeRole
, AssumeRoleWithSAML
, AssumeRoleWithWebIdentity
, GetSessionToken
, and GetFederationToken
, return temporary security credentials: an access key ID, a secret access key, and a session token. This change governs the session token, the opaque string that STS creates from the session policies and tags you pass plus the context that AWS adds.
Three things have changed.
- A single limit: Previously, STS enforced two size limits on the session token. It serialized and compressed your session policies and tags into a form called the packed policy, which had its own limit. The assembled token, which included the packed policy, had a separate overall limit. A request could fail against either limit, and both failures returned the same
PackedPolicyTooLargeException
, so you couldn’t tell which one you exceeded. STS now enforces a single limit: the assembled session token must fit within 4,096 bytes. The separate packed policy limit, which made failures hard to predict, has been removed. When a token exceeds the assembled session token limit, STS returnsPackedPolicyTooLargeException
. STS continues to use the same exception, so existing error-handling code works without an SDK update. - Session token size is now reported. Every successful response from an STS session-vending API includes
SessionTokenSize
(which reports the session token size in bytes) andSessionTokenUtilization
(which reports the percentage of the 4,096-byte limit consumed). STS also returnsPackedPolicySize
in every successful response for backward compatibility.PackedPolicySize
now reports the same value asSessionTokenUtilization
, enabling applications that use older AWS SDK versions to monitor utilization through this field. These response fields are also recorded in CloudTrail events. In CloudWatch,SessionTokenSize
andSessionTokenMaxSize
(the enforced limit) are published in the AWS/STS namespace. - Testing is more straightforward:
MinimumSessionTokenSize
is a new optional parameter on the STS session-vending APIs. You can use it to increase a session token to at least the size you specify, up to 4,096 bytes. Use the parameter to find the maximum token size your infrastructure can handle.
| Behavior | Previously | Now |
| Limits enforced | Two: Packed policy size and assembled token size | One: Assembled session token size (4096 bytes) |
| Error on failure | PackedPolicyTooLargeException : The error message didn’t identify which of the two limits was exceeded. |
PackedPolicyTooLargeException : The updated message reports your session token size and the maximum allowed size, both in bytes. |
| Session token size visibility | Not reported |
API Response and AWS CloudTrail:
Amazon CloudWatch:
|
| Infrastructure testing | No mechanism | MinimumSessionTokenSize : Parameter on sesssion-vending APIs |
What this change means for you?
How this affects you depends on your situation. The following scenarios cover the most common cases.
- If you have never hit a token size error: You’re unlikely to notice a change. Your tokens stay their current size and gain headroom. Over time they could become larger than your systems have handled before. We recommend you use
MinimumSessionTokenSize
to find the maximum token size your systems can handle. See the What to do next section for more details. - If you’ve hit
PackedPolicyTooLargeException
before: Some requests that previously failed now succeed under the single limit. Review any workarounds you put in place specifically to avoid token size errors and decide whether you still need them. General best practices still apply: consistent tag casing and reused tag values compress more efficiently, and concise session policies keep the assembled token smaller. No code change is required for error handling. AWS STS still returnsPackedPolicyTooLargeException
when the assembled session token exceeds the limit, the same exception STS returned before this change. - If your systems enforce their own size limits on credentials: If your application uses an AWS SDK to obtain temporary credentials and make AWS API calls, the SDK handles the session token internally, so token size doesn’t affect your code. Focus instead on systems that store or forward session tokens, such as load balancers, proxies, caches, and databases. These systems might have size limits that smaller tokens didn’t reach. For example, a database column defined as
varchar(2048)
can’t hold a 4,096-byte token. Review where you persist or pass session tokens, and identify the maximum token size each system supports. The next section shows how to test this.
What to do next
We recommend the following three steps to prepare your systems for this change.
- Validate the maximum token size your systems can handle. Use
MinimumSessionTokenSize
to find the maximum session token size each system in your infrastructure can handle. Knowing these limits helps you identify systems that might reject or truncate larger tokens. The 4,096-byte limit reflects today’s needs, not a permanent ceiling. It might grow as AWS introduces new capabilities such as additional context keys for new services, richer audit metadata, and larger cryptographic signatures as the industry transitions to post-quantum algorithms. Avoid hard-coding the current maximum into your systems and revisit any fixed size assumptions if the limit changes.
Tip: AWS STS serializes and compresses your session policies and tags when assembling the token. Compression results vary based on the actual content, not just its length. Two sets of tags with identical character counts can produce different token sizes. This is why
MinimumSessionTokenSize
is a more reliable way to test your infrastructure than estimating from input length.Start at 4,096 bytes to test against the largest possible token. If a system truncates or rejects it, lower the value to find the size your infrastructure supports, then raise that limit where you can.
MinimumSessionTokenSize
is available in the latest AWS SDK, AWS Command Line Interface (AWS CLI), and Tools for PowerShell versions. See the STS API Reference for details. If your AWS SDK or AWS CLI predates the parameter, update it to use this feature. - Monitor your session token size (recommended). If your infrastructure has size constraints, you can use monitoring to see tokens that are approaching your limit and act before a request fails. AWS STS reports size through three channels, each suited to a different need.
- In the API response: Reading
SessionTokenUtilization
andSessionTokenSize
from the response requires the latest AWS SDK version. You can also monitor token size through CloudWatch and CloudTrail without updating your SDK.
- In CloudWatch: STS publishes
SessionTokenSize
andSessionTokenMaxSize
in theAWS/STS
namespace. Use them to build dashboards and set alarms. Set your alarm against the size limit you found during testing, not the 4,096-byte maximum. The maximum is the same for every account, so your own infrastructure limit is the one that matters.
The following figure shows the
SessionTokenMaxSize
andSessionTokenSize
metrics graphed in the CloudWatch console.- In CloudTrail: Each STS session-vending event records
SessionTokenUtilization
andSessionTokenSize
for successful calls.
- In the API response: Reading
- Use appropriate fields for monitoring session token utilization. AWS STS still returns
PackedPolicySize
in session-vending API responses and CloudTrail records for backward compatibility. The field now reports the same value asSessionTokenUtilization
: the percentage of the 4,096-byte session token size limit consumed by the token. As a result,PackedPolicySize
values might appear lower even when your token content has not changed.If your SDK exposes
SessionTokenUtilization
, use that field because its name reflects the value’s current meaning. If an earlier SDK does not exposeSessionTokenUtilization
, usePackedPolicySize
to monitor the same utilization percentage without updating the SDK. We recommend you monitorSessionTokenSize
for the token size in bytes.
Conclusion
You now have more room for session tags, tag values, and session policies in your AWS sessions. AWS STS enforces a single 4,096-byte session token limit, returns a clearer error message when a token exceeds it, and reports token size so you can track growth proactively. Validate your token-handling systems with MinimumSessionTokenSize
, and watch SessionTokenUtilization
and SessionTokenSize
for ongoing visibility.
References
- AWS STS API Reference
- Request temporary security credentials
- Session policies
- Pass session tags in AWS STS
If you have feedback about this post, submit comments in the Comments section below.