Traefik PassTLSClientCert 中间件文档

PassTLSClientCert（传递 TLS 客户端证书）

passTLSClientCert 中间件将传入的客户端 TLS 证书中选定的数据作为请求头转发到后端服务。

配置示例

在 X-Forwarded-Tls-Client-Cert 头中传递 PEM

YAML 格式：

http:
  middlewares:
    test-passtlsclientcert:
      passTLSClientCert:
        pem: true

TOML 格式：

[http.middlewares]
  [http.middlewares.test-passtlsclientcert.passTLSClientCert]
    pem = true

Labels 格式：

labels:
  - "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"

Kubernetes 格式：

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-passtlsclientcert
spec:
  passTLSClientCert:
    pem: true

在 X-Forwarded-Tls-Client-Cert-Info 头中传递所有可用信息

YAML 格式：

http:
  middlewares:
    test-passtlsclientcert:
      passTLSClientCert:
        info:
          notAfter: true
          notBefore: true
          sans: true
          subject:
            country: true
            province: true
            locality: true
            organization: true
            organizationalUnit: true
            commonName: true
            serialNumber: true
            domainComponent: true
          issuer:
            country: true
            province: true
            locality: true
            organization: true
            commonName: true
            serialNumber: true
            domainComponent: true

配置选项

字段	描述	默认值	必填
pem	如果为 true，则将客户端证书的完整 PEM 表示转发到 X-Forwarded-Tls-Client-Cert 头。	false	否
info	选择性地将证书字段转发到 X-Forwarded-Tls-Client-Cert-Info 头。	-	否
info.notAfter	转发证书的 notAfter 日期。	false	否
info.notBefore	转发证书的 notBefore 日期。	false	否
info.sans	转发证书的 Subject Alternative Names（SANs）。	false	否
info.subject.*	转发证书 subject 的指定字段。	false	否
info.issuer.*	转发证书 issuer 的指定字段。	false	否

何时使用

• 当你的后端服务需要识别和验证客户端证书时（例如 mTLS 场景）
• 当你想要在后端服务日志中记录客户端证书的元数据时
• 当你想要根据客户端证书的特定属性（如组织、域名）来路由或限流时

头名称

• X-Forwarded-Tls-Client-Cert：包含客户端证书的完整 PEM
• X-Forwarded-Tls-Client-Cert-Info：包含所选证书字段，格式为 key=value 对

---

在生产环境使用 Traefik OSS？

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

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