Mastering AWS Temporary Credentials: Securely Assume IAM Roles

In early operations teams often created high‑privilege IAM users with long‑lived access keys stored on servers and developers' machines, which introduces severe security risks such as key leakage, tangled permission management, and cumbersome cross‑account collaboration.

Core Concept: IAM Roles and Temporary Credentials

AWS solves these problems with IAM roles that have no permanent keys. Trusted entities (IAM users, EC2 instances, other services) can assume a role to obtain temporary credentials consisting of an AccessKeyId, SecretAccessKey, SessionToken, and an explicit expiration time. The aws sts assume-role command is the entry point for acquiring these credentials.

Trust Policy (Who Can Assume the Role)

A trust policy is attached to the role and specifies which principals are allowed to call sts:AssumeRole. Example:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"AWS": "arn:aws:iam::111122223333:user/DevUser"},
    "Action": "sts:AssumeRole"
  }]
}

This policy permits only the user DevUser in account 111122223333 to assume the role.

Permissions Policy (What the Caller Can Do)

The permissions policy is attached to the caller (IAM user) and defines which roles it may assume. Example:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::444455556666:role/TargetRole"
  }]
}

This allows the user to assume the role TargetRole in account 444455556666.

Running the Assume‑Role Command

Basic syntax:

aws sts assume-role \
    --role-arn "arn:aws:iam::444455556666:role/TargetRole" \
    --role-session-name "MyWebAppSession"

--role-arn

: ARN of the role to assume. --role-session-name: Identifier that appears in CloudTrail logs; choose a meaningful name such as user-john-debug-s3-issue.

Successful execution returns a JSON object with a Credentials block:

{
  "Credentials": {
    "AccessKeyId": "ASIA...",
    "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY",
    "SessionToken": "AQoDYXdzEJr...",
    "Expiration": "2025-06-26T03:52:00Z"
  },
  ...
}

Using the Temporary Credentials

Export them as environment variables:

export AWS_ACCESS_KEY_ID="ASIA..."
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY"
export AWS_SESSION_TOKEN="AQoDYXdzEJr..."

All subsequent aws CLI commands in that session will use the assumed role. When the terminal closes or the credentials expire, the variables become invalid.

One‑Liner with jq and export

export $(aws sts assume-role --role-arn "arn:aws:iam::ACCOUNT_B_ID:role/ROLE_NAME" \
    --role-session-name "my-session" \
    --query "Credentials.[AccessKeyId,SecretAccessKey,SessionToken]" \
    --output text | awk '{printf "AWS_ACCESS_KEY_ID=%s AWS_SECRET_ACCESS_KEY=%s AWS_SESSION_TOKEN=%s", $1, $2, $3}')

Best Practice: Use AWS CLI Profiles

Instead of manually exporting variables, configure a profile that automatically assumes the role.

# ~/.aws/credentials
[default]
aws_access_key_id = YOUR_IAM_USER_KEY
aws_secret_access_key = YOUR_IAM_USER_SECRET

# ~/.aws/config
[profile cross-account-admin]
role_arn = arn:aws:iam::444455556666:role/TargetRole
source_profile = default
region = us-east-1

Running a command with --profile cross-account-admin triggers an implicit sts:AssumeRole call, providing temporary credentials transparently.

# List S3 buckets using the assumed role
aws s3 ls --profile cross-account-admin

Summary

Least‑privilege : Grant only the temporary permissions needed for a task.

Improved security : Eliminate long‑lived keys and reduce leakage risk.

Simplified cross‑account management : Seamlessly operate across multiple AWS accounts.

Enhanced auditability : Use role-session-name to trace actions in CloudTrail.

For AWS operations engineers, adopting the CLI profile assume‑role workflow should be a standard operating procedure to protect cloud assets.