Assume an IAM role with STS

Part 115 of AWS from Zero. This lesson changes or inspects one IAM concept so the permission model stays understandable.

What we are learning

sts assume-role returns an access key, secret key, session token, and expiration. These credentials represent a named role session.

Before you run it

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
ROLE_ARN="arn:aws:iam::$ACCOUNT_ID:role/aws-zero-demo-role"

The role trust policy and caller authorization must allow assumption. Do not paste returned secrets into logs or source files.

The command

aws sts assume-role \
  --role-arn "$ROLE_ARN" \
  --role-session-name aws-zero-session

IAM writes can take a short time to propagate. Inspect the resource after every change.

Inspect the result

aws sts assume-role \
  --role-arn "$ROLE_ARN" \
  --role-session-name aws-zero-inspect \
  --query "{Session:AssumedRoleUser.Arn,Expires:Credentials.Expiration}" \
  --output table

Read the returned ARN, path, IDs, and attachment state instead of checking only the command exit code.

One tiny variation

aws sts assume-role \
  --role-arn "$ROLE_ARN" \
  --role-session-name aws-zero-short \
  --duration-seconds 900

Fifteen minutes is the minimum role-session duration accepted by STS.

Common mistake

The returned session permissions are not necessarily every permission attached to the role. Session policies and permission controls can only narrow the resulting access.

Cleanup

unset ROLE_ARN

STS credentials expire automatically. Remove any local environment variables or temporary files that captured them.

Next, we will learn Use STS temporary credentials in shell variables.

Official AWS CLI reference