在 Gateway 中修改 HTTP 请求标头

具有 Allow 操作的 Gateway HTTP 策略可以在匹配的请求到达目的地之前修改其标头。您可以添加动态值来设置标头，以便将诸如用户身份、源 IP 和其他输入之类的信息转发到上游服务，实施 SaaS 租户控制，剥离内部标头，以及覆盖标头内容。

标头操作需要进行 TLS 解密，因为 HTTP 标头仅在 Gateway 能够解密的流量上可见。

Gateway 在 HTTP 策略上支持三种标头操作。当请求与配置了标头操作的 Allow 策略匹配时，Gateway 按以下顺序应用它们：

1. Delete（删除） —— 从请求中移除标头。
2. Overwrite（覆盖） —— 覆盖请求中的标头。具有匹配名称的标头的其值将被覆盖。如果标头不存在，则会被创建。
3. Add（添加） —— 将标头附加到请求中。如果标头已存在，则添加的值将追加到现有值之后。

每个策略最多可以配置 20 个标头操作。标头名称限制为 256 字节，标头值限制为 4 KB。

添加标头会将一个值附加到请求中。如果标头已存在，该值将与现有值并存，而不是替换它。

覆盖标头会覆盖任何现有值。如果请求中尚不存在该标头，则创建它。当您需要保证特定的标头值而不论客户端发送了什么时，请使用此操作。

删除标头会将它从请求中完全移除。如果标头不存在，该操作将没有任何效果。

标头值可以包括动态变量，Gateway 会在请求时使用当前会话中的身份、设备和网络上下文来解析这些变量。动态变量使用 @{...} 语法，并且可以在同一个值中与静态文本混合使用。

例如，在请求时，user-@{identity.email} 的标头值将解析为 user-jdoe@example.com。

以下动态变量可用：

动态变量需要一个处于活动状态的身份会话。如果 Gateway 无法解析变量（例如，用户未通过身份验证），则该变量将被替换为类似 cf-unresolved 或 cf-invalid 的警告字符串，并向 HTTP 日志中添加一条警告。

要创建具有标头操作的 HTTP 策略：

1. 在 Cloudflare One 仪表板 ↗中，转到 Traffic policies（流量策略） > Firewall policies（防火墙策略） > HTTP。
2. 选择 Add a policy（添加策略）。
3. 构建一个表达式来匹配您想要修改的流量。
4. 在 Action（操作） 中，选择 Allow（允许）。
5. 在 Modify request headers（修改请求标头） 下，选择 Add（添加） 或 Overwrite（覆盖） 以添加或覆盖标头，或选择 Remove（移除） 以删除标头。
6. 对于 Add 和 Overwrite 操作，输入标头名称和值。要使用动态变量，请在值字段中输入 @{...} 语法，或者选择 {} 按钮来查看可用值列表。对于 Remove 操作，仅输入标头名称。
7. 保存您的策略。

要通过 API 创建具有标头操作的 HTTP 策略，请在 rule_settings 对象中包含 add_headers、set_headers 和 delete_headers。

curl https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/rules \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
  "name": "Forward identity headers",
  "action": "allow",
  "enabled": true,
  "filters": ["http"],
  "traffic": "any(http.request.domains[*] in {\"app.example.com\"})",
  "rule_settings": {
    "add_headers": {
      "X-User-Email": ["@{identity.email}"],
      "X-User-Groups": ["@{identity.groups}"]
    },
    "set_headers": {
      "X-Forwarded-User": ["@{identity.email}"]
    },
    "delete_headers": ["X-Debug-Token", "X-Internal-Only"]
  }
}'

rule_settings 中用于标头操作的字段为：

单个标头值可以包含静态文本和动态变量的混合。例如：

{
  "add_headers": {
    "X-Request-Context": ["user=@{identity.email}, device=@{device.id}, src=@{source.ip}"]
  }
}

如果您从浏览器保存 HAR (HTTP Archive) 文件来分析您的 Web 流量，使用 Gateway 定义的自定义标头不会显示在该文件中。这是因为 Gateway 是在请求离开浏览器之后注入该标头的。

要验证 Gateway 正在应用自定义标头：

1. 在包含自定义标头的策略中，添加一个选择器以匹配 HTTPBin ↗（一个用于测试 HTTP 请求的开源网站）的流量。例如：

   选择器	运算符	值	逻辑	操作	不受信任的证书操作
   Application（应用程序）	in	Google Workspace	Or（或）	Allow（允许）	Block（阻止）
   Domain（域名）	in	httpbin.org

2. 在您的设备上，前往 httpbin.org/anything ↗。您的自定义标头将显示在标头列表中。

3. （可选）从您的策略中移除 HTTPBin 表达式。

租户控制（Tenant control）允许您的用户访问企业 SaaS 应用程序，同时阻止访问同一服务上的个人账户。例如，您可以允许访问您公司的 Google Workspace，同时阻止个人 Gmail 登录。

Gateway 通过向匹配的请求中注入自定义 HTTP 标头来实现租户控制。这些标头告诉 SaaS 应用程序哪个租户（组织）是已授权的。如果用户尝试使用个人账户进行身份验证，SaaS 应用程序会读取该标头并拒绝该请求。

您可以使用动态标头值将用户身份信息转发到您的上游应用程序，而不需要这些应用程序直接与 Cloudflare Access 集成。

您的上游应用程序可以读取这些标头来识别用户、执行授权逻辑或填充审计日志。

为了防止客户端伪造内部标头，在转发请求之前，使用删除操作移除标头，然后使用添加或设置操作以验证后的值重新注入它们。

curl https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/rules \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
  "name": "Replace internal headers",
  "action": "allow",
  "enabled": true,
  "filters": ["http"],
  "traffic": "any(http.request.domains[*] in {\"internal.example.com\"})",
  "rule_settings": {
    "delete_headers": ["X-Internal-User"],
    "set_headers": {
      "X-Internal-User": ["@{identity.email}"]
    }
  }
}'

您可以在 HTTP 策略中包含自定义标头，以允许您的用户通过 Cloudflare WAF。这对于仅允许 Cloudflare One Client 用户通过您的 WAF 很有用。

1. 为您的 WAF 后面的内部域名创建一条带有自定义标头的 Allow 策略。

   选择器	运算符	值	操作
   Domain（域名）	in	internalapp.com	Allow（允许）

   自定义标头名称	自定义标头值
   X-Example-Header	example-value

2. 在 Cloudflare WAF 中，创建一个自定义规则以要求相同的 HTTP 标头。

您配置浏览器隔离来发送自定义标头。这对于为隔离的 SaaS 应用程序实施租户控制，或者向隔离的网站发送任意自定义请求标头有用。

要在浏览器隔离中使用自定义标头，请创建两条针对相同域名或应用程序组的 HTTP 策略。例如，您可以为 HTTPBin（一个用于测试 HTTP 请求的开源网站）创建策略：

1. 为 httpbin.org 创建一条 Isolate 策略。

   选择器	运算符	值	操作
   Domain（域名）	in	httpbin.org	Isolate（隔离）

2. 为 httpbin.org 创建一条带有自定义标头的 Allow 策略。

   选择器	运算符	值	操作
   Domain（域名）	in	httpbin.org	Allow（允许）

   自定义标头名称	自定义标头值
   Example-Header	example-value

3. 前往 httpbin.org/anything ↗。Cloudflare 将在隔离浏览器中渲染该网站。您的自定义标头将显示在标头列表中。