飞网网络认证连接器(FW-IDP)

目录

• 一、项目简介与优势
• 二、服务端部署配置指南
  • 第一步：飞网 ACL 配置与字段说明
  • 第二步：采用 Docker 或 Docker Compose 部署
  • 第三步：FW-IDP 服务端管理与创建客户端凭证
• 三、客户端（应用端）接入

---

1. 项目简介与优势

FW-IDP 是专为飞网网络设计的标准化 OIDC Provider（身份提供商）。
它基于飞网底层的 WhoIs API 与网络层强身份信任机制（TCP 源 IP 不可伪造），实现了无前端登录页、无密码数据库的身份认证模型，从根本上消除了企业内网 SSO 的众多基建痛点。

本质上，它就是飞网内部的“统一登录中心”，专门为网络中的各类服务签发标准化的登录凭证（OIDC Token），让应用无需自行管理用户密码或认证逻辑。

架构对比与极简体验：

1. 传统 SSO 架构

传统身份鉴权需跨域跳转，体验割裂并增加安全风险。业务侧与底层网络隔离行驶。

2. 传统业务接入 FW-IDP

直接静默读取终端底层网络身份，仅改一点 OIDC 配置即可享受全程无跳转的免密登录。

3. 纯飞网生态 FW-IDP

内网完全对外隐身，自动完成专属域名解析与系统级 HTTPS 证书下发，根治内网握手报错。

FW-IDP 核心优势总结：

• 无需维护用户/数据库：彻底告别密码库和认证 UI。授权全部收敛在飞网控制台：员工加入飞网即获 OAuth 应用权限，移出飞网瞬间失去全盘登录能力。
• 零感免密登录：用户访问应用 → FW-IDP 拦截请求 → 静默查验 TCP 源 IP → 瞬间签发 Code 返回。底层应用无需改代码，用户全程无前端交互，零感直达后台。
• 自动内网域名解析 (飞网节点域名解析)：启动时主动向飞网登记，自动注册专有内网域名（如 idp.您的网络域名.gmzta.net），完美解决 redirect_uri 的跨机寻址难题。
• 自动 HTTPS 证书配置：利用飞网自动通过 DNS challenge 自动向 Let's Encrypt 申请受全球信任的 SSL 证书，无需公网暴露，从根本上解决内网对接 OIDC 时常见的 TLS 报错问题。

通过上述机制，FW-IDP 作为“翻译官”，将飞网底层的极高网络安全信任，平滑转换为应用层通用且标准的 OAuth 信任，为开发者和使用者双向减负。

且 FW-IDP 支持MCP授权规范要求和建议的所有端点，包括动态客户端注册 (DCR)，可无缝接入标准 OIDC/OAuth 生态。

2. 服务端部署配置指南

⚠️ 注意事项：
FW-IDP 服务需配合 飞网客户端 1.2.4 及以上版本 使用，以确保客户端完整支持底层的身份标识透传与零交互网络断言功能。低于此版本的客户端可能在认证跳转拦截环节出现无法跨网透传验证的情况。

部署流程主要分为两步：配置访问策略与启动服务。

第一步：飞网 ACL 配置与字段说明

在“飞网控制面板”-“访问控制”-增加“允许访问策略”。
例如： 所有员工的设备都可以访问“fw-idp设备组”，并根据需求配置飞网内置应用“内置fw-idp服务”的访问策略，配置示例如下：

◆ 端口：任意；源地址：管理员用户集合；目的地址：fw-idp设备组；应用名称：内置fw-idp服务；授权用户范围：任意；授权目标服务：留空；是否允许自动注册客户端：允许；是否允许访问管理后台：允许；扩展身份属性： "roles": ["admin"]；是否在用户信息接口返回扩展身份：允许。

◆ 端口：任意；源地址：用户集合；目的地址：fw-idp设备组；应用名称：内置fw-idp服务；授权用户范围：任意；授权目标服务：留空；是否允许自动注册客户端：允许；是否允许访问管理后台：拒绝；扩展身份属性： "roles": [ "dev"]；是否在用户信息接口返回扩展身份：允许。

内置fw-idp服务字段详解

（Audience） 核对

字段	数据类型	说明
登录用户范围	[]string	指定哪些用户或节点可以发起 OAuth 登录。填写 "*" 表示允许网络内所有成员。
访问目标服务	[]string	指定签发的访问令牌可用于访问哪些目标服务（Audience）。留空表示不限制使用范围。
是否允许自动注册客户端	bool	是否允许通过动态客户端注册接口自动生成 Client ID 与 Secret，适用于自动化接入场景。
是否允许访问管理后台	bool	是否允许访问 fw-idp 的 Web 管理界面，用于手动创建和管理客户端配置。
扩展身份属性	object	定义需要附加到身份信息中的自定义字段（如 roles: admin）。可用于下游系统进行角色或权限控制。
是否在用户信息接口返回扩展身份属性	bool	控制上述“扩展身份属性”是否同时在 /userinfo 接口中返回。开启后，下游系统可通过用户信息接口获取这些字段。

