HTTPS automatique avec Caddy : fonctionnement du TLS auto et dépannage

En bref : Caddy active automatiquement HTTPS pour toute adresse de site qui est un nom de domaine public. Il demande un certificat via ACME (Let's Encrypt ou ZeroSSL par défaut), prouve le contrôle du domaine par le challenge HTTP-01 ou TLS-ALPN-01 sur les ports 80 et 443, redirige HTTP vers HTTPS et renouvelle le certificat avant son expiration, sans aucune configuration supplémentaire.

Un reverse proxy Caddy, c'est simplement Caddy qui termine cette connexion HTTPS et transmet la requête à une application sur un autre port, conteneur ou hôte grâce à la directive `reverse_proxy`. Cette combinaison — TLS plus proxy en quelques lignes — est la principale raison pour laquelle on le choisit.

Un reverse proxy avec SSL en trois lignes

Avec un DNS pointant vers le serveur et les ports 80 et 443 joignables, ce Caddyfile constitue un reverse proxy HTTPS complet pour deux noms d'hôte. Caddy obtient les certificats des deux noms au démarrage, sert HTTP/1.1, HTTP/2 et HTTP/3, et transmet `X-Forwarded-For`, `X-Forwarded-Proto` et `X-Forwarded-Host` au backend. L'option `email` est facultative mais permet à l'autorité de certification de vous contacter au sujet de certificats expirant ou révoqués.

L'installation depuis le dépôt apt officiel et les bases de systemd sont couvertes dans le guide reverse proxy Caddy ; pour les conteneurs, voir Caddy comme reverse proxy Docker. Appliquez les modifications avec `sudo systemctl reload caddy`.

# /etc/caddy/Caddyfile
{
	email [email protected]
}

example.com, www.example.com {
	reverse_proxy 127.0.0.1:8080
}

Comment fonctionne le TLS automatique de Caddy en coulisses

Quand Caddy charge une configuration, il collecte chaque nom d'hôte des adresses de site et décide qui doit émettre chaque certificat. Les domaines publics vont aux émetteurs ACME publics ; `localhost`, les adresses IP et les noms purement internes reçoivent des certificats de l'autorité locale de Caddy (équivalent à écrire `tls internal`). Certificats, clés et compte ACME sont stockés dans le répertoire de données de Caddy : `/var/lib/caddy/.local/share/caddy` pour le paquet apt, `/data` dans l'image Docker officielle.

Le renouvellement se fait en arrière-plan bien avant l'expiration, et Caddy agrafe les réponses OCSP lorsque l'autorité le permet. Si l'émission échoue, Caddy réessaie avec un backoff exponentiel et utilise l'endpoint de staging de l'autorité pour les nouvelles tentatives afin de ne pas épuiser les limites de production. Plusieurs instances Caddy partageant le même stockage se coordonnent pour qu'une seule demande un certificat donné.

Certificats wildcard avec DNS-01

Les certificats wildcard comme `*.example.com` ne peuvent être émis que via le challenge DNS-01. Le binaire Caddy standard n'inclut pas de plugins de fournisseurs DNS : vous en compilez un avec xcaddy (ou choisissez le fournisseur sur la page de téléchargement officielle) et donnez à Caddy un jeton d'API limité à la modification du DNS de cette zone. DNS-01 fonctionne aussi lorsque les ports 80 et 443 ne sont pas joignables depuis Internet, par exemple sur un serveur purement interne.

Gardez le jeton hors du Caddyfile : placez-le dans un fichier d'environnement utilisé par l'unité systemd (`sudo systemctl edit caddy`, puis `EnvironmentFile=/etc/caddy/caddy.env` sous `[Service]`) et restreignez le fichier avec `chmod 600`.

# Build Caddy with a DNS provider module (example: Cloudflare)
xcaddy build --with github.com/caddy-dns/cloudflare

# Caddyfile: one wildcard certificate for all subdomains
*.example.com {
	tls {
		dns cloudflare {env.CF_API_TOKEN}
	}

	@app host app.example.com
	handle @app {
		reverse_proxy 127.0.0.1:3000
	}

	handle {
		respond "Unknown host" 404
	}
}

TLS à la demande et staging

Le TLS à la demande permet à Caddy d'obtenir un certificat lors de la première poignée de main TLS pour un nom d'hôte qu'il n'a jamais vu. Il est conçu pour les plateformes où les clients pointent leurs propres domaines vers votre serveur. Configurez toujours l'endpoint `ask` : Caddy l'appelle avec `?domain=name` et ne poursuit que sur une réponse 200. Sans lui, n'importe qui pourrait pointer des noms aléatoires vers votre IP et vous faire atteindre les limites de débit.

Pendant vos essais, basculez vers l'autorité de staging de Let's Encrypt avec l'option globale `acme_ca`. Les certificats de staging ne sont pas reconnus par les navigateurs, mais les limites sont bien plus élevées : vous pouvez casser et réparer librement. Une fois terminé, retirez l'option et, si vous le souhaitez, supprimez les certificats de staging du répertoire de données.

{
	on_demand_tls {
		ask http://127.0.0.1:5555/allowed
	}
}

https:// {
	tls {
		on_demand
	}
	reverse_proxy 127.0.0.1:8080
}

