The Amazon SDK for Java 1.x reached end-of-support on December 31, 2025. We recommend that you migrate to the [Amazon SDK for Java 2.x](https://docs.amazonaws.cn/sdk-for-java/latest/developer-guide/home.html) to continue receiving new features, availability improvements, and security updates.
# Provide temporary credentials to the Amazon SDK for Java
To make requests to Amazon Web Services, you must supply Amazon temporary credentials for the Amazon SDK for Java to use when it calls the services. You can do this in the following ways:
+ Use the default credential provider chain *(recommended)*.
+ Use a specific credential provider or provider chain (or create your own).
+ Supply the temporary credentials yourself in code.
## Using the Default Credential Provider Chain
When you initialize a new service client without supplying any arguments, the Amazon SDK for Java attempts to find temporary credentials by using the *default credential provider chain* implemented by the [DefaultAWSCredentialsProviderChain](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/DefaultAWSCredentialsProviderChain.html) class. The default credential provider chain looks for credentials in this order:
1. **Environment variables**-`Amazon_ACCESS_KEY_ID`, `Amazon_SECRET_KEY` or `Amazon_SECRET_ACCESS_KEY`, and `Amazon_SESSION_TOKEN`. The Amazon SDK for Java uses the [EnvironmentVariableCredentialsProvider](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/EnvironmentVariableCredentialsProvider.html) class to load these credentials.
1. **Java system properties**-`aws.accessKeyId`, `aws.secretKey` (but not `aws.secretAccessKey`), and `aws.sessionToken`. The Amazon SDK for Java uses the [SystemPropertiesCredentialsProvider](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/SystemPropertiesCredentialsProvider.html) to load these credentials.
1. **Web Identity Token credentials** from the environment or container.
1. **The default credential profiles file**- typically located at `~/.aws/credentials` (location can vary per platform), and shared by many of the Amazon SDKs and by the Amazon CLI. The Amazon SDK for Java uses the [ProfileCredentialsProvider](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/profile/ProfileCredentialsProvider.html) to load these credentials.
You can create a credentials file by using the `aws configure` command provided by the Amazon CLI, or you can create it by editing the file with a text editor. For information about the credentials file format, see [Amazon Credentials File Format](#credentials-file-format).
1. **Amazon ECS container credentials**- loaded from the Amazon ECS if the environment variable `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is set. The Amazon SDK for Java uses the [ContainerCredentialsProvider](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/ContainerCredentialsProvider.html) to load these credentials. You can specify the IP address for this value.
1. **Instance profile credentials**- used on EC2 instances, and delivered through the Amazon EC2 metadata service. The Amazon SDK for Java uses the [InstanceProfileCredentialsProvider](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/InstanceProfileCredentialsProvider.html) to load these credentials. You can specify the IP address for this value.
**Note**
Instance profile credentials are used only if `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is not set. See [EC2ContainerCredentialsProviderWrapper](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/EC2ContainerCredentialsProviderWrapper.html) for more information.
### Set temporary credentials
To be able to use Amazon temporary credentials, they must be set in *at least one* of the preceding locations. For information about setting credentials, see the following topics:
+ To specify credentials in the *environment* or in the default *credential profiles file*, see [Configure temporary credentials](setup-credentials.md#setup-credentials-setting) .
+ To set Java *system properties*, see the [System Properties](http://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) tutorial on the official *Java Tutorials* website.
+ To set up and use *instance profile credentials* with your EC2 instances, see [Using IAM Roles to Grant Access to Amazon Resources on Amazon EC2](java-dg-roles.md).
### Set an alternate credentials profile
The Amazon SDK for Java uses the *default* profile by default, but there are ways to customize which profile is sourced from the credentials file.
You can use the Amazon Profile environment variable to change the profile loaded by the SDK.
For example, on Linux, macOS, 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 affects credential loading for all officially supported Amazon SDKs and Tools (including the Amazon CLI and the Amazon Tools for Windows PowerShell). To change only the profile for a Java application, you can use the system property `aws.profile` instead.
**Note**
The environment variable takes precedence over the system property.
### Set an alternate credentials file location
The Amazon SDK for Java loads Amazon temporary 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 Amazon SDK for Java looks for your credentials file (for example, by setting this variable with the command line). Or you can set the environment variable in your user or system environment to change it for the user or systemwide.
#### To override the default credentials file location
+ Set the `AWS_CREDENTIAL_PROFILES_FILE` environment variable to the location of your Amazon credentials file.
+ On Linux, macOS, or Unix, use:
```
export AWS_CREDENTIAL_PROFILES_FILE=path/to/credentials_file
```
+ On Windows, use:
```
set AWS_CREDENTIAL_PROFILES_FILE=path/to/credentials_file
```
### `Credentials` file format
By following the[ instructions in the Basic setup](signup-create-iam-user.md#setup-temp-creds) of this guide, your credentials file should have the following basic format.
```
[default]
aws_access_key_id={{}}
aws_secret_access_key={{}}
aws_session_token={{}}
[profile2]
aws_access_key_id={{}}
aws_secret_access_key={{}}
aws_session_token={{}}
```
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 `metadata_service_timeout`, and `metadata_service_num_attempts`. These are not configurable with the CLI—you must edit the file by hand if you want to use them. For more information about the configuration file and its available fields, see [Configuring the Amazon Command Line Interface](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the Amazon Command Line Interface User Guide.
### Load credentials
After you set temporary credentials, the SDK loads them by using the default credential provider chain.
To do this, you instantiate an Amazon Web Services service client without explicitly providing credentials to the builder, as follows.
```
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
.withRegion(Regions.US_WEST_2)
.build();
```
## Specify a credential provider or provider chain
You can specify 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](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/AWSCredentialsProvider.html) interface as input. The following example shows how to use *environment* credentials specifically.
```
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
.withCredentials(new EnvironmentVariableCredentialsProvider())
.build();
```
For the full list of Amazon SDK for Java-supplied credential providers and provider chains, see **All Known Implementing Classes** in [AWSCredentialsProvider](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/AWSCredentialsProvider.html).
**Note**
You can use this technique to supply credential providers or provider chains that you create by using your own credential provider that implements the `AWSCredentialsProvider` interface, or by subclassing the [AWSCredentialsProviderChain](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/AWSCredentialsProviderChain.html) class.
## Explicitly specify temporary credentials
If the default credential chain or a specific or custom provider or provider chain doesn’t work for your code, you can set credentials that you supply explicitly. If you’ve retrieved temporary credentials using Amazon STS, use this method to specify the credentials for Amazon access.
1. Instantiate the [BasicSessionCredentials](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/BasicSessionCredentials.html) class, and supply it with the Amazon access key, Amazon secret key, and Amazon session token that the SDK will use for the connection.
1. Create an [AWSStaticCredentialsProvider](https://docs.amazonaws.cn/sdk-for-java/v1/reference/com/amazonaws/auth/AWSStaticCredentialsProvider.html) with the `AWSCredentials` object.
1. Configure the client builder with the `AWSStaticCredentialsProvider` and build the client.
The following is an example.
```
BasicSessionCredentials awsCreds = new BasicSessionCredentials("access_key_id", "secret_key_id", "session_token");
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
.withCredentials(new AWSStaticCredentialsProvider(awsCreds))
.build();
```
## More Info
+ [Sign Up for Amazon and Create an IAM User](signup-create-iam-user.md)
+ [Set up Amazon Credentials and Region for Development](setup-credentials.md)
+ [Using IAM Roles to Grant Access to Amazon Resources on Amazon EC2](java-dg-roles.md)