在 Gateway 中修改 HTTP 请求标头

带有 Allow 操作的 Gateway HTTP 策略可以在匹配请求到达目标之前修改其标头。你可以添加动态值，将用户身份、源 IP 和其他输入转发给上游服务、强制实施 SaaS 租户控制、剥离内部标头、覆盖标头内容。

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

对于需要自定义代码或响应转换的标头更改，请使用 Forward（转发）（beta）在 HTTP 过滤之后调用 Worker。可直接在策略中表达的更改仍可使用内置的 Allow 策略标头操作。

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

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

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

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

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

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

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

例如，标头值 user-@{identity.email} 在请求时会解析为 [email protected]。

以下动态变量可用：

动态变量需要活动的身份会话。如果 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 表达式。

租户控制允许用户访问企业 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 标头。

你可以配置 Browser Isolation 以发送自定义标头。这对于为隔离的 SaaS 应用程序实施租户控制，或向隔离网站发送任意自定义请求标头很有用。

要将自定义标头与 Browser Isolation 一起使用，请创建两条针对同一域名或应用程序组的 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 会在隔离浏览器中渲染该站点。自定义标头将出现在标头列表中。