AWS Security Blog
Scope down permissions of existing sessions using AWS STS GetScopedCredentials
When you build AI agents, you often want each agent or sub-agent to have only the permissions its tasks require, rather than the full permissions of the session that started it. GetScopedCredentials is a new AWS Security Token Service (AWS STS) API that you can use to scope down the permissions of existing temporary security credentials. You can assign each agent, sub-agent, or process its own set of credentials that keep the caller’s AWS Identity and Access Management (IAM) identity but carry reduced permissions, a shorter session duration, or both.
You can call GetScopedCredentials with the temporary security credentials you already use, such as those from aws login, an Amazon Elastic Compute Cloud (Amazon EC2) instance profile, or an AWS Lambda function. In each call, you pass a scope down policy, a shorter session duration, or both. A scope down policy is an inline policy that describes the maximum permissions for the new credentials. The resulting permissions are the intersection of your session’s effective permissions and the scope down policy, so they can only be reduced. Similarly, the session duration you request can’t exceed the remaining duration of the calling session. You can also call GetScopedCredentials again with the resulting credentials to scope down permissions or reduce session duration even further.
GetScopedCredentials is designed as a building block. Because it scopes down permissions on the credentials you already have, you can build it into agent frameworks, services that issue credentials to other components, continuous integration and deployment (CI/CD) pipelines, and your own applications. You can also call it again with scoped-down credentials, so an orchestrating agent can give each sub-agent narrower access than its own.
In this post, we walk through a few common use cases to get you started, show you how to call GetScopedCredentials, and explain how to manage access to it.
Example use cases
You can use GetScopedCredentials whenever a workload needs narrower access than the session that starts it. Examples include limiting what AI agents can do, scoping down permissions based on runtime context, and granting just-in-time access. We cover two of the most common use cases in more detail in this section.
Limit what AI agents can do
When you pass credentials to an agent, the agent can use any permission those credentials carry. An agent decides which actions to take at runtime, often based on prompts or tool output. If its credentials are overly permissive, an agent that makes a mistake can act beyond the task you gave it.
Before you pass credentials to an agent, you can use GetScopedCredentials to scope down permissions to only what its tasks require, such as read access to a single Amazon Simple Storage Service (Amazon S3) bucket. You could also take the opposite approach and keep most of its permissions while removing only the actions the agent should never perform, such as deleting resources. An orchestrating agent can do the same for each sub-agent it starts. Because a scope down operation can only narrow permissions, a sub-agent never has more access than the agent that started it. To help ensure that your agents only have access to the scoped-down credentials, run them in isolated or sandbox environments such as AWS Strands Box.
Scope down permissions based on runtime context
Many workloads run under a single IAM role but need different, narrower permissions for each task they perform. The right set of permissions for a task often depends on information the workload learns only at runtime, such as who sent a request.
Consider a multi-tenant application that stores each tenant’s files under a separate prefix in one S3 bucket. This application uses a single IAM role to serve all its tenants, so the role can access every tenant’s prefix. However, each request should reach only the files of the tenant who sent it, and the application learns which tenant that is only after it authenticates the request. At that point, a trusted credential broker in the application takes the tenant details from the authenticated session and calls GetScopedCredentials with a scope down policy that allows access only to that tenant’s prefix. It passes only the scoped-down credentials to the worker that handles the request, so Amazon S3 denies that worker access to other tenants’ prefixes even though the original role covers them all.
How to call GetScopedCredentials
This section walks through the process of scoping down permissions for an existing session. Before you call GetScopedCredentials, make sure you have valid temporary security credentials and that they have the permissions to call the API. The following identity based policy grants that permission.
To call GetScopedCredentials, use the latest version of the AWS Command Line Interface (AWS CLI) or the AWS SDK for your programming language.
Step 1: Define a scope down policy
Write a scope down policy that describes the maximum permissions the resulting credentials should have. At launch, GetScopedCredentials accepts one inline scope down policy of up to 2,048 characters. You can write a scope down policy in many ways, such as authoring a policy from scratch, reusing or modifying an existing policy, or asking an AI assistant to draft one. This section covers two such approaches.
Option A: Write the policy yourself
If you know which actions and resources your task needs, write the policy directly. The following sample policy allows the resulting credentials to only read objects from a single S3 bucket.
Make sure to include every action the task needs, including dependent actions. For example, if your task uses Amazon Athena to query data in Amazon S3, the policy must also allow s3:GetObject on that data, because Athena reads it with your credentials.
To keep most of the calling session’s permissions and remove only a few sensitive ones, use an Allow statement with NotAction. This statement doesn’t grant additional access, because a scope down policy can only reduce permissions. The resulting credentials keep the calling session’s permissions except the actions you list, which makes this a quick way to set guardrails without listing each action a task needs. The following sample policy blocks identity and account management, assuming other roles, and deleting some critical resources.
Option B: Generate the policy with IAM Policy Autopilot
You can also use IAM Policy Autopilot to generate a scope down policy. IAM Policy Autopilot is an open source tool from AWS that analyzes the AWS SDK calls in your code and identifies the permissions it requires to run successfully. You can run it from the command line or as a Model Context Protocol (MCP) server in your AI coding assistant. To install it, see the Getting Started instructions for IAM Policy Autopilot.
We’ll use the following Python code to generate a scope down policy using IAM Policy Autopilot. It records a report’s status in an Amazon DynamoDB table.
Save the code as report_status.py and run the following command. If the generated policy exceeds the 2,048 character limit, set the max-policy-size and allow-overpermissive-wildcards-to-limit-total-output-size options to 2048. IAM Policy Autopilot then replaces groups of actions with wildcards to fit that size and warns you if it can’t.
IAM Policy Autopilot returns the following policy.
IAM Policy Autopilot generates a starting policy that can include wildcards, either because specific resources can’t be inferred from the code, such as with the table/* and key/* resources in this example, or because an optional parameter that limits policy size replaced actions with wildcards. Review the generated policies and replace the wildcards with the actions and resources your task should access.
However you create the policy, save it as scope-down-policy.json. If you want to continue calling GetScopedCredentials with the resulting credentials, also include the sts:GetScopedCredentials action in the Allow block of the permission policy.
Step 2: Call GetScopedCredentials
Pass the scope down policy you created to GetScopedCredentials. The following command also uses the optional duration-seconds parameter to limit the resulting session duration and the optional scoped-session-description parameter to record context for the scoped-down credentials. If you omit the duration-seconds parameter, the credentials keep the calling session’s remaining duration.
The response includes a new set of temporary security credentials, a SessionInfo element, and some helpful information about session size and contents.
Notice that the Amazon Resource Name (ARN) in the SessionInfo element matches the ARN of your calling session. The scoped-down credentials retain the identity of the calling session, including the role session name, session tags and context keys.
The ScopedPoliciesCount value in the response shows how many scope down policies apply to the session. It increases only when a recursive call adds a new scope down policy and not when a call only shortens the session duration.
Each GetScopedCredentials call is logged in AWS CloudTrail. The following event, shortened for readability, shows the call from this example.
The scopedSessionDescription value in the CloudTrail event records the text you passed to the API call earlier. Later calls made with the scoped-down credentials show the scoped down session’s access key ID in userIdentity.accessKeyId, which can be used to trace back to its immediate parent session.
Step 3 (optional): Scope down the credentials again
You can call GetScopedCredentials recursively with the scoped-down credentials to narrow permissions or reduce session duration even further. You can apply a maximum of three scope down policies to a session, and each new scope down policy intersects with all prior ones. Recursive calls that only shorten the session duration and don’t add a scope down policy don’t count toward this limit. For a recursive call to succeed, every earlier scope down policy must allow the sts:GetScopedCredentials action.
Managing access to GetScopedCredentials
You can control access to the sts:GetScopedCredentials action in all relevant policy types. You can also use the sts:DurationSeconds condition key to limit the session duration of scoped-down credentials, and global condition keys such as aws:PrincipalArn, aws:PrincipalTag, and aws:SourceVpce to restrict who can call the API and from where.
Availability and request quota
GetScopedCredentials is available in all AWS commercial Regions, AWS GovCloud (US) Regions, and the China Regions. The API has a dedicated request quota of 200 requests per second per account in each Region at launch. You can use scoped-down credentials with most AWS services. For a list of services that aren’t supported, see the GetScopedCredentials API reference.
Conclusion
GetScopedCredentials gives you a building block for reducing permissions at runtime. This is particularly helpful when you want to give each agent, sub agent or workload only the access it needs.
For more information about GetScopedCredentials, see the GetScopedCredentials API reference. To learn how permissions are evaluated for scoped-down credentials, see Permissions for GetScopedCredentials and Policy evaluation for requests within a single account. Now go build!
If you have feedback about this post, submit comments in the Comments section below. If you have questions about this post, start a new thread on AWS re:Post or contact AWS Support.