飞网Nginx认证连接器

—— 5分钟快速接入飞网认证服务

---

🚀 1.飞网 Nginx 认证连接器使用指南

1.1 体验飞网 Nginx 认证服务

在接入飞网测试团队网络之前，访问飞网单点登录演示项目（地址如下）：

https://demo2.demonet.gmzta.net/

此时由于尚未接入体验网络，访问将会失败，页面显示如下所示的认证失败信息：

飞网nginx网络认证演示网址

认证失败

---

注册飞网账号，并成功接入测试团队网络后，页面访问状态会发生变化，进入认证成功界面。如下图所示：

加入体验网络

飞网 Nginx 认证服务测试

1.2 安装飞网 Nginx 认证连接器

当前仅支持 Docker 部署。

1.2.1 准备 Nginx 配置文件

飞网 Nginx 认证连接器依赖 Nginx 的 auth_request 机制，对每个请求发起子请求完成身份校验：

• 子请求返回 2xx 时，表示认证通过，请求继续访问后端服务。
• 子请求返回 401 或 403 时，表示认证失败，Nginx 将拒绝访问。
• 该机制适合将认证能力统一前置到 Nginx 层。

更多资料访问

请先在宿主机准备 Nginx 配置文件，例如 default.conf，并将后端应用地址替换为实际业务服务地址：

server {
    listen 80;
    server_name 127.0.0.1; # 本地监听，仅用于开发或反代内部服务

    error_log /var/log/nginx/error.log debug;
    access_log /var/log/nginx/access.log;

    # --- 身份认证接口 ---
    location = /auth {
        internal; # 此路径仅供 NGINX 内部调用，防止外部直接访问

        # 调用飞网 nginx-auth 认证服务（通过本地 Unix Socket）
        proxy_pass http://unix:/var/run/gmzta-nginx-connector.sock;

        proxy_pass_request_body off; # 不转发请求体，认证只需头部信息

        # 设置发送给认证服务的请求头
        proxy_set_header Host $http_host;
        proxy_set_header Remote-Addr $remote_addr;
        proxy_set_header Remote-Port $remote_port;
        proxy_set_header Original-URI $request_uri;

        # 设置认证响应格式（避免暴露内容类型）
        proxy_hide_header Content-Type;
        add_header Content-Type 'text/plain';

        # 限制只允许 GET/HEAD 请求访问该路径（防止滥用）
        limit_except GET HEAD {
            deny all;
        }
    }

    # --- 身份认证失败时返回 401 页面 ---
    error_page 401 /401.html;

    location = /401.html {
        root /usr/share/nginx/html;
        internal; # 防止用户直接访问 401 页面，只用于 error_page 渲染
    }

    # --- 对外服务代理（带身份认证） ---
    location / {
        # 启用飞网认证机制
        auth_request /auth; # 请求前先走 /auth 验证，认证失败返回 401

        # 从认证响应中提取用户身份信息（来自 nginx-auth 返回的 header）
        auth_request_set $auth_user            $upstream_http_gmzta_user;
        auth_request_set $auth_name            $upstream_http_gmzta_name;
        auth_request_set $auth_login           $upstream_http_gmzta_login;
        auth_request_set $auth_gmztanet        $upstream_http_gmzta_gmztanet;
        auth_request_set $auth_profile_picture $upstream_http_gmzta_profile_picture;

        # 将身份信息通过 Header 注入到后端应用，可自定义返回名称 
        proxy_set_header X-Webauth-GmztaUser            "$auth_user";
        proxy_set_header X-Webauth-GmztaName            "$auth_name";
        proxy_set_header X-Webauth-GmztaLogin           "$auth_login";
        proxy_set_header X-Webauth-GmztaNet             "$auth_gmztanet";
        proxy_set_header X-Webauth-Gmzta-Profile-Picture "$auth_profile_picture";

        # 反向代理到本地服务（或改为你的业务服务地址）
        proxy_pass http://localhost:3002;
    }
}

1.2.2 拉取镜像

docker pull registry.cn-beijing.aliyuncs.com/gmzta/gmzta-nginx-connector:latest

1.2.3 启动容器

docker run -d \
  --name gmzta-nginx-connector \
  --hostname gmzta-nginx-connector \
  -p 80:80 \
  -e GM_TOKEN=gmzta-authkey-1234567890abcd \
  -e GM_CONFIG_DIR=/var/lib/gmzta \
  -e GM_TUN=false \
  -v /path/to/gmzta/conf:/var/lib/gmzta \
  -v /path/to/default.conf:/etc/nginx/conf.d/default.conf \
  --restart unless-stopped \
  registry.cn-beijing.aliyuncs.com/gmzta/gmzta-nginx-connector:latest