Wie man einen CSR auf Heroku generiert

Dieses Tutorial zeigt Ihnen, wie Sie eine CSR (Certificate Signing Request) für Heroku erstellen, indem Sie OpenSSL verwenden, und wie Sie das ausgestellte Zertifikat mit der Heroku CLI hochladen.

Heroku selbst verfügt über kein integriertes CSR-Formular, daher werden die Anfrage und der passende private Schlüssel außerhalb der Plattform erstellt (auf Ihrem lokalen Linux-, macOS- oder Windows-Rechner oder in jeder beliebigen Shell mit OpenSSL). Sobald die Zertifizierungsstelle das Zertifikat ausgestellt hat, kombinieren Sie es mit der Zwischenzertifikatskette und laden es über heroku certs:add hoch.

Benötigen Sie überhaupt eine CSR auf Heroku?

Für die meisten Heroku-Apps lautet die Antwort nein. Herokus Automated Certificate Management (ACM) stellt für jede benutzerdefinierte Domain der App automatisch ein kostenloses Let’s Encrypt-Zertifikat aus und erneuert es auch automatisch – ohne dass Sie eine CSR erstellen oder einen Erneuerungskalender führen müssen. ACM ist bei Eco-, Basic-, Standard- und Performance-Dynos verfügbar. Wenn ACM zu Ihrem Anwendungsfall passt, aktivieren Sie es mit einem einzigen CLI-Befehl:

heroku certs:auto:enable -a your-app-name

Erstellen Sie nur dann eine CSR und verwenden Sie ein selbst verwaltetes (Drittanbieter-)Zertifikat, wenn einer der folgenden Punkte zutrifft:

• Sie benötigen ein Wildcard-Zertifikat. ACM stellt pro benutzerdefinierter Domain nur Let’s Encrypt-Zertifikate mit einem einzelnen Namen aus, nicht *.example.com.
• Sie benötigen eine OV– oder EV-Validierung. ACM bietet nur DV.
• Ihre Richtlinie oder Ihr Vertrag verlangt eine bestimmte Zertifizierungsstelle, die nicht Let’s Encrypt ist.
• Sie besitzen bereits ein gültiges Zertifikat und möchten es auf Heroku erneut bereitstellen, ohne es neu ausstellen zu lassen.
• Sie benötigen ein Multi-Domain-Zertifikat (SAN), das Hostnamen abdeckt, die nicht alle zu dieser Heroku-App gehören.

Trifft nichts davon zu, überspringen Sie die CSR-Erstellung und verwenden Sie ACM. Den eigentlichen Installationsablauf finden Sie in unserem Leitfaden SSL-Zertifikat auf Heroku installieren.

Heroku-SSL-Grundlagen, die Sie vor der CSR-Erstellung kennen sollten

Ein paar Plattformbeschränkungen bestimmen, wie die CSR und der Schlüssel aussehen müssen:

• SNI ist der Standard. Jede neue App verwendet Heroku SSL, das auf Server Name Indication basiert, sodass ein einzelner Heroku-Endpunkt mehrere HTTPS-Hostnamen mit eigenen Zertifikaten bedienen kann. Das ältere SSL Endpoint-Add-on wurde 2021 abgekündigt (neue Bereitstellungen wurden am 14. Mai 2021 eingestellt; das Produkt erreichte am 18. Oktober 2021 sein Lebensende) und steht bei neuen Apps nicht mehr zur Verfügung.
• Nur RSA-Schlüssel. Herokus SSL-Stack akzeptiert private RSA-Schlüssel (2048 Bit oder größer). ECDSA-Schlüssel werden für manuelle Zertifikats-Uploads nicht unterstützt, erstellen Sie die CSR daher mit -newkey rsa:2048 (oder rsa:3072 / rsa:4096, falls Ihre Richtlinie einen größeren Schlüssel vorschreibt).
• Vollständige PEM-Kette erforderlich. Heroku erwartet eine einzelne PEM-Datei, in der zuerst das Endzertifikat und danach das gebündelte Zwischenzertifikat der Zertifizierungsstelle stehen. Ein Zertifikat ohne die Zwischenzertifikate wird beim Upload abgelehnt.
• Unverschlüsselter privater Schlüssel. Der zusammen mit dem Zertifikat hochgeladene Schlüssel darf nicht durch eine Passphrase geschützt sein. Der unten stehende OpenSSL-Befehl verwendet -nodes, um den Schlüssel im Klartext-PEM-Format zu schreiben.
• Voraussetzung: benutzerdefinierte Domain. Heroku bindet kein Zertifikat (weder ACM noch manuell), solange die benutzerdefinierte Domain nicht über heroku domains:add bei der App registriert und auf das domainspezifische DNS-Ziel *.herokudns.com ausgerichtet wurde.

