Authelia Session 配置完全指南:Cookie 会话与 Redis 存储的实战与源码解析

原创2026-10-10 21:15:011,457 阅读
文章标签:认证鉴权单点登录身份认证后端网络安全前端

Authelia Session 配置完全指南:Cookie 会话与 Redis 存储的实战与源码解析

Authelia 依赖会话(Session)Cookie 对受保护的 Web 应用进行授权判定,本文围绕 session 配置节展开,系统讲解会话 Cookie 的域(domain)规则、有效期参数(inactivity / expiration / remember_me)、多域 Cookie 覆盖机制,以及 Memory 与 Redis / Redis Sentinel 三种会话存储 Provider 的选型与配置。读完本文,你将掌握 Authelia 会话体系从配置到校验、再到底层存储实现的全链路知识,能够在单域、多域乃至 Kubernetes 高可用场景下正确、安全地落地会话配置。

Session 配置节的作用与定位

Authelia 官方文档指出:Authelia 依赖会话 Cookie 来授权用户访问各类受保护的网站,session 配置节负责控制会话 Cookie 的行为,以及 Authelia 可以为哪些域名提供授权请求服务(参见 docs/content/configuration/session/introduction.md)。

在实际运行中,会话生命周期由 internal/session 包承载:GetSession / SaveSession / DestroySession / RegenerateSession / UpdateExpiration 等方法封装了底层会话的读取、保存、销毁、ID 轮换与过期时间更新(参见 internal/session/session.go),而 Cookie 的名称、域、SameSite、Secure 等属性在 internal/session/provider_config.go 中完成装配。理解这些底层实现,有助于判断每个配置项的真实行为。

配置速览:一份可直接对照的完整 YAML

官方文档给出的最小完整示例覆盖了全局默认值与 cookies 多域列表两种写法:

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'

要点说明:

  • 顶层 name / same_site / inactivity / expiration / remember_me 是全局默认值,cookies 列表中未显式指定的项会逐级继承这些默认值;
  • secret 是 Redis 会话数据的加密密钥(使用 Memory Provider 时同样要求配置);
  • cookies 列表中的每个条目代表一个被保护的 Cookie 域,可以拥有完全独立的时间参数。

仓库根目录的 config.template.yml 提供了带完整注释的参考模板,其中明确说明:inactivity、expiration、remember_me 三个值支持"秒"或 Authelia 通用的 duration 语法(如 5m、1h、1 month),且"这三个值都影响 Cookie/会话的有效期,越长的有效期越不安全,因为被盗的 Cookie 存活越久,给攻击者的侦察和攻击时间越多"。

全局默认项详解

secret

secret 是必填的字符串类型(配置类型标注为 string, required=yes, secret=yes),其作用是用作 Redis 会话数据的加密密钥。

官方文档强烈建议使用 64 个及以上字符的随机字母数字字符串。从源码看,该密钥在 Redis Provider 场景下通过 NewEncryptingSerializer 派生为 256 位密钥,并使用 AES-GCM 对会话数据进行加密(参见 internal/session/encrypting_serializer.go),因此密钥强度直接决定会话数据的保密性。

name

name 为字符串类型,默认值为 authelia_session,非必填。它是所有 cookies 配置中 Cookie 名称的默认值。schema 中同样定义了这一默认值(参见 internal/configuration/schema/session.go)。

same_site

same_site 为字符串类型,默认值为 lax,非必填。它作为所有 cookies 配置中 SameSite 属性的默认值。schema 定义其可枚举值为 lax、strict、none(见 internal/configuration/schema/session.go)。

inactivity

inactivity 为 string,integer 类型,采用 duration 语法,默认值为 5 minutes,非必填。它代表用户不活动多久后会话被销毁,适合在需要较长会话总时长、但又不想让闲置设备长期暴露风险的场景。校验器对非正值会自动回落到默认值(见 internal/configuration/validator/session.go)。

expiration

expiration 为 string,integer 类型,duration 语法,默认值为 1 hour,非必填。它代表Cookie 过期前的时间,即未勾选 remember me 时会话的存活上限。校验逻辑同样会对非正值回落到 1 小时默认值(见 internal/configuration/validator/session.go)。

remember_me

