Authelia Session 配置完全指南:会话 Cookie、多域名与 Redis 会话存储

原创2026-09-11 19:28:501,880 阅读
文章标签:认证鉴权单点登录身份认证后端网络安全前端

Authelia Session 配置完全指南:会话 Cookie、多域名与 Redis 会话存储

导读:Authelia 依赖会话 Cookie 来授权用户访问各个受保护站点,会话(session)配置段决定了 Cookie 的行为方式、可服务的授权请求域名,以及会话数据的存储位置。本文以官方配置文档为骨架,结合仓库内配置 Schema 与校验器源码,系统讲解 session 段的全部配置项(含 cookies 多域名列表)、Memory / Redis / Redis Sentinel 三种会话存储 Provider 的选型原则,以及每个参数在源码中的默认值与校验规则,帮助你搭建安全、可横向扩展的 SSO 会话体系。

配置总览

在 configuration.yml 中,session 是一个顶层配置段。以下是一个完整的最小示例(源码级字段定义见 internal/configuration/schema/session.go):

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'
      name: 'authelia_session'
      same_site: 'lax'
      inactivity: '5m'
      expiration: '1h'
      remember_me: '1d'

结构上,session 段由两大部分组成:

  1. Cookie 公共默认值:name、same_site、inactivity、expiration、remember_me,它们作为 cookies 列表中每个条目的默认值来源;
  2. cookies 列表:为每个受保护域名单独定义 Cookie 行为,未正确配置的域名会被 Authelia 自动拒绝服务。

在源码中,schema.Session 通过 SessionCookieCommon(内联展开)持有公共字段,并包含 Secret、Cookies []SessionCookie、Redis *SessionRedis 三个字段;其中顶层 Domain 字段已被标记为 Deprecated(已弃用),官方建议改用 cookies 下的同名配置。

会话存储 Provider 选型

当前共有两种会话存储 Provider(若将 Redis Sentinel 单独计数则为三种):

Provider 状态 是否需要额外配置 说明
Memory 有状态(stateful) 否 默认 Provider,会话数据保存在 Authelia 进程内存中,进程重启即丢失
Redis 无状态(stateless) 是 会话数据持久化在 Redis 中,详见 Redis 会话配置
Redis Sentinel 无状态(stateless) 是 基于 Redis Sentinel 的高可用方案,配置方式见 Redis 高可用小节

Kubernetes 与高可用场景的选型警示:在 Kubernetes 等水平扩展/高可用场景下,不推荐使用有状态的 Provider(如默认的 Memory)。文档明确建议:优先选择标注为 stateless 的 Provider(即 Redis 或 Redis Sentinel),因为多副本 Authelia 实例共享内存会话将导致会话漂移与认证状态不一致。

从源码看,Provider 的实例化入口位于 internal/session/provider.go 的 NewProvider/NewSessionProvider,它根据 schema.Session 配置决定底层后端;而会话数据的加密序列化由 internal/session/encrypting_serializer.go 中的 EncryptingSerializer 负责——这也是 secret 选项存在的原因:用于加密存储在 Redis 中的会话数据。

顶层选项详解

secret

  • 类型:string
  • 必填:是
  • 敏感:是(建议通过环境变量注入,避免明文入库)

用于加密 Redis 中会话数据的密钥。官方强烈建议使用 64 字符及以上的随机字母数字字符串。生成方式可参考仓库内指南 Generating a Random Alphanumeric String,例如使用 Authelia 自带 CLI:

authelia crypto rand --length 64 --charset alphanumeric

或在 Docker 环境下:

docker run --rm authelia/authelia:latest authelia crypto rand --length 64 --charset alphanumeric

校验器(internal/configuration/validator/session.go 的 validateRedisCommon)会在配置 Redis 时强制要求 secret 非空,否则报错 errFmtSessionSecretRequired。

name

  • 类型:string
  • 默认值:authelia_session
  • 必填:否

所有 cookies 配置的默认 Cookie 名称。默认值在源码中定义于 DefaultSessionConfiguration.Name(见 internal/configuration/schema/session.go)。当某个 cookie 条目未显式设置 name 时,validateSessionCookieName 会将其回填为顶层的 name 值。

same_site

  • 类型:string
  • 默认值:lax
  • 必填:否

所有 cookies 配置的默认 SameSite 值。注意必须使用小写,例如要设置 Strict 时配置值需写为 strict。源码中合法取值为 lax、strict、none 三选一(见 SessionCookieCommon.SameSite 的 enum 标注);非法值会触发 errFmtSessionSameSite 校验错误。

选型建议(官方观点):

  • Lax:对 Authelia 而言通常是最理想的选择,也是新默认值;
  • None:不推荐,除非你完全清楚后果且信任所有受保护应用;
  • Strict:在很多使用场景下无法正常工作,官方未在此状态下进行过充分测试,仅作为可选项开放。

注意:在提供该配置选项之前,此值默认是 None,新默认值已改为 Lax。

