Managed Devices#

Some organizations like to have an “always on VPN”, or “system VPN” for their managed devices, meaning: the VPN is already connected before the user is even authenticating to the device. Use cases are for example:

The service(s) required to complete the user authentication are only available on-premises, or through VPN;
Not require the users to do anything to be on the VPN, it just works automatically without needing to manually use a VPN client.

There are a number of aspects involved to make this work:

Configure the VPN server to handle these kinds of connections;
Configure the device(s) to set up the VPN as a system service.

NOTE: we limit our instructions to WireGuard only, it SHOULD work for OpenVPN as well, but we did not (yet) extensively test this.

NOTE: below we will configure everything manually, if you have a way to provision your managed devices, you can and should leverage that ability. How to do this exactly, is out of scope for this document as it highly organization specific.

Server#

Typically you will want to create one or more profiles for your managed devices to connect to. Ideally “split tunnel” so only the traffic strictly required goes over the VPN, if for no other purpose as to avoid operating system updates or streaming video to go over the VPN. Of course, your situation may be different, and require “full tunnel”, so this is just a recommendation.

In addition, when deploying the VPN server, VPN configuration expire after 90 days (by default). For a “system VPN” this is a bit short, especially if you can secure the configuration in such a way that the user can not access the configuration in any way and thus limit the risk of it being exposed or compromised.

You could for example choose to allow those configurations to be valid for 1 year, 3 years, or even longer as you can manage the individual device configurations through the Admin UI anyway. It is also possible to have multiple expiry values, for example the configurations on your managed devices expire after 3 years, but “bring your own” VPN users’ configurations expire after e.g. 1 week.

Another option is to have two separate VPN servers, one for your managed devices, and one for your “bring your own” VPN users. That way, you can separate everything, and there’s no need to expose the VPN server’s web interface or API at all.

In order to set everything up on the server, we take the following steps:

Create a “Managed Devices” Profile;
Configurable Expiry;
Enable the Admin API;
(Bulk) create VPN configurations with the Admin API that expire after 3 years
Manage the VPN connections of your managed devices through the Admin UI.

Profile#

NOTE: below we create the profile configuration as JSON instead of modifying the main PHP configuration file, but both are possible.

The profile configuration looks like this:

{
    "defaultGateway": false,
    "displayName": "Managed Devices",
    "dnsSearchDomainList": [
        "example.org"
    ],
    "dnsServerList": [
        "192.168.5.123",
        "fd9f:10b3:9ae7:5::123"
    ],
    "hostName": "vpn.example.org",
    "profileId": "managed-devices",
    "routeList": [
        "192.168.0.0/16",
        "fd9f:10b3:9ae7::/48"
    ],
    "wRangeFour": "10.38.208.0/20",
    "wRangeSix": "fd04:ab05:e096:490d::/64"
}

You can store it at /etc/vpn-user-portal/profiles/managed-devices.json, if the profiles directory does not (yet) exist you can create it. It is also possible to add the profile (using PHP syntax) in /etc/vpn-user-portal/config.php instead.

Expiry#

In order to allow creating VPN configurations that expire after, say, 3 years, we need to modify the portal configuration as well in /etc/vpn-user-portal/config.php. Search for sessionExpiry. By default it is set to P90D, which we’ll leave in this case to its default. We add the supportedSessionExpiry option right below it:

'sessionExpiry' => 'P90D',
'supportedSessionExpiry' => ['P3Y'],

NOTE: we do not have to explicitly add the value of sessionExpiry to supportedSessionExpiry as well, it is supported automatically. It does not hurt to add it, if you want.

Admin API#

In order to activate the “Admin API”, you can follow the instructions here. It may be sufficient to generate the key, and nothing more. Feel free to look around the various API calls that are supported to get an idea of what is possible.

Create Configurations#

Now in order to create configurations, we use a script with curl to create a bunch of configuration files. We assume that you have a way to uniquely address your managed devices, e.g. using an alias, or hostname. As a simple example, we create 3 configurations (in a loop) for our devices.

You can set the user_id field to an account name you’d like to use, it does not (yet) need to exist, and does not need to be a “real” account.

#!/bin/sh

API_KEY=${1}
DEVICE_NAMES="dev0001 dev0002 dev0003"

for DEVICE_NAME in ${DEVICE_NAMES}; do
    curl -o "${DEVICE_NAME}.conf" \
         -H "Authorization: Bearer ${API_KEY}" \
         -d "user_id=admin" \
         -d "display_name=${DEVICE_NAME}" \
         -d "profile_id=managed-devices" \
         -d "expires_in=P3Y" \
         https://vpn.example.org/vpn-user-portal/admin/api/v1/create
done

You can run the script, with the API key you generated in /etc/vpn-user-portal/keys/admin-api.key as the first parameter.

This results in three .conf files in your current directory, those files need to be distributed to the managed devices.

Client#

Previously we created three configuration files that now need to be distributed to the managed devices.

How to do this exactly depends on the means your organization has to exactly do this. Conceptually it is very easy: push a configuration file to the device, and start/enable a service. Below we’ll show the steps needed to do this on a specific OS, how to exactly automate that for your organization is out of scope as we assume that there is no “common” approach taken by organizations.

Windows#

Full details can be found here. We’ll just quickly go over some commands.

Make sure your user account is member of the Administrators group to set everything up. Normal users, won’t be able to manage the WireGuard connections afterwards, only the admin(s).

You can install WireGuard using the MSI.

Copy your configuration file, e.g. dev0001.conf to C:\Program Files\WireGuard\Data\Configurations\dev0001.conf and then start the WireGuard UI. It should show the WireGuard configuration. Enable it.

Other Tricks#

By default the interface will be put in the “Public” network category. You can move it for example “Private” if that is needed to allow certain incoming connections to your managed devices.

You can use PowerShell (as Administrator) to set the “NetworkCategory”:

> Set-NetConnectionProfile -Name "dev0001" -NetworkCategory "Private"

The default firewall will also not allow ICMP echo (ping). You can modify the firewall to allow this. I used that to test that the VPN was actually up before any user logged in. This is of course optional!

Start the firewall UI by running fw.msc. Select “Inbound Rules” and search for “Core Networking Diagnostics - ICMP Echo Request (ICMPv4-In)” with the profile “Private,Public”. Right click on it and choose “Enable Rule”. There is also one for IPv6. Enable that one as well. Now you can ping your devices from your VPN server.

If you want your VPN clients to be always online, even when no traffic goes over it, you MAY want to enable WireGuard Keepalive.

macOS#

TBD.

Linux#

TBD.