Authelia 与 Envoy 反向代理集成实战指南：基于 ExtAuthz 的外部授权配置

Authelia 与 Envoy 反向代理集成实战指南基于 ExtAuthz 的外部授权配置【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 官方支持以 Envoy 官方集成指南结合 Authelia 源码与相关配置文档完整讲解从环境假设、端点配置、Session 配置到 Envoy 静态配置compose 编排 envoy.yaml的落地步骤并给出可信代理、转发头安全与结果验证的实操指引。集成概览Authelia 如何与 Envoy 协同Envoy 与 Authelia 的集成走的是ExtAuthz 授权实现External Authorization。根据 Proxy Authorization 参考文档 中的默认端点表/api/authz/ext-authz端点默认启用ExtAuthz实现并支持HeaderAuthorization与CookieSession两种认证策略Authn Strategies端点名称路径实现认证策略ext-authz/api/authz/ext-authzExtAuthzHeaderAuthorization、CookieSession该端点从请求中收集两类信息来完成判定请求元数据Method、Scheme、Hostname、Path、IP、Authelia URL用于资源与访问控制的匹配用户身份则由认证策略确定。从源码结构看Authelia 通过 handler_authz_impl_extauthz.go 中的handleAuthzGetObjectExtAuthz函数将请求的 Method、X-Forwarded-Proto、Host、以及端点子路径组合成authorization.Object交给授权引擎判定可见 ExtAuthz 实现对应的元数据来源正是 Envoy 过滤器需要正确透传的那些请求信息。重要官方指南明确指出它无法为每一种代理部署方式提供示例给出的配置是建议性方案你需要理解 Envoy 配置并根据自身架构调整。文末的 See Also 与正文各处均引用了 Envoy 官方文档供深入学习。开始前的必读准备官方强烈建议首次部署 Authelia 的用户先阅读 Get started 指南它涵盖了引导 Authelia 启动所必需的步骤。同时在阅读本集成配置前请先阅读 Forwarded Headers 一节——X-Forwarded-*系列头必须来自可信来源反向代理必须移除并替换由客户端直接携带的这些头否则可能造成安全隐患。此外本集成还涉及一条安全红线安全提示除了阅读本节内容你还应阅读 Validating Forwarded Authentication 参考指南并将其中描述的验证步骤纳入使用本集成时的常规安全验证流程。可信代理与集成安全在配置任何代理集成时可信代理Trusted Proxies的界定是核心安全前提官方示例不适用于生产环境它只是用来演示如何配置多个 IP 段。你应该根据自身架构定制只把架构中真实的代理 IP 段加入可信范围除非某个子网内只有可信代理且没有其他服务否则不要信任整个子网。信任范围直接关系到 访问控制规则 中networks网络条件的安全性——该条件依赖X-Forwarded-For头来还原客户端真实 IP。如果非可信代理也能伪造该头攻击者就可能绕过按网络限定的认证条件。关于云代理如 Cloudflare场景下的头清理与信任配置可参阅 Forwarded Headers 文档。环境假设与适配说明官方示例基于以下部署假设高级复杂场景需要你自行适配部署形态单主机Authelia 以容器方式部署容器名为authelia端口9091代理容器与 Authelia 位于同一 Docker 网络。因此代理访问 Authelia 的地址默认为http://authelia:9091需要按以下规则替换若 Authelia 配置了 TLS 证书将 URL 全部改为https://容器名不同或代理部署位置不同时替换 URL 中的authelia修改了默认端口时替换 URL 中的9091Authelia 与代理不在同一主机时替换整个 URL。所有服务都属于example.com域名示例中的域名与子域名需替换为你自己的域名仅测试或确需使用该域名时除外。前置配置Authz 端点与 Session1. 启用 ExtAuthz 端点示例假定你使用默认的 Authz 端点配置 或与其等价的最小化配置server: endpoints: authz: ext-authz: implementation: ExtAuthz该配置将/api/authz/ext-authz端点绑定到ExtAuthz实现。根据 server-endpoints-authz 配置文档端点名称同时决定了路径所有端点以/api/authz/开头implementation的合法取值为ForwardAuth、ExtAuthz、AuthRequest、Legacy大小写敏感并可进一步通过authn_strategies列表按顺序声明认证策略例如server: endpoints: authz: ext-authz: implementation: ExtAuthz authn_strategies: - name: HeaderAuthorization schemes: - Basic scheme_basic_cache_lifespan: 0 - name: CookieSession其中schemes可选Basic与Bearerscheme_basic_cache_lifespan默认 0 秒即默认不缓存 Basic 用户名/密码组合。2. 现代 Session 配置推荐示例假定你使用包含domain、authelia_url、default_redirection_url子键的现代 Session 配置。下方同时给出现代与遗留Legacy两种写法现代配置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官方特别建议Authelia 在代理中的 URLauthelia_url优先在 Session Cookies 配置中声明而不是通过 Envoy 的X-Authelia-URL请求头注入后者在示例中仅以注释形式出现。Session 配置的完整说明见 Session Introduction。Envoy 集成示例配置支持 Envoy 需要Authelia v4.37.0 及以上版本通过 Envoy 的 external authorization 过滤器 实现。以下给出两个文件的完整示例容器编排compose.yml与 Envoy 静态配置envoy.yaml。Docker Compose 编排示例部署三个服务Envoy入口代理、Authelia认证门户、Nextcloud受保护后端networks: net: driver: bridge services: envoy: container_name: envoy image: envoyproxy/envoy:v1.24 restart: unless-stopped networks: net: {} ports: - 80:8080 - 443:8443 volumes: - ${PWD}/data/envoy/envoy.yaml:/etc/envoy/envoy.yaml - ${PWD}/data/certificates:/certificates authelia: container_name: authelia image: authelia/authelia restart: unless-stopped networks: net: {} volumes: - ${PWD}/data/authelia/config:/config environment: TZ: Australia/Melbourne nextcloud: container_name: nextcloud image: linuxserver/nextcloud restart: unless-stopped networks: net: {} volumes: - ${PWD}/data/nextcloud/config:/config - ${PWD}/data/nextcloud/data:/data environment: PUID: 1000 PGID: 1000 TZ: Australia/MelbourneEnvoy 静态配置envoy.yaml以下是完整的 Envoy 配置包含 HTTP 重定向监听器、HTTPS 监听器集成 ext_authz 过滤器、两个上游集群nextcloud 与 authelia以及运行时资源限制static_resources: listeners: - name: listener_http address: socket_address: address: 0.0.0.0 port_value: 8080 filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: type: type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager codec_type: auto stat_prefix: ingress_http route_config: name: local_route virtual_hosts: - name: backend domains: [*] routes: - match: prefix: / redirect: https_redirect: true http_filters: - name: envoy.filters.http.router typed_config: type: type.googleapis.com/envoy.extensions.filters.http.router.v3.Router - name: listener_https address: socket_address: address: 0.0.0.0 port_value: 8443 filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: type: type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager stat_prefix: ingress_http use_remote_address: true skip_xff_append: false route_config: name: local_route virtual_hosts: - name: whoami_service domains: [nextcloud.example.com] routes: - match: prefix: / route: cluster: nextcloud - name: authelia_service domains: [auth.example.com] typed_per_filter_config: envoy.filters.http.ext_authz: type: type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute disabled: true routes: - match: prefix: / route: cluster: authelia http_filters: - name: envoy.filters.http.ext_authz typed_config: type: type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz transport_api_version: v3 allowed_headers: patterns: - exact: authorization - exact: proxy-authorization - exact: accept - exact: cookie - exact: location http_service: path_prefix: /api/authz/ext-authz/ server_uri: uri: authelia:9091 cluster: authelia timeout: 0.25s authorization_request: allowed_headers: patterns: - exact: authorization - exact: proxy-authorization - exact: accept - exact: cookie - exact: location headers_to_add: - key: X-Forwarded-Proto value: %REQ(:SCHEME)% ## 以下注释行用于在代理中配置 Authelia URL。 ## 官方强烈建议在 Authelia 配置的 Session Cookies 部分配置该项。 # - key: X-Authelia-URL # value: https://auth.example.com authorization_response: allowed_upstream_headers: patterns: - prefix: remote- - prefix: authelia- allowed_client_headers: patterns: - exact: set-cookie allowed_client_headers_on_success: patterns: - exact: set-cookie failure_mode_allow: false - name: envoy.filters.http.router typed_config: type: type.googleapis.com/envoy.extensions.filters.http.router.v3.Router clusters: - name: nextcloud connect_timeout: 0.25s type: logical_dns dns_lookup_family: v4_only lb_policy: round_robin load_assignment: cluster_name: nextcloud endpoints: - lb_endpoints: - endpoint: address: socket_address: address: nextcloud port_value: 80 - name: authelia connect_timeout: 0.25s type: logical_dns dns_lookup_family: v4_only lb_policy: round_robin load_assignment: cluster_name: authelia endpoints: - lb_endpoints: - endpoint: address: socket_address: address: authelia port_value: 9091 layered_runtime: layers: - name: static_layer_0 static_layer: envoy: resource_limits: listener: example_listener_name: connection_limit: 10000 overload: global_downstream_max_connections: 50000配置要点逐项拆解1. 两个监听器分工listener_http8080接收 HTTP 流量并全部https_redirect重定向到 HTTPS保证认证链路强制走 TLS。listener_https8443真正的业务入口。use_remote_address: true表示使用对端真实地址skip_xff_append: false表示 Envoy 会追加X-Forwarded-For这两项直接关系到 Authelia 能否拿到准确的客户端 IP。2. Virtual Host 与按路由禁用认证nextcloud.example.com走nextcloud集群由全局 ext_authz 过滤器保护auth.example.comAuthelia 门户自身通过typed_per_filter_config中的ExtAuthzPerRoute将disabled设为true按路由禁用外部授权避免认证门户自我认证造成死循环。3. ExtAuthz 过滤器核心配置path_prefix: /api/authz/ext-authz/指向 Authelia 的 ExtAuthz 端点server_uri.uri: authelia:9091与 compose 中 Authelia 容器名、端口对应需按你的环境假设替换authorization_request.allowed_headers仅允许透传authorization、proxy-authorization、accept、cookie、location五个请求头给 Authelia这是两个认证策略Header 头认证与 CookieSession所需的元数据headers_to_add注入X-Forwarded-Proto取自%REQ(:SCHEME)%动态值补全 Scheme 元数据authorization_response.allowed_upstream_headers允许remote-与authelia-前缀的响应头回传给上游后端应用用于 Trusted Header SSO 场景allowed_client_headers与allowed_client_headers_on_success允许set-cookie响应头返回给客户端确保认证成功后 Session Cookie 能被浏览器正确写入后者限定仅在授权成功时下发failure_mode_allow: falseExtAuthz 服务不可用时拒绝请求fail-closed这是安全默认值。4. 集群与运行时nextcloud与authelia两个集群均使用logical_dns、v4_only、round_robin通过 Docker 网络内的容器名解析layered_runtime设置了监听器连接数上限10000与全局下游最大连接数50000可根据容量调整或移除。ExtAuthz 元数据请求信息如何传递Envoy 场景下Authelia 判定授权所需的元数据来源如下详见 Proxy Authorization 参考文档元数据来源键MethodHTTP 起始行HTTP 方法Scheme请求头X-Forwarded-ProtoHostname请求头HostPath请求头端点子路径IP请求头X-Forwarded-ForAuthelia URLSession Cookie 配置authelia_url备选来源Fallback/Override元数据类型来源键SchemeFallback请求头服务器 SchemeIPFallbackTCP 报文源 IPAuthelia URLOverride请求头X-Authelia-URL注意区分两类备选Fallback仅在主来源与覆盖值完全未设置时生效Override会优先于元数据主来源。authelia_url既可在 Session Cookie 配置中声明也可通过X-Authelia-URL头覆盖但官方推荐前者。这解释了示例中为何headers_to_add里的X-Authelia-URL被注释——正常情况下无需在 Envoy 层注入。Kubernetes 生态Authelia 还支持多种基于 Envoy 的 Kubernetes Ingress 方案例如 Envoy Gateway 与 Istio。完整列表见 Kubernetes Envoy 集成指南。验证集成是否生效完成配置后请务必执行 Validating Forwarded Authentication 中的验证流程重点覆盖以下时机完成初始配置后修改了代理中与 Authelia 相关的配置或集成 URL 后修改了 server address 后修改了使用该集成的应用的代理配置后修改了 Authelia 访问控制规则后升级代理后代理缺陷、行为变化或升级覆盖配置都可能引入故障。通用运行验证登出 Authelia 后访问受保护应用确认被重定向到 Authelia 登录门户并按要求完成对应等级的认证。网络访问控制验证若使用networks条件则必须执行在访问控制规则最顶部临时加入一条针对app.example.com、networks: [169.254.1.2]、policy: bypass的规则然后执行curl -i -H X-Forwarded-For: 169.254.1.2 https://app.example.com若代理未盲目信任X-Forwarded-For响应应为302重定向到登录门户如location: https://auth.example.com/?rd...rmGET。验证完成后务必移除该临时规则。常见问题与排查方向认证门户自身无法打开检查authelia_service虚拟主机的ExtAuthzPerRoute.disabled: true是否配置正确否则 ext_authz 过滤器会对门户请求自身发起认证形成循环。无法重定向到门户确认authorization_request.allowed_headers包含cookie且authorization_response允许set-cookie返回客户端同时确认 Session 配置中的authelia_url正确。客户端 IP 不准确 / 访问控制 network 规则失效检查use_remote_address、skip_xff_append以及可信代理配置确保X-Forwarded-For只来自可信来源见 Forwarded Headers。上游拿不到用户信息确认authorization_response.allowed_upstream_headers中的remote-/authelia-前缀规则与 Trusted Header SSO 要求的头一致。超时或失败server_uri.timeout: 0.25s较激进若 Authelia 响应较慢可适当调大failure_mode_allow: false下任何 ext_authz 调用失败都会直接拒绝请求。See AlsoEnvoy 外部授权过滤器官方文档Forwarded HeadersProxy Authorization 参考指南Server Authz Endpoints 配置Validating Forwarded AuthenticationKubernetes Envoy 集成【免费下载链接】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），仅供参考