OpenVPN + Keycloak : configuration OAuth2

Intégrer OpenVPN avec Keycloak via le plugin openvpn-auth-oauth2

Jadis, l'accès aux ressources dans un environnement protégé sur Yandex Cloud reposait sur une installation auto-hébergée d'OpenVPN utilisant l'authentification PAM. Avec la croissance du nombre d'utilisateurs, l'intégration à Keycloak est devenue indispensable. Le plugin openvpn-auth-oauth2 permet l'authentification OAuth2 via Keycloak et fonctionne sur les systèmes Debian et RedHat.

L'installation sous Ubuntu 24.04 LTS se fait directement depuis le dépôt du projet :

curl -L https://raw.githubusercontent.com/jkroepke/openvpn-auth-oauth2/refs/heads/main/packaging/apt/openvpn-auth-oauth2.sources | sudo tee /etc/apt/sources.list.d/openvpn-auth-oauth2.sources
sudo apt update
sudo apt install openvpn-auth-oauth2

Création d'un client dans Keycloak

Dans Keycloak, créez un nouveau client pour le plugin :

• Définissez l'ID client : openvpn-auth-oauth2.
• Activez l'authentification client : ON.
• Activez le flux standard : ON.
• Définissez le type d'accès : confidentiel.

Copiez le secret client — il sera nécessaire pour la configuration.

Configuration du plugin openvpn-auth-oauth2

Fichier de configuration principal : /etc/openvpn-auth-oauth2/config.yaml. Configuration minimale fonctionnelle :

http:
  baseurl: "https://vpn.votredomaine.com"
  listen: ":9000"
  secret: "votre_mot_de_passe_secret"
oauth2:
  issuer: "https://keycloak.votredomaine/realm/securerealm"
  client:
    id: "openvpn-auth-oauth2"
    secret: "votre_secret_keycloak"
openvpn:
  addr: "unix:///run/openvpn/server.sock"
  password: "votre_mot_de_passe_secret"

Paramètres :

• baseurl : domaine de l'endpoint OAuth2, proxyé via nginx sur le port 9000.
• listen : port d'écoute du service.
• secret : clé de chiffrement des cookies (16/24/32 caractères).
• issuer : URL Keycloak avec le realm.
• client.id/secret : identifiants du client provenant de Keycloak.
• openvpn.addr/password : socket et mot de passe pour OpenVPN.

Configuration du serveur OpenVPN

Créez le fichier /etc/openvpn/server/server-keycloak.conf :

port 56890
management /run/openvpn/server.sock unix /etc/openvpn/password.txt
management-client-auth
auth-user-pass-optionals
auth-gen-token 28800 external-auth
proto udp
dev tun
ca /etc/openvpn/certs/ca.crt
cert /etc/openvpn/certs/server.crt
key /etc/openvpn/certs/server.key
dh /etc/openvpn/certs/dh.pem
server 10.212.245.0 255.255.255.0
client-config-dir /etc/openvpn/ccd
ifconfig-pool-persist /etc/openvpn/ipp.txt
push "route 10.167.0.0 255.255.0.0"
push "route 10.168.0.0 255.255.0.0"
push "route 10.169.0.0 255.255.0.0"
keepalive 10 120
cipher AES-256-GCM
max-clients 100
persist-tun
status /var/log/openvpn/openvpn-keycloak-status.log
verb 3

Options clés pour l'intégration :

• management ... : socket Unix pour le contrôle externe.
• management-client-auth : autorise les commandes externes.
• auth-user-pass-optionals : ne nécessite pas de login/mot de passe client.
• auth-gen-token 28800 external-auth : jeton généré par le plugin, TTL de 8 heures.

Démarrage du service :

systemctl enable openvpn-server@server-keycloak --now

Proxification via nginx

Installez nginx et certbot pour HTTPS. Fichier de configuration /etc/nginx/conf.d/vpn.votredomaine.com.conf :

server {
    server_name vpn.votredomaine.com;
    listen 80;
    listen [::]:80;
    access_log /var/log/nginx/vpn.votredomaine.com-access.log;
    error_log /var/log/nginx/vpn.votredomaine.com-error.log;

    location ^~ /.well-known/acme-challenge/ {
        default_type "text/plain";
        root /var/www/certbot;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    server_name vpn.votredomaine.com;
    listen 443 ssl;
    error_log /var/log/nginx/vpn.votredomaine.com-error.log;

    ssl_certificate /etc/letsencrypt/live/vpn.votredomaine.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vpn.votredomaine.com/privkey.pem;

    location ^~ /.well-known/acme-challenge/ {
        default_type "text/plain";
        root /var/www/certbot;
    }

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://localhost:9000;
    }
}

Rechargez nginx : systemctl reload nginx.

Configuration du client et tests

Fichier .ovpn client :

client
dev tun
proto udp
remote vpn.votredomaine.com 56890
nobind
persist-key
persist-tun
verb 3
<ca>
-----BEGIN CERTIFICATE-----
Ici votre certificat CA
-----END CERTIFICATE-----
</ca>
cipher AES-256-GCM

Importez-le dans un client OpenVPN (ex. OpenVPN Access Server). À la connexion, le navigateur redirigera vers Keycloak pour l'authentification. En cas de succès :

• Le navigateur affiche une confirmation.
• La connexion VPN s'établit correctement.

Les clients uniquement en console ne prennent pas en charge ce flux navigateur — une personnalisation supplémentaire est requise.

Points clés

• Le plugin openvpn-auth-oauth2 remplace PAM par OAuth2 via Keycloak pour une authentification évolutif.
• Utilisez les sockets Unix pour une gestion sécurisée d'OpenVPN.
• TTL du jeton : 28800 secondes (8 heures), ajustable via auth-gen-token.
• Le proxy nginx est obligatoire pour HTTPS et l'intégration Let’s Encrypt.
• Idéal pour les ingénieurs DevOps intermédiaires à avancés axés sur la configuration et les intégrations.

— Editorial Team