企业官网建设流程全解析

Authelia 与 Traefik v1 反向代理集成指南：ForwardAuth 配置与实战部署

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia

本篇技术指南以 Authelia 官方仓库中 Traefik v1 集成文档 为核心，系统讲解如何将 Authelia 单点登录多因素认证门户接入 Traefik 1.x 反向代理：涵盖 ForwardAuth 授权实现原理、受信任代理（Trusted Proxies）安全配置、会话 Cookie 现代/遗留两种配置范式，以及一份完整可运行的 Docker Compose 部署示例（Traefik 1.x + Authelia + Nextcloud + Heimdall）。读完本文，你将掌握用 Traefik v1 的traefik.frontend.auth.forward.*系列标签保护任意后端应用，并能正确配置 Basic 认证场景下的/api/verify?auth=basic端点。

前提说明：遗留支持状态

在动手之前，必须明确一点：Traefik 官方已停止对 1.x 版本的支持，因此 Authelia 也不再对其进行正式支持。当前仓库中的这份指南保留下来，是作为一种"遗留支持"（legacy support）形式存在，方便仍在使用 Traefik 1.x 的用户参考。

安全提示：若你正在规划新部署，建议优先参考仓库中的 Traefik（现行版本）集成指南，它覆盖了 Traefik 3.x 的 Docker Compose labels、动态 YAML 配置以及基于客户端证书的 mTLS 通信方案。本文聚焦 Traefik v1 的历史配置语法。

另外需要强调的是：官方无法为每一种代理部署方式提供示例。本文展示的是一套建议性配置，你必须理解代理配置并针对自身架构进行定制，官方文档中的 See Also 小节也提供了 Traefik v1 官方文档链接供进一步查阅。

Get started：首次部署前必读

如果你是第一次搭建 Authelia，官方强烈建议先阅读 Get started 入门指南。该指南会带你完成引导 Authelia 所必需的各种步骤——包括生成密钥、准备用户数据库、配置存储后端等，这些是成功集成反向代理的前置条件。

受信任代理与集成安全

为什么必须关注转发头（Forwarded Headers）

集成安全的第一课是：呈现给 Authelia 的X-Forwarded-*头必须来自可信来源。反向代理与负载均衡器必须被配置为：当这些头直接来自客户端（而非可信环境内的代理）时，予以移除并替换。详细原理见仓库中的 Forwarded Headers 文档。

这一点的关键影响在于 访问控制规则 中的network（网络）条件依赖X-Forwarded-For头来判断客户端真实 IP。如果该头可以被不可信来源伪造，攻击者理论上可以劫持任何包含该条件的规则，视配置方式不同甚至可能绕过认证条件。

Authelia 官方同时要求：在使用本集成时，务必阅读 Validating Forwarded Authentication 参考指南，并将其中描述的验证步骤纳入常规安全验证流程。该指南给出了一个可落地的验证方法：

1. 在访问控制规则最顶部临时加入如下规则：

access_control: rules: - domain: 'app.example.com' policy: 'bypass' networks: - '169.254.1.2' # Your normal rules here.

2. 执行curl -i -H 'X-Forwarded-For: 169.254.1.2' https://app.example.com。
3. 若配置正确，应返回302状态码并重定向到 Authelia 登录门户（如location: https://auth.example.com/?rd=...&rm=GET），说明代理没有盲目信任伪造的X-Forwarded-For头（因为该伪造 IP 命中了 bypass 规则，却仍被要求认证）。验证完毕后移除该临时规则。

Traefik v1 的默认安全行为

Traefik 默认不信任任何其他代理，要求显式配置哪些代理是可信的，并会移除可能导致安全问题的伪造头——这样的配置很难出错。这是具有良好安全实践的代理所共有的重要安全特性。

配置 TrustedIPs

在 Traefik v1 中，受信任代理通过 entrypoint 参数ForwardedHeaders.TrustedIPs与ProxyProtocol.TrustedIPs配置。示例中给出了四个被注释的配置行，演示如何将以下网段加入受信任代理列表：

• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16
• fc00::/7

重要提醒：示例配置并非生产环境推荐，它只是用来演示如何配置多个 IP 网段。生产环境中应只包含架构内受信任代理的具体 IP 地址范围，除非整个子网内只有受信任代理、没有其他服务，否则不应信任整个子网。

假设与适配（Assumptions and Adaptation）

本指南基于以下部署假设，在更复杂的场景中你可能需要自行适配（示例中的占位值可以在官方文档站点通过变量自动替换）：

• 部署场景：
  • 单主机（Single Host）
  • Authelia 以容器方式部署，容器名为authelia，端口为9091
  • 代理与 Authelia 以容器方式部署，并共享同一 Docker 网络
• 基于以上假设，代理访问 Authelia 的地址为http://authelia:9091，因此你需要：
  • 若 Authelia 配置了 TLS 密钥与证书，将 URL 中的http://全部改为https://
  • 若使用了不同的容器名或代理部署位置不同，调整 URL 中的authelia主机名
  • 若调整了配置中的默认端口，调整 URL 中的9091
  • 若 Authelia 与代理不在同一主机，调整整个 URL
