Using credentials

To make requests to Amazon Web Services using the AWS SDK for Java 2.x, you must use cryptographically-signed credentials issued by AWS. You can use programmatic access keys or temporary security credentials such as AWS IAM Identity Center (successor to AWS Single Sign-On) 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
• Load credentials from an external process
• 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 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 SDK for Java 2.x searches for credentials in your environment using a predefined sequence.

1. Java system properties

   • The SDK uses the SystemPropertyCredentialsProvider class to load credentials from the aws.accessKeyId and aws.secretAccessKey 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 Security Token Service

   • 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

As an alternative to the default credential provider chain, 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.

The following code snippet demonstrates how to build a service client that uses the credentials defined as part of the profile named my_profile.

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

Set a different 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.

Load credentials from an external process

Warning

The following describes a method of sourcing credentials from an external process. This can potentially be dangerous, so proceed with caution. Other credential providers should be preferred if at all possible. If using this option, you should make sure that the config file is as locked down as possible using security best practices for your operating system.

Ensure that your custom credential tool does not write any secret information to StdErr because the SDKs and CLI can capture and log such information, potentially exposing it to unauthorized users.

The SDK for Java 2.x allows you to acquire credentials from an external process for custom use cases. There are two ways to configure this functionality.

Use the credential_process setting

If you have a method that provides credentials, you can integrate it by adding the credential_process setting as part of a profile definition in the config file. The value you specify must use the full path to the command file and surround the file path with quotation marks if it contains any spaces.

The SDK will call the command exactly as given and then read JSON data from stdout.

The following examples show the use of this setting for file paths that have no spaces and for file paths that do contain spaces.

Linux/MacOS

No spaces in file path

[profile process-credential-profile]
credential_process = /path/to/credential/file/credential_file.sh --custom-command custom_parameter

Spaces in file path

[profile process-credential-profile]
credential_process = "/path/with/space to/credential/file/credential_file.sh" --custom-command custom_parameter

Windows

No spaces in file path

[profile process-credential-profile]
credential_process = C:\Path\To\credentials.cmd --custom_command custom_parameter

Spaces in file path

[profile process-credential-profile]
credential_process = "C:\Path\With Space To\credentials.cmd" --custom_command custom_parameter

The following code snippet demonstrates how to build a service client that uses the credentials defined as part of the profile named process-credential-profile.

Region region = Region.US_WEST_2;
S3Client s3Client = S3Client.builder()
      .region(region)
      .credentialsProvider(ProfileCredentialsProvider.create("process-credential-profile"))
      .build();

For detailed information about using an external processes as a source of credentials, refer to the process credentials section in the AWS SDKs and Tools Reference Guide.

Use the ProcessCredentialsProvider

As an alternative to using settings in the config file, you can use the SDK's ProcessCredentialsProvider to load credentials using Java.

The following examples show various versions of how to specify an external process using the ProcessCredentialsProvider and configuring a service client that uses the credentials.

Linux/MacOS

No spaces in file path

ProcessCredentialsProvider credentials = 
    ProcessCredentialsProvider
        .builder()
        .command("/path/to/credentials.sh optional_param1 optional_param2")
        .build();

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

Spaces in file path

ProcessCredentialsProvider credentials = 
    ProcessCredentialsProvider
        .builder()
        .command("/path\\ with\\ spaces\\ to/credentials.sh optional_param1 optional_param2")
        .build();

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

Windows

No spaces in file path

ProcessCredentialsProvider credentials = 
    ProcessCredentialsProvider
        .builder()
        .command("C:\\Path\\To\\credentials.exe optional_param1 optional_param2")
        .build();

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

Spaces in file path

ProcessCredentialsProvider credentials = 
    ProcessCredentialsProvider
        .builder()
        .command("\"C:\\Path\\With Spaces To\\credentials.exe\" optional_param1 optional_param2")
        .build();

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

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.

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();