
Trying Out AWS STS GetScopedCredentials to Narrow Down Permissions and Session Duration of Temporary Credentials
This page has been translated by machine translation. View original
Introduction
On November 19, 2026, AWS STS GetScopedCredentials was announced.
This API issues credentials with narrowed permissions, session duration, or both from existing temporary credentials. In this article, I issued credentials with the AWS CLI and checked how the scoped credentials behave and how they are recorded in CloudTrail.
Test environment
| Item | Details |
|---|---|
| AWS CLI | aws-cli/2.41.2 |
| Region | ap-northeast-1 |
| Caller | A session (assumed-role) of an IAM role that can list S3 buckets, list EC2 Regions, and run CloudTrail lookup-events |
You call GetScopedCredentials with temporary credentials such as an assumed role or a federated session. If you want to narrow down from the long-term credentials of an IAM user, first obtain temporary credentials with GetSessionToken and then call it. It cannot be used with the global endpoint, so specify a regional endpoint.
Passing credentials
I store the issued JSON in a shell variable, and the following function with_creds sets those credentials only inside a subshell and runs a command. The Region is fixed to ap-northeast-1 with environment variables.
Changes to environment variables stay within the subshell, so the credentials of the original shell are unchanged. This means the next issuance can also continue with the caller's credentials. This function uses jq.
export AWS_REGION=ap-northeast-1 AWS_DEFAULT_REGION=ap-northeast-1
with_creds() {
local json="$1"; shift
(
unset AWS_PROFILE
AWS_ACCESS_KEY_ID="$(jq -r .Credentials.AccessKeyId <<<"$json")"
AWS_SECRET_ACCESS_KEY="$(jq -r .Credentials.SecretAccessKey <<<"$json")"
AWS_SESSION_TOKEN="$(jq -r .Credentials.SessionToken <<<"$json")"
export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
"$@"
)
}
Narrowing permissions
Save a policy that allows only listing S3 buckets as policy-s3-list.json.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": "*"
}
]
}
Before issuing, check the caller's ARN and the session expiration.
aws sts get-caller-identity
{
"UserId": "<ROLE_ID>:<SESSION_NAME>",
"Account": "<ACCOUNT_ID>",
"Arn": "arn:aws:sts::<ACCOUNT_ID>:assumed-role/<ROLE_NAME>/<SESSION_NAME>"
}
aws configure export-credentials --format process | jq -r .Expiration
2026-11-20T03:08:25+00:00
Pass this policy to --policy and a string indicating the purpose to --scoped-session-description, and issue the credentials.
CREDS=$(aws sts get-scoped-credentials \
--policy file://policy-s3-list.json \
--scoped-session-description devio-verify-1120-step1 \
--output json)
CREDS contains the following JSON.
{
"Credentials": {
"AccessKeyId": "<masked>",
"SecretAccessKey": "<masked>",
"SessionToken": "<masked>",
"Expiration": "2026-11-20T03:08:25+00:00"
},
"SessionInfo": {
"ScopedSessionId": "<ROLE_ID>:<SESSION_NAME>",
"Arn": "arn:aws:sts::<ACCOUNT_ID>:assumed-role/<ROLE_NAME>/<SESSION_NAME>"
},
"SessionTokenUtilization": 18,
"SessionTokenSize": 760,
"ScopedPoliciesCount": 1
}
Because --duration-seconds was omitted, Expiration is the same value as the caller session's expiration.
With the scoped credentials, I ran the following in order: checking the ARN, an operation allowed by the policy, and an operation not allowed by the policy.
with_creds "$CREDS" aws sts get-caller-identity
{
"UserId": "<ROLE_ID>:<SESSION_NAME>",
"Account": "<ACCOUNT_ID>",
"Arn": "arn:aws:sts::<ACCOUNT_ID>:assumed-role/<ROLE_NAME>/<SESSION_NAME>"
}
with_creds "$CREDS" aws s3api list-buckets --query 'length(Buckets)'
95
with_creds "$CREDS" aws ec2 describe-regions --query 'length(Regions)'
aws: [ERROR]: An error occurred (UnauthorizedOperation) when calling the DescribeRegions operation: You are not authorized to perform this operation. User: arn:aws:sts::<ACCOUNT_ID>:assumed-role/<ROLE_NAME>/<SESSION_NAME> is not authorized to perform: ec2:DescribeRegions because no session policy allows the ec2:DescribeRegions action
The ARN of the scoped credentials remained the same as the caller's, and the permissions were limited to only the operations allowed by the policy.
Narrowing the session duration
If you specify only --duration-seconds, you can shorten the duration without changing the permissions.
SHORT=$(aws sts get-scoped-credentials \
--duration-seconds 900 \
--output json)
The call time was 2026-11-20T02:32:22Z, and the Expiration in the response was 2026-11-20T02:47:22+00:00, that is, 900 seconds later. Because the policy was omitted, ScopedPoliciesCount is 0.
I listed the S3 buckets and the EC2 Regions, which was denied in the previous section.
with_creds "$SHORT" aws s3api list-buckets --query 'length(Buckets)'
with_creds "$SHORT" aws ec2 describe-regions --query 'length(Regions)'
95
17
The permissions are the same as the caller's, so both succeeded.
Not exceeding the caller
You can also call GetScopedCredentials again from scoped credentials. In this section, I call the credentials issued from the caller the "parent" and the credentials issued from the parent the "child."
To issue a child from the parent's credentials, the parent's policy must allow sts:GetScopedCredentials. So for the parent, I specify a policy that allows listing S3 buckets and sts:GetScopedCredentials, and set the duration to 900 seconds. Save the policy as policy-parent-s3-list-and-scope.json.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets",
"sts:GetScopedCredentials"
],
"Resource": "*"
}
]
}
For the child, I specify a policy broader than the parent's, allowing listing EC2 Regions in addition to listing S3 buckets. --duration-seconds is omitted.
Child policy (policy-s3-list-ec2-regions.json)
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets",
"ec2:DescribeRegions"
],
"Resource": "*"
}
]
}
PARENT=$(aws sts get-scoped-credentials \
--policy file://policy-parent-s3-list-and-scope.json \
--duration-seconds 900 \
--scoped-session-description devio-verify-1120-step4b-parent \
--output json)
CHILD=$(with_creds "$PARENT" aws sts get-scoped-credentials \
--policy file://policy-s3-list-ec2-regions.json \
--scoped-session-description devio-verify-1120-step4b-child \
--output json)
The Expiration of both the parent and the child was 2026-11-20T02:47:48+00:00, so the child inherited the parent's expiration. ScopedPoliciesCount is 1 for the parent and 2 for the child.
With the child's credentials, I listed S3 buckets, which both the child and the parent allow, and EC2 Regions, which only the child allows.
with_creds "$CHILD" aws s3api list-buckets --query 'length(Buckets)'
with_creds "$CHILD" aws ec2 describe-regions --query 'length(Regions)'
95
aws: [ERROR]: An error occurred (UnauthorizedOperation) when calling the DescribeRegions operation: You are not authorized to perform this operation. User: arn:aws:sts::<ACCOUNT_ID>:assumed-role/<ROLE_NAME>/<SESSION_NAME> is not authorized to perform: ec2:DescribeRegions because no session policy allows the ec2:DescribeRegions action
Even though I specified a policy broader than the parent's for the child, the permissions stayed within the parent's scope.
The upper limit of the duration is also the parent's remaining time. When I tried to issue from the parent's credentials with --duration-seconds 3600, it was denied.
with_creds "$PARENT" aws sts get-scoped-credentials --duration-seconds 3600
aws: [ERROR]: An error occurred (InsufficientSessionLifetime) when calling the GetScopedCredentials operation: The requested DurationSeconds exceeds the remaining lifetime of the calling session. Remaining session lifetime is 898 seconds.
CloudTrail records
About 10 minutes after the last call, I searched with lookup-events.
aws cloudtrail lookup-events \
--lookup-attributes AttributeKey=EventName,AttributeValue=GetScopedCredentials \
--max-results 20
All the GetScopedCredentials calls I ran in the test were recorded as management events. managementEvent was true and eventCategory was Management. The call that was denied for exceeding the duration is also included, as an event with errorCode InsufficientSessionLifetimeException.
requestParameters records the full text of the specified policy and scopedSessionDescription. The record for the issuance in the "Narrowing permissions" section is as follows.
{
"policy": "{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": \"s3:ListAllMyBuckets\",\n \"Resource\": \"*\"\n }\n ]\n}\n",
"scopedSessionDescription": "devio-verify-1120-step1"
}
For calls that specify a duration, durationSeconds is also recorded.
The responseElements.credentials of a successful issuance event contains accessKeyId, sessionToken, and expiration. secretAccessKey is not included.
In the events of operations performed with the scoped credentials, the arn, principalId, and sessionContext in userIdentity are the same as the caller's. Only accessKeyId differs. The following table shows the issuance in the "Narrowing permissions" section and the events of the S3 and EC2 operations performed with the issued credentials.
| Time | Event name | accessKeyId | errorCode |
|---|---|---|---|
| 02:32:00Z | GetScopedCredentials | Caller's key | |
| 02:32:01Z | ListBuckets | Issued key | |
| 02:32:02Z | DescribeRegions | Issued key | Client.UnauthorizedOperation |
The accessKeyId of ListBuckets and DescribeRegions matched the accessKeyId recorded in the responseElements of the issuance event. From this match, I could link the operation events of the credentials issued in the "Narrowing permissions" section to the issuance event. Because the issuance event records scopedSessionDescription and the full text of the policy, the purpose and permissions of the issuance can also be confirmed.
Summary
With GetScopedCredentials, you can now issue credentials with narrowed permissions or duration from existing temporary credentials.
The issuance calls are recorded in CloudTrail as management events, and I could link the operation events of the issued credentials to the issuance event.
Please use it as a way to give workloads such as sub-agents or subtasks that perform specific work the minimum necessary permissions.
