Domaine personnalisé bloqué lors de la validation SSL

Vous avez ajouté l'enregistrement. dig l'affiche. La plateforme indique toujours que la validation est en attente, et ce depuis une heure. Un domaine personnalisé bloqué lors de la validation est particulièrement exaspérant, précisément parce que toutes les vérifications que vous pouvez effectuer vous-même semblent réussir.

Il y a quatre causes possibles, elles sont toutes mécaniques, et l'ordre ci-dessous permet de les identifier le plus rapidement.

Première étape : ce que fait réellement la validation

Avant qu'une autorité de certification n'émette un certificat, elle doit établir que vous contrôlez le nom de domaine. Il existe deux méthodes courantes, et celle utilisée par votre plateforme détermine ce qui peut provoquer l'échec :

• HTTP-01 — la CA demande http://your-domain/.well-known/acme-challenge/<token> et attend une chaîne spécifique. Les requêtes HTTP simples vers votre domaine doivent donc atteindre la plateforme.
• DNS-01 — la CA recherche un enregistrement TXT. L'enregistrement doit donc exister et être visible par le resolver de la CA, qui n'est pas nécessairement celui que vous avez interrogé.

Presque tous les blocages de validation sont dus à quelque chose qui s'interpose entre la CA et l'un de ces deux éléments.

Cause 1 : un proxy devant le challenge

C'est la cause la plus fréquente lorsque le domaine se trouve derrière un CDN, et elle est particulièrement déroutante, car le proxy est généralement précisément ce que vous vouliez mettre en place.

Si votre enregistrement DNS est proxifié au lieu de pointer directement vers la plateforme, la requête HTTP-01 de la CA aboutit au proxy. Celui-ci présente son propre certificat, applique ses propres règles et peut renvoyer une redirection, une page de challenge ou une erreur 404 — rien de tout cela ne contient le token attendu par la CA.

La solution consiste à laisser passer le challenge :