• 所有服务都属于example.com域：除非你只是测试或恰好使用该域名，否则示例中该域名及其子域名都必须替换为你自己的域名。

实现原理：ForwardAuth 授权端点

Traefik（包括 v1）使用的是 Authelia 的ForwardAuth授权实现。与它关联的 ForwardAuth Metadata 应视为必填项。

从 Proxy Authorization 参考指南 可以查到，Authelia 默认提供四个授权端点：

其中 ForwardAuth 实现通过以下元数据（均来自请求头）确定用户请求的对象（资源）与身份：

从源码结构也可以印证这一点：在 handler_authz_impl_forwardauth.go 中，handleAuthzGetObjectForwardAuth函数依次读取X-Forwarded-Method（为空则直接报错）、X-Forwarded-Proto、X-Forwarded-Host与X-Forwarded-URI，组合成authorization.Object用于后续授权判定。也就是说，Traefik v1 的trustForwardHeader: true标签必须开启，才能把这些X-Forwarded-*头正确传递给 Authelia。

前置配置：Authz 端点

以下示例默认你使用默认的 Authz 端点配置，或与之类似的最小配置：

server: endpoints: authz: forward-auth: implementation: 'ForwardAuth'

关于端点配置，补充说明：authz下的第一级是端点名称，所有端点路径以/api/authz/开头并以名称结尾；implementation为大小写敏感的枚举值（ForwardAuth、ExtAuthz、AuthRequest、Legacy）；authn_strategies是有序的认证策略列表，第一个成功者生效，失败（而非信息不足）会立即短路后续策略。默认的forward-auth端点同时启用了HeaderAuthorization（Basic/Bearer）与CookieSession两种策略。

前置配置：会话 Cookie（现代 vs 遗留）

以下示例还假设你使用现代会话配置，即domain、authelia_url、default_redirection_url作为session.cookies键下的列表项子键。下面给出现代配置及遗留配置的对照：

现代配置（推荐）：

session: cookies: - domain: 'example.com' authelia_url: 'https://auth.example.com' default_redirection_url: 'https://www.example.com'

遗留配置：

default_redirection_url: 'https://www.example.com' session: domain: 'example.com'

补充说明（依据 Session 配置文档）：cookies是 Authelia 处理的特定 Cookie 域列表，未正确配置的域会被 Authelia 自动拒绝；每个列表项可独立设置name（默认authelia_session）、same_site（默认lax）、inactivity（默认 5 分钟）、expiration（默认 1 小时）、remember_me（默认 1 个月）等选项。

配置：完整的 Docker Compose 部署示例

下面是一份带注释的 docker 部署示例，包含四个服务：

• Traefik 1.x：反向代理
• Authelia portal：认证门户
• 受保护端点（Nextcloud）：需要完整会话认证
• 带Authorization头的受保护端点（Heimdall）：用于 Basic 认证场景

示例展示的是用 Traefik v1 的 labels 保护端点（本例为 Nextcloud）的方式。

注意：示例中未包含 ACME 证书配置，你需要为自己的 Traefik 单独配置对应的 ACME 设置。

Basic Authentication 说明

Authelia 支持通过Proxy-Authorization头完成第一因素认证。由于该头与 Traefik 1.x不兼容，你可以调用 Authelia 的/api/verify端点并附加auth=basic查询参数，强制切换为使用Authorization头。这正是下方 Heimdall 服务使用/api/authz/forward-auth/basic端点地址的原因。

compose.yml

