awscrt.auth¶

AWS client-side authentication: standard credentials providers and signing.

class awscrt.auth.AwsCredentials(access_key_id, secret_access_key, session_token=None, expiration=None)¶

AwsCredentials are the public/private data needed to sign an authenticated AWS request.

AwsCredentials are immutable.

Parameters:

access_key_id (str) – Access key ID
secret_access_key (str) – Secret access key
session_token (Optional[str]) – Optional security token associated with the credentials.
expiration (Optional[datetime.datetime]) – Optional expiration datetime, that the credentials will no longer be valid past. Converted to UTC timezone and rounded down to nearest second. If not set, then credentials do not expire.

access_key_id¶

Access key ID

Type:: str

secret_access_key¶

Secret access key

Type:: str

session_token¶

Security token associated with the credentials. None if not set.

Type:: Optional[str]

expiration¶

Expiration datetime, that the credentials will no longer be valid past. None if credentials do not expire. Timezone is always UTC.

Type:: Optional[datetime.datetime]

class awscrt.auth.AwsCredentialsProvider(binding)¶

Credentials providers source the AwsCredentials needed to sign an authenticated AWS request.

This class provides new_X() functions for several built-in provider types. To define a custom provider, use the new_delegate() function.

classmethod new_default_chain(client_bootstrap=None)¶

Create the default provider chain used by most AWS SDKs.

Generally:

Environment
Profile
(conditional, off by default) ECS
(conditional, on by default) EC2 Instance Metadata

Parameters:: client_bootstrap (Optional[ClientBootstrap]) – Client bootstrap to use when initiating socket connection. If not set, uses the default static ClientBootstrap instead.
Returns:: AwsCredentialsProvider

classmethod new_static(access_key_id, secret_access_key, session_token=None)¶

Create a simple provider that just returns a fixed set of credentials.

Parameters:

access_key_id (str) – Access key ID
secret_access_key (str) – Secret access key
session_token (Optional[str]) – Optional session token

Returns:

AwsCredentialsProvider

classmethod new_profile(client_bootstrap=None, profile_name=None, config_filepath=None, credentials_filepath=None)¶

Creates a provider that sources credentials from key-value profiles loaded from the aws credentials file.

Parameters:

client_bootstrap (Optional[ClientBootstrap]) – Client bootstrap to use when initiating socket connection. If not set, uses the static default ClientBootstrap instead.
profile_name (Optional[str]) – Name of profile to use. If not set, uses value from AWS_PROFILE environment variable. If that is not set, uses value of “default”
config_filepath (Optional[str]) – Path to profile config file. If not set, uses value from AWS_CONFIG_FILE environment variable. If that is not set, uses value of “~/.aws/config”
credentials_filepath (Optional[str]) – Path to profile credentials file. If not set, uses value from AWS_SHARED_CREDENTIALS_FILE environment variable. If that is not set, uses value of “~/.aws/credentials”

Returns:

AwsCredentialsProvider

classmethod new_process(profile_to_use=None)¶

Creates a provider that sources credentials from running an external command or process.

The command to run is sourced from a profile in the AWS config file, using the standard profile selection rules. The profile key the command is read from is “credential_process.” Example:

[default]
credential_process=/opt/amazon/bin/my-credential-fetcher --argsA=abc

On successfully running the command, the output should be a json data with the following format:

{
    "Version": 1,
    "AccessKeyId": "accesskey",
    "SecretAccessKey": "secretAccessKey"
    "SessionToken": "....",
    "Expiration": "2019-05-29T00:21:43Z"
}

Version here identifies the command output format version. This provider is not part of the default provider chain.

Parameters:: profile_to_use (Optional[str]) – Name of profile in which to look for credential_process. If not set, uses value from AWS_PROFILE environment variable. If that is not set, uses value of “default”
Returns:: AwsCredentialsProvider

classmethod new_environment()¶

Creates a provider that returns credentials sourced from environment variables.

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

