Authelia 与 Traefik Kubernetes Ingress 集成实战Middleware、IngressRoute 与 HTTPRoute 完整配置指南【免费下载链接】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 官方 Kubernetes 集成文档为核心讲解如何在 Kubernetes 集群中通过 Traefik 2.x 的两种 Ingress 形态Kubernetes Ingress 与 Kubernetes CRD为业务应用接入 Authelia 的 ForwardAuth 单点登录认证并深入结合仓库源码剖析认证请求的处理链路帮助你在实际集群中完成可复制的安全配置。Authelia 官方在 Kubernetes 集成文档 中明确了其对 Traefik 2.x 系列 Kubernetes Ingress 控制器的官方支持。Traefik 是 Authelia 官方支持的反向代理之一二者通过ForwardAuth 授权端点/api/authz/forward-auth协同工作Traefik 将待保护应用的原始请求信息转发给 Authelia 做鉴权Authelia 根据访问控制规则返回放行、拒绝或重定向到登录门户的结果。读完本文你将掌握在 Kubernetes 中创建 ForwardAuth Middleware、并通过Ingress、IngressRoute与HTTPRouteGateway API三种方式挂载该 Middleware 的完整方法以及底层鉴权原理与安全注意事项。前置说明与文档定位官方支持两种 Traefik Kubernetes Ingress 控制器形态Traefik Kubernetes Ingress使用 Kubernetes 原生networking.k8s.io/v1的Ingress资源通过注解annotations引用 Traefik 路由与中间件配置。Traefik Kubernetes CRD使用 Traefik 自有的IngressRoute、Middleware等 CRD 资源配置能力更丰富。非 Kubernetes 场景下的 Traefik 配置同样具有参考价值可阅读 Traefik 反向代理集成文档其中包含 Docker Compose、动态文件配置YAML、mTLS 通信等更细粒度的示例本文聚焦集群内的 Ingress 形态。如果你是第一次部署 Authelia官方强烈建议先阅读 Authelia 快速上手指南仓库文档根入口完成基础引导用户数据库、访问控制规则、会话密钥、存储后端等初始化工作这些是让 ForwardAuth 鉴权正常工作的前提。说明官方文档中的部分值如auth.example.com、example.com在官网渲染时会被文档变量自动替换。本文示例默认使用文档变量的默认值即 Authelia 门户域名为auth.example.com、业务域名为example.com实际部署时请替换为你自己的域名。集成原理ForwardAuth 如何工作Traefik 侧的集成完全依赖 Authelia 的ForwardAuthAuthz 实现ForwardAuthImplementation对应端点路径为/api/authz/forward-auth。该实现要求代理在请求中携带一组描述原始请求的头部MetadataAuthelia 据此重建被保护资源的对象信息再结合访问控制规则做出判定。根据 代理授权参考文档ForwardAuth 需要以下关键元数据元数据来源请求头键方法 Method请求头X-Forwarded-Method协议 Scheme请求头X-Forwarded-Proto主机名 Hostname请求头X-Forwarded-Host路径 Path请求头X-Forwarded-URI客户端 IP请求头X-Forwarded-For可选建议提供Authelia 门户 URL会话 Cookie 配置session.cookies[].authelia_url从源码可以印证这一处理逻辑。在 handler_authz_impl_forwardauth.go 中handleAuthzGetObjectForwardAuth会读取X-Forwarded-Method头并调用authorization.NewObjectMethodSchemeHostPath用X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-URI三个头构造出被请求资源对象若X-Forwarded-Method为空会直接报错。因此 Traefik 侧必须正确传递这些头部这正是 Middleware 中trustForwardHeader: true的意义所在——它允许 Traefik 信任上游注入的转发头并把它们透传给 Authelia。鉴权判定完成后Authelia 在授权成功时200 OK会把用户身份写入响应头。见 handler_authz_common.go 中的handleAuthzAuthorizedStandard以及常量定义 internal/handlers/const.goRemote-User用户名Remote-Groups用户所属组逗号分隔Remote-Name用户显示名Remote-Email用户主邮箱这些响应头随后由 Traefik 的authResponseHeaders配置注入到发给后端应用的请求中实现单点登录后身份透传。这一行为同样被测试用例验证见 handler_authz_test.go 中对Remote-User、Remote-Name、Remote-Groups响应头的断言。前置配置会话与授权端点在部署 Ingress 之前Authelia 自身的配置需要满足两个前提1. 现代会话配置推荐。官方建议在session.cookies列表中配置domain、authelia_url、default_redirection_url这也是 ForwardAuth 元数据表中authelia_url的来源。示例如下session: cookies: - domain: example.com authelia_url: https://auth.example.com default_redirection_url: https://www.example.com2. 授权端点启用 ForwardAuth 实现。默认配置即适用也可显式声明见 Server Authz 端点配置文档server: endpoints: authz: forward-auth: implementation: ForwardAuth该端点默认启用HeaderAuthorization与CookieSession两种认证策略Authn Strategies普通浏览器用户通过会话 Cookie 识别身份API 客户端可通过Authorization: Basic头完成第一因子认证详见 代理授权参考文档。从源码看认证策略按顺序执行且失败即短路相关实现集中在 handler_authz_authn.go 中例如CookieSessionAuthnStrategy.Get会校验会话 Cookie 的域名一致性、非活跃时长与过期刷新而HeaderAuthnStrategy则解析Authorization/Proxy-Authorization头中的Basic或Bearer凭据。创建 ForwardAuth Middleware无论你最终使用 Traefik Kubernetes Ingress 还是纯粹的 CRD目前都需要借助 Traefik Kubernetes CRD 来定义 ForwardAuth Middleware官方文档明确指出据目前所知配置 ForwardAuth Middleware 必须使用 CRD 形态。示例假定Authelia 部署在default命名空间通过名为authelia的 Service 在 TCP 80 端口暴露 HTTP 服务集群默认 DNS 域名为cluster.local。--- apiVersion: traefik.containo.us/v1alpha1 kind: Middleware metadata: name: forwardauth-authelia # name of middleware as it appears in Traefik, and how you reference in ingress rules namespace: default # name of namespace that Traefik is in labels: app.kubernetes.io/instance: authelia app.kubernetes.io/name: authelia spec: forwardAuth: address: http://authelia.default.svc.cluster.local/api/authz/forward-auth trustForwardHeader: true maxResponseBodySize: 8192 authResponseHeaders: - Remote-User - Remote-Groups - Remote-Email - Remote-Name ...各字段含义与取值建议字段说明建议值spec.forwardAuth.addressForwardAuth 鉴权端点地址即 Authelia 服务的集群内 DNS 名FQDN 端点路径http://authelia.default.svc.cluster.local/api/authz/forward-authspec.forwardAuth.trustForwardHeader是否信任上游传递的X-Forwarded-*转发头并将其透传给 AutheliatrueForwardAuth 实现依赖这些头重建请求对象spec.forwardAuth.maxResponseBodySize允许的鉴权响应体最大字节数防止 Authelia 重定向页面的响应体过大被 Traefik 截断8192官方示例值spec.forwardAuth.authResponseHeaders将 Authelia 授权成功响应中的身份头复制到转发给后端的请求中Remote-User、Remote-Groups、Remote-Email、Remote-Name关键注意事项Middleware 绝不能应用到 Authelia 自身的 Ingress / IngressRoute 上只能应用于你想保护的业务应用入口。否则 Authelia 门户本身也会被 ForwardAuth 拦截形成认证死循环。官方文档以醒目警告强调这一点。方式一通过原生 Ingress 挂载 Middleware如果你使用 Traefik Kubernetes Ingress 形态Kubernetes 原生Ingress资源需要在Ingress的注解中引用上一步创建的 Middleware。示例假定应用部署在default命名空间Service 名为app、TCP 端口 80应用对外域名为app.example.com。--- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app namespace: default annotations: traefik.ingress.kubernetes.io/router.entryPoints: websecure # name of your https entry point (default is websecure) traefik.ingress.kubernetes.io/router.middlewares: default-forwardauth-autheliakubernetescrd # name of your middleware, as defined in your middleware.yml traefik.ingress.kubernetes.io/router.tls: true spec: rules: - host: app.example.com http: paths: - path: /bar pathType: Prefix backend: service: name: app port: number: 80 ...注解要点traefik.ingress.kubernetes.io/router.entryPoints指定流量入口点HTTPS 入口默认为websecure。traefik.ingress.kubernetes.io/router.middlewares以命名空间-中间件名kubernetescrd格式引用 Middleware例如default-forwardauth-autheliakubernetescrd。注意这里的命名空间是 Middleware 所在的命名空间与引用处kubernetescrd后缀共同构成 Traefik 的资源全名。traefik.ingress.kubernetes.io/router.tls置为true启用 TLS 终止证书签发需另行配置如 ACME。示例中路径/bar采用Prefix前缀匹配意味着app.example.com/bar及其子路径都会先经过 Authelia 鉴权实际可按需改用Exact精确匹配。方式二通过 IngressRouteCRD挂载 Middleware使用 Traefik Kubernetes CRD 形态时路由与中间件的引用全部在IngressRoute资源内声明。示例假定与上文一致。--- apiVersion: traefik.containo.us/v1alpha1 kind: IngressRoute metadata: name: app namespace: default spec: entryPoints: - websecure # name of your https entry point (default is websecure) routes: - kind: Rule match: Host(app.example.com) middlewares: - name: forwardauth-authelia # name of your middleware, as defined in your middleware.yml namespace: default services: - kind: Service name: app namespace: default port: 80 scheme: http strategy: RoundRobin weight: 10 ...结构解读spec.entryPoints路由绑定的入口点列表示例为websecure。routes[].matchTraefik 路由匹配规则Host(\app.example.com) 表示仅匹配该主机名也可组合 Path 前缀等规则。routes[].middlewares显式指定name与namespace即 Middleware 所在命名空间。这里与 Ingress 注解不同无需kubernetescrd后缀而是通过namespace字段完成跨命名空间引用。routes[].services后端负载均衡配置支持strategy: RoundRobin与weight权重示例为 10scheme: http表示使用 HTTP 与后端通信。方式三通过 HTTPRouteGateway API挂载 Middleware若你的集群启用了 Kubernetes Gateway API如 Traefik 作为 Gateway 实现可以使用HTTPRoute资源并通过ExtensionRef过滤器引用 Traefik Middleware。--- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: app namespace: default spec: parentRefs: - name: traefik sectionName: http kind: Gateway hostnames: - app.example.com rules: - backendRefs: - name: app namespace: default port: 80 filters: - type: ExtensionRef extensionRef: group: traefik.io kind: Middleware name: forwardauth-authelia ...要点说明spec.parentRefs指向承载流量的 TraefikGateway资源示例名为traefiksectionName对应 Gateway 上的监听器名称。spec.hostnames路由匹配的主机名列表。rules[].filtersExtensionRef过滤器用于引用 Traefik 扩展资源此处group: traefik.io、kind: Middleware、name: forwardauth-authelia即指向前面创建的 ForwardAuth Middleware。跨命名空间引用的特殊说明默认情况下 Traefik 不允许跨命名空间引用资源。若你的 Middleware 与受保护的 Ingress / IngressRoute 不在同一命名空间需要根据 Traefik 版本在 Traefik 部署中开启allowCrossNamespace选项对应 Traefik Kubernetes CRD Provider 的allowCrossNamespace配置以便从其他命名空间的 Ingress / IngressRoute 复用 Middleware另一种折中方案是在每个需要使用该 Middleware 的命名空间中各创建一份 Middleware 副本。请以你所部署的 Traefik 版本的官方文档为准。安全与运维注意事项转发头信任Trusted ProxiesTraefik 默认不信任任何上游代理需要显式配置可信代理网段trustedIPs才会采信X-Forwarded-For等转发头否则会移除可能伪造的头这本身是良好的安全默认值。参考 Traefik 集成文档示例网段需按实际架构裁剪切勿整网段信任10.0.0.0/8172.16.0.0/12192.168.0.0/16fc00::/7同时Authelia 官方建议定期执行 验证转发认证 中的校验步骤将其纳入常规安全巡检。集群层面的两个前提根据 Kubernetes 集成总览文档External Traffic Policy承载流量进入 Ingress 的 Service 应设置externalTrafficPolicy: local否则 Authelia及其他应用可能拿到错误的远端 IP从而影响基于 IP 的访问控制规则判断。Enable Service LinksAuthelia 的配置管理系统与 Pod 的enableServiceLinks: true默认值存在冲突应在 Authelia 的 Pod 规格中显式设置为false。常见问题排查Middleware 找不到若 Traefik 报类似middleware ... not found优先检查引用格式是否正确Ingress 注解需命名空间-名称kubernetescrdIngressRoute 需同时给出name与namespace并确认 Middleware 所在命名空间与allowCrossNamespace配置。应用未收到身份头检查authResponseHeaders是否完整列出四个Remote-*头并确认 Authelia 端授权成功响应200 OK若返回 401/403则按访问控制规则与认证策略逐项核对。需要 Basic 认证弹窗若业务场景要求使用Authorization头触发浏览器基础认证登录框可改用 Authelia 的/api/verify?authbasic端点Legacy 实现的 Basic 模式具体见 Traefik 集成文档 FAQ。鉴权全链路小结将上述内容串起来一次受保护请求的完整链路如下客户端请求https://app.example.com/bar流量进入 Traefik 的websecure入口点Traefik 根据 Ingress / IngressRoute / HTTPRoute 规则命中路由先执行forwardauth-autheliaMiddlewareTraefik 携带X-Forwarded-Method、X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-URI、X-Forwarded-For等头向http://authelia.default.svc.cluster.local/api/authz/forward-auth发起鉴权请求Authelia 依据请求头重建资源对象见 handler_authz_impl_forwardauth.go执行认证策略CookieSession / HeaderAuthorization后在 handler_authz.go 中通过授权器计算访问级别并判定结果授权成功返回200 OK并携带Remote-User等身份头见 handler_authz_common.goTraefik 将其透传后端应用未认证则返回重定向到auth.example.com门户的响应未授权则返回403 Forbidden。至此你已掌握在 Kubernetes 中让 Traefik 2.x 与 Authelia 协同完成单点登录认证的三种 Ingress 接入方式以及底层 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），仅供参考