Default credentials provider chain in the AWS SDK for Java 2.x (original) (raw)

The default credentials provider chain in the AWS SDK for Java 2.x automatically searches for AWS credentials in a predefined sequence of locations, allowing applications to authenticate with AWS services without explicitly specifying credential sources.

The default credentials provider chain is implemented by the DefaultCredentialsProvider class. It sequentially delegates to other credentials provider implementations that check for configuration in various locations. The first credentials provider that can find all necessary configuration elements causes the chain to end.

To use the default credentials provider chain to supply temporary credentials, create a service client builder but don't specify a credentials provider. The following code snippet creates a DynamoDbClient that uses the default credentials provider chain to locate and retrieve configuration settings.

// Any external Region configuration is overridden.
// The SDK uses the default credentials provider chain because no specific credentials provider is specified.
Region region = Region.US_WEST_2;
DynamoDbClient ddb = 
    DynamoDbClient.builder()
                  .region(region)
                  .build();

Credential settings retrieval order

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

  1. Java system properties
    • The SDK uses the SystemPropertyCredentialsProvider class to load temporary credentials from the aws.accessKeyId,aws.secretAccessKey, and aws.sessionToken Java system properties.
    Note

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

  2. Environment variables
  3. Web identity token and IAM role ARN
    • The SDK uses the WebIdentityTokenFileCredentialsProvider class to load credentials by assuming a role using a web identity token.
    • The credentials provider looks for the following environment variables or JVM system properties:
      * AWS_WEB_IDENTITY_TOKEN_FILE or`aws.webIdentityTokenFile`
      * AWS_ROLE_ARN or aws.roleArn
      * AWS_ROLE_SESSION_NAME oraws.roleSessionName (optional)
    • After the SDK acquires the values, it calls the AWS Security Token Service (STS) and uses the temporary credentials it returns to sign requests.
    • Runtime environments such as Amazon Elastic Kubernetes Service (EKS) automatically make web identity tokens available to AWS SDKs, enabling applications to obtain temporary AWS credentials.
  4. The shared credentials and config files
    • The SDK uses the ProfileCredentialsProvider to load IAM Identity Center single sign-on settings or temporary credentials from the [default] profile in the sharedcredentials and config files.
      The AWS SDKs and Tools Reference Guide has detailed information about how the SDK for Java works with the IAM Identity Center single sign-on token to get temporary credentials that the SDK uses to call AWS services.
    • Because a profile in the shared credentials andconfig files can contain many different sets of settings, the ProfileCredentialsProvider delegates to a series of other providers to look for settings under the [default] profile:
      * Basic credentials (classStaticCredentialsProvider): When the profile containsaws_access_key_id andaws_secret_access_key.
      * Session credentials (classStaticSessionCredentialsProvider): When the profile contains aws_access_key_id,aws_secret_access_key, andaws_session_token.
      * Process credentials (classProcessCredentialsProvider): When the profile containscredential_process.
      * SSO credentials (classSsoCredentialsProvider): When the profile contains SSO-related properties such as sso_role_name,sso_account_id.
      * Web identity token credentials (class WebIdentityTokenCredentialsProvider): When the profile contains role_arn andweb_identity_token_file.
      * Role-based credentials with source profile (classStsAssumeRoleCredentialsProvider): When the profile contains role_arn and source_profile.
      * Role-based credentials with credential source (classStsAssumeRoleWithSourceCredentialsProvider): When the profile contains role_arn andcredential_source.
      * When credential_source = Environment: It uses a chain of SystemPropertyCredentialsProvider andEnvironmentVariableCredentialsProvider
      * When credential_source = Ec2InstanceMetadata: It uses InstanceProfileCredentialsProvider
      * When credential_source = EcsContainer: It usesContainerCredentialsProvider
  5. Amazon ECS container credentials
    • The SDK uses the ContainerCredentialsProvider class to load temporary credentials using the following environment variables:
      1. AWS_CONTAINER_CREDENTIALS_RELATIVE_URI orAWS_CONTAINER_CREDENTIALS_FULL_URI
      2. AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE orAWS_CONTAINER_AUTHORIZATION_TOKEN

The ECS container agent automatically sets theAWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable, which points to the ECS credentials endpoint. The other environment variables are typically set in specific scenarios where the standard ECS credential endpoint isn't used. 6. Amazon EC2 instance IAM role-provided credentials

  1. If the SDK can't find the necessary configuration settings through all this steps listed above, it throws an exception with output similar to the following:
software.amazon.awssdk.core.exception.SdkClientException: Unable to load credentials from any of the providers  
in the chain AwsCredentialsProviderChain(credentialsProviders=[SystemPropertyCredentialsProvider(),  
EnvironmentVariableCredentialsProvider(), WebIdentityTokenCredentialsProvider(), ProfileCredentialsProvider(),  
ContainerCredentialsProvider(), InstanceProfileCredentialsProvider()])

Use theDefaultCredentialsProvider in code

You can explicitly use the default credentials provider chain in your code. This is functionally equivalent to you not specifying a credentials provider at all, since the SDK uses DefaultCredentialsProvider by default. However, explicitly using it can make your code more readable and self-documenting. It clearly shows your intention to use the default credentials chain.

import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;

public class ExplicitDefaultCredentialsExample {
    public static void main(String[] args) {
        // Explicitly create the DefaultCredentialsProvider.
        DefaultCredentialsProvider defaultCredentialsProvider = DefaultCredentialsProvider
                                                                    .builder().build();

        // Use it with any service client.
        S3Client s3Client = S3Client.builder()
            .region(Region.US_WEST_2)
            .credentialsProvider(defaultCredentialsProvider)
            .build();

        // Now you can use the client with the default credentials chain.
        s3Client.listBuckets();
    }
}

When you build the default credentials provider you can provide more configuration:

DefaultCredentialsProvider customizedProvider = DefaultCredentialsProvider.builder()
    .profileName("custom-profile")  // Use a specific profile if the chain gets to the `ProfileCredentialsProvider` stage.
    .asyncCredentialUpdateEnabled(true)  // Enable async credential updates.
    .build();

This approach gives you more control while still providing the convenience of the default credentials chain.