AWS Request Signing
This filter should be configured with the type URL
type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning
.
Attention
The AWS request signing filter is experimental and is currently under active development.
The HTTP AWS request signing filter is used to access authenticated AWS services. It uses the existing AWS Credential Provider to get the secrets used for generating the required headers.
This filter can be used to communicate with both AWS API endpoints and customer API endpoints, such as AWS API Gateway hosted APIs or Amazon VPC Lattice services.
The use_unsigned_payload option determines whether or not requests are buffered so the request body can be used to compute the payload hash. Some services, such as S3, allow requests with unsigned payloads. Consult the AWS documentation and your service’s resource policies to determine if this option is appropriate.
When use_unsigned_payload is false (the default), requests which exceed the configured buffer limit will receive a 413 response. See the flow control docs for details.
The match_excluded_headers
option allows excluding certain request headers from being signed. This usually applies to headers that are likely to mutate or
are added later such as in retries. By default, the headers x-forwarded-for
, x-forwarded-proto
, and x-amzn-trace-id
are always excluded.
The signing_algorithm
can be specified as AWS_SIGV4
or AWS_SIGV4A
. If the signing algorithm is unspecified, this filter will default to AWS_SIGV4
.
If AWS_SIGV4
is unspecified, or explicitly specified, the signing_algorithm parameter
is used to define the region to which the sigv4 calculation is addressed to.
If AWS_SIGV4A
is explicitly specified, the signing_algorithm parameter
is used as a region set. A region set is a single region, or comma seperated list of regions. Regions in a region set can also include wildcards,
such as us-east-*
or even *
. By using AWS_SIGV4A
and wildcarded regions it is possible to simplify the overall envoy configuration for
multi-region implementations.
Signing can be added to the query string, rather than in the headers, by enabling query_string Query string signing adds an additional parameter expiration_time which determines the length of time after which this URL becomes invalid, starting from the time the URL is signed. The default expiration time is 5 seconds, with a maximum of 3600 seconds. It is recommended to keep this value as small as practicable, as the generated URL is replayable before this time expires.
Example configuration
Example filter configuration:
25 http_filters:
26 - name: envoy.filters.http.aws_request_signing
27 typed_config:
28 "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning
29 service_name: s3
30 region: us-west-2
31 use_unsigned_payload: true
32 match_excluded_headers:
33 - prefix: x-envoy
34 - prefix: x-forwarded
35 - exact: x-amzn-trace-id
This filter also supports per route configuration. Below is an example of route-level config overriding the config at the virtual-host level.
20 routes:
21 - match:
22 prefix: "/"
23 route:
24 cluster: versioned-cluster
25 typed_per_filter_config:
26 envoy.filters.http.aws_request_signing:
27 "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigningPerRoute
28 aws_request_signing:
29 service_name: s3
30 region: us-west-1
31 use_unsigned_payload: true
32 host_rewrite: new-host
33 match_excluded_headers:
34 - prefix: x-envoy
35 - prefix: x-forwarded
36 - exact: x-amzn-trace-id
37 stat_prefix: some-prefix
An example of configuring this filter to use AWS_SIGV4A
signing with a wildcarded region set, to an Amazon VPC Lattice service, using query string signing and a 3 second expiration:
26 - name: envoy.filters.http.aws_request_signing
27 typed_config:
28 "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning
29 service_name: vpc-lattice-svcs
30 signing_algorithm: AWS_SIGV4A
31 region: '*'
32 query_string:
33 expiration_time: 3s
34 use_unsigned_payload: true
35 match_excluded_headers:
36 - prefix: x-envoy
Configuration as an upstream HTTP filter
SigV4 or SigV4A request signatures are calculated using the HTTP host, URL and payload as input. Depending on the configuration, Envoy may modify one or more of these prior to forwarding to the Cluster subsystem, but after the signature has been calculated and inserted into the HTTP headers or query string. Modifying fields in a SigV4 or SigV4A signed request will result in an invalid signature.
To avoid invalid signatures, the AWS Request Signing Filter can be configured as an upstream HTTP filter. This allows signatures to be calculated as a final step before the HTTP request is forwarded upstream, ensuring signatures are correctly calculated over the updated HTTP fields.
Configuring this filter as an upstream HTTP filter is done in a similar way to the downstream case, but using the http_filters filter chain within the cluster configuration.
47 typed_config:
48 "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning
49 service_name: vpc-lattice-svcs
50 region: '*'
51 signing_algorithm: AWS_SIGV4A
52 use_unsigned_payload: true
53 match_excluded_headers:
54 - prefix: x-envoy
55 - prefix: x-forwarded
56 - exact: x-amzn-trace-id
57 - name: envoy.filters.http.upstream_codec
Credentials
The filter uses a few different credentials providers to obtain an AWS access key ID, AWS secret access key, and AWS session token. It moves through the credentials providers in the order described below, stopping when one of them returns an access key ID and a secret access key (the session token is optional).
Environment variables. The environment variables
AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
, andAWS_SESSION_TOKEN
are used.The AWS credentials file. The environment variables
AWS_SHARED_CREDENTIALS_FILE
andAWS_PROFILE
are respected if they are set, else the file~/.aws/credentials
and profiledefault
are used. The fieldsaws_access_key_id
,aws_secret_access_key
, andaws_session_token
defined for the profile in the credentials file are used. These credentials are cached for 1 hour.From AssumeRoleWithWebIdentity API call towards AWS Security Token Service using
WebIdentityToken
read from a file pointed byAWS_WEB_IDENTITY_TOKEN_FILE
environment variable and role arn read fromAWS_ROLE_ARN
environment variable. The credentials are extracted from the fieldsAccessKeyId
,SecretAccessKey
, andSessionToken
are used, and credentials are cached for 1 hour or until they expire (according to the fieldExpiration
). To enable this credentials provider setenvoy.reloadable_features.use_http_client_to_fetch_aws_credentials
totrue
so that it can use http async client to fetch the credentials. This provider is not compatible with Grpc Credentials AWS AwsIamConfig plugin which can only support deprecated libcurl credentials fetcher , see https://github.com/envoyproxy/envoy/pull/30626. To fetch the credentials a static cluster is required with the namests_token_service_internal
pointing towards regional AWS Security Token Service. The static internal cluster will still be added even if initiallyenvoy.reloadable_features.use_http_client_to_fetch_aws_credentials
is not set so that subsequently if the reloadable feature is set totrue
the cluster config is available to fetch the credentials.Either EC2 instance metadata, ECS task metadata or EKS Pod Identity. For EC2 instance metadata, the fields
AccessKeyId
,SecretAccessKey
, andToken
are used, and credentials are cached for 1 hour. For ECS task metadata, the fieldsAccessKeyId
,SecretAccessKey
, andToken
are used, and credentials are cached for 1 hour or until they expire (according to the fieldExpiration
). For EKS Pod Identity, The environment variableAWS_CONTAINER_AUTHORIZATION_TOKEN_FILE
will point to a mounted file in the container, containing the string required in the Authorization header sent to the EKS Pod Identity Agent. The fieldsAccessKeyId
,SecretAccessKey
, andToken
are used, and credentials are cached for 1 hour or until they expire (according to the fieldExpiration
). Note that the latest update on AWS credentials provider utility provides an option to use http async client functionality instead of libcurl to fetch the credentials. This behavior can be changed by settingenvoy.reloadable_features.use_http_client_to_fetch_aws_credentials
totrue
. The usage of libcurl is on the deprecation path and will be removed soon. To fetch the credentials from either EC2 instance metadata or ECS task metadata a static cluster is required pointing towards the credentials provider. The static cluster name has to beec2_instance_metadata_server_internal
for fetching from EC2 instance metadata orecs_task_metadata_server_internal
for fetching from ECS task metadata. If these clusters are not provided in the bootstrap configuration then either of these will be added by default. The static internal cluster will still be added even if initiallyenvoy.reloadable_features.use_http_client_to_fetch_aws_credentials
is not set so that subsequently if the reloadable feature is set totrue
the cluster config is available to fetch the credentials.
Regions
In a similar way to retrieving credentials, the region can be sourced from a number of locations. In order, these are the locations which are checked, which align with the AWS SDK behavior:
If signing_algorithm is AWS_SIGV4
:
The
region
parameter in the extension xDS configuration. For theaws_request_signing
filter, this is the region optional parameter.Environment variables. The environment variables
AWS_REGION
,AWS_DEFAULT_REGION
are used.The AWS credentials file. The environment variables
AWS_SHARED_CREDENTIALS_FILE
,AWS_PROFILE
andDEFAULT_AWS_PROFILE
are respected if they are set, else the file~/.aws/credentials
and profiledefault
are used. The fieldregion
defined for the profile in the credentials file is used.The AWS config file. The environment variables
AWS_CONFIG_FILE
,AWS_PROFILE``and ``DEFAULT_AWS_PROFILE
are respected if they are set, else the file~/.aws/config
and profiledefault
are used. The fieldregion
defined for the profile in the config file is used.
If signing_algorithm is AWS_SIGV4A
:
The
region
parameter in the extension xDS configuration. For theaws_request_signing
filter, this is the region optional parameter.Environment variables. The environment variable
AWS_SIGV4A_SIGNING_REGION_SET
is used.The AWS credentials file. The environment variables
AWS_SHARED_CREDENTIALS_FILE
,AWS_PROFILE
andDEFAULT_AWS_PROFILE
are respected if they are set, else the file~/.aws/credentials
and profiledefault
are used. The fieldsigv4a_signing_region_set
defined for the profile in the credentials file is used.The AWS config file. The environment variables
AWS_CONFIG_FILE
,AWS_PROFILE``and ``DEFAULT_AWS_PROFILE
are respected if they are set, else the file~/.aws/config
and profiledefault
are used. The fieldsigv4a_signing_region_set
defined for the profile in the config file is used.
Statistics
The AWS request signing filter outputs statistics in the http.<stat_prefix>.aws_request_signing. namespace. The stat prefix comes from the owning HTTP connection manager.
Name |
Type |
Description |
---|---|---|
signing_added |
Counter |
Total requests for which signing succeeded (includes payload_signing_added) |
signing_failed |
Counter |
Total requests for which signing failed (includes payload_signing_failed) |
payload_signing_added |
Counter |
Total requests for which the payload was buffered signing succeeded |
payload_signing_failed |
Counter |
Total requests for which the payload was buffered but signing failed |