Aggregation options and keys

By default, a rate-based rule aggregates and rate limits requests based on the request IP address. You can configure the rule to use various other aggregation keys and key combinations. For example, you can aggregate based on a forwarded IP address, on the HTTP method, or on a query argument. You can also specify aggregation key combinations, such as IP address and HTTP method, or the values of two different cookies.

Note

All of the request components that you specify in the aggregation key must be present in a web request for the request to be evaluated or rate limited by the rule.

You can configure your rate-based rule with the following aggregation options.

• Source IP address – Aggregate using only the IP address from the web request origin.

  The source IP address might not contain the address of the originating client. If a web request goes through one or more proxies or load balancers, this will contain the address of the last proxy.

• IP address in header – Aggregate using only a client address in an HTTP header. This is also referred to as a forwarded IP address.

  With this configuration, you also specify a fallback behavior to apply to a web request with a malformed IP address in the header. The fallback behavior sets the matching result for the request, to match or no match. For no match, the rate-based rule doesn't count or rate limit the request. For match, the rate-based rule groups the request together with other requests that have a malformed IP address in the specified header.

  Use caution with this option, because headers can be handled inconsistently by proxies and they can also be modified to bypass inspection. For additional information and best practices, see Forwarded IP address.

• Count all – Count and rate limit all requests that match the rule's scope-down statement. This option requires a scope-down statement. This is typically used to rate limit a specific set of requests, such as all requests with a specific label or all requests from a specific geographic area.

• Custom keys – Aggregate using one or more custom aggregation keys. To combine either of the IP address options with other aggregation keys, define them here under custom keys.

  Custom aggregation keys are a subset of the web request component options described at Request component options.

  The key options are the following. Except where noted, you can use an option multiple times, for example, two headers or three label namespaces.

  • Label namespace – Use a label namespace as an aggregation key. Each distinct fully qualified label name that has the specified label namespace contributes to the aggregation instance. If you use just one label namespace as your custom key, then each label name fully defines an aggregation instance.

    The rate-based rule uses only labels that have been added to the request by rules that are evaluated beforehand in the web ACL.

    For information about label namespaces and names, see Label syntax and naming requirements.

  • Header – Use a named header as an aggregation key. Each distinct value in the header contributes to the aggregation instance.

    Header takes an optional text transformation. See Text transformations.

  • Cookie – Use a named cookie as an aggregation key. Each distinct value in the cookie contributes to the aggregation instance.

    Cookie takes an optional text transformation. See Text transformations.

  • Query argument – Use a single query argument in the request as an aggregate key. Each distinct value for the named query argument contributes to the aggregation instance.

    Query argument takes an optional text transformation. See Text transformations.

  • Query string – Use the entire query string in the request as an aggregate key. Each distinct query string contributes to the aggregation instance. You can use this key type once.

    Query string takes an optional text transformation. See Text transformations.

  • URI path – Use the URI path in the request as an aggregate key. Each distinct URI path contributes to the aggregation instance. You can use this key type once.

    URI path takes an optional text transformation. See Text transformations.

  • HTTP method – Use the request's HTTP method as an aggregate key. Each distinct HTTP method contributes to the aggregation instance. You can use this key type once.

  • IP address – Aggregate using the IP address from the web request origin in combination with other keys.

    This might not contain the address of the originating client. If a web request goes through one or more proxies or load balancers, this will contain the address of the last proxy.

  • IP address in header – Aggregate using the client address in an HTTP header in combination with other keys. This is also referred to as a forwarded IP address.

    Use caution with this option, as headers can be handled inconsistently by proxies and they can be modified to bypass inspection. For additional information and best practices, see Forwarded IP address.