Authelia 与 Traefik 反向代理集成实战指南（Docker Compose 全流程部署）

Authelia 与 Traefik 反向代理集成实战指南Docker Compose 全流程部署【免费下载链接】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 官方博客《Authelia Traefik Setup Guide》完整演示如何在单主机 Docker Compose 环境中将Authelia作为独立认证服务接入Traefik反向代理通过 ForwardAuth 中间件实现auth.example.com门户登录与受保护应用的访问控制one_factor / two_factor 策略。读完本文你将掌握目录结构与 Compose 编排、Authelia 完整配置逐项解析、密钥安全生成、用户数据库初始化、启动验证与故障排查并理解 ForwardAuth 端点底层如何通过转发请求头完成鉴权。安全提示官方将该指南定位为临时解决方案用于在官方 Getting Started 文档完善期间提供参考未来版本可能不再随新版本更新届时会发布弃用通告。它不是一键演示环境如需开箱即用的整体演示可参考 本地集成包。文中的配置遵循官方支持的方式属于有观点opinionated的推荐部署形态。前提假设与适配要点本指南基于以下假设高级复杂场景需要自行适配无法覆盖所有进阶配置项Docker 已正确安装并可用Docker 安装文档单主机Single Host部署默认变量下文所有示例均使用这些默认值请按需替换容器名autheliaAuthelia 监听端口9091域名example.comAuthelia 门户子域auth.example.com。需要适配的情形使用不同容器名或代理部署在不同位置时需修改 URL 中的authelia修改了配置中的默认端口时需同步修改 URL 中的9091Authelia 与代理不在同一主机时需整体替换 URL所有服务均属于example.com域除非仅用于测试或确实使用该域名否则示例中所有域名与子域都必须替换为你自己的域名。项目文件结构建议按如下目录组织整个项目 project ┣ authelia ┃ ┣ config ┃ ┃ ┣ configuration.yml ┃ ┃ ┗ users.yml ┃ ┗ secrets ┣ compose.yml ┗ traefik ┣ config ┃ ┣ dynamic.yml ┃ ┗ traefik.yml ┣ data ┃ ┗ acme.json ┣ logs ┗ secrets其中authelia/config/存放 Authelia 配置文件与用户数据库authelia/secrets/存放密钥文件traefik/存放 Traefik 静态/动态配置、ACME 证书存储与日志。搭建 Traefik 与第一个测试服务本指南只聚焦与 Authelia 协作所需的最小 Traefik 配置进阶特性请参考 Traefik 官方文档。Docker Compose 定义services: traefik: image: traefik:latest container_name: traefik restart: unless-stopped security_opt: - no-new-privilegestrue networks: proxy: aliases: - auth.example.com authelia: {} ports: - 80:80 - 443:443 environment: TZ: America/Los_Angeles ## 时区见下方说明 volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./traefik/config/traefik.yml:/traefik.yml:ro - ./traefik/config/dynamic.yml:/dynamic.yml:ro - ./traefik/data/:/data - ./traefik/logs:/logs labels: traefik.enable: true traefik.http.routers.dashboard.rule: Host(traefik.example.com) traefik.http.routers.dashboard.entrypoints: https traefik.http.routers.dashboard.middlewares: autheliadocker traefik.http.routers.dashboard.service: apiinternal whoami: image: traefik/whoami restart: unless-stopped container_name: whoami labels: traefik.enable: true traefik.http.routers.whoami.rule: Host(whoami.example.com) traefik.http.routers.whoami.entrypoints: https networks: proxy: {} ## 其他服务在这里添加 networks: proxy: external: true name: proxy authelia: name: authelia几点说明traefik容器同时加入proxy与authelia两个网络proxy网络用于发现和路由各业务容器authelia网络用于与 Authelia 单独通信安全隔离见下文网络章节Traefik 挂载 Docker socket 以动态发现容器建议以:ro只读方式挂载时区字符串可参考 Go timezone 表也可根据你的部署位置替换为Asia/Shanghai等whoami是不受保护的测试服务用于验证 Traefik 基础路由是否正常。Traefik 基础配置静态配置## Traefik 基础配置 api: dashboard: true debug: false insecure: false log: level: INFO accessLog: filePath: /logs/access.log entryPoints: http: address: :80 http: redirections: entryPoint: to: https scheme: https permanent: true https: address: :443 http: tls: certResolver: myresolver providers: docker: endpoint: unix:///var/run/docker.sock exposedByDefault: false file: filename: /dynamic.yml certificatesResolvers: myresolver: acme: storage: /data/acme.json httpChallenge: entryPoint: http tls: options: default: minVersion: VersionTLS12 cipherSuites: - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305要点解析entryPoints.http将所有 80 端口请求永久 301 重定向到 HTTPSentryPoints.https挂载 ACME 证书解析器myresolverproviders.docker启用 Docker Provider 且exposedByDefault: false——只有显式打了traefik.enable: true标签的容器才会被路由这是推荐的安全默认providers.file加载/dynamic.yml即挂载的traefik/config/dynamic.yml用于放置动态路由/中间件配置certificatesResolvers.myresolver.acme使用 HTTP-01 挑战证书状态存于/data/acme.json需提前创建参见仓库 integration 文档中的 ACME 说明TLS 默认选项强制最低 TLS 1.2 并只启用现代 AEAD 密码套件AES-GCM / ChaCha20-Poly1305。域名动态配置## 此文件用于定义动态 routers/services/middlewares。动态文件初始为空即可——Traefik 的路由、中间件主要由 Docker 标签提供。以上均为聚焦 Authelia 集成的最小配置请结合 Traefik 官方文档按需调整。接入 Authelia 容器与 ForwardAuth 中间件以下服务定义应追加到前面创建的compose.yml中。它创建 Authelia 核心服务并通过 Traefik 暴露门户auth.example.com同时新增一个受 Authelia 保护的whoami-secure容器。authelia: image: authelia/authelia:4.38 container_name: authelia volumes: - ./authelia/secrets:/secrets:ro - ./authelia/config:/config - ./authelia/logs:/var/log/authelia/ networks: authelia: {} labels: ## 通过 Traefik 暴露 Authelia traefik.enable: true traefik.docker.network: authelia traefik.http.routers.authelia.rule: Host(auth.example.com) traefik.http.routers.authelia.entrypoints: https ## 配置 Authelia ForwardAuth 中间件 traefik.http.middlewares.authelia.forwardAuth.address: http://authelia:9091/api/authz/forward-auth traefik.http.middlewares.authelia.forwardAuth.trustForwardHeader: true traefik.http.middlewares.authelia.forwardAuth.maxResponseBodySize: 8192 traefik.http.middlewares.authelia.forwardAuth.authResponseHeaders: Remote-User,Remote-Groups,Remote-Name,Remote-Email environment: TZ: America/Los_Angeles X_AUTHELIA_CONFIG_FILTERS: template whoami-secure: image: traefik/whoami restart: unless-stopped container_name: whoami-secure labels: traefik.enable: true traefik.http.routers.whoami-secure.rule: Host(whoami-secure.example.com) traefik.http.routers.whoami-secure.entrypoints: https traefik.http.routers.whoami-secure.middlewares: autheliadocker networks: proxy: {}核心标签逐一说明traefik.http.routers.authelia.rule将auth.example.com路由到 Authelia 门户traefik.docker.network: authelia明确指定 Traefik 通过authelia网络访问 Authelia 容器traefik.http.middlewares.authelia.forwardAuth.address整个集成的核心——Traefik 将受保护请求转发给 Authelia 的http://authelia:9091/api/authz/forward-auth端点做鉴权。若你修改了容器名或端口此 URL 必须同步修改trustForwardHeader: true信任 Traefik 注入的X-Forwarded-*头ForwardAuth 实现依赖这些头获取请求元数据见下文原理章节maxResponseBodySize: 8192限制 Auth 响应体大小防止响应过大authResponseHeaders鉴权通过后Authelia 返回的用户身份信息用户名、组、显示名、邮箱由 Traefik 以Remote-User、Remote-Groups、Remote-Name、Remote-Email请求头转发给后端应用——这正是从源码 handleAuthzAuthorizedStandard 中可以看到的实际响应头实现X_AUTHELIA_CONFIG_FILTERS: template启用 Authelia 配置文件的模板渲染详见 Templating 参考指南使configuration.yml中的{{ secret ... }}等模板指令生效。官方参考指南中同样提到配置模板可以通过 authelia config template 命令或trace日志级别以 base64 输出渲染结果进行验证调试。whoami-secure通过traefik.http.routers.whoami-secure.middlewares: autheliadocker挂载认证中间件成为受保护的演示应用。Docker 网络规划需要或会自动创建两个网络它们承担不同的信任边界proxy 网络包含 Traefik用于把任意附加容器接入 Traefik 代理。该网络为外部网络需手动创建docker network create proxy \ --opt com.docker.network.bridge.namebr-docker-proxyauthelia 网络包含 Authelia 运行所需的容器并把 Authelia 与 Traefik 通过独立网络相连。本指南未涉及但该网络中通常会包含存储提供者PostgreSQL 或 MySQL、会话提供者Redis以及 LDAP 认证后端。该网络无需手动创建容器启动时会自动创建。注意whoami-secure虽然受 Authelia 中间件保护却不在authelia网络中——这是为了避免任何 HTTP 流量被截获的风险。受保护业务应位于proxy网络或与 Traefik 共享的网络而 Authelia 专用服务使用独立的authelia网络以获得更强的安全隔离。Authelia 核心配置逐项解析server: address: tcp4://:9091 log: level: debug file_path: /var/log/authelia/authelia.log keep_stdout: true identity_validation: elevated_session: require_second_factor: true reset_password: jwt_lifespan: 5 minutes jwt_secret: {{ secret /secrets/jwt_secret.txt | mindent 0 | | msquote }} totp: disable: false issuer: example.com period: 30 skew: 1 password_policy: zxcvbn: enabled: true min_score: 4 authentication_backend: file: path: /config/users.yml password: algorithm: argon2 argon2: variant: argon2id iterations: 3 memory: 65535 parallelism: 4 key_length: 32 salt_length: 16 access_control: default_policy: deny rules: - domain: traefik.example.com policy: one_factor - domain: whoami-secure.example.com policy: two_factor session: name: authelia_session secret: {{ secret /secrets/session_secret.txt | mindent 0 | | msquote }} cookies: - domain: example.com authelia_url: https://auth.example.com regulation: max_retries: 4 find_time: 120 ban_time: 300 storage: encryption_key: {{ secret /secrets/storage_encryption_key.txt | mindent 0 | | msquote }} local: path: /config/db.sqlite3 notifier: disable_startup_check: false filesystem: filename: /config/notification.txt各配置段说明本指南未涉及的选项请查阅官方配置文档serverServer 配置设置监听地址为tcp4://:9091端口与 ForwardAuth 中间件中的地址必须一致logLogging 配置级别设为debug便于排查同时写文件并保留标准输出容器日志identity_validationIdentity Validation 配置启用提升会话需二次验证重置密码的 JWT 有效期 5 分钟其jwt_secret通过模板指令从密钥文件读取totpTOTP 配置启用 TOTP 二次验证issuer 为example.com30 秒周期、允许 1 个时间窗口偏差password_policyPassword Policy 配置启用 zxcvbn 密码强度评估并要求最低得分 4满分 4即要求强密码authentication_backend使用文件认证后端/config/users.yml密码哈希算法为argon2id迭代 3 次、内存 64 MiB、并行度 4、密钥长 32 字节、盐长 16 字节access_controlAccess Control 配置default_policy: deny为安全默认——未命中任何规则的请求一律拒绝规则按顺序匹配rule 的匹配条件同时满足才命中traefik.example.com只需一次因子one_factorwhoami-secure.example.com需要二次因子two_factor。该配置段不适用于 OpenID Connect 1.0 场景详见官方 FAQsessionSession 配置会话 Cookie 名authelia_sessionsecret从密钥文件读取现代配置将domain与authelia_url作为session.cookies列表项的子键authelia_url: https://auth.example.com用于门户跳转旧版配置为顶层default_redirection_urlsession.domain官方 Traefik 集成文档 提供了两种形态对比regulationRegulation 配置暴力破解防护——120 秒内最多 4 次失败超限封禁 300 秒storageStorage 配置encryption_key从密钥文件读取本地存储使用 SQLite/config/db.sqlite3。生产环境可替换为 MySQL / PostgreSQL会话可改用 Redis见文末下一步notifierNotifier 配置文件通知器把邮件内容写入/config/notification.txt——适合测试环境例如注册 TOTP/WebAuthn 时接收验证链接生产应改用 SMTP。密钥文件与模板指令配置中{{ }}包裹的是 Go 模板启动时会被指定文件的内容替换需配合环境变量X_AUTHELIA_CONFIG_FILTERS: template开启详见 Templating 参考指南。其中secret函数用于读取文件内容并去除尾部换行mindent 0 |与msquote用于保证多行内容以正确的 YAML 块标量|呈现、单行内容以单引号包裹避免密钥中含特殊字符时破坏 YAML 结构。需要在authelia/secrets/目录创建 3 个必需密钥文件jwt_secret.txt重置密码 JWT 签名密钥storage_encryption_key.txt存储加密密钥session_secret.txt会话加密密钥在项目根目录project/下依次执行以下命令完成权限设置与自动生成chown 8000:8000 ./authelia/secrets chmod 0700 ./authelia/secretsdocker run --rm -u 8000:8000 -v ./authelia/secrets:/secrets docker.io/authelia/authelia sh -c cd /secrets authelia crypto rand --length 64 session_secret.txt storage_encryption_key.txt jwt_secret.txt说明容器默认以 UID/GID 8000authelia用户运行因此密钥目录需归属8000:8000并设为0700否则容器内无法读取第二条命令以 UID 8000 启动一次性容器在/secrets目录内调用authelia crypto rand --length 64生成 3 个 64 字符随机字符串文件参见 Generating Secure Values 参考指南如果自行生成强烈建议这 3 个值使用 64 字符及以上的随机字母数字字符串authelia crypto rand --length 64 --charset alphanumeric是官方推荐的生成方式。关于容器权限官方 Docker 部署文档 还记录了PUID/PGID/UMASK三个容器环境变量——当容器以 UID 0 启动时entrypoint 会降权到PUID/PGID并自动修正文件属主而本指南采用-u 8000:8000的方式直接以非特权用户运行需要手动保证文件系统权限正确两种方式可任选其一。用户数据库users: authelia: ## 用户名 displayname: Authelia User ## 警告以下为仅供测试的默认密码 ## 重要生产部署前必须修改该密码 ## 使用以下指引生成新的密码哈希 ## https://www.authelia.com/reference/guides/passwords/#passwords ## 当前密码是 authelia password: $6$rounds50000$BpLnfgDsc2WD8F2q$Zis.ixdg9s/UOJYrs56b5QEZFiZECu0qZVNsIYxBaNJ7ucIL.nlxVCT5tqh8KHG8X4tlwCFm5r6NTOZZ5qRFN/ email: autheliaauthelia.com groups: - admin - dev当前示例密码为authelia仅用于测试正式部署前必须按 Passwords 参考指南 重新生成哈希推荐使用 Authelia 自带命令生成随机密码及哈希参考 Generating Secure Valuesdocker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --random --random.length 64 --random.charset alphanumeric文件认证后端完整选项argon2id 参数、密码哈希算法等参见 First Factor 配置。启动、验证与排错启动整个栈所有 Traefik、Authelia 及业务容器配置完成后在project/目录执行docker compose up -dCompose 会拉取镜像并启动全部容器authelia网络会自动创建。验证安装查看容器状态docker compose ps访问 Traefik 仪表盘https://traefik.example.com需先通过一次因子认证测试认证流程访问https://whoami-secure.example.com未登录时应被重定向到https://auth.example.com门户完成 two_factor 认证用户名/密码 TOTP后可访问。常见问题排查查看容器日志docker logs authelia确认 3 个密钥文件均存在且权限正确目录0700、属主8000:8000若 Traefik 报middleware autheliadocker not found当 Traefik 与 Authelia 分属不同 Compose 栈时可能出现该错误可通过depends_on确保 Authelia 先于 Traefik 启动或在 Traefik 容器上直接定义 ForwardAuth 中间件标签解决参见 Traefik 集成文档 FAQ。ForwardAuth 鉴权原理源码视角了解 Traefik 集成背后的机制有助于排查为什么某个请求被放行/拒绝。Authelia 的 ForwardAuth 实现在internal/handlers/handler_authz_impl_forwardauth.go中它从请求头中读取元数据并构造鉴权对象——请求方法取自X-Forwarded-Method协议、主机、路径分别取自X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-URI这些正是 Proxy Authorization 参考指南 中 ForwardAuth 实现所要求的元数据方法/协议/主机/路径/IP/门户 URL也是 Traefik 中间件必须设置trustForwardHeader: true的原因。而门户 URL默认取自会话 Cookie 配置中的authelia_url也可通过查询参数覆盖。鉴权完成后参见 handler_authz_common.go授权成功返回 200并写入Remote-User、Remote-Groups、Remote-Name、Remote-Email响应头对应中间件中的authResponseHeaders未授权对普通浏览器请求返回 302/303 重定向到门户handleAuthzRedirectStatusCode会根据请求方法选择 302 或 303HEAD 请求重定向不带响应体对 XHR 或非 HTML 请求返回 401——这正是页面访问跳转门户、API 请求直接 401行为的源码出处。从源码结构还可以推断受保护请求会按顺序执行多种认证策略会话 Cookie、Authorization 头等最终由访问控制规则决定是否放行这也解释了为何 Traefik 仪表盘traefik.example.com配置 one_factor 而业务站点whoami-secure.example.com配置 two_factor 即可实现差异化保护。下一步扩展方向本指南未覆盖 Authelia 的全部能力以下官方文档可作为后续深入的方向OpenID Connect 1.0Provider 配置让支持 OIDC 的应用直接对接 Authelia 完成认证无需反向代理参与外部数据库Storage 配置除 SQLite 外支持 MySQL、PostgreSQL适合多副本/高可用部署非内存会话存储Session 配置默认内存会话在 Authelia 重启后会全部失效、用户需重新认证接入 Redis 后会话可跨重启持久化并使 Authelia 完全无状态化指标监控Metrics 参考指南 与 Telemetry 配置导出安装实例的各项统计指标便于接入 Prometheus/Grafana生产化改造将文件通知器替换为 SMTP、收紧log.level、为 Authelia 自身启用 TLS 客户端证书双向认证Traefik YAML 集成示例见 Traefik 集成文档其中展示了通过serversTransports 客户端证书确保只有受信代理能访问 Authelia 的加固方案并定期按 Validating Forwarded Authentication 指南 校验转发认证的安全性。至此你已经拥有了一套由 Traefik 统一入口、Authelia 集中鉴权的单点登录多因子认证架构一条 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考