Come generare un CSR su Heroku

Questo tutorial ti mostra come generare una CSR (Certificate Signing Request) per Heroku utilizzando OpenSSL e come caricare il certificato emesso con la Heroku CLI.

Heroku non dispone di un modulo CSR integrato nella piattaforma stessa, quindi la richiesta e la chiave privata corrispondente vengono generate al di fuori della piattaforma (sulla tua macchina locale Linux, macOS o Windows, oppure in qualsiasi shell dove sia disponibile OpenSSL). Una volta che l’Autorità di Certificazione emette il certificato, lo combini con la catena intermedia e lo carichi tramite heroku certs:add.

Ti serve davvero una CSR su Heroku?

Per la maggior parte delle app Heroku, la risposta è no. La funzione Automated Certificate Management (ACM) di Heroku fornisce e rinnova automaticamente un certificato Let’s Encrypt gratuito per ogni dominio personalizzato sull’app, senza bisogno di generare una CSR né di gestire un calendario di rinnovi. ACM è disponibile sui dyno Eco, Basic, Standard e Performance. Se ACM è adatto al tuo caso d’uso, attivalo con un singolo comando della CLI:

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

Genera una CSR e usa un certificato autogestito (di terze parti) solo se si applica una delle seguenti condizioni:

• Ti serve un certificato wildcard. ACM emette solo certificati Let’s Encrypt a nome singolo per ogni dominio personalizzato, non *.example.com.
• Ti serve la validazione OV o EV. ACM offre solo la validazione DV.
• La tua politica o il tuo contratto richiede una specifica Autorità di Certificazione diversa da Let’s Encrypt.
• Possiedi già un certificato valido e vuoi ridistribuirlo su Heroku senza doverlo riemettere.
• Ti serve un certificato multi-dominio (SAN) che coprisca hostname non tutti presenti su questa app Heroku.

Se nessuna delle condizioni precedenti è vera, salta il lavoro sulla CSR e usa ACM. Per il flusso di installazione stesso, consulta la nostra guida su come installare un certificato SSL su Heroku.

Nozioni di base su Heroku SSL da conoscere prima di generare la CSR

Alcuni vincoli della piattaforma determinano come devono essere la CSR e la chiave:

• SNI è l’impostazione predefinita. Ogni nuova app usa Heroku SSL, che si basa su Server Name Indication, quindi un singolo endpoint Heroku può servire più hostname HTTPS con i propri certificati. Il componente aggiuntivo legacy SSL Endpoint è stato deprecato nel 2021 (i nuovi provisioning si sono fermati il 14 maggio 2021; il prodotto ha raggiunto il fine vita il 18 ottobre 2021) e non è disponibile sulle nuove app.
• Solo chiavi RSA. Lo stack SSL di Heroku accetta chiavi private RSA (2048 bit o superiori). Le chiavi ECDSA non sono supportate per i caricamenti manuali dei certificati, quindi genera la CSR con -newkey rsa:2048 (oppure rsa:3072 / rsa:4096 se la tua politica richiede una chiave più grande).
• È richiesto il PEM fullchain. Heroku si aspetta un unico file PEM con il certificato end-entity prima e il bundle CA intermedio concatenato dopo. Un certificato solo foglia verrà rifiutato durante il caricamento.
• Chiave privata non cifrata. La chiave caricata con il certificato non può essere protetta da passphrase. Il comando OpenSSL riportato di seguito usa -nodes per scrivere la chiave in PEM in chiaro.
• Prerequisito del dominio personalizzato. Heroku non associerà alcun certificato (ACM o manuale) finché il dominio personalizzato non sarà registrato con l’app tramite heroku domains:add e puntato al target DNS specifico per dominio *.herokudns.com.

Genera la CSR per Heroku con OpenSSL

Se hai già generato la tua CSR e ricevuto il certificato firmato dalla tua Autorità di Certificazione, salta direttamente a Carica il certificato su Heroku. Hai due modi per creare una CSR per un deployment Heroku:

• Usa il Generatore CSR di SSL Dragon: produce sia la CSR che la chiave privata RSA corrispondente direttamente nel browser a partire da un breve modulo, poi incolli la CSR durante l’ordine del tuo SSL.
• Genera la CSR tu stesso con OpenSSL, sia sulla tua macchina locale sia in qualsiasi shell dove OpenSSL sia installato. I passaggi seguenti descrivono questo percorso.

