Use a specific credentials provider
The SDK uses credentials providers to retrieve, manage, and supply authentication credentials (such as access keys and session tokens) that are needed to access AWS services.
Credential providers simplify retrieving credentials from various sources, implement security best practices, and support flexible authentication strategies across AWS environments.
Specify a credentials provider
To bypass the default credentials provider chain, specify which credentials provider a service client should use. When you supply a specific credentials provider, the SDK skips the process of checking various locations, which slightly reduces the time to create a service client.
For example, if you set your default configuration using environment variables,
supply an EnvironmentVariableCredentialsProvidercredentialsProvider
method on the service client builder, as shown 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 the API reference for
AwsCredentialsProvider
Note
You can also use your own credentials provider or provider chains by implementing
the AwsCredentialsProvider
interface.
Configure a credentials
provider
As an example of configuring a credentials provider implementation, you might want to have the SDK use a background thread to pre-fetch (retrieve in advance) credentials before they expire. That way you can avoid the blocking call that retrieves fresh credentials.
The following shows an example that creates an StsAssumeRoleCredentialsProvider
that uses a background thread to
pre-fetch credentials by setting the asyncCredentialUpdateEnabled
property to true
on the
builder:
S3Client s3Client = S3Client.builder()
.credentialsProvider(StsAssumeRoleCredentialsProvider.builder()
.asyncCredentialUpdateEnabled(true)
.stsClient(StsClient.create())
.refreshRequest(r -> r
.roleArn("arn:aws:iam::111122223333:role/S3-listbuckets-only-role")
.roleSessionName("test-temp-session")
.durationSeconds(900))
.build())
.build();
When you invoke an operation on s3Client
for the first time, an
AssumeRoleRequest
is sent to the AWS Security Token Service (STS). STS returns
temporary credentials that are valid for 15 minutes (900 seconds). The
s3Client
instance uses the cached credentials until it's time to refresh
them before the 15 minutes elapse. By default, the SDK attempts to retrieve new
credentials for a new session between 5 minutes and 1 minute before the expiration time
of the current session. The pre-fetch window is configurable by using the prefetchTime
and staleTime
properties.
You can configure the following session-based credentials providers similarly:
-
StsWebIdentityTokenFileCredentialsProvider
-
StsGetSessionTokenCredentialsProvider
-
StsGetFederationTokenCredentialsProvider
-
StsAssumeRoleWithWebIdentityCredentialsProvider
-
StsAssumeRoleWithSamlCredentialsProvider
-
StsAssumeRoleCredentialsProvider
-
DefaultCredentialsProvider
(when it delegates to credentials provider that uses sessions) -
ProcessCredentialsProvider
-
WebIdentityTokenFileCredentialsProvider
-
ContainerCredentialsProvider
-
InstanceProfileCredentialsProvider