Authelia Session 配置完全指南:Cookie 会话与 Redis 存储的实战与源码解析
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 条必须满足的规则:
- 必须是标准的公开使用域,即 URL 中主机名部分(不含端口),且全局受信任的证书颁发机构愿意为其签发 X.509 证书(TLS 是硬性要求);
- 必须是
authelia_url主机名部分的有效后缀或与之完全匹配; - 必须至少包含一个域段(即一个句点
.); - 不得与公开后缀列表(Public Suffix List)中的域完全匹配,例如
duckdns.org是不允许的,应写成example.duckdns.org这类形式——浏览器会拒绝为这类域设置任何 Cookie;因此如果你同时拥有example.duckdns.org和example-auth.duckdns.org,它们之间无法共享 Cookie; - 不得是
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,用于在需要认证时生成合适的重定向地址。它必须:
- 能够为配置的
domain读写 Cookie; - 使用
https://协议; - 在必要时包含路径,例如当你通过
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 配置说明)。它必须:
- 能够为配置的
domain读写 Cookie; - 使用
https://协议; - 不能与
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 分钟时会话即被销毁。
综合实践建议:
- 生产环境使用 Redis 或 Redis Sentinel,保持 Authelia 无状态,支持多实例与 Kubernetes 部署;
secret使用 64+ 字符的随机字母数字串,作为最高优先级的密钥管理项;same_site保持lax,仅在完全可控的内网场景才考虑none;- 严格按 5 条规则配置
domain,避免使用公开后缀域导致 Cookie 完全失效; - 为每个 Cookie 域显式配置
authelia_url,并视需要设置default_redirection_url; - 多实例部署时必须配置 Redis TLS 与连接池参数,并遵循 Sentinel 的
host/nodes组合要求。