wwRadius: WWPass authentication for FreeRadius

Solution architecture#

wwRadius brings three additional components to the VPN client/server system

  • WWPass client - GUI application installed on user terminal
  • WWPass Helper - server side WWPass Service Provider
  • rlm_wwpass - freeradius module which extends freeradius server

wwRadius / Blocks

Authentication Sequence#

Message Sequence chart of user authentication is shown on the following diagrams

wwRadius / Message Sequence chart

  1. User initiates a connection in WWPass Client GUI application. After WWPass Key is authenticated, WWPassClient connects to RaduisHelper.
  2. RadiusHelper downloads corresponding WWPass DataContainer and gets username
  3. RadiusHelper generates one-time-password (OTP) and sends it along with username to WWPass Client
  4. WWPass Client starts VPN client, supplying it with username and OTP

wwRadius / Message Sequence chart

  1. VPN client connects to VPN server in order to create a tunnel. Username and OTP are given to VPN server
  2. VPN server asks Radius server to authenticate user. In accordance with Radius configuration, rlm_wwpass module is activated first.
  3. rlm_wwpass module checks (username,OTP) with Radius Helper
  4. Radius server confirms user rights to VPN server
  5. The tunnel is established

Initial key binding#

If there is no username yet in the DataContainer (i.e. user WWPass Key is not binded to Radius data), the scenario changes:

wwRadius / Initial key binding

  1. User initiates a connection in WWPass Client GUI application. After WWPass Key is authenticated, WWPassClient connects to RaduisHelper.
  2. RadiusHelper downloads empty cWWPass DataContainer
  3. RadiusHelper requsets WWPass client to provide radius username and password
  4. The (username,password) pair is returned to RadiusHelper
  5. RadiusHelper checks with Radius Server if user credentials are correct
  6. If yes, username is stored in WWPass DataContainer

INSTALL: Ubuntu LTS 14.04 and 12.04#

Installation procedures are almost identical for both distributions.

Building rlm_wwpass module.


dpkg-dev (sudo apt-get install dpkg-dev) one of libcurl-dev (e.g. libcurl4-openssl-dev)

Create new directory - say build, cd into it and do the following:

apt-get source freeradius
sudo apt-get build-dep freeradius
cd freeradius-2.1.12+dfsg/

Now copy wwradius.git/rlm_wwpass directory into freeradius-xxx/src/modules and add a line


to the freeradius-xxx/src/modules/stable file

Next compile the package:

make deb

make deb means precisely

fakeroot dpkg-buildpackage -b -uc

If the packages were created successfully, you will find them in a directory you created at the very beginning (parent of freeradius-2.1.12+dfsg/)

there will be 12 DEB files total.

Install at least the bare minimum:

sudo dpkg -i freeradius_2.1.12+dfsg-1.2ubuntu8_amd64.deb \
libfreeradius2_2.1.12+dfsg-1.2ubuntu8_amd64.deb \

We also recommend to install freeradius-utils (radclient, radtest etc)

sudo dpkg -i freeradius-utils_2.1.12+dfsg-1.2ubuntu8_amd64.deb

Now we may need to disable automatic package update of the newly compiled freeradius.

The procedure is called ”Holding Packages” and is accomplished with the following command:

sudo apt-mark hold freeradius

See full Ubuntu documentation

Installation & Configuration#

In the directory /etc/freeradius/modules

create file wwpass with the following content:

wwpass {

In FreeRadius site configuration ( e.g. /etc/freeradius/sites-enabled/default) add a line


in the beginning of “authorize” section and lines

Auth-Type WWPASS {

in the beginning of “authenticate” section


when rlm_wwpass cannot connect to rhelper, it returns “notfound”

* connect to ::1 port 10060 failed: Connection refused
* Trying
* connect to port 10060 failed: Connection refused
* Failed to connect to localhost port 10060: Connection refused
* Closing connection 0
++[wwpass] returns notfound
++[preprocess] returns ok

and control is passed to the next module



  • ssl-cert,
  • python >= 2.6,
  • python-tornado >= 3.1,
  • python-crypto>=2.6.1,
  • python-pyrad >= 2.0

tornado version in Ubuntu 12.04 is 2.1. Use the following command to update tornado:

sudo pip install --upgrade tornado

Copy the rhelper directory to any suitable location - e.g. /usr/lib. Modify config.conf: set proper paths of certificate and private key files for your WWPass Service Provider (go to manage.wwpass.com to obtain a certificate). Also fill parameters of your RADIUS server in config.conf . Then run:

python rhelper.py

You may also want to make this service run automatically on server startup. Use the way appropriate to your OS.

Ubuntu server: create file /etc/init/wwradius-helper.conf

with the following content:

description "WWPass Radius Helper module"
start on runlevel [2345]
stop on runlevel [!2345]
exec sudo -u freerad /usr/bin/python /usr/lib/radius-helper/rhelper.py

CentOS 7: install the hard way#

Building rlm_wwpass module#

Same as with Ubuntu distribution, the rlm_wwpass module should be compiled as a part of source freeradius package, thus producing distribution-compatible RPM.

Here are links to relevant CentOS documentation:



Install the packages needed to handle source rmps:

yum install rpm-build
yum install redhat-rpm-config

Create "rpmbuild" directory in your home directory

mkdir ~/rpmbuild

Get the source from http://vault.centos.org/:

go to http://vault.centos.org/7.0.1406/os/Source/SPackages/ and download freeradius-3.0.1-6.el7.src.rpm

install the package:

rpm -i freeradius-3.0.1-6.el7.src.rpm

Prepare patch file

cd ~/rpmbuild/SPECS
rpmbuild -bp freeradius.spec

copy ~/rpmbuild/BUILD/freeraadius-server-3.0.1 to any directory - let it be e.g. ~/temp, the copy will be used as a reference for patching

copy /rlm_wwpass directory from wwRadius distribution to ~/rpmbuild/BUILD/freeraadius-server-3.0.1/src/modules and add a line


to the ~/rpmbuild/BUILD/freeraadius-server-3.0.1/src/modules/stable file

go to the ~/temp directory and execute the diff command

diff -rupN freeradius-server-3.0.1 ~/rpmbuild/BUILD/freeradius-server-3.0.1 > ~/rpmbuild/SOURCES/freeradius-rlm_wwpass.patch

Edit ~/rpmbuild/SPECS/freeradius.spec file, add line

Patch8: freeradius-rlm_wwpass.patch

as a last line of the patch list section

now locate a line which starts with %setup, find a list of commands applying patches, add a new line:

%patch8 -p1

finally add the following line to the %files section:


build the rpm

rpmbuild -bb freeradius.spec

New RPMs will be written into ~/rpmbuild/RPMS

CentOS radius setup#

yum install freeradius freeradius-utils

CentOS keeps confiuration in /etc/raddb with ownership root:radiusd