第二步：采用 Docker 或 Docker Compose 部署

前置条件：宿主机需安装 Docker，并拥有飞网控制台生成的授权密钥（含 fw-idp设备组 标签），如 gmzta-authkey-xxxx。

支持的环境变量说明

容器运行时支持以下环境变量配置：

环境变量	说明
GM_CONFIG_DIR	指定存储飞网客户端程序配置文件的目录，配置文件默认为仅内存中使用。此目录文件在容器启动时加载，将该文件映射至外部存储，可防止该设备被识别为新设备。
GM_HOSTNAME	指定飞网节点的主机名，默认为 fw-idp。
GMIDP_ENABLE_STS	开启 OIDC 的 STS (Secure Token Service) 令牌交换功能支持。
GM_USE_IN	启用飞网入口网关功能，允许公网直接访问服务。
GM_PORT	服务在宿主机上监听的端口，默认为 443。
GM_LOCAL_PORT	容器内额外监听的本地端口（可选）。
GM_LOG	控制综合日志输出级别，可选：debug, info, warn, error。
GM_DEBUG_ALL_REQUESTS	开启极度详细的 HTTP 请求与响应调试日志。
GM_DEBUG_GMNET	开启底层 gmnet 网络组件的调试日志。
GM_TOKEN	飞网控制面板生成的认证授权密钥，用于服务上线认证。

方案一：Docker CLI 部署 (适合快速测试)

docker run -d \
  --name fw-idp \
  --restart unless-stopped \
  -v ./fw-idp-data:/data \
  -e GM_CONFIG_DIR=/data \
  -e GM_HOSTNAME=idp \
  -e GM_TOKEN="gmzta-authkey-你的真实授权密钥串" \
  registry.cn-beijing.aliyuncs.com/gmzta/fw-idp

🌟 提示：特殊部署参数 -e GM_USE_IN=1 (入口网关模式)
什么时候该使用它？当 FW-IDP 与您的业务系统分别部署在不同的服务器/网络环境，且业务系统不想做任何改动或安装飞网客户端时。开启此模式后，FW-IDP 将通过飞网的入口网关安全地公开到公网，使得分离部署的业务系统也能顺利与其进行 OIDC 交互和免密核对。如果 FW-IDP 与业务系统部署在同一台服务器内，则无需开启。

方案二：Docker Compose 部署 (推荐)

创建 docker-compose.yml 配置文件：

version: '3.8'

services:
  fw-idp:
    container_name: fw-idp
    image: registry.cn-beijing.aliyuncs.com/gmzta/fw-idp
    restart: unless-stopped
    volumes:
      # 持久化状态配置与 SSL 证书
      - ./fw-idp-data:/data
    environment:
      # 状态数据存储路径，需与 volumes 映射一致
      - GM_CONFIG_DIR=/data
      # 服务主机名（分配为 idp.网络域名.gmzta.net）
      - GM_HOSTNAME=idp
      # 控制台生成的认证授权 Token
      - GM_TOKEN="gmzta-authkey-你的真实授权密钥串"
      # 可选：开启 STS 支持（适配高级 MCP 等架构）
      # - GMIDP_ENABLE_STS=1
      # 🌟 可选：入口网关模式（适用于 **FW-IDP 与业务系统分别部署在不同服务器，且业务系统不想安装飞网** 的场景。开启后 fw-idp 会公开到公网，方便分离的业务系统也能完成免密 OIDC 交互）
      # - GM_USE_IN=1
      # 可选：如果需要调试请求头或改变日志级别，可取消下方注释
      # - GM_LOG=debug
      # - GM_DEBUG_ALL_REQUESTS=1

启动服务：

docker compose up -d

通过 docker compose logs -f 可监听启动日志。待证书申请完成（约 1-2 分钟内），即可通过分配的内部 HTTPS 域名访问 FW-IDP 管理后台创建客户端。

方案三：Windows 二进制直接部署

如果您需要在 Windows 服务器上直接部署（免装 Docker），可通过直接运行可执行文件（.exe）来启动服务。打开 PowerShell 或新建脚本：

# 从飞网控制面板获取的服务端真实授权密钥串（唯一需要用环境变量传递的机密参数）
$env:GM_TOKEN = "gmzta-authkey-你的真实授权密钥串"

# 切换到执行文件所在目录，通过命令行参数启动进程
.\fw-idp.exe `
  -dir "D:\fw-idp-data" `
  -hostname "idp" `
  -log "info"
  # -in               # 🌟 取消注释以开启入口网关模式（适用于 **FW-IDP 与业务系统分别部署在不同服务器，且业务系统不想安装飞网** 的场景。开启后 fw-idp 会公开到公网，方便分离的业务系统完成免密交互）
  # -local-port 8080  # 取消注释以绑定本地其他端口

提示：第一次运行会在 -dir 指定位置生成运行状态文件及自动下发的 SSL 证书；如需后台常驻，可使用 NSSM 等工具将其包装为 Windows 系统服务。

Windows 命令行参数说明（对应 Docker 环境变量）：

在 Windows 二进制部署中，除了凭证 $env:GM_TOKEN 通过环境变量传递外，其他控制参数均通过命令行 flag 传入，具体对应关系如下：

命令行参数	对应的环境变量	说明
-dir	GM_CONFIG_DIR	指定存储飞网客户端程序配置文件的目录，配置文件默认为仅内存中使用。此目录文件在运行启动时加载，可防止该设备被识别为新设备。
-hostname	GM_HOSTNAME	指定飞网节点的主机名，默认为 fw-idp。
-enable-sts	GMIDP_ENABLE_STS	开启 OIDC 的 STS (Secure Token Service) 令牌交换功能支持。
-in	GM_USE_IN	启用飞网入口网关功能，允许公网直接访问服务。
-port	GM_PORT	服务监听的端口，默认为 443。
-local-port	GM_LOCAL_PORT	允许来自本机回环地址的请求监听端口（可选）。
-log	GM_LOG	控制综合日志输出级别，可选：debug, info, warn, error。
-debug-all-requests	GM_DEBUG_ALL_REQUESTS	开启极度详细的 HTTP 请求与响应调试日志。
-debug-gmnet	GM_DEBUG_GMNET	开启底层 gmnet 网络组件的调试日志。

第三步：FW-IDP 服务端管理与创建客户端凭证

1. 浏览器访问 FW-IDP 服务端管理后台：https://idp.您的网络域名.gmzta.net。

2. 在控制台中点击“新增 OIDC 客户端”，配置如下核心信息：

   • 客户端名称：填写用于标识此 OIDC 客户端的描述性名称（例如截图中的 dex 或您的实际业务应用名）。
   • 回调地址：填写第三方应用接收 OIDC 授权码的回调处理地址（例如：http://127.0.0.1:5556/dex/callback）。支持配置多个，每行输入一个。
   

3. 确认无误后点击“创建客户端”，系统会成功生成对应的接入凭证。

4. ⚠️ 重要提醒：请立即保存界面显示的 Client ID 和 Client Secret（客户端密钥）。出于安全机制，Secret 创建后将不会再次在后台中显示！

   

3. 客户端（应用端）接入

3.1 客户端 OIDC 核心配置说明

FW-IDP 完全兼容标准 OIDC 协议。无论是自研业务应用，还是 Dex、Keycloak 等联邦认证中台，都可以非常方便地将 FW-IDP 作为一个增量的上游身份提供商（Upstream Identity Provider）平滑接入。

在绝大多数企业的实际场景中，您只需在原有的登录体系外，增设一个“飞网一键登录”的第三方登录入口。这种非侵入式接入完美兼顾了：

• 旧系统无缝兼容：原有账号密码、LDAP/AD 登录框照常保留，外部协作者或未安装飞网的临时设备不受任何影响，避免一刀切的麻烦。
• 内部员工免密直达：已接入飞网的员工点击该入口时重定向至 FW-IDP，底层网络瞬间完成静默人证合一校验，体验极其顺滑。

无论是直接接入还是联邦接入，您只需在相关的第三方应用中开启 OIDC 登录身份验证，并填入以下核心映射参数：

• issuer (OIDC 发行者地址)：设置为 FW-IDP 的飞网内部域名，如 https://idp.您的网络域名.gmzta.net。
• clientID：填入上个步骤中在 FW-IDP 管理后台生成的 Client ID。
• clientSecret：填入伴随生成的 Client Secret。
• redirectURI：应用侧接收回调授权码的地址（必须与 FW-IDP 后台配置的接收回调地址一字不差），参考图例如 http://127.0.0.1:5556/dex/callback。
• scopes：请求权限规范，通常需包含 openid, profile, email 等。

3.2 零交互免密认证网络流转（原理解析）

配置完成后，用户在客户端点选登录，实际浏览器网络跳转如下（全程无需输入帐号密码）：

首先，用户在应用登录页选择“使用 FW-IDP 登录”：

1. [由应用端发起] 用户点击登录，应用触发 HTTP 302，将用户重定向至 FW-IDP 的授权端点（例如向 /authorize?client_id=...&redirect_uri=...&scope=openid... 发起请求）。
2. [FW-IDP 静默拦截检定] 浏览器跳转至 FW-IDP 域名 (fw-idp.testteam.gmzta.net) 后，FW-IDP 不会展示任何登录页面，而是直接透过飞网底层识别当前请求连接对应的真实人员身份，核对无误后自动签发凭证。
3. [发回授权码给应用] FW-IDP 内部处理校验完成后，立即通过 HTTP 302 / 303 Redirect，直接携带着授权码 (code=...) 重定向回应用的配置侧回调地址（如本例的 /dex/callback?code=...）。
4. [应用验证与会话建立] 随后应用的后端截获 code，利用 Secret 借由内网通道去 FW-IDP 请求换取出 Access Token 与真正的用户信息，应用本身校验成功后即渲染内容页面（转入应用的后续 approval 或业务请求端点）。

对用户来说，点击登录后由于底层信任传递的极速验证，只会感知到浏览器跳转闪烁，配置后即可顺畅体验免密认证。