Session Policy

A Session Policy is an inline IAM policy that you pass when you programmatically create a temporary session (via AssumeRole, AssumeRoleWithSAML, AssumeRoleWithWebIdentity, or GetFederationToken).

How It Works

The effective permissions for the session are the intersection of the role's identity-based policies and the session policy. A session policy cannot grant more permissions than the role already has - it can only further restrict them.

Use Cases

• Per-user scoping: a shared role with different session policies per user, limiting each to their own resources
• Temporary restrictions: grant a break-glass role but scope the session to only the affected resources
• Federation: scope federated user access without creating multiple roles

Limits

• The plaintext used for inline and managed session policies combined cannot exceed 2,048 characters
• You can pass up to 10 managed policy ARNs as session policies
• Policies and session tags are also compressed into a packed binary format with its own separate limit; the PackedPolicySize response field shows, as a percentage, how close your request is to that ceiling, and the request fails above 100 percent even if the plaintext is under 2,048 characters

How It Goes Wrong in Practice

The critical thing to understand about session policies is who applies them: the caller. That makes them a self-imposed restriction, not a security boundary against the caller. The failure pattern looks like this: a team builds an access broker that assumes one powerful shared role and passes a per-tenant session policy to scope each session down. The design is sound exactly as long as the broker is the only principal that can assume the role. If the role's trust policy is broader than intended, say it trusts a whole account root, then anyone in that account with sts:AssumeRole permission on it can call AssumeRole directly, pass no session policy at all, and receive the full, unscoped permissions of the role. The session policy protected nothing, because the attacker simply did not include one.

The correct mental model: the role's identity policies define the maximum, the trust policy defines who can reach that maximum, and the session policy is a voluntary reduction the trusted caller applies to its own session, for example to honor least privilege per tenant or to cap the blast radius of a long-running job. If your security depends on the reduction, it must be enforced elsewhere: tighten the trust policy to the broker's principal only, or use conditions on the assume call. A second, more mundane failure is the packed size limit: teams template large per-tenant session policies, the compressed policy-plus-session-tags payload crosses the packed limit, and AssumeRole calls start failing in production for the tenants with the longest resource lists.

A Practical Check

Pass an inline session policy while assuming a role and observe the effect:

aws sts assume-role --role-arn arn:aws:iam::123456789012:role/SupportRole --role-session-name tenant-42 --policy file://scope.json

The response contains temporary credentials plus a PackedPolicySize percentage. Keep an eye on that value in your broker's logs: if it trends toward 100, your next larger tenant will break. You can also pass managed policies by ARN with --policy-arns, up to 10 of them, sharing the same 2,048 character plaintext budget with the inline policy.

Frequently Asked Questions

Can a session policy add permissions the role does not have? No. The session's effective permissions are the intersection of the role's identity-based policies and the session policy. Passing an admin session policy on a read-only role still yields a read-only session. This also means a session policy can never be used to escalate; its only failure direction is restricting less than you intended.

Who decides whether a session policy is applied? The entity calling AssumeRole (or the other STS operations that accept one). Nothing forces a caller to pass a session policy, which is why it protects against your own trusted automation being over-broad, not against a hostile caller. The enforced controls are the role's permissions, its trust policy, and any SCPs or permission boundaries in play.

Session policy or permission boundary: which one do I need? They cap permissions at different moments. A permission boundary is attached to a user or role by an administrator and applies to everything that identity does, always. A session policy applies to one temporary session and is chosen per call by the caller. Use boundaries to constrain identities you hand out; use session policies to let one shared role safely serve many differently-scoped sessions.