Traefik SSL/TLS : Let's Encrypt, ACME et certificats automatiques

Ce guide vous accompagne dans la configuration de certificats TLS automatiques avec Traefik v3.6. Vous apprendrez à utiliser Let’s Encrypt via le protocole ACME pour obtenir des certificats gratuits, que ce soit par HTTP Challenge (le plus simple) ou DNS Challenge (pour les wildcards et réseaux privés). À la fin, vos services seront accessibles en HTTPS avec des certificats renouvelés automatiquement.

Temps estimé : 20-25 minutes selon votre configuration.

Quel challenge choisir ?

• HTTP Challenge : le plus simple, fonctionne si le port 80 est accessible depuis Internet
• DNS Challenge : nécessaire pour les certificats wildcard (*.exemple.com) ou si le port 80 est bloqué
• TLS Challenge : quand seul le port 443 est accessible (rare)

Prérequis

Domaine pointant vers Traefik

Vous devez avoir un nom de domaine dont les enregistrements DNS pointent vers l’IP de votre serveur Traefik :

# Vérifier que votre domaine pointe vers votre serveur
dig +short mon-domaine.com A
# Doit retourner l'IP de votre serveur

Domaine obligatoire

Let’s Encrypt ne délivre pas de certificats pour des adresses IP ou des domaines locaux (.local, .localhost). Vous avez besoin d’un vrai nom de domaine.

Ports réseau

Challenge	Port requis	Direction
HTTP-01	80	Entrant depuis Internet
TLS-ALPN-01	443	Entrant depuis Internet
DNS-01	Aucun	Sortant vers API DNS

Glissez pour voir

Vérifiez l’accessibilité depuis l’extérieur :

# Depuis un autre serveur ou https://www.whatsmyip.org/port-scanner/
nc -zv votre-ip-publique 80
nc -zv votre-ip-publique 443

Traefik installé

Ce guide suppose que Traefik est déjà installé. Si ce n’est pas le cas, consultez d’abord Installer Traefik v3.

Compte DNS provider (pour DNS Challenge)

Si vous utilisez le DNS Challenge, vous aurez besoin d’un accès API à votre provider DNS (Cloudflare, OVH, Route53, etc.).

Comment fonctionne ACME

Le protocole ACME

ACME (Automatic Certificate Management Environment) est le protocole utilisé par Let’s Encrypt pour automatiser la délivrance de certificats. Voici comment ça fonctionne :

1. Votre serveur demande un certificat pour un domaine (ex: api.exemple.com)
2. Let’s Encrypt vous lance un défi : “Prouvez que vous contrôlez ce domaine”
3. Vous relevez le défi (via HTTP, DNS ou TLS selon le type choisi)
4. Let’s Encrypt vérifie et délivre le certificat

Les certificats Let’s Encrypt sont gratuits et valides 90 jours. Traefik gère automatiquement le renouvellement (généralement 30 jours avant expiration).

Les trois types de challenges

Challenge	Comment ça marche	Quand l’utiliser
HTTP-01	Let’s Encrypt fait une requête HTTP sur /.well-known/acme-challenge/	Port 80 accessible, cas le plus courant
DNS-01	Vous créez un enregistrement TXT _acme-challenge.domaine	Wildcard, port 80 fermé, réseau privé
TLS-ALPN-01	Vérification via TLS sur le port 443	Port 80 fermé mais 443 ouvert

Glissez pour voir

Configuration de base Let’s Encrypt

Certificate Resolver

Un Certificate Resolver est la configuration qui indique à Traefik comment obtenir des certificats. Vous le définissez dans la configuration statique :

YAML

# traefik.yaml - Configuration statique
certificatesResolvers:
  letsencrypt:
    acme:
      email: "admin@votre-domaine.com"  # Email pour les notifications
      storage: /etc/traefik/acme.json   # Où stocker les certificats
      caServer: "https://acme-v02.api.letsencrypt.org/directory"
      httpChallenge:
        entryPoint: web                 # Entrypoint pour le challenge HTTP

