Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Credentials caching in the Amazon SDK for Java 2.x

The Amazon SDK for Java 2.x implements credential caching to improve performance and reduce calls to credentials sources. This section explains how credentials caching works and how you can configure it for your applications.

Understanding credential provider caching

Credential providers in the SDK for Java 2.x use different caching strategies:

Providers with internal credentials caching

The following credentials providers cache credentials internally, even when you create new instances:

Providers without internal caching

The following providers don't implement internal caching:

Configuring credential caching

You can customize caching behavior when building credential providers:

Stale Time

Controls when credentials are considered stale and need refreshing:

.staleTime(Duration.ofMinutes(2))  // Consider stale 2 minutes before expiration.

Prefetch Time

Determines when to start refreshing credentials before they expire:

.prefetchTime(Duration.ofMinutes(10))  // Start refresh 10 minutes before expiration.

Asynchronous Updates

Enables background credential refreshing:

.asyncCredentialUpdateEnabled(true)  // Refresh credentials in background thread.

Session Duration

For STS-based providers, controls how long temporary credentials remain valid:

.refreshRequest(r -> r.durationSeconds(3600))  // 1 hour session.

Caching credentials configuration example

As an example of configuring caching for 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:

StsAssumeRoleCredentialsProvider provider = StsAssumeRoleCredentialsProvider.builder()
    .refreshRequest(r -> r
        .roleArn("arn:aws:iam::111122223333:role/example-role")
        .roleSessionName("example-session")
        .durationSeconds(3600))  // 1 hour session
    .staleTime(Duration.ofMinutes(5))  // Consider stale 5 minutes before expiration
    .prefetchTime(Duration.ofMinutes(10))  // Start refresh 10 minutes before expiration
    .asyncCredentialUpdateEnabled(true)  // Refresh in background
    .build();

S3Client s3 = S3Client.builder()
    .credentialsProvider(provider)
    .build();

When you invoke an operation on s3Client for the first time, an AssumeRoleRequest is sent to the Amazon 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:

Understanding credential caching helps you optimize your application's performance and reliability when working with Amazon Web Services services.