Ubiquiti UniFi

Purpose

The UniFi connector reads controller (UniFi Network Application or UniFi OS Console) inventory, client, VLAN and firmware state so AssurIQ can assess segmentation, firmware currency and rogue device exposure on UniFi-managed networks.

Requirements

• UniFi Network Application 7.x+ or a UniFi OS Console (Dream Machine/Cloud Key) reachable from the collector
• A local admin account with read-only role, or the built-in Viewer role
• HTTPS (443) reachability from the collector to the controller

Permissions

• Controller account with the Viewer (read-only) administrator role
• API access enabled on the controller for local API keys where supported

Setup

1. 1
   Create a read-only admin

   In the UniFi controller, create a local administrator with the Viewer role.
2. 2
   Generate credentials or API key

   Generate an API key (UniFi OS) or record the Viewer account credentials.
3. 3
   Add the controller to AssurIQ

   In Integrations, add the UniFi controller URL and store the credential in the Credential Vault.
4. 4
   Select sites to monitor

   Choose which UniFi sites within the controller map to which AssurIQ sites.
5. 5
   Run initial discovery

   Trigger collection and confirm access points, switches and clients populate.

Verification

• Network Map shows UniFi access points and switches with model and firmware version
• VLAN inventory matches the controller's network configuration
• Client list matches connected devices in the UniFi dashboard

Data collected

• Access point, switch and gateway inventory and firmware versions
• VLAN and network configuration
• Connected client inventory and signal/health metrics
• Port and PoE state on managed switches

Security model

The connector uses a Viewer-role account or read-only API key; it cannot change controller configuration. Traffic runs outbound from the collector over HTTPS with certificate validation.

Common errors

• AIQ-CRD-001Credentials failing
  Stored credentials were rejected by one or more targets.
• AIQ-NET-001Device missing from discovery
  A device expected on the network was not seen in the last discovery cycle.

Troubleshooting

• If firmware versions look stale, confirm the controller itself has synced with Ubiquiti's cloud for update metadata.
• If a UniFi OS Console rejects the API key, confirm the key has not expired and local access is enabled.

Disconnect

1. Remove the controller from AssurIQ Integrations.
2. Delete or disable the Viewer account or API key in the UniFi controller.