Credentials providers

To make requests to Amazon Web Services using the AWS SDK for Kotlin, the SDK uses cryptographically-signed credentials issued by AWS. At runtime, the SDK retrieves configuration values for credentials by checking several locations.

If the retrieved configuration includes IAM Identity Center single sign-on access settings, the SDK works with the IAM Identity Center to retrieve temporary credentials that it uses to make request to AWS services.

If the retrieved configuration includes temporary credentials, the SDK uses them to make AWS service calls. Temporary credentials consist of access keys and a session token.

The default credentials provider chain

When not explicitly specified at client construction, the SDK for Kotlin uses a credential provider that sequentially checks each place where you can supply credentials.

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

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

For more information, see the various ways to construct and configure a client.

Credential retrieval order

The default credentials provider chain searches for credentials using the following predefined sequence:

1. 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.

2. Shared credentials and config files

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

This sequence step is when the SDK for Kotlin uses the single sign-on token that was set up by running AWS CLI command aws sso login. The SDK uses the temporary credentials that the IAM Identity Center exchanged for a valid token. The SDK then uses the temporary credentials when it calls AWS services. The AWS SDKs and Tools Reference Guide has detailed information about this process.

You can use the aws.profile JVM system property or the AWS_PROFILE environment variable to choose the profile you want the SDK to load.

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.

3. AWS STS web identity (including Amazon Elastic Kubernetes Service (Amazon EKS))

The SDK attempts to resolve JVM system properties and environment variables to assume a role using a web identity.

4. Amazon ECS container credentials (IAM roles for task)

The SDK attempts to resolve AWS_CONTAINER_CREDENTIALS_RELATIVE_URI or AWS_CONTAINER_CREDENTIALS_FULL_URI environment variables to fetch credentials from.

5. Amazon EC2 Instance Metadata Service (IAM role attached to an instance)

The SDK attempts to fetch credentials from the Instance Metadata Service.

Note

The SDK only supports IMDSv2.

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

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.