Authelia 4.38 发布详解OIDC 安全特性大升级、多域名保护与可定制授权端点【免费下载链接】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 官方 4.38 版本发布说明撰写系统梳理该版本在 OpenID Connect 1.0、多域名保护Multi-Domain Protection、WebAuthn、可定制授权端点、用户控制面板与配置系统等方向引入的核心能力并结合仓库源码与配置模板逐一说明其原理、迁移步骤与实战用法。读完本文你将掌握 4.38 升级所需的关键配置变更、新旧配置映射方式以及如何启用 PAR、JARM、Client Credentials Flow 等进阶 OIDC 安全特性。Authelia 4.38 于 2024 年 3 月发布是项目史上体量最大的一次版本之一落地了多项里程碑级路线图任务。它在 OpenID Connect 1.0 领域大幅向Financial-grade APIFAPI安全规范与 OAuth 2.0 安全最佳实践靠拢同时重构了会话Session与授权端点体系为后续 v5.0.0 铺路。本文逐项拆解这些变更并给出可直接落地的配置示例与迁移对照。升级前必读Foreword 与兼容性说明4.38 包含若干废弃旧配置的变更。升级后日志中出现的 deprecation 警告目前只是警告可以暂时忽略但按项目规划v5.0.0 将移除这些旧配置的支持因此官方强烈建议尽早按本文说明调整配置——部分新特性若不调整配置将完全无法启用。需要特别注意的是有几组配置变更必须同步进行使用新的代理Proxy授权端点配置时必须同时使用新的会话Session配置官方明确建议将多域名保护的 Session 变更与可定制授权端点变更在同一时间一起完成因为二者存在功能依赖。此外若你通过 Helm Chart 部署请注意 Chart 0.9.0 将包含本版本且按此前预告属于破坏性变更breaking change升级前务必核对 Chart 相关说明。OpenID Connect 1.0向 FAPI 与安全最佳实践迈进4.38 在 OIDC 方向引入了大量面向安全与隐私的特性是向 [Financial-grade API Security Profile 1.0 (Advanced)] 与 OAuth 2.0 Security Best Current Practice 靠拢的重要一步。同时配置项命名也在向规范对齐为未来实现 Dynamic Client Registration 等能力做准备。OAuth 2.0 Client Credentials Flow机器凭证流本版本正式支持基于机器的 Client Credentials Flow可用于以编程方式获取令牌。管理员可配置该流程对最终令牌的影响包括自动授予客户端有权请求的 audience受众。该流程通常配合下面的 Bearer Token 使用适合服务间调用、后台任务等无用户参与的场景。OAuth 2.0 Bearer Token 使用RFC 6750配合 Client Credentials FlowAuthelia 支持使用特殊的OAuth 2.0 Bearer Access Token按 [RFC6750] 实现允许用户/客户端创建自己的令牌。官方承诺后续会补充专门工具但目前已可通过标准化安全机制使用。详细接入方式见 OAuth 2.0 Bearer Token Usage 集成指南。OAuth 2.0 Authorization Server Issuer IdentificationRFC 9207在各种授权流程的响应中新增了一个标识授权服务器issuer的响应参数客户端可据此做额外校验符合 [RFC9207] 要求。支持该机制的客户端将自动受益无需额外配置。OAuth 2.0 Pushed Authorization RequestsPARRFC 9126PAR 是本版本 OIDC 实现的主打特性之一对应 [RFC9126]依赖方Relying Party / Client将 Authorization Request 参数通过**后端通道back-channel**发送给授权服务器换回一个不透明的 URI再以该 URI 作为标准授权端点的redirect_uri替代原先在前端通道明文传输的请求参数PAR 端点要求依赖方提供Token Endpoint 认证参数即使用客户端认证信息调用因此即使攻击者截获了授权码Authorization Code也缺少交换 Access Token / ID Token 所必需的client_id等关键信息该机制带来四重收益① 隐私增强规范的首要目标② 满足 FAPI Advanced 规范要求③ 防止攻击者在授权服务器收到请求前篡改请求参数④ 减少前端通道最易被窃听的位置暴露的信息量。PAR 可全局强制启用适用于所有客户端都支持 PAR 的场景也可按客户端单独启用。它还可以与 PKCE 同时使用。相关客户端配置参考 OIDC 客户端配置文档。OAuth 2.0 JWT Secured Authorization Response ModeJARMJARM 允许授权服务器对授权响应整体进行签名和/或加密确保响应由已知密钥签发。客户端可通过以下配置启用response_modes允许query.jwt、fragment.jwt、form_post.jwt等 JARM 响应模式authorization_signed_response_alg/authorization_signed_response_key_id指定签名算法与密钥其取值方式与下文 Client JSON Web Key Selection 一致。OAuth 2.0 JWT Response for Token Introspection与 JARM 类似令牌内省Introspection响应也可以签名成 JWT通过客户端配置项introspection_signed_response_alg与introspection_signed_response_key_id控制密钥选择同样走 Client JSON Web Key Selection 机制。PKCE 按客户端强制RFC 7636此前 Authelia 已支持 PKCE[RFC7636]并可在全局层面对公钥客户端或所有客户端强制要求。4.38 新增按客户端强制能力通过客户端配置项require_pkce管理员可要求某个特定客户端必须使用 PKCE。提示PKCE 可与 PAR 同时启用再加上 Authelia 对 HTTPS 方案的强制要求组合起来是非常强的安全防线。Client Authentication MethodToken Endpoint本节为重要变更升级后需重点关注。本版本允许管理员为 Token Endpoint 配置客户端认证方法限制客户端的令牌端点使用方式并为更高级的客户端认证方法铺路。对应客户端配置项为token_endpoint_auth_method。默认值为client_secret_basic现代客户端最常用的标准化默认值。从仓库源码可以看到默认逻辑internal/oidc/client.go 中GetTokenEndpointAuthMethod在未配置时公钥客户端Public默认none其余默认client_secret_basic认证方法常量定义于 internal/oidc/const.goclient_secret_basic、client_secret_post、client_secret_jwt、private_key_jwt、none。本版本新增了对client_secret_jwt与private_key_jwt两种方法的支持。日志中会给出客户端实际使用的方法据此更新配置即可。官方提示个别客户端可能因默认值变更而无法正常工作但这通常很容易修复——查看日志中客户端使用的方法将其写入token_endpoint_auth_method即可。Subject-Based Client Authorization Policies客户端现在可以针对单个用户或用户组配置允许allow、禁止disallow或要求特定认证级别require。相关配置见 OIDC Provider 的 authorization_policies。Per-Client Per-Grant Per-Token Lifespans令牌生命周期可以做到按客户端、按授权类型Grant、按令牌类型的细粒度控制。例如在客户端a上可以分别独立控制 Client Credentials Grant 的 Access Token 与 Refresh Token 的有效期。配置见 OIDC Provider 的 lifespans。附加客户端校验本版本新增了若干客户端配置合法性校验用于拦截技术上互不兼容的配置组合。目前这些校验仍是警告级别但后续版本很可能升级为错误建议在升级时一并清理。Multiple JSON Web Keys多 JWK与迁移授权服务器Issuer现在可以配置多个 JSON Web Key从而根据应用需求或内部策略用不同的密钥或算法为不同客户端签名。本节为重要变更不迁移到新配置则大量与“密钥选择”相关的 OIDC 新特性无法保证可用。新旧配置对照如下完整选项见 OIDC Provider 的 jwks 章节变更前旧式废弃identity_providers: oidc: issuer_private_key: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- issuer_certificate_chain: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----变更后新式identity_providers: oidc: jwks: - key: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- certificate_chain: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----变更后结合 template 过滤器从文件读取密钥identity_providers: oidc: jwks: - key: {{ secret /config/jwks/rsa.2048.pem | mindent 10 | | msquote }} certificate_chain: {{ secret /config/jwks/rsa.2048.cert | mindent 10 | | msquote }}注意新的jwks配置本身不支持内嵌明文密钥secrets 需通过模板过滤器处理。使用模板示例前必须通过环境变量X_AUTHELIA_CONFIG_FILTERStemplate启用template过滤器详见下文 配置模板化。从源码看新配置对应 internal/configuration/schema/identity_providers.go 中的JSONWebKeys []JWKkoanf 键名jwks同时客户端侧还支持jwks_uri与内联jwks两种公钥注册方式二者互斥。Client JSON Web Key Selection客户端 JWK 选择多个客户端配置项现在允许管理员指定用于特定操作的签名密钥大多数可通过“算法”或“具体 Key ID”两种方式选择前提是该 JWK 已注册到新的jwks选项中。典型应用包括access_token_signed_response_alg/access_token_signed_response_key_id为客户端启用OAuth 2.0 JWT Profile for Access Tokens[RFC9068]即把 Access Token 也做成 JWT 格式按客户端级别配置authorization_signed_response_alg/authorization_signed_response_key_idJARM 签名introspection_signed_response_alg/introspection_signed_response_key_id内省响应签名discovery_signed_response_alg/discovery_signed_response_key_id见下节。Discovery 端点签名OAuth 2.0 Authorization Server Metadata 与 OpenID Connect Discovery 1.0 端点现在可以可选地在元数据中嵌入签名 JWT供兼容客户端校验发现Discovery元数据。配置见 OIDC Provider 的 discovery_signed_response_alg / discovery_signed_response_key_id。其他值得注意的 OIDC 变更修复了注册客户端sector_identifier_uri此前未正确校验的问题升级后可能需要重新审视该配置详见 客户端 sector_identifier_uri 文档。多域名保护Multi-Domain Protection本版本落地了多域名保护路线图的核心实现详见 路线图。初始实现用户现在可以为 Cookie 配置多个根域名前提是这些域名之间互不为对方的子域每个域名还可以拥有各自独立的设置如各自的 Authelia URL、默认重定向地址。两点重要说明该特性不提供跨域单点登录SSO——官方调研显示用户对此兴趣很低且技术上涉及大量关键安全考量实现并不 trivial结合下文可定制授权端点该特性允许在NGINX / NGINX Proxy Manager / SWAG / HAProxy 之外的代理上通过配置自动探测 Authelia Portal URI——这意味着只需配置一个中间件/辅助组件即可完成自动重定向。⚠️ 注意该特性在撰写本文时与 WebAuthn 配合尚不完善官方正在解决但不会因此推迟本特性发布。配置变更Session**本节为重要变更建议与可定制授权端点变更同步进行。**若不迁移Forwarded / Redirected Authorization Flow 的诸多新能力将永远无法使用。完整选项见 Session 配置文档。新旧对照如下变更前旧式default_redirection_url: https://www.example.com session: name: authelia_session domain: example.com same_site: lax secret: insecure_session_secret expiration: 1h inactivity: 5m remember_me_duration: 1M变更后新式session: secret: insecure_session_secret name: authelia_session same_site: lax inactivity: 5m expiration: 1h remember_me: 1M cookies: - domain: example.com authelia_url: https://auth.example.com default_redirection_url: https://www.example.com变更后结合 template 过滤器多环境复用session: secret: insecure_session_secret name: authelia_session same_site: lax inactivity: 5m expiration: 1h remember_me: 1M cookies: - domain: {{ env DOMAIN_A }} authelia_url: https://auth.{{ env DOMAIN_A }} default_redirection_url: https://www.{{ env DOMAIN_A }}变更要点归纳维度变更前变更后顶层session.domain单一字符串移除改由session.cookies[].domain数组承载顶层default_redirection_url全局一个下沉到每个cookies[].default_redirection_urlremember_me_duration顶层更名为remember_me位于每个 cookie 块之外session 顶层新增authelia_url无每个 cookie 域可指定 Authelia Portal 地址用于代理自动重定向源码佐证Session 结构体在 internal/configuration/schema/session.go 中新增Cookies []SessionCookie其中每个SessionCookie含AutheliaURL与DefaultRedirectionURLL39-L40而顶层default_redirection_url在 internal/configuration/schema/configuration.go 中已被标记为deprecated。WebAuthn每用户多凭证4.38 完整支持每用户多个 WebAuthn 凭证passkey / 安全密钥。该功能的前端体验通过 用户仪表盘 / 控制面板 提供用户可在其中添加、管理多个凭证。相关路线图见 WebAuthn 完整路线图。可定制授权端点Customizable Authorization Endpoints长期以来Authelia 一直用/api/verify端点承担全部授权校验工作。4.38 正式废弃该端点改为可按实现定制的新端点每种受支持的代理对应一种独立实现。旧端点仍可工作甚至可通过Legacy实现方式再配置一个等效端点但官方强烈不建议继续使用——旧端点后续将不再有计划新增功能或修复安全修复除外。新端点体系支持自定义端点路径创建自己的实现完全禁用其他所有实现安全加固。使用新端点需要重新配置代理官方将为每个代理发布配套指南。完整配置见 Server Authz Endpoints 指南。变更说明代理集成迁移本节为重要变更建议与多域名保护 Session 变更同步完成。核心动作是将代理集成从废弃的/api/verify切换到对应代理的/api/authz/*端点并移除rd参数——重定向地址现在由 Session 变更中新增的authelia_url值接管。各代理默认端点映射如下以默认监听http://authelia:9091为例代理旧端点废弃新端点默认Traefik / Caddy / HAProxyhttp://authelia:9091/api/verify?rdhttps://auth.example.comhttp://authelia:9091/api/authz/forward-authNGINX 系含 NGINX Proxy Manager / SWAG同上http://authelia:9091/api/authz/auth-requestEnvoy同上http://authelia:9091/api/authz/ext-authz这些新端点可在 server endpoints authz 配置 中自定义一旦提供自定义配置只有被配置的端点会存在且部分代理可能需要额外配置请对照 代理集成指南 检查你的代理。源码佐证internal/server/const.go 中定义pathAuthz /api/authz、pathAuthzLegacy /api/verify并在 internal/server/handlers.go 中动态注册pathAuthz/name端点同时保留ANY /api/verify路由以兼容旧配置。用户仪表盘 / 控制面板User Dashboard / Control Panel澄清这是面向最终用户的控制面板管理自己的 2FA 设备、凭证等不是用于配置系统设置的管理员后台。设备注册 OTPElevated Session原先通过链接完成的敏感操作现在改为由 Authelia密码学随机生成的一次性代码/密码OTP。用户获得该 OTP 后可在限定时长内执行安全敏感任务即所谓elevation提权会话。OTP 的有效期以及用户处于提权状态的时长均可定制配置见新的 Elevated Session 配置文档。动机这种方式适用场景更广且对钓鱼攻击的抵抗力更强。TOTP 注册校验此前系统假定用户已成功注册 TOTP 应用现在则要求用户先输入 TOTP 验证码确认无误后才写入数据库从源头杜绝“注册了但没用过”的无效设备。Configuration配置系统增强目录加载Directories现在可以为文件配置指定一个目录目录内所有.yml与.yaml文件将按**字典序lexical order**加载。限制如下不允许跨文件合并列表例如所有 Access Control Rules 必须在同一个文件中所有 OIDC 注册客户端也必须在同一个文件中但其余配置可以方便地拆分到多个文件中管理。发现Discovery新增了用于配置发现的环境变量并且这将成为官方容器镜像的默认方式。其优势在于由于该变量在容器上下文中执行命令时始终可用即使配置路径发生变化或额外定义了其他路径只要正确使用该变量authelia命令也能正确定位配置文件。详见 文件配置方法的加载行为与发现章节。配置模板化Templating文件型配置新增了若干实验性模板过滤器用于创建配置模板第一个过滤器可把大部分环境变量直接展开到配置中第二个过滤器使用Go template 引擎工作方式与 Helm 非常相似。由于属于实验特性它们可能发生损坏、被移除或行为变化不过官方测试表明其稳定性相当高。典型用法即上文出现的{{ env DOMAIN_A }}与{{ secret /path/to/secret | mindent 10 | | msquote }}。启用方式设置环境变量X_AUTHELIA_CONFIG_FILTERStemplate。相关文档Configuration Prologue Security Sensitive ValuesConfiguration Methods Files: File FiltersReference Guides TemplatingMiscellaneous其他要点邮件通知Email Notifications由用户触发的事件例如新增 2FA 设备将生成新的邮件通知发送到用户邮箱。存储导入 / 导出Storage Import/Export新增并统一了用于导出、随后导入Authelia 关键存储值的实用功能可通过 Authelia CLI 使用详见 Authelia CLI 参考指南。隐私政策Privacy Policy为帮助管理员更轻松地符合GDPR要求前端可可选显示指向管理员自有隐私政策的链接并可可选要求用户在使用 Authelia 前接受该政策。LDAP 实现LDAP Implementations在既有实现基础上新增了若干LDAP implementation。相关配置见 LDAP 配置的 implementation 选项背景知识见 LDAP 参考指南。Server Listener服务器监听器重构服务器监听器配置被重构factorized。若更新不正确特别是旧path选项与/api/verify类端点路径结合的不当代理配置可能导致授权被跳过——已有用户踩过此坑。正确迁移方式如下详见 Server 配置的 address 章节变更前旧式server: host: 0.0.0.0 port: 9091 path: authelia变更后新式server: address: tcp://0.0.0.0:9091/authelia变更要点host与port合并进addresstcp://host:port格式path合并进address的路径部分/authelia。务必按照此方式迁移避免因监听路径与授权端点路径不一致而导致授权校验被意外跳过。升级行动清单综合以上变更升级到 4.38 建议按以下顺序执行备份配置与存储并准备回滚方案迁移 Session 配置将session.domain与顶层default_redirection_url迁移到session.cookies[]配合authelia_url与remember_me更名迁移授权端点将代理集成从/api/verify?rd...切换到对应代理的/api/authz/*端点并移除rd参数与第 2 步同时进行迁移 JWK 配置将issuer_private_key/issuer_certificate_chain迁移到identity_providers.oidc.jwks[]敏感密钥建议配合template过滤器从文件加载核对 Token Endpoint 客户端认证方法观察日志为各客户端补全token_endpoint_auth_method更新 Server 监听器配置为address单一字段形式最后再按需启用 PAR、JARM、PKCE 强制、Client Credentials Flow、多 JWK 签名、按客户端令牌生命周期等新特性并处理日志中的 deprecation 警告与新增的客户端配置校验警告。参考文档索引OIDC Provider 配置jwks / authorization_policies / lifespans / discovery 签名OIDC 客户端配置response_modes / require_pkce / token_endpoint_auth_method / sector_identifier_uriOAuth 2.0 Bearer Token 集成指南Session 配置介绍Server Authz Endpoints 配置Elevated Session 配置文件配置方法与模板过滤器代理集成指南[Financial-grade API Security Profile 1.0 (Advanced)]OIDF 发布的 FAPI 高级安全规范本文所述 PAR、JARM、签名内省等特性均与其对齐。[RFC6750]OAuth 2.0 Bearer Token 使用规范。[RFC9207]OAuth 2.0 Authorization Server Issuer Identification 规范。[RFC9126]OAuth 2.0 Pushed Authorization Requests 规范。[RFC7636]Proof Key for Code Exchange 规范。[RFC9068]OAuth 2.0 JWT Profile for Access Tokens 规范。【免费下载链接】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），仅供参考