# Global options block for testing
{
	email [email protected]
	# Test against Let's Encrypt staging; remove when everything works
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

Pannes TLS courantes de Caddy et comment les corriger

1. 01.DNS mal pointé : l'enregistrement A ou AAAA est absent, pointe encore vers un ancien serveur ou est en cache. Un AAAA obsolète est un piège classique, car l'autorité privilégie IPv6 quand il existe. Vérifiez les deux avec `dig`.
2. 02.Port 80 ou 443 fermé : le pare-feu de l'hôte, un pare-feu cloud ou un routeur bloque le trafic entrant, si bien que ni HTTP-01 ni TLS-ALPN-01 ne peuvent aboutir. Ouvrez 80/tcp et 443/tcp (et 443/udp pour HTTP/3).
3. 03.Port déjà utilisé : Apache, nginx ou un autre conteneur écoute sur 80 ou 443, et Caddy ne peut pas s'y lier. Arrêtez l'autre service ou placez-le derrière Caddy.
4. 04.Proxy CDN en frontal : un proxy façon « nuage orange » termine le TLS avant Caddy, ce qui peut casser TLS-ALPN-01. Utilisez DNS-01, ou passez l'enregistrement en DNS seul pendant l'émission.
5. 05.Limites de débit : des tentatives échouées répétées ou l'effacement du répertoire de données vous font atteindre les limites de l'autorité (Let's Encrypt limite les validations échouées par nom d'hôte et par heure, et les certificats en double par semaine). Corrigez la cause, utilisez le staging et gardez le répertoire de données persistant.
6. 06.Enregistrement CAA : un CAA qui n'autorise qu'une autre autorité bloque l'émission. Autorisez `letsencrypt.org` et `sectigo.com` (utilisé par ZeroSSL) ou supprimez la restriction.

# Does the name resolve to this server (both IPv4 and IPv6)?
dig +short A example.com
dig +short AAAA example.com
curl -4 -s https://ifconfig.me ; echo

# Are ports 80 and 443 open in the host firewall?
sudo ufw status
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

# Is something else already bound to 80/443?
sudo ss -ltnp '( sport = :80 or sport = :443 )'

# What does Caddy say?
sudo journalctl -u caddy --no-pager -n 100

HTTPS jusqu'au backend aussi

La plupart des backends sur le même hôte parlent HTTP en clair sur localhost, ce qui convient. Quand l'upstream est sur une autre machine ou exige TLS, utilisez un upstream `https://` et indiquez à Caddy quel nom vérifier et quelle autorité approuver. Évitez `tls_insecure_skip_verify` hors des tests rapides, car cela supprime la protection contre l'interception entre le proxy et le backend. Pour le trafic entre serveurs, un tunnel WireGuard privé est souvent plus simple que la gestion de certificats côté backend.

Sur un VPS NoctisNode avec accès root complet et une adresse IPv4 dédiée, la configuration habituelle est : pointer un enregistrement A (pas de AAAA sauf si le serveur a de l'IPv6) vers le serveur, ouvrir 80 et 443, et laisser Caddy faire le reste. Pour transférer du trafic non HTTP, voir proxy TCP et SSH avec Caddy.

example.com {
	reverse_proxy https://10.0.0.5:8443 {
		transport http {
			tls_server_name backend.internal
			tls_trust_pool file /etc/caddy/backend-ca.pem
		}
	}
}

FAQ