Authelia 与 Envoy Gateway 集成指南通过 Kubernetes Gateway API 为应用启用 OpenID Connect 1.0 单点登录【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本指南讲解如何在 Kubernetes 集群中将 Authelia 作为 OpenID Connect 1.0 提供方OP与 Envoy Gateway 的 OIDC 认证能力对接为基于 Gateway API 的 HTTPRoute 或整个 Gateway 施加统一的身份认证。读完本文你将掌握 Authelia 侧的 OIDC 客户端注册配置、Envoy Gateway 侧的 SecurityPolicy 声明式配置以及两种作用范围单条 HTTPRoute 与整个 Gateway的完整落地方法。测试版本Tested Versions本集成指南在以下版本组合上完成验证组件版本Autheliav4.39.24Envoy Gatewayv1.4.1本文中展示的集成方式基于 Envoy Gateway 的 SecurityPolicy OIDC 能力与 Gateway API 资源模型适用前提是集群中已经安装并配置好 Envoy Gateway含eg网关实例与 Authelia且二者网络互通。假设前提Assumptions本示例采用如下假设值你可以按实际环境替换应用根 URLhttps://envoy.example.com/Authelia 根 URLhttps://auth.example.com/Client IDenvoyClient Secretinsecure_secret需要说明的是示例中的example.com域名与insecure_secret仅用于演示。生产环境中客户端标识符与密钥应使用随机生成的高强度值详见下文“客户端凭证的生成与安全”小节并替换为真实域名。在开始配置之前务必先阅读 Authelia 官方的 OpenID Connect 1.0 集成介绍 与 客户端配置文档其中包含注册客户端前必须了解的重要事项客户端凭证规范、作用域定义、各端点行为等。一、Authelia 侧配置注册 OIDC 客户端在 Authelia 的configuration.yml中为 Envoy Gateway 注册一个名为envoy的 OIDC 客户端。OpenID Connect 1.0 提供方的其余必需配置如issuer、jwks、hmac_secret等需要按照提供方配置指南另行补齐下面的片段仅展示客户端注册部分identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. ## See: https://www.authelia.com/c/oidc clients: - client_id: envoy client_name: Envoy Gateway client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # The digest of insecure_secret. public: false authorization_policy: two_factor require_pkce: false pkce_challenge_method: redirect_uris: - https://envoy.example.com/authelia/openid_connect/callback scopes: - openid - offline_access grant_types: - authorization_code - refresh_token response_types: - code access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_basic关键配置项解读对照 客户端配置参考逐一说明上述字段的作用与默认行为client_id/client_name客户端的唯一标识与显示名称。client_id在整个提供方中必须唯一且应只包含 RFC3986 非保留字符长度不超过 100 字符。client_secret客户端密钥。示例中存放的是insecure_secret的 PBKDF2-SHA512 哈希摘要$pbkdf2-sha512$310000$...。Authelia 强烈推荐以哈希形式存储密钥而非明文哈希工作因子过高可能导致客户端认证超时可参考 FAQ 中的工作因子调优。public: false声明为机密型confidential客户端。机密型客户端必须能够安全保管凭证其默认认证方式为client_secret_basic。authorization_policy: two_factor该客户端发起的授权请求所需满足的认证级别可取one_factor、two_factor或提供方authorization_policies中自定义的策略名。注意此策略仅作用于 OIDC 授权请求与访问控制规则Access Control Rules是两套独立机制。require_pkce/pkce_challenge_method是否强制使用 PKCE以及强制使用的 challenge 方法。合法值为空字符串、plain、S256S256是强烈推荐的选项。示例中 Envoy Gateway 未启用 PKCE因此二者均为关闭/空值。redirect_uris合法的回调 URI 白名单大小写敏感且 scheme 必须为http或https。这里必须与 Envoy Gateway SecurityPolicy 中的redirectURL保持一致。scopes允许该客户端消费的作用域。示例仅授予openid必需的 OIDC 作用域与offline_access刷新令牌所需更贴近最小权限原则。grant_types允许使用的授权类型。示例包含authorization_code与refresh_token对应授权码 刷新令牌的标准流程。response_types允许的响应类型示例仅使用code授权码模式这也是官方推荐的最安全的响应类型。access_token_signed_response_alg: noneAccess Token 不进行 JWT 签名保持默认的不透明令牌形式。若改为非none值则会按 RFC9068 将 Access Token 编码为 JWT仅建议在资源服务器需要无状态校验的高负载场景使用。userinfo_signed_response_alg: noneUserInfo 端点返回未签名的 JSONapplication/json而非 JWT。token_endpoint_auth_method: client_secret_basic令牌端点客户端认证方式机密型客户端默认值即为client_secret_basicHTTP Basic 携带凭证符合 OAuth 2.0 规范要求。客户端凭证的生成与安全不要直接使用示例中的insecure_secret或envoy。Authelia 官方 FAQ 建议客户端标识符与密钥每个客户端唯一、随机生成、长度超过 40 字符且只使用 RFC3986 非保留字符部分依赖方在访问令牌端点时无法正确 URL 编码特殊字符。Authelia 提供了便捷的生成命令参考 FAQ生成 72 字符的随机 Client IDauthelia crypto rand --length 72 --charset rfc3986同时生成随机 Client Secret 及其 PBKDF2 哈希哈希值用于写入 Authelia 配置明文值用于配置 Envoy Gatewayauthelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986二、Envoy Gateway 侧配置SecurityPolicy 接入 OIDCEnvoy Gateway 只有一种接入方式通过声明式的SecurityPolicy资源gateway.envoyproxy.io/v1alpha1在其oidc字段中描述 OIDC 提供方与客户端信息。因为该方案会把 ID Token 与 Access Token 存放在会话 Cookie 中官方文档特别给出如下安全告诫重要提示由于本方案将 ID Token 与 Access Token 存放在会话 Cookie 中强烈建议满足以下两点每个应用都应用独立的 SecurityPolicy每个 SecurityPolicy 配置的cookieDomain必须与受保护应用的域名完全匹配。这样可以避免 Cookie 在多个应用/域名间被错误共享降低令牌泄露风险。方式一仅保护单条 HTTPRoute适用场景集群中存在多个应用但只想为其中某一个如envoy应用启用 OIDC 认证。第 1 步创建客户端密钥 Secret使用kubectl创建保存 OIDC 客户端密钥的 Secretkubectl create secret generic envoy-oidc-client-secret --from-literalclient-secretinsecure_secret第 2 步创建示例应用的 HTTPRoute下面的 HTTPRoute 只是一个用于演示的示例应用路由关键在于metadata.name取值为envoySecurityPolicy 将以此关联目标资源--- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: envoy spec: parentRefs: - name: eg hostnames: - envoy.example.com rules: - matches: - path: type: PathPrefix value: / backendRefs: - name: envoy-service-backend port: 80 ...第 3 步创建 SecurityPolicy 施加 OIDC 认证下面的 SecurityPolicy 仅对上述envoyHTTPRoute 启用 OpenID Connect 1.0 授权核心是targetRefs它指明了该策略作用在哪个资源上--- apiVersion: gateway.envoyproxy.io/v1alpha1 kind: SecurityPolicy metadata: name: envoy-oidc spec: targetRefs: - group: gateway.networking.k8s.io kind: HTTPRoute name: envoy oidc: provider: issuer: https://auth.example.com authorizationEndpoint: https://auth.example.com/api/oidc/authorization tokenEndpoint: https://auth.example.com/api/oidc/token clientID: envoy clientSecret: name: envoy-oidc-client-secret cookieDomain: envoy.example.com cookieNames: idToken: accessToken: scopes: - openid - offline_access redirectURL: https://envoy.example.com/authelia/openid_connect/callback forwardAccessToken: false refreshToken: true passThroughAuthHeader: false ...方式二保护整个 Gateway 下的所有路由适用场景希望eg这个 Gateway 上的所有 HTTPRoute 统一走 OIDC 认证新加入的路由无需逐一配置策略。第 1 步创建客户端密钥 Secret同上kubectl create secret generic envoy-oidc-client-secret --from-literalclient-secretinsecure_secret第 2 步创建示例 HTTPRoute下面的 HTTPRoute 只是一个用于演示重定向行为的占位应用非真实业务应用--- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: envoy-oidc spec: parentRefs: - name: eg hostnames: - envoy-oidc.example.com rules: - matches: - path: type: PathPrefix value: / ...第 3 步创建覆盖整个 Gateway 的 SecurityPolicy与方式一的唯一区别在于targetRefs的目标从HTTPRoute换成了Gatewayname: eg从而对eg上的所有 HTTPRoute 生效--- apiVersion: gateway.envoyproxy.io/v1alpha1 kind: SecurityPolicy metadata: name: envoy-oidc spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: eg oidc: provider: issuer: https://auth.example.com authorizationEndpoint: https://auth.example.com/api/oidc/authorization tokenEndpoint: https://auth.example.com/api/oidc/token clientID: envoy clientSecret: name: envoy-oidc-client-secret cookieDomain: envoy-oidc.example.com cookieNames: idToken: accessToken: scopes: - openid - offline_access redirectURL: https://envoy-oidc.example.com/authelia/openid_connect/callback forwardAccessToken: false refreshToken: true passThroughAuthHeader: false ...SecurityPolicy 关键字段说明对照两种清单逐项说明spec.oidc下的字段含义字段说明provider.issuerOIDC 提供方Authelia的发行者标识即 Authelia 根 URL。Envoy Gateway 将据此校验 ID Token 的iss声明provider.authorizationEndpoint授权端点对应 Authelia 的/api/oidc/authorizationprovider.tokenEndpoint令牌端点对应 Authelia 的/api/oidc/tokenclientID与 Authelia 客户端配置中的client_id完全一致envoyclientSecret.name引用第 1 步创建的 Kubernetes Secret 名称明文密钥存放在该 Secret 中cookieDomain会话 Cookie 的域名必须与受保护应用域名完全匹配方式一为envoy.example.com方式二为envoy-oidc.example.comcookieNames自定义 Cookie 名称留空表示使用 Envoy Gateway 默认值scopes请求的作用域与 Authelia 客户端注册的scopes保持一致openid、offline_accessredirectURL授权码回调地址必须与 Authelia 注册的redirect_uris完全一致/authelia/openid_connect/callbackforwardAccessToken是否把 Access Token 透传给后端应用示例为falserefreshToken是否启用刷新令牌流程以维持会话示例为true需要客户端具备offline_access作用域与refresh_token授权类型passThroughAuthHeader是否将认证信息透传至后端示例为false三、端点对应关系理解回调链路SecurityPolicy 中的authorizationEndpoint、tokenEndpoint与回调路径均指向 Authelia 实现的 OpenID Connect 1.0 端点。根据 集成介绍 中记录的端点实现以https://auth.example.com为 Authelia 根 URL 时本方案涉及的端点如下端点路径授权端点authorization_endpointhttps://auth.example.com/api/oidc/authorization令牌端点token_endpointhttps://auth.example.com/api/oidc/token发现端点OpenID Connect Discovery 1.0https://auth.example.com/.well-known/openid-configuration用户访问受保护应用时的完整链路可以概括为用户请求https://envoy.example.com/Envoy Gateway 发现无有效会话 CookieEnvoy Gateway 将用户重定向到授权端点/api/oidc/authorization携带client_idenvoy、redirect_uri、scope、state等参数Authelia 要求用户完成登录本示例为双因素认证见authorization_policy: two_factor必要时征得用户同意consentAuthelia 将用户重定向回回调地址/authelia/openid_connect/callback并携带授权码Envoy Gateway 使用客户端凭证在令牌端点/api/oidc/token兑换 ID Token 与 Access Token客户端认证方式为client_secret_basicEnvoy Gateway 校验令牌后将 ID/Access Token 写入会话 Cookie放行请求后续请求通过 Cookie 直接鉴权并在令牌即将过期时利用refresh_token流程静默续期。四、验证与排障要点确认端点可达可以从集群内或浏览器直接访问https://auth.example.com/.well-known/openid-configuration核对authorization_endpoint、token_endpoint、issuer等字段是否与 SecurityPolicy 中配置一致。集成介绍明确指出无论 Authelia 版本如何都应优先利用该发现端点获取准确的端点 URL。核对回调地址一致性redirect_urisAuthelia与redirectURLEnvoy Gateway必须逐字符一致含 scheme、域名、路径且大小写敏感否则授权请求会被拒绝。核对作用域与授权类型refreshToken: true要求 Authelia 客户端同时配置offline_access作用域与refresh_token授权类型若刷新流程报错优先检查这两处配置是否匹配。Cookie 域隔离若出现会话串扰或回调异常检查cookieDomain是否与受保护应用的 hostname 完全匹配参见前文“重要提示”。凭证明文与哈希写入 Authelia 配置的client_secret是 PBKDF2 哈希而写入 Kubernetes Secret--from-literalclient-secret...与依赖方配置的是明文值二者不能互换使用。参见Envoy Gateway OIDC 认证安全任务Authelia OpenID Connect 1.0 集成介绍Authelia OpenID Connect 1.0 客户端配置参考Authelia OpenID Connect 1.0 提供方配置参考Authelia OpenID Connect 1.0 常见问题含客户端标识符/密钥生成【免费下载链接】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），仅供参考
