Benutzerdefinierte Domain bleibt bei der SSL-Validierung hängen

Du hast den Record angelegt. dig zeigt ihn an. Die Plattform meldet weiterhin „ausstehend“ – und das bereits seit einer Stunde. Eine benutzerdefinierte Domain, die bei der Validierung hängen bleibt, ist gerade deshalb so frustrierend, weil scheinbar jede Prüfung, die du selbst durchführen kannst, erfolgreich ist.

Es gibt vier Ursachen. Sie sind alle mechanischer Natur, und mit der folgenden Reihenfolge findest du sie am schnellsten.

Zuerst: Was bei der Validierung tatsächlich passiert

Bevor eine Certificate Authority ein Zertifikat ausstellt, muss sie feststellen, dass du die Kontrolle über den Namen hast. Dafür gibt es zwei gängige Verfahren. Welches deine Plattform verwendet, entscheidet darüber, was schiefgehen kann:

• HTTP-01 — Die CA ruft http://your-domain/.well-known/acme-challenge/<token> auf und erwartet eine bestimmte Zeichenfolge. Dafür müssen unverschlüsselte HTTP-Anfragen an deine Domain die Plattform erreichen.
• DNS-01 — Die CA sucht nach einem TXT-Record. Dafür muss der Record existieren und für den Resolver der CA sichtbar sein – und das ist nicht unbedingt der Resolver, den du abgefragt hast.

Fast jede Validierung, die hängen bleibt, wird durch etwas verursacht, das zwischen der CA und einem dieser beiden Punkte steht.

Ursache 1: Ein Proxy vor der Challenge

Das ist die häufigste Ursache, wenn die Domain hinter einem CDN liegt. Gleichzeitig ist sie wirklich verwirrend, weil der Proxy normalerweise genau das ist, was du eigentlich haben wolltest.

Wenn dein DNS-Record proxied ist, statt direkt auf die Plattform zu zeigen, endet die HTTP-01-Anfrage der CA beim Proxy. Der Proxy liefert sein eigenes Zertifikat aus, wendet seine eigenen Regeln an und gibt möglicherweise eine Weiterleitung, eine Challenge-Seite oder einen 404-Fehler zurück – nichts davon enthält das Token, auf das die CA wartet.

Die Lösung besteht darin, die Challenge durchzulassen:

