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 Console-completion_url aus und beendet erfolgreich, statt endlos auf eine Bestellung zu warten, der noch Business-Daten fehlen.

Falls certbro noch nicht installiert und konfiguriert ist, starte zuerst mit dem allgemeinen Rezept TLS automation with regfish certbro. Dieses Rezept setzt voraus, dass certbro bereits mit deinem 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 Console öffnen kann
• optional ein eigenes Output-Verzeichnis, wenn du den Default-Pfad /etc/certbro/example.com überschreiben willst

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änzt du nur dann, wenn deine 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 darfst du hier nicht mehr übergeben.

Schritt 1: OV-Bestellung mit certbro starten

Um den Console-Completion-Pfad gezielt zu demonstrieren, startest du 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 dein 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 Console-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 solltest du jetzt keine Ersatzbestellung manuell erzeugen. certbro weiß bereits, wie dieselbe Pending-Bestellung später fortgesetzt wird.

Schritt 3: Console-Completion-URL öffnen

Öffne die completion_url, die certbro ausgegeben hat. Für eine staged OV-Bestellung zeigt sie in die regfish Console 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 in der Console 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 Console-Login danach wieder auf die Completion-Seite zurückführen.

Schritt 4: Dieselbe Bestellung mit certbro renew fortsetzen

Nachdem der Console-Schritt abgeschlossen wurde, startest du nicht noch einmal issue. Stattdessen setzt du 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ührst du 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 kannst du 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, kannst du 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 Console-Abschluss explizit zeigen soll, lässt du --org-id bewusst weg, damit der staged OV-Pfad sichtbar wird
• den lokalen Zustand unter pending/ lässt du unangetastet, bis certbro renew die Bestellung finalisiert hat
• nach dem Console-Abschluss setzt du immer mit certbro renew --name ... fort, nicht mit einem zweiten issue
• verwende die von certbro ausgegebene completion_url, nicht einen hart codierten Console-Pfad
• wenn bereits eine nutzbare Organisation bekannt ist, ist --org-id der saubere Abkürzungspfad ohne gestuften Business-Schritt
• behandle --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 Console aus und lässt danach certbro dieselbe Bestellung fertigstellen. So bekommst du den staged OV-/Business-Flow, ohne auf rohe API-Calls oder manuelle DCV-Skripte zurückfallen zu müssen.