APIv4 (Draft)#

NOTE: Work in Progress!

This document describes version 4 of the API provided by eduVPN and Let’s Connect! servers.

See Changes from APIv3 for a list of changes since our current APIv3.

The API is intended to be used by the eduVPN and Let’s Connect! applications. If you are creating your own application, look here how to register your own client in the server.

Using this document you should be able to implement the API in your VPN client, or provide the same API for your VPN server to leverage the existing VPN clients.

Standards#

We use a simple HTTP API protected by OAuth 2, following all recommendations of the OAuth 2.1 draft specification.

For some further implementation notes and recommendations for the client, please read this document.

Server Discovery#

As there are many servers running eduVPN / Let’s Connect! you need to know which server you need to connect to. This can be either hard-coded in the application, the user can be asked to provide a server address or a “discovery” can be implemented.

For eduVPN specific we implement “server discovery” as documented here.

Server Endpoint Discovery#

A “well-known” URL is provided to figure out the OAuth and API endpoint one has to use. The document can be retrieved from /.well-known/vpn-user-portal, e.g.:

{
    "api": {
        "http://eduvpn.org/api#4": {
            "api_endpoint": "https://vpn.example.org/vpn-user-portal/api/v4",
            "authorization_endpoint": "https://vpn.example.org/vpn-user-portal/oauth/authorize",
            "token_endpoint": "https://vpn.example.org/vpn-user-portal/oauth/token"
        }
    },
    "v": "4.0.0-1.fc41"
}

Servers that provide the http://eduvpn.org/api#4 key under api, support this API.

The application MUST retrieve this document at least once per application run, i.e. if the user restarts the application this document MUST be retrieved fresh for each server the client interacts with. An application MAY opt to refresh the document more frequently.

Endpoint Location#

When fetching this document, redirects, e.g. 301, 302, 303, 307 or 308 MUST be followed, but MUST NOT allow redirect to anything else than other https:// URLs, e.g. redirects to http:// MUST be rejected.

Authorization Endpoint#

The authorization_endpoint is used to obtain an authorization code through an “Authorization Request”. The following parameters MUST be set:

client_id;
redirect_uri;
response_type: MUST be code;
scope: MUST be config;
state;
code_challenge_method: MUST be S256;
code_challenge.

When the client’s redirect_uri is the “Loopback Interface Redirection” URL, it MUST add the response_mode parameter with the value form_post, otherwise it can be ignored.

The authorization_endpoint with its parameters set MUST be opened in the platform’s default browser or follow the platform’s best practice dealing with application authorization(s). The redirect_uri parameter MUST point back to a location the application can intercept.

All error conditions, both during the authorization phase AND when talking to the API endpoint MUST be handled according to the OAuth specification(s).

Token Endpoint#

The token_endpoint is used to exchange the authorization code for an access and refresh token. The authorization code is obtained through the query parameters added to the redirect_uri, or through the POST body to the redirect_uri. The token endpoint is also used to obtain new access tokens when the current one expires.

All error conditions, both during the authorization phase AND when talking to the API endpoint MUST be handled according to the OAuth specification(s).

Using the API#

Every API call below will include a cURL example, and an example response that can be expected.

All POST requests MUST be sent encoded as application/x-www-form-urlencoded.

The API can be used with the access token obtained using the OAuth flow as documented above. The following API calls are available:

Get a list of “Profiles” from the VPN server (/profiles);
“Connect” to a VPN profile (/connect);
“Disconnect” from a VPN profile (/disconnect)

API Calls#

Profiles#

This call will show the available VPN profiles for this instance. This will allow the application to show the user which profiles are available.

This GET call has no parameters.

Request#

Request all available VPN profiles:

$ curl \
    -H "Authorization: Bearer abcdefgh" \
    https://vpn.example.org/vpn-user-portal/api/v4/profiles

Response#

HTTP/1.1 200 OK
Content-Type: application/json

{
    "profiles": [
        {
            "description": {
                "en": "Access to files and printers.",
                "nl": "Toegang tot bestanden en printers."
            },
            "id": "employees",
            "name": {
                "en": "Employees",
                "nl": "Medewerkers"
            },
            "priority": 0
        },
        {
            "description": {
                "en": "Access to network and virtual machine management systems."
            },
            "id": "admins",
            "name": {
                "en": "Administrators"
            },
            "priority": 5
        }
    ]
}

