Installer Pomerium avec Docker Compose

Ce guide vous permet de déployer Pomerium en 10 minutes avec Docker Compose et de protéger vos premières applications web derrière un accès authentifié. Vous repartirez avec un environnement fonctionnel, trois applications protégées et la compréhension du flux de bout en bout. Prérequis : Docker et Docker Compose installés.

Avant de commencer

Si vous ne connaissez pas encore Pomerium, lisez d’abord le guide Comprendre Pomerium qui explique l’architecture et les concepts. Ce lab met en pratique ces notions.

Objectif du lab

À la fin de ce guide, vous aurez :

• Un conteneur Pomerium en mode all-in-one (proxy + authenticate + authorize + databroker)
• Trois applications protégées :
  • Verify : service Pomerium qui affiche les informations de votre session
  • Grafana : dashboard d’observabilité
  • Whoami : service simple qui affiche les headers de la requête
• Un flux d’authentification fonctionnel via le service d’authentification hébergé de Pomerium

L’ensemble tourne en local sur votre machine. Aucun serveur distant n’est nécessaire.

Prérequis

Prérequis	Version minimale	Vérification
Docker	20+	docker --version
Docker Compose	v2+	docker compose version
Navigateur web	Récent	—
Compte email	Quelconque	Pour l’authentification

Glissez pour voir

DNS automatique

Pomerium fournit le domaine *.localhost.pomerium.io qui pointe automatiquement vers 127.0.0.1. Pas besoin de modifier votre fichier /etc/hosts ni de configurer un DNS local.

Architecture du lab

Le lab déploie 4 conteneurs sur un réseau Docker interne :

Seul le port 443 de Pomerium est exposé sur l’hôte. Les applications upstream ne sont accessibles que via Pomerium.

Préparer le projet

1. Créez le répertoire du lab

   mkdir -p ~/Projets/pomerium-lab && cd ~/Projets/pomerium-lab

2. Créez le fichier de configuration Pomerium

   Créez un fichier config.yaml à la racine du projet :

   config.yaml

   authenticate_service_url: https://authenticate.pomerium.app
   
   routes:
     - from: https://verify.localhost.pomerium.io
       to: http://verify:8000
       policy:
         - allow:
             or:
               - email:
                   is: votre-email@example.com
       pass_identity_headers: true
   
     - from: https://grafana.localhost.pomerium.io
       to: http://grafana:3000
       allow_any_authenticated_user: true
   
     - from: https://whoami.localhost.pomerium.io
       to: http://whoami:80
       allow_any_authenticated_user: true

   Remplacez votre-email@example.com par votre adresse email réelle. C’est l’email avec lequel vous vous authentifierez.

   Piège fréquent : erreur 403 après authentification

   L’email dans config.yaml doit correspondre exactement à celui de votre compte Google ou GitHub. Si vous vous authentifiez avec alice@gmail.com mais que le fichier contient user@example.com, Pomerium retournera une erreur 403 (Forbidden). Vérifiez bien l’email avant de continuer.

3. Créez le fichier Docker Compose

   docker-compose.yaml

   services:
     pomerium:
       image: pomerium/pomerium:v0.32.4
       volumes:
         - ./config.yaml:/pomerium/config.yaml:ro
       ports:
         - 443:443
   
     verify:
       image: pomerium/verify:latest
       expose:
         - "8000"
   
     grafana:
       image: grafana/grafana:latest
       expose:
         - "3000"
   
     whoami:
       image: traefik/whoami:latest
       expose:
         - "80"

Comprendre la configuration

Avant de démarrer, détaillons les éléments clés du fichier config.yaml :

Le service d’authentification hébergé

authenticate_service_url: https://authenticate.pomerium.app

Cette ligne indique que Pomerium utilise son service d’authentification hébergé. Pomerium fournit un IdP (fournisseur d’identité) intégré pour les tests et les démarrages rapides. Vous n’avez pas besoin de configurer Keycloak ou Authentik pour ce premier lab.

