Apache Guacamole (accès RDP)

Ce guide explique comment ouvrir des sessions Bureau à distance (RDP) depuis le navigateur avec Apache Guacamole, en utilisant VaultysHub pour l'authentification. L'utilisateur s'authentifie avec son VaultysID, choisit un serveur et obtient le bureau Windows dans un onglet : il ne voit ni ne saisit jamais le mot de passe du compte Windows.

Fonctionnement

Navigateur ──HTTPS──▶ oauth2-proxy ──▶ Guacamole (web) ──▶ guacd ──RDP──▶ Serveur Windows
     │                     │
     └── VaultysID ◀── VaultysHub (OpenID Connect)

• guacd ouvre la vraie session RDP vers le serveur Windows et la transmet au navigateur. Rien n'est installé sur le poste de l'utilisateur.
• Guacamole (application web) stocke les connexions : hôte, port, domaine, compte et mot de passe. Ces identifiants restent côté serveur et ne sont jamais envoyés au navigateur.
• VaultysHub authentifie l'utilisateur. Guacamole reçoit son adresse e-mail et lui donne accès aux connexions qui lui sont attribuées.
• oauth2-proxy est recommandé en frontal (voir ci-dessous). Il gère la connexion OpenID Connect avec VaultysHub et transmet l'e-mail de l'utilisateur à Guacamole.

Pourquoi oauth2-proxy ?

Le module OpenID natif de Guacamole ne gère que le flux implicit. VaultysHub ne l'autorise que si l'URL de redirection est en https:// et n'est pas localhost. oauth2-proxy utilise le flux authorization code avec PKCE : il fonctionne dans tous les cas, et c'est le flux recommandé.

Méthode	Flux OIDC	Guacamole en HTTP	Recommandée
oauth2-proxy + authentification par en-tête	Authorization code + PKCE	Oui (tests uniquement)	✅
Module OpenID natif de Guacamole	Implicit	Non, HTTPS obligatoire	Si vous ne pouvez pas ajouter oauth2-proxy

Prérequis

• Docker et Docker Compose sur une machine qui peut joindre les serveurs Windows sur le port TCP 3389.
• Un nom DNS et un certificat HTTPS pour Guacamole en production (par exemple rdp.example.com derrière votre reverse proxy).
• Un compte Windows par serveur ou par environnement, que Guacamole utilisera pour ouvrir la session.
• Un accès administrateur à VaultysHub.

Configuration dans VaultysHub

1. Créer l'application

1. Connectez-vous à VaultysHub en tant qu'administrateur.
2. Allez dans Applications → Ajouter et créez l'application :
   • Nom : Bureau à distance
   • URL : https://rdp.example.com/guacamole/
3. Dans la configuration de l'application, choisissez le type OIDC.

2. Paramétrer OpenID Connect

• URI de redirection : https://rdp.example.com/oauth2/callback
• Étendue autorisée : openid, email et profile
• Identifiant du sujet (sub) : Adresse e-mail
• Utiliser HTTP : désactivé. Cette option sert uniquement à exposer les points d'accès de VaultysHub lui-même en http://.
• Exiger le PKCE : peut être activé, oauth2-proxy envoie un PKCE S256.