inactivity

  • 类型:string,integer(duration 语法)
  • 默认值:5 minutes
  • 必填:否

所有 cookies 配置的默认空闲超时。用户在该时间段内无任何活动则会话被销毁。该选项特别适合"想要较长的会话总时长,但又不希望闲置设备长期暴露在风险中"的场景。校验器在 Expiration <= 0 或 Inactivity <= 0 时会回填默认值(1 小时 / 5 分钟)。

expiration

  • 类型:string,integer(duration 语法)
  • 默认值:1 hour
  • 必填:否

所有 cookies 配置的默认 Cookie 过期时间。会话在超过该时长后销毁。当用户勾选"记住我"(remember me)时,该值会被 remember_me 覆盖。

remember_me

  • 类型:string,integer(duration 语法)
  • 默认值:1 month(源码中为 time.Hour * 24 * 30,即 30 天)
  • 必填:否

所有 cookies 配置的默认"记住我"过期时间。勾选记住我时,Cookie 过期与会话销毁周期使用该值。设置为 -1 可在全局层面禁用该功能(源码中 schema.RememberMeDisabled 对应的处理逻辑见 validateSession:命中时置 DisableRememberMe = true)。

cookies:多域名 Cookie 配置列表

cookies 是 Authelia 配置为处理会话的具体 Cookie 域名列表。未正确配置的域名会被 Authelia 自动拒绝。它允许管理员为多个 Cookie 域名定义各自独立的设置。该列表中的每个条目拥有与顶层几乎同名的选项,未设置时全部继承顶层默认值。

源码中的继承逻辑:validateSessionCookieName、validateSessionExpiration、validateSessionRememberMe、validateSessionSameSite 会依次把空值回填为顶层值;若顶层 same_site 非法,则回退到硬编码默认值 lax。

以下示例配置了单个域名 example.com:

session:
  cookies:
    - domain: 'example.com'
      authelia_url: 'https://auth.example.com'
      name: 'authelia_session'
      same_site: 'lax'
      inactivity: '5m'
      expiration: '1h'
      remember_me: '1d'

domain

  • 类型:string
  • 必填:是

会话 Cookie 所保护的域名。校验器(validateSessionDomainName)与文档共同规定该值必须满足以下约束:

  1. 必须是标准用途域名:即 URL 的主机名部分(不含端口),且全球可信的证书颁发机构(CA)愿意为其签发 X.509 证书(使用 TLS 是硬性要求);
  2. 必须是 authelia_url 主机名的有效后缀或与之完全匹配(校验器通过 utils.HasURIDomainSuffix 强制检查);
  3. 必须包含至少一个域名段,即至少有一个点(如 example.com;validateSessionDomainName 会对无点域名报错);
  4. 不能恰好匹配公共后缀(Public Suffix List)中的域名:浏览器对某些域名(如 duckdns.org)会完全拒绝写入 Cookie,应改用类似 example.duckdns.org 的形式。注意这意味着 example.duckdns.org 与 example-auth.duckdns.org 之间无法共享 Cookie;
  5. 不能是特殊用途域名(如 localhost),因为浏览器不允许这些域名设置 Authelia 正常运行所需的 Cookie。

此外,从源码校验还可以得到两个额外规则:

  • 域名不允许以 . 开头(会输出警告 errFmtSessionDomainHasPeriodPrefix);
  • 域名不允许携带端口(如 example.com:8080 会输出警告);
  • 不允许使用通配符形式 *.example.com(直接报错 errFmtSessionDomainMustBeRoot);
  • 列表中不允许出现重复或互相嵌套(suffix 关系)的域名,否则触发 errFmtSessionDomainDuplicate / errFmtSessionDomainDuplicateCookieScope 错误。

举例:若 Authelia 通过 https://auth.example.com 访问,则 domain 应为 auth.example.com 或 example.com 二者之一。

⚠️ 重要提示:浏览器对 Cookie 域名有严格的写入规则,特别是 Public Suffix List 中的域名通常不允许设置 Cookie。配置前务必确认目标域名不在该列表中。

authelia_url

  • 类型:string(URI 格式)
  • 必填:是

该 Cookie 域名对应的 Authelia 安装根 URL,用于在需要认证时生成正确的重定向地址。必须满足:

  1. 能够为该 domain 读写 Cookie(源码校验:authelia_url 的主机名必须是 domain 的后缀或相等,否则报 errFmtSessionDomainURLNotInCookieScope);
  2. 使用 https:// scheme(非绝对 URL 报 errFmtSessionDomainURLNotAbsolute,非安全 scheme 报 errFmtSessionDomainURLInsecure);
  3. 必要时包含路径:例如当通过 server address 选项指定了子路径、且门户无法从 https://example.com 直接访问时,应写成 https://example.com/authelia 而非 https://example.com。

特别地,校验器会对 authelia_url 的路径做规范化处理:如果路径既非空也非 /,且不以 / 结尾,会自动补上结尾的 /。

