How to setup FreeRadius with SQL and Rest

In modern network environments, managing user access securely and efficiently is pain (in th harsh). Whether for a large enterprise, a university campus, or an ISP, manually configuring credentials on individual network devices simply doesn’t scale. This is where the AAA framework—Authentication, Authorisation, and Accounting—comes into play, and the RADIUS protocol is one of its most robust and widely adopted implementations in the industry.

RADIUS enables users to join a network based on various credentials, such as a username/password combination or a device’s MAC address. More importantly, it allows network administrators to enforce policies, controlling everything from assigned IP addresses and VLAN memberships to bandwidth limits and session durations.

In this article, we will explore how to implement a centralized authentication system using FreeRADIUS. We will cover how to integrate it with a centralised database like MariaDB using SQL module and how to extend its functionality by connecting to an external API with the rlm_rest module (trust me, this one is a pain but we will try to see how we can set it up).

Automating customer access with Radius

This guide is motivated by a real-world scenario. The project involves an ISP that delivers internet access to business customers via fiber and radio links, presenting each customer’s connection as a unique stateful tunnel. The current process lacks automated authentication. When an user subscribe to the ISP, we define manually the PPPoE password combination in the BNG where the subscriber get Internet. It’s not simple and it’s not the best way to do it as it requires manual intervention on the network equipment. That’s where FreeRADIUS is useful.

The goal is to build a centralised, self-service system where:

• New customers can find their credentials in their personal dashboard on the website (not developed in this article).
• Upon first connection, their credentials are automatically authenticated.
• The system assigns the correct network policies (IP, VLAN, bandwidth) without manual intervention from the ISP’s operations team.

What is RADIUS?

RADIUS (Remote Authentication Dial-In User Service) is a networking protocol that provides centralised Authentication, Authorisation, and Accounting (AAA) management. Originally defined in RFC 2058 and updated in RFC 2865, it operates on a client-server model. Great! But what’s next? Why do I need RADIUS and why it’s a good point to have a server able to talk RADIUS?

AAA is the benefits of using RADIUS and it means :

• Authentication: Verifies the identity of a user or device (e.g., “Is this username/password correct?”).
• Authorisation: Determines what an authenticated user is allowed to do (e.g., “This user gets a static IP and 100Mbps bandwidth”).
• Accounting: Tracks the consumption of network resources for billing, auditing, or reporting purposes (e.g., “User X consumed 15GB of data this month”).

RADIUS act as a back-end for network devices. End-user devices does not directly talk with the RADIUS server. Instead, they make a request (using PPPoE, DHCP, or whatever) to a Network Access Server (the BNG or the Wi-Fi access point, etc.) in the middle.

Why RADIUS is so critical?

For a small home network, adding a user to a router is trivial. But managing thousands or millions of subscribers, ensuring revoked access is immediate, and applying complex policy rules is impossible without a centralized system. RADIUS is the solution, finding essential use cases in:

• Internet Service Providers (ISPs): Managing subscriber access over PPPoE, DHCP, or captive portals.
• Enterprise Networks & Wi-Fi: Securing employee access to corporate WLANs and internal systems.
• VPNs (Virtual Private Networks): Authenticating remote users before granting access to corporate resources.
• Universities: Providing secure, credential-based WiFi access for students and staff.

Setup FreeRADIUS

FreeRADIUS is the open-source implementation of the RADIUS protocol. It is used by some of the world’s largest ISPs and enterprises and guest what ? It’s free and open source. Developed in C, this software is almost available on all major GNU/Linux distributions as Ubuntu, Debian, Fedora or OpenSUSE.

1. Installation

Installation is straightforward on most Linux distributions. On Ubuntu 22.04, you can install it with:

$ sudo apt update
$ sudo apt install freeradius freeradius-mysql freeradius-utils

Note: The package and configuration directory may vary. On Debian/Ubuntu, the server is called freeradius and configuration files are in /etc/freeradius/ (versions 3.0+), while older guides may reference radiusd and /etc/raddb/.

Configure FreeRADIUS

Basic configuration

The main configuration files are located in /etc/freeradius/. Before integrating a database, test the basic setup using the default file-based authentication.

• Edit the client configuration (/etc/freeradius/clients.conf) to define your network device (NAS – e.g., your BNG or router) and a shared secret for secure communication.
• Start the FreeRADIUS server in debug mode to see detailed logs:
• In a new terminal, test authentication using the built-in radtest tool and a default user listed in /etc/freeradius/mods-config/files/authorize:

sudo systemctl stop freeradiussudo freeradius -X

radtest testing password localhost 0 testing123

You should see the server respond with an Access-Accept message in the debug output, indicating a successful test.

Configure with MariaDB (or MySQL)

For a dynamic, scalable user database, integrating SQL is essential.

• Install MariaDB: sudo apt install mariadb-server
• Configure Database: Secure the installation and create a database schema for FreeRADIUS. You can use the official schema provided in /etc/freeradius/mods-config/sql/main/mysql/schema.sql.
• Configure FreeRADIUS SQL Module: Enable and configure the sql module by editing /etc/freeradius/mods-available/sql. Point the connection details to your MariaDB instance and database.
• Update Sites: Ensure the sql module is being called in your virtual server configuration (typically in /etc/freeradius/sites-available/default).

sudo ln -s /etc/freeradius/mods-available/sql /etc/freeradius/mods-enabled/

Configure with RLM REST API

For ultimate flexibility, you can have FreeRADIUS authenticate against your existing customer API or user dashboard using the rlm_rest module. This allows you to:

• Validate credentials against a web application’s database.
• Dynamically generate custom RADIUS reply attributes based on API responses.
• Integrate with modern authentication providers.

Configuration involves enabling the rest module and defining the endpoint URL, HTTP method, and how to translate the RADIUS request into API parameters and vice-versa.

Conclusion

Implementing FreeRADIUS moves network authentication from a manual, decentralised chore to an automated, centralised strategy. By leveraging its powerful SQL integration, you can manage thousands of users dynamically. Furthermore, the REST module opens doors to nearly limitless integration possibilities, allowing you to weave RADIUS authentication directly into your existing business logic and user management systems.

Whether you’re building a new ISP network or securing a large enterprise, FreeRADIUS provides the robust, scalable AAA foundation you need to ensure secure and manageable network access.