Credentials providers

The order in which the default credential provider chain resolves credentials changed with version 1.4.0 For details, see the note below.

To make requests to Amazon Web Services using the AWS SDK for Kotlin, the SDK uses cryptographically-signed credentials issued by AWS. To acquire the credentials, the SDK can use configuration settings that are located in several places, for example JVM system properties, environment variables, shared AWS config and credentials files, and Amazon EC2 instance metadata.

The SDK uses the credentials provider abstraction to simplify the process of retrieving credentials from various sources. The SDK contains several credentials provider implementations.

For example, If the retrieved configuration includes IAM Identity Center single sign-on access settings from the shared config file, the SDK works with the IAM Identity Center to retrieve temporary credentials that it uses to make request to AWS services. With this approach to acquiring credentials, the SDK uses the IAM Identity Center provider (also known as the SSO credentials provider). The set up section of this guide described this configuration.

To use a specific credentials provider, you can specify one when you create a service client. Alternatively, you can use the default credentials provider chain to search for configuration settings automatically.

The default credentials provider chain

When not explicitly specified at client construction, the SDK for Kotlin uses a credentials provider that sequentially checks each place where you can supply credentials. This default credentials provider is implemented as a chain of credentials providers.

To use the default chain to supply credentials in your application, create a service client without explicitly providing a credentialsProvider property.

val ddb = DynamoDbClient {
    region = "us-east-2"
}

For more information about service client creation, see construct and configure a client.

Learn about the default credentials provider chain

The default credentials provider chain searches for credentials configuration using the following predefined sequence. When the configured settings provide valid credentials, the chain stops.

1. AWS access keys (JVM system properties)

The SDK looks for the aws.accessKeyId, aws.secretAccessKey, and aws.sessionToken JVM system properties.

2. AWS access keys (environment variables)

The SDK attempts to load credentials from the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables.

3. Web identity token

The SDK looks for the environment variables AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_ARN (or the JVM system properties aws.webIdentityTokenFile and aws.roleArn). Based on the token information and the role, the SDK acquires temporary credentials.

4. A profile in a configuration file

In this step, the SDK uses settings associated with a profile. By default, the SDK uses the shared AWS config and credentials files, but if the AWS_CONFIG_FILE environment variable is set, the SDK uses that value. If the AWS_PROFILE environment variable (or aws.profile JVM system property) is not set, the SDK looks for the “default” profile, otherwise it looks for the profile that matches AWS_PROFILE’s value.

The SDK looks for the profile based on the configuration described in the previous paragraph and uses the settings defined there. If the settings found by the SDK contain a mix of settings for different credential-provider approaches, the SDK uses the following ordering:

1. AWS access keys (configuration file) - The SDK uses the settings for aws_access_key_id, aws_access_key_id, and aws_session_token.

2. Assume role configuration - If the SDK finds role_arn and source_profile or credential_source settings, it attempts to assume a role. If the SDK finds the source_profile setting, it sources credentials from another profile to receive temporary credentials for the role specified by role_arn. If the SDK finds the credential_source setting, it sources credentials from an Amazon ECS container, an Amazon EC2 instance, or from environment variables depending on the value of the credential_source setting. It then uses those credentials to acquire temporary credentials for the role.

   A profile should contain either the source_profile setting or the credential_source setting, but not both.

3. Web identity token configuration - If the SDK finds role_arn and web_identity_token_file settings, it acquires temporary credentials to access AWS resources based on the role_arn and the token.

4. SSO token configuration - If the SDK finds sso_session, sso_account_id, sso_role_name settings (along with a companion sso-session section in the configuration files), the SDK retrieves temporary credentials from the IAM Identity Center service.

5. Legacy SSO configuration - If the SDK finds sso_start_url, sso_region, sso_account_id, and sso_role_name settings, the SDK retrieves temporary credentials from the IAM Identity Center service.

6. Process configuration - If the SDK finds a credential_process setting, it uses the path value to invoke a process and acquire temporary credentials.

5. Container credentials

The SDK looks for environment variables AWS_CONTAINER_CREDENTIALS_RELATIVE_URI or AWS_CONTAINER_CREDENTIALS_FULL_URI and AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE or AWS_CONTAINER_AUTHORIZATION_TOKEN. It uses these values to load credentials from the specified HTTP endpoint through a GET request.

6. IMDS credentials

The SDK attempts to fetch credentials from the Instance Metadata Service at the default or configured HTTP endpoint. The SDK only supports IMDSv2.

If credentials still aren’t resolved at this point, client creation fails with an exception.

Note: Change in the order of credentials resolution

The ordering of credentials resolution described above is current for the 1.4.x+ release of the SDK for Kotlin. Before the 1.4.0 release, items number 3 and 4 were switched and the current 4a item followed the current 4f item.

Explicit credentials provider

Instead of using the default provider chain, you can specify a specific credentials provider or a custom chain (CredentialsProviderChain) that the SDK should use. For example, if you set the default credentials using environment variables, supply an EnvironmentCredentialsProvider to the client builder, as in the following code snippet.

val ddb = DynamoDbClient {
    region = "us-east-1"
    credentialsProvider = EnvironmentCredentialsProvider()
}

Note

The default chain caches credentials, but standalone providers do not. You can wrap any credentials provider using the CachedCredentialsProvider class to avoid unnecessarily fetching credentials on every API call. The cached provider only fetches new credentials when the current ones expire.

Note

You can implement your own credentials provider or provider chain by implementing the CredentialsProvider interface.