Authelia 前置认证的价值很明确:在业务应用之前加一道统一身份门,没有通过单点登录与双因素校验的请求根本到不了后端。相比在每个面板里各改一套登录逻辑,把认证抽到反向代理层的收益是可审计、可统一策略、可一处下线。
多数团队的现状是「每个面板一套账号」:GitLab 有 GitLab 的密码,Grafana 有 Grafana 的密码,Wiki 用的是第三套,其中只有一两个支持双因素。运维要记十几组口令,离职人员清理时漏掉一个就是长期后门。用 Nginx 的 auth_request 把认证外置,应用连改配置都不需要,这是性价比最高的一步。
适用场景
- 内网有多个自建面板(GitLab、Grafana、Wiki、Jenkins),每个都要单独建号,人员变动时逐个清理容易遗漏
- 等保或内部审计要求「统一身份认证 + 双因素」,但业务应用本身不支持 2FA,也不允许改代码
- 需要按组下发差异化策略:开发组访问 Git 强制双因素,行政组访问 Wiki 单因素即可
- 出现过针对登录接口的撞库,需要一处集中查看失败次数并自动封禁来源 IP
前置条件
- Authelia 4.38 及以上(Docker 镜像
authelia/authelia:4.38,或官方 deb 包) - 一个独立认证域名
auth.example.com及有效证书,且与受保护业务域同属一个父域,否则会话 Cookie 无法共享 - Nginx 1.24 及以上,官方包默认已包含
auth_request模块(nginx -V中可见--with-http_auth_request_module) - 配置目录
/opt/authelia/config,需持久化保存db.sqlite3与users_database.yml - 注意:Authelia 自身不提供 HTTPS,只监听 9091 明文端口,必须由 Nginx 终结 TLS 并限制该端口仅本机可达
原理说明
Authelia 走的是 forward-auth 模式,不是 OAuth 回调。Nginx 收到请求后,先向 Authelia 发一个内部子请求问「这个请求放不放」,Authelia 回 200 表示放行、401 表示需要登录,Nginx 据此决定转发给后端还是 302 到登录页。整个过程业务应用无感知,也就不存在「改代码接 SSO」的成本。
4.38 的认证子请求地址是 /api/authz/auth-request,旧版的 /api/verify 已废弃,照旧教程抄会拿到 404。放行时响应头里带 Remote-User、Remote-Groups、Remote-Email 三个字段,Nginx 用 auth_request_set 取出后转给后端,这是「认证通过后把身份传给应用」的唯一通道。不配这一段,应用拿到的永远是匿名请求。
策略判定完全由 access_control 决定,规则自下而上匹配、命中即停。四个策略档位含义不同:bypass 不校验直接放行(只给登录页自己用)、one_factor 只校验口令、two_factor 强制第二因子、deny 直接拒绝。default_policy 必须设为 deny——默认放行等于所有规则白写。
口令存储用的是 Argon2id,默认参数内存 64MB、迭代 3 轮、并行度 4。这是内存硬算法,单次校验就要占 64MB,离线爆破的单价远高于 sha512crypt,这也是为什么用户库里不该出现任何 md5 或 sha1 形态的摘要。
防爆破由 regulation 承担:max_retries 次失败落在 find_time 窗口内即封禁 ban_time,计数维度是「用户名 + 来源 IP」。它拦的是在线撞库,与口令哈希强度是两件互补的事,缺一不可。
操作步骤
1. 生成密钥与目录
三个密钥必须用密码学随机源生成,不要手敲:
sudo mkdir -p /opt/authelia/config
cd /opt/authelia
# 会话密钥:填 session.secret
docker run --rm authelia/authelia:4.38 \
authelia crypto rand --length 64 --charset alphanumeric
# 存储加密密钥:填 storage.encryption_key(至少 20 字符,建议 32)
docker run --rm authelia/authelia:4.38 \
authelia crypto rand --length 32 --charset alphanumeric
# 重置口令令牌密钥:填 identity_validation.reset_password.jwt_secret
docker run --rm authelia/authelia:4.38 \
authelia crypto rand --length 64 --charset alphanumeric
encryption_key 一旦更换,数据库里已加密的 TOTP 种子与 WebAuthn 凭据全部作废,所有用户都要重新绑定。生成后立刻连同 db.sqlite3 一起进密码管理器备份,不要只留在服务器上。
2. 主配置文件
把上一步的三个值填进对应位置,其余保持默认即可。注意 cookies.domain 要写父域 example.com(前面带点或不带都能匹配),写具体子域会导致跨站不共享登录态:
---
theme: dark
default_2fa_method: totp
server:
address: 'tcp://0.0.0.0:9091'
log:
level: info
format: text
totp:
issuer: auth.example.com
period: 30
skew: 1
identity_validation:
reset_password:
jwt_secret: '<64位随机串>'
authentication_backend:
file:
path: /config/users_database.yml
password:
algorithm: argon2id
argon2:
variant: argon2id
iterations: 3
memory: 65536
parallelism: 4
key_length: 32
salt_length: 16
password_reset:
disable: false
access_control:
default_policy: deny
rules:
- domain: 'auth.example.com'
policy: bypass
- domain: 'git.example.com'
subject: ['group:devs']
policy: two_factor
- domain: 'wiki.example.com'
subject: ['group:staff']
policy: one_factor
session:
secret: '<64位随机串>'
name: authelia_session
expiration: 1h
inactivity: 10m
remember_me: 1M
cookies:
- domain: example.com
authelia_url: https://auth.example.com
default_redirection_url: https://portal.example.com
regulation:
max_retries: 5
find_time: 2m
ban_time: 10m
storage:
encryption_key: '<32位随机串>'
local:
path: /config/db.sqlite3
notifier:
filesystem:
filename: /config/notifications.txt
default_policy: deny 是整份配置的地基,先全拒再逐条放行,新增业务域名时忘记写规则的结果是「打不开」,而不是「裸奔」。notifier 先用文件后端把通知写到本地,验证链路通了再换成 SMTP,避免一上来就被邮件配置卡住。
3. 用户库与口令哈希
口令必须先算出 Argon2id 摘要再落盘,配置里不接受明文:
docker run --rm authelia/authelia:4.38 \
authelia crypto hash generate argon2 --password 'ChangeMe_2026!'
命令输出里的 Digest 就是用户库中 password 字段的完整值,形如 $argon2id$v=19$m=65536,t=3,p=4$...。groups 里的组名要与 access_control 的 group: 前缀对应:
users:
alice:
displayname: "Alice"
password: "$argon2id$v=19$m=65536,t=3,p=4$<盐>$<摘要>"
email: alice@example.com
groups:
- devs
- staff
bob:
displayname: "Bob"
password: "$argon2id$v=19$m=65536,t=3,p=4$<盐>$<摘要>"
email: bob@example.com
groups:
- staff
文件权限要收到 600:chmod 600 /opt/authelia/config/users_database.yml。这份文件是离线爆破的首要目标,权限放宽等于把口令摘要公开。
4. 启动并初始化存储
cat > /opt/authelia/docker-compose.yml <<'EOF'
services:
authelia:
image: authelia/authelia:4.38
container_name: authelia
volumes:
- ./config:/config
ports:
- '127.0.0.1:9091:9091'
restart: unless-stopped
environment:
- TZ=Asia/Shanghai
EOF
cd /opt/authelia
docker compose up -d
# 建表(首次必须执行,否则登录时报 storage 错误)
docker exec authelia authelia storage migrate up --config /config/configuration.yml
# 配置语法自检
docker exec authelia authelia validate-config /config/configuration.yml
端口映射写成 127.0.0.1:9091:9091 是刻意的:9091 是明文 HTTP,直接暴露到公网等于把口令以明文传输。外部访问一律走 Nginx 的 443。
双因素种子不要在界面上让用户自己绑,运维侧直接生成二维码更可控(--username 指定账号,命令会打印一次性注册链接):
docker exec -it authelia authelia storage user totp generate \
--username alice --config /config/configuration.yml
5. Nginx 认证中枢
先给认证域本身配一个普通反代,注意关闭可能干扰 Cookie 的缓冲设置:
server {
listen 443 ssl;
http2 on;
server_name auth.example.com;
ssl_certificate /etc/letsencrypt/live/auth.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/auth.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
add_header Strict-Transport-Security "max-age=31536000" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
location / {
proxy_pass http://127.0.0.1:9091;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
6. 业务站点接入 auth_request
关键在三个 auth_request_set:第一个拼出回跳地址,后两个把身份透传给后端。缺失 Remote-User 时,后端日志里全是匿名访问,等于认证做了但审计做不了:
server {
listen 443 ssl;
http2 on;
server_name git.example.com;
ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
# 内部子请求:只允许 Nginx 自己调用
location = /internal/authz {
internal;
proxy_pass http://127.0.0.1:9091/api/authz/auth-request;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
proxy_set_header X-Original-Method $request_method;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-URI $request_uri;
proxy_set_header X-Forwarded-For $remote_addr;
}
location / {
auth_request /internal/authz;
auth_request_set $target_url $scheme://$http_host$request_uri;
auth_request_set $auth_user $upstream_http_remote_user;
auth_request_set $auth_group $upstream_http_remote_groups;
error_page 401 =302 https://auth.example.com/?rd=$target_url;
proxy_set_header Remote-User $auth_user;
proxy_set_header Remote-Groups $auth_group;
proxy_set_header Host $host;
proxy_pass http://10.0.0.21:3000;
}
}
改完执行 nginx -t 再 systemctl reload nginx。注意 error_page 401 必须放在 location 内且用 =302 改写状态码,否则浏览器会看到一个 401 空白页而不是登录界面。
7. 策略按组分层
规则顺序即优先级,越具体的放前面,兜底放最后。下面这段表达的是:认证域自身放行、Git 只给开发组且强制双因素、Wiki 全员工单因素、其余一律拒绝:
access_control:
default_policy: deny
rules:
- domain: 'auth.example.com'
policy: bypass
- domain:
- 'git.example.com'
subject:
- 'group:devs'
policy: two_factor
- domain: 'wiki.example.com'
subject:
- 'group:staff'
- 'group:devs'
policy: one_factor
- domain: 'grafana.example.com'
subject:
- 'group:ops'
policy: two_factor
networks:
- '10.0.0.0/8'
networks 让同一条规则可以叠加来源网段限制:上例中只有内网来源的 ops 组才能进 Grafana,公网即便登录成功也会被拒。策略改完 docker exec authelia authelia validate-config 再 restart,Authelia 不支持热加载。
配置验证
# 1) 健康检查,应返回 200 OK
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9091/api/health
# 2) 未登录访问受保护站点,应 302 到认证域并带 rd 参数
curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' https://git.example.com/
# 3) 9091 不应出现在公网网卡
ss -tlnp | grep 9091
# 4) 认证域安全头
curl -sI https://auth.example.com | grep -iE 'strict-transport|x-frame|content-security'
# 5) 配置与存储状态
docker exec authelia authelia validate-config /config/configuration.yml
docker exec authelia authelia storage user identities list --config /config/configuration.yml
预期结果:健康检查 200;未登录访问返回 302 且跳转地址形如 https://auth.example.com/?rd=https%3A%2F%2Fgit.example.com%2F;9091 只绑定 127.0.0.1;身份列表里能看到 step 3 建的账号。若第 2 步返回 200,说明 access_control 命中了 bypass 或子请求根本没发出去,先查 nginx -T | grep auth_request。
常见问题
FAQ 1:登录成功后又跳回登录页,反复循环怎么办?
九成是 Cookie 域不匹配。浏览器只在「请求域与 Cookie 域相同或是其子域」时才回传 Cookie,如果 session.cookies[].domain 写成 auth.example.com,那么对 git.example.com 的请求就带不上这个 Cookie。改成父域 example.com 即可。第二种可能是 authelia_url 与实际访问协议不一致(写成 http),HTTPS 下 Cookie 会被标记 Secure 而拒绝发送。
FAQ 2:认证已经通过,后端应用的日志里仍然是匿名用户?
先确认 auth_request_set $auth_user $upstream_http_remote_user; 与 proxy_set_header Remote-User $auth_user; 两行都在,且变量名大小写与 Authelia 返回头一致(Remote-User,中划线不是下划线)。其次确认后端确实读取该请求头:GitLab 需要打开 X-Forwarded-User 或对应的 omniauth 配置,纯静态站点则无从读取——这类站点只能用 auth_request 做准入控制,身份透传没有意义。
FAQ 3:账号被 regulation 锁死后如何立即解锁?
等待 ban_time 到期是最省事的做法(默认 10 分钟)。要立刻解封,重置该账号的下一次失败计数即可:docker exec authelia authelia storage user regulation reset --username alice --config /config/configuration.yml。若整个网段被误封,检查是否有反向代理把真实 IP 覆盖成同一个值——X-Forwarded-For 没透传时,所有请求看起来都来自 Nginx 本机,一次撞库就会把全站锁死。
总结
Authelia 的加固逻辑是「先立门、再分级、后兜底」。default_policy: deny 立住门框,access_control 按组与网段分级,auth_request 加 Remote-User 透传解决「认证了但审计不到人」,Argon2id 用户库加 regulation 解决口令侧风险,最后把 9091 收回回环。四项配完,原本十几套独立账号收成一个入口,人员离职只要从 users_database.yml 删一行、重启容器即可,比在十个面板里点十次删除可靠得多。