The fields are described in the table below, look under the table for additional information.

Key	Always Set	Type	Description	Since	Deprecated
`id`	Yes	`string`	Profile ID	4.0.0	No
`name`	Yes	`object`	Human readable name(s) for profile	4.0.0	No
`priority`	Yes	`int`	Hint for client to sorting the available profiles, highest number first	4.0.0	No
`description`	No	`object`	Human readable description(s) for profile	4.0.0	No

The id of type string is a unique identifier for the profile.

The name is a JSON object of the type map[string]string, i.e. it contains a mapping from language code to (translated) string. It should contain a short (human readable) name of the profile, e.g. “Students”.

The description is a JSON object of the type map[string]string, i.e. it contains a mapping from language code to (translated) string. It should contain a longer (human readable) description of the profile, e.g. “Get access to the library, file shares and printers.”

The priority is an unsigned int between 0 and 65535. The highest numeric value has the highest priority. If the values are identical between profiles, the order is undefined.

TBD: should we still allow negative numbers? Should we make the lowest value have priority instead of the highest?!

TBD: describe which chars are allowed in which fields, e.g. id probably uses a limited vocabulary that is “file system” and “URL safe”. The rest, UTF-8…

Connect#

Get the profile configuration for the profile you want to connect to.

Request#

Connect to the “Employees” profile (employees) and specify the WireGuard public key of the key pair that was generated on-device:

$ curl \
    -H "Authorization: Bearer abcdefgh" \
    -H "Accept: application/x-wireguard-profile" \
    --data-urlencode "profile_id=employees" \
    --data-urlencode "public_key=nmZ5ExqRpLgJV9yWKlaC7KQ7EAN7eRJ4XBz9eHJPmUU=" \
    "https://vpn.example.org/vpn-user-portal/api/v4/connect"

NOTE: a call to /connect immediately invalidates any previously obtained VPN configuration that belongs to the same OAuth authorization.

The POST request has the following parameters:

Parameter	Required	Value(s)
`profile_id`	Yes	The `id` of profile to retrieve a configuration file for
`public_key`	No	WireGuard public key

See VPN Protocol Selection for more info on the Accept header.

The value of profile_id MUST be of one of the identifiers (id)s for the profiles returned in the /profiles response.

The public_key parameter MUST be set if the VPN client supports WireGuard. The value of public_key MUST be a valid WireGuard public key. It has this format:

$ wg genkey | wg pubkey
e4C2dNBB7k/U8KjS+xZdbicbZsqR1BqWIr1l924P3R4=

You MUST generate a new key pair for every server and profile combination. You MAY generate a new key pair for every call to /connect. If the key pair is to be stored on-device you SHOULD store it in a protected key store.

Response#

You’ll get a WireGuard client configuration in the wg(8) format with Content-Type: application/x-wireguard-profile, e.g.:

X-Vpn-Expires-At: Fri, 06 Aug 2021 03:59:59 GMT
X-Vpn-Gone-Interval: 259200
Content-Type: application/x-wireguard-profile

[Interface]
Address = 10.43.43.2/24,fd43::2/64
DNS = 9.9.9.9,2620:fe::fe

[Peer]
PublicKey = iWAHXts9w9fQVEbA5pVriPlAYMwwEPD5XcVCZDZn1AE=
AllowedIPs = 0.0.0.0/0,::/0
Endpoint = vpn.example:51820

As can be seen in the examples, this API response also contains some HTTP response headers:

X-Vpn-Expires-At: Date/time at which the VPN configuration expires, i.e. after which it is no longer valid. Same syntax as the HTTP Expires header.
X-Vpn-Gone-Interval: Time in seconds after which VPN connection is considered “dead” by the server if no handshake occurs within that interval. The value is a 64 bit unsigned integer. Corresponds to App Gone Interval.

The API client MUST add the PrivateKey field under [Interface] with the private key that belongs to the public key specified in the /connect request in order to get a full wg(8) compatible configuration file.

The client MUST keep track of the value of X-Vpn-Gone-Interval and check, for example, after resume from suspend, or possibly at other moments like network roaming, whether to interval was exceeded based on the last successful WireGuard handshake.