• Désactivez le proxy (désactivez le proxy via le nuage gris) jusqu'à l'émission du certificat, puis réactivez-le.
• Ou excluez /.well-known/acme-challenge/* de toute règle de redirection ou de contrôle d'accès.

Le piège, ici, est que les protections de type « Always Use HTTPS » et « Under Attack » interrompent toutes deux HTTP-01 tout en donnant l'impression, dans votre navigateur, que le site fonctionne parfaitement.

Cause 2 : le mauvais type d'enregistrement

Deux erreurs expliquent la plupart des autres cas :

Un enregistrement A pointant vers une adresse susceptible de changer. Si la plateforme vous a fourni un hostname, utilisez un CNAME. Copier l'adresse IP actuelle dans un enregistrement A fonctionne jusqu'à ce que l'adresse change sans prévenir.

Un CNAME à l'apex de la zone. example.com ne peut légalement pas contenir un CNAME en parallèle de ses enregistrements SOA et NS. Certains fournisseurs proposent ALIAS, ANAME ou le « CNAME flattening » pour contourner ce problème ; d'autres non. Si le vôtre ne le permet pas, utilisez un sous-domaine — app.example.com — et redirigez l'apex.

# What the world actually sees, not what your dashboard shows
dig +short app.example.com CNAME
dig +short app.example.com A

Si les deux commandes ne renvoient rien, inutile d'examiner le reste de cette liste pour le moment.

Cause 3 : une propagation que vous ne mesurez pas

dig sans argument interroge votre resolver, qui peut avoir mis en cache la réponse que vous venez de créer — ou, pire encore, avoir mis en cache le NXDOMAIN d'avant sa création. Une entrée de cache négative avec un TTL long est une raison très fréquente pour laquelle une validation échoue pendant une heure, puis réussit sans aucune intervention.

Interrogez directement les serveurs faisant autorité, ainsi qu'un resolver public, pour voir ce que la CA est susceptible d'obtenir :

# Ask the zone's own nameservers
dig +short app.example.com @$(dig +short NS example.com | head -1)

# Ask a resolver outside your network
dig +short app.example.com @1.1.1.1
dig +short app.example.com @8.8.8.8

Si la réponse faisant autorité est correcte alors que les resolvers publics renvoient une réponse erronée, vous devez simplement attendre l'expiration du TTL : il n'y a rien à corriger.

Cause 4 : CAA refuse l'émetteur

Ce cas est rare, invisible lors des vérifications DNS classiques et totalement silencieux lorsqu'il se produit.

Un enregistrement CAA sur votre domaine indique quelles autorités de certification sont autorisées à émettre des certificats pour celui-ci. Si vous en avez un — souvent hérité d'une ancienne configuration ou ajouté à la suite d'une recommandation d'un audit de sécurité — et qu'il n'inclut pas la CA utilisée par votre plateforme, l'émission échoue. Le seul endroit où cela apparaît est dans les logs de la CA, auxquels vous n'avez pas accès.

dig +short example.com CAA
dig +short app.example.com CAA

Une sortie vide signifie qu'aucune restriction ne s'applique, ce qui convient parfaitement. Si des enregistrements sont renvoyés, ajoutez la CA utilisée par votre plateforme ou supprimez la restriction.

L'ordre à suivre pour trouver la cause le plus rapidement

1. Interrogez l'enregistrement avec dig via un resolver public. Aucune réponse signifie que l'enregistrement est incorrect ou qu'il ne s'est pas encore propagé — arrêtez-vous ici.
2. Vérifiez si l'enregistrement est proxifié. Si c'est le cas, désactivez le proxy ou excluez le chemin ACME.
3. Vérifiez les enregistrements CAA sur l'apex et le sous-domaine.
4. Ce n'est qu'ensuite que vous pourrez envisager un problème du côté de la plateforme.

Quatre-vingt-dix pour cent des validations bloquées se résolvent à l'étape 1 ou à l'étape 2.

Fonctionnement avec Dockup

Deux choix de conception éliminent la plupart des approximations.

L'enregistrement DNS est créé pour vous. Si votre zone se trouve sur Cloudflare et que vous avez connecté le compte, l'ajout d'un domaine crée directement l'enregistrement au lieu de vous laisser recopier une valeur manuellement :

dockup domain add app.example.com my-project/my-api --port 3000 --cloudflare

Cela élimine toute une catégorie d'erreurs de saisie et de type d'enregistrement : la plateforme sait si elle doit utiliser un CNAME ou un enregistrement A et crée le bon enregistrement.

L'autorisation repose sur deux permissions. Zone:Read et DNS:Edit, rien de plus. Dockup ne peut pas lire vos autres zones, modifier les paramètres du compte ni intervenir sur quoi que ce soit qui ne lui a pas été accordé. La mise en place de l'automatisation DNS ne devrait pas nécessiter de donner accès à tout un compte.

L'état de la vérification et celui du certificat sont visibles pour chaque domaine, plutôt que regroupés dans un statut global. Ainsi, « DNS vérifié, mais TLS en attente » décrit bien la situation : deux étapes distinctes, dont une est terminée.

Foire aux questions

Combien de temps l'émission d'un certificat doit-elle prendre ? Généralement moins d'une minute une fois que le DNS se résout correctement. Si le statut est en attente depuis plus d'une quinzaine de minutes, quelque chose bloque probablement le processus : il ne s'agit pas simplement d'une lenteur.

Pourquoi mon domaine fonctionne-t-il dans le navigateur, mais échoue-t-il lors de la validation ? Parce que votre navigateur suit les redirections et utilise HTTPS, contrairement au challenge. Un proxy qui sert parfaitement votre site peut tout de même intercepter la requête ACME en HTTP simple.

Puis-je utiliser un CNAME sur mon domaine racine ? Pas avec le DNS standard. Utilisez une fonctionnalité de fournisseur telle qu'ALIAS ou le CNAME flattening, ou faites pointer l'apex vers un sous-domaine avec une redirection.

Qu'est-ce qu'un enregistrement CAA et en ai-je besoin ? Il restreint les autorités de certification autorisées à émettre des certificats pour votre domaine. Vous n'en avez pas besoin, mais si vous en avez un qui exclut la CA de votre plateforme, l'émission échouera silencieusement.