Traefik ForwardAuth 中间件文档

ForwardAuth（转发认证）

forwardAuth 中间件将身份认证委托给外部服务。

• 如果认证服务返回 2XX 响应码，则授予访问权限，并继续执行原始请求。
• 否则，认证服务器的响应将直接返回给客户端。

配置示例

YAML 格式：

# 转发认证到 example.com
http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"

Kubernetes 格式：

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth

配置选项

字段	描述	默认值	必填
address	认证服务器的地址。	-	是
trustForwardHeader	在 X-Forwarded-Method、X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-Uri 头中转发所有原始方法、协议、主机、URI 等，而非 X-Forwarded-For 头。更多信息参见 trustForwardHeader。	false	否
authResponseHeaders	认证响应中要复制的头列表。	[]	否
authResponseHeadersRegex	认证响应中要复制的头正则表达式。更多信息参见 authResponseHeadersRegex。	""	否
authRequestHeaders	认证请求中要复制的头列表。	[]	否
addAuthCookiesToResponse	允许在请求成功后转发 Set-Cookie 头到客户端。	false	否
forwardBody	转发请求体到认证服务器。	false	否
maxBodySize	转发请求体的最大字节数。更多信息参见 maxBodySize。	-1	否
maxResponseBodySize	来自认证服务的响应体最大字节数。更多信息参见 maxResponseBodySize。	-1	否
headerField	允许定义用于存储已认证用户的头字段。	""	否

trustForwardHeader

警告

启用后，Traefik 信任所有接收到的 X-Forwarded-* 头。

authResponseHeadersRegex

authResponseHeadersRegex 允许使用正则表达式来匹配认证响应头。例如：匹配 Foo 和 Bar 但不匹配 FooBar：

authResponseHeadersRegex: "^Foo|Bar$"

maxBodySize

• 0 表示不转发请求体到认证服务器。
• -1 表示使用 maxRequestBodyBytes 限制，默认为无限制（但至少支持 1MB）。

maxResponseBodySize

• 0 禁用响应体读取。
• -1 表示无限制。
• 超过限制时，认证响应体将被截断。

---

在生产环境使用 Traefik OSS？

如果你在工作中使用 Traefik，可以考虑为其添加企业级 API 网关能力或获取 Traefik OSS 的商业支持。

• 观看我们的 API 网关演示视频
• 申请 24/7/365 OSS 支持