Modify incoming request headers - Edge Security Acceleration

You can configure rules to modify, add, or delete specific request headers from clients or other services. This lets you control the content of requests. For example, you can add headers such as Accept-Encoding and Accept-Language to customize the visitor experience and gain insights into user behavior.

Overview

The Modify Incoming Request Headers feature of Edge Security Acceleration (ESA) lets you process original client requests at points of presence (POPs). You can add, modify, or delete specified request headers. This enables fine-grained back-to-origin route control, enriches backend log information, and removes irrelevant request header data to enhance business flexibility and security.

Configure incoming request headers

After you add a rule, when a user requests a resource, ESA matches and executes rules sequentially based on the rule execution priority.

In the ESA console, go to Websites, and in the Website column, click the target site.
In the navigation pane on the left, choose Rules > Transform Rules.
Click the Modify request header tab, select Client to ESA, and click Create Rule.

In the Add Request Header Modification Rule area, configure the following:

Rule Name: Enter a custom rule name.
If requests match...: Select the conditions for matching requests.
- All Requests: The rule applies to all requests for the current site.
- Filtered Requests: The rule applies only to traffic that matches a custom expression. Configure a custom expression to filter traffic.

Modify Request Header: The action to perform on matching requests.

Operation	Type	Description	Example
Add	Static	Adds the specified request header to the origin request. If the client request already contains a header with the same name, the new header overwrites the existing one.	To add a request header named `x-code` with the value `key1`, enter the following: Request Header Name: `x-code` Request Header Value: `key1`
Add	Dynamic	The header value can be set to an expression.	To add a request header named `True-Client-IP` with the value `ip.src` to record the client's originating IP address, enter the following: Request Header Name: `True-Client-IP` Request Header Value: `ip.src`
Change	Static	Changes the value of a specified request header in the origin request.	To change the value of the request header named `x-code` to `key2` in the origin request, enter the following: Request Header Name: `x-code` Request Header Value: `key2`
Change	Dynamic	The header value can be set to an expression.	To change the request header named `True-Client-IP` to the value `ip.src` in the origin request, setting its value to the client's originating IP address, enter the following: Request Header Name: `True-Client-IP` Request Header Value: `ip.src`
Delete		Deletes all headers from the origin request that match the specified Request Header Name, regardless of whether there are duplicate header parameters.	To delete the request header named `x-code`, enter the Request Header Name: `x-code`.

Note

Do not configure a Request Header Name that starts with ali- or Ali-.
To configure multiple values for the Request Header Value, separate them with a comma (,).
The delete operation is the same for both static and dynamic patterns.
The modify operation changes an existing header. This operation applies only if a header with the specified name exists in the original request.
In a single rule, multiple operations are executed sequentially. If different operations target the same header name, the last operation overwrites the previous ones.

Expression configuration example

Add the originating IP address of the client

Use case

Add a request header to record the originating IP address of the client for all incoming requests.

Procedure

In the ESA console, click Websites. In the Website column, click the target site.
In the navigation pane on the left, choose Rules > Transform Rules.
Click the Modify request header tab, select Client to ESA, and click Create Rule.
In the Add Request Header Modification Rule area, configure the following:
- Rule Name: Enter the custom rule name add-client-ip-in.
- If requests match...: Select All Requests to apply the rule to all requests for the current site.
- Modify Request Header:
  - Type: Dynamic
  - Operation: Add
  - Request Header Name: True-Client-IP-IN
  - Request Header Value: ip.src

Verify the result

Before configuration: The request header does not include the originating IP address of the client.

After configuration: The true-client-ip-in header contains the client's originating IP address.

Add the country code that corresponds to the client's IP address

Use case

Add a request header to record the country code corresponding to the client's IP address for all requests that do not originate from China (Hong Kong).

Procedure

In the ESA console, go to Websites, and in the Website column, click the target site.
In the navigation pane on the left, choose Rules > Transform Rules.
Click the Modify request header tab, select Client to ESA, and click Create Rule.
In the Add Request Header Modification Rule section, specify the following parameters:
- Rule Name: Enter a custom rule name, such as add-client-country.
- If requests match...: Select Filtered Requests and enter Country/Region does not equal China (Hong Kong).
  You can also directly edit the expression as follows: (ip.geoip.country ne "HK")
- Modify Request Header:
  - Type: Dynamic
  - Operation: Add
  - Request Header Name: IP-Country-Code
  - Request Header Value: ip.geoip.country

Verification

Before configuration: The request header does not include the country information corresponding to the client's IP address.

After configuration: The ip-country-code header, which contains the country code corresponding to the client's IP address, is added to the request header.

Add the province code that corresponds to the client's IP address

Use case

Add a request header to record the province code corresponding to the client's IP address for requests where the URI path is /content.

Procedure

In the ESA console, go to Websites and click the target site in the Website column.
In the navigation pane on the left, choose Rules > Transform Rules.
Click the Modify request header tab, select Client to ESA, and click Create Rule.
In the Add Request Header Modification Rule section, specify the following parameters:
- Rule Name: Enter a custom rule name, such as add-client-province.
- If requests match...: Select Filtered Requests and enter URI Path equals /content.
  You can also directly edit the expression as follows: (http.request.uri.path eq "/content")
- Modify Request Header:
  - Type: Dynamic
  - Operation: Add
  - Request Header Name: IP-Province-Code
  - Request Header Value: ip.src.subdivision_1_iso_code

Verification

Before configuration: The request header does not include the province information corresponding to the client's IP address.

After configuration: The ip-province-code header, which contains the province code corresponding to the client's IP address, is added to the request header.

References

Rule-related features vary in execution priority, rule behavior, and configuration scope. For more information, see How ESA rules take effect.