使用轻量级中间件 VoidAuth 快速构建站点SSO，支持Docker一键部署与Nginx快速接入

luler · 2025-12-19T17:50:24+00:00

一、简介 VoidAuth 是一款开源的 SSO 身份验证和用户管理中间件，可以为您的自托管站点与应用保驾护航它非常易用，并支持诸多实用功能，例如Passkeys、多因素身份认证，用户邀请、自助注册、电子邮件支持等等提供在线管理面板，可以对站点分组授权、用户信息等进行管理支持Docker快速部署，可以轻...

luler

一、简介

VoidAuth 是一款开源的 SSO 身份验证和用户管理中间件，可以为您的自托管站点与应用保驾护航
它非常易用，并支持诸多实用功能，例如Passkeys、多因素身份认证，用户邀请、自助注册、电子邮件支持等等
提供在线管理面板，可以对站点分组授权、用户信息等进行管理
支持Docker快速部署，可以轻松接入caddy、traefik、nginx等反代服务
该项目的开源地址参考：https://github.com/voidauth/voidauth

二、安装与使用

1. Docker快速安装voidauth

新建docker-compose.yml配置文件，参考如下内容：

services:


  voidauth: 
    image: voidauth/voidauth:latest
    restart: unless-stopped
    volumes:
      - ./voidauth/config:/app/config
      - ./db:/app/db
    environment:
   
      APP_URL: https://127.0.0.1 # 必须设置，并且开启https, 如：https://auth.example.com
      STORAGE_KEY: igzMCL400WvzCi3ekcBWI8U90G7pbtJW # 必须，可以随机生成32位字符

      DB_ADAPTER: sqlite #数据库驱动，支持sqlite、postgresql
    ports:
      - "3000:3000"

配置完成，执行如下命令，一键启动

docker-compose up -d

voidauth 启动成功之后，可以查看容器的logs，获得初始化的账号密码

docker-compose logs

参考如下截图：

2. nginx反代配置

voidauth 认证端点nginx配置，用户访问voidauth在线管理页面和系统，这里只粘贴了部分配置，其他https证书、域名配置请自行配置

location / {
  proxy_set_header Host $host;
  proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
  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;
  proxy_pass http://172.17.0.1:3000;
}

受保护应用nginx配置

# 认证端点
location /api/authz/auth-request {
  # internal 表示这个 location 只能被内部子请求访问
  # 外部直接访问 /api/authz/auth-request 会返回 404
  internal;

  # 认证请求发送到 VoidAuth 的认证端点
  proxy_pass http://172.17.0.1:3000/api/authz/auth-request;
  
  # 不转发原始请求体（认证只需要 headers）
  proxy_pass_request_body off;

  # 清空 Content-Length，因为不发送 body
  proxy_set_header Content-Length "";
  
  # 以下 headers 让 VoidAuth 知道用户原本想访问什么
  proxy_set_header Host $host;
  proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
  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 / {
  # ========== 触发认证 ==========
  # 在处理请求前，先发送子请求到 /api/authz/auth-request
  # 根据返回状态码决定是否放行
  auth_request /api/authz/auth-request;

  # ========== 处理认证失败 ==========
  # 从 VoidAuth 响应中获取 Location header（登录页地址）
  auth_request_set $redirection_url $upstream_http_location;
  
  # 如果 VoidAuth 返回 401，重写为 302 重定向到登录页
  error_page 401 =302 $redirection_url;
  
  # 407 是 Proxy Authentication Required，同样处理
  error_page 407 =302 $redirection_url;

  # ========== 获取用户信息 ==========
  # 从 VoidAuth 200 响应的 headers 中提取用户信息
  # $upstream_http_xxx 表示上游响应的 header
  auth_request_set $auth_user $upstream_http_remote_user;      # 用户名
  auth_request_set $auth_groups $upstream_http_remote_groups;  # 用户组
  auth_request_set $auth_email $upstream_http_remote_email;    # 邮箱
  auth_request_set $auth_name $upstream_http_remote_name;      # 显示名称

  # ========== 标准代理 headers ==========
  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;
  
  # ========== Trusted Header SSO ==========
  # 将用户信息传递给后端应用
  # 后端应用可以直接信任这些 headers 来识别用户
  proxy_set_header Remote-User $auth_user;
  proxy_set_header Remote-Groups $auth_groups;
  proxy_set_header Remote-Email $auth_email;
  proxy_set_header Remote-Name $auth_name;

  # 转发到后端应用
  proxy_pass http://172.17.0.1:8080;
}

3. 使用示例

登录voidauth管理后台，新增用户、用户授权、用户要求等
可以通过邀请链接创建新的用户，最好给每个用户创建并设定分组
可以授权哪个分组的用户才能访问指定域名和路径的资源，不在指定分组内的其他用户就算登录也无权访问（管理员分组除外）
接入的 voidauth 的站点之间是实现单点登录的，就是只需要登录一次，后面访问不通的应用也不需要重新登录了

三、总结

VoidAuth 是一个小而美开源自托管单点登录(SSO)系统，支持 OIDC 和 ForwardAuth 代理认证，所有网站应用都能轻松接入
安全性做的不错，支持 Passkeys 通行密钥、多因素认证、数据库加密等
安装部署使用相对简单，Docker一键部署，支持sqlite数据库轻便运行，还带一个简洁易用的可视化管理面板
需要注意的点：
- Docke r启动 voidauth，可以通过docker-compose logs看到一次初始化账号密码，请记住并修改，后面不再出现
- voidauth的账号名称不要是中文名称、特殊符号，会报错无法运行，应该是个未修复的Bug