Come installare un certificato SSL su Heroku

Questa guida mostra come installare un certificato SSL su Heroku. Copre entrambi i metodi con cui Heroku gestisce oggi la terminazione TLS: Automated Certificate Management (ACM), che genera e rinnova per te certificati gratuiti Let’s Encrypt, e il caricamento manuale di un certificato di terze parti tramite la dashboard o la Heroku CLI.

Alcune cose da sapere prima di iniziare. Il vecchio add-on SSL Endpoint di Heroku (il prodotto a pagamento da $20/mese) è stato dismesso nel 2021 e non può più essere attivato su nuove app. Ogni nuovo deployment HTTPS utilizza Heroku SSL, che si basa sull’estensione SNI (Server Name Indication) ed è incluso senza costi aggiuntivi in ogni piano dyno a pagamento. I dyno gratuiti sono stati ritirati il 28 novembre 2022, quindi è necessario un piano Eco, Basic, Standard o Performance per collegare un dominio personalizzato e servire contenuti HTTPS.

Genera il CSR (per i certificati caricati manualmente)

Se hai già generato il tuo CSR e ricevuto il certificato emesso dalla tua Certificate Authority, passa direttamente a Installa un certificato SSL su Heroku.

Hai bisogno di un CSR solo se stai acquistando un certificato di terze parti da caricare manualmente. Se prevedi di usare ACM, puoi saltare completamente questa sezione: ACM emette il certificato per te e non c’è alcun CSR da inviare.

Un CSR (Certificate Signing Request) è un blocco di testo che invii alla Certificate Authority durante l’ordine. Contiene i dettagli del tuo dominio e della tua organizzazione, oltre alla chiave pubblica per cui verrà emesso il certificato. Heroku non genera i CSR direttamente sulla piattaforma, quindi devi generare la richiesta al di fuori di essa. Hai due opzioni:

• Usa il CSR Generator di SSL Dragon, che genera il CSR e la chiave privata corrispondente da un breve modulo.
• Genera la richiesta in locale con OpenSSL seguendo il nostro tutorial su come generare un CSR per Heroku.

Apri il file .csr risultante in un qualsiasi editor di testo e copia l’intero blocco, inclusi i marcatori —–BEGIN CERTIFICATE REQUEST—– e —–END CERTIFICATE REQUEST—–, quindi incollalo durante il tuo ordine su SSL Dragon. Attendi che la CA convalidi ed emetta il certificato (da pochi minuti per un DV a diversi giorni lavorativi per OV/EV) e prosegui con l’installazione qui sotto.

Installa un certificato SSL su Heroku

Heroku offre due percorsi per l’HTTPS. Scegli quello che corrisponde al modo in cui hai ottenuto il certificato:

• ACM (consigliato per la maggior parte delle app). Heroku emette, installa e rinnova automaticamente un certificato gratuito Let’s Encrypt per ogni dominio personalizzato dell’app. Nessun file da caricare, nessun calendario di rinnovo da gestire. Disponibile su dyno Eco, Basic, Standard e Performance.
• Caricamento manuale. Usa questa opzione quando hai bisogno di un certificato di terze parti specifico (ad esempio un prodotto Organization Validated o Extended Validation, oppure un wildcard emesso da una CA diversa da Let’s Encrypt). Carichi tu stesso il certificato e la chiave privata tramite la dashboard o la CLI.

Passaggio 1. Aggiungi il tuo dominio personalizzato all’app

Heroku non genererà alcun certificato (ACM o manuale) finché il tuo dominio personalizzato non è registrato con l’app. Da un terminale con privilegi elevati, esegui:

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

Sostituisci www.example.com con il tuo dominio e your-app-name con il nome della tua app Heroku. Ripeti il comando per eventuali altri hostname (ad esempio un dominio principale nudo o un secondo sottodominio). Puoi anche aggiungere il dominio dalla dashboard in Settings > Domains and certificates > Add domain.

