This is an automated email from the ASF dual-hosted git repository.
shreemaan-abhishek pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 323997dda docs(forward-auth): clarify that X-Forwarded-* carry the
client request (#13978)
323997dda is described below
commit 323997dda2f684c98c272c7c615f4743ff91c41f
Author: Shreemaan Abhishek <[email protected]>
AuthorDate: Fri Oct 9 00:12:30 2026 +0800
docs(forward-auth): clarify that X-Forwarded-* carry the client request
(#13978)
---
docs/en/latest/plugins/forward-auth.md | 20 +++++++++++++++++++-
docs/zh/latest/plugins/forward-auth.md | 20 +++++++++++++++++++-
2 files changed, 38 insertions(+), 2 deletions(-)
diff --git a/docs/en/latest/plugins/forward-auth.md
b/docs/en/latest/plugins/forward-auth.md
index 13f7e9ef3..1946e4eca 100644
--- a/docs/en/latest/plugins/forward-auth.md
+++ b/docs/en/latest/plugins/forward-auth.md
@@ -42,9 +42,27 @@ The `forward-auth` Plugin supports the integration with an
external authorizatio
- `X-Forwarded-Proto`: scheme
- `X-Forwarded-Method`: HTTP method
- `X-Forwarded-Host`: host
-- `X-Forwarded-Uri`: URI
+- `X-Forwarded-Uri`: normalized URI, including the query string
- `X-Forwarded-For`: source IP
+:::note
+
+These headers describe the request as the client sent it. If the Route also
rewrites the request with [proxy-rewrite](./proxy-rewrite.md), the Upstream
service receives the rewritten scheme, method, host, and URI, while the headers
above keep carrying the client values.
+
+If your authorization service decides based on the URI that the Upstream
service receives, forward it explicitly with `extra_headers` and the
`$upstream_uri` variable:
+
+```json
+{
+ "extra_headers": {
+ "X-Forwarded-Upstream-Uri": "$upstream_uri"
+ }
+}
+```
+
+`$upstream_uri` is set by the Plugins that rewrite the forwarded path, such as
`proxy-rewrite`. It is empty when nothing rewrites the request, in which case
the Upstream service receives the URI in `X-Forwarded-Uri`.
+
+:::
+
## Attributes
| Name | Type | Required | Default | Valid values
| Description
|
diff --git a/docs/zh/latest/plugins/forward-auth.md
b/docs/zh/latest/plugins/forward-auth.md
index ab1b7f9cb..6b7117858 100644
--- a/docs/zh/latest/plugins/forward-auth.md
+++ b/docs/zh/latest/plugins/forward-auth.md
@@ -42,9 +42,27 @@ import TabItem from '@theme/TabItem';
- `X-Forwarded-Proto`：协议
- `X-Forwarded-Method`：HTTP 方法
- `X-Forwarded-Host`：主机
-- `X-Forwarded-Uri`：URI
+- `X-Forwarded-Uri`：规范化后的 URI，包含查询字符串
- `X-Forwarded-For`：源 IP
+:::note
+
+这些请求头描述的是客户端发送的原始请求。如果该路由同时使用 [proxy-rewrite](./proxy-rewrite.md)
改写请求，上游服务收到的是改写后的协议、方法、主机和 URI，而上述请求头仍然携带客户端的值。
+
+如果授权服务需要根据上游服务实际收到的 URI 做出决策，请通过 `extra_headers` 和 `$upstream_uri` 变量显式传递：
+
+```json
+{
+ "extra_headers": {
+ "X-Forwarded-Upstream-Uri": "$upstream_uri"
+ }
+}
+```
+
+`$upstream_uri` 由改写转发路径的插件设置，例如 `proxy-rewrite`。当没有插件改写请求时该变量为空，此时上游服务收到的就是
`X-Forwarded-Uri` 中的 URI。
+
+:::
+
## 属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