Returns:: AwsCredentialsProvider

classmethod new_chain(providers)¶

Creates a provider that sources credentials from an ordered sequence of providers.

This provider uses the first set of credentials successfully queried. Providers are queried one at a time; a provider is not queried until the preceding provider has failed to source credentials.

Parameters:: providers (List[AwsCredentialsProvider]) – List of credentials providers.
Returns:: AwsCredentialsProvider

classmethod new_delegate(get_credentials)¶

Creates a provider that sources credentials from a custom synchronous callback.

Parameters:: get_credentials – Callable which takes no arguments and returns AwsCredentials.
Returns:: AwsCredentialsProvider

classmethod new_cognito(*, endpoint: str, identity: str, tls_ctx: ClientTlsContext, logins: Sequence[Tuple[str, str]] | None = None, custom_role_arn: str | None = None, client_bootstrap: ClientBootstrap | None = None, http_proxy_options: HttpProxyOptions | None = None)¶

Creates a provider that sources credentials from the AWS Cognito Identity service.

Parameters:

endpoint (str) – Cognito Identity service regional endpoint to source credentials from.
identity (str) – Cognito identity to fetch credentials relative to.
tls_ctx (ClientTlsContext) – Client TLS context to use when querying cognito credentials by HTTP.
logins (Optional[Sequence[tuple[str, str]]]) – Sequence of tuples specifying pairs of identity provider name and token values, representing established login contexts for identity authentication purposes.
custom_role_arn (Optional[str]) – ARN of the role to be assumed when multiple roles were received in the token from the identity provider.
client_bootstrap (Optional[ClientBootstrap]) – Client bootstrap to use when initiating a socket connection. If not set, uses the static default ClientBootstrap instead.
http_proxy_options (Optional[HttpProxyOptions]) – Optional HTTP proxy options. If None is provided then an HTTP proxy is not used.

Returns:

AwsCredentialsProvider

classmethod new_x509(*, endpoint: str, thing_name: str, role_alias: str, tls_ctx: ClientTlsContext, client_bootstrap: ClientBootstrap | None = None, http_proxy_options: HttpProxyOptions | None = None)¶

Creates a provider that sources credentials from IoT’s X509 credentials service.

Parameters:

endpoint (str) – X509 service regional endpoint to source credentials from. This is a per-account value that can be determined via the CLI: aws iot describe-endpoint –endpoint-type iot:CredentialProvider
thing_name (str) – The name of the IoT thing to use to fetch credentials.
role_alias (str) – The name of the role alias to fetch credentials through.
tls_ctx (ClientTlsContext) – The client TLS context to use when establishing the http connection to IoT’s X509 credentials service.
client_bootstrap (Optional[ClientBootstrap]) – Client bootstrap to use when initiating a socket connection. If not set, uses the static default ClientBootstrap instead.
http_proxy_options (Optional[HttpProxyOptions]) – Optional HTTP proxy options. If None is provided then an HTTP proxy is not used.

Returns:

AwsCredentialsProvider

get_credentials()¶

Asynchronously fetch AwsCredentials.

Returns:: concurrent.futures.Future – A Future which will contain AwsCredentials (or an exception) when the operation completes. The operation may complete on a different thread.

class awscrt.auth.AwsSigningAlgorithm(value)¶

AWS signing algorithm enumeration.

V4 = 0¶: Signature Version 4

V4_ASYMMETRIC = 1¶: Signature Version 4 - Asymmetric

V4_S3EXPRESS = 2¶: Signature Version 4 - S3 Express

class awscrt.auth.AwsSignatureType(value)¶

Which sort of signature should be computed from the signable.

HTTP_REQUEST_HEADERS = 0¶: A signature for a full HTTP request should be computed, with header updates applied to the signing result.

HTTP_REQUEST_QUERY_PARAMS = 1¶: A signature for a full HTTP request should be computed, with query param updates applied to the signing result.