• Deaktiviere den Proxy (versetze den Record in den „grey-cloud“-Status), bis das Zertifikat ausgestellt wurde, und aktiviere ihn anschließend wieder.
• Oder schließe /.well-known/acme-challenge/* von Weiterleitungen oder Zugriffsregeln aus.

Die Falle dabei: Schutzfunktionen wie „Always Use HTTPS“ und „Under Attack“ unterbrechen HTTP-01, obwohl die Website in deinem Browser scheinbar einwandfrei funktioniert.

Ursache 2: Der falsche Record-Typ

Zwei Fehler machen den Großteil der übrigen Fälle aus:

Ein A-Record, der auf eine wechselnde Adresse zeigt. Wenn dir die Plattform einen Hostnamen gegeben hat, verwende einen CNAME. Eine aktuelle IP-Adresse in einen A-Record zu kopieren, funktioniert nur so lange, bis sich die Adresse ändert.

Ein CNAME am Zonen-Apex. example.com kann neben seinen SOA- und NS-Records nicht rechtmäßig einen CNAME enthalten. Manche Anbieter bieten dafür ALIAS, ANAME oder „CNAME flattening“ an, andere nicht. Wenn dein Anbieter diese Möglichkeit nicht unterstützt, verwende eine Subdomain – app.example.com – und leite den Apex dorthin weiter.

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

Wenn beide Abfragen leer zurückkommen, ist alles andere auf dieser Liste zunächst irrelevant.

Ursache 3: Eine Propagation, die du nicht misst

dig ohne Argumente fragt deinen Resolver ab. Dieser kann die gerade erstellte Antwort bereits aus dem Cache liefern – oder, noch schlimmer, den NXDOMAIN-Eintrag aus der Zeit vor der Erstellung zwischengespeichert haben. Ein negativer Cache-Eintrag mit langer TTL ist ein sehr häufiger Grund dafür, dass eine Validierung eine Stunde lang fehlschlägt und anschließend ohne weiteres Zutun erfolgreich ist.

Frage die autoritativen Server direkt sowie einen öffentlichen Resolver ab, um zu sehen, was die CA wahrscheinlich erhält:

# 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

Wenn die autoritative Antwort korrekt ist und die öffentlichen Resolver eine falsche Antwort liefern, wartest du auf den Ablauf der TTL. Daran lässt sich nichts reparieren.

Ursache 4: CAA lehnt den Aussteller ab

Diese Ursache ist selten, bei normalen DNS-Prüfungen unsichtbar und völlig lautlos, wenn sie zum Problem wird.

Ein CAA-Record für deine Domain legt fest, welche Certificate Authorities Zertifikate dafür ausstellen dürfen. Wenn ein solcher Record vorhanden ist – oft aus einer alten Konfiguration übernommen oder aufgrund der Empfehlung eines Security-Scans angelegt – und die von deiner Plattform verwendete CA nicht enthält, schlägt die Ausstellung fehl. Der einzige Hinweis darauf steht dann in den Logs der CA, auf die du keinen Zugriff hast.

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

Eine leere Ausgabe bedeutet, dass keine Einschränkung besteht, und ist in Ordnung. Wenn Records zurückgegeben werden, füge entweder die von deiner Plattform verwendete CA hinzu oder entferne die Einschränkung.

Die Reihenfolge, mit der du das Problem am schnellsten findest

1. Frage den Record mit dig über einen öffentlichen Resolver ab. Keine Antwort bedeutet, dass der Record falsch ist oder noch nicht propagiert wurde – brich hier ab.
2. Prüfe, ob der Record proxied ist. Falls ja, deaktiviere den Proxy oder schließe den ACME-Pfad aus.
3. Prüfe CAA sowohl am Apex als auch an der Subdomain.
4. Erst dann solltest du in Betracht ziehen, dass die Plattform das Problem verursacht.

Neunzig Prozent aller Validierungen, die hängen bleiben, enden bei Schritt 1 oder Schritt 2.

So funktioniert es mit Dockup

Zwei Designentscheidungen ersparen dir den größten Teil der Fehlersuche.

Der DNS-Record wird für dich angelegt. Wenn deine Zone bei Cloudflare liegt und du das Konto verbunden hast, schreibt das Hinzufügen einer Domain den Record automatisch, statt dich einen Wert manuell kopieren zu lassen:

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

Damit entfällt die gesamte Fehlerklasse aus Tippfehlern und falschen Record-Typen – die Plattform weiß, ob sie einen CNAME oder einen A-Record benötigt, und legt den richtigen Record an.

Die Berechtigung besteht aus zwei Permissions. Zone:Read und DNS:Edit, mehr nicht. Dockup kann deine anderen Zonen nicht lesen, keine Kontoeinstellungen ändern und nichts anfassen, für das keine Berechtigung erteilt wurde. Die DNS-Automatisierung sollte nicht voraussetzen, dass du ein gesamtes Konto aus der Hand gibst.

Der Verifizierungs- und Zertifikatsstatus wird pro Domain angezeigt statt in einem einzigen Gesamtstatus. Dadurch bedeutet „DNS verifiziert, aber TLS ausstehend“ genau das, was es aussagt: zwei getrennte Schritte, von denen einer abgeschlossen ist.

Häufig gestellte Fragen

Wie lange sollte die Ausstellung eines Zertifikats dauern? Normalerweise weniger als eine Minute, sobald DNS korrekt aufgelöst wird. Wenn der Status länger als etwa fünfzehn Minuten ausstehend bleibt, blockiert wahrscheinlich etwas die Ausstellung, statt dass der Vorgang einfach nur langsam ist.

Warum funktioniert meine Domain im Browser, schlägt aber bei der Validierung fehl? Weil dein Browser Weiterleitungen befolgt und HTTPS verwendet, während die Challenge beides nicht tut. Ein Proxy, der deine Website perfekt ausliefert, kann die ACME-Anfrage über unverschlüsseltes HTTP trotzdem abfangen.

Kann ich für meine Root-Domain einen CNAME verwenden? Nicht im Standard-DNS. Verwende eine Provider-Funktion wie ALIAS oder CNAME flattening oder leite den Apex per Weiterleitung auf eine Subdomain.

Was ist ein CAA-Record, und brauche ich einen? Er schränkt ein, welche Certificate Authorities Zertifikate für deine Domain ausstellen dürfen. Du brauchst keinen. Wenn jedoch ein CAA-Record vorhanden ist, der die CA deiner Plattform nicht enthält, schlägt die Ausstellung lautlos fehl.