Michael Letts

← Go Back to Professional Blog

AWS has a new method for generating temporary credentials via STS

· Michael Letts

A crude, hand drawn image of a key.

Important

  • GetScopedCredentials scopes down an existing STS session and preserves the caller’s identity.
  • The caller needs temporary credentials, an explicit allow for sts:GetScopedCredentials, and a regional STS endpoint.
  • Permissions and session lifetime can only narrow monotonically across a chain of scoped sessions.

AWS STS has unveiled GetScopedCredentials, a way to narrow the permissions or lifetime of temporary credentials at the moment you need to hand them off.

At first blush, this looks a lot like passing a session policy to AssumeRole. With GetScopedCredentials, you work with the session you already have, so there’s no target role or additional trust policy to configure. The same ARN, role session name, session tags (including transitive tag keys), source identity, and Trusted Identity Propagation context carry through to the scoped credentials.

Grant sts:GetScopedCredentials with "Resource": "*" in the caller’s IAM policy. The action must be explicitly allowed by the caller’s effective permissions, which may already be limited by a permissions boundary or SCP. Use temporary credentials from an assumed role or federated session, for example. If you’re starting with long-term IAM user keys, the STS API reference points you to GetSessionToken first. Here’s the IAM permissions guide. And here’s the STS API reference.

Pass an inline IAM Policy, a DurationSeconds, or both. The scope down policy intersects with the caller’s effective permissions. The policy can be up to 2,048 characters, subject to a separate packed size limit. Each additional policy adds another layer to the intersection, up to three. If you want a recipient to scope down its credentials again, sts:GetScopedCredentials has to survive every layer.

Omit DurationSeconds to inherit the caller’s expiration. You can request 1 second to 36 hours, up to the time left on the calling session. STS rejects a duration beyond that with InsufficientSessionLifetime. A duration-only request leaves the existing policy layers in place. Here’s the STS API reference.

Potential Use Cases

  1. Least privilege for agents. An orchestrator can hand a sandboxed agent credentials for the precise task at hand and keep the broader credentials out of the sandbox.
  2. Temporary third-party delegation. A broker in your account can vend credentials for a specific task to an external worker. Calls made with those credentials carry the broker session’s identity, so use a separate role when you need a distinct AWS principal.
  3. Custom credential brokering. A broker can vend different slices of the same session to humans, workloads, or agents. Needless to say, this opens up some interesting possibilities for open source tools like boto3-refresh-session and elhaz.

AWS lists a few services and engine versions where scoped credentials are unsupported. Some services cache KMS data keys, so removing KMS permissions alone may leave recently accessed data readable. Scope the service action itself to the resources the task needs. Here’s the IAM guide to service support and encrypted resources.

CloudTrail

CloudTrail logs each GetScopedCredentials call. Since the session ARN is shared, follow the access key IDs. In AWS’s example, userIdentity.accessKeyId identifies the key that made the call, and responseElements.credentials.accessKeyId identifies the key STS issued. Pass a ScopedSessionDescription to record what the credentials are for. The CloudTrail creationDate tracks the original session, so use eventTime for the time of the scope down call. Revoking the parent role session also revokes credentials scoped down from it. Here’s the IAM guide and sample CloudTrail event.

AWS CLI

Both examples use temporary credentials from your usual AWS credential source and a Regional STS endpoint. Replace the bucket and key with an existing object that your session can read using s3:GetObject alone, such as an SSE-S3 object in a general purpose bucket. The calls request five minutes, so the source session needs at least that much time left. Use AWS CLI v2.41.2 or later for the CLI example. Here’s the AWS CLI command reference.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
aws sts get-scoped-credentials \
    --region us-west-2 \
    --policy '{
        "Version": "2012-10-17",
        "Statement": [{
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/my_file.csv"
        }]
    }' \
    --duration-seconds 300 \
    --scoped-session-description 'Read my_file.csv' \
    --output json

The response includes the credentials and metadata about the resulting session. Here are the relevant fields, with example values.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "Credentials": {
        "AccessKeyId": "ASIAIOSFODNN7EXAMPLE",
        "SecretAccessKey": "...",
        "SessionToken": "...",
        "Expiration": "2026-11-20T18:05:00Z"
    },
    "ScopedPoliciesCount": 1,
    "SessionInfo": {
        "ScopedSessionId": "AROAEXAMPLEID:example-session",
        "Arn": "arn:aws:sts::123456789012:assumed-role/example-role/example-session"
    }
}

To use the credentials in another CLI command, pass all three values to that process as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN. If you want a reusable profile, a credential_process can call get-scoped-credentials using a separate source profile and return the credentials in the CLI’s process format. Here’s the AWS CLI credential process format.

AWS Python SDK

Use Boto3 1.44.7 or later. The Credentials object returned by get_scoped_credentials has the familiar STS fields, so fret not. Pass them to your S3 client and use the credentials before Expiration. Set the S3 client’s region_name to the bucket’s Region. Here’s the Boto3 changelog.. And here’s the Boto3 credentials guide.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import json

import boto3

bucket = "amzn-s3-demo-bucket"
key = "my_file.csv"
policy = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": f"arn:aws:s3:::{bucket}/{key}",
        }
    ],
}

sts = boto3.client(
    "sts",
    region_name="us-west-2",
    endpoint_url="https://sts.us-west-2.amazonaws.com",
)
response = sts.get_scoped_credentials(
    Policy=json.dumps(policy),
    DurationSeconds=300,
    ScopedSessionDescription=f"Read {key}",
)
credentials = response["Credentials"]
s3 = boto3.client(
    "s3",
    region_name="us-west-2",
    aws_access_key_id=credentials["AccessKeyId"],
    aws_secret_access_key=credentials["SecretAccessKey"],
    aws_session_token=credentials["SessionToken"],
)
with s3.get_object(Bucket=bucket, Key=key)["Body"] as body:
    print(body.read().decode("utf-8"))

#aws #sts #getscopedcredentials #assumerole #get-scoped-credentials #assume-role #get-session-token