截至 2025 年 3 月，Network Application 9.1.105 已在早期访问 (EA) 阶段发布，API 文档和密钥生成已完成。你可以通过 Network > Control Plane > Integrations 访问文档并生成 API 密钥。

组件

  • 客户端设备
  • UniFi 接入点
  • UniFi 交换机与 Cloud Gateway
  • 外部门户服务器 (Hotspot/认证门户)

授权流程概述

在标准的 UniFi 网络部署中，客户端可以连接配置了 Hotspot > Captive Portal 的 SSID。当访客加入网络时，初始会被标记为 GUEST，authorized: false，处于预授权状态。

尝试访问任何网页时，客户端会被重定向到 外部门户服务器。该服务器可处理多种认证方式，包括：

  • 身份提供商（IdP）认证
  • 支付系统
  • 酒店式认证（如房号和姓氏）
  • 新闻订阅注册

外部门户完成认证后，可通过 Network API 发送 POST 请求授权客户端。

API 工作流程

  1. 客户端连接 SSID
    • 客户端连接到启用 Hotspot > Captive Portal 的 Wi-Fi SSID，默认被标记为 GUEST 且 authorized: false。
  2. 重定向到外部门户服务器
    • 当客户端尝试访问网页时，会被重定向至 外部门户服务器。服务器收到客户端的 MAC 地址和 SSID，可用于后续授权。
    • 外部门户服务器可通过解析重定向 URL 获取客户端 clientId，例如：
    • http://PATH_TO_EXTERNAL_PORTAL/guest/s/default/?ap=94:2a:6f:d0:30:57&id=1c:71:25:63:e4:24&t=1742398732&url=http://netcts.cdn-apple.com%2F&ssid=dph-guest
      • ap = UniFi AP 的 MAC 地址
      • id = 客户端设备的 MAC 地址
      • url = 原始重定向目标
      • ssid = 客户端连接的 SSID
      • 使用客户端 MAC 地址，外部服务可调用：
      • GET /v1/sites/{siteId}/clients filter=macAddress.eq('AA:AA:AA:AA:AA:AA')
      • 这会返回包含所需 clientId 的客户端对象。
  3. 外部门户服务器授权客户端
    • 完成认证后，外部门户服务器通过 POST 请求向 Network API 授权该客户端。请求可包含如时长、流量和速率限制等选项。
  4. 授权确认
    • 授权流程完成后，客户端状态更新为 authorized: true。更新的客户端信息可在 Network API 获取。

授权流程

1.png

API 端点

1. 获取站点列表

GET /v1/sites

该接口返回由 Network Application 管理的站点列表。对于 Cloud Gateway，通常仅有 1 个站点（包含 site ID）。

示例响应：

[
  {
    "id": "siteId",
    "name": "Site Name"
  }
]

2. 获取站点客户端列表

GET /v1/sites/{siteId}/clients

此接口获取指定站点的客户端列表。

示例响应：

{
  "type": "WIRELESS",
  "id": "clientId",
  "name": "Apple iPad Pro",
  "macAddress": "42:8a:f7:3c:50:b0",
  "access": {
    "type": "GUEST",
    "authorized": false
  }
}

3. 授权客户端

POST /v1/sites/{siteId}/clients/{clientId}/actions

此接口通过发送 POST 请求（可包含时长/流量/速率等限制）来授权访客接入网络。

示例请求体：

{
  "action": "AUTHORIZE_GUEST_ACCESS",
  "timeLimitMinutes": 120,
  "dataUsageLimitMBytes": 500,
  "rxRateLimitKbps": 100,
  "txRateLimitKbps": 100
}

4. 获取已授权客户端详情

GET /v1/sites/{siteId}/clients/{clientId}

该接口返回更新后的客户端授权详情。

示例响应：

{
  "access": {
    "authorized": true,
    "authorization": {
      "authorizedAt": "2025-03-19T11:20:44Z",
      "expiresAt": "2025-03-19T13:00:44Z",
      "dataUsageLimitMBytes": 500
    }
  }
}

2.png

有线客户端的访客认证门户

Hotspot 区域默认包含在 基于区域的防火墙 策略内，提供将访客重定向至认证门户的即用型策略。

你可以为有线客户端配置 GuestLAN，确保它们享有与无线访客相同的认证体验，实现无线与有线访客体验一致。

  1. 新建访客专用网络

创建专用于访客的新网络（如 GuestLAN），并将其区域设置为 Hotspot。

3.png

2. 在基于区域的防火墙表中校验

检查 Hotspot 区域是否已应用于目标网络。如无，请在 Zone-Based Firewall 配置中手动选择 Hotspot 区域。

4.png

  1. 连接有线客户端

所有连接到 GuestLAN 端口的有线客户端均会被同样纳入认证门户流程，与无线访客一致。

5.png