AWS Request Signing

This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning.
v3 API reference

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 AWS 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.

Example configuration

Example filter configuration:

aws-request-signing-filter.yaml

          http_filters:
          - name: envoy.filters.http.aws_request_signing
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning
              service_name: s3
              region: us-west-2
              use_unsigned_payload: true
              match_excluded_headers:
              - prefix: x-envoy
              - prefix: x-forwarded
              - exact: x-amzn-trace-id

Note that this filter also supports per route configuration:

aws-request-signing-filter-route-level-override.yaml

              routes:
              - match:
                  prefix: "/"
                route:
                  cluster: versioned-cluster
                typed_per_filter_config:
                  envoy.filters.http.aws_request_signing:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigningPerRoute
                    aws_request_signing:
                      service_name: s3
                      region: us-west-1
                      use_unsigned_payload: true
                      host_rewrite: new-host
                      match_excluded_headers:
                      - prefix: x-envoy
                      - prefix: x-forwarded
                      - exact: x-amzn-trace-id
                    stat_prefix: some-prefix

Above shows an example of route-level config overriding the config on the virtual-host level.

An example of configuring this filter to use AWS_SIGV4A signing with a wildcarded region set, to a AWS VPC Lattice service:

aws-request-signing-filter-sigv4a.yaml

          - name: envoy.filters.http.aws_request_signing
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning
              service_name: vpc-lattice-svcs
              signing_algorithm: AWS_SIGV4A
              region: '*'
              use_unsigned_payload: true
              match_excluded_headers:
              - prefix: x-envoy
              - prefix: x-forwarded
              - exact: x-amzn-trace-id

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, and AWS_SESSION_TOKEN are used.
The AWS credentials file. The environment variables AWS_SHARED_CREDENTIALS_FILE and AWS_PROFILE are respected if they are set, else the file ~/.aws/credentials and profile default are used. The fields aws_access_key_id, aws_secret_access_key, and aws_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 by AWS_WEB_IDENTITY_TOKEN_FILE environment variable and role arn read from AWS_ROLE_ARN environment variable. The credentials are extracted from the fields AccessKeyId, SecretAccessKey, and SessionToken are used, and credentials are cached for 1 hour or until they expire (according to the field Expiration). To enable this credentials provider set envoy.reloadable_features.use_http_client_to_fetch_aws_credentials to true 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 name sts_token_service_internal pointing towards regional AWS Security Token Service. The static internal cluster will still be added even if initially envoy.reloadable_features.use_http_client_to_fetch_aws_credentials is not set so that subsequently if the reloadable feature is set to true the cluster config is available to fetch the credentials.
Either EC2 instance metadata or ECS task metadata. For EC2 instance metadata, the fields AccessKeyId, SecretAccessKey, and Token are used, and credentials are cached for 1 hour. For ECS task metadata, the fields AccessKeyId, SecretAccessKey, and Token are used, and credentials are cached for 1 hour or until they expire (according to the field Expiration). 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 setting envoy.reloadable_features.use_http_client_to_fetch_aws_credentials to true. 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 be ec2_instance_metadata_server_internal for fetching from EC2 instance metadata or ecs_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 initially envoy.reloadable_features.use_http_client_to_fetch_aws_credentials is not set so that subsequently if the reloadable feature is set to true the cluster config is available to fetch the credentials.

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