Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using temporary credentials with Amazon resources

You can use temporary security credentials to make programmatic requests for Amazon resources using the Amazon CLI or Amazon API (using the Amazon SDKs). The temporary credentials provide the same permissions as long-term security credentials, such as IAM user credentials. However, there are a few differences:

If you are using the Amazon SDKs, the Amazon Command Line Interface (Amazon CLI), or the Tools for Windows PowerShell, the way to get and use temporary security credentials differs with the context. If you are running code, Amazon CLI, or Tools for Windows PowerShell commands inside an EC2 instance, you can take advantage of roles for Amazon EC2. Otherwise, you can call an Amazon STS API to get the temporary credentials, and then use them explicitly to make calls to Amazon services.

Using temporary credentials in Amazon EC2 instances

If you want to run Amazon CLI commands or code inside an EC2 instance, the recommended way to get credentials is to use roles for Amazon EC2. You create an IAM role that specifies the permissions that you want to grant to applications that run on the EC2 instances. When you launch the instance, you associate the role with the instance.

Applications, Amazon CLI, and Tools for Windows PowerShell commands that run on the instance can then get automatic temporary security credentials from the instance metadata. You do not have to explicitly get the temporary security credentials. The Amazon SDKs, Amazon CLI, and Tools for Windows PowerShell automatically get the credentials from the EC2 Instance Metadata Service (IMDS) and use them. The temporary credentials have the permissions that you define for the role that is associated with the instance.

For more information and for examples, see the following:

Using temporary security credentials with the Amazon SDKs

To use temporary security credentials in code, you programmatically call an Amazon STS API like AssumeRole and extract the resulting credentials and session token. You then use those values as credentials for subsequent calls to Amazon. The following example shows pseudocode for how to use temporary security credentials if you're using an Amazon SDK:

assumeRoleResult = AssumeRole(role-arn);
tempCredentials = new SessionAWSCredentials(
   assumeRoleResult.AccessKeyId, 
   assumeRoleResult.SecretAccessKey, 
   assumeRoleResult.SessionToken);
s3Request = CreateAmazonS3Client(tempCredentials);

For an example written in Python (using the Amazon SDK for Python (Boto)), see Switching to an IAM role (Amazon API). This example shows how to call AssumeRole to get temporary security credentials and then use those credentials to make a call to Amazon S3.

For details about how to call AssumeRole, GetFederationToken, and other API operations, see the Amazon Security Token Service API Reference. For information on getting the temporary security credentials and session token from the result, see the documentation for the SDK that you're working with. You can find the documentation for all the Amazon SDKs on the main Amazon documentation page, in the SDKs and Toolkits section.

You must make sure that you get a new set of credentials before the old ones expire. In some SDKs, you can use a provider that manages the process of refreshing credentials for you; check the documentation for the SDK you're using.

Using temporary security credentials with the Amazon CLI

You can use temporary security credentials with the Amazon CLI. This can be useful for testing policies.

Using the Amazon CLI, you can call an Amazon STS API like AssumeRole or GetFederationToken and then capture the resulting output. The following example shows a call to AssumeRole that sends the output to a file. In the example, the profile parameter is assumed to be a profile in the Amazon CLI configuration file. It is also assumed to reference credentials for an IAM user who has permissions to assume the role.

aws sts assume-role --role-arn arn:aws-cn:iam::123456789012:role/role-name --role-session-name "RoleSession1" --profile IAM-user-name > assume-role-output.txt

When the command is finished, you can extract the access key ID, secret access key, and session token from wherever you've routed it. You can do this either manually or by using a script. You can then assign these values to environment variables.

When you run Amazon CLI commands, the Amazon CLI looks for credentials in a specific order—first in environment variables and then in the configuration file. Therefore, after you've put the temporary credentials into environment variables, the Amazon CLI uses those credentials by default. (If you specify a profile parameter in the command, the Amazon CLI skips the environment variables. Instead, the Amazon CLI looks in the configuration file, which lets you override the credentials in the environment variables if you need to.)

The following example shows how you might set the environment variables for temporary security credentials and then call an Amazon CLI command. Because no profile parameter is included in the Amazon CLI command, the Amazon CLI looks for credentials first in environment variables and therefore uses the temporary credentials.

Linux

$ export AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
$ export AWS_SESSION_TOKEN=AQoDYXdzEJr...<remainder of session token>
$ aws ec2 describe-instances --region us-west-1

Windows

C:\> SET AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
C:\> SET AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
C:\> SET AWS_SESSION_TOKEN=AQoDYXdzEJr...<remainder of token> 
C:\> aws ec2 describe-instances --region us-west-1

Using temporary security credentials with API operations

If you're making direct HTTPS API requests to Amazon, you can sign those requests with the temporary security credentials that you get from the Amazon Security Token Service (Amazon STS). To do this, you use the access key ID and secret access key that you receive from Amazon STS. You use the access key ID and secret access key the same way you would use long-term credentials to sign a request. You also add to your API request the session token that you receive from Amazon STS. You add the session token to an HTTP header or to a query string parameter named X-Amz-Security-Token. You add the session token to the HTTP header or the query string parameter, but not both. For more information about signing HTTPS API requests, see Signing Amazon API Requests in the Amazon Web Services General Reference.

More information

For more information about using Amazon STS with other Amazon services, see the following links: