Auth Scheme and Auth Scheme Resolver Customization Guidance

[ysaito1001]

What are Auth Scheme and Auth Scheme Resolver?

An Auth Scheme is a data structure that consists of

• A scheme ID - A unique identifier for the auth scheme (e.g. sigv4, http-basic-auth)
• An identity resolver - An API to acquire the customer ’s identity
• A signer - An API to sign HTTP requests

We define AuthScheme as a trait in the aws-smithy-runtime-api crate.

An Auth Scheme Resolver is a runtime component within the orchestrator that determines which auth scheme to use for that service. The following crate::config::auth::ResolveAuthScheme trait is code-generated per service.

ResolveAuthScheme trait

pub trait ResolveAuthScheme: Send + Sync + Debug {
    /// Resolve a priority list of auth scheme options with the given parameters
    fn resolve_auth_scheme<'a>(
        &'a self,
        params: &'a crate::config::auth::Params,
        cfg: &'a ::aws_smithy_types::config_bag::ConfigBag,
        runtime_components: &'a ::aws_smithy_runtime_api::client::runtime_components::RuntimeComponents,
    ) -> ::aws_smithy_runtime_api::client::auth::AuthSchemeOptionsFuture<'a>;

    /// Convert this service-specific resolver into a `SharedAuthSchemeOptionResolver`
    fn into_shared_resolver(self) -> ::aws_smithy_runtime_api::client::auth::SharedAuthSchemeOptionResolver
    where
        Self: ::std::marker::Sized + 'static,
    {
        ::aws_smithy_runtime_api::client::auth::SharedAuthSchemeOptionResolver::new(DowncastParams(self))
    }
}

What's Changing

You may need to customize auth schemes and an auth scheme resolver in scenarios such as:

• disable signing for an existing auth scheme already registered in the smithy runtime
• register a new auth scheme

The Rust SDK now allows you to configure them at the service client level or at the individual operation invocation level.

Note

For brevity, the code examples below demonstrate overriding at the service client level only. Overriding at the individual operation invocation level is also possible just like other configurations, as described here.

Also, the code examples arbitrarily use S3 for demonstration purposes.

How to Customize Auth Scheme

Auth schemes from a given Smithy model are code-generated as documented in the spec, and are recognized by the runtime. To override the default behavior, you can define a custom auth scheme by implementing the AuthScheme trait and pass it to the .push_auth_scheme method on a service config builder. Auth scheme customization can be done for two primary reasons: modifying existing schemes or registering new ones.

Modifying existing auth scheme

For instance, you can customize the default sigv4 auth scheme to modify its behavior, such as disabling request signing. Here's an example of how to implement this:

Custom sigv4 auth scheme

use aws_smithy_runtime_api::{
    box_error::BoxError,
    client::{
        auth::{
            AuthScheme, AuthSchemeEndpointConfig, AuthSchemeId, Sign,
        },  
        identity::{Identity, SharedIdentityResolver},
        orchestrator::HttpRequest,
        runtime_components::{GetIdentityResolver, RuntimeComponents},
  },  
  shared::IntoShared,
};
use aws_smithy_types::config_bag::ConfigBag;

#[derive(Debug)]
struct CustomSigv4AuthScheme {
    signer: DisabledSigner,
}
impl Default for CustomSigv4AuthScheme {
    fn default() -> Self {
        Self { signer: DisabledSigner }
    }
}

#[derive(Debug)]
struct DisabledSigner;
impl Sign for DisabledSigner {
    fn sign_http_request(
        &self,
        _request: &mut HttpRequest,
        _identity: &Identity,
        _auth_scheme_endpoint_config: AuthSchemeEndpointConfig<'_>,
        _runtime_components: &RuntimeComponents,
        _config_bag: &ConfigBag,
    ) -> Result<(), BoxError> {
        Ok(()) // No signing
    }
}

impl AuthScheme for CustomSigv4AuthScheme {
    fn scheme_id(&self) -> AuthSchemeId {
        aws_runtime::auth::sigv4::SCHEME_ID // Specify the scheme ID for sigv4
    }
    fn identity_resolver(&self, identity_resolvers: &dyn GetIdentityResolver) -> Option<SharedIdentityResolver> {
        // Using the input parameter `identity_resolvers` means letting the orchestrator choose the matching
        // identity resolver from its runtime components whose auth scheme ID is sigv4.
        identity_resolvers.identity_resolver(self.scheme_id())
    }
    fn signer(&self) -> &dyn Sign {
        &self.signer
    }
}

You can then pass the custom auth scheme CustomSigv4AuthScheme to .push_auth_scheme on the service config builder:

let config = aws_sdk_s3::Config::builder()
    .push_auth_scheme(CustomSigv4AuthScheme::default())
    // other configurations
    .build();

Assuming the service models siv4, the code-generated default auth scheme resolver recognizes CustomSigv4AuthScheme by its auth scheme ID, causing the smithy runtime to use its DisabledSigner as expected.

Registering new auth scheme

You can define a custom auth scheme whose auth scheme ID is not yet known to the runtime.

New auth scheme

use aws_smithy_runtime_api::{
    box_error::BoxError,
    client::{
        auth::{
            AuthScheme, AuthSchemeEndpointConfig, AuthSchemeId, Sign,
        },  
        identity::{Identity, IdentityFuture, ResolveIdentity, SharedIdentityResolver},
        orchestrator::HttpRequest,
        runtime_components::{GetIdentityResolver, RuntimeComponents},
  },  
  shared::IntoShared,
};
use aws_smithy_types::config_bag::ConfigBag;

#[derive(Debug)]
struct CustomAuthScheme {
    id: AuthSchemeId,
    identity_resolver: SharedIdentityResolver,
    signer: CustomSigner,
}
impl Default for CustomAuthScheme {
    fn default() -> Self {
        Self {
            id: AuthSchemeId::new("custom"), // Custom auth scheme ID
            identity_resolver: CustomIdentityResolver.into_shared(),
            signer: CustomSigner,
        }
    }
}
impl AuthScheme for CustomAuthScheme {
    fn scheme_id(&self) -> AuthSchemeId {
        self.id.clone()
    }
    fn identity_resolver(
        &self,
        _identity_resolvers: &dyn GetIdentityResolver,
    ) -> Option<SharedIdentityResolver> {
        // The fact the input parameter `identity_resolvers` is unused means the identity resolver stored in this
        // struct is returned, since orchestrator's runtime components isn't aware of `CustomIdentityResolver`.
        Some(self.identity_resolver.clone())
    }
    fn signer(&self) -> &dyn Sign {
        &self.signer
    }
}

#[derive(Debug, Default)]
struct CustomSigner;
impl Sign for CustomSigner {
    fn sign_http_request(
        &self,
        _request: &mut HttpRequest,
        _identity: &Identity,
        _auth_scheme_endpoint_config: AuthSchemeEndpointConfig<'_>,
        _runtime_components: &RuntimeComponents,
        _config_bag: &ConfigBag,
    ) -> Result<(), BoxError> {
        // --snip--
    }
}

#[derive(Debug)]
struct CustomIdentityResolver;
impl ResolveIdentity for CustomIdentityResolver {
    fn resolve_identity<'a>(
        &'a self,
        _runtime_components: &'a RuntimeComponents,
        _config_bag: &'a ConfigBag,
    ) -> IdentityFuture<'a> {
        // --snip--
    }
}

You can then pass CustomAuthScheme to .push_auth_scheme on the service config builder.

let config = aws_sdk_s3::Config::builder()
    .push_auth_scheme(CustomAuthScheme::default())
    // other configurations
    .build();

However, this code most likely will not work as expected because the default auth scheme resolver doesn't recognize the
auth scheme ID of CustomAuthScheme. To resolve this, you'll need to customize the auth scheme resolver as described in the next section.

How to Customize Auth Scheme Resolver

The AWS SDK for Rust provides a code-generated default auth scheme resolver. The default resolver returns an ordered list of AuthSchemeOptions for modeled auth schemes. If you need to register a custom auth scheme with the ID not yet known to the runtime, you should define a custom auth scheme resolver by implementing the crate::config::auth::ResolveAuthScheme trait and pass it to the .auth_scheme_resolver method on a service config builder.

Building on the previous example from Registering new auth scheme, here's how to define a custom resolver:

use aws_smithy_runtime_api::{
    client::{
        auth::{
            AuthSchemeId, AuthSchemeOption, AuthSchemeOptionsFuture,
        },  
        runtime_components::RuntimeComponents,
  },  
};
use aws_smithy_types::config_bag::ConfigBag;

#[derive(Debug)]
struct CustomAuthSchemeResolver;
impl aws_sdk_s3::config::auth::ResolveAuthScheme for CustomAuthSchemeResolver {
    fn resolve_auth_scheme<'a>(
        &'a self,
        _params: &'a aws_sdk_s3::config::auth::Params,
        _cfg: &'a ConfigBag,
        _runtime_components: &'a RuntimeComponents,
    ) -> AuthSchemeOptionsFuture<'a> {
        // Favors the auth scheme ID from `CustomAuthScheme`
        AuthSchemeOptionsFuture::ready(Ok(vec![AuthSchemeOption::from(AuthSchemeId::new(
            "custom",
        ))]))
    }
}

You can then pass CustomAuthSchemeResolver to .auth_scheme_resolver on the service config builder.

let config = aws_sdk_s3::Config::builder()
    .push_auth_scheme(CustomAuthScheme::default()) // Refer to the "Registering new auth scheme" section above
    .auth_scheme_resolver(CustomAuthSchemeResolver)
    .build();

The orchestrator will use CustomAuthSchemeResolver, which prioritizes the CustomAuthScheme. As a result, the identity resolver and the signer associated with it will be used during the identity resolution and signing.