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 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 an “interesting” algorithm to encrypt the user’s password AND allows for manipulation of RADIUS responses by an attacker “on the line”

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

NOTE: vpn-user-portal >= 3.9.0 removes support for the RADIUS PECL extension (on Debian 11).

NOTE: the permissionAttributeList and timeOutSec options are available in vpn-user-portal >= 3.8.0.

NOTE: the maxRetry and requireMessageAuthenticator options are available in vpn-user-portal >= 3.9.0.

NOTE: in vpn-user-portal >= 3.9.0 the “Challenge/Response” authentication is supported, see Challenge/Response.

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',
    ],

    // Add "realm" to the user provided "Username"
    // Previously called "addRealm", both still work
    // DEFAULT = N/A
    //'radiusRealm' => 'example.org',

    // Identifier to send to the RADIUS server
    // DEFAULT = "VPN Server"
    //'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,

    // Configure the number of attempts a server should be contacted before 
    // giving up (and moving to the next one, if configured)
    // DEFAULT = 3 times
    //'maxRetry' => 3,

    // DEFAULT = false
    // You really SHOULD, enable this if your RADIUS server supports this, or
    // can be configured to use Message-Authenticator!
    'requireMessageAuthenticator' => true,

    // Attribute to use for Permissions (Legacy)
    // Single "integer" only, you can also use `permissionAttributeList`
    //'permissionAttribute' => 18,

    // Attributes to use for Permissions
    //'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 radiusRealm option (previously called addRealm) when set to example.org modifies the user ID to foo@example.org and uses that to authenticate to the RADIUS server.

When more than one server has been configured, the client will attempt to connect to them in random “round robin” order.

Permissions#

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

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

The first one is considered legacy, but it will remain working. You should probably use 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.

Challenge/Response#

Together with php-radius 2.x, “Challenge/Response” authentication is supported. This means that the user will authenticate with their username/password and then be prompted to provide an additional credential, e.g. a TOTP code.

Challenge/Response will work out of the box, however you SHOULD modify your RADIUS server to provide a useful Reply-Message together with the Access-Challenge reply, as the value of the Reply-Message is used to “customize” the prompt:

Please let us know if you have any problems, see the next section on how to debug RADIUS issues.

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.