OV-Zertifikat mit certbro bestellen

Dieses Rezept zeigt denselben staged OV-Flow wie das reine API-Rezept, aber über certbro. Der entscheidende Unterschied ist: certbro hält Private Key, CSR und den Pending-Zustand der Bestellung lokal vor, gibt die completion_url ins dash aus und beendet erfolgreich, statt endlos auf eine Bestellung zu warten, der noch Business-Daten fehlen.

Falls certbro noch nicht installiert und konfiguriert ist, beginnen Sie bei der Werkzeugseite certbro und dem Rezept Automatisieren mit certbro. Dieses Rezept setzt voraus, dass certbro bereits mit Ihrem regfish API-Key und State-File funktioniert.

Voraussetzungen

Linux mit bereits installiertem certbro
ein konfiguriertes State-File, zum Beispiel /etc/certbro/state.json
ein regfish API-Key mit Zugriff auf TLS und DNS
eine DNS-Zone, die über regfish DNS verwaltet wird
ein browserbasierter Nutzerfluss, der die regfish dash öffnen kann
optional ein eigenes Output-Verzeichnis, wenn Sie den Default-Pfad /etc/certbro/example.com überschreiben wollen

Die Beispiele unten verwenden bewusst den Default-State-Pfad von certbro unter /etc/certbro/state.json. Für den Beispiel-Common-Name leitet certbro außerdem den Default-Output-Pfad /etc/certbro/example.com ab. --state-file und --output-dir ergänzen Sie nur dann, wenn Ihre Installation andere Orte verwendet.

Für OV- oder EV-artige Bestellungen erwartet --org-id die öffentliche TLS-Organisations-ID aus dem regfish TLS API, zum Beispiel hdl_7K9QW3M2ZT8HJ. Eine alte numerische CA-Organisations-ID dürfen Sie hier nicht mehr übergeben.

Schritt 1: OV-Bestellung mit certbro starten

Um den dash-Completion-Pfad gezielt zu demonstrieren, starten Sie die OV-Bestellung ohne --org-id. Dadurch erzeugt certbro die lokalen Key- und CSR-Daten, schickt die technische Bestellung ab und stoppt dann genau in dem Moment, in dem die TLS API meldet, dass noch ein Business-Schritt offen ist.

sudo certbro issue \
  --name example-com \
  --common-name example.com \
  --dns-name www.example.com \
  --product SecureSite

certbro validiert das Produkt vorher gegen den Live-Produktkatalog von regfish. Welche Produkte für Ihr Konto verfügbar sind, zeigt GET /tls/products. Für SecureSite kann die TLS API eine staged OV-Bestellung mit action_required=true zurückgeben.

Schritt 2: Gestufte Ausgabe lesen und Pending-Zustand behalten

Wenn die Bestellung einen dash-Abschluss braucht, beendet sich certbro issue erfolgreich und gibt unter anderem diese Felder aus:

certificate_id
pending_reason
pending_message
completion_url

Gleichzeitig hält certbro den temporären Bestellzustand lokal im Zertifikatsverzeichnis vor, typischerweise unter:

/etc/certbro/example.com/pending/

Genau deshalb sollten Sie jetzt keine Ersatzbestellung manuell erzeugen. certbro weiß bereits, wie dieselbe Pending-Bestellung später fortgesetzt wird.

Schritt 3: dash-Completion-URL öffnen

Öffnen Sie die completion_url, die certbro ausgegeben hat. Für eine staged OV-Bestellung zeigt sie in die regfish dash auf dieselbe Zertifikats-ID.

Dort schließt der Nutzer den Business-Schritt ab:

eine vorhandene bestellfähige Organisation auswählen, oder
eine neue DigiCert-Organisation anlegen, oder
den verbleibenden Bestellschritt im dash abschließen

Das alles gehört weiterhin zu derselben Bestellung, die certbro bereits lokal gespeichert hat.

Falls der Nutzer noch nicht eingeloggt ist, sollte ihn der dash-Login danach wieder auf die Completion-Seite zurückführen.

Schritt 4: Dieselbe Bestellung mit certbro renew fortsetzen

Nachdem der dash-Schritt abgeschlossen wurde, starten Sie nicht noch einmal issue. Stattdessen setzen Sie dieselbe Pending-Bestellung fort mit:

sudo certbro renew --name example-com

Ab hier nimmt certbro renew die gespeicherte Pending-Bestellung wieder auf, setzt DNS-DCV automatisch, sobald Validierungsdaten verfügbar sind, wartet auf die Ausstellung, lädt das Zertifikat herunter und deployt es in dasselbe Output-Verzeichnis.

Falls die Bestellung nach einem Timeout noch pending ist, führen Sie denselben renew-Befehl erneut aus. certbro beobachtet dann denselben bestehenden Request weiter, statt eine doppelte Bestellung anzulegen.

Schritt 5: Finales Deployment prüfen

Nach erfolgreichem Abschluss liegen die stabilen Deploy-Dateien unter live/, versionierte Snapshots unter archive/.

Typische Dateien sind:

/etc/certbro/example.com/live/fullchain.pem
/etc/certbro/example.com/live/cert.pem
/etc/certbro/example.com/live/chain.pem
/etc/certbro/example.com/live/privkey.pem
/etc/certbro/example.com/live/request.csr.pem
/etc/certbro/example.com/live/metadata.json
/etc/certbro/example.com/live/bundle.zip (sofern der Anbieter ein ZIP-Bundle liefert)

Das deployte Zertifikat können Sie schnell so prüfen:

openssl x509 -in /etc/certbro/example.com/live/cert.pem -noout -subject -issuer -dates

Optionale Variante: bekannte öffentliche Organisations-ID direkt mitgeben

Wenn bereits eine nutzbare öffentliche TLS-Organisations-ID aus GET /tls/organization bekannt ist, können Sie sie direkt übergeben:

sudo certbro issue \
  --name example-com \
  --common-name example.com \
  --dns-name www.example.com \
  --product SecureSite \
  --org-id hdl_7K9QW3M2ZT8HJ

Wenn diese Organisation bereits bestellfähig ist, kann die TLS API direkt weiterlaufen, ohne eine staged completion_url zurückzugeben.

Praxishinweise für produktive Abläufe

für ein Rezept, das den dash-Abschluss explizit zeigen soll, lassen Sie --org-id bewusst weg, damit der staged OV-Pfad sichtbar wird
den lokalen Zustand unter pending/ lassen Sie unangetastet, bis certbro renew die Bestellung finalisiert hat
nach dem dash-Abschluss setzen Sie immer mit certbro renew --name ... fort, nicht mit einem zweiten issue
verwenden Sie die von certbro ausgegebene completion_url, nicht einen hart codierten dash-Pfad
wenn bereits eine nutzbare Organisation bekannt ist, ist --org-id der saubere Abkürzungspfad ohne gestuften Business-Schritt
behandeln Sie --org-id als öffentliche hdl_...-ID und nicht als Integer

Ergebnis

Dieser Ablauf startet die OV-Bestellung mit certbro, lagert den fehlenden Organisationsschritt kontrolliert in die regfish dash aus und lässt danach certbro dieselbe Bestellung fertigstellen. So bekommen Sie den staged OV-/Business-Flow, ohne auf rohe API-Calls oder manuelle DCV-Skripte zurückfallen zu müssen.