Passo 1: apri una shell con OpenSSL

OpenSSL è incluso in ogni distribuzione Linux recente e in macOS. Su Windows, installalo (consulta la nostra guida su come installare OpenSSL su Windows) ed esegui il comando in PowerShell o nel Prompt dei comandi. Apri un terminale in una cartella su cui hai i permessi di scrittura: OpenSSL creerà lì i file della CSR e della chiave come testo semplice, così potrai spostarli fuori dalla macchina una volta terminato.

Passo 2: esegui il comando OpenSSL

Esegui il seguente comando nella tua shell. Sostituisci yourdomain con il tuo dominio effettivo (ad esempio, example.com):

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

Cosa fa ciascun parametro:

• -new crea una nuova CSR.
• -newkey rsa:2048 genera una nuova chiave privata RSA a 2048 bit insieme alla CSR. Usa rsa:3072 o rsa:4096 se la tua politica richiede una chiave più grande. Non passare a ECDSA: Heroku rifiuta le chiavi ECC nei caricamenti manuali.
• -nodes scrive la chiave senza passphrase (in OpenSSL 3.x il parametro equivalente è -noenc; entrambi funzionano). Heroku rifiuterà una chiave privata cifrata durante heroku certs:add.
• -keyout e -out sono i percorsi di output per la chiave e la CSR.
• -addext “subjectAltName=DNS:…” incorpora direttamente i Subject Alternative Names (SAN) (richiede OpenSSL 1.1.1 o successivo). Ogni browser e CA moderni richiedono l’estensione SAN, anche per i certificati a dominio singolo, quindi includi sia l’apice (yourdomain.com) che qualsiasi variante www che intendi servire su Heroku. Per un wildcard, elenca anche *.yourdomain.com.

Passo 3: compila i dettagli della CSR

OpenSSL ti chiede i campi identificativi del certificato. Inseriscili come segue:

• Country Name: il codice ISO a due lettere del paese in cui la tua organizzazione è legalmente registrata (ad esempio, US).
• State or Province Name: il nome completo dello stato o della regione (ad esempio, Nevada). Non abbreviare.
• Locality Name: la città (ad esempio, Las Vegas).
• Organization Name: il nome legale della tua organizzazione. Per un certificato a Validazione di Dominio questo campo non viene convalidato e può essere omesso, ma non limitarti a premere Invio: OpenSSL inserirà allora qualsiasi valore predefinito definito dalla sua configurazione, e la configurazione standard include Internet Widgits Pty Ltd, che finirebbe nella tua CSR. Digita un singolo punto (.) per lasciarlo effettivamente vuoto.
• Organizational Unit Name: deprecato dal CA/Browser Forum, quindi lascialo vuoto.
• Common Name: il nome di dominio completamente qualificato (FQDN) che vuoi proteggere, ad esempio www.yourdomain.com. Per un wildcard, inserisci *.yourdomain.com. Il Common Name deve essere presente anche nell’elenco SAN.
• Email Address: un’e-mail di contatto valida (oppure lascia vuoto).
• A challenge password e An optional company name: lascia entrambi vuoti. Premi Invio per saltare.

OpenSSL scrive due file nella directory corrente:

• yourdomain.csr: la CSR che invii alla tua Autorità di Certificazione.
• yourdomain.key: la chiave privata. Mantieni questo file privato e crea un backup; ne avrai nuovamente bisogno quando caricherai il certificato emesso su Heroku.

Passo 4: invia la CSR alla tua Autorità di Certificazione

Apri yourdomain.csr in un qualsiasi editor di testo e copia l’intero blocco, inclusi i marcatori -----BEGIN CERTIFICATE REQUEST----- e -----END CERTIFICATE REQUEST-----. Incollalo nel campo CSR durante l’ordine del tuo SSL.

Prima di procedere con l’invio, puoi verificare il contenuto della CSR con il nostro Decodificatore CSR: mostra il Common Name, l’elenco SAN, il tipo di chiave e la lunghezza della chiave così puoi individuare eventuali errori prima che lo faccia la CA.

