aws-sts

Get temporary security credentials to access specific AWS resources

$ aws sts assume-role --role-arn [aws_role_arn]

$ aws sts get-caller-identity

aws sts [options] [arguments]

Examples:
aws sts assume-role --role-arn arn:aws:iam::123456789012:role/MyRole --role-session-name MySession
aws sts get-caller-identity
aws sts get-session-token --duration-seconds 3600 --serial-number arn:aws:iam::123456789012:mfa/user --token-code 123456

    Specifies the STS operation to perform. Common subcommands include assume-role, get-session-token, get-caller-identity, and decode-authorization-message.

--role-arn
    (Used with assume-role) The ARN of the role to assume, identifying the AWS role. Required for assume-role.

--role-session-name
    (Used with assume-role) An identifier for the assumed role session. This name appears in CloudTrail logs. Required for assume-role.

--duration-seconds
    (Used with assume-role, get-session-token) The duration, in seconds, for which the temporary credentials are valid. Defaults to 1 hour (3600 seconds). Maximum is 12 hours (43200 seconds) for roles and up to 36 hours for session tokens, depending on permissions.

--serial-number
    (Used with get-session-token, and assume-role if MFA is required) The serial number of the MFA device associated with the user or role.

--token-code
    (Used with get-session-token, and assume-role if MFA is required) The value provided by the MFA device. This is the 6-digit code from your virtual or hardware MFA device.

--external-id
    (Used with assume-role) A unique identifier that might be required by the role's trust policy, typically when assuming roles cross-account to prevent confused deputy attacks.

--output
    Specifies the output format: json (default), text, or table. This is a global AWS CLI option.

--region
    The AWS region to send the request to, overriding the default configured region. This is a global AWS CLI option.

The aws sts command, part of the AWS Command Line Interface (CLI), enables interaction with the AWS Security Token Service (STS). STS provides temporary, limited-privilege credentials for AWS IAM users or federated users. These credentials enhance security by allowing access to AWS resources without exposing long-term static access keys. Common use cases include assuming IAM roles for cross-account access, obtaining session tokens for programmatic access, or retrieving information about the current calling entity. The command is essential for scripting automated tasks, CI/CD pipelines, and applications that require secure, temporary access to AWS resources without embedding permanent credentials.

The aws sts command relies on a correctly installed and configured AWS CLI. Credentials obtained are temporary and expire after a specified duration; they must be refreshed. Users or roles must have appropriate IAM policies that grant permission to perform specific STS operations. MFA requirements can add complexity to scripting, often necessitating interactive input or secure token management. It's crucial to handle temporary credentials securely, avoiding their exposure in logs or insecure storage.

The output of aws sts commands (e.g., assume-role, get-session-token) typically provides AccessKeyId, SecretAccessKey, and SessionToken. These values can be exported as environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) to allow subsequent AWS CLI commands or SDKs to use the temporary credentials. For example:
eval $(aws sts assume-role --role-arn arn:aws:iam::123456789012:role/MyRole --role-session-name MySession --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' --output text | awk '{print "export AWS_ACCESS_KEY_ID=" $1 "\nexport AWS_SECRET_ACCESS_KEY=" $2 "\nexport AWS_SESSION_TOKEN=" $3 "\nexport AWS_SESSION_EXPIRES=" strftime("%s",systime()+$4) }')

When Multi-Factor Authentication (MFA) is required for a role assumption or session token, scripting can be challenging as the --token-code must be provided. For automation, users often integrate with secure credential stores or use tools like aws-vault, which can manage MFA prompts and securely store credentials.

The AWS Security Token Service (STS) is a fundamental service for managing temporary security credentials, integral to AWS's security model. The AWS CLI, including its sts subcommand, was first released in 2013, providing a unified command-line interface to interact with AWS services. Since its inception, the aws sts command has evolved alongside the service, receiving updates and new features to support enhanced security practices and more flexible credential management scenarios.

aws(1), aws-iam(1), aws-configure(1)