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?authbasic端点。前提说明遗留支持状态在动手之前必须明确一点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 参考指南并将其中描述的验证步骤纳入常规安全验证流程。该指南给出了一个可落地的验证方法在访问控制规则最顶部临时加入如下规则access_control: rules: - domain: app.example.com policy: bypass networks: - 169.254.1.2 # Your normal rules here.执行curl -i -H X-Forwarded-For: 169.254.1.2 https://app.example.com。若配置正确应返回302状态码并重定向到 Authelia 登录门户如location: https://auth.example.com/?rd...rmGET说明代理没有盲目信任伪造的X-Forwarded-For头因为该伪造 IP 命中了 bypass 规则却仍被要求认证。验证完毕后移除该临时规则。Traefik v1 的默认安全行为Traefik 默认不信任任何其他代理要求显式配置哪些代理是可信的并会移除可能导致安全问题的伪造头——这样的配置很难出错。这是具有良好安全实践的代理所共有的重要安全特性。配置 TrustedIPs在 Traefik v1 中受信任代理通过 entrypoint 参数ForwardedHeaders.TrustedIPs与ProxyProtocol.TrustedIPs配置。示例中给出了四个被注释的配置行演示如何将以下网段加入受信任代理列表10.0.0.0/8172.16.0.0/12192.168.0.0/16fc00::/7重要提醒示例配置并非生产环境推荐它只是用来演示如何配置多个 IP 网段。生产环境中应只包含架构内受信任代理的具体 IP 地址范围除非整个子网内只有受信任代理、没有其他服务否则不应信任整个子网。假设与适配Assumptions and Adaptation本指南基于以下部署假设在更复杂的场景中你可能需要自行适配示例中的占位值可以在官方文档站点通过变量自动替换部署场景单主机Single HostAuthelia 以容器方式部署容器名为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 默认提供四个授权端点名称路径实现认证策略forward-auth/api/authz/forward-authForwardAuthHeaderAuthorization, CookieSessionext-authz/api/authz/ext-authzExtAuthzHeaderAuthorization, CookieSessionauth-request/api/authz/auth-requestAuthRequestHeaderAuthorization, CookieSessionlegacy/api/verifyLegacyHeaderLegacy, CookieSession其中 ForwardAuth 实现通过以下元数据均来自请求头确定用户请求的对象资源与身份元数据来源键MethodHeaderX-Forwarded-MethodSchemeHeaderX-Forwarded-ProtoHostnameHeaderX-Forwarded-HostPathHeaderX-Forwarded-URIIPHeaderX-Forwarded-ForAuthelia URLSession Cookie 配置authelia_url从源码结构也可以印证这一点在 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、Legacyauthn_strategies是有序的认证策略列表第一个成功者生效失败而非信息不足会立即短路后续策略。默认的forward-auth端点同时启用了HeaderAuthorizationBasic/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端点并附加authbasic查询参数强制切换为使用Authorization头。这正是下方 Heimdall 服务使用/api/authz/forward-auth/basic端点地址的原因。compose.ymlnetworks: 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.entrypointapi - --docker - --defaultEntryPointshttps - --logLevelDEBUG - --traefikLogtrue - --traefikLog.filepath/var/log/traefik.log - --entryPointsName:http Address::80 - --entryPointsName: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. # - --entryPointsName: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 # - --entryPointsName: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 - --entryPointsName: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_urlhttps%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.addressForwardAuth 中间件的目标地址即 Authelia 的授权端点。普通会话认证使用/api/authz/forward-authBasic 认证场景使用/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_urlhttps%3A%2F%2Fauth.example.com%2FURL 编码后的https://auth.example.com/在代理侧覆盖 Authelia 门户地址的写法。官方强烈建议将该值配置在 Authelia 配置的 Session Cookies 小节即session.cookies[].authelia_url中而不是写在代理标签里。认证通过后的请求流整体工作流可以概括为用户访问https://nextcloud.example.comTraefik 前端匹配该 Host 规则。Traefik 以子请求方式调用http://authelia:9091/api/authz/forward-auth并附带X-Forwarded-Method/Proto/Host/URI/For头。Authelia 依据 CookieSession 策略校验会话 Cookie未登录则 302 重定向到authelia_url登录门户若存在Authorization/Proxy-Authorization头则尝试 HeaderAuthorization 策略。授权通过后返回 200并将Remote-User等响应头回传给 TraefikTraefik 再转发给后端应用未通过则返回 401/407 或重定向。验证与排障建议完成配置后建议按 Validating Forwarded Authentication 的流程进行验证常规运行验证退出 Authelia 登录状态访问受保护应用确认被重定向到 Authelia 登录门户并被要求执行预期等级的认证单因素或多因素。网络访问控制规则验证按上文受信任代理一节中的方法临时加入基于169.254.1.2的 bypass 规则并curl测试确认代理未盲目信任伪造的X-Forwarded-For头。在以下场景变更后都应重新验证初次配置完成、修改代理中与 Authelia 相关的配置或集成 URL、修改 server address、修改某个应用的代理配置、修改访问控制规则升级代理时也建议验证代理 bug、行为变化或升级导致配置丢失都可能引发故障。See AlsoTraefik现行版本集成指南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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考