class awscrt.auth.AwsSignedBodyValue¶

Values for use with AwsSigningConfig.signed_body_value.

Some services use special values (e.g. “UNSIGNED-PAYLOAD”) when the body is not being signed in the usual way.

EMPTY_SHA256 = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'¶: The SHA-256 of the empty string.

UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD'¶: Unsigned payload option (not accepted by all services)

STREAMING_AWS4_HMAC_SHA256_PAYLOAD = 'STREAMING-AWS4-HMAC-SHA256-PAYLOAD'¶: Each payload chunk will be signed (not accepted by all services)

STREAMING_AWS4_HMAC_SHA256_EVENTS = 'STREAMING-AWS4-HMAC-SHA256-EVENTS'¶: Each event will be signed (not accepted by all services)

class awscrt.auth.AwsSignedBodyHeaderType(value)¶

Controls if signing adds a header containing the canonical request’s signed body value.

See AwsSigningConfig.signed_body_value.

NONE = 0¶: Do not add a header.

X_AMZ_CONTENT_SHA_256 = 1¶: Add the “x-amz-content-sha256” header with the canonical request’s signed body value

class awscrt.auth.AwsSigningConfig(algorithm=AwsSigningAlgorithm.V4, signature_type=AwsSignatureType.HTTP_REQUEST_HEADERS, credentials_provider=None, region='', service='', date=None, should_sign_header=None, use_double_uri_encode=True, should_normalize_uri_path=True, signed_body_value=None, signed_body_header_type=AwsSignedBodyHeaderType.NONE, expiration_in_seconds=None, omit_session_token=False)¶

Configuration for use in AWS-related signing.

AwsSigningConfig is immutable.

It is good practice to use a new config for each signature, or the date might get too old.

Parameters:

algorithm (AwsSigningAlgorithm) – Which signing algorithm to use.
signature_type (AwsSignatureType) – Which sort of signature should be computed from the signable.
credentials_provider (AwsCredentialsProvider) – Credentials provider to fetch signing credentials with. If the algorithm is AwsSigningAlgorithm.V4_ASYMMETRIC, ECC-based credentials will be derived from the fetched credentials.
region (str) – If the algorithm is AwsSigningAlgorithm.V4, the region to sign against. If the algorithm is AwsSigningAlgorithm.V4_ASYMMETRIC, the value of the “X-amzn-region-set” header (added in signing).
service (str) – Name of service to sign a request for.
date (Optional[datetime.datetime]) – Date and time to use during the signing process. If None is provided then datetime.datetime.now(datetime.timezone.utc) is used. Naive dates (lacking timezone info) are assumed to be in local time.
should_sign_header (Optional[Callable[[str], bool]]) –
Optional function to control which headers are a part of the canonical request.

Skipping auth-required headers will result in an unusable signature. Headers injected by the signing process are not skippable. This function does not override the internal check function (x-amzn-trace-id, user-agent), but rather supplements it. In particular, a header will get signed if and only if it returns true to both the internal check (skips x-amzn-trace-id, user-agent) and this function (if defined).
use_double_uri_encode (bool) – Whether to double-encode the resource path when constructing the canonical request (assuming the path is already encoded). Default is True. All services except S3 use double encoding.
should_normalize_uri_path (bool) – Whether the resource paths are normalized when building the canonical request. Default is True.
signed_body_value (Optional[str]) – If set, this value is used as the canonical request’s body value. Typically, this is the SHA-256 of the payload, written as lowercase hex. If this has been precalculated, it can be set here. Special values used by certain services can also be set (see AwsSignedBodyValue). If None is passed (the default), the typical value will be calculated from the payload during signing.
signed_body_header_type (AwsSignedBodyHeaderType) – Controls if signing adds a header containing the canonical request’s signed body value. Default is to not add a header.
expiration_in_seconds (Optional[int]) – If set, and signature_type is AwsSignatureType.HTTP_REQUEST_QUERY_PARAMS, then signing will add “X-Amz-Expires” to the query string, equal to the value specified here.
omit_session_token (bool) – If set True, the “X-Amz-Security-Token” query param is omitted from the canonical request. The default False should be used for most services.