TOML

traefik.toml

[certificatesResolvers.letsencrypt.acme]
  email = "admin@votre-domaine.com"
  storage = "/etc/traefik/acme.json"
  caServer = "https://acme-v02.api.letsencrypt.org/directory"
  [certificatesResolvers.letsencrypt.acme.httpChallenge]
    entryPoint = "web"

CLI

--certificatesresolvers.letsencrypt.acme.email=admin@votre-domaine.com \
--certificatesresolvers.letsencrypt.acme.storage=/etc/traefik/acme.json \
--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web

Stockage des certificats (acme.json)

Les certificats obtenus sont stockés dans un fichier JSON. Ce fichier doit avoir des permissions strictes car il contient vos clés privées :

# Créer le fichier avec les bonnes permissions
touch /etc/traefik/acme.json
chmod 600 /etc/traefik/acme.json

Permissions obligatoires

Traefik refuse de démarrer si acme.json a des permissions trop ouvertes. Le fichier doit être en 600 (lecture/écriture propriétaire uniquement).

Avec Docker, créez le fichier avant de lancer le conteneur :

mkdir -p ~/traefik/certs
touch ~/traefik/certs/acme.json
chmod 600 ~/traefik/certs/acme.json

Activer TLS sur un router

Une fois le resolver configuré, activez-le sur vos routers :

Docker labels

docker-compose.yml

services:
  mon-app:
    image: mon-image
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.mon-app.rule=Host(`app.exemple.com`)"
      - "traefik.http.routers.mon-app.entrypoints=websecure"
      - "traefik.http.routers.mon-app.tls=true"
      - "traefik.http.routers.mon-app.tls.certresolver=letsencrypt"

YAML dynamique

config/dynamic/routers.yaml

http:
  routers:
    mon-app:
      rule: "Host(`app.exemple.com`)"
      entryPoints:
        - websecure
      service: mon-app
      tls:
        certResolver: letsencrypt

HTTP Challenge

C’est la méthode la plus simple. Let’s Encrypt vérifie que vous contrôlez le domaine en faisant une requête HTTP sur le port 80.

Fonctionnement

     ┌──────────────────────────────────────────────────────────────┐
     │                       HTTP-01 Challenge                      │
     └──────────────────────────────────────────────────────────────┘

     1. Traefik demande un certificat pour app.exemple.com

     2. Let's Encrypt génère un token unique

     3. Let's Encrypt fait une requête :
        GET http://app.exemple.com/.well-known/acme-challenge/{token}

     4. Traefik répond avec la preuve de contrôle

     5. Let's Encrypt délivre le certificat

Configuration complète

1. Configurer les entrypoints

   Vous avez besoin de deux entrypoints : un pour HTTP (port 80) et un pour HTTPS (port 443) :

   traefik.yaml

   entryPoints:
     web:
       address: ":80"
     websecure:
       address: ":443"

2. Configurer le certificate resolver

   traefik.yaml

   certificatesResolvers:
     letsencrypt:
       acme:
         email: "admin@exemple.com"
         storage: /etc/traefik/acme.json
         httpChallenge:
           entryPoint: web

3. Activer TLS sur vos services

   # docker-compose.yml - Service avec HTTPS
   services:
     whoami:
       image: traefik/whoami
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.whoami.rule=Host(`whoami.exemple.com`)"
         - "traefik.http.routers.whoami.entrypoints=websecure"
         - "traefik.http.routers.whoami.tls.certresolver=letsencrypt"

4. Redirection HTTP vers HTTPS (optionnel mais recommandé)

   Ajoutez une redirection automatique dans les entrypoints :

   traefik.yaml

   entryPoints:
     web:
       address: ":80"
       http:
         redirections:
           entryPoint:
             to: websecure
             scheme: https
             permanent: true

