This document will describe how an application should work with the VPN API, i.e. it will provide flow diagrams containing the steps that should be taken.
A VPN service running at a particular domain is called an instance, e.g.
demo.eduvpn.nl. An instance can have multiple profiles, e.g.
This assumes the user already configured the application with their favorite VPN instance and profile and that there are no errors.
info.jsontogether with the already stored OAuth access token and displays them to the user;
Step 3 is needed as the API configuration, e.g. endpoints, can change over time. Step 6 is needed as the server configuration can change over time, e.g. new TLS cipher configuration or new VPN endpoints.
Step 4 exposes whether or not the user is enrolled for 2FA, and whether or not the user is blocked. This information should be used by the application before attempting to connect. If a profile requires 2FA and the user is not enrolled, this should be indicated to the user and the enrollment process started by opening the browser.
Adding a new instance/profile to the app consists of:
After the enrollment the Basic Flow is executed starting at step 4.
Steps 6 and 7 consist of obtaining the current VPN configuration, and combining this configuration with the client certificate and key.
Obtained configurations have everything, except the client certificate and private key.
The profile configuration is currently an OpenVPN configuration file, without
<key> fields. So to make a complete OpenVPN configuration
file these need to be merged by adding
<key> with the values
from the client certificate and private key.
Many of the OAuth considerations are part of API. An application will have to deal with expiring access tokens, revoked access tokens and refreshing them when needed, possibly using refresh tokens if they were provided.
A connection to a VPN server can fail for a number of reasons:
The application should deal with all this situations, deal with the issue automatically if possible, and if not show an appropriate error message.
NOTE: a blocked user will still be able to do everything using the API,
connecting the VPN will be blocked though, this information is also exposed
NOTE: for various situations the OpenVPN process will give the same error,
i.e. for 2FA error, blocked user or ACL issues the same "authentication error"
is returned. A profile is not listed in the
/profile_list call if the user is
not member of the required groups (anymore) and the
/user_info call will
indicate whether the user is blocked. So it is possible that a
no longer shows a previously configured VPN profile because the user no longer
has access. Appropriate errors need to be shown to the user.
More details on the API can be found in the separate API.
This section contains a list of changes in the future that should already be contemplated, although not necessarily implemented, not all is implemented at this time in the API.
It will be required for an app to store the client certificate and key in a "protected" storage on the device, e.g. a secure element or otherwise tamper proof storage.
The application can (and must) generate their own key and have it signed by the API, this way the private key never leaves the device the app is running on.