Radius#

This document describes how to configure RADIUS for deployed systems. We assume you used the deploy_${DIST}.sh script to deploy the software. Below we assume you use vpn.example, but modify this domain to your own domain name!

In order to make a particular user an “administrator” in the portal, see Portal Admin.

NOTE: You absolutely MUST make sure the communication between the VPN server and the RADIUS server is done over a secure network, the security of RADIUS (with PAP) depends on md5 and in some cases hmac-md5, so please be careful :)

NOTE: RADIUS integration only supports “PAP”, not EAP, nor (T)TLS.

NOTE: If you have the choice between LDAP and RADIUS, always choose LDAP! LDAP is supported by all common IdMs, even Active Directory. Look here for instructions on how to configure LDAP.

Initially, RADIUS support was only available on Debian 11 using the php-radius package (a PHP extension). Support for it was dropped in Debian (and other supported operating systems) as the PHP extension not supported PHP >= 8.

We developed a RADIUS library that works on all versions of PHP. See its page for more information. It will be used by default on all operating systems. The new client is available in vpn-user-portal >= 3.4.2.

The permissionAttributeList and timeOutSec options are available in vpn-user-portal >= 3.8.0.

If you are currently using RADIUS on Debian 11 you will keep using the PHP extension, unless you remove the PHP extension manually. See Debian 11 below.

Configuration#

You can configure the portal to use RADIUS. This is done in the file /etc/vpn-user-portal/config.php.

'authModule' => 'RadiusAuthModule',

// ...

'RadiusAuthModule' => [
    'serverList' => [
        // Format: HOST:PORT:SECRET
        'radius.example.org:1812:testing123',

        // IPv4 address
        // '192.0.2.10:1812:s3cr3t',

        // IPv6 address
        // '[2001:db8::10]:1812:s3cr3t',
    ],

    'addRealm' => 'example.org',
    'nasIdentifier' => 'vpn.example.org',

    // configure the time (in seconds) we wait for a RADIUS server response 
    // before giving up (and move to the next if >1 server is configured)
    // DEFAULT = 3 seconds
    'timeOutSec' => 3,

    // Attribute (int) to use for Permissions
    // With PHP extension and PHP library
    //'permissionAttribute' => 18,

    // Attributes to use for Permissions
    // With PHP library only
    //'permissionAttributeList' => ['Reply-Message', '3076.25'],
],

Here serverList is an array of server configurations where you can add multiple RADIUS servers to be used for user authentication. The format is HOST:PORT:SECRET, see the examples above.

You can also configure whether or not to add a “realm” to the identifier the user provides. If for example the user provides foo as a user ID, the addRealm option when set to example.org modifies the user ID to foo@example.org and uses that to authenticate to the RADIUS server.

Permissions#

There are two ways to configure using RADIUS response attributes as “Permissions”:

Use int value with permissionAttribute;
Use array<string> value(s) with permissionAttributeList.

The first one works both with the PHP extension as well as the PHP library. If you can choose, use the second option, i.e.: permissionAttributeList. The list of available attributes can be found here.

As an example, if you want to use the Reply-Message RADIUS attribute, you would configure it like this for scenario 1:

'permissionAttribute' => 18,

For scenario 2:

'permissionAttributeList' => ['Reply-Message'],

With scenario 2 you can also use VSAs (Vendor Specific Attributes). If you want to for example use Cisco-ASA.ASA-Group-Policy you can configure it like this:

'permissionAttributeList' => ['3076.25'],

Here, 3076 is the Vendor ID of Cisco-ASA and 25 the attribute ASA-Group-Policy. You can talk to your RADIUS server operator to figure out what you can use in your case.

See Permissions on how to use these permissions in the VPN server.

Problems#

In case you can’t figure out why RADIUS is not working for you, we recommend you follow instructions here to test your setup. If it works there, it will work with the VPN server.

If you can’t get it to work for you, please contact us so we can figure out how to properly support your RADIUS server.

Debian 11#

If you were using RADIUS on Debian 11 before the release of vpn-user-portal 3.4.2 you are using the php-radius PHP extension.

If you deploy a new VPN server (on Debian 11 or any other OS) with vpn-user-portal >= 3.4.2, you’ll use the new library.

Use PHP extension#

NOTE: only works on Debian 11.

If you want to use the PHP extension:

$ sudo apt install php-radius
$ sudo systemctl restart php$(/usr/sbin/phpquery -V)-fpm

If the new library does not work, please contact us so we can get it to work! If you want to debug the issue, look here.

Use PHP Library#

If you are using the PHP extension, and want to switch to the new library, you can do that as well:

$ sudo apt remove php-radius
$ sudo systemctl restart php$(/usr/sbin/phpquery -V)-fpm

If the new library does not work, please contact us so we can get it to work! On Debian 11 you can switch back, see previous section. If you want to debug the issue, look here.