Basic setup to work with AWS services - AWS SDK for Java 1.x
OverviewSign-in ability to the AWS access portalSet up shared configuration filesInstall a Java Development Environment

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

Basic setup to work with AWS services

Overview

To successfully develop applications that access AWS services using the AWS SDK for Java, the following conditions are required:

Important

The instructions in this setup section assume that you or organization uses IAM Identity Center. If your organization uses an external identity provider that works independently of IAM Identity Center, find out how you can get temporary credentials for the SDK for Java to use. Follow these instructions to add temporary credentials to the ~/.aws/credentials file.

If your identity provider adds temporary credentials automatically to the ~/.aws/credentials file, make sure that the profile name is [default] so that you do not need to provide a profile name to the SDK or AWS CLI.

Sign-in ability to the AWS access portal

The AWS access portal is the web location where you manually sign in to the IAM Identity Center. The format of the URL is d-xxxxxxxxxx.awsapps.com/startor your_subdomain.awsapps.com/start.

If you are not familiar with the AWS access portal, follow the guidance for account access in Step 1 of the IAM Identity Center authentication topic in the AWS SDKs and Tools Reference Guide. Do not follow the Step 2 because the AWS SDK for Java 1.x does not support automatic token refresh and automatic retrieval of temporary credentials for the SDK that Step 2 describes.

Set up shared configuration files

The shared configuration files reside on your development workstation and contain basic settings used by all AWS SDKs and the AWS Command Line Interface (CLI). The shared configuration files can contain a number of settings, but these instructions set up the basic elements that are required to work with the SDK.

Set up the shared config file

The following example shows content of a shared config file.

[default]
region=us-east-1
output=json

For development purposes, use the AWS Region nearest to where you plan to run your code. For a listing of region codes to use in the config file see the Amazon Web Services General Reference guide. The json setting for the output format is one of several possible values.

Follow the guidance in this section to create the config file.

Set up temporary credentials for the SDK

After you have access to an AWS account and IAM role through the AWS access portal, configure your development environment with temporary credentials for the SDK to access.

Steps to set up a local credentials file with temporary credentials

  1. Create a shared credentials file.

  2. In the credentials file, paste the following placeholder text until you paste in working temporary credentials.

    [default]
aws_access_key_id=<value from AWS access portal>
aws_secret_access_key=<value from AWS access portal>
aws_session_token=<value from AWS access portal>

  3. Save the file. The file ~/.aws/credentials should now exist on your local development system. This file contains the [default] profile that the SDK for Java uses if a specific named profile is not specified.

  4. Sign in to the AWS access portal.

  5. Follow these instructions under the Manual credential refresh heading to copy IAM role credentials from the AWS access portal.

    1. For step 4 in the linked instructions, choose the IAM role name that grants access for your development needs. This role typically has a name like PowerUserAccess or Developer.

    2. For step 7, select the Manually add a profile to your AWS credentials file option and copy the contents.

  6. Paste the copied credentials into your local credentials file and remove any profile name that was pasted. Your file should resemble the following:

    [default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE

  7. Save the credentials file

The SDK for Java will access these temporary credentials when it create a service client and use them for each request. The settings for the IAM role chosen in step 5a determine how long the temporary credentials are valid. The maximum duration is twelve hours.

After the temporary credentials expire, repeat steps 4 through 7.

Install a Java Development Environment

The AWS SDK for Java requires J2SE Development Kit 6.0 or later. You can download the latest Java software from http://www.oracle.com/technetwork/java/javase/downloads/.

Important

Java version 1.6 (JS2E 6.0) did not have built-in support for SHA256-signed SSL certificates, which are required for all HTTPS connections with AWS after September 30, 2015.

Java versions 1.7 or newer are packaged with updated certificates and are unaffected by this issue.

Choosing a JVM

For the best performance of your server-based applications with the AWS SDK for Java, we recommend that you use the 64-bit version of the Java Virtual Machine (JVM). This JVM runs only in server mode, even if you specify the -Client option at run time.

Using the 32-bit version of the JVM with the -Server option at run time should provide comparable performance to the 64-bit JVM.