Using credentials

To make requests to Amazon Web Services using the AWS SDK for Java, you must use cryptographically-signed credentials issued by AWS. You can use programmatic access keys or temporary security credentials such AWS SSO or IAM roles to grant access to AWS resources.

For information on setting up credentials, see Set default credentials and Region and Set up credentials profiles.

Topics

• Use the default credential provider chain
• Use a specific credentials provider or provider chain
• Use credentials profiles
• Supply credentials explicitly
• Configuring IAM roles for Amazon EC2

Use the default credential provider chain

After you Set default credentials and Region for your environment, the AWS SDK for Java will automatically use those credentials when your application makes requests to AWS. The default credential provider chain, implemented by the DefaultCredentialsProvider class, checks sequentially each of places where you can set default credentials and selects the first one you set.

To use the default credential provider chain to supply credentials in your application, create a service client builder without specifying credentials provider configuration.

Region region = Region.US_WEST_2;
DynamoDbClient ddb = DynamoDbClient.builder()
            .region(region)
            .build();

Credential retrieval order

The default credential provider chain of the AWS SDK for Java 2.x searches for credentials in your environment using a predefined sequence.

Default credential provider chain

1. Java system properties

   • The SDK uses the SystemPropertyCredentialsProvider class to load credentials from the aws.accessKeyId and aws.secretKey Java system properties. If aws.sessionToken is also specified, the SDK will use temporary credentials.

     Note

     For information on how to set Java system properties, see the System Properties tutorial on the official Java Tutorials website.

2. Environment variables

   • The SDK uses the EnvironmentVariableCredentialsProvider class to load credentials from the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY system environment variables. If AWS_SESSION_TOKEN is also specified, the SDK will use temporary credentials.

3. Web identity token from AWS STS

   • The SDK uses the WebIdentityTokenFileCredentialsProvider class to load credentials from Java system properties or environment variables.

4. The shared credentials and config files

   • The SDK uses the ProfileCredentialsProvider to load credentials from the [default] credentials profile in the shared credentials and config files.

   Note

   The credentials and config files are shared by various AWS SDKs and Tools. For more information, see The .aws/credentials and .aws/config files in the AWS SDKs and Tools Reference Guide.

5. Amazon ECS container credentials

   • The SDK uses the ContainerCredentialsProvider class to load credentials from the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI system environment variable.

6. Amazon EC2 instance profile credentials

   • The SDK uses the InstanceProfileCredentialsProvider class to load credentials from the Amazon EC2 metadata service.

Use a specific credentials provider or provider chain

Alternatively, you can specify which credentials provider the SDK should use. For example, if you set your default credentials using environment variables, supply an EnvironmentVariableCredentialsProvider object to the credentialsProvider method on the service client builder, as in the following code snippet.

Region region = Region.US_WEST_2;
DynamoDbClient ddb = DynamoDbClient.builder()
            .region(region)
            .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
            .build();

For a complete list of credential providers and provider chains, see All Known Implementing Classes in AwsCredentialsProvider.

Note

You can use your own credential provider or provider chains by implementing the AwsCredentialsProvider interface.

Use credentials profiles

Using the shared credentials file, you can set up custom profiles which enables you to use multiple sets of credentials in your application. The [default] profile was mentioned above. The SDK uses the ProfileCredentialsProvider class to load credentials from profiles defined in the shared credentials file.

For information on how to set up custom profiles, see Set up credentials profiles.

This code snippet demonstrates how to build a service client that uses the credentials defined as part of the profile_name profile.

Region region = Region.US_WEST_2;
DynamoDbClient ddb = DynamoDbClient.builder()
            .region(region)
            .credentialsProvider(ProfileCredentialsProvider.create("profile_name"))
            .build();

Set a custom profile as the default

To set a profile other than the [default] profile as the default for your application, set the AWS_PROFILE environment variable to the name of your custom profile.

To set this variable on Linux, macOS, or Unix, use export:

export AWS_PROFILE="other_profile"

To set these variables on Windows, use set:

set AWS_PROFILE="other_profile"

Alternatively, set the aws.profile Java system property to the name of the profile.

Supply credentials explicitly

If the default credential chain or a specific or custom provider or provider chain doesn’t work for your application, you can supply the credentials that you want directly in code. 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, use IAM account credentials instead of the AWS account credentials when accessing AWS. 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 a StaticCredentialsProvider object and supply it with the AwsCredentials object.

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

The following example creates a new service client using credentials that you supply:

AwsBasicCredentials awsCreds = AwsBasicCredentials.create(
    "your_access_key_id",
    "your_secret_access_key");

S3Client s3 = S3Client.builder()
                       .credentialsProvider(StaticCredentialsProvider.create(awsCreds))
                       .build();