OpenVPN: Part 3 — Login via Keycloak (SSO and two-factor authentication)

Certificates protect the tunnel well, but are a poor tool for managing human access. When there are dozens of employees, certificates have to be issued and revoked manually, and a dismissed person can continue to connect until their certificate is added to the revocation list. A certificate also has no second factor: the profile file can be copied to any device.

The solution is to delegate user verification to a single sign-on system. An employee connects to the VPN, the client opens a browser, the person signs in to the corporate account with a password and a one-time code, and only after that the tunnel is brought up. Disable the account in one place — VPN access is gone everywhere.

Keycloak — an open source identity server — is often used for such a system. There’s no built-in “Keycloak button” in OpenVPN. There are two practical ways, and they depend on the server edition.

Path 1. Access Server and SAML

OpenVPN Access Server, starting with version 2.11, supports login via SAML. Keycloak can act as a SAML Identity Provider (IdP), so the integration is assembled using features of both products without external code. There is a dedicated guide for Keycloak in the Access Server documentation.

Setup steps per the Access Server documentation:

1. Provide service data to Keycloak. Access Server has Service Provider (SP) metadata: an identifier and an Assertion Consumer Service (ACS) URL. In Keycloak create a SAML client: its Client ID equals the SP identifier, and the ACS URL is added to the list of allowed redirect URIs.
2. Provide Keycloak data to Access Server. Each Keycloak realm has a SAML metadata URL like https://sso.example.ru/realms/<realm>/protocol/saml/descriptor. It is specified in the SAML settings in the Access Server web interface.
3. Enable SAML for all users or for specific groups.
4. Grant access to users on the Keycloak side.
5. Verify login: the user selects a profile in OpenVPN Connect, the client opens the Keycloak login page in the browser, and after successful authentication the tunnel is brought up.

Important detail: when logging in via SAML the built-in two-factor authentication of Access Server (TOTP) does not work. The second factor must be configured on the Keycloak side.

The limitation for Russian companies is the same as described in the first part of the series: Access Server is sold by subscription and cannot be paid for with a Russian card. Without a subscription only two simultaneous connections are available.

Path 2. OpenVPN Community and openvpn-auth-oauth2

For the free OpenVPN Community edition there is an external project openvpn-auth-oauth2 licensed under MIT. It’s a separate service that connects to the OpenVPN management interface and guides the user through login via OpenID Connect. Keycloak is listed among the supported providers. The project works as a client of the management interface or as a plugin for Linux and FreeBSD.

How authentication works

1. The client connects to the OpenVPN server.
2. The server notifies openvpn-auth-oauth2 that the user is awaiting verification.
3. The service returns a login URL, the server passes it to the client, and the client opens a browser.
4. The user signs in to Keycloak; Keycloak redirects the browser back to the service with an authorization code, and the service exchanges the code for tokens.
5. The service allows or denies the connection, and the server brings up the tunnel or refuses it.

Requirements

Per the project’s documentation: OpenVPN server version 2.6.2 or newer (Access Server is not supported), client version 2.5.0 or newer with browser-based login support. Known to work are OpenVPN GUI from the Community 2.6+ package for Windows, Tunnelblick 4 for macOS, Viscosity, and on Linux — clients based on the OpenVPN 3 library (3.9 and newer). OpenVPN Connect is partially supported, and the NetworkManager module for GNOME does not work with this login. This must be considered before deployment: employees’ clients must be from the approved list.

OpenVPN configuration

Add the lines from the project’s documentation to the server configuration:

management /run/openvpn/server.sock unix /etc/openvpn/password.txt
management-client-auth
auth-user-pass-optional
auth-gen-token 28800 external-auth

• management … unix — management interface on a local socket with the password from a file;
• management-client-auth — the decision to admit a client is made by the external service;
• auth-user-pass-optional — the client is not required to enter a username and password in OpenVPN itself;
• auth-gen-token 28800 external-auth — after login the server issues a token to the client for 8 hours. Without it, the user would have to re-authenticate on each key rotation (by default once an hour).

Keycloak configuration

Create a client in the required Keycloak realm:

• type — OpenID Connect, enable client authentication (Client authentication);
• in the list of allowed redirect URIs — the service address, e.g. https://vpn-login.example.ru/oauth2/callback;
• on the Credentials tab — the client secret.

Configuring openvpn-auth-oauth2

Minimum YAML configuration file per the project’s documentation:

http:
  listen: ":9000"
  baseurl: "https://vpn-login.example.ru"
openvpn:
  addr: "unix:///run/openvpn/server.sock"
  password: "<password from /etc/openvpn/password.txt>"
oauth2:
  issuer: "https://sso.example.ru/realms/company"
  client:
    id: "openvpn"
    secret: "<client secret from Keycloak>"

baseurl — the address that will be opened in the user’s browser. It must be available over HTTPS: some clients, for example Viscosity, refuse to open a non-encrypted address by default. Usually the service is placed behind a reverse proxy with a certificate.

Two-factor authentication in Keycloak

In both paths the second factor is checked by Keycloak, not by OpenVPN. The simplest option is one-time codes from an authenticator app (TOTP):

1. In the realm settings check the One-Time Password policy (algorithm, code length, period).
2. For users enable the required action “Configure OTP”: on their next login Keycloak will ask them to scan a QR code in the authenticator app.
3. Verify that the realm’s Authentication flow requires OTP for the intended users.

This way VPN login receives the same second factor as other corporate services on Keycloak.

What to choose

Common mistakes

• No auth-gen-token. The user is sent to the login page every hour.
• Service address over HTTP. Some clients will not open the login page, and the password and code will be sent over the network in plaintext.
• Incompatible clients. Employees using NetworkManager or an old client will not be able to log in — the list of approved clients must be chosen in advance.
• Certificates removed entirely. External authorization verifies the person, while the certificate and tls-crypt still protect the tunnel itself. You should not abandon them.

You can order Keycloak and single sign-on setup for VPN and other company services on the “Keycloak / SSO setup” page: [/ru/services/keycloak-sso/].