Completa i passaggi di validazione richiesti dalla CA (DNS, basati su file o e-mail). Una volta emesso il certificato, la CA ti invierà il certificato end-entity firmato (di solito un file .crt) e il bundle CA intermedio (spesso un file .ca-bundle). Prosegui con il caricamento descritto di seguito.

Carica il certificato su Heroku

Passo 1: registra il tuo dominio personalizzato con l’app

Heroku non associerà un certificato finché il dominio personalizzato non sarà registrato con l’app. Da un terminale con accesso alla Heroku CLI, esegui:

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

Sostituisci www.example.com con il tuo dominio e your-app-name con la tua app Heroku. Ripeti il comando per eventuali hostname aggiuntivi (ad esempio un dominio radice o un secondo sottodominio). Il comando restituisce un target DNS specifico per dominio come quiet-fire-1234.herokudns.com: punterai il tuo provider DNS a questo valore nel Passo 4.

Passo 2: crea il file PEM fullchain

Heroku si aspetta un unico file PEM con il certificato end-entity prima e la catena intermedia dopo. Su Linux o macOS, concatena i file con cat:

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

Su Windows, apri entrambi i file in un editor di testo semplice (Notepad++ o VS Code, non Word) e incolla il contenuto del .ca-bundle sotto il contenuto del .crt, in quest’ordine, senza righe vuote tra i blocchi. Salva il file combinato come server.crt. Se la tua CA ti ha già inviato la catena all’interno di un unico PEM (con la foglia in alto), puoi usare quel file così com’è.

Passo 3: carica il certificato con la Heroku CLI

Per una nuova installazione, carica il PEM fullchain e la chiave privata corrispondente con certs:add:

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

Se stai sostituendo un certificato esistente sulla stessa app (ad esempio durante il rinnovo), usa invece certs:update così Heroku mantiene lo stesso target DNS:

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

Preferisci la dashboard? Apri l’app, vai su Settings > Domains and certificates, clicca su Configure SSL, scegli Manually, trascina il file combinato server.crt nello slot del certificato e il file .key nello slot della chiave privata, poi clicca su Next e confirm.

Se durante il caricamento vedi un Internal server error, quasi sempre la Heroku CLI sulla tua macchina non è aggiornata. Esegui heroku update e riprova. Se l’errore persiste, verifica che il file del certificato sia una fullchain in formato PEM (end-entity prima, intermedi dopo) e che la chiave privata sia la chiave RSA corrispondente alla CSR che hai inviato.

Passo 4: punta il DNS al target DNS di Heroku

Elenca i tuoi domini e copia il target DNS restituito da Heroku per ciascuno:

heroku domains -a your-app-name

Sul tuo provider DNS, crea un record per ogni dominio:

• Sottodominio (ad esempio www.example.com): crea un record CNAME che punti al target DNS di Heroku.
• Dominio apice / radice (ad esempio example.com): un CNAME non è consentito sull’apice secondo la specifica DNS, quindi usa un record ALIAS, ANAME o CNAME appiattito (il nome esatto dipende dal tuo provider DNS) che punti allo stesso target DNS di Heroku. Se il tuo provider DNS non supporta nessuno di questi, sposta il DNS su uno che lo faccia (Cloudflare, DNSimple, Route 53, NS1, easyDNS e simili).

Non puntare il DNS a your-app-name.herokuapp.com né a un hostname *.herokussl.com: l’associazione manuale non verrà instradata correttamente attraverso nessuno di questi. Usa sempre il target DNS specifico per dominio assegnato da Heroku.

Verifica la CSR e il certificato distribuito

Prima di inviare la CSR, decodificala localmente per confermare il Common Name, l’elenco SAN, il tipo di chiave e la lunghezza della chiave:

openssl req -in yourdomain.csr -noout -text

Oppure incolla la CSR nel nostro Decodificatore CSR per ottenere le stesse informazioni direttamente nel browser.

Dopo il caricamento, confirma che il certificato sia installato e stia servendo il traffico. Dalla CLI:

heroku certs:info -a your-app-name

L’output elenca il certificato, la CA emittente, la data di scadenza e i domini che copre. Poi apri il tuo sito tramite https:// in un browser, verifica la presenza del lucchetto ed esegui una scansione esterna più approfondita con il nostro SSL Checker per confermare che la catena del certificato sia completa e che i protocolli siano configurati correttamente.