remember_me 为 string,integer 类型,duration 语法,默认值为 1 month,非必填。当用户勾选"记住我"(Remember Me)复选框时,用它覆盖 expiration。将其设置为 -1 可整体禁用该功能。schema 中定义了常量 RememberMeDisabled = -1 second(见 internal/configuration/schema/const.go),校验器检测到该值时会将 DisableRememberMe 置为 true(见 internal/configuration/validator/session.go)。

官方文档还专门提示:Passkey 登录流程当前要求会话处于"被记住"状态,因为 WebAuthn 对话框会打断 UI 操作,且未来的 Conditional Mediation 以及 OpenID Connect 1.0 Relying Party 登录场景若要求先勾选复选框会显得笨拙;未来"记住我"将演进为在用户完成初次登录后立即询问的问题。

cookies:多域会话 Cookie 配置

cookies 是 Authelia 被配置来处理的具体 Cookie 域列表。官方文档强调:未正确配置的域会被 Authelia 自动拒绝。该列表允许管理员为多个会话 Cookie 域分别定义独立设置。

domain(必填)

domain 是会话 Cookie 所保护的目标域。官方文档给出了 5 条必须满足的规则:

  1. 必须是标准的公开使用域,即 URL 中主机名部分(不含端口),且全局受信任的证书颁发机构愿意为其签发 X.509 证书(TLS 是硬性要求);
  2. 必须是 authelia_url 主机名部分的有效后缀或与之完全匹配;
  3. 必须至少包含一个域段(即一个句点 .);
  4. 不得与公开后缀列表(Public Suffix List)中的域完全匹配,例如 duckdns.org 是不允许的,应写成 example.duckdns.org 这类形式——浏览器会拒绝为这类域设置任何 Cookie;因此如果你同时拥有 example.duckdns.org 和 example-auth.duckdns.org,它们之间无法共享 Cookie;
  5. 不得是 localhost 之类的特殊用途域,因为浏览器不允许站点为这些域设置 Authelia 正常运行所需的 Cookie。

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

校验器对上述规则有完整的源码实现:拒绝以 *. 开头的通配域、拒绝不含句点的域、拒绝命中公开后缀列表的域,并对以 . 开头或包含端口号的域发出警告(见 internal/configuration/validator/session.go)。测试用例也验证了 duckdns.org 会被判定为"special public suffix list"错误(见 internal/configuration/validator/session_test.go)。

authelia_url(必填)

authelia_url 是该 Cookie 域下 Authelia 安装的根 URL,用于在需要认证时生成合适的重定向地址。它必须:

  1. 能够为配置的 domain 读写 Cookie;
  2. 使用 https:// 协议;
  3. 在必要时包含路径,例如当你通过 server.address 指定了子路径时,应写成 https://example.com/authelia 而非 https://example.com(参考 server.address 配置)。

相关代理的查询参数或请求头可以覆盖此行为。校验器会强制 URL 为绝对地址且使用安全协议,并检查 authelia_url 的主机名必须位于 domain 的 Cookie 作用域内(见 internal/configuration/validator/session.go)。

default_redirection_url(可选)

default_redirection_url 是完全可选的 URL,用于用户直接访问 Authelia 时的重定向目的地,它取代了全局的 default_redirection_url 配置(见 miscellaneous 配置说明)。它必须:

  1. 能够为配置的 domain 读写 Cookie;
  2. 使用 https:// 协议;
  3. 不能与 authelia_url 相同。

若未配置此项,则必须借助相关代理的查询参数或请求头完成重定向。校验器会检查该 URL 与 authelia_url 是否相等(相等时报错),并确保其处于 Cookie 域作用域内(见 internal/configuration/validator/session.go)。

name / same_site / inactivity / expiration / remember_me(cookies 列表内)

这五个子项分别继承顶层同名设置作为默认值,用于对特定域做覆盖:

  • name:会话 Cookie 的名称,默认继承顶层的 name;
  • same_site:Cookie 的 SameSite 属性值。官方文档特别指出:提供该配置选项之前默认值为 None,新默认值是 Lax,且配置必须使用小写(例如想设置为 Strict,配置中需写 strict)。总体而言 Lax 对 Authelia 是最理想的取值;None 只在完全清楚后果且信任全部受保护应用时才推荐;Strict 在很多场景下不适用,官方未在此状态下进行过测试,但作为选项保留。底层实现将 lax / strict / none 分别映射到 fasthttp 的三种 Cookie SameSite 模式,其余取值一律回落为 Lax(见 internal/session/provider_config.go);
  • inactivity:该域会话因不活动被销毁的时长;
  • expiration:该域 Cookie 过期、会话被销毁的时间,勾选 remember me 时被 remember_me 覆盖;
  • remember_me:勾选 remember me 时该域 Cookie 的过期时间,设置为 -1 会完全禁用该域的此功能。

