Skip to content

Add non-recoverable STS error codes #7241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alextwoods wants to merge 1 commit into
base: feature/master/credential_cache
Choose a base branch
from
+354 −1
Open

Add non-recoverable STS error codes #7241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion ...es/sts/src/main/java/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,11 @@

import java.time.Duration;
import java.time.Instant;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashSet;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.function.Function;
import software.amazon.awssdk.annotations.NotThreadSafe;
Expand All @@ -26,6 +30,7 @@
import software.amazon.awssdk.auth.credentials.AwsCredentials;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import software.amazon.awssdk.auth.credentials.AwsSessionCredentials;
import software.amazon.awssdk.awscore.exception.AwsServiceException;
import software.amazon.awssdk.identity.spi.AwsCredentialsIdentity;
import software.amazon.awssdk.services.sts.StsClient;
import software.amazon.awssdk.utils.Logger;
Expand Down Expand Up @@ -53,6 +58,21 @@
@ThreadSafe
@SdkPublicApi
public abstract class StsCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable {

/**
* STS error codes that indicate a non-recoverable failure. When a credential refresh fails with one of these codes,
* the error bypasses static stability and is surfaced to the caller immediately, because retrying cannot fix the
* underlying problem.
*/
static final Set<String> NON_RECOVERABLE_ERROR_CODES = Collections.unmodifiableSet(new HashSet<>(Arrays.asList(
"AccessDenied",
"IDPRejectedClaim",
"InvalidIdentityToken",
"MalformedPolicyDocument",
"PackedPolicyTooLarge",
"RegionDisabledException"
)));

private static final Logger log = Logger.loggerFor(StsCredentialsProvider.class);

private static final Duration DEFAULT_STALE_TIME = Duration.ofMinutes(1);
Expand Down Expand Up @@ -86,7 +106,8 @@ public abstract class StsCredentialsProvider implements AwsCredentialsProvider,
CachedSupplier.builder(this::updateSessionCredentials)
.cachedValueName(toString())
.staleValueBehavior(CachedSupplier.StaleValueBehavior.ALLOW)
.prefetchJitterEnabled(false);
.prefetchJitterEnabled(false)
.nonRecoverableErrorPredicate(StsCredentialsProvider::isNonRecoverableError);
if (builder.asyncCredentialUpdateEnabled) {
cacheBuilder.prefetchStrategy(new NonBlocking(asyncThreadName));
}
Expand Down Expand Up @@ -153,6 +174,25 @@ public Duration prefetchTime() {
public String toString() {
return ToString.create(providerName());
}

static boolean isNonRecoverableError(RuntimeException e) {
AwsServiceException serviceException = extractServiceException(e);
if (serviceException == null || serviceException.awsErrorDetails() == null) {
return false;
}
String errorCode = serviceException.awsErrorDetails().errorCode();
return errorCode != null && NON_RECOVERABLE_ERROR_CODES.contains(errorCode);
}

private static AwsServiceException extractServiceException(RuntimeException e) {
if (e instanceof AwsServiceException) {
return (AwsServiceException) e;
}
if (e.getCause() instanceof AwsServiceException) {
return (AwsServiceException) e.getCause();
}
return null;
}

/**
* Implemented by a child class to call STS and get a new set of credentials to be used by this provider.
Expand Down
150 changes: 150 additions & 0 deletions ...rc/test/java/software/amazon/awssdk/services/sts/auth/StsCredentialsProviderTestBase.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,19 @@

import java.time.Duration;
import java.time.Instant;
import java.util.stream.Stream;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.MethodSource;
import org.mockito.Mock;
import org.mockito.Mockito;
import org.mockito.junit.jupiter.MockitoExtension;
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.AwsCredentials;
import software.amazon.awssdk.auth.credentials.AwsSessionCredentials;
import software.amazon.awssdk.awscore.exception.AwsErrorDetails;
import software.amazon.awssdk.awscore.exception.AwsServiceException;
import software.amazon.awssdk.core.exception.SdkClientException;
import software.amazon.awssdk.identity.spi.AwsCredentialsIdentity;
import software.amazon.awssdk.services.sts.StsClient;
Expand Down Expand Up @@ -160,6 +165,151 @@ public void initialFetchFailureThrowsException_noCachedCredentials() {
}
}

static Stream<String> nonRecoverableErrorCodes() {
return StsCredentialsProvider.NON_RECOVERABLE_ERROR_CODES.stream();
}

/**
* Non-recoverable STS errors must bypass static stability and propagate to the caller immediately,
* even when cached credentials exist. This is because retrying the same request will never succeed
* for these error codes — the underlying problem (e.g., revoked access, invalid policy) requires
* operator intervention.
*/
@ParameterizedTest
@MethodSource("nonRecoverableErrorCodes")
public void nonRecoverableError_bypassesStaticStability_throwsImmediately(String errorCode) {
// First call returns valid but already-expired credentials (forces refresh on next call)
Credentials validCredentials = Credentials.builder()
.accessKeyId("a")
.secretAccessKey("b")
.sessionToken("c")
.expiration(Instant.now().minus(Duration.ofSeconds(5)))
.build();
RequestT request = getRequest();
ResponseT response = getResponse(validCredentials);

AwsServiceException nonRecoverableException = AwsServiceException.builder()
.message("Access denied")
.awsErrorDetails(AwsErrorDetails.builder()
.errorCode(errorCode)
.errorMessage("Non-recoverable STS error")
.serviceName("STS")
.build())
.statusCode(403)
.build();

// First call succeeds, second call fails with a non-recoverable error
when(callClient(stsClient, request))
.thenReturn(response)
.thenThrow(nonRecoverableException);

StsCredentialsProvider.BaseBuilder<?, ? extends StsCredentialsProvider> credentialsProviderBuilder =
createCredentialsProviderBuilder(request);

try (StsCredentialsProvider credentialsProvider = credentialsProviderBuilder.stsClient(stsClient).build()) {
// First call succeeds and caches credentials
AwsCredentials firstResult = credentialsProvider.resolveCredentials();
assertThat(((AwsSessionCredentials) firstResult).accessKeyId()).isEqualTo("a");

// Second call must throw because the error is non-recoverable — static stability must NOT absorb it
assertThatThrownBy(credentialsProvider::resolveCredentials)
.isInstanceOf(AwsServiceException.class)
.satisfies(e -> assertThat(((AwsServiceException) e).awsErrorDetails().errorCode())
.isEqualTo(errorCode));
}
}

/**
* Non-recoverable errors wrapped inside an SdkClientException (as a cause) must also bypass
* static stability. The predicate extracts the AwsServiceException from the exception chain.
*/
@Test
public void nonRecoverableError_wrappedInSdkClientException_throwsImmediately() {
Credentials validCredentials = Credentials.builder()
.accessKeyId("a")
.secretAccessKey("b")
.sessionToken("c")
.expiration(Instant.now().minus(Duration.ofSeconds(5)))
.build();
RequestT request = getRequest();
ResponseT response = getResponse(validCredentials);

AwsServiceException accessDenied = AwsServiceException.builder()
.message("Access denied")
.awsErrorDetails(AwsErrorDetails.builder()
.errorCode("AccessDenied")
.errorMessage("User is not authorized")
.serviceName("STS")
.build())
.statusCode(403)
.build();
// Wrap in SdkClientException as might happen in the real call path
SdkClientException wrappedException = SdkClientException.create("Failed to assume role", accessDenied);

when(callClient(stsClient, request))
.thenReturn(response)
.thenThrow(wrappedException);

StsCredentialsProvider.BaseBuilder<?, ? extends StsCredentialsProvider> credentialsProviderBuilder =
createCredentialsProviderBuilder(request);

try (StsCredentialsProvider credentialsProvider = credentialsProviderBuilder.stsClient(stsClient).build()) {
AwsCredentials firstResult = credentialsProvider.resolveCredentials();
assertThat(((AwsSessionCredentials) firstResult).accessKeyId()).isEqualTo("a");

// Must throw — the wrapped AccessDenied is non-recoverable
assertThatThrownBy(credentialsProvider::resolveCredentials)
.isInstanceOf(SdkClientException.class)
.hasCauseInstanceOf(AwsServiceException.class);
}
}

/**
* Verifies that recoverable errors (those with error codes NOT in the non-recoverable set) still
* benefit from static stability — the provider returns cached credentials instead of throwing.
* This is the complement to the non-recoverable error tests: a service unavailable or throttling
* error should not propagate immediately.
*/
@Test
public void recoverableError_staticStabilityReturnsCachedCredentials() {
Credentials validCredentials = Credentials.builder()
.accessKeyId("a")
.secretAccessKey("b")
.sessionToken("c")
.expiration(Instant.now().minus(Duration.ofSeconds(5)))
.build();
RequestT request = getRequest();
ResponseT response = getResponse(validCredentials);

// A throttling error — recoverable, should be absorbed by static stability
AwsServiceException throttlingException = AwsServiceException.builder()
.message("Rate exceeded")
.awsErrorDetails(AwsErrorDetails.builder()
.errorCode("Throttling")
.errorMessage("Rate exceeded")
.serviceName("STS")
.build())
.statusCode(400)
.build();

when(callClient(stsClient, request))
.thenReturn(response)
.thenThrow(throttlingException);

StsCredentialsProvider.BaseBuilder<?, ? extends StsCredentialsProvider> credentialsProviderBuilder =
createCredentialsProviderBuilder(request);

try (StsCredentialsProvider credentialsProvider = credentialsProviderBuilder.stsClient(stsClient).build()) {
AwsCredentials firstResult = credentialsProvider.resolveCredentials();
assertThat(((AwsSessionCredentials) firstResult).accessKeyId()).isEqualTo("a");

// Second call should return cached credentials — Throttling is recoverable
AwsCredentials secondResult = credentialsProvider.resolveCredentials();
assertThat(secondResult).isInstanceOf(AwsSessionCredentials.class);
assertThat(((AwsSessionCredentials) secondResult).accessKeyId()).isEqualTo("a");
}
}

/**
* The advisory refresh window must be honored exactly, rather than being jittered to some later point. Here the
* configured window covers the credential's entire lifetime, so the advisory window opens the moment the credentials are
Expand Down
Loading
Loading