Relevez ensuite le Client ID (identifiant de l'application, noté [appid] ci-dessous) et le Secret client.

Vérifiez l'émetteur (issuer) annoncé par VaultysHub. C'est cette valeur exacte qu'il faudra donner à oauth2-proxy :

curl -s https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration | grep -o '"issuer":"[^"]*"'

3. Donner l'accès aux utilisateurs

Attribuez l'application aux utilisateurs ou aux groupes concernés. Un utilisateur qui n'y a pas accès est refusé par VaultysHub avant d'arriver dans Guacamole.

Déploiement de Guacamole

1. Initialiser la base de données

mkdir -p guacamole/initdb guacamole/recordings && cd guacamole
docker run --rm guacamole/guacamole:1.6.0 /opt/guacamole/bin/initdb.sh --postgresql > initdb/initdb.sql

2. Fichier .env

OIDC_CLIENT_ID=[appid]
OIDC_CLIENT_SECRET=votre-secret-client
# Valeur exacte du champ "issuer" relevée à l'étape précédente
OIDC_ISSUER=https://votre-smartlink.link.vaultys.org/api/oidc/[appid]
# 32 caractères aléatoires : openssl rand -hex 16
COOKIE_SECRET=remplacez-moi
POSTGRES_PASSWORD=remplacez-moi

3. Fichier docker-compose.yml

services:
  guacd:
    image: guacamole/guacd:1.6.0
    restart: unless-stopped
    volumes:
      - ./recordings:/var/lib/guacamole/recordings

  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: guacamole_db
      POSTGRES_USER: guacamole
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./initdb:/docker-entrypoint-initdb.d:ro
      - ./pgdata:/var/lib/postgresql/data

  guacamole:
    image: guacamole/guacamole:1.6.0
    restart: unless-stopped
    depends_on: [guacd, postgres]
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRESQL_HOSTNAME: postgres
      POSTGRESQL_DATABASE: guacamole_db
      POSTGRESQL_USERNAME: guacamole
      POSTGRESQL_PASSWORD: ${POSTGRES_PASSWORD}
      # Crée l'utilisateur Guacamole à sa première connexion via VaultysHub
      POSTGRESQL_AUTO_CREATE_ACCOUNTS: "true"
      # Utilisateur transmis par oauth2-proxy
      HTTP_AUTH_HEADER: X-Forwarded-Email
      RECORDING_SEARCH_PATH: /var/lib/guacamole/recordings
    volumes:
      - ./recordings:/var/lib/guacamole/recordings:ro
    # Pas de "ports" : Guacamole ne doit être joignable que par oauth2-proxy

  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.12.0
    restart: unless-stopped
    depends_on: [guacamole]
    environment:
      OAUTH2_PROXY_PROVIDER: oidc
      OAUTH2_PROXY_OIDC_ISSUER_URL: ${OIDC_ISSUER}
      OAUTH2_PROXY_CLIENT_ID: ${OIDC_CLIENT_ID}
      OAUTH2_PROXY_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
      OAUTH2_PROXY_REDIRECT_URL: https://rdp.example.com/oauth2/callback
      OAUTH2_PROXY_SCOPE: openid email profile
      OAUTH2_PROXY_CODE_CHALLENGE_METHOD: S256
      OAUTH2_PROXY_EMAIL_DOMAINS: "*"
      OAUTH2_PROXY_UPSTREAMS: http://guacamole:8080/
      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
      OAUTH2_PROXY_PASS_USER_HEADERS: "true"
      OAUTH2_PROXY_SKIP_PROVIDER_BUTTON: "true"
      OAUTH2_PROXY_COOKIE_SECRET: ${COOKIE_SECRET}
      OAUTH2_PROXY_COOKIE_SECURE: "true"
    ports:
      - "127.0.0.1:4180:4180"

Publiez ensuite 127.0.0.1:4180 derrière votre reverse proxy HTTPS sous https://rdp.example.com, puis démarrez :

docker compose up -d

Authentification par en-tête

Guacamole fait confiance à l'en-tête X-Forwarded-Email. Il ne doit donc être joignable que par oauth2-proxy. N'exposez jamais son port 8080 directement : n'importe qui pourrait alors envoyer cet en-tête et se faire passer pour un autre utilisateur.

4. Premier administrateur

La base est livrée avec un compte local guacadmin / guacadmin. Avec la configuration ci-dessus, la page de connexion n'est plus accessible, donc :

1. Connectez-vous une première fois via VaultysHub sur https://rdp.example.com/guacamole/ : votre compte est créé, sans droits.
2. Donnez-lui les droits d'administration depuis la base :

docker compose exec -T postgres psql -U guacamole -d guacamole_db -c "
INSERT INTO guacamole_system_permission (entity_id, permission)
SELECT entity_id, p::guacamole_system_permission_type
FROM guacamole_entity, unnest(ARRAY['ADMINISTER','CREATE_CONNECTION','CREATE_CONNECTION_GROUP','CREATE_USER','CREATE_USER_GROUP']) p
WHERE name = 'votre.email@example.com' AND type = 'USER'
ON CONFLICT DO NOTHING;"

3. Rechargez la page. Le menu Paramètres apparaît. Supprimez ensuite le compte guacadmin (Paramètres → Utilisateurs).

Configurer une connexion RDP

Dans Paramètres → Connexions → Nouvelle Connexion :

Champ	Valeur
Protocole	RDP
Nom d'hôte / Port	srv01.corp.local / 3389
Identifiant / Mot de passe	Le compte Windows utilisé pour cette connexion
Nom de domaine	Le domaine AD, par exemple CORP
Mode de Sécurité	NLA (Network Level Authentication)
Ignorer le certificat du serveur	Uniquement si le serveur utilise un certificat auto-signé

Organisez les serveurs par environnement ou par domaine avec des groupes de connexions (Nouveau Groupe). Ensuite, dans Paramètres → Utilisateurs (ou Groupes), cochez les connexions auxquelles chaque personne a droit.

Groupes VaultysHub

VaultysHub ne transmet pas les groupes à l'application OIDC. Les droits se gèrent donc dans Guacamole, par utilisateur ou via des groupes Guacamole. VaultysHub décide qui peut entrer, Guacamole décide quels serveurs chacun peut ouvrir.

Enregistrement des sessions

Dans la section Enregistrement écran de la connexion, renseignez :

• Chemin de l'enregistrement : ${HISTORY_PATH}/${HISTORY_UUID}
• Créer automatiquement un chemin d'enregistrement : coché

Les enregistrements sont stockés dans ./recordings et se rejouent depuis Paramètres → Historique.

Test de la configuration

1. Ouvrez https://rdp.example.com/guacamole/.
2. Vous êtes redirigé vers VaultysHub : validez avec votre VaultysID.
3. Vous arrivez dans Guacamole avec la liste de vos connexions.
4. Ouvrez une connexion : le bureau Windows s'affiche sans saisie de mot de passe.
5. Ouvrez l'application depuis le tableau de bord VaultysHub : l'ouverture apparaît dans le journal d'audit. Une connexion directe à l'URL de Guacamole passe aussi par VaultysHub, mais n'y est pas journalisée comme une ouverture d'application.

Variante : module OpenID natif de Guacamole

Si vous ne pouvez pas ajouter oauth2-proxy, Guacamole peut utiliser VaultysHub directement. Il faut alors servir Guacamole en HTTPS, sur un nom autre que localhost.

Dans VaultysHub, déclarez l'URI de redirection https://rdp.example.com/guacamole/. Ensuite, dans le service guacamole, remplacez HTTP_AUTH_HEADER par :

      OPENID_AUTHORIZATION_ENDPOINT: https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/auth
      OPENID_JWKS_ENDPOINT: https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/jwks
      OPENID_ISSUER: https://votre-smartlink.link.vaultys.org/api/oidc/[appid]
      OPENID_CLIENT_ID: "[appid]"
      OPENID_REDIRECT_URI: https://rdp.example.com/guacamole/
      OPENID_USERNAME_CLAIM_TYPE: email
      OPENID_SCOPE: openid email profile

Supprimez alors le service oauth2-proxy et publiez directement le port 8080 de Guacamole derrière votre reverse proxy HTTPS. Le premier administrateur se crée de la même façon qu'au paragraphe Premier administrateur.

Dépannage

oauth2-proxy redémarre en boucle : « issuer did not match »

La valeur OIDC_ISSUER doit être exactement celle du champ issuer de la configuration OpenID de VaultysHub (voir la commande curl plus haut), y compris http ou https. Si l'option Utiliser HTTP est activée sur l'application, l'issuer commence par http://. Désactivez-la, sauf si VaultysHub lui-même est servi en HTTP.

« Invalid redirect URI »

L'URI déclarée dans VaultysHub doit être identique à celle envoyée : https://rdp.example.com/oauth2/callback avec oauth2-proxy, https://rdp.example.com/guacamole/ avec le module natif (barre oblique finale comprise).

L'utilisateur arrive dans Guacamole sans aucune connexion

C'est normal à la première connexion : son compte Guacamole vient d'être créé. Attribuez-lui des connexions dans Paramètres → Utilisateurs.

La session RDP se ferme immédiatement

• Vérifiez que guacd joint le serveur : docker compose exec guacd nc -zv srv01.corp.local 3389.
• Essayez le mode de sécurité Négotiation automatique et cochez Ignorer le certificat du serveur pour isoler un problème de certificat.
• Consultez les journaux : docker compose logs guacd.

Sécurité

• HTTPS obligatoire en production. Gardez OAUTH2_PROXY_COOKIE_SECURE: "true".
• Guacamole jamais exposé directement quand l'authentification par en-tête est active.
• Un compte Windows dédié et limité par environnement. Évitez un compte d'administration du domaine utilisable partout.
• Enregistrement des sessions activé pour les comptes à privilèges.
• Mises à jour régulières de guacd et Guacamole, qui embarquent FreeRDP.

Ressources

• Documentation Apache Guacamole
• Guacamole avec Docker
• Documentation oauth2-proxy