En production, vous remplacerez cette URL par votre propre IdP. C’est l’objet d’un guide ultérieur dans la série.

Les routes

Chaque route définit un point d’entrée (from) et une destination (to) :

Champ	Rôle	Exemple
from	URL publique que l’utilisateur tape dans son navigateur	https://grafana.localhost.pomerium.io
to	Adresse du service en amont, sur le réseau Docker	http://grafana:3000
policy	Règles d’accès (qui peut entrer)	Voir ci-dessous

Glissez pour voir

Les politiques d’accès

Le fichier utilise deux types de politiques :

Politique par email (route Verify) — seul l’utilisateur avec l’email spécifié peut accéder :

policy:
  - allow:
      or:
        - email:
            is: votre-email@example.com

Politique ouverte (routes Grafana et Whoami) — tout utilisateur authentifié peut accéder, quel que soit son email :

allow_any_authenticated_user: true

Les headers d’identité

pass_identity_headers: true

Cette option demande à Pomerium de transmettre les informations d’identité (email, nom, groupes) à l’application upstream via des headers HTTP. Le service Verify utilise ces headers pour afficher les détails de votre session.

Déployer l’environnement

1. Téléchargez les images Docker

   docker compose pull

   Résultat attendu :

   ✔ Image grafana/grafana:latest Pulled
   ✔ Image pomerium/pomerium:v0.32.4 Pulled
   ✔ Image traefik/whoami:latest Pulled

2. Démarrez les services

   docker compose up -d

   Résultat attendu :

   ✔ Network pomerium-lab_default      Created
   ✔ Container pomerium-lab-grafana-1  Created
   ✔ Container pomerium-lab-whoami-1   Created
   ✔ Container pomerium-lab-pomerium-1 Created
   ✔ Container pomerium-lab-verify-1   Created

3. Vérifiez que tous les conteneurs tournent

   docker compose ps

   Les 4 conteneurs doivent avoir le statut Up :

   NAME                      IMAGE                       STATUS         PORTS
   pomerium-lab-grafana-1    grafana/grafana:latest      Up             3000/tcp
   pomerium-lab-pomerium-1   pomerium/pomerium:v0.32.4   Up             0.0.0.0:443->443/tcp
   pomerium-lab-verify-1     pomerium/verify:latest      Up             8000/tcp
   pomerium-lab-whoami-1     traefik/whoami:latest       Up             80/tcp

4. Vérifiez les logs Pomerium

   docker compose logs pomerium | head -15

   Vous devez voir les messages suivants confirmant le bon démarrage :

   pomerium-1 | {"level":"info","message":"config: updated config"}
   pomerium-1 | {"level":"info","version":"0.32.4","message":"cmd/pomerium"}
   pomerium-1 | {"level":"info","message":"server started"}
   pomerium-1 | {"level":"info","message":"enabled authenticate service"}
   pomerium-1 | {"level":"info","message":"enabled authorize service"}
   pomerium-1 | {"level":"info","message":"enabled databroker service"}
   pomerium-1 | {"level":"info","message":"enabled proxy service"}

Avertissement COOKIE_SECRET

Au démarrage, vous verrez le message using a generated COOKIE_SECRET. C’est normal en lab. En production, il faut définir un COOKIE_SECRET fixe pour éviter de déconnecter tous les utilisateurs à chaque redémarrage. Nous couvrons ce point dans le guide d’architecture production.

Accéder au lab

En local

Si Docker tourne directement sur votre machine, ouvrez simplement les URLs dans votre navigateur :

• https://verify.localhost.pomerium.io
• https://grafana.localhost.pomerium.io
• https://whoami.localhost.pomerium.io

Le DNS *.localhost.pomerium.io est un DNS public qui pointe vers 127.0.0.1. Votre navigateur résout l’adresse automatiquement.

VS Code SSH Remote

Si vous travaillez en SSH Remote (Docker tourne sur un serveur distant) :