会话存储 Provider:选型与场景

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

Provider 特性 场景建议
Memory 默认,有状态,无需额外配置 单实例、开发调试
Redis 无状态 生产环境推荐
Redis Sentinel 无状态、高可用 生产环境、多实例、Kubernetes

官方文档明确指出:在 Kubernetes 或其他高可用场景中,有状态的 Provider 不被推荐,应优先选择标注为"无状态"的 Provider(相关讨论可参见 statelessness 文档)。这是因为多实例部署下,有状态的 Memory 会话无法在实例间共享。

从源码结构看,NewSessionProvider 根据 session.redis 是否配置选择 Memory、Redis 或 Redis Sentinel,并据此决定会话数据的序列化方式(见 internal/session/provider_config.go)。

Redis Provider:连接、认证与连接池

在 session 下配置 redis 子节即启用 Redis 会话存储。官方文档强调:默认使用内存 Provider,不配置 redis 会使 Authelia 保持有状态;在高可用场景中配置本项非常重要,且在生产环境中被强烈推荐。

host(必填)

Redis 的地址或 Unix socket 路径。若使用 IPv6 字面量地址,必须用方括号括起并加引号:

host: '[fd00:1111:2222:3333::1]'

源码中,当 port 为 0 时网络类型会被判定为 unix,直接以 host 作为 socket 地址(见 internal/session/provider_config.go);校验器对绝对路径形式的 host 不再要求端口号(见 internal/configuration/validator/session.go)。

port

端口,整数类型,默认值 6379,非必填。

timeout

连接超时,string,integer 类型,duration 语法,默认值 5 seconds,非必填。

max_retries

失败命令的最大重试次数,整数类型,默认值 0。设置为 0 表示完全禁用重试。注意 schema 中该字段的 JSON Schema 默认标注为 3,但运行时的 DefaultRedisConfiguration 实际默认值是 0(见 internal/configuration/schema/session.go),以文档描述与实际代码为准。

username / password

  • username(可选):Redis 认证用户名,仅在 Redis 6.0+ 支持,且 Redis 目前向后兼容仅密码认证;除非你配置了 Redis ACL,否则通常无需设置;
  • password(可选,敏感项):Redis 认证密码。官方强烈建议使用 64 个及以上字符的随机字母数字字符串,并将用户密码修改为该值。

database_index

数据库索引号,整数类型,默认值 0,即与 Redis SELECT 命令指定的数据库号一致。

maximum_active_connections / minimum_idle_connections

  • maximum_active_connections:同一时刻到 Redis 的最大连接数,整数,默认值 8;
  • minimum_idle_connections:在不超过最大活跃连接的前提下保持打开的最小空闲连接数,整数,默认值 0,在建立连接耗时较长时比较有用。

这两个值在 provider 构建时分别映射到连接池的 PoolSize 与 MinIdleConns(见 internal/session/provider_config.go),连接最大空闲时间为 300 秒。

tls

tls 为结构体(TLS 结构),可选。一旦定义即启用 TLS socket 连接,并控制到 Redis 服务器的 TLS 连接校验参数。默认情况下 Authelia 使用系统证书信任链进行 TLS 证书校验,可通过全局的 certificates_directory 选项扩充信任范围。TLS 配置支持 server_name、skip_verify、minimum_version(默认 TLS1.2)、maximum_version、certificate_chain 与 private_key。校验器在配置 TLS 时会自动以 Redis host 作为默认 server_name,并校验 TLS 版本配置(见 internal/configuration/validator/session.go)。

Redis Sentinel 高可用配置

在 redis 下配置 high_availability 子节即启用 Redis Sentinel 连接。官方文档提到未来可能加入 Redis Cluster 支持。

sentinel_name(必填)

Sentinel 主节点(master)名称。注意它是你 Redis Sentinel 配置中定义的名字,不是主机名。当前高可用配置必须定义此项。