For WireGuard over TCP, see WireGuard over TCP.

TODO: add no-cache headers to prevent caching.

TODO: maybe enhance the /profiles response to also include the OAuth session expiry, that way we know when the VPN config is no longer valid. Or would the Expires header be enough?

TODO: can app-gone-interval be deleted? should we simply state that if the WG handshake time was >3 minutes ago, connection check should run again? perhaps triggered automatically after resume?

Disconnect#

This call is to indicate to the server that the VPN session(s) belonging to this OAuth authorization can be terminated.

The purpose of this call is to clean up on the server, e.g. release the IP address reserved for the client.

Request#

$ curl -X POST \
    -H "Authorization: Bearer abcdefgh" \
    "https://vpn.example.org/vpn-user-portal/api/v4/disconnect"

This POST call has no parameters.

Response#

HTTP/1.1 204 No Content

Error Responses#

Call	Example Message	Code	Description
`/connect`	`no such "profile_id"`	400 (`Bad Request`)	When the profile does not exist, or the user has no permission
`/connect`	`invalid value for "profile_id"`	400 (`Bad Request`)	When the syntax for the `profile_id` is invalid
`/connect`	`?`	406 (`Not Acceptable`)	When the profile does not support the VPN protocol(s) supported by the client (or vice versa)

TODO: other errors could be invalid public key, invalid Accept header, missing parameters, etc.

An example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"no such \"profile_id\""}

In addition to these errors, there can also be an error with the server that we did not anticipate or is an unusual situation. In that case the response code will be 500 and the JSON error key will contain more information about the error.

VPN Protocol Selection#

The client can influence the VPN protocol decision by using the HTTP request Accept header.

Value	Description
`application/x-wireguard-profile`	Accept WireGuard configurations
`application/x-openvpn-profile`	Accept OpenVPN configurations

A VPN client that supports both would have this HTTP Accept request header value:

Accept: application/x-wireguard-profile,application/x-openvpn-profile

The Accept request header MUST be set for all calls to /connect.

TBD: should we also require it to /profiles so we can filter out the profiles that offer protocols we don’t support?

WireGuard over TCP#

For tunneling WireGuard over TCP, we use ProxyGuard. For the use of ProxyGuard, we need to know a URL to use with ProxyGuard. By convention, we use the value of the Endpoint configuration key to construct it from that.

The value of Endpoint is of the format HOST:PORT. The URL for ProxyGuard becomes https://HOST/proxyguard/HOST. As the Endpoint field also supports IPv4 and IPv6 addresses, we support those as well.

Endpoint	ProxyGuard URL
`vpn.example:51820`	`https://vpn.example/proxyguard/vpn.example`
`192.0.2.5:443`	`https://192.0.2.5/proxyguard/192.0.2.5`
`[2001:db8::5]:51820`	`https://[2001:db8::5]/proxyguard/[2001:db8::5]`

NOTE: it is possible to get a server certificate for a literal IP address, Let’s Encrypt will support that in the near future.

TBD: do we still want to support the option to only have one designated reverse proxy in case of multi-node deployments, like we currently do in 3.x?

TBD: the second occurrence of /HOST can be removed from the URL if we are sure we don’t want to support a single proxy (see previous point)

TBD: do we also want to use the square brackets in the path of the URL if it is an IPv6 address?

Changes from APIv3#

The API was updated to drop a bunch of things no longer needed and simplify the calls. We currently do not describe OpenVPN, but this MAY need to be supported in order to have older servers that still use OpenVPN support APIv4 as well.

X-Proxy-Endpoint header is used to indicated WireGuard+TCP support
/info call display_name has been renamed to profile_name and is always an object now
/info call profile_description has been added and can be used to give extra information about a profile, is always an object
/info call no longer returns default_gateway (was only needed for OpenVPN+Linux)
/info call no longer returns vpn_proto_list (was only needed for OpenVPN+Linux)
/info call no longer returns dns_search_domain_list (was only needed for OpenVPN+Linux)
/info call vpn_proto_transport_list removed
/connect call now requires public_key
/connect call no longer supports prefer_tcp
/connect call now MUST be sent with Accept header indicating the supported VPN protocol
/connect responds with 400 code when profile does not exist