AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Working with AWS Credentials

To make requests to Amazon Web Services, you will need to supply AWS credentials to the AWS SDK for Java. There are a number of ways to do this:

  • Use the default credential provider chain (recommended)
  • Use a specific credential provider or provider chain (or create your own).
  • Supply the credentials yourself. These can be either root account credentials, IAM credentials or temporary credentials retrieved from AWS STS.


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 IAM User Guide.

This topic provides information about how to load credentials for AWS using the AWS SDK for Java.

Using the Default Credential Provider Chain#

When you initialize a new service client without supplying any arguments, the AWS SDK for Java will attempt to find AWS credentials using the default credential provider chain implemented by the DefaultAWSCredentialsProviderChain class. The default credential provider chain looks for credentials in this order:

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

  2. Java System Propertiesaws.accessKeyId and aws.secretKey. The AWS SDK for Java uses the SystemPropertiesCredentialsProvider to load these credentials.

  3. The default credential profiles file – typically located at ~/.aws/credentials (this location may vary per platform), this credentials 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, or you can create it by hand-editing the file with a text editor. For information about the credentials file format, see AWS Credentials File Format.

  4. Amazon ECS container credentials – loaded from the Amazon EC2 Container Service 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 – used on EC2 instances, and delivered through the Amazon EC2 metadata service. The AWS SDK for Java uses the InstanceProfileCredentialsProvider to load these credentials.


    Instance profile credentials are used only if AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is not set. See EC2ContainerCredentialsProviderWrapper for more information.

Setting Credentials#

AWS credentials must be set in at least one of the preceding locations in order to be used. For information about setting credentials, visit one of the following topics:

Setting an Alternate Credentials Profile#

The SDK for Java will use the default profile by default but there are a couple of ways to customize which profile is sourced from the credentials file.

The AWS Profile environment variable can be used to change the profile loaded by the SDK.

For example, on Linux, OS X, or Unix you would run the following command to change the profile to myProfile

export AWS_PROFILE="myProfile"

On Windows you would use the following:

set AWS_PROFILE="myProfile"

Setting the AWS_PROFILE environment variable will affect credential loading for all other officially supported AWS SDKs and Tools (including the AWS CLI and the AWS CLI for PowerShell). If you want to only change the profile for a Java application, you can use the system property aws.profile instead. Please note that the environment variable takes precedence over the system property.

Setting an Alternate Credentials File Location#

Although the SDK for Java will load AWS credentials automatically from the default credentials file location, you can also specify the location yourself by setting the AWS_CREDENTIAL_PROFILES_FILE environment variable with the full pathname to the credentials file.

This feature can be used to temporarily change the location where the SDK for Java looks for your credentials file (by setting this variable with the command-line, for example), or you can set the environment variable in your user or system environment to change it for the user or system-wide.

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, OS X, 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 create an AWS credentials file using the aws configure command, it creates a file with the following format:



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, which can be added or edited using aws configure --profile PROFILE_NAME to select the profile to configure.

You can specify additional fields, such as aws_session_token, metadata_service_timeout and metadata_service_num_attempts. These are not configurable with the CLI—you must edit the file by hand if you wish to use them. For more information about the configuration file and its available fields, see Configuring the AWS Command Line Interface in the AWS CLI User Guide.

Loading Credentials#

Once credentials have been set, you can load them using the default credential provider chain.

To load credentials using the default credential provider chain

  • Instantiate an AWS Service client without explicitly providing credentials to the builder. For example:

    AmazonS3 s3Client = AmazonS3ClientBuilder.standard()

Specifying a Credential Provider or Provider Chain#

If you want to specify a different credential provider than the default credential provider chain, you can specify it via the client builder.

To specify a specific credentials provider

  • Provide an instance of a credentials provider or provider chain to a client builder that takes an AWSCredentialsProvider interface as input. For example, to use environment credentials specifically:

    AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
                            .withCredentials(new EnvironmentVariableCredentialsProvider())

For the full list of AWS SDK for Java-supplied credential providers and provider chains, see the list of "All known implementing classes" in the reference topic for AWSCredentialsProvider.


You can use this technique to supply credential providers or provider chains that you create, by implementing your own credential provider that implements the AWSCredentialsProvider interface, or by sub-classing the AWSCredentialsProviderChain class.

Explicitly Specifying Credentials#

If neither the default credential chain or a specific or custom provider or provider chain works for your code, you can set credentials explicitly by supplying them yourself. If you have retrieved temporary credentials using AWS STS, use this method to specify the credentials for AWS access.

To explicitly supply credentials to an AWS client:

  1. Instantiate a class that provides the AWSCredentials interface, such as BasicAWSCredentials, supplying it with the AWS access key and secret key you will use for the connection.
  2. Create a AWSStaticCredentialsProvider with the AWSCredentials object.
  3. Configure the client builder with the AWSStaticCredentialsProvider and build the client.

For example:

BasicAWSCredentials awsCreds = new BasicAWSCredentials("access_key_id", "secret_key_id");
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
                        .withCredentials(new AWSStaticCredentialsProvider(awsCreds))

When using temporary credentials obtained from STS, create a BasicSessionCredentials object, passing it the STS-supplied credentials and session token:

BasicSessionCredentials sessionCredentials = new BasicSessionCredentials(

AmazonS3 s3 = AmazonS3ClientBuilder.standard()
                        .withCredentials(new AWSStaticCredentialsProvider(sessionCredentials)