Skip to main content

RADIUS Configuration

The Atrium Agent includes an embedded RADIUS server that authenticates guest WiFi connections against active vouchers. This page covers how to configure the RADIUS server and connect it to your WiFi infrastructure.

RADIUS basics​

RADIUS (Remote Authentication Dial-In User Service) is the standard protocol for WiFi authentication. When a visitor's device connects to your guest WiFi:

  1. The WiFi controller sends a RADIUS Access-Request to the Agent (containing username and password).
  2. The Agent checks the credentials against its voucher store.
  3. The Agent responds with Access-Accept (valid voucher) or Access-Reject (unknown user or wrong password).

The Agent supports PAP authentication (Password Authentication Protocol). PAP transmits the password encrypted with the RADIUS shared secret. CHAP and EAP are not supported in the current version.

Configuring the RADIUS shared secret​

The RADIUS shared secret is a password shared between the WiFi controller (the RADIUS client) and the Agent (the RADIUS server). It's used to encrypt passwords in RADIUS packets and to authenticate requests.

On the Agent side: Set the RADIUS_SECRET environment variable when deploying the container.

On the WiFi controller side: Configure the Agent's IP address as a RADIUS server and enter the same shared secret. The exact steps depend on your WiFi controller — see your vendor's documentation.

Same secret everywhere

The RADIUS shared secret must be identical on both the Agent and the WiFi controller. A mismatch will cause all authentication attempts to fail silently (the controller interprets the response as invalid and drops the session).

Ports​

PortProtocolDirectionPurpose
1812UDPWiFi controller → AgentRADIUS Authentication (Access-Request / Accept / Reject)
1813UDPWiFi controller → AgentRADIUS Accounting (session start/stop, IP assignment)

Both ports must be reachable from the WiFi controller. If the Agent runs on a different network segment, ensure firewall rules allow UDP traffic on these ports.

WiFi controller configuration​

To connect your WiFi infrastructure to the Atrium Agent:

  1. Add the Agent as a RADIUS server in your WiFi controller's configuration.

    • Authentication server: Agent IP, port 1812.
    • Accounting server: Agent IP, port 1813.
    • Shared secret: the value from RADIUS_SECRET.

  2. Configure the guest WiFi SSID to use RADIUS (WPA2-Enterprise or a captive portal with RADIUS backend, depending on your setup).

  3. Configure NAS settings — the WiFi controller should identify itself via NAS-IP-Address in RADIUS packets. This helps with session tracking and termination.

The specific configuration steps vary by vendor (Cisco WLC, Aruba, Ruckus, UniFi, Meraki, etc.). Refer to your controller's documentation for RADIUS server configuration.

Testing RADIUS​

To verify the RADIUS configuration is working:

  1. Create a test visit in Atrium and check in the visitor (this generates a WiFi voucher).
  2. Connect a device to the guest WiFi using the voucher credentials.
  3. Check the Agent logs for the RADIUS exchange: ACCEPT user="..." nas=... mac=... confirms successful authentication.
  4. Verify the connection in the Atrium dashboard (session tracking shows the connected device).

Common failure modes:

SymptomLikely cause
No RADIUS logs at allWiFi controller can't reach the Agent (network/firewall issue) or is pointing to the wrong IP/port.
REJECT user="..." reason=unknown_userThe voucher hasn't reached the Agent yet, or the username doesn't match. Check if the Agent is connected to the Server.
REJECT user="..." reason=invalid_credentialsUsername matches but password is wrong. Verify the credentials shown in the dashboard match what the device is using.
Authentication hangs (no accept/reject)RADIUS shared secret mismatch. The Agent receives the request but can't decrypt the password.