CSR für Heroku mit OpenSSL erstellen

Wenn Sie Ihre CSR bereits erstellt und das signierte Zertifikat von Ihrer Zertifizierungsstelle erhalten haben, springen Sie direkt zu Zertifikat auf Heroku hochladen. Es gibt zwei Möglichkeiten, eine CSR für ein Heroku-Deployment zu erstellen:

• Verwenden Sie den CSR-Generator von SSL Dragon: Er erstellt sowohl die CSR als auch den passenden privaten RSA-Schlüssel direkt in Ihrem Browser anhand eines kurzen Formulars, danach fügen Sie die CSR bei Ihrer SSL-Bestellung ein.
• Erstellen Sie die CSR selbst mit OpenSSL, entweder auf Ihrem lokalen Rechner oder in jeder Shell, in der OpenSSL installiert ist. Die folgenden Schritte beschreiben diesen Weg.

Schritt 1: Eine Shell mit OpenSSL öffnen

OpenSSL ist auf jeder aktuellen Linux-Distribution und auf macOS bereits vorhanden. Installieren Sie es unter Windows (siehe unseren Leitfaden zur Installation von OpenSSL unter Windows) und führen Sie den Befehl in PowerShell oder der Eingabeaufforderung aus. Öffnen Sie ein Terminal in einem beliebigen Ordner, in den Sie schreiben können: OpenSSL erstellt dort die CSR- und Schlüsseldateien als Klartext, sodass Sie sie anschließend vom Rechner entfernen können.

Schritt 2: Den OpenSSL-Befehl ausführen

Führen Sie den folgenden Befehl in Ihrer Shell aus. Ersetzen Sie yourdomain durch Ihre tatsächliche Domain (zum Beispiel example.com):

openssl req -new -newkey rsa:2048 -nodes 
  -keyout yourdomain.key -out yourdomain.csr 
  -addext "subjectAltName = DNS:yourdomain.com,DNS:www.yourdomain.com"

Was jede Option bewirkt:

• -new erstellt eine neue CSR.
• -newkey rsa:2048 erzeugt zusammen mit der CSR einen neuen privaten RSA-Schlüssel mit 2048 Bit. Verwenden Sie rsa:3072 oder rsa:4096, falls Ihre Richtlinie einen größeren Schlüssel vorschreibt. Wechseln Sie nicht zu ECDSA: Heroku lehnt ECC-Schlüssel bei manuellen Uploads ab.
• -nodes schreibt den Schlüssel ohne Passphrase (bei OpenSSL 3.x lautet die entsprechende Option -noenc; beide funktionieren). Heroku lehnt einen verschlüsselten privaten Schlüssel bei heroku certs:add ab.
• -keyout und -out sind die Ausgabepfade für den Schlüssel und die CSR.
• -addext „subjectAltName=DNS:…“ bettet Subject Alternative Names (SANs) direkt ein (erfordert OpenSSL 1.1.1 oder neuer). Jeder moderne Browser und jede CA verlangt die SAN-Erweiterung, selbst bei Zertifikaten für eine einzelne Domain. Geben Sie daher sowohl die Hauptdomain (yourdomain.com) als auch jede www-Variante an, die Sie über Heroku bereitstellen möchten. Für ein Wildcard-Zertifikat listen Sie zusätzlich *.yourdomain.com auf.

Schritt 3: Die CSR-Details ausfüllen

OpenSSL fragt Sie nach den Identitätsfeldern des Zertifikats. Geben Sie diese wie folgt ein:

