Skip to content

Add more documentation and code snippet for custom signer #6600

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

Merged
merged 2 commits into from
Dec 1, 2025
+692 −25
Merged

Add more documentation and code snippet for custom signer #6600

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a366cdc
Add more documentation and code snippet for custom signer
zoewangg Nov 27, 2025
c850c33
Fix build
zoewangg Dec 1, 2025
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
39 changes: 21 additions & 18 deletions core/auth/src/main/java/software/amazon/awssdk/auth/signer/AwsSignerExecutionAttribute.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
import software.amazon.awssdk.auth.credentials.AwsCredentials;
import software.amazon.awssdk.auth.credentials.CredentialUtils;
import software.amazon.awssdk.auth.signer.params.Aws4SignerParams;
import software.amazon.awssdk.core.SdkRequest;
import software.amazon.awssdk.core.SelectedAuthScheme;
import software.amazon.awssdk.core.interceptor.ExecutionAttribute;
import software.amazon.awssdk.core.interceptor.ExecutionInterceptor;
Expand All @@ -36,11 +37,13 @@
import software.amazon.awssdk.http.auth.aws.signer.AwsV4aHttpSigner;
import software.amazon.awssdk.http.auth.aws.signer.RegionSet;
import software.amazon.awssdk.http.auth.spi.scheme.AuthSchemeOption;
import software.amazon.awssdk.http.auth.spi.scheme.AuthSchemeProvider;
import software.amazon.awssdk.http.auth.spi.signer.AsyncSignRequest;
import software.amazon.awssdk.http.auth.spi.signer.AsyncSignedRequest;
import software.amazon.awssdk.http.auth.spi.signer.HttpSigner;
import software.amazon.awssdk.http.auth.spi.signer.SignRequest;
import software.amazon.awssdk.http.auth.spi.signer.SignedRequest;
import software.amazon.awssdk.http.auth.spi.signer.SignerProperty;
import software.amazon.awssdk.identity.spi.AwsCredentialsIdentity;
import software.amazon.awssdk.identity.spi.Identity;
import software.amazon.awssdk.regions.Region;
Expand All @@ -51,8 +54,8 @@
* AWS-specific signing attributes attached to the execution. This information is available to {@link ExecutionInterceptor}s and
* {@link Signer}s.
*
* @deprecated Signer execution attributes have been deprecated in favor of signer properties, set on the auth scheme's signer
* option.
* @deprecated Signer execution attributes have been deprecated in favor of {@link SignerProperty}s, set on the
* {@link AuthSchemeOption}. See {@link AuthSchemeProvider} and {@link SignerProperty} for how to use it.
*/
@Deprecated
@SdkProtectedApi
Expand All @@ -61,9 +64,9 @@ public final class AwsSignerExecutionAttribute extends SdkExecutionAttribute {
* The key under which the request credentials are set.
*
* @deprecated This is a protected class that is internal to the SDK, so you shouldn't be using it. If you are using it
* from execution interceptors, you should instead be overriding the credential provider via the {@code SdkRequest}'s
* from execution interceptors, you should instead be overriding the credential provider via the {@link SdkRequest}'s
* {@code overrideConfiguration.credentialsProvider}. If you're using it to call the SDK's signers, you should migrate to a
* subtype of {@code HttpSigner}.
* subtype of {@link HttpSigner}.
*/
@Deprecated
public static final ExecutionAttribute<AwsCredentials> AWS_CREDENTIALS =
Expand All @@ -79,9 +82,9 @@ public final class AwsSignerExecutionAttribute extends SdkExecutionAttribute {
* for global services like IAM.
*
* @deprecated This is a protected class that is internal to the SDK, so you shouldn't be using it. If you are using it
* from execution interceptors, you should instead be overriding the signing region via the {@code AuthSchemeProvider} that
* from execution interceptors, you should instead be overriding the signing region via the {@link AuthSchemeProvider} that
* is configured on the SDK client builder. If you're using it to call the SDK's signers, you should migrate to a
* subtype of {@code HttpSigner}.
* subtype of {@link HttpSigner}.
*/
@Deprecated
public static final ExecutionAttribute<Region> SIGNING_REGION =
Expand All @@ -97,9 +100,9 @@ public final class AwsSignerExecutionAttribute extends SdkExecutionAttribute {
* for global services like IAM.
*
* @deprecated This is a protected class that is internal to the SDK, so you shouldn't be using it. If you are using it
* from execution interceptors, you should instead be overriding the signing region scope via the {@code AuthSchemeProvider}
* from execution interceptors, you should instead be overriding the signing region scope via the {@link AuthSchemeProvider}
* that is configured on the SDK client builder. If you're using it to call the SDK's signers, you should migrate to a
* subtype of {@code HttpSigner}.
* subtype of {@link HttpSigner}.
*/
@Deprecated
public static final ExecutionAttribute<RegionScope> SIGNING_REGION_SCOPE =
Expand All @@ -114,9 +117,9 @@ public final class AwsSignerExecutionAttribute extends SdkExecutionAttribute {
* The signing name of the service to be using in SigV4 signing
*
* @deprecated This is a protected class that is internal to the SDK, so you shouldn't be using it. If you are using it
* from execution interceptors, you should instead be overriding the signing region name via the {@code AuthSchemeProvider}
* from execution interceptors, you should instead be overriding the signing region name via the {@link AuthSchemeProvider}
* that is configured on the SDK client builder. If you're using it to call the SDK's signers, you should migrate to a
* subtype of {@code HttpSigner}.
* subtype of {@link HttpSigner}.
*/
@Deprecated
public static final ExecutionAttribute<String> SERVICE_SIGNING_NAME =
Expand All @@ -131,9 +134,9 @@ public final class AwsSignerExecutionAttribute extends SdkExecutionAttribute {
* The key to specify whether to use double url encoding during signing.
*
* @deprecated This is a protected class that is internal to the SDK, so you shouldn't be using it. If you are using it
* from execution interceptors, you should instead be overriding the double-url-encode setting via the {@code
* from execution interceptors, you should instead be overriding the double-url-encode setting via the {@link
* AuthSchemeProvider} that is configured on the SDK client builder. If you're using it to call the SDK's signers, you
* should migrate to a subtype of {@code HttpSigner}.
* should migrate to a subtype of {@link HttpSigner}.
*/
@Deprecated
public static final ExecutionAttribute<Boolean> SIGNER_DOUBLE_URL_ENCODE =
Expand All @@ -148,9 +151,9 @@ public final class AwsSignerExecutionAttribute extends SdkExecutionAttribute {
* The key to specify whether to normalize the resource path during signing.
*
* @deprecated This is a protected class that is internal to the SDK, so you shouldn't be using it. If you are using it
* from execution interceptors, you should instead be overriding the normalize-path setting via the {@code
* from execution interceptors, you should instead be overriding the normalize-path setting via the {@link
* AuthSchemeProvider} that is configured on the SDK client builder. If you're using it to call the SDK's signers, you
* should migrate to a subtype of {@code HttpSigner}.
* should migrate to a subtype of {@link HttpSigner}.
*/
@Deprecated
public static final ExecutionAttribute<Boolean> SIGNER_NORMALIZE_PATH =
Expand All @@ -167,9 +170,9 @@ public final class AwsSignerExecutionAttribute extends SdkExecutionAttribute {
* @see Aws4SignerParams.Builder#signingClockOverride(Clock)
*
* @deprecated This is a protected class that is internal to the SDK, so you shouldn't be using it. If you are using it
* from execution interceptors, you should instead be overriding the clock setting via the {@code
* from execution interceptors, you should instead be overriding the clock setting via the {@link
* AuthSchemeProvider} that is configured on the SDK client builder. If you're using it to call the SDK's signers, you
* should migrate to a subtype of {@code HttpSigner}.
* should migrate to a subtype of {@link HttpSigner}.
*/
@Deprecated
public static final ExecutionAttribute<Clock> SIGNING_CLOCK =
Expand All @@ -184,9 +187,9 @@ public final class AwsSignerExecutionAttribute extends SdkExecutionAttribute {
* The key to specify the expiration time when pre-signing aws requests.
*
* @deprecated This is a protected class that is internal to the SDK, so you shouldn't be using it. If you are using it
* from execution interceptors, you should instead be overriding the expiration via the {@code AuthSchemeProvider} that is
* from execution interceptors, you should instead be overriding the expiration via the {@link AuthSchemeProvider} that is
* configured on the SDK client builder. If you're using it to call the SDK's signers, you should migrate to a subtype of
* {@code HttpSigner}.
* {@link HttpSigner}.
*/
@Deprecated
public static final ExecutionAttribute<Instant> PRESIGNER_EXPIRATION = new ExecutionAttribute<>("PresignerExpiration");
Expand Down
6 changes: 4 additions & 2 deletions core/auth/src/main/java/software/amazon/awssdk/auth/signer/S3SignerExecutionAttribute.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,19 +23,21 @@
import software.amazon.awssdk.core.interceptor.SdkInternalExecutionAttribute;
import software.amazon.awssdk.http.auth.aws.signer.AwsV4FamilyHttpSigner;
import software.amazon.awssdk.http.auth.spi.scheme.AuthSchemeOption;
import software.amazon.awssdk.http.auth.spi.scheme.AuthSchemeProvider;
import software.amazon.awssdk.http.auth.spi.signer.AsyncSignRequest;
import software.amazon.awssdk.http.auth.spi.signer.AsyncSignedRequest;
import software.amazon.awssdk.http.auth.spi.signer.HttpSigner;
import software.amazon.awssdk.http.auth.spi.signer.SignRequest;
import software.amazon.awssdk.http.auth.spi.signer.SignedRequest;
import software.amazon.awssdk.http.auth.spi.signer.SignerProperty;
import software.amazon.awssdk.identity.spi.Identity;
import software.amazon.awssdk.utils.CompletableFutureUtils;

/**
* S3-specific signing attributes attached to the execution.
*
* @deprecated Signer execution attributes have been deprecated in favor of signer properties, set on the auth scheme's signer
* option.
* @deprecated Signer execution attributes have been deprecated in favor of {@link SignerProperty}s, set on the
* {@link AuthSchemeOption}. See {@link AuthSchemeProvider} and {@link SignerProperty} for how to use it.
*/
@SdkProtectedApi
@Deprecated
Expand Down
107 changes: 107 additions & 0 deletions core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/scheme/AuthScheme.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,118 @@
* <li>A signer - An API that can be used to sign HTTP requests.</li>
* </ol>
*
* <p>
* Auth schemes are used to configure how requests are authenticated. The SDK provides built-in schemes like
* {@code AwsV4AuthScheme} for AWS Signature Version 4, but you can implement custom schemes for specialized
* authentication requirements.
*
* <p>
* See example auth schemes defined <a href="https://smithy.io/2.0/spec/authentication-traits.html">here</a>.
*
* <p>
* <b>Implementing a Custom Auth Scheme</b>
* <p>
* To implement a custom authentication scheme, you need to:
* <ol>
* <li>Implement the {@link AuthScheme} interface</li>
* <li>Implement a custom {@link HttpSigner}</li>
* <li>Configure the scheme on the client builder</li>
* </ol>
*
* <p>
* Example - Custom authentication scheme with custom signer:
*
* {@snippet :
* // Step 1: Implement custom signer
* public class CustomHttpSigner implements HttpSigner<AwsCredentialsIdentity> {
* public static final SignerProperty<String> CUSTOM_HEADER =
* SignerProperty.create(CustomHttpSigner.class, "CustomHeader");
*
* @Override
* public SignedRequest sign(SignRequest<? extends AwsCredentialsIdentity> request) {
* String headerValue = request.property(CUSTOM_HEADER);
* SdkHttpRequest signedRequest = request.request().toBuilder()
* .putHeader("X-Custom-Auth", headerValue)
* .build();
* return SignedRequest.builder()
* .request(signedRequest)
* .payload(request.payload().orElse(null))
* .build();
* }
*
* @Override
* public CompletableFuture<AsyncSignedRequest> signAsync(AsyncSignRequest<? extends AwsCredentialsIdentity> request) {
* // Async implementation
* }
* }
*
* // Step 2: Implement custom auth scheme
* public class CustomAuthScheme implements AwsV4AuthScheme {
* private static final String SCHEME_ID = "custom.auth#v1";
*
* @Override
* public String schemeId() {
* return SCHEME_ID;
* }
*
* @Override
* public IdentityProvider<AwsCredentialsIdentity> identityProvider(IdentityProviders providers) {
* return providers.identityProvider(AwsCredentialsIdentity.class);
* }
*
* @Override
* public AwsV4HttpSigner signer() {
* return new CustomHttpSigner();
* }
* }
*
* // Step 3: Configure on client
* S3AsyncClient s3 = S3AsyncClient.builder()
* .region(Region.US_WEST_2)
* .credentialsProvider(CREDENTIALS)
* .putAuthScheme(new CustomAuthScheme())
* .build();
* }
*
* <p>
* <b>Overriding Built-in Auth Schemes</b>
* <p>
* You can override built-in auth schemes by providing a custom implementation with the same scheme ID.
* The custom scheme will take precedence over the default.
*
* <p>
* Example - Overriding the default SigV4 scheme:
*
* {@snippet :
* public class CustomSigV4AuthScheme implements AwsV4AuthScheme {
* @Override
* public String schemeId() {
* // Use the same scheme ID as the default SigV4 scheme
* return AwsV4AuthScheme.SCHEME_ID;
* }
*
* @Override
* public IdentityProvider<AwsCredentialsIdentity> identityProvider(IdentityProviders providers) {
* return providers.identityProvider(AwsCredentialsIdentity.class);
* }
*
* @Override
* public AwsV4HttpSigner signer() {
* return new CustomSigV4Signer();
* }
* }
*
* S3AsyncClient s3 = S3AsyncClient.builder()
* .region(Region.US_WEST_2)
* .credentialsProvider(CREDENTIALS)
* .putAuthScheme(new CustomSigV4AuthScheme())
* .build();
* }
*
* @param <T> The type of the {@link Identity} used by this authentication scheme.
* @see IdentityProvider
* @see HttpSigner
* @see AuthSchemeProvider
*/
@SdkPublicApi
public interface AuthScheme<T extends Identity> {
Expand Down
101 changes: 99 additions & 2 deletions ...-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/scheme/AuthSchemeOption.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,108 @@
/**
* An authentication scheme option, composed of the scheme ID and properties for use when resolving the identity and signing
* the request.
*
* <p>
* Auth scheme options are returned by {@link AuthSchemeProvider}s to specify which authentication schemes should be used
* for a request, along with the properties needed to configure the identity provider and signer. The SDK will attempt
* to use the schemes in the order they are returned.
*
* <p>
* Each option contains:
* <ul>
* <li>A scheme ID - Identifies which {@link AuthScheme} to use (e.g., "aws.auth#sigv4")</li>
* <li>Identity properties - Configuration for the identity provider (e.g., account ID, role ARN)</li>
* <li>Signer properties - Configuration for the signer (e.g., signing name, region, algorithm parameters)</li>
* </ul>
*
* <p>
* <b>Using Auth Scheme Options</b>
* <p>
* Auth scheme options are typically created and modified within custom {@link AuthSchemeProvider} implementations
* to customize authentication behavior.
*
* <p>
* Example - Modifying signer properties in an auth scheme option:
*
* {@snippet :
* public class CustomSigningNameAuthSchemeProvider implements S3AuthSchemeProvider {
* private final S3AuthSchemeProvider delegate;
*
* public CustomSigningNameAuthSchemeProvider() {
* this.delegate = S3AuthSchemeProvider.defaultProvider();
* }
*
* @Override
* public List<AuthSchemeOption> resolveAuthScheme(S3AuthSchemeParams authSchemeParams) {
* List<AuthSchemeOption> options = delegate.resolveAuthScheme(authSchemeParams);
* return options.stream()
* .map(option -> option.toBuilder()
* .putSignerProperty(AwsV4HttpSigner.SERVICE_SIGNING_NAME, "custom-service")
* .putSignerProperty(AwsV4HttpSigner.REGION_NAME, "us-west-2")
* .build())
* .collect(Collectors.toList());
* }
* }
* }
*
* <p>
* <b>Creating Custom Auth Scheme Options</b>
* <p>
* This is used in the output from the auth scheme resolver. The resolver returns a list of these, in the order the auth scheme
* resolver wishes to use them.
* You can create custom auth scheme options from scratch when implementing a custom {@link AuthSchemeProvider}.
*
* <p>
* Example - Creating a custom auth scheme option:
*
* {@snippet :
* public class CustomAuthSchemeProvider implements S3AuthSchemeProvider {
* @Override
* public List<AuthSchemeOption> resolveAuthScheme(S3AuthSchemeParams authSchemeParams) {
* AuthSchemeOption customOption = AuthSchemeOption.builder()
* .schemeId("custom.auth#v1")
* .putSignerProperty(CustomHttpSigner.CUSTOM_HEADER, "custom-value")
* .putIdentityProperty(IdentityProperty.create(CustomAuthSchemeProvider.class, "AccountId"), "123456789")
* .build();
*
* return Collections.singletonList(customOption);
* }
* }
* }
*
* <p>
* <b>Reading Properties from Auth Scheme Options</b>
* <p>
* Within a custom {@link software.amazon.awssdk.http.auth.spi.signer.HttpSigner}, you can read properties from
* the auth scheme option via the sign request.
*
* <p>
* Example - Reading signer properties in a custom signer:
*
* {@snippet :
* public class CustomHttpSigner implements HttpSigner<AwsCredentialsIdentity> {
* public static final SignerProperty<String> CUSTOM_HEADER =
* SignerProperty.create(CustomHttpSigner.class, "CustomHeader");
*
* @Override
* public SignedRequest sign(SignRequest<? extends AwsCredentialsIdentity> request) {
* // Read property that was set on the AuthSchemeOption
* String headerValue = request.property(CUSTOM_HEADER);
*
* SdkHttpRequest signedRequest = request.request().toBuilder()
* .putHeader("X-Custom-Auth", headerValue)
* .build();
*
* return SignedRequest.builder()
* .request(signedRequest)
* .payload(request.payload().orElse(null))
* .build();
* }
* }
* }
*
* @see AuthScheme
* @see AuthSchemeProvider
* @see SignerProperty
* @see IdentityProperty
*/
@SdkPublicApi
public interface AuthSchemeOption extends ToCopyableBuilder<AuthSchemeOption.Builder, AuthSchemeOption> {
Expand Down
Loading
Loading