ref: fd46c663b61b90594214f4ab25b347635dd80a92 vpn-documentation/SERVER_DISCOVERY_SKIP_WAYF.md -rw-r--r-- 4.3 KiB
fd46c663François Kooman mention VPN Server software is licensed under AGPLv3+ 9 months ago

#title: Avoid Organization Selection description: Avoid Browser Organization Selection in Identity Federations category: dev

#Skipping the SAML WAYF

This builds on SERVER_DISCOVERY.


Most "Secure Internet" servers use SAML to authenticate users and have a WAYF (Where Are You From) in the browser to redirect users to the IdP of the organization chosen by the user for the actual authentication.

As we require the user to choose an organization in the eduVPN application already, therefor the user should NOT be required to have to choose again in the browser.

This document explains how the eduVPN application can be modified to not show the organization selection (WAYF) in the browser.

NOTE: this ONLY applies for "Secure Internet" and NOT for "Institute Access"!


As described in API the application uses OAuth to obtain authorization to act on behalf of the user towards the API to obtain configurations and certificates.

This document describes a way in which the OAuth authorization URL can be modified to include information about which organization the user chose in the application.

The typical OAuth authorization URL that is generated by the OAuth library that is used in the eduVPN looks like this:


This is what is the URL that is opened by the application in the browser.

#Including Organization Information

The application still needs to use this URL, but in a modified form. The application needs to know three things:

  1. The OAuth authorization URL, as mentioned above;
  2. The org_id of the entry the user chose from the organization_list.json, for example https://idp.surfnet.nl. All entries are required to have an org_id;
  3. The OPTIONAL authentication_url_template from the server_list.json.

In case the authentication_url_template exists, it MUST be used by the application. If it does NOT exist, the OAuth URL as show above MUST be used directly, just like before.

For example the https://nl.eduvpn.org/ server in server_list.json has the following authentication_url_template:


This template contains two values that MUST be substituted:

  • @RETURN_TO@ is replaced with the URL encoded OAuth authorization URL as determined before;
  • @ORG_ID@ is replaced with the URL encoded org_id.

The URL encoding of the OAuth authorization URL is done using application/x-www-form-urlencoded type, which differs from RFC 3986 encoding in that spaces are encoded as + and not %20. The encoded OAuth authorization URL as mentioned above looks like this:


The URL encoded org_id as used above looks like this:


Using the authentication_url_template and replacing the values results in this URL:


This then becomes the URL the application needs to open in the browser instead of the OAuth authorization URL.