• Country Name: der zweistellige ISO-Code des Landes, in dem Ihre Organisation rechtlich registriert ist (zum Beispiel US).
• State or Province Name: der vollständige Name des Bundeslandes oder der Region (zum Beispiel Nevada). Nicht abkürzen.
• Locality Name: die Stadt (zum Beispiel Las Vegas).
• Organization Name: der offizielle Name Ihrer Organisation. Bei einem Domain-Validation-Zertifikat wird dieses Feld nicht validiert und kann leer bleiben, aber drücken Sie nicht einfach nur Enter: OpenSSL trägt dann den in seiner Konfiguration festgelegten Standardwert ein, und die Standardkonfiguration enthält Internet Widgits Pty Ltd, was dann in Ihrer CSR landen würde. Geben Sie einen einzelnen Punkt (.) ein, um das Feld wirklich leer zu lassen.
• Organizational Unit Name: vom CA/Browser Forum als veraltet eingestuft, daher leer lassen.
• Common Name: der vollqualifizierte Domainname (FQDN), den Sie absichern möchten, zum Beispiel www.yourdomain.com. Für ein Wildcard-Zertifikat geben Sie *.yourdomain.com ein. Der Common Name muss auch in der SAN-Liste enthalten sein.
• Email Address: eine gültige Kontakt-E-Mail (oder leer lassen).
• A challenge password und An optional company name: beide leer lassen. Drücken Sie Enter, um sie zu überspringen.

OpenSSL schreibt zwei Dateien in das aktuelle Verzeichnis:

• yourdomain.csr: die CSR, die Sie bei Ihrer Zertifizierungsstelle einreichen.
• yourdomain.key: der private Schlüssel. Bewahren Sie diese Datei vertraulich auf und sichern Sie sie; Sie benötigen sie erneut, wenn Sie das ausgestellte Zertifikat auf Heroku hochladen.

Schritt 4: Die CSR bei Ihrer Zertifizierungsstelle einreichen

Öffnen Sie yourdomain.csr in einem beliebigen Texteditor und kopieren Sie den gesamten Block einschließlich der Markierungen -----BEGIN CERTIFICATE REQUEST----- und -----END CERTIFICATE REQUEST-----. Fügen Sie ihn während Ihrer SSL-Bestellung in das CSR-Feld ein.

Vor dem Einreichen können Sie den Inhalt der CSR mit unserem CSR-Decoder überprüfen: Er zeigt den Common Name, die SAN-Liste, den Schlüsseltyp und die Schlüssellänge an, damit Sie Tippfehler erkennen, bevor es die CA tut.

Führen Sie die von der CA geforderten Validierungsschritte durch (DNS-, dateibasiert oder per E-Mail). Sobald das Zertifikat ausgestellt ist, sendet Ihnen die CA das signierte Endzertifikat (meist eine .crt-Datei) und das gebündelte Zwischenzertifikat (oft eine .ca-bundle-Datei). Fahren Sie mit dem Upload unten fort.

Zertifikat auf Heroku hochladen

Schritt 1: Ihre benutzerdefinierte Domain bei der App registrieren

Heroku bindet kein Zertifikat, solange die benutzerdefinierte Domain nicht bei der App registriert ist. Führen Sie in einem Terminal, das bei der Heroku CLI angemeldet ist, Folgendes aus:

heroku domains:add www.example.com -a your-app-name

Ersetzen Sie www.example.com durch Ihre Domain und your-app-name durch Ihre Heroku-App. Wiederholen Sie den Befehl für weitere Hostnamen (zum Beispiel eine reine Root-Domain oder eine zweite Subdomain). Der Befehl liefert ein domainspezifisches DNS-Ziel wie quiet-fire-1234.herokudns.com zurück: Darauf richten Sie in Schritt 4 Ihren DNS-Anbieter aus.

Schritt 2: Die vollständige PEM-Kette erstellen

Heroku erwartet eine einzelne PEM-Datei, in der zuerst das Endzertifikat und danach die Zwischenzertifikatskette steht. Unter Linux oder macOS verketten Sie die Dateien mit cat:

cat yourdomain.crt yourdomain.ca-bundle > server.crt

Öffnen Sie unter Windows beide Dateien in einem reinen Texteditor (Notepad++ oder VS Code, nicht Word) und fügen Sie den Inhalt der .ca-bundle-Datei unterhalb des Inhalts der .crt-Datei ein, in dieser Reihenfolge, ohne Leerzeile zwischen den Blöcken. Speichern Sie die kombinierte Datei als server.crt. Wenn Ihre CA die Kette bereits in einer einzigen PEM-Datei gesendet hat (mit dem Endzertifikat an oberster Stelle), können Sie diese Datei unverändert verwenden.