1. Ouvrez le panneau Ports dans VS Code (onglet à côté du Terminal)
2. Cliquez Forward a Port et entrez 443
3. VS Code crée un tunnel SSH : localhost:443 sur votre machine locale → port 443 du serveur distant

Le DNS *.localhost.pomerium.io pointe vers 127.0.0.1, donc votre navigateur local envoie la requête au tunnel SSH, qui la transmet à Pomerium sur le serveur. Le header Host est préservé — Pomerium reçoit bien verify.localhost.pomerium.io et sait quelle route servir.

Ouvrez ensuite les URLs dans votre navigateur local (pas le Simple Browser de VS Code) :

• https://verify.localhost.pomerium.io
• https://grafana.localhost.pomerium.io
• https://whoami.localhost.pomerium.io

Tester le flux d’authentification

1. Ouvrez le service Verify dans votre navigateur

   Rendez-vous sur : https://verify.localhost.pomerium.io

   Votre navigateur affichera un avertissement de certificat auto-signé. C’est normal en lab — Pomerium génère un certificat auto-signé quand aucun n’est fourni.

   Pour contourner l’avertissement :

   • Chrome / Edge : cliquez n’importe où dans la page et tapez thisisunsafe (sans espaces, sans champ de saisie visible) puis Entrée
   • Firefox : cliquez “Avancé” → “Accepter le risque et poursuivre”

2. Authentifiez-vous

   Pomerium vous redirige vers authenticate.pomerium.app. Cette page propose plusieurs fournisseurs d’identité : Google, GitHub, etc.

   Pas de mot de passe Pomerium

   Le service authenticate.pomerium.app est un IdP hébergé par Pomerium pour les tests. Il n’a pas de couple identifiant/mot de passe propre. Vous vous connectez avec votre compte Google ou GitHub existant. L’email associé à ce compte doit correspondre à celui configuré dans config.yaml.

   Choisissez un fournisseur (par exemple GitHub), autorisez l’accès, et Pomerium récupère votre email depuis le provider.

3. Vérifiez l’accès au service Verify

   Après authentification, le service Verify affiche les informations de votre session : email, groupes, claims JWT. Cela confirme que Pomerium transmet correctement les headers d’identité.

4. Testez la route Grafana

   Ouvrez https://grafana.localhost.pomerium.io. Si vous êtes déjà authentifié, Pomerium vous laisse passer directement (la session est partagée). Vous arrivez sur la page de login Grafana.

5. Testez la route Whoami

   Ouvrez https://whoami.localhost.pomerium.io. Le service Whoami affiche tous les headers HTTP de la requête. Repérez les headers ajoutés par Pomerium :

   • X-Pomerium-Jwt-Assertion : le JWT contenant votre identité
   • X-Pomerium-Claim-Email : votre adresse email
   • X-Pomerium-Claim-Groups : vos groupes (si disponibles)

Vérifier avec curl

Vous pouvez aussi vérifier le comportement depuis le terminal :

# Vérifie que Pomerium redirige vers l'authentification (302)
curl -ksI https://verify.localhost.pomerium.io | head -5

Résultat attendu :

HTTP/2 302
location: https://authenticate.pomerium.app/.pomerium/sign_in?...
x-pomerium-intercepted-response: true

Le code 302 confirme que Pomerium intercepte la requête et redirige vers le service d’authentification. Un accès non authentifié ne passe jamais directement à l’upstream.

Modifier la configuration

Pomerium recharge la configuration automatiquement quand le fichier config.yaml est modifié (hot reload). Pas besoin de redémarrer les conteneurs.

Ajouter une nouvelle application

Pour protéger une nouvelle application, ajoutez une route dans config.yaml. Par exemple, pour ajouter un service Portainer :

config.yaml