5. Vérifier le certificat

   # Attendre quelques secondes que le certificat soit généré
   curl -v https://whoami.exemple.com 2>&1 | grep -A5 "Server certificate"
   
   # Ou avec openssl
   echo | openssl s_client -connect whoami.exemple.com:443 -servername whoami.exemple.com 2>/dev/null | openssl x509 -noout -issuer -subject -dates

   Résultat attendu :

   issuer=C = US, O = Let's Encrypt, CN = R3
   subject=CN = whoami.exemple.com
   notBefore=Feb 17 12:00:00 2026 GMT
   notAfter=May 18 12:00:00 2026 GMT

DNS Challenge

Le DNS Challenge est nécessaire pour les certificats wildcard (ex: *.exemple.com) ou quand le port 80 n’est pas accessible depuis Internet.

Pourquoi utiliser DNS Challenge

Situation	HTTP Challenge	DNS Challenge
Port 80 ouvert	✅	✅
Port 80 fermé (entreprise)	❌	✅
Certificat wildcard	❌	✅
Réseau privé (homelab)	❌	✅
Multi-domaines sur un certificat	✅	✅

Glissez pour voir

Providers DNS supportés

Traefik supporte plus de 100 providers DNS. Voici les plus courants :

Provider	Provider name	Variables d’environnement
Cloudflare	cloudflare	CF_API_EMAIL, CF_DNS_API_TOKEN
OVH	ovh	OVH_ENDPOINT, OVH_APPLICATION_KEY, OVH_APPLICATION_SECRET, OVH_CONSUMER_KEY
AWS Route53	route53	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
Google Cloud DNS	gcloud	GCE_PROJECT, credentials file
Azure DNS	azure	AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP
Hetzner	hetzner	HETZNER_API_KEY
DigitalOcean	digitalocean	DO_AUTH_TOKEN

Glissez pour voir

La liste complète est disponible sur lego DNS providers.

Configuration DNS Challenge (Cloudflare)

1. Créer un token API Cloudflare

   Dans Cloudflare Dashboard → My Profile → API Tokens → Create Token :

   • Template : Edit zone DNS
   • Zone Resources : Include → Specific zone → votre domaine
   • Copiez le token généré

2. Configurer le resolver avec DNS Challenge

   traefik.yaml

   certificatesResolvers:
     letsencrypt-dns:
       acme:
         email: "admin@exemple.com"
         storage: /etc/traefik/acme.json
         dnsChallenge:
           provider: cloudflare
           propagation:
             delayBeforeChecks: 10s
           resolvers:
             - "1.1.1.1:53"
             - "8.8.8.8:53"

3. Passer les variables d’environnement

   docker-compose.yml

   services:
     traefik:
       image: traefik:v3.6.7
       environment:
         - CF_API_EMAIL=votre-email@exemple.com
         - CF_DNS_API_TOKEN=votre-token-cloudflare
       # ...

4. Configurer un certificat wildcard

   services:
     traefik:
       labels:
         - "traefik.http.routers.wildcard.tls.certresolver=letsencrypt-dns"
         - "traefik.http.routers.wildcard.tls.domains[0].main=exemple.com"
         - "traefik.http.routers.wildcard.tls.domains[0].sans=*.exemple.com"

Configuration DNS Challenge (OVH)

