Server 3.x

Guest Access#

This document describes how to enable “Guest Access”. This is a feature provided to the eduVPN community. It is NOT available for Let’s Connect!.

Participating NRENs configure an eduVPN server to allow users from servers hosted by other NRENs to access their VPN server as well.

This means for example that a user from the eduVPN server hosted in The Netherlands by SURF can access the VPN server in Germany hosted by DFN.

NOTE: the “Guest Access” server MUST be a server dedicated ONLY for this purpose. It MUST NOT be used for any other purpose like providing access to restricted resources on the network!

Eligibility / Requirements#

Only NRENs are able to register a server for “Guest Access”. We MAY request a introduction (video) call if none of the eduVPN team has met you before.

You MUST use SAML authentication for your VPN server and provide us with a link to the SAML metadata for all IdPs (Identity Providers) that have access to your server. We need this information to populate the organizations list in the eduVPN applications. Without SAML metadata URL you can still participate, but your local users won’t be able to access any of the other “Guest Access” servers.

Currently we do NOT recommend registering your VPN server in eduGAIN!

In order to enable “Guest Access” on your server you MUST have vpn-user-portal >= 3.1. In older versions it will NOT work.


The “Guest Access” functionality MUST be manually enabled.

You need to edit /etc/vpn-user-portal/config.php and modify the Api section:

'Api' => [
    'enableGuestAccess' => true,

After enabling “Guest Access” you MUST reset your server to remove all data. With “Guest Access” enabled you’ll get new “User IDs” which will break e.g. OAuth. With this reset you’ll delete all existing user accounts, invalidate all VPN configurations and associated OAuth authorizations.

$ sudo vpn-maint-reset-system

Next you need to generate a HMAC key that will be used to “obfuscate” the user identifiers of your users as to not “leak” them to other NREN servers.

$ sudo /usr/libexec/vpn-user-portal/generate-secrets --hmac

If you were using the adminUserIdList option in /etc/vpn-user-portal/config.php to list your admins, you MUST update them to list the new “User IDs”. Have your admins look on their “Account” page in the portal so you can add them. For more information on admin accounts you can look here.

Public Key#

We need to register your OAuth public key in our “discovery” file to allow all participating servers to fetch it and allow users from your VPN service.

You can find this Public Key by going to the “Info” tab, with an admin account, in your VPN portal. Expand the “Server” section by clicking “More” and look for “Public Key” under “OAuth”. It has the following form:

Make note of this public key as you need it for your server’s registration.


Please contact and provide use with the following information:

Use “Add [${FQDN}] to Secure Internet eduVPN” as “Subject” of the mail.


Subject: Add [] to Secure Internet eduVPN


Generic Contact:
Abuse Contact:
Technical Contact:
End-user Support Contact: 
  - +1234567890
Information Website:
SAML Metadata:
Country / Region: The Netherlands
  - in/outbound tcp/25 blocked
Public Key:

Do NOT forget to attach the signed copy of the policy document!


Once deployed, it may be interesting to figure out whether your service is used and by whom.

Guest Users#

To show how many guest users there are, you can use the including tooling, e.g.:

$ sudo vpn-user-portal-account --list | grep '@' | cut -d '@' -f 2 | sort | uniq -c | sort -n -r

Here you can see how many unique users arrive from a particular other country. Of course you could have also seen that on the portal’s “Users” tab, but this makes it easier to automatically count them.

If you are more interested in getting results about the actual use on a particular date, you can try this:

$ sudo sqlite3 \
    /var/lib/vpn-user-portal/db.sqlite \
    "SELECT DATE(connected_at) AS date, COUNT(DISTINCT user_id) as unique_guest_user_count FROM connection_log WHERE user_id LIKE '%@%' GROUP BY date ORDER BY connected_at"

Local Users#

When “Guest Access” is enabled, and you also have local users, you can also figure out who they are, depending on your server’s configuration. For example, if you use Shibboleth for user authentication, and you use the eduPersonTargetedID attribute (or any other that contains the domain (or scope) of the organization the user originates from) you can do this.

When “Guest Access” is enabled, a “pseudonymous” identifier is generated for each user account and the original identifier is stored in the auth_data column of the users table as JSON. This is done as to not “leak” the local user identifier to other servers.

When using the eduPersonTargetedID attribute, the value has the format ${IDP_ENTITY_ID}!${SP_ENTITY_ID}!${USER_ID}, for example!!588b17cf3a31012abb4860ae6faf440b6da006fe.

Now to figure out which “IdPs” are used and by how many users, we can query the database:

$ sudo sqlite3 \
    /var/lib/vpn-user-portal/db.sqlite \
    "SELECT json_extract(auth_data, '$.userId') FROM users WHERE user_id NOT LIKE '%@%'" \
    | cut -d '!' -f 1 \
    | sort \
    | uniq -c \
    | sort -r -n

This will output IdPs used together with how many users of each IdP used the service.