Interface AuthScheme<T extends Identity>

Type Parameters:
T - The type of the Identity used by this authentication scheme.
All Known Subinterfaces:
AwsV4aAuthScheme, AwsV4AuthScheme, BearerAuthScheme, NoAuthAuthScheme, S3ExpressAuthScheme
All Known Implementing Classes:
CrtS3ExpressNoOpAuthScheme, DefaultAwsV4aAuthScheme, DefaultAwsV4AuthScheme, DefaultBearerAuthScheme, DefaultNoAuthAuthScheme, DefaultS3ExpressAuthScheme, DpopAuthScheme
@SdkPublicApi public interface AuthScheme<T extends Identity>
An authentication scheme, composed of:
  1. A scheme ID - A unique identifier for the authentication scheme.
  2. An identity provider - An API that can be queried to acquire the customer's identity.
  3. A signer - An API that can be used to sign HTTP requests.

Auth schemes are used to configure how requests are authenticated. The SDK provides built-in schemes like AwsV4AuthScheme for AWS Signature Version 4, but you can implement custom schemes for specialized authentication requirements.

See example auth schemes defined here.

Implementing a Custom Auth Scheme

To implement a custom authentication scheme, you need to:

  1. Implement the AuthScheme interface
  2. Implement a custom HttpSigner
  3. Configure the scheme on the client builder

Example - Custom authentication scheme with custom signer: 

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

Overriding Built-in Auth Schemes

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.

Example - Overriding the default SigV4 scheme: 

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();
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    IdentityProvider<T>
    identityProvider(IdentityProviders providers)
    Retrieve the identity provider associated with this authentication scheme.
    String
    schemeId()
    Retrieve the scheme ID, a unique identifier for the authentication scheme.
    HttpSigner<T>
    signer()
    Retrieve the signer associated with this authentication scheme.

  • Method Details

    • schemeId

      String schemeId()
      Retrieve the scheme ID, a unique identifier for the authentication scheme.

    • identityProvider

      IdentityProvider<T> identityProvider(IdentityProviders providers)
      Retrieve the identity provider associated with this authentication scheme. The identity generated by this provider is guaranteed to be supported by the signer in this authentication scheme.

      For example, if the scheme ID is aws.auth#sigv4, the provider returns an AwsCredentialsIdentity, if the scheme ID is httpBearerAuth, the provider returns a TokenIdentity.

      Note, the returned identity provider may differ from the type of identity provider retrieved from the provided IdentityProviders.

    • signer

      HttpSigner<T> signer()
      Retrieve the signer associated with this authentication scheme. This signer is guaranteed to support the identity generated by the identity provider in this authentication scheme.