Authelia SSO 认证网关¶

一句话概述：Authelia 是开源的 SSO（单点登录）认证网关，给你所有自建服务加一个统一的登录页面，支持双因素认证（TOTP/WebAuthn）、访问控制策略，配合 Nginx/Traefik 使用。

核心知识点¶

概念	白话解释
SSO	单点登录，登录一次就能访问所有服务
2FA/MFA	双因素/多因素认证，密码 + 手机验证码
TOTP	基于时间的一次性密码（Google Authenticator）
WebAuthn	硬件密钥认证（YubiKey、指纹）
反向代理集成	Authelia 不直接面对用户，通过 Nginx/Traefik 代理
访问控制	按域名、路径、用户组设置不同的认证级别

安装配置¶

Docker Compose（推荐）¶

# docker-compose.yml
version: "3"
services:
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    volumes:
      - ./authelia:/config  # 配置文件目录
    ports:
      - "9091:9091"  # Authelia Web 端口
    environment:
      - TZ=Asia/Shanghai
    restart: unless-stopped

配置文件¶

# authelia/configuration.yml
server:
  address: 'tcp://:9091'  # 监听端口

log:
  level: info  # 日志级别

totp:
  issuer: 'My Services'  # TOTP 显示名称
  period: 30  # 验证码有效期（秒）

authentication_backend:
  file:
    path: /config/users_database.yml  # 用户数据库文件

access_control:
  default_policy: deny  # 默认拒绝所有访问
  rules:
    - domain: public.example.com  # 公开访问
      policy: bypass  # 无需认证
    - domain: '*.example.com'  # 所有子域名
      policy: one_factor  # 需要密码登录
    - domain: admin.example.com  # 管理后台
      policy: two_factor  # 需要密码 + 2FA
      subject:
        - 'group:admins'  # 只有 admins 组的用户

session:
  name: authelia_session  # Cookie 名称
  secret: your_session_secret  # 会话密钥
  cookies:
    - domain: example.com  # Cookie 域
      authelia_url: https://auth.example.com  # Authelia 地址

storage:
  local:
    path: /config/db.sqlite3  # SQLite 存储（小规模用）

notifier:
  filesystem:
    filename: /config/notification.txt  # 通知文件（测试用）
  # smtp:  # 生产环境用邮件
  #   host: smtp.gmail.com
  #   port: 587
  #   username: your@gmail.com
  #   password: app_password
  #   sender: noreply@example.com

用户数据库¶

# authelia/users_database.yml
users:
  admin:
    displayname: "管理员"
    password: "$argon2id$..."  # 用 authelia hash-password 生成
    email: admin@example.com
    groups:
      - admins
      - users
  zhangsan:
    displayname: "张三"
    password: "$argon2id$..."
    email: zhang@example.com
    groups:
      - users

# 生成密码哈希
docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password "your_password"

Nginx 集成¶

# nginx 配置 - 在每个需要保护的 server 块中加入
location /authelia {
    internal;
    proxy_pass http://authelia:9091/api/authz/forward-auth;
    proxy_set_header X-Forwarded-For $remote_addr;
}

server {
    server_name app.example.com;

    # Authelia 认证
    auth_request /authelia;
    auth_request_set $user $upstream_http_remote_user;

    location / {
        proxy_pass http://your-app:8080;
        proxy_set_header Remote-User $user;
    }
}

常见报错¶

报错信息	原因	解决方案
登录页面打不开	Authelia 没启动	检查 Docker 容器状态
登录后无限重定向	Cookie 域配置错误	确保 session cookies domain 正确
2FA 验证码不对	时间不同步	检查服务器时间（NTP）
`Access denied`	权限策略拦截	检查 access_control 规则

速查表¶

# 访问控制策略
bypass      # 无需认证（公开页面）
one_factor  # 需要用户名密码
two_factor  # 需要用户名密码 + 2FA
deny        # 拒绝访问

# 支持的反向代理
Nginx / Traefik / Caddy / HAProxy / Envoy

# 支持的认证方式
TOTP（Google Authenticator）
WebAuthn（YubiKey/指纹）
Duo Push

参考：Authelia 官网 | GitHub | 配置文档