飞网Nginx认证连接器

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

---

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

1.1 体验飞网 Nginx 认证服务

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

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

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

飞网nginx网络认证演示网址

认证失败

---

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

加入体验网络

飞网 Nginx 认证服务测试

1.2 安装飞网 Nginx 认证连接器

1.2.1 下载飞网 Nginx 认证连接器安装包。

注：需要在安装飞网后使用

    根据您的操作系统类型和CPU架构选择并安装飞网 Nginx 认证连接程序文件：

🐧 Debian / Ubuntu 系统

wget -N https://pkgs.gmzta.com/deb/gmzta-nginx-connector-amd64.deb
sudo apt install ./gmzta-nginx-connector-amd64.deb

🧱 Red Hat / CentOS 系统

wget -N https://pkgs.gmzta.com/rpm/gmzta-nginx-connector-amd64.rpm
sudo yum install ./gmzta-nginx-connector-amd64.rpm

1.2.2. 配置Nginx，开启无密码身份验证

注：若未安装Nginx，请自行安装Nginx。

编辑Nginx配置文件，添加以下内容：

需自行配置后端应用地址

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;
    }
}

• 上述配置使用了Nginx的一个特性：基于子请求结果的身份认证。Nginx可以通过外部服务器或外部服务对网站的每个请求进行身份验证。为了执行身份验证，NGINX向外部服务器发出一个HTTP子请求，并在那里对该子请求进行身份验证。如果子请求返回一个2xx响应代码，表示身份验证成功则允许继续访问；如果子请求返回401或者403，表示身份验证失败则拒绝访问。这种类型的身份验证可以实现各种身份验证方案，例如多因素身份验证，或者实现LDAP或OAuth身份验证。
• 更多资料访问

1.2.3重启nginx服务。

nginx -s reload

1.2.4开启飞网nginx 认证连接器

// 开启服务
systemctl start gmzta.nginx-connector.socket
systemctl start gmzta.nginx-connector.service
// 配置开机自启
systemctl enable gmzta.nginx-connector.socket
systemctl enable gmzta.nginx-connector.service

1.3 docker 安装飞网 Nginx 认证连接器

1.3.1 准备nginx配置文件

参考4.1安装飞网-nginx-认证连接器

1.3.2 拉取镜像

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

1.3.2 启动容器

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 $(pwd)/gmzta/conf:/var/lib/gmzta \
  -v $(pwd)/default.conf:/etc/nginx/conf.d/default.conf \
  --restart unless-stopped \
  registry.cn-beijing.aliyuncs.com/gmzta/gmzta-nginx-connector:latest