routes:
  - from: https://verify.localhost.pomerium.io
    to: http://verify:8000
    policy:
      - allow:
          or:
            - email:
                is: votre-email@example.com
    pass_identity_headers: true

  - from: https://grafana.localhost.pomerium.io
    to: http://grafana:3000
    allow_any_authenticated_user: true

  - from: https://portainer.localhost.pomerium.io
    to: http://portainer:9000
    allow_any_authenticated_user: true

Ajoutez le service correspondant dans docker-compose.yaml et relancez :

docker compose up -d

Pomerium détecte le changement et applique la nouvelle route sans redémarrage.

Restreindre l’accès par email

Pour limiter l’accès Grafana à un seul utilisateur, remplacez allow_any_authenticated_user par une politique explicite :

- from: https://grafana.localhost.pomerium.io
  to: http://grafana:3000
  policy:
    - allow:
        or:
          - email:
              is: alice@example.com

Dépannage

Symptôme	Cause probable	Solution
ERR_CONNECTION_REFUSED sur le port 443	Conteneur Pomerium non démarré	docker compose ps puis docker compose up -d
Certificat auto-signé bloquant	Navigateur refuse le certificat	Taper thisisunsafe dans la page (Chrome/Edge)
no healthy upstream dans les logs	Le conteneur upstream n’est pas prêt	docker compose ps — vérifier que tous les conteneurs sont Up
Boucle de redirection infinie	Email dans config.yaml différent de celui utilisé	Vérifier que l’email correspond exactement
config: updated config non affiché	Fichier config.yaml mal monté	Vérifier le volume dans docker-compose.yaml
Erreur 403 après authentification	Politique trop restrictive	Vérifier l’email dans la policy ou utiliser allow_any_authenticated_user
ERR_CONNECTION_REFUSED en SSH Remote	Port 443 non forwardé	Forwarder le port 443 dans l’onglet Ports de VS Code

Glissez pour voir

Diagnostiquer une erreur 403

L’erreur 403 est le problème le plus fréquent lors de la première utilisation. Elle signifie que vous êtes authentifié mais pas autorisé. Pomerium identifie votre email via le provider (Google, GitHub…) et le compare à la politique de la route.

Pour identifier le problème, consultez les logs :

docker compose logs pomerium | grep -i "email\|403\|unauthorized"

Cherchez la ligne authorize check qui contient votre email réel et la raison du refus :

{"email":"alice@gmail.com","allow":false,"allow-why-false":["email-unauthorized"]}

Si l’email dans les logs ne correspond pas à celui dans config.yaml, corrigez le fichier. Pomerium recharge la configuration automatiquement :

# Voir l'email actuel dans la config
grep "is:" config.yaml

# Corriger avec l'email réel
sed -i 's/ancien-email@example.com/votre-vrai-email@gmail.com/' config.yaml

Puis rafraîchissez la page dans le navigateur — le 403 disparaît sans redémarrage.

Pour voir les logs en temps réel :

docker compose logs -f pomerium

Nettoyage

Pour arrêter et supprimer l’environnement de lab :

# Arrêter les conteneurs
docker compose down

# Supprimer aussi les volumes (données Grafana, etc.)
docker compose down -v

À retenir

• Pomerium se déploie en une image Docker en mode all-in-one, avec un seul fichier de configuration
• Le domaine *.localhost.pomerium.io pointe vers 127.0.0.1 — pas besoin de DNS local
• Chaque route associe une URL publique (from) à un service interne (to) avec une politique d’accès
• Le service d’authentification hébergé (authenticate.pomerium.app) permet de démarrer sans configurer d’IdP
• Les headers X-Pomerium-* transmettent l’identité à l’application upstream
• La configuration se recharge à chaud — pas de redémarrage nécessaire
• En production, il faudra fixer le COOKIE_SECRET et configurer votre propre IdP

Prochaines étapes

Comprendre Pomerium Revenir aux concepts : architecture, composants, flux d'authentification.

Teleport Comparer avec une approche bastion pour l'accès SSH et multi-protocole.

×

📖 Voir la documentation →