sentinel_username / sentinel_password

  • sentinel_username(可选):Sentinel 连接用户名。若提供该值,Authelia 将使用 ACL 认证连接 Sentinel;否则使用传统的 requirepass 认证;
  • sentinel_password(可选,若提供 sentinel_username 则必填):Sentinel 连接密码。与 sentinel_username 一起提供时走 ACL 认证,否则走 requirepass 认证。同样强烈建议使用 64+ 字符的随机字母数字字符串。

源码中,Sentinel 场景使用 redis.NewFailover,将上述值分别映射为 SentinelUsername / SentinelPassword,并把 route_by_latency、route_randomly 映射到 RouteByLatency、RouteRandomly(见 internal/session/provider_config.go)。

nodes

Sentinel 节点列表,用于负载均衡。官方文档要求:必须定义 redis.host 或至少一个 Sentinel 节点;且此时 redis.host 必须是 Sentinel 主机而非普通 Redis 主机,各实际 Redis 主机由 Sentinel 命令动态确定。每个节点包含 host 与 port:

- host: redis-sentinel-0
  port: 26379
  • 节点 host:该 Sentinel 节点的主机名(schema 中标注为 boolean 属于文档笔误,实为字符串主机名,参见 internal/configuration/schema/session.go);
  • 节点 port:默认值 26379。

源码中,host 与各节点的 host:port 会被汇总去重后作为 SentinelAddrs 传入 Failover 配置(见 internal/session/provider_config.go)。

route_by_latency / route_randomly

两个布尔选项,默认均为 false:

  • route_by_latency:设为 true 时优先选择低延迟的 Sentinel 节点;
  • route_randomly:设为 true 时随机选择 Sentinel 节点。

Redis 存储的底层细节

当启用 Redis 时,Authelia 会以 authelia-session 作为会话 Key 前缀(见 internal/session/provider_config.go 与同文件 L171),并使用 AES-GCM(256 位密钥)加密序列化会话数据(见 internal/session/encrypting_serializer.go)。这就是 session.secret 之所以重要的原因:即使 Redis 数据泄露,会话内容也无法被解密。

配置校验规则与合法值汇总

结合 internal/configuration/validator/session.go 与 schema 定义,可将关键校验规则汇总如下:

  • 未配置 cookies 时提示必填错误;使用旧版顶层 domain 时会产生警告并自动转换为 cookies 条目(见 validateSessionCookieDomains 与 validateSession 中的迁移逻辑);
  • domain 不允许以 . 开头(警告)、不允许包含端口(警告)、不允许 *. 通配、不允许不含句点、不允许命中公开后缀列表、不允许与既有 Cookie 域重复或互相存在后缀重叠(validateSessionUniqueCookieDomain);
  • authelia_url 与 default_redirection_url 必须是绝对 URL 且为 https://,主机名必须位于对应 domain 的 Cookie 作用域内,且二者不能相同;
  • same_site 的合法值为 lax、strict、none(小写),非法值会被校验器拒绝并报错,测试用例 TestShouldRaiseErrorWhenSameSiteSetIncorrectlyGlobal 等对此有覆盖;
  • inactivity、expiration、remember_me 的非正值(除 -1 禁用 remember me 外)会被自动回落为默认值。

安全建议与最佳实践

官方安全文档 measures.md 中专门讨论了会话安全:最重要的配置是会话密钥(secret),它用于在 Redis 中加密会话数据,应尽量长且随机;会话有效期高度可配置,例如在高安全要求的场景,可将 remember_me 设为 0(文档语境下即禁用)、expiration 设为 2 小时、inactivity 设为 10 分钟,这样 Cookie 年龄超过 2 小时或用户不活动超过 10 分钟时会话即被销毁。

综合实践建议:

  1. 生产环境使用 Redis 或 Redis Sentinel,保持 Authelia 无状态,支持多实例与 Kubernetes 部署;
  2. secret 使用 64+ 字符的随机字母数字串,作为最高优先级的密钥管理项;
  3. same_site 保持 lax,仅在完全可控的内网场景才考虑 none;
  4. 严格按 5 条规则配置 domain,避免使用公开后缀域导致 Cookie 完全失效;
  5. 为每个 Cookie 域显式配置 authelia_url,并视需要设置 default_redirection_url;
  6. 多实例部署时必须配置 Redis TLS 与连接池参数,并遵循 Sentinel 的 host / nodes 组合要求。
登录后查看全文
authelia