replace(**kwargs)¶: Return an AwsSigningConfig with the same attributes, except for those attributes given new values by whichever keyword arguments are specified.

property algorithm¶

Which signing algorithm to use

Type:: AwsSigningAlgorithm

property signature_type¶

Which sort of signature should be computed from the signable.

Type:: AwsSignatureType

property credentials_provider¶

Credentials provider to fetch signing credentials with. If the algorithm is AwsSigningAlgorithm.V4_ASYMMETRIC, ECC-based credentials will be derived from the fetched credentials.

Type:: AwsCredentialsProvider

property region¶

If signing algorithm is AwsSigningAlgorithm.V4, the region to sign against. If the algorithm is AwsSigningAlgorithm.V4_ASYMMETRIC, the value of the “X-amzn-region-set header” (added in signing).

Type:: str

property service¶

Name of service to sign a request for

Type:: str

property date¶

Date and time to use during the signing process.

If None is provided, then datetime.datetime.now(datetime.timezone.utc) at time of object construction is used.

It is good practice to use a new config for each signature, or the date might get too old.

Type:: datetime.datetime

property should_sign_header¶

Optional function to control which headers are a part of the canonical request.

Skipping auth-required headers will result in an unusable signature. Headers injected by the signing process are not skippable. This function does not override the internal check function (x-amzn-trace-id, user-agent), but rather supplements it. In particular, a header will get signed if and only if it returns true to both the internal check (skips x-amzn-trace-id, user-agent) and this function (if defined).

Type:: Optional[Callable[[str], bool]]

property use_double_uri_encode¶

Whether to double-encode the resource path when constructing the canonical request (assuming the path is already encoded).

By default, all services except S3 use double encoding.

Type:: bool

property should_normalize_uri_path¶

Whether the resource paths are normalized when building the canonical request.

Type:: bool

property signed_body_value¶

What to use as the canonical request’s body value. If None is set (the default), a value will be calculated from the payload during signing. Typically, this is the SHA-256 of the payload, written as lowercase hex. If this has been precalculated, it can be set here. Special values used by certain services can also be set (see AwsSignedBodyValue).

Type:: Optional[str]

property signed_body_header_type¶

Controls if signing adds a header containing the canonical request’s signed body value.

Type:: AwsSignedBodyHeaderType

property expiration_in_seconds¶

If set, and signature_type is AwsSignatureType.HTTP_REQUEST_QUERY_PARAMS, then signing will add “X-Amz-Expires” to the query string, equal to the value specified here. Otherwise, this is None has no effect.

Type:: Optional[int]

property omit_session_token¶

Whether the “X-Amz-Security-Token” query param is omitted from the canonical request. This should be False for most services.

Type:: bool

awscrt.auth.aws_sign_request(http_request, signing_config)¶

Perform AWS HTTP request signing.

The awscrt.http.HttpRequest is transformed asynchronously, according to the AwsSigningConfig.

When signing:

It is good practice to use a new config for each signature, or the date might get too old.
Do not add the following headers to requests before signing, they may be added by the signer: x-amz-content-sha256, X-Amz-Date, Authorization
Do not add the following query params to requests before signing, they may be added by the signer: X-Amz-Signature, X-Amz-Date, X-Amz-Credential, X-Amz-Algorithm, X-Amz-SignedHeaders

Parameters:

http_request (awscrt.http.HttpRequest) – The HTTP request to sign.
signing_config (AwsSigningConfig) – Configuration for signing.

Returns:

concurrent.futures.Future – A Future whose result will be the signed awscrt.http.HttpRequest. The future will contain an exception if the signing process fails.

awscrt.auth¶

Table of Contents

Previous topic

Next topic

This Page