Set up Amazon temporary credentials and Amazon Web Services Region for development - Amazon SDK for Java 1.x
Configure temporary credentialsRefreshing IMDS credentialsSet the Amazon Web Services Region
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).

We announced the upcoming end-of-support for Amazon SDK for Java (v1). We recommend that you migrate to Amazon SDK for Java v2. For dates, additional details, and information on how to migrate, please refer to the linked announcement.

Set up Amazon temporary credentials and Amazon Web Services Region for development

To connect to any of the supported services with the Amazon SDK for Java, you must provide Amazon temporary credentials. The Amazon SDKs and CLIs use provider chains to look for Amazon temporary credentials in a number of different places, including system/user environment variables and local Amazon configuration files.

This topic provides basic information about setting up your Amazon temporary credentials for local application development using the Amazon SDK for Java. If you need to set up credentials for use within an EC2 instance or if you’re using the Eclipse IDE for development, refer to the following topics instead:

Configure temporary credentials

You can configure temporary credentials for the Amazon SDK for Java in a number of ways, but here are the recommended approaches:

  • Set temporary credentials in the Amazon credentials profile file on your local system, located at:

    • ~/.aws/credentials on Linux, macOS, or Unix

    • C:\Users\USERNAME\.aws\credentials on Windows

    See the Set up temporary credentials for the SDK in this guide for instructions on how to get your temporary credentials.

  • Set the AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables.

    To set these variables on Linux, macOS, or Unix, use :

    export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key
export AWS_SESSION_TOKEN=your_session_token

    To set these variables on Windows, use:

    set AWS_ACCESS_KEY_ID=your_access_key_id
set AWS_SECRET_ACCESS_KEY=your_secret_access_key
set AWS_SESSION_TOKEN=your_session_token

  • For an EC2 instance, specify an IAM role and then give your EC2 instance access to that role. See IAM Roles for Amazon EC2 in the Amazon EC2 User Guide for Linux Instances for a detailed discussion about how this works.

Once you have set your Amazon temporary credentials using one of these methods, they will be loaded automatically by the Amazon SDK for Java by using the default credential provider chain. For further information about working with Amazon credentials in your Java applications, see Working with Amazon Credentials.

Refreshing IMDS credentials

The Amazon SDK for Java supports opt-in refreshing IMDS credentials in the background every 1 minute, regardless of the credential expiration time. This allows you to refresh credentials more frequently and reduces the chance that not reaching IMDS impacts the perceived Amazon availability.

 1. // Refresh credentials using a background thread, automatically every minute. This will log an error if IMDS is down during
 2. // a refresh, but your service calls will continue using the cached credentials until the credentials are refreshed
 3. // again one minute later.
 4.
 5. InstanceProfileCredentialsProvider credentials =
 6.     InstanceProfileCredentialsProvider.createAsyncRefreshingProvider(true);
 7.
 8. AmazonS3Client.builder()
 9.              .withCredentials(credentials)
 10.              .build();
 11.
 12. // This is new: When you are done with the credentials provider, you must close it to release the background thread.
 13. credentials.close();

Set the Amazon Web Services Region

You should set a default Amazon Web Services Region that will be used for accessing Amazon services with the Amazon SDK for Java. For the best network performance, choose a region that’s geographically close to you (or to your customers). For a list of regions for each service, see Regions and Endpoints in the Amazon Web Services General Reference.

Note

If you don’t select a region, then us-east-1 will be used by default.

You can use similar techniques to setting credentials to set your default Amazon region:

  • Set the Amazon Web Services Region in the Amazon config file on your local system, located at:

    • ~/.aws/config on Linux, macOS, or Unix

    • C:\Users\USERNAME\.aws\config on Windows

    This file should contain lines in the following format:

    +

    [default]
region = your_aws_region

    +

    Substitute your desired Amazon Web Services Region (for example, "us-east-1") for your_aws_region.

  • Set the AWS_REGION environment variable.

    On Linux, macOS, or Unix, use :

    export AWS_REGION=your_aws_region

    On Windows, use :

    set AWS_REGION=your_aws_region

    Where your_aws_region is the desired Amazon Web Services Region name.