BREAKING: Refactored Identity and Authentication API

[aajtodd]

An upcoming release of the AWS SDK for Kotlin includes a redesigned API for identity and authentication. Most notably affecting the CredentialsProvider type and it's implementations.

NOTE: If you don't implement a custom CredentialsProvider or change the default signer configured on a service client this change should not affect you.

Release Date

This feature will ship with the v0.22.0-beta release planned for 04/13/2023.

What's changing?

1. CredentialsProvider interface has a changed method name and signature. It now extends a more generic IdentityProvider interface.

2. The signer: AwsSigner property has been removed from all service client configuration in favor of configuring one or more HttpAuthScheme instances. An auth scheme is a tuple of (schemeID, identityProvider, signer) and is used to provide the identity (e.g. AWS credentials) that is used to sign requests.

How to migrate?

Implementing or consuming CredentialsProvider

If you implement a custom credential provider you simply need to change the method name and signature to match the new interface. If you are consuming a credential provider and calling getCredentials() you need to change the invocation to resolve() (the attributes parameter is defaulted in the IdentityProvider interface and can be omitted).

Before

public interface CredentialsProvider {
    public suspend fun getCredentials(): Credentials
}

After

public interface CredentialsProvider : IdentityProvider {
    public override suspend fun resolve(attributes: Attributes): Credentials
}

Configuring a custom signer

NOTE: Most users will not have a need to customize signing. Both before and after this refactor the service clients have a default implementation that works out of the box.

Customizing the AwsSigner used to sign requests with:

Before

// e.g. use the CRT based signer instead of the pure Kotlin one used by default
val s3 = S3Client {
    signer = CrtAwsSigner
}

After

val sigv4AuthScheme = object : HttpAuthScheme {
    override val schemeId = AuthSchemeId.AwsSigV4

    override val signer = AwsHttpSigner { 
        signer = CrtAwsSigner
        service = "s3"
    }

}

val s3 = S3Client {
    authSchemes = listOf(sigv4AuthScheme)
}

Additional resources

If you have any questions concerning this change, please feel free to engage with us in this discussion. If you've encountered a bug with these changes, please file an issue.