networks: net: driver: 'bridge' services: traefik: image: 'traefik:v1.7.34-alpine' container_name: 'traefik' volumes: - '/var/run/docker.sock:/var/run/docker.sock' networks: net: {} labels: traefik.frontend.rule: 'Host:traefik.example.com' traefik.port: '8081' ports: - '80:80' - '443:443' - '8081:8081' restart: 'unless-stopped' command: - '--api' - '--api.entrypoint=api' - '--docker' - '--defaultEntryPoints=https' - '--logLevel=DEBUG' - '--traefikLog=true' - '--traefikLog.filepath=/var/log/traefik.log' - '--entryPoints=Name:http Address::80' - '--entryPoints=Name:https Address::443 TLS' ## See the Forwarded Header Trust section. Comment the above two lines, then uncomment and customize the next two lines to configure the TrustedIPs. # - '--entryPoints=Name:http Address::80 ForwardedHeaders.TrustedIPs:10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7 ProxyProtocol.TrustedIPs:10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7' # - '--entryPoints=Name:https Address::443 TLS ForwardedHeaders.TrustedIPs:10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7 ProxyProtocol.TrustedIPs:10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7' - '--entryPoints=Name:api Address::8081' authelia: image: 'authelia/authelia' container_name: 'authelia' volumes: - '/path/to/authelia:/config' networks: net: {} labels: traefik.frontend.rule: 'Host:auth.example.com' restart: 'unless-stopped' environment: TZ: 'Australia/Melbourne' nextcloud: image: 'linuxserver/nextcloud' container_name: 'nextcloud' volumes: - '/path/to/nextcloud/config:/config' - '/path/to/nextcloud/data:/data' networks: net: {} labels: traefik.frontend.rule: 'Host:nextcloud.example.com' traefik.frontend.auth.forward.address: 'http://authelia:9091/api/authz/forward-auth' ## The following commented line is for configuring the Authelia URL in the proxy. We strongly suggest this is ## configured in the Session Cookies section of the Authelia configuration. # traefik.frontend.auth.forward.address: 'http://authelia:9091/api/authz/forward-auth?authelia_url=https%3A%2F%2Fauth.example.com%2F' traefik.frontend.auth.forward.trustForwardHeader: 'true' traefik.frontend.auth.forward.authResponseHeaders: 'Remote-User,Remote-Groups,Remote-Email,Remote-Name' restart: 'unless-stopped' environment: PUID: '1000' PGID: '1000' TZ: 'Australia/Melbourne' heimdall: image: 'linuxserver/heimdall' container_name: 'heimdall' volumes: - '/path/to/heimdall/config:/config' networks: net: {} labels: traefik.frontend.rule: 'Host:heimdall.example.com' traefik.frontend.auth.forward.address: 'http://authelia:9091/api/authz/forward-auth/basic' traefik.frontend.auth.forward.trustForwardHeader: 'true' traefik.frontend.auth.forward.authResponseHeaders: 'Remote-User,Remote-Groups,Remote-Email,Remote-Name' restart: 'unless-stopped' environment: PUID: '1000' PGID: '1000' TZ: 'Australia/Melbourne'

关键标签逐项解读

针对 Traefik v1 的 Frontend 标签，逐项说明其作用：

• traefik.frontend.rule: 'Host:nextcloud.example.com'：定义该前端（frontend）匹配的 Host 规则，Traefik 依据它把请求路由到对应后端容器。
• traefik.frontend.auth.forward.address：ForwardAuth 中间件的目标地址，即 Authelia 的授权端点。普通会话认证使用/api/authz/forward-auth，Basic 认证场景使用/api/authz/forward-auth/basic。
• traefik.frontend.auth.forward.trustForwardHeader: 'true'：必须开启，让 Traefik 把X-Forwarded-*系列头转发给 Authelia（见上文 ForwardAuth 元数据表与源码实现）。
• traefik.frontend.auth.forward.authResponseHeaders: 'Remote-User,Remote-Groups,Remote-Email,Remote-Name'：认证成功后，Authelia 返回的这些响应头会被 Traefik 附加到发往后端应用的请求上，供后端识别用户身份与所属组。

被注释的那行traefik.frontend.auth.forward.address演示了通过查询参数authelia_url=https%3A%2F%2Fauth.example.com%2F（URL 编码后的https://auth.example.com/）在代理侧覆盖 Authelia 门户地址的写法。官方强烈建议将该值配置在 Authelia 配置的 Session Cookies 小节（即session.cookies[].authelia_url）中，而不是写在代理标签里。

认证通过后的请求流

整体工作流可以概括为：

1. 用户访问https://nextcloud.example.com，Traefik 前端匹配该 Host 规则。
2. Traefik 以子请求方式调用http://authelia:9091/api/authz/forward-auth，并附带X-Forwarded-Method/Proto/Host/URI/For头。
3. Authelia 依据 CookieSession 策略校验会话 Cookie（未登录则 302 重定向到authelia_url登录门户）；若存在Authorization/Proxy-Authorization头则尝试 HeaderAuthorization 策略。
4. 授权通过后返回 200，并将Remote-User等响应头回传给 Traefik，Traefik 再转发给后端应用；未通过则返回 401/407 或重定向。

验证与排障建议

完成配置后，建议按 Validating Forwarded Authentication 的流程进行验证：

1. 常规运行验证：退出 Authelia 登录状态，访问受保护应用，确认被重定向到 Authelia 登录门户，并被要求执行预期等级的认证（单因素或多因素）。
2. 网络访问控制规则验证：按上文"受信任代理"一节中的方法，临时加入基于169.254.1.2的 bypass 规则并curl测试，确认代理未盲目信任伪造的X-Forwarded-For头。
3. 在以下场景变更后都应重新验证：初次配置完成、修改代理中与 Authelia 相关的配置或集成 URL、修改 server address、修改某个应用的代理配置、修改访问控制规则；升级代理时也建议验证（代理 bug、行为变化或升级导致配置丢失都可能引发故障）。

See Also

• Traefik（现行版本）集成指南
• ForwardAuth 授权实现参考
• Forwarded Headers 安全说明
• Validating Forwarded Authentication 验证指南
• Server Authz 端点配置
• Session 会话配置

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia