FRPS 第三方认证对接

frps_helper 内置 FRPS 认证服务器(HTTP,默认 8089,原 frps-authd 功能),实现 frps 的 httpPlugins 插件协议:只有持有有效会话的设备才能建立隧道。

frps 配置

在 frps 配置文件(frps.toml)中添加 HTTP 插件,指向 frps_helper 的 8089 端口(frps 与 frps_helper 同机时用 127.0.0.1):

[[httpPlugins]]
name = "my-auth"
addr = "127.0.0.1:8089"
path = "/handler"
ops = ["Login", "Ping"]

认证流程

xfrpc(设备) frps frps_helper :8089 Login(用户名/密码/run_id) POST /handler(Login) 校验 session_id ok · run_id → session_id 认证通过 · 隧道建立 alt 会话无效 reject(拒绝接入) 8089 仅允许 frps 访问(127.0.0.1 / 防火墙限制)· 拒绝原因写入结构化日志
  1. 设备先经南向接口(6999)join 获得 session_id,并按会话周期上报状态续期。
  2. xfrpc 连接 frps 时,frps 触发 Login 操作,将登录信息转发给 frps_helper 的 /handler。
  3. frps_helper 校验设备会话的有效性(session 存在、未过期、单设备单会话)。
  4. 校验通过后,frps_helper 把 run_id 替换为 session_id 返回给 frps,隧道建立;Ping 操作用于工作负载健康检查。

辅助接口

认证服务器还提供(详见仓库 docs/frpc认证接口规范.md):

  • /handler — frps httpPlugins 回调入口(Login / Ping)。
  • /clients — 当前已认证客户端查询。
  • /health — 健康检查。

安全语义

  • 无有效会话的接入请求一律拒绝,拒绝原因写入结构化日志(logrus)。
  • 空闲会话过期(默认 180s)后,隧道凭据随之失效,防止失效会话残留。
  • 8089 为 HTTP 且无设备语义鉴权,请勿对公网开放,仅允许 frps 所在主机访问(127.0.0.1 / 防火墙限制)。