Ogni dominio che aggiungi viene restituito insieme a un DNS target univoco, ad esempio quiet-fire-1234.herokudns.com. Avrai bisogno di questo valore quando aggiornerai il DNS al Passaggio 3.

Passaggio 2. Genera il certificato

Opzione A: ACM (gratuito, rinnovo automatico con Let’s Encrypt)

Abilita ACM per l’app dalla CLI:

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

Heroku inizia a emettere un certificato Let’s Encrypt per ogni dominio personalizzato dell’app. Per seguire l’avanzamento e confermare lo stato, esegui:

heroku certs:auto -a your-app-name

Puoi anche abilitare ACM dalla dashboard: apri l’app, vai su Settings > Domains and certificates, clicca su Configure SSL, scegli Automated Certificate Management, quindi Continue. Una volta che il DNS è configurato correttamente (Passaggio 3), ACM completa la convalida del dominio e il certificato diventa attivo. I rinnovi avvengono automaticamente circa un mese prima della scadenza.

Opzione B: caricamento manuale di un certificato di terze parti

La CA ti invia tre file nella casella di posta:

• Il certificato end-entity, solitamente con estensione .crt (formato PEM).
• Il bundle CA (certificati intermedi), spesso con estensione .ca-bundle.
• La chiave privata generata insieme al CSR (un file .key).

Heroku richiede un unico file PEM che contenga il certificato end-entity seguito dagli intermedi (una fullchain). Su Linux o macOS, concatenali con cat:

cat yourcertificate.crt bundle.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 file .ca-bundle sotto il contenuto del file .crt, in quest’ordine, senza righe vuote tra i blocchi. Salva il file combinato come server.crt.

Carica la fullchain e la chiave privata con la Heroku CLI:

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

Se stai sostituendo un certificato già esistente sull’app (ad esempio durante un rinnovo), usa invece certs:update in modo che Heroku mantenga lo stesso DNS target:

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

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

Se durante il caricamento vedi un errore Internal server error, molto probabilmente la tua Heroku CLI locale non è aggiornata. Aggiornala con heroku update e riprova. Heroku richiede inoltre chiavi RSA; le chiavi ECDSA non sono al momento supportate per i caricamenti manuali.

Passaggio 3. Punta il DNS verso il DNS target di Heroku

Indipendentemente dal metodo di generazione, il certificato diventa attivo solo quando il DNS del dominio personalizzato risolve verso Heroku. Elenca i tuoi domini e copia il DNS target restituito da Heroku:

heroku domains -a your-app-name

Vedrai un valore come quiet-fire-1234.herokudns.com accanto a ciascun dominio. Presso il tuo provider DNS, crea un record per ogni dominio:

• Sottodominio (ad esempio www.example.com): crea un record CNAME che punti al DNS target di Heroku.
• Dominio apex / root (ad esempio example.com): il CNAME non è consentito sull’apex secondo la specifica DNS, quindi usa un record ALIAS, ANAME o CNAME appiattito (flattened) (il nome esatto dipende dal tuo provider DNS) che punti allo stesso DNS target di Heroku. Se il tuo provider DNS non supporta nessuna di queste opzioni, ospita il DNS presso uno che lo faccia (Cloudflare, DNSimple, Route 53, NS1, easyDNS, ecc.).

Non puntare il DNS verso your-app-name.herokuapp.com o verso qualsiasi hostname *.herokussl.com: ACM non può convalidare il certificato tramite questi indirizzi, e anche un’associazione manuale non instraderebbe correttamente il traffico. Usa sempre il DNS target specifico per dominio assegnato da Heroku.

Le modifiche al DNS possono richiedere da pochi minuti ad alcune ore per propagarsi. Una volta che Heroku rileva il record aggiornato, ACM completa automaticamente la convalida (oppure il certificato manuale inizia a servire il traffico).

Passaggio 4. Verifica che il certificato sia attivo

Conferma l’installazione 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 e verifica che sia presente il lucchetto, ed esegui una scansione esterna più approfondita con il nostro SSL Checker per confermare che la catena di certificati sia completa e che i protocolli siano configurati correttamente.

Domande frequenti