企业官网建设流程全解析

Authelia 反向代理集成改配置后如何执行转发认证验证步骤

【免费下载链接】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、Caddy、HAProxy、NGINX、Envoy 等）以转发认证方式保护 Web 应用。一旦你修改了与 Authelia 相关的代理配置，就应当按 Validating Forwarded Authentication 参考指南重新走一遍验证，确认集成仍然按预期工作。本文给出验证的前提检查、两个验证步骤（通用运行验证和 networks 访问控制规则验证）、判断依据与测试后清理动作，适用环境是任何已将 Authelia 接入反向代理的部署。

哪些改动之后必须执行验证

指南明确列出应验证配置的以下场景：

1. 初始配置完成后；
2. 修改了 Authelia 或相关集成 URL 的代理配置后；
3. 修改了 server address 的值之后；
4. 修改了某个使用该集成的应用的代理配置后；
5. 修改了 Authelia 的访问控制规则后。

此外指南建议升级反向代理时也要抽时间验证一次：代理升级可能引入 bug、改变集成相关行为，或者删除/改动了原有配置，从而导致认证失败。

准备：选定应用并核对头部要求

选定要验证的应用

选一个满足以下三个条件的应用：

1. 使用了该转发认证集成；
2. 需要认证才能访问；
3. 是你本次想要验证的对象。

后续两个验证步骤都围绕这个应用展开。

确认代理已转发必需头部

Authelia 依赖反向代理设置的X-Forwarded-*系列头部来识别请求信息。根据 Proxies 集成文档，Authelia 门户本身要求代理至少设置以下头部（含各自的回退来源）：

• Scheme Detection：默认X-Forwarded-Proto，回退为 TLS 监听状态；
• Host Detection：默认X-Forwarded-Host，回退为Host；
• Path Detection：默认X-Forwarded-URI，回退为请求起始行；
• Remote IP：默认X-Forwarded-For，回退为 TCP 源 IP。

缺少这些头部会导致访问控制、会话 Cookie 域、重定向、OpenID Connect、WebAuthn 等功能无法正确识别请求信息。authz 端点（/api/authz/forward-auth、/api/authz/ext-authz、/api/authz/auth-request、/api/verify）依赖的具体头部因实现而异，详见 Proxy Authorization 参考。

子路径部署注意

如果通过 serveraddress（或已废弃的path选项）把 Authelia 配置在子路径上，指南强烈建议：配置/api/authz/*或/api/verify端点时，URL 中不要包含所配置的路径。因为 handler 会同时监听根路径和所配置路径，这样做可以规避多种误配置问题。另外 server address 文档说明：当路径不是/时（例如tcp://:9091/authelia），请求会同时由/和/authelia/处理。修改该值之后属于上面第 3 类场景，必须执行本验证。

步骤一：验证通用运行

这一步对所有用户都很重要。

1. 确保你已退出（logged out）Authelia 本身的登录状态。
2. 访问你选定的应用，确认两件事：
   • 请求被重定向到 Authelia 登录门户；
   • 你被要求执行预期级别的认证（例如 one_factor 或 two_factor，取决于访问控制规则对该应用的策略）。

如果直接进入了应用内容而没有跳转登录门户，说明认证链路已断，需要回头检查代理到 authz 端点的配置。

步骤二：验证 networks 访问控制规则（可选）

如果你使用了访问控制规则中的 networks 条件，这一步是必需的。networks 条件依赖X-Forwarded-For头部的真实性：如果代理随意信任客户端伪造的X-Forwarded-For，攻击者可以借此命中含 networks 条件的规则并绕过认证，详见 Forwarded Headers。

添加一条临时访问控制规则

假设你选定的应用位于app.example.com域（下文中app.example.com为文档示例域名，请替换为你的实际应用域名），在 Authelia 访问控制规则的最顶部添加：

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

发送测试请求

对应用发起带伪造X-Forwarded-For的请求（文档中的示例命令，URL 需替换为你的实际应用地址）：

curl -i -H 'X-Forwarded-For: 169.254.1.2' https://app.example.com

判断结果

响应应类似下面的文档示例（示例输出，域名、时间、Cookie 值以你的实际环境为准）：

HTTP/2 302 alt-svc: h3=":443"; ma=2592000 content-type: text/html; charset=utf-8 date: Sat, 21 Mar 2026 04:35:35 GMT location: https://auth.example.com/?rd=https%3A%2F%2Fapp.example.com%2F&rm=GET permissions-policy: accelerometer=(), autoplay=(), camera=(), display-capture=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), screen-wake-lock=(), sync-xhr=(), xr-spatial-tracking=(), interest-cohort=() referrer-policy: strict-origin-when-cross-origin set-cookie: authelia-session=Zdlhz6#ZTKPg5MOul3!TRLWv4sb$RznL; expires=Sat, 21 Mar 2026 05:35:36 GMT; domain=example.com; path=/; HttpOnly; secure; SameSite=Lax x-content-type-options: nosniff x-dns-prefetch-control: off x-frame-options: DENY content-length: 119 <a href="https://auth.example.com/?rd=https%3A%2F%2Fapp.example.com%2F&amp;rm=GET">302 Found</a>

判断标准：第一行是302、最后一行是302 Found，即请求被重定向去认证，说明代理没有采纳伪造的X-Forwarded-For，临时 bypass 规则未命中，该来源是可信的。

删除临时规则

验证完成后，把第 1 小步添加的规则从访问控制规则中移除，避免测试规则残留在生产配置里。

响应状态速查

Proxies 集成文档 说明了 Authelia 在授权策略判定下的各类响应，验证时可据此核对行为：

限制与注意

• X-Forwarded-*头部必须来自可信来源。若前面还有云代理（如 Cloudflare），需确保云代理会剥离不可信客户端发送的X-Forwarded-For，或自行配置规则处理，否则客户端可伪造远程 IP；详见 Forwarded Headers 中针对 Cloudflare 的方法说明。
• 步骤二只针对使用networks条件的用户；不使用该条件时完成步骤一即可。
• 步骤二会临时修改访问控制规则，测试用的 bypass 规则务必在验证后立即删除。
• 步骤二的示例配置、示例域名与示例输出均来自文档示例，实际执行时请替换为你自己的应用域名与地址，并以302/302 Found这一判断标准为准，而不是比对示例中的时间、Cookie 等具体值。

完成以上验证后，若通用运行验证未出现预期重定向，或 networks 验证未返回302，回到代理侧核对 authz 端点 URL 与X-Forwarded-*头部配置；各代理的具体集成写法见 integration/proxies 下对应代理的文档。

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