Comment installer un certificat SSL sur Heroku

Ce guide vous explique comment installer un certificat SSL sur Heroku. Il couvre les deux méthodes que Heroku utilise aujourd’hui pour terminer TLS : la gestion automatisée des certificats (ACM), qui provisionne et renouvelle gratuitement les certificats Let’s Encrypt pour vous, et le téléversement manuel d’un certificat tiers via le tableau de bord ou le Heroku CLI.

Voici quelques éléments à connaître avant de commencer. Le module complémentaire historique SSL Endpoint de Heroku (le produit payant à 20 $/mois) a été déprécié en 2021 et ne peut plus être provisionné sur de nouvelles applications. Tout nouveau déploiement HTTPS utilise Heroku SSL, qui repose sur l’extension SNI (Server Name Indication) et est inclus sans frais supplémentaires sur chaque palier de dyno payant. Les dynos gratuits ont été retirés le 28 novembre 2022, il vous faut donc un forfait Eco, Basic, Standard ou Performance pour attacher un domaine personnalisé et servir en HTTPS.

Générer la CSR (pour les certificats téléversés manuellement)

Si vous avez déjà généré votre CSR et reçu le certificat émis par votre autorité de certification, passez directement à Installer un certificat SSL sur Heroku.

Vous n’avez besoin d’une CSR que si vous achetez un certificat tiers à téléverser manuellement. Si vous prévoyez d’utiliser ACM, vous pouvez ignorer entièrement cette section : ACM émet le certificat pour vous et il n’y a aucune CSR à soumettre.

Une CSR (Certificate Signing Request) est un bloc de texte que vous soumettez à l’autorité de certification lors de la commande. Elle contient les détails de votre domaine et de votre organisation, ainsi que la clé publique pour laquelle le certificat sera émis. Heroku ne génère pas de CSR directement sur la plateforme, vous devez donc générer la demande en dehors de celle-ci. Vous avez deux options :

• Utiliser le générateur de CSR de SSL Dragon, qui produit la CSR et la clé privée correspondante à partir d’un court formulaire.
• Générer la demande localement avec OpenSSL en suivant notre tutoriel sur comment générer une CSR pour Heroku.

Ouvrez le fichier .csr obtenu dans un éditeur de texte quelconque et copiez l’intégralité du bloc, y compris les marqueurs —–BEGIN CERTIFICATE REQUEST—– et —–END CERTIFICATE REQUEST—–, puis collez-le lors de votre commande SSL Dragon. Attendez que l’autorité de certification valide et émette le certificat (quelques minutes pour un DV à plusieurs jours ouvrés pour un OV/EV) et poursuivez avec l’installation ci-dessous.

Installer un certificat SSL sur Heroku

Heroku vous propose deux chemins vers le HTTPS. Choisissez celui qui correspond à la manière dont vous avez obtenu le certificat :

• ACM (recommandé pour la plupart des applications). Heroku émet, installe et renouvelle automatiquement un certificat Let’s Encrypt gratuit pour chaque domaine personnalisé de l’application. Aucun fichier à téléverser, aucun calendrier de renouvellement à suivre. Disponible sur les dynos Eco, Basic, Standard et Performance.
• Téléversement manuel. Utilisez cette méthode lorsque vous avez besoin d’un certificat tiers spécifique (par exemple, un produit à validation d’organisation ou à validation étendue, ou un certificat wildcard d’une autorité de certification autre que Let’s Encrypt). Vous téléversez vous-même le certificat et la clé privée via le tableau de bord ou le CLI.

Étape 1. Ajouter votre domaine personnalisé à l’application

Heroku ne provisionnera aucun certificat (ACM ou manuel) tant que votre domaine personnalisé n’est pas enregistré auprès de l’application. Depuis un terminal avec privilèges élevés, exécutez :

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

Remplacez www.example.com par votre domaine et your-app-name par le nom de votre application Heroku. Répétez la commande pour tout nom d’hôte supplémentaire (par exemple un domaine racine nu ou un second sous-domaine). Vous pouvez aussi ajouter le domaine depuis le tableau de bord, dans Settings > Domains and certificates > Add domain.

Chaque domaine ajouté est retourné avec une cible DNS unique, par exemple quiet-fire-1234.herokudns.com. Vous aurez besoin de cette valeur lors de la mise à jour du DNS à l’étape 3.

Étape 2. Provisionner le certificat

Option A : ACM (gratuit, renouvellement automatique avec Let’s Encrypt)

Activez ACM pour l’application depuis le CLI :

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

