Interface AuthSchemeOption

All Superinterfaces:
ToCopyableBuilder<AuthSchemeOption.Builder,AuthSchemeOption>
All Known Implementing Classes:
DefaultAuthSchemeOption
@SdkPublicApi public interface AuthSchemeOption extends ToCopyableBuilder<AuthSchemeOption.Builder,AuthSchemeOption>
An authentication scheme option, composed of the scheme ID and properties for use when resolving the identity and signing the request.

Auth scheme options are returned by AuthSchemeProviders 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.

Each option contains:

  • A scheme ID - Identifies which AuthScheme to use (e.g., "aws.auth#sigv4")
  • Identity properties - Configuration for the identity provider (e.g., account ID, role ARN)
  • Signer properties - Configuration for the signer (e.g., signing name, region, algorithm parameters)

Using Auth Scheme Options

Auth scheme options are typically created and modified within custom AuthSchemeProvider implementations to customize authentication behavior.

Example - Modifying signer properties in an auth scheme option: 

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());
    }
}

Creating Custom Auth Scheme Options

You can create custom auth scheme options from scratch when implementing a custom AuthSchemeProvider.

Example - Creating a custom auth scheme option: 

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);
    }
}

Reading Properties from Auth Scheme Options

Within a custom HttpSigner, you can read properties from the auth scheme option via the sign request.

Example - Reading signer properties in a 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) {
        // 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 Also:

  • Method Details

    • builder

      static AuthSchemeOption.Builder builder()
      Get a new builder for creating a AuthSchemeOption.

    • schemeId

      String schemeId()
      Retrieve the scheme ID, a unique identifier for the authentication scheme (aws.auth#sigv4, smithy.api#httpBearerAuth).

    • identityProperty

      <T> T identityProperty(IdentityProperty<T> property)
      Retrieve the value of an IdentityProperty.
      Type Parameters:
      T - The type of the IdentityProperty.
      Parameters:
      property - The IdentityProperty to retrieve the value of.

    • signerProperty

      <T> T signerProperty(SignerProperty<T> property)
      Retrieve the value of an SignerProperty.
      Type Parameters:
      T - The type of the SignerProperty.
      Parameters:
      property - The SignerProperty to retrieve the value of.

    • forEachIdentityProperty

      void forEachIdentityProperty(AuthSchemeOption.IdentityPropertyConsumer consumer)
      A method to operate on all IdentityProperty values of this AuthSchemeOption.
      Parameters:
      consumer - The method to apply to each IdentityProperty.

    • forEachSignerProperty

      void forEachSignerProperty(AuthSchemeOption.SignerPropertyConsumer consumer)
      A method to operate on all SignerProperty values of this AuthSchemeOption.
      Parameters:
      consumer - The method to apply to each SignerProperty.