Schritt 3: Das Zertifikat mit der Heroku CLI hochladen

Bei einer komplett neuen Installation laden Sie die vollständige PEM-Kette und den passenden privaten Schlüssel mit certs:add hoch:

heroku certs:add server.crt yourdomain.key -a your-app-name

Wenn Sie ein bestehendes Zertifikat bei derselben App ersetzen (zum Beispiel bei einer Erneuerung), verwenden Sie stattdessen certs:update, damit Heroku dasselbe DNS-Ziel beibehält:

heroku certs:update server.crt yourdomain.key -a your-app-name

Bevorzugen Sie das Dashboard? Öffnen Sie die App, gehen Sie zu Settings > Domains and certificates, klicken Sie auf Configure SSL, wählen Sie Manually, ziehen Sie die kombinierte Datei server.crt in das Zertifikatsfeld und die .key-Datei in das Feld für den privaten Schlüssel, klicken Sie dann auf Next und bestätigen Sie.

Wenn beim Upload ein Internal server error angezeigt wird, ist fast immer die Heroku CLI auf Ihrem Rechner veraltet. Führen Sie heroku update aus und versuchen Sie es erneut. Besteht der Fehler weiterhin, prüfen Sie, ob die Zertifikatsdatei eine vollständige Kette im PEM-Format ist (Endzertifikat zuerst, danach die Zwischenzertifikate) und ob der private Schlüssel der RSA-Schlüssel ist, der zur eingereichten CSR passt.

Schritt 4: DNS auf das Heroku-DNS-Ziel ausrichten

Listen Sie Ihre Domains auf und kopieren Sie das von Heroku für jede zurückgegebene DNS-Ziel:

heroku domains -a your-app-name

Erstellen Sie bei Ihrem DNS-Anbieter für jede Domain einen Eintrag:

• Subdomain (zum Beispiel www.example.com): Erstellen Sie einen CNAME-Eintrag, der auf das Heroku-DNS-Ziel verweist.
• Apex-/Root-Domain (zum Beispiel example.com): Ein CNAME ist auf der Apex-Ebene laut DNS-Spezifikation nicht zulässig, verwenden Sie daher einen ALIAS-, ANAME– oder abgeflachten CNAME-Eintrag (die genaue Bezeichnung hängt von Ihrem DNS-Anbieter ab), der auf dasselbe Heroku-DNS-Ziel verweist. Falls Ihr DNS-Anbieter keine dieser Optionen unterstützt, wechseln Sie zu einem Anbieter, der dies tut (Cloudflare, DNSimple, Route 53, NS1, easyDNS und ähnliche).

Richten Sie DNS nicht auf your-app-name.herokuapp.com oder auf einen *.herokussl.com-Hostnamen aus: Die manuelle Bindung wird über keinen dieser beiden korrekt geroutet. Verwenden Sie immer das von Heroku zugewiesene domainspezifische DNS-Ziel.

Die CSR und das bereitgestellte Zertifikat überprüfen

Bevor Sie die CSR einreichen, dekodieren Sie sie lokal, um den Common Name, die SAN-Liste, den Schlüsseltyp und die Schlüssellänge zu überprüfen:

openssl req -in yourdomain.csr -noout -text

Oder fügen Sie die CSR in unseren CSR-Decoder ein, um dieselben Informationen direkt in Ihrem Browser zu erhalten.

Bestätigen Sie nach dem Upload, dass das Zertifikat installiert ist und den Datenverkehr bedient. Über die CLI:

heroku certs:info -a your-app-name

Die Ausgabe listet das Zertifikat, die ausstellende CA, das Ablaufdatum und die abgedeckten Domains auf. Öffnen Sie anschließend Ihre Website über https:// in einem Browser, prüfen Sie, ob das Schlosssymbol angezeigt wird, und führen Sie mit unserem SSL Checker einen ausführlicheren externen Scan durch, um zu bestätigen, dass die Zertifikatskette vollständig ist und die Protokolle korrekt konfiguriert sind.