Heroku commence à émettre un certificat Let’s Encrypt pour chaque domaine personnalisé de l’application. Pour suivre la progression et confirmer le statut, exécutez :

heroku certs:auto -a your-app-name

Vous pouvez également activer ACM depuis le tableau de bord : ouvrez l’application, allez dans Settings > Domains and certificates, cliquez sur Configure SSL, choisissez Automated Certificate Management, puis Continue. Une fois le DNS en place (étape 3), ACM termine la validation du domaine et le certificat devient actif. Les renouvellements se font automatiquement environ un mois avant l’expiration.

Option B : téléversement manuel d’un certificat tiers

L’autorité de certification livre trois fichiers dans votre boîte de réception :

• Le certificat d’entité finale, généralement avec une extension .crt (format PEM).
• Le paquet de l’autorité de certification (certificats intermédiaires), souvent avec une extension .ca-bundle.
• La clé privée générée en même temps que la CSR (un fichier .key).

Heroku attend un seul fichier PEM contenant le certificat d’entité finale suivi des intermédiaires (une chaîne complète). Sur Linux ou macOS, concatenez-les avec cat :

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

Sur Windows, ouvrez les deux fichiers dans un éditeur de texte brut (Notepad++ ou VS Code, pas Word) et collez le contenu du .ca-bundle sous le contenu du .crt, dans cet ordre, sans ligne vide entre les blocs. Enregistrez le fichier combiné sous le nom server.crt.

Téléversez la chaîne complète et la clé privée avec le Heroku CLI :

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

Si vous remplacez un certificat existant sur l’application (par exemple lors d’un renouvellement), utilisez plutôt certs:update afin que Heroku conserve la même cible DNS :

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

Vous préférez le tableau de bord ? Ouvrez l’application, allez dans Settings > Domains and certificates, cliquez sur Configure SSL, choisissez Manually, puis faites glisser le fichier combiné server.crt dans l’emplacement du certificat et le fichier .key dans l’emplacement de la clé privée. Cliquez sur Next et confirmez.

Si vous voyez une Internal server error lors du téléversement, votre Heroku CLI local est très probablement obsolète. Mettez-le à jour avec heroku update et réessayez. Heroku exige également des clés RSA ; les clés ECDSA ne sont pas prises en charge pour les téléversements manuels à l’heure actuelle.

Étape 3. Pointer le DNS vers la cible DNS Heroku

Quelle que soit la méthode de provisionnement, le certificat ne devient actif que lorsque le DNS du domaine personnalisé pointe vers Heroku. Listez vos domaines et copiez la cible DNS retournée par Heroku :

heroku domains -a your-app-name

Vous verrez une valeur telle que quiet-fire-1234.herokudns.com à côté de chaque domaine. Chez votre fournisseur DNS, créez un enregistrement par domaine :

• Sous-domaine (par exemple www.example.com) : créez un enregistrement CNAME pointant vers la cible DNS Heroku.
• Domaine apex / racine (par exemple example.com) : un CNAME n’est pas autorisé sur l’apex selon la spécification DNS, utilisez donc un enregistrement ALIAS, ANAME ou de type CNAME aplati (le nom exact dépend de votre fournisseur DNS) pointant vers la même cible DNS Heroku. Si votre fournisseur DNS ne prend en charge aucune de ces options, hébergez le DNS chez un fournisseur qui les prend en charge (Cloudflare, DNSimple, Route 53, NS1, easyDNS, etc.).

Ne pointez pas le DNS vers your-app-name.herokuapp.com ni vers un nom d’hôte *.herokussl.com : ACM ne peut pas valider le certificat par ce biais, et une liaison manuelle ne sera pas non plus correctement routée. Utilisez toujours la cible DNS spécifique au domaine attribuée par Heroku.

Les modifications DNS peuvent prendre de quelques minutes à quelques heures pour se propager. Une fois que Heroku détecte l’enregistrement mis à jour, ACM termine la validation automatiquement (ou votre certificat manuel commence à servir le trafic).

Étape 4. Vérifier que le certificat est actif

Confirmez l’installation depuis le CLI :

heroku certs:info -a your-app-name

La sortie affiche le certificat, l’autorité de certification émettrice, la date d’expiration et les domaines couverts. Ensuite, ouvrez votre site via https:// dans un navigateur et vérifiez la présence du cadenas, puis effectuez une analyse externe plus approfondie avec notre SSL Checker pour confirmer que la chaîne de certificats est complète et que les protocoles sont correctement configurés.

Questions fréquemment posées