Authelia Session 配置完全指南:会话 Cookie、多域名与 Redis 会话存储
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 段由两大部分组成:
- Cookie 公共默认值:
name、same_site、inactivity、expiration、remember_me,它们作为cookies列表中每个条目的默认值来源; 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)与文档共同规定该值必须满足以下约束:
- 必须是标准用途域名:即 URL 的主机名部分(不含端口),且全球可信的证书颁发机构(CA)愿意为其签发 X.509 证书(使用 TLS 是硬性要求);
- 必须是
authelia_url主机名的有效后缀或与之完全匹配(校验器通过utils.HasURIDomainSuffix强制检查); - 必须包含至少一个域名段,即至少有一个点(如
example.com;validateSessionDomainName会对无点域名报错); - 不能恰好匹配公共后缀(Public Suffix List)中的域名:浏览器对某些域名(如
duckdns.org)会完全拒绝写入 Cookie,应改用类似example.duckdns.org的形式。注意这意味着example.duckdns.org与example-auth.duckdns.org之间无法共享 Cookie; - 不能是特殊用途域名(如
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,用于在需要认证时生成正确的重定向地址。必须满足:
- 能够为该
domain读写 Cookie(源码校验:authelia_url的主机名必须是domain的后缀或相等,否则报errFmtSessionDomainURLNotInCookieScope); - 使用
https://scheme(非绝对 URL 报errFmtSessionDomainURLNotAbsolute,非安全 scheme 报errFmtSessionDomainURLInsecure); - 必要时包含路径:例如当通过 server address 选项指定了子路径、且门户无法从
https://example.com直接访问时,应写成https://example.com/authelia而非https://example.com。
特别地,校验器会对 authelia_url 的路径做规范化处理:如果路径既非空也非 /,且不以 / 结尾,会自动补上结尾的 /。
对应代理的适当查询参数或请求头可以覆盖此选项的行为(即认证重定向目标优先由代理侧传入参数决定)。
default_redirection_url
- 类型:
string(URI 格式) - 必填:否
完全可选的 URL,用于直接访问 Authelia 时作为重定向位置。此选项弃用了全局的 default_redirection_url 选项。必须满足:
- 能够为
domain读写 Cookie(域名后缀校验同上); - 使用
https://scheme; - 不能与
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 属性引起的认证故障。