1. Créer les clés API OVH

   Rendez-vous sur https://eu.api.ovh.com/createToken/ et créez un token avec les droits :

   • GET /domain/zone/*
   • POST /domain/zone/*
   • DELETE /domain/zone/*

2. Configurer Traefik

   traefik.yaml

   certificatesResolvers:
     letsencrypt-dns:
       acme:
         email: "admin@exemple.com"
         storage: /etc/traefik/acme.json
         dnsChallenge:
           provider: ovh
           propagation:
             delayBeforeChecks: 30s  # OVH peut être lent

3. Variables d’environnement

   docker-compose.yml

   environment:
     - OVH_ENDPOINT=ovh-eu
     - OVH_APPLICATION_KEY=xxx
     - OVH_APPLICATION_SECRET=xxx
     - OVH_CONSUMER_KEY=xxx

Environnement staging Let’s Encrypt

Éviter les rate limits

Let’s Encrypt impose des limites strictes en production :

Limite	Valeur
Certificats par domaine	50 / semaine
Échecs de validation	5 / heure / compte
Nouveaux enregistrements	10 / 3 heures / IP

Glissez pour voir

Attention aux rate limits

Si vous dépassez ces limites, vous serez bloqué pendant une semaine. Utilisez toujours l’environnement staging pour vos tests.

Configuration staging

Ajoutez le serveur staging dans votre configuration :

traefik.yaml

certificatesResolvers:
  letsencrypt-staging:
    acme:
      email: "admin@exemple.com"
      storage: /etc/traefik/acme-staging.json  # Fichier séparé !
      caServer: "https://acme-staging-v02.api.letsencrypt.org/directory"
      httpChallenge:
        entryPoint: web

Utilisez ce resolver pour vos tests :

- "traefik.http.routers.test.tls.certresolver=letsencrypt-staging"

Certificats staging

Les certificats staging sont signés par “Fake LE Intermediate X1” et ne sont pas reconnus par les navigateurs. C’est normal, ils servent uniquement à tester votre configuration.

Passer en production

Une fois que le staging fonctionne :

1. Changez le resolver vers letsencrypt (production)
2. Supprimez le fichier acme-staging.json
3. Redémarrez Traefik

rm /etc/traefik/acme-staging.json
docker compose restart traefik

Options TLS avancées

TLS Options

Définissez des profils TLS réutilisables pour contrôler les versions et cipher suites :

config/dynamic/tls.yaml

tls:
  options:
    # Profil moderne (TLS 1.3 uniquement)
    modern:
      minVersion: VersionTLS13
      sniStrict: true

    # Profil intermédiaire (compatibilité TLS 1.2)
    intermediate:
      minVersion: VersionTLS12
      cipherSuites:
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305

Appliquez un profil à un router :

# Docker labels
- "traefik.http.routers.secure-app.tls.options=modern@file"

SNI strict

Le SNI (Server Name Indication) permet d’héberger plusieurs certificats sur une même IP. Avec sniStrict: true, Traefik rejette les connexions qui ne fournissent pas de SNI valide :

tls:
  options:
    strict:
      minVersion: VersionTLS12
      sniStrict: true  # Rejette les connexions sans SNI

Headers de sécurité HSTS

Activez HSTS (HTTP Strict Transport Security) via un middleware :

config/dynamic/middlewares.yaml

http:
  middlewares:
    hsts:
      headers:
        stsSeconds: 31536000        # 1 an
        stsIncludeSubdomains: true
        stsPreload: true
        forceSTSHeader: true

Appliquez-le à vos routers :

- "traefik.http.routers.app.middlewares=hsts@file"

Renouvellement des certificats

Automatique par Traefik

Traefik renouvelle automatiquement les certificats 30 jours avant leur expiration. Vous n’avez rien à faire.

Le processus se déclenche au démarrage de Traefik et vérifie tous les certificats stockés dans acme.json.

Monitoring des expirations

Surveillez les certificats avec les métriques Prometheus :

traefik.yaml

metrics:
  prometheus:
    entryPoint: metrics
    addServicesLabels: true

Métrique disponible : traefik_tls_certs_not_after_timestamp

Exemple d’alerte Alertmanager :

- alert: CertificateExpiringSoon
  expr: (traefik_tls_certs_not_after_timestamp - time()) / 86400 < 14
  for: 1h
  labels:
    severity: warning
  annotations:
    summary: "Certificat expire dans moins de 14 jours"

Forcer le renouvellement

Si vous devez forcer un renouvellement :

# Sauvegarder puis supprimer le certificat
cp /etc/traefik/acme.json /etc/traefik/acme.json.bak

# Supprimer uniquement le certificat concerné (avec jq)
jq 'del(.letsencrypt.Certificates[] | select(.domain.main == "exemple.com"))' \
   /etc/traefik/acme.json > /tmp/acme.json && mv /tmp/acme.json /etc/traefik/acme.json

# Redémarrer Traefik
docker compose restart traefik

Lab : configuration complète

Un lab complet est disponible pour tester toutes ces configurations :

cd ~/Projets/lab-traefik-tls-acme

Structure du lab

lab-traefik-tls-acme/
├── docker-compose.yml       # Stack Docker
├── config/
│   ├── traefik.yaml         # Configuration statique
│   └── dynamic/
│       ├── tls.yaml         # Options TLS
│       └── middlewares.yaml # Middlewares HTTPS
└── certs/
    └── acme.json            # Stockage certificats (chmod 600)

Démarrage rapide

# Créer le fichier de certificats
touch certs/acme.json && chmod 600 certs/acme.json

# Démarrer avec certificats auto-signés (pour tests locaux)
docker compose up -d

# Vérifier les logs
docker compose logs -f traefik

# Tester
curl -k https://localhost:8443 -H "Host: whoami.localhost"

Dépannage

Certificat non généré

Symptôme : pas de certificat, erreur 526 ou certificat auto-signé affiché.

Vérifications :

# 1. Vérifier les logs Traefik
docker compose logs traefik | grep -i acme

# 2. Vérifier que le port 80 est accessible
curl http://votre-domaine.com

# 3. Vérifier le DNS
dig +short votre-domaine.com A

# 4. Vérifier le fichier acme.json
cat /etc/traefik/acme.json | jq '.letsencrypt'

Solutions courantes :

Erreur	Cause	Solution
”acme: error validating”	Port 80 bloqué	Ouvrir le firewall ou utiliser DNS Challenge
”too many certificates”	Rate limit atteint	Attendre 1 semaine ou utiliser staging
”DNS problem”	DNS mal configuré	Vérifier les enregistrements A/AAAA

Glissez pour voir

Erreur “too many certificates”

Vous avez atteint la limite Let’s Encrypt. Options :

1. Attendre : la limite se réinitialise après 7 jours
2. Utiliser staging : pas de limite pour les tests
3. Utiliser un wildcard : un seul certificat pour tous les sous-domaines

DNS propagation timeout

Avec le DNS Challenge, Let’s Encrypt peut ne pas voir l’enregistrement TXT à temps.

# Augmenter le délai
certificatesResolvers:
  letsencrypt-dns:
    acme:
      dnsChallenge:
        provider: ovh
        propagation:
          delayBeforeChecks: 60s  # Augmenter à 60s voire plus

Vous pouvez aussi spécifier des resolvers DNS rapides :

        resolvers:
          - "1.1.1.1:53"   # Cloudflare
          - "8.8.8.8:53"   # Google

Certificat staging en production

Si votre certificat est signé par “Fake LE” en production :

1. Vérifiez que vous utilisez le bon resolver (pas -staging)
2. Supprimez acme.json et redémarrez pour forcer un nouveau certificat
3. Vérifiez les logs pour les erreurs ACME

À retenir

• Let’s Encrypt fournit des certificats TLS gratuits et automatiques via le protocole ACME
• HTTP Challenge est le plus simple (port 80 requis), DNS Challenge permet les wildcards
• Toujours tester avec staging avant de passer en production pour éviter les rate limits
• Le fichier acme.json doit avoir les permissions 600 (lecture/écriture propriétaire uniquement)
• Traefik renouvelle automatiquement les certificats 30 jours avant expiration
• Utilisez les TLS Options pour définir des profils de sécurité réutilisables

Prochaines étapes

Middlewares de sécurité BasicAuth, ForwardAuth, headers sécurisés et rate limiting

Traefik avec Docker Configuration complète avec labels Docker

×

📖 Voir la documentation →