Authelia Multi-Domain Protection单实例保护多个根域名的实现路线与配置指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia导读Multi-Domain Protection 是 Authelia 社区呼声最高的功能之一它允许管理员使用单个 Authelia 实例为多个根域名提供认证保护并为未来的跨根域单点登录SSO铺路。本文以官方路线图文档docs/content/roadmap/active/multi-domain-protection.md为主体结合 v4.38.0 的实际发布内容、session.cookies多域配置的完整参数说明与底层 Go 源码验证逻辑帮你完整掌握这一功能的实现阶段、迁移方法与使用限制。功能背景为什么需要 Multi-Domain Protection长期以来Authelia 的会话 Cookie 只能绑定在一个根域名上例如example.com。如果管理员运营着多个彼此独立的根域名例如example.com、example.org、example.net并且希望它们共用一个 Authelia 身份认证门户就会遇到根本性障碍——Cookie 的作用域由浏览器强制限定在单个域及子域内跨根域名的 Cookie 无法共享。路线图文档开篇即明确表达了官方立场We have seen and heard the feedback from our users and we are acting on it. This feature is being prioritized.multi-domain-protection.md。允许管理员利用单一 Authelia 实例保护多个根域名是一项实现难度较大的功能官方计划分阶段推进。注意本文描述的功能面向配置与使用层面仓库是只读的文中所有配置示例均用于本地部署与验证。实现路线图四个阶段路线图文档将整个功能拆分为按依赖顺序排列的阶段官方用roadmap-status标记了每个阶段的进度complete 表示已完成阶段一Decide on a Method确定实现方法—— 已完成需要先决定该功能的初始实现方式以及最终以何种形态提供根域名间的 SSO。根据文档中的更新说明初始实现方案与 SSO 实现方案均已确定。阶段二Decide on a Session Library确定会话库—— 已完成一个关键的技术决策官方决定弃用当前使用的第三方会话库改为完全在内部实现会话逻辑。这一决定为后续的多 Cookie 域管理、以及未来的跨域 SSO 提供了底层控制能力因为第三方会话库很难满足多域 Cookie 与跨域会话的定制需求。阶段三Initial Implementation初始实现—— 已完成随 v4.38.0 发布初始实现采用基础 Cookie 方案用户需要在每个根域名分别登录此时不存在跨域 SSO 功能。其定位是先把单实例保护多根域的能力落地再逐步演进。阶段四SSO ImplementationSSO 实现—— 进行中初始实现虽要求用户逐域登录但文档明确指出通过 OpenID Connect 1.0 等身份协议/框架可以实现对用户透明的单点登录。该阶段很可能与 OpenID Connect 1.0 Relying Party依赖方 支持同时实现——也就是说未来的跨域 SSO 将借助 OIDC 协议让其中一个域完成认证后其他域通过 OIDC 信任链透明地获得会话而不是依赖浏览器层面的跨域 Cookie。初始实现详解v4.38.0 的多 Cookie 域配置v4.38.0 发布说明release-notes-4.38/index.md正式宣告了 Multi-Domain Protection 初始实现的落地用户现在可以配置多个根域名的 Cookie前提是这些域名中没有一个是另一个已配置域名的子域。此外每个域名都可以拥有独立的设置。核心配置变更session.domain→session.cookies旧版配置使用单一的session.domain绑定一个根域v4.38.0 起该选项被标记为弃用替换为session.cookies列表每一项是一个完整的 Cookie 域配置。从源码结构看这一变更对应 internal/configuration/schema/session.go 中的SessionCookie结构体type SessionCookie struct { SessionCookieCommon koanf:,squash yaml:,inline Domain string koanf:domain ... AutheliaURL *url.URL koanf:authelia_url ... DefaultRedirectionURL *url.URL koanf:default_redirection_url ... Legacy bool yaml:- ... }同时原Session结构体中的Domain字段被显式标记为Deprecated: Use the session cookies option with the same name instead.验证器会给出对应的弃用提示见 internal/configuration/validator/const.go 中的errFmtSessionDomainLegacysession: option domain is deprecated in v4.38.0 and has been replaced by a multi-domain configuration...。迁移前后对比示例以下Before / After示例来自 v4.38.0 发布说明展示了从单域到多域的迁移方式Before旧版单域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: 1MAfter新版多域列表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 - domain: example.org authelia_url: https://auth.example.org default_redirection_url: https://www.example.org注意几个关键差异顶层的default_redirection_url被移入每个 Cookie 域的default_redirection_url中全局选项被该选项弃用remember_me_duration更名为remember_me每个 Cookie 域都可以独立指定name、same_site、inactivity、expiration、remember_me等设置。结合模板过滤器管理多域配置如果希望通过环境变量驱动多域配置例如为多个租户生成同一份配置可以启用template配置过滤器通过环境变量X_AUTHELIA_CONFIG_FILTERStemplate开启示例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.cookies完整参数说明以下参数说明综合自官方配置文档 docs/content/configuration/session/introduction.md顶层默认值作用于所有 Cookie 域参数类型默认值说明secretstring必填用于加密 Redis 中会话数据的密钥强烈建议使用 64 位以上随机字母数字字符串namestringauthelia_session所有 Cookie 域默认的会话 Cookie 名称same_sitestringlax所有 Cookie 域的默认 SameSite 值小写可取lax/strict/noneinactivityduration5m默认不活跃超时超时后会话销毁expirationduration1h默认过期时间未勾选记住我时remember_meduration1M勾选记住我时的默认过期时间cookies列表内的每项配置参数类型必填说明domainstring是会话 Cookie 负责保护的域名即 URL 的 hostname 部分不含端口authelia_urlstring是该 Cookie 域对应的 Authelia 门户根 URL用于在需要认证时生成重定向地址default_redirection_urlstring否直接访问 Authelia 时的重定向地址弃用全局同名选项不能与authelia_url相同namestring否该域会话 Cookie 名称默认取顶层namesame_sitestring否该域 SameSite 值默认取顶层same_siteinactivityduration否该域不活跃超时默认取顶层值expirationduration否该域过期时间默认取顶层值remember_meduration否该域记住我时长设为-1可完全禁用默认取顶层值domain的硬性约束源码级验证从验证器实现 internal/configuration/validator/session.go 的validateSessionDomainName可以看出domain字段必须满足以下条件否则配置校验直接失败必须是标准使用域名即全球可信 CA 愿意为其签发 X.509 证书的 hostname 部分TLS 是严格前提不允许通配符*.example.com会报错must be the domain you wish to protect not a wildcard domain必须至少包含一个句点纯localhost或单段域名会报错must have at least a single period or be an ip address同时localhost属于特殊用途域名浏览器不允许其写入 Authelia 所需的 Cookie不能是 Public Suffix List 上的公共后缀域如duckdns.org浏览器会拒绝为这类域设置 Cookie应使用类似example.duckdns.org的子域形式不能带端口包含端口会触发警告不允许以.前缀开头会触发警告提示不建议的用法。此外validateSessionUniqueCookieDomain负责检测域名冲突完全重复的域名→ 报错option domain is a duplicate value for another configured session domain一个域是另一个域的子域共享同一 Cookie 作用域→ 报错option domain shares the same cookie domain scope as another configured session domain。这正是发布说明中不能配置互为子域的域名这一限制的源码体现相关测试见 internal/configuration/validator/session_test.go。URL 类参数的作用域校验验证器还严格校验 URL 与 Cookie 域的作用域关系validateSessionCookiesURLsauthelia_url必须是绝对 URL且使用https://安全协议IsURISecure校验HTTP 会报does not have a secure schemeauthelia_url的域名必须是domain的后缀或与之完全匹配即必须能读写该域的 Cookie若 Authelia 门户通过子路径访问例如server.address配置了子路径authelia_url需带上路径如https://example.com/autheliadefault_redirection_url同样必须为绝对、安全的 URL且与authelia_url不得相同在不支持跨域跳转的旧版Legacy模式下作用域不匹配仅降级为警告并清空该值。与 Customizable Authorization Endpoints 的配合初始实现还带来一个重要的衍生能力基于配置的 Authelia Portal URI 检测。借助新的 可定制授权端点Customizable Authorization Endpoints/api/authz/*系列取代已弃用的/api/verify在非 NGINX / NGINX Proxy Manager / SWAG / HAProxy 的反向代理上Authelia 可以直接依据每个 Cookie 域配置的authelia_url自动生成正确的重定向地址——这意味着你只需要配置一个中间件或辅助程序即可完成自动跳转而无须为每个代理手工编写跳转逻辑。官方强烈建议session.cookies迁移与代理端授权端点升级同时进行代理配置中需要移除旧的rd重定向参数该参数现已由authelia_url取代并将/api/verify切换为对应代理类型的/api/authz/*端点。这是因为多项新功能相互依赖只迁移其中一项会导致新特性不可用。已知限制与未来方向当前限制无跨域 SSO需要特别强调的是v4.38.0 的初始实现不提供跨根域的 SSO。发布说明指出官方调查显示用户对跨不同根域自动登录的需求度很低且该功能实现并非易事——涉及大量关键安全考量跨域会话共享在浏览器安全模型下极易引入会话固定、CSRF 等风险。因此当前状态下用户访问第二个根域时仍需再次登录。未来方向基于 OIDC 的跨域 SSO路线图文档将跨域 SSO 的实现寄托于OpenID Connect 1.0通过身份协议实现用户无感知的单点登录即其中一个根域作为 OIDC Provider 完成认证其他根域通过 OIDC 流程获得会话。这一步很可能与 OpenID Connect 1.0 Relying Party 支持同时实现。从 OIDC Provider 路线图openid-connect-1.0-provider.md的 Multi-Issuer Configuration 小节可以看到两者之间的设计联动该小节明确写道OIDC 实现的最初设计早于 Multi-Domain Protection 被纳入考虑为了 Authelia 的未来将强制用户为希望提供 OIDC 服务的每个域分别配置一个 Issuer且每个 Issuer 是完全独立的逻辑单元——这正是一实例多根域与 OIDC 多 Issuer 设计相互配套的体现。其他注意事项WebAuthn 兼容性初始实现在发布时与 WebAuthnPasskey配合不佳官方表示正在着手解决但不会因此推迟该功能发布Session 存储多 Cookie 域配置不影响会话存储后端的选择——内存默认、有状态、Redis无状态与 Redis Sentinel无状态、高可用均可用Kubernetes / 高可用场景推荐使用无状态的 Redis 系列见 docs/content/configuration/session/introduction.md。结语Multi-Domain Protection 是 Authelia 从单域认证门户迈向多域身份基础设施的关键里程碑v4.38.0 通过session.cookies多域列表 每域独立配置 可定制授权端点落地了单实例保护多个根域名的初始能力其底层的会话逻辑内部化与严格的 Cookie 域作用域校验可追溯至 internal/configuration/schema/session.go 与 internal/configuration/validator/session.go为后续基于 OpenID Connect 1.0 的跨域 SSO 打好了基础。如果你正在为多个根域名规划统一的认证入口现在就可以按本文示例完成session.cookies迁移若需要跨域单点登录则可关注路线图中 SSO Implementation 与 OIDC Relying Party 的后续进展。【免费下载链接】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），仅供参考 Authelia Multi-Domain Protection：单实例保护多个根域名的实现路线与配置指南
Authelia Multi-Domain Protection单实例保护多个根域名的实现路线与配置指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia导读Multi-Domain Protection 是 Authelia 社区呼声最高的功能之一它允许管理员使用单个 Authelia 实例为多个根域名提供认证保护并为未来的跨根域单点登录SSO铺路。本文以官方路线图文档docs/content/roadmap/active/multi-domain-protection.md为主体结合 v4.38.0 的实际发布内容、session.cookies多域配置的完整参数说明与底层 Go 源码验证逻辑帮你完整掌握这一功能的实现阶段、迁移方法与使用限制。功能背景为什么需要 Multi-Domain Protection长期以来Authelia 的会话 Cookie 只能绑定在一个根域名上例如example.com。如果管理员运营着多个彼此独立的根域名例如example.com、example.org、example.net并且希望它们共用一个 Authelia 身份认证门户就会遇到根本性障碍——Cookie 的作用域由浏览器强制限定在单个域及子域内跨根域名的 Cookie 无法共享。路线图文档开篇即明确表达了官方立场We have seen and heard the feedback from our users and we are acting on it. This feature is being prioritized.multi-domain-protection.md。允许管理员利用单一 Authelia 实例保护多个根域名是一项实现难度较大的功能官方计划分阶段推进。注意本文描述的功能面向配置与使用层面仓库是只读的文中所有配置示例均用于本地部署与验证。实现路线图四个阶段路线图文档将整个功能拆分为按依赖顺序排列的阶段官方用roadmap-status标记了每个阶段的进度complete 表示已完成阶段一Decide on a Method确定实现方法—— 已完成需要先决定该功能的初始实现方式以及最终以何种形态提供根域名间的 SSO。根据文档中的更新说明初始实现方案与 SSO 实现方案均已确定。阶段二Decide on a Session Library确定会话库—— 已完成一个关键的技术决策官方决定弃用当前使用的第三方会话库改为完全在内部实现会话逻辑。这一决定为后续的多 Cookie 域管理、以及未来的跨域 SSO 提供了底层控制能力因为第三方会话库很难满足多域 Cookie 与跨域会话的定制需求。阶段三Initial Implementation初始实现—— 已完成随 v4.38.0 发布初始实现采用基础 Cookie 方案用户需要在每个根域名分别登录此时不存在跨域 SSO 功能。其定位是先把单实例保护多根域的能力落地再逐步演进。阶段四SSO ImplementationSSO 实现—— 进行中初始实现虽要求用户逐域登录但文档明确指出通过 OpenID Connect 1.0 等身份协议/框架可以实现对用户透明的单点登录。该阶段很可能与 OpenID Connect 1.0 Relying Party依赖方 支持同时实现——也就是说未来的跨域 SSO 将借助 OIDC 协议让其中一个域完成认证后其他域通过 OIDC 信任链透明地获得会话而不是依赖浏览器层面的跨域 Cookie。初始实现详解v4.38.0 的多 Cookie 域配置v4.38.0 发布说明release-notes-4.38/index.md正式宣告了 Multi-Domain Protection 初始实现的落地用户现在可以配置多个根域名的 Cookie前提是这些域名中没有一个是另一个已配置域名的子域。此外每个域名都可以拥有独立的设置。核心配置变更session.domain→session.cookies旧版配置使用单一的session.domain绑定一个根域v4.38.0 起该选项被标记为弃用替换为session.cookies列表每一项是一个完整的 Cookie 域配置。从源码结构看这一变更对应 internal/configuration/schema/session.go 中的SessionCookie结构体type SessionCookie struct { SessionCookieCommon koanf:,squash yaml:,inline Domain string koanf:domain ... AutheliaURL *url.URL koanf:authelia_url ... DefaultRedirectionURL *url.URL koanf:default_redirection_url ... Legacy bool yaml:- ... }同时原Session结构体中的Domain字段被显式标记为Deprecated: Use the session cookies option with the same name instead.验证器会给出对应的弃用提示见 internal/configuration/validator/const.go 中的errFmtSessionDomainLegacysession: option domain is deprecated in v4.38.0 and has been replaced by a multi-domain configuration...。迁移前后对比示例以下Before / After示例来自 v4.38.0 发布说明展示了从单域到多域的迁移方式Before旧版单域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: 1MAfter新版多域列表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 - domain: example.org authelia_url: https://auth.example.org default_redirection_url: https://www.example.org注意几个关键差异顶层的default_redirection_url被移入每个 Cookie 域的default_redirection_url中全局选项被该选项弃用remember_me_duration更名为remember_me每个 Cookie 域都可以独立指定name、same_site、inactivity、expiration、remember_me等设置。结合模板过滤器管理多域配置如果希望通过环境变量驱动多域配置例如为多个租户生成同一份配置可以启用template配置过滤器通过环境变量X_AUTHELIA_CONFIG_FILTERStemplate开启示例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.cookies完整参数说明以下参数说明综合自官方配置文档 docs/content/configuration/session/introduction.md顶层默认值作用于所有 Cookie 域参数类型默认值说明secretstring必填用于加密 Redis 中会话数据的密钥强烈建议使用 64 位以上随机字母数字字符串namestringauthelia_session所有 Cookie 域默认的会话 Cookie 名称same_sitestringlax所有 Cookie 域的默认 SameSite 值小写可取lax/strict/noneinactivityduration5m默认不活跃超时超时后会话销毁expirationduration1h默认过期时间未勾选记住我时remember_meduration1M勾选记住我时的默认过期时间cookies列表内的每项配置参数类型必填说明domainstring是会话 Cookie 负责保护的域名即 URL 的 hostname 部分不含端口authelia_urlstring是该 Cookie 域对应的 Authelia 门户根 URL用于在需要认证时生成重定向地址default_redirection_urlstring否直接访问 Authelia 时的重定向地址弃用全局同名选项不能与authelia_url相同namestring否该域会话 Cookie 名称默认取顶层namesame_sitestring否该域 SameSite 值默认取顶层same_siteinactivityduration否该域不活跃超时默认取顶层值expirationduration否该域过期时间默认取顶层值remember_meduration否该域记住我时长设为-1可完全禁用默认取顶层值domain的硬性约束源码级验证从验证器实现 internal/configuration/validator/session.go 的validateSessionDomainName可以看出domain字段必须满足以下条件否则配置校验直接失败必须是标准使用域名即全球可信 CA 愿意为其签发 X.509 证书的 hostname 部分TLS 是严格前提不允许通配符*.example.com会报错must be the domain you wish to protect not a wildcard domain必须至少包含一个句点纯localhost或单段域名会报错must have at least a single period or be an ip address同时localhost属于特殊用途域名浏览器不允许其写入 Authelia 所需的 Cookie不能是 Public Suffix List 上的公共后缀域如duckdns.org浏览器会拒绝为这类域设置 Cookie应使用类似example.duckdns.org的子域形式不能带端口包含端口会触发警告不允许以.前缀开头会触发警告提示不建议的用法。此外validateSessionUniqueCookieDomain负责检测域名冲突完全重复的域名→ 报错option domain is a duplicate value for another configured session domain一个域是另一个域的子域共享同一 Cookie 作用域→ 报错option domain shares the same cookie domain scope as another configured session domain。这正是发布说明中不能配置互为子域的域名这一限制的源码体现相关测试见 internal/configuration/validator/session_test.go。URL 类参数的作用域校验验证器还严格校验 URL 与 Cookie 域的作用域关系validateSessionCookiesURLsauthelia_url必须是绝对 URL且使用https://安全协议IsURISecure校验HTTP 会报does not have a secure schemeauthelia_url的域名必须是domain的后缀或与之完全匹配即必须能读写该域的 Cookie若 Authelia 门户通过子路径访问例如server.address配置了子路径authelia_url需带上路径如https://example.com/autheliadefault_redirection_url同样必须为绝对、安全的 URL且与authelia_url不得相同在不支持跨域跳转的旧版Legacy模式下作用域不匹配仅降级为警告并清空该值。与 Customizable Authorization Endpoints 的配合初始实现还带来一个重要的衍生能力基于配置的 Authelia Portal URI 检测。借助新的 可定制授权端点Customizable Authorization Endpoints/api/authz/*系列取代已弃用的/api/verify在非 NGINX / NGINX Proxy Manager / SWAG / HAProxy 的反向代理上Authelia 可以直接依据每个 Cookie 域配置的authelia_url自动生成正确的重定向地址——这意味着你只需要配置一个中间件或辅助程序即可完成自动跳转而无须为每个代理手工编写跳转逻辑。官方强烈建议session.cookies迁移与代理端授权端点升级同时进行代理配置中需要移除旧的rd重定向参数该参数现已由authelia_url取代并将/api/verify切换为对应代理类型的/api/authz/*端点。这是因为多项新功能相互依赖只迁移其中一项会导致新特性不可用。已知限制与未来方向当前限制无跨域 SSO需要特别强调的是v4.38.0 的初始实现不提供跨根域的 SSO。发布说明指出官方调查显示用户对跨不同根域自动登录的需求度很低且该功能实现并非易事——涉及大量关键安全考量跨域会话共享在浏览器安全模型下极易引入会话固定、CSRF 等风险。因此当前状态下用户访问第二个根域时仍需再次登录。未来方向基于 OIDC 的跨域 SSO路线图文档将跨域 SSO 的实现寄托于OpenID Connect 1.0通过身份协议实现用户无感知的单点登录即其中一个根域作为 OIDC Provider 完成认证其他根域通过 OIDC 流程获得会话。这一步很可能与 OpenID Connect 1.0 Relying Party 支持同时实现。从 OIDC Provider 路线图openid-connect-1.0-provider.md的 Multi-Issuer Configuration 小节可以看到两者之间的设计联动该小节明确写道OIDC 实现的最初设计早于 Multi-Domain Protection 被纳入考虑为了 Authelia 的未来将强制用户为希望提供 OIDC 服务的每个域分别配置一个 Issuer且每个 Issuer 是完全独立的逻辑单元——这正是一实例多根域与 OIDC 多 Issuer 设计相互配套的体现。其他注意事项WebAuthn 兼容性初始实现在发布时与 WebAuthnPasskey配合不佳官方表示正在着手解决但不会因此推迟该功能发布Session 存储多 Cookie 域配置不影响会话存储后端的选择——内存默认、有状态、Redis无状态与 Redis Sentinel无状态、高可用均可用Kubernetes / 高可用场景推荐使用无状态的 Redis 系列见 docs/content/configuration/session/introduction.md。结语Multi-Domain Protection 是 Authelia 从单域认证门户迈向多域身份基础设施的关键里程碑v4.38.0 通过session.cookies多域列表 每域独立配置 可定制授权端点落地了单实例保护多个根域名的初始能力其底层的会话逻辑内部化与严格的 Cookie 域作用域校验可追溯至 internal/configuration/schema/session.go 与 internal/configuration/validator/session.go为后续基于 OpenID Connect 1.0 的跨域 SSO 打好了基础。如果你正在为多个根域名规划统一的认证入口现在就可以按本文示例完成session.cookies迁移若需要跨域单点登录则可关注路线图中 SSO Implementation 与 OIDC Relying Party 的后续进展。【免费下载链接】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），仅供参考