Add more documentation and code snippet for custom signer

Author: zoewangg

core/auth/src/main/java/software/amazon/awssdk/auth/signer/AwsSignerExecutionAttribute.java

@@ -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;
@@ -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;
@@ -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} for how to use it.
  */
 @Deprecated
 @SdkProtectedApi
@@ -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 =
@@ -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 =
@@ -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 =
@@ -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 =
@@ -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 =
@@ -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 =
@@ -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 =
@@ -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");

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/scheme/AuthScheme.java

@@ -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> {

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/scheme/AuthSchemeOption.java

@@ -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> {