Authelia 前置认证加固实战:双因素与访问控制

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 删一行、重启容器即可,比在十个面板里点十次删除可靠得多。