Ubiquiti

UniFi Integration

Configure Ubiquiti UniFi wireless networks to authenticate users with NetKey RADIUS for WPA2/WPA3-Enterprise and MAC-based authentication.

UniFi Controller Version

This guide applies to UniFi Network Application 7.x and later. Settings location may vary slightly in older versions.

Prerequisites

  • UniFi Network Application (Controller) 7.x or later
  • UniFi Access Points adopted and running
  • Network connectivity between APs and NetKey RADIUS
  • NetKey Group configured with RADIUS secret
Finding Your RADIUS Server Details

Log in to app.netkey.no → Settings → RADIUS Clients to find your RADIUS server IP/hostname and create a shared secret for your UniFi network.

iPSK Limitations

UniFi's native PPSK (Private PSK) feature doesn't use RADIUS. For RADIUS-based iPSK, use MAC authentication with NetKey.

Controller Configuration

Step 1: Add RADIUS Profile

1

Open your UniFi Network Application

Navigate to Settings → Profiles → RADIUS

2

Click Create New and configure:

Profile Name NetKey-RADIUS
VLAN Support Enabled (for dynamic VLAN)
3

Add Authentication Server:

IP Address your-radius-server
Port 1812
Shared Secret Your NetKey RADIUS secret
4

Add Accounting Server (optional but recommended):

IP Address your-radius-server
Port 1813
Shared Secret Same as authentication
5

Click Apply Changes

Step 2: Create WiFi Network (WPA2-Enterprise)

6

Navigate to Settings → WiFi

Click Create New

7

Configure WiFi settings:

Name Corporate-WiFi
Security Protocol WPA2 Enterprise
RADIUS Profile NetKey-RADIUS
8

Configure Network settings:

Network Select your network or "Default"
VLAN Leave blank for dynamic or set default
9

Click Apply Changes

MAC-Based Authentication

For device authentication (iPSK alternative), use MAC authentication.

Enable MAC Authentication

1

Edit your WiFi network settings

Under Advanced, enable:

RADIUS MAC Authentication Enabled

MAC Format

UniFi sends MAC addresses in lowercase with colons:

Format 
aa:bb:cc:dd:ee:ff

Configure NetKey to expect this format in Group Settings → RADIUS → MAC Format.

Combined Authentication

You can combine WPA2-Enterprise with MAC authentication for additional device verification or to support devices that can't do 802.1X.

Dynamic VLAN Assignment

UniFi supports dynamic VLAN assignment from RADIUS.

Prerequisites

  • VLANs configured in UniFi Networks
  • VLAN Support enabled in RADIUS Profile
  • Switch ports configured for VLAN trunking

Create VLANs

1

Navigate to Settings → Networks

Create networks for each VLAN:

Guest Network VLAN 100
Employee Network VLAN 200
IoT Network VLAN 300

RADIUS Response

NetKey returns VLAN assignment using standard tunnel attributes:

RADIUS Response 
Tunnel-Type = VLAN
Tunnel-Medium-Type = IEEE-802
Tunnel-Private-Group-ID = "100"

WPA3-Enterprise

UniFi supports WPA3-Enterprise for enhanced security.

1

When creating WiFi network, select:

Security Protocol WPA3 Enterprise

Or for compatibility:

Security Protocol WPA2/WPA3 Enterprise
Device Compatibility

Not all devices support WPA3. Use "WPA2/WPA3 Enterprise" for mixed environments to maintain backward compatibility.

Testing & Verification

Test RADIUS Connection

UniFi doesn't have a built-in RADIUS test. Verify by:

  1. Connecting a test device to the WiFi network
  2. Checking NetKey Auth Logs for the authentication attempt
  3. Viewing UniFi client list for connection status

View Connected Clients

1

Navigate to Clients in the sidebar

Click on a client to see details including:

  • Authentication method
  • VLAN assignment
  • Connection history

View Events

1

Navigate to System Log (Alerts icon)

Filter for WiFi events to see authentication attempts.

Troubleshooting

  • Check NetKey Auth Logs for authentication attempts
  • Verify RADIUS profile is assigned to WiFi network
  • Ensure RADIUS secret matches exactly
  • Check firewall allows UDP 1812/1813
  • Verify client credentials are correct
  • Verify AP can reach RADIUS server IP
  • Check RADIUS profile configuration
  • Ensure WiFi network uses correct profile
  • Try reprovisioning the APs
  • Verify "VLAN Support" is enabled in RADIUS Profile
  • Ensure VLAN exists in UniFi Networks
  • Check switch ports allow the VLAN
  • Verify NetKey returns Tunnel-Private-Group-ID
  • Ensure MAC format matches (lowercase, colons)
  • Verify endpoint exists in NetKey
  • Check "RADIUS MAC Authentication" is enabled
  • View NetKey logs for MAC-based auth attempts

Advanced Configuration

Guest Network with RADIUS

Create a guest network that uses RADIUS for tracking:

  1. Create WiFi network with Guest settings
  2. Enable RADIUS MAC Authentication
  3. Use NetKey to track guest devices
  4. Set up automatic expiration in NetKey

Site-to-Site Consistency

For multi-site deployments:

  • Use the same RADIUS profile across sites
  • Ensure all sites can reach NetKey RADIUS
  • Consider RadSec for secure cross-WAN communication