apache · 8rief · Jul 9, 2026
diff --git a/docs/en/latest/plugins/authz-casbin.md b/docs/en/latest/plugins/authz-casbin.md
@@ -48,6 +48,8 @@ You must either specify the `model_path`, `policy_path`, and the `username` attr
 
 If you wish to use a global Casbin configuration, you can first specify `model` and `policy` attributes in the Plugin metadata and only the `username` attribute in the Plugin configuration. All Routes will use the Plugin configuration this way.
 
+The `username` attribute names the request header used as the Casbin subject. APISIX does not rewrite or verify this header against an authenticated consumer. If clients can send this header directly, make sure a trusted component at the edge strips, rewrites, or sets it before `authz-casbin` evaluates the request.
+
 :::
 
 ## Metadata

diff --git a/docs/zh/latest/plugins/authz-casbin.md b/docs/zh/latest/plugins/authz-casbin.md
@@ -48,6 +48,8 @@ description: 本文介绍了关于 Apache APISIX `authz-casbin` 插件的基本
 
 如果你想要使所有的 Route 共享 Casbin 配置，你可以先在插件元数据中指定 `model` 和 `policy`，在插件配置中仅指定 `username`，这样所有 Route 都可以使用 Casbin 插件配置。
 
+`username` 属性用于指定作为 Casbin subject 的请求头。APISIX 不会将该请求头与已认证的 consumer 进行改写或校验。如果客户端可以直接发送该请求头，请确保在可信边界处由可信组件先移除、重写或设置该请求头，再交由 `authz-casbin` 进行鉴权。
+
 ::::
 
 ## 元数据
-Original file line number
+Diff line change
@@ Expand Up @@
     If you wish to use a global Casbin configuration, you can first specify `model` and `policy` attributes in the Plugin metadata and only the `username` attribute in the Plugin configuration. All Routes will use the Plugin configuration this way.
+    The `username` attribute names the request header used as the Casbin subject. APISIX does not rewrite or verify this header against an authenticated consumer. If clients can send this header directly, make sure a trusted component at the edge strips, rewrites, or sets it before `authz-casbin` evaluates the request.
     :::
     ## Metadata
@@ Expand Down @@