对应代理的适当查询参数或请求头可以覆盖此选项的行为(即认证重定向目标优先由代理侧传入参数决定)。

default_redirection_url

  • 类型:string(URI 格式)
  • 必填:否

完全可选的 URL,用于直接访问 Authelia 时作为重定向位置。此选项弃用了全局的 default_redirection_url 选项。必须满足:

  1. 能够为 domain 读写 Cookie(域名后缀校验同上);
  2. 使用 https:// scheme;
  3. 不能与 authelia_url 相同(源码中 utils.EqualURLs 检测到相等时直接报错)。

若未配置此选项,则必须通过对应代理的查询参数或请求头来指定重定向目标。另需注意:从源码看,一旦在 cookies 中配置了条目,同时又在全局配置了旧版 default_redirection_url,会触发弃用错误 errFmtSessionLegacyRedirectionURL;同理,旧的顶层 domain 写法与 cookies 并存也会报错。

name / same_site / inactivity / expiration / remember_me(cookie 级)

  • 类型:分别同顶层同名选项
  • 必填:否
  • 默认值:均继承自对应顶层选项
Cookie 级选项 默认来源 说明
name 顶层 name(authelia_session) 会话 Cookie 名称
same_site 顶层 same_site(lax) Cookie 的 SameSite 值,小写书写
inactivity 顶层 inactivity(5m) 空闲销毁时间,适合"长会话 + 闲置设备防护"
expiration 顶层 expiration(1h) Cookie 过期时间;勾选记住我后被 remember_me 覆盖
remember_me 顶层 remember_me(1M) 勾选记住我后的过期时间;设为 -1 可对该域名完全禁用该功能

Passkey 登录流程的特殊说明:当前 Passkey(WebAuthn)登录流程在启用记住我功能时要求会话被记住。原因是 WebAuthn 对话框对 UI 交互具有破坏性,而包括 Conditional Mediation 与 OpenID Connect 1.0 Relying Party 登录在内的多项未来特性,若必须先勾选复选框会显得笨拙。官方规划中,记住我状态的控制将演进为"用户完成初始登录后立即向其提问"的新交互形态。

安全注意事项

session 配置段直接影响整体安全态势,官方建议阅读 security measures 文档中的 Session Security 小节 了解更全面的安全措施。结合本文档与源码,核心安全要点可归纳为:

  • secret 必须使用高强度随机值(≥64 位随机字母数字字符串),并妥善保管,它直接决定 Redis 中会话密文的强度;
  • same_site 优先使用 lax,none 仅在完全信任所有受保护应用时考虑;
  • inactivity 与 expiration 应遵循最小化原则:长期会话配合空闲超时,降低闲置设备被利用的风险;
  • 高可用环境务必切换到 Redis/Sentinel 等无状态 Provider,避免多副本内存会话不一致;
  • Cookie 域名必须满足 CA 签发与 Public Suffix List 约束,否则浏览器根本不会写入 Cookie,认证流程将完全失效。

实战:完整配置示例

结合以上所有要点,一个面向生产环境(含 Redis 会话存储、多域名 Cookie)的完整配置如下,可在此基础上按需裁剪:

session:
  secret: 'a_64_character_random_alphanumeric_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: 'auth.example.com'
      authelia_url: 'https://auth.example.com'
      remember_me: '-1'
  redis:
    host: 'redis.example.com'
    port: 6379
    username: 'authelia'
    password: 'another_64_character_random_alphanumeric_secret'
    database_index: 0
    maximum_active_connections: 8
    minimum_idle_connections: 0
    tls:
      server_name: 'redis.example.com'
      skip_verify: false
      minimum_version: 'TLS1.2'

其中 Redis 相关的完整选项(含 timeout、max_retries、tls.certificate_chain、tls.private_key、high_availability.sentinel_name、sentinel_username、sentinel_password、nodes、route_by_latency、route_randomly 等)的逐项说明与完整示例,请直接参阅 Redis 会话配置文档,本文不再展开。各 Redis 选项的源码默认值(端口 6379、超时 5s、最大重试 0、最大活跃连接 8、TLS 最低版本 TLS1.2 等)均可在 internal/configuration/schema/session.go 的 DefaultRedisConfiguration 中查到,Sentinel 模式下节点端口默认 26379。

总结

session 配置是 Authelia 认证链路中承上启下的关键一环:cookies 列表决定了哪些域名可以被服务、Cookie 如何写入;secret 与 same_site 等选项决定了会话数据的安全边界;而 Provider 的选型(Memory / Redis / Redis Sentinel)则直接关系到生产环境的高可用能力。配置时建议以官方文档(本文所依据的 docs/content/configuration/session/introduction.md)为主体,对照 internal/configuration/validator/session.go 中的校验规则逐项自查,即可避免绝大多数由域名、URL 或 Cookie 属性引起的认证故障。

登录后查看全文
authelia