REST API Server for FreeRADIUS

A simple REST Server for the FreeRadius rlm_rest module based on node.js and Express.js Framework.

Intro

This is a complete working API for the rlm_rest module that enables Freeradius to authenticate via http. In this particular case I used MongoDB as the data storage, but essencialy any DB could be used. Logic for authentication is completely executed by the API.

Installation

Basics

Basicly we only need node.js, mongoDB and FreeRadius. Install node.js, MongoDB and Git on Debian based distros with:

curl -sL https://deb.nodesource.com/setup_7.x | bash -
apt-get install -y nodejs  mongodb-org git

FreeRADIUS

Unfortunately it's very hard to find FreeRADIUS prebuild with the rlm_rest module, no apt-get here. But we can build it ourselves with these steps:

Install build dependencies with:

apt-get install -y build-essential libssl-dev libcurl4-openssl-dev libjson-c-dev

Then download and build FreeRADIUS with:

git clone -b v3.0.x https://github.com/FreeRADIUS/freeradius-server.git
cd freeradius-server
./configure
make
make install

Configure FreeRADIUS to startup on boot and start it:

cp /usr/local/sbin/rc.radiusd /etc/init.d/radiusd
chmod 755 /etc/init.d/radiusd
/etc/init.d/radiusd start

API Install

Now install this API with:

git clone https://github.com/fgsants/REST-API-FreeRADIUS.git
cd REST-API-FreeRADIUS
npm install

And finaly, copy the FreeRADIUS config files:

cp resources/freeradius/nano /usr/local/etc/raddb/sites-enabled/nano
cp resources/freeradius/rest /usr/local/etc/raddb/mods-enabled/rest
cp resources/freeradius/radiusd.conf /usr/local/etc/raddb/radiusd.conf

Starting everything up

Start the API server with npm run start. The API will be available at http://localhost:4000

The API in depth

All details, addicional info, endpoints an how the API works are described below.

What can I do with it and how it works?

This API enables you to create and manipulate users and access profiles that can be authenticated with FreeRADIUS. It verifies information provided by the NAS to the radius server to decide if the user is authorized to authenticate and, if it's the case, passes attributes to the server (like max download speed, etc...).

This API comes ready to be used in a simple ISP scenario where you can add users, upload and download speed policies. But can be expanded to cover much more by simply expanding the DB schema and authentication logic.

It can also receive FreeRADIUS accounting logs and save it to MongoDB for later use and analysis.

Endpoint

The API has two main categories as enpoints:

• Radius - Used to communicate with the FreeRADIUS server.
• DB Manipulation - Used to create, edit and remove entries in the database.

Radius endpoints

/check (GET) | Checks if the user exists in the DB, if true, 'Authorize' in FreeRADIUS succeeds and sets Auth-Type to REST.

/auth (GET) | Checks if password is correcct and executes login logic. If ok, send attributes to FreeRadius and authenticates the user.

/accounting (POST) | Receives accounting info from FreeRADIUS and logs it to DB.

DB endpoints

/users (GET, POST) | GET: Lists all users in the DB | POST: Creates user

/users/:userID (PUT, DELETE) | Updates or removes user.

/profiles (GET, POST) | GET: Lists all profiles in the DB | POST: Creates profile

/profiles/:profileID (PUT, DELETE) | Updates or removes profile.

Securing your setup

This API dosn't have any security built in. If you'll use it somewhere please modify it to include some sort of authentication. The rlm_rest module also supports http auth enpoints, but for simplification reasons I did't configured it. PLease read the rest module config on how to implement it. Also, please read the MongoDB guidelines on how to secure it too.