Authelia 与 Kubernetes Envoy Gateway 集成实战指南基于 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 作为面向 Web 应用的单点登录与多因素认证门户在 Kubernetes 场景下可以借助 Envoy Gateway一个 Gateway API 实现完成统一认证接入。本篇技术指南以 gateway.md 为核心骨架讲解如何在 Envoy Gateway 上通过 Envoy 的 external authorizationExtAuthz过滤器将流量转发给 Authelia 鉴权并给出可直接落地的 SecurityPolicy、HTTPRoute 与 ReferenceGrant 清单。读完本文你将掌握两种作用域单 Gateway、单 HTTPRoute的鉴权策略配置方法、Authelia 侧ext-authz端点的底层实现原理以及跨命名空间引用所需的 ReferenceGrant 规则。集成原理与适用版本Envoy Gateway 是 Gateway API 的官方参考实现因此它对 Gateway API 资源Gateway、HTTPRoute、ReferenceGrant等有相对完整、规范的集成支持。Authelia 从v4.37.0 起支持与 Envoy Gateway 集成其底层依赖的是 Envoy 代理的 external authorizationExtAuthzHTTP 过滤器Envoy 在转发上游请求之前先把请求发给 Authelia 的鉴权端点由 Authelia 判断请求是否被允许再决定放行、重定向或拒绝。该机制在 Authelia 内部对应 proxy-authorization 参考指南 中定义的ExtAuthz实现默认端点路径为/api/authz/ext-authz。由于 Authelia 与 Envoy 通过标准 HTTP 头交换元数据这一方案具有天然的跨实现通用性——事实上同一套 ExtAuthz 实现也支撑了 Envoy 反向代理非 Kubernetes集成以及同为 Envoy 系 Kubernetes 入口的 Istio完整列表见 Kubernetes Envoy 集成总览。如果你希望把 ID Token 或 Access Token 共享给后端应用例如后端需要读取用户身份令牌还可以选择 OpenID Connect 1.0 方案进行集成见 Envoy Gateway OIDC 客户端集成官方文档原链接位于../../openid-connect/envoy-gateway/仓库中实际以该路径的 alias 形式存在。重要提示官方文档强调这些集成指南展示的是一种推荐配置而非适用于所有部署形态的万能模板。你需要理解 Envoy Gateway 的配置语义并结合自身架构命名空间、Service 名称、端口、域名做适配。开始前的准备首次搭建 Authelia 的用户强烈建议先阅读官方 Get started快速入门 指南。该指南覆盖了引导 Authelia 所必需的关键步骤基础配置、用户存储、会话与身份验证提供方等是完成本集成的前提。此外本文中的部分示例值如auth.example.com中的域名与子域在官方文档站上可通过文档变量sitevar自动替换。在本仓库的 Markdown 源文件中这些值以{{ sitevar ... }}短代码形式呈现实际部署时请替换为你的真实域名。在动手配置 Envoy Gateway 之前还应确认 Authelia 侧已正确开启并暴露ext-authz鉴权端点。从源码看ExtAuthz 请求处理器 会基于请求的 Method、X-Forwarded-Proto头、Host 头、端点子路径等构造授权对象authorization.NewObjectMethodSchemeHostPath再交由访问控制决策。因此代理侧必须把这些元数据正确传递到 Authelia。默认配置下端点路径为/api/authz/ext-authz如需显式声明或调整可参考 Server Authz Endpoints 配置文档server: endpoints: authz: ext-authz: implementation: ExtAuthz部署假设本文示例假定你已经完成以下部署Authelia 以 Pod 形式部署并通过 URLhttps://auth.example.com即{{ sitevar namesubdomain-authelia nojsauth }}.{{ sitevar namedomain nojsexample.com }}对外提供服务在default命名空间中存在名为authelia的 Kubernetes Service其 TCP 端口80转发到 Authelia Pod 的 HTTP 端口集群使用默认 DNS 域名cluster.local。Envoy Gateway 侧的 SecurityPolicy 正是基于“Service 名 命名空间 端口”来定位 Authelia 后端的因此以上三项假设必须与实际集群一致否则需相应调整清单中的backendRefs。方式一使用 SecurityPolicy 接入 ExtAuthz 鉴权Envoy Gateway 通过gateway.envoyproxy.io/v1alpha1的SecurityPolicy资源表达安全策略。下面给出两种作用域的完整清单均直接复用了官方文档的示例。作用域一绑定到单个 Gateway以下 SecurityPolicy 将鉴权策略绑定到名为eg的单个 Gateway 上意味着该 Gateway 下所有流量都要经过 Authelia 鉴权--- apiVersion: gateway.envoyproxy.io/v1alpha1 kind: SecurityPolicy metadata: name: authelia-extauthz-by-gateway spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: eg extAuth: headersToExtAuth: - accept - cookie - location - authorization - proxy-authorization - x-forwarded-proto failOpen: false http: backendRefs: - name: authelia namespace: default port: 80 path: /api/authz/ext-authz/ headersToBackend: - Remote-User - Remote-Groups - Remote-Name - Remote-Email作用域二绑定到单个 HTTPRoute以下 SecurityPolicy 仅对名为example的单个 HTTPRoute 生效适合“同一 Gateway 下部分路由受保护、部分路由放行”的精细化场景--- apiVersion: gateway.envoyproxy.io/v1alpha1 kind: SecurityPolicy metadata: name: authelia-extauthz-by-route spec: targetRefs: - group: gateway.networking.k8s.io kind: HTTPRoute name: example extAuth: headersToExtAuth: - accept - cookie - authorization - proxy-authorization - x-forwarded-proto failOpen: false http: backendRefs: - name: authelia namespace: default port: 80 path: /api/authz/ext-authz/ headersToBackend: - Remote-User - Remote-Groups - Remote-Name - Remote-Email对应的 HTTPRoute被上述 SecurityPolicy 保护的应用路由定义如下此处为app.example.com域名的示例应用--- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: example spec: parentRefs: - name: eg hostnames: - app.example.com rules: - matches: - path: type: PathPrefix value: / backendRefs: - name: app port: 80清单要点解析对照官方文档与仓库源码以下配置项值得重点关注headersToExtAuth转发给 Authelia 的请求头Envoy 只会把这里列出的请求头转发给 Authelia 鉴权服务。cookie用于携带会话 Cookie 交给 Authelia 的 CookieSession 认证策略authorization/proxy-authorization用于 HeaderAuthorization / HeaderProxyAuthorization 认证策略location与accept服务于认证成功后的重定向与内容协商x-forwarded-proto则是 ExtAuthz 实现必需的元数据来源之一。failOpen: false当 Authelia 不可达或返回错误时Envoy 将拒绝请求fail-closed而不是放行fail-open。从安全角度这是推荐值避免“认证服务挂了反而绕过鉴权”。http.path指向 Authelia 的鉴权端点/api/authz/ext-authz/与 Authelia 默认端点路径一致。该路径在 Envoy 侧同时承担了 ExtAuthz 元数据中Path端点子路径的职责。headersToBackend回注给上游应用的响应头Remote-User、Remote-Groups、Remote-Name、Remote-Email是 Authelia 在鉴权成功后注入的标识头。这些常量在 handlers/const.go 中有明确定义后台应用可以据此识别当前登录用户及其所属分组。跨命名空间引用ReferenceGrantGateway API 遵循“显式授权”的跨命名空间引用模型。当 Envoy Gateway 部署在eg命名空间、而 Authelia 的 Service 位于default命名空间时SecurityPolicy 对 Authelia Service 的引用默认是不被允许的必须通过ReferenceGrant显式放行。以下示例假设Authelia 部署在default命名空间你已将上述 作用域一Scoped to Gateway 的 SecurityPolicy 部署到eg命名空间即名为authelia-extauthz-by-gateway的策略。--- apiVersion: gateway.networking.k8s.io/v1beta1 kind: ReferenceGrant metadata: name: example-ref-authelia-svc namespace: default spec: from: - group: gateway.envoyproxy.io kind: SecurityPolicy namespace: eg name: authelia-extauthz-by-gateway to: - group: kind: Service name: authelia注意该清单中的三个关键字段metadata.namespace: defaultReferenceGrant 必须与被引用目标Authelia Service同命名空间spec.from声明“谁”被允许引用——这里是eg命名空间中名为authelia-extauthz-by-gateway的 SecurityPolicyspec.to声明“引用什么”——即default命名空间中的autheliaService。如果 SecurityPolicy 的命名空间与名称与你的实际部署不同请同步修改spec.from中的namespace与name否则引用会被 Gateway API 控制器拒绝。底层实现ExtAuthz 端点的元数据与认证策略要理解为何上述清单中的头必须被转发需要回到 Authelia 的 ExtAuthz 实现细节。根据 proxy-authorization 参考指南ExtAuthz 端点收集以下必需元数据元数据来源键/位置Method请求起始行HTTP 方法Scheme请求头X-Forwarded-ProtoHostname请求头HostPath请求头端点子路径IP请求头X-Forwarded-ForAuthelia URL会话 Cookie 配置authelia_url其中 Scheme 的兜底来源是服务端 SchemeIP 的兜底来源是 TCP 源地址而 Authelia URL 可通过X-Authelia-URL请求头覆盖。这解释了为什么x-forwarded-proto必须出现在headersToExtAuth中——缺少它将导致 Scheme 元数据缺失进而影响访问控制规则的匹配。请求处理端的实现可参见 handler_authz_impl_extauthz.go它用ctx.Method()、ctx.XForwardedProto()、ctx.Host()与ctx.AuthzPath()构造授权对象再交给 authorization 包做资源判定。在身份认证Authn层面ExtAuthz 端点默认按顺序执行两条策略HeaderAuthorization读取Authorization头如 Basic/Bearer失败时返回带WWW-Authenticate头的401 UnauthorizedCookieSession读取会话 Cookie失败时重定向用户去 Authelia 门户完成认证这也是浏览器用户走完登录流程后能回到原页面的机制。这两条策略正是headersToExtAuth中需要包含authorization、proxy-authorization与cookie的根本原因。若你的场景需要Proxy-Authorization头认证Authelia 也提供HeaderProxyAuthorization、HeaderAuthRequestProxyAuthorization等策略可在 Server Authz Endpoints 配置文档 中按需调整。仓库中的单元测试 handler_authz_impl_extauthz_test.go 对 ExtAuthz 行为做了系统性验证例如认证失败时响应应携带Location头用于跳转 Authelia 门户、成功时不应出现该头等可作为理解端到端行为与排查集成问题的参考。安全提示信任的转发头与集成安全在使用任何代理类集成时Authelia 官方还给出了一条重要提醒见 Envoy 代理集成文档 的 “Trusted Proxies and Integration Security” 小节务必阅读并定期执行 Validating Forwarded Authentication转发认证校验参考指南 中的校验步骤将其纳入日常安全巡检。需要特别注意的是Remote-User、Remote-Groups、Remote-Email等头由 Authelia 注入到上游请求其可信度建立在“只有受信任代理能改写这些头”这一前提上。如果你的集群中存在其他不经过 Envoy Gateway 就能直达后端的入口或代理配置允许外部直接注入这些头都可能绕过 Authelia 的授权决策。此外官方还建议阅读 Envoy 的 Forwarded Headers 相关文档见 Envoy 集成文档确保X-Forwarded-*头只被可信代理写入。备选方案OpenID Connect 1.0 集成除 ExtAuthz 外Authelia 官方还为 Envoy Gateway 提供了 OpenID Connect 1.0 客户端集成方案详见 Envoy Gateway OIDC 客户端集成。该方案的优势在于当你的后端应用需要共享 ID Token 或 Access Token例如校验用户身份声明、调用受保护 API时OIDC 方式比 ExtAuthz 更直接。其典型做法是在 Authelia 侧注册 OIDC 客户端client_id: envoy、授权策略two_factor、authorization_code授权类型等同时在 Envoy Gateway 侧通过SecurityPolicy的oidc段声明 issuer、authorizationEndpoint、tokenEndpoint、clientID 与clientSecret以 Kubernetes Secret 形式引用等参数。需要提醒的是OIDC 方案会把 ID Token / Access Token 存储在会话 Cookie 中官方明确建议每个应用使用独立的 SecurityPolicy且每个 SecurityPolicy 配置与受保护应用完全匹配的cookieDomain以避免令牌被不相关应用读取。选择哪种方案取决于你是更看重“统一入口鉴权 后端无感”ExtAuthz还是“后端需要消费令牌”OIDC。排查与验证建议验证 Authelia 端点可达性在集群内用curl直接请求http://authelia.default.svc.cluster.local/api/authz/ext-authz/观察返回码确认 Service 与端点路径无误。检查元数据头是否完整ExtAuthz 元数据中X-Forwarded-Proto、Host、X-Forwarded-For缺失都会导致鉴权判定异常请确认headersToExtAuth已包含对应头。确认 ReferenceGrant 生效SecurityPolicy 与 Authelia Service 跨命名空间时若策略未生效优先检查 ReferenceGrant 的from/to是否与实际资源完全匹配。验证失败模式failOpen: false下可临时停掉 Authelia Pod确认受保护路由返回拒绝而非放行以验证 fail-closed 行为符合预期。延伸阅读Envoy Gateway 官方文档GeneralEnvoy Gateway External Authorization Security TasksEnvoy Gateway OIDC Authentication Security Tasks仓库内相关文档Envoy 代理集成、Kubernetes Envoy 集成总览、Proxy Authorization 参考指南、Server Authz Endpoints 配置仓库内相关源码ExtAuthz 请求处理器、远程标识头常量、ExtAuthz 单元测试【免费下载链接】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），仅供参考