AWS SDK for Java version 2
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Supplying and Retrieving AWS Credentials

To make requests to Amazon Web Services (AWS), you must supply AWS credentials to the AWS SDK for Java. You can do this by using the following methods:

  • Use the default credential provider chain (recommended).

  • Use a specific credential provider or provider chain.

  • Supply credentials explicitly.

Each of these methods is discussed in the following sections.

Use the Default Credential Provider Chain

When you initialize a new service client without supplying any arguments, the AWS SDK for Java attempts to find AWS credentials. It uses the default credential provider chain implemented by the DefaultCredentialsProvider class.

The following example creates a new service client that uses the default credential provider chain:

S3Client s3 = S3Client.builder() .region(Region.US_WEST_2) .build();

Credential Retrieval Order

When the default credential provider chain attempts to retrieve credentials, it uses the following in the order shown:

  1. Java system propertiesaws.accessKeyId and aws.secretAccessKey. The AWS SDK for Java uses the SystemPropertyCredentialsProvider to load these credentials.

  2. Environment variablesAWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. The AWS SDK for Java uses the EnvironmentVariableCredentialsProvider class to load these credentials.

  3. The default credential profiles file– The specific location of this file can vary per platform, but is typically located at ~/.aws/credentials. This file is shared by many of the AWS SDKs and by the AWS CLI. The AWS SDK for Java uses the ProfileCredentialsProvider to load these credentials.

    You can create a credentials file by using the aws configure command provided by the AWS CLI. You can also create it by editing the file with a text editor. For information about the credentials file format, see AWS Credentials File Format.

  4. Amazon ECS container credentials– This is loaded from Amazon ECS if the environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is set. The AWS SDK for Java uses the ContainerCredentialsProvider to load these credentials.

  5. Instance profile credentials– This is used on Amazon EC2 instances, and delivered through the Amazon EC2 metadata service. The AWS SDK for Java uses the InstanceProfileCredentialsProvider to load these credentials.

Setting Credentials

To use AWS credentials, supply them in at least one of the preceding locations. For information about setting credentials, see the following topics:

Setting an Alternate Credentials Profile

The AWS SDK for Java uses the default profile, but there are ways to customize which profile is sourced from the credentials file.

You can use the AWS_PROFILE environment variable to change the profile loaded by the SDK.

For example, in Linux, macOS, or Unix, you run the following command to change the profile to myProfile.

export AWS_PROFILE="myProfile"

In Windows, run the following command.

set AWS_PROFILE="myProfile"

Setting the AWS_PROFILE environment variable affects credential loading for all officially supported AWS SDKs and tools, for example the AWS CLI and the AWS Tools for PowerShell. To change only the profile for a Java application, use the system property aws.profile instead.

Setting an Alternate Credentials File Location

The AWS SDK for Java loads AWS credentials automatically from the default credentials file location. However, you can also specify the location by setting the AWS_CREDENTIAL_PROFILES_FILE environment variable with the full path to the credentials file.

You can use this feature to temporarily change the location where the AWS SDK for Java looks for your credentials file. For example, set this variable with the command line. You can also set the environment variable in your user or system environment to change it for the user specifically or across the system.

To override the default credentials file location

  • Set the AWS_CREDENTIAL_PROFILES_FILE environment variable to the location of your AWS credentials file.

    • On Linux, macOS, or Unix, use export :

      export AWS_CREDENTIAL_PROFILES_FILE=path/to/credentials_file
    • On Windows, use set :

      set AWS_CREDENTIAL_PROFILES_FILE=path/to/credentials_file

AWS Credentials File Format

When you use the aws configure command to create an AWS credentials file, the command creates a file with the following format.

[default] aws_access_key_id={YOUR_ACCESS_KEY_ID} aws_secret_access_key={YOUR_SECRET_ACCESS_KEY} [profile2] aws_access_key_id={YOUR_ACCESS_KEY_ID} aws_secret_access_key={YOUR_SECRET_ACCESS_KEY}

The profile name is specified in square brackets (for example, [default]), followed by the configurable fields in that profile as key-value pairs. You can have multiple profiles in your credentials file. You can add or edit them using aws configure --profile PROFILE_NAME to select the profile to configure. In addition to the access key and secret access keys, you can specify a session token using the aws_session_token field.

Use a Specific Credential Provider or Provider Chain

You can use a credential provider that is different from the default credential provider chain by using the client builder.

You provide an instance of a credentials provider or provider chain to a client builder that takes an AwsCredentialsProvider interface as input.

The following example creates a new service client that uses the environment credentials provided, called EnvironmentVariableCredentialsProvider:

S3Client s3 = S3Client.builder() .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .build();

For the full list of AWS SDK for Java-supplied credential providers and provider chains, see All Known Implementing Classes in AwsCredentialsProvider.

Note

You supply credential providers or provider chains that you create by using your own credential provider that implements the AwsCredentialsProvider interface.

Supply Credentials Explicitly

If the default credential chain or a specific or custom provider or provider chain doesn't work for your code, you can supply the credentials that you want. These can be AWS account credentials, IAM credentials, or temporary credentials retrieved from AWS Security Token Service (AWS STS). If you've retrieved temporary credentials using AWS STS, use this method to specify the credentials for AWS access.

Important

For security, we strongly recommend that you use IAM account credentials instead of the AWS account credentials for AWS access. For more information, see AWS Security Credentials in the Amazon Web Services General Reference.

To explicitly supply credentials to an AWS client

  1. Instantiate a class that provides the AwsCredentials interface, such as AwsSessionCredentials. Supply it with the AWS access key and secret key to use for the connection.

  2. Create an StaticCredentialsProvider with the AwsCredentials object.

  3. Configure the client builder with the StaticCredentialsProvider and build the client.

The following example creates a new service client that uses credentials that you supplied:

AwsSessionCredentials awsCreds = AwsSessionCredentials.create( "your_access_key_id_here", "your_secret_key_id_here", "your_session_token_here"); S3Client s32 = S3Client.builder() .credentialsProvider(StaticCredentialsProvider.create(awsCreds)) .build();