Menu
AWS SDK for Java
Developer Guide

Getting Temporary Credentials with AWS STS

You can use AWS Security Token Service (AWS STS) to get temporary, limited-privilege credentials that can be used to access AWS services.

There are three steps involved in using AWS STS:

  1. Activate a region (optional).

  2. Retrieve temporary security credentials from AWS STS.

  3. Use the credentials to access AWS resources.

Note

Activating a region is optional; by default, temporary security credentials are obtained from the global endpoint sts.amazonaws.com. However, to reduce latency and to enable you to build redundancy into your requests by using additional endpoints if an AWS STS request to the first endpoint fails, you can activate regions that are geographically closer to your services or applications that use the credentials.

(Optional) Activate and use an AWS STS region

To activate a region for use with AWS STS, use the AWS Management Console to select and activate the region.

To activate additional STS regions

  1. Sign in as an IAM user with permissions to perform IAM administration tasks "iam:*" for the account for which you want to activate AWS STS in a new region.

  2. Open the IAM console and in the navigation pane click Account Settings.

  3. Expand the STS Regions list, find the region that you want to use, and then click Activate.

After this, you can direct calls to the STS endpoint that is associated with that region.

Note

For more information about activating STS regions and for a list of the available AWS STS endpoints, see Activating and Deactivating AWS STS in an AWS Region in the IAM User Guide.

Retrieve temporary security credentials from AWS STS

To retrieve temporary security credentials using the AWS SDK for Java

  1. Create an AWSSecurityTokenServiceClient object:

    Copy
    AWSSecurityTokenServiceClient sts_client = new AWSSecurityTokenServiceClient();

    When creating the client with no arguments, the default credential provider chain is used to retrieve credentials. You can provide a specific credential provider if you want. For more information, see Providing AWS Credentials in the AWS SDK for Java.

  2. Optional; requires that you have activated the region) Set the endpoint for the STS client:

    Copy
    sts_client.setEndpoint("sts-endpoint.amazonaws.com");

    where sts-endpoint represents the STS endpoint for your region.

    Important

    Do not use the setRegion method to set a regional endpoint—for backwards compatibility, that method continues to use the single global endpoint of sts.amazonaws.com.

  3. Create a GetSessionTokenRequest object, and optionally set the duration in seconds for which the temporary credentials are valid:

    Copy
    GetSessionTokenRequest session_token_request = new GetSessionTokenRequest(); session_token_request.setDurationSeconds(7200); // optional.

    The duration of temporary credentials can range from 900 seconds (15 minutes) to 129600 seconds (36 hours) for IAM users. If a duration isn't specified, then 43200 seconds (12 hours) is used by default.

    For a root AWS account, the valid range of temporary credentials is from 900 to 3600 seconds (1 hour), with a default value of 3600 seconds if no duration is specified.

    Important

    It is strongly recommended, from a security standpoint, that you use IAM users instead of the root account for AWS access. For more information, see IAM Best Practices in the IAM User Guide.

  4. Call getSessionToken on the STS client to get a session token, using the GetSessionTokenRequest object:

    Copy
    GetSessionTokenResult session_token_result = sts_client.getSessionToken(session_token_request);
  5. Get session credentials using the result of the call to getSessionToken:

    Copy
    Credentials session_creds = session_token_result.getCredentials();

The session credentials provide access only for the duration that was specified by the GetSessionTokenRequest object. Once the credentials expire, you will need to call getSessionToken again to obtain a new session token for continued access to AWS.

Use the temporary credentials to access AWS resources

Once you have temporary security credentials, you can use them to initialize an AWS service client to use its resources, using the technique described in Explicitly Specifying Credentials.

For example, to create an S3 client using temporary service credentials:

Copy
BasicSessionCredentials sessionCredentials = new BasicSessionCredentials( session_creds.getAccessKeyId(), session_creds.getSecretAccessKey(), session_creds.getSessionToken()); AmazonS3 s3 = AmazonS3ClientBuilder.standard() .withCredentials(new AWSStaticCredentialsProvider(sessionCredentials) .build();

You can now use the AmazonS3 object to make Amazon S3 requests.

For more information

For more information about how to use temporary security credentials to access AWS resources, visit the following sections in the IAM User Guide: