Comment générer une CSR sur Heroku

Ce tutoriel vous montre comment générer un CSR (Certificate Signing Request) pour Heroku en utilisant OpenSSL et comment téléverser le certificat émis avec le Heroku CLI.

Heroku ne dispose d’aucun formulaire CSR intégré sur la plateforme elle-même, la demande et la clé privée correspondante sont donc générées hors plateforme (sur votre machine locale Linux, macOS ou Windows, ou dans n’importe quel shell disposant d’OpenSSL). Une fois que l’autorité de certification a émis le certificat, vous le combinez avec la chaîne intermédiaire et le téléversez via heroku certs:add.

Avez-vous réellement besoin d’un CSR sur Heroku ?

Pour la plupart des applications Heroku, la réponse est non. La fonctionnalité Automated Certificate Management (ACM) de Heroku provisionne et renouvelle automatiquement un certificat Let’s Encrypt gratuit pour chaque domaine personnalisé de l’application, sans aucun CSR à générer ni calendrier de renouvellement à gérer. ACM est disponible sur les dynos Eco, Basic, Standard et Performance. Si ACM correspond à votre cas d’usage, activez-le avec une seule commande CLI :

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

Générez un CSR et utilisez un certificat auto-géré (tiers) uniquement dans l’un des cas suivants :

• Vous avez besoin d’un certificat wildcard. ACM n’émet que des certificats Let’s Encrypt à nom unique par domaine personnalisé, pas *.example.com.
• Vous avez besoin d’une validation OV ou EV. ACM ne propose que le DV.
• Votre politique ou votre contrat exige une autorité de certification spécifique autre que Let’s Encrypt.
• Vous possédez déjà un certificat valide et souhaitez le redéployer sur Heroku sans le réémettre.
• Vous avez besoin d’un certificat multi-domaines (SAN) couvrant des noms d’hôtes qui ne se trouvent pas tous sur cette application Heroku.

Si aucun des cas ci-dessus ne s’applique, passez outre le travail sur le CSR et utilisez ACM. Pour le processus d’installation lui-même, consultez notre guide sur comment installer un certificat SSL sur Heroku.

Notions de base sur le SSL Heroku à connaître avant de générer le CSR

Quelques contraintes de la plateforme déterminent l’apparence que doivent avoir le CSR et la clé :

• SNI est la valeur par défaut. Chaque nouvelle application utilise Heroku SSL, qui repose sur le Server Name Indication, de sorte qu’un seul point de terminaison Heroku peut servir plusieurs noms d’hôtes HTTPS avec leurs propres certificats. L’ancien add-on SSL Endpoint a été déprécié en 2021 (le nouveau provisionnement s’est arrêté le 14 mai 2021 ; le produit a atteint sa fin de vie le 18 octobre 2021) et n’est plus disponible pour les nouvelles applications.
• Clés RSA uniquement. La pile SSL de Heroku accepte les clés privées RSA (2048 bits ou plus). Les clés ECDSA ne sont pas prises en charge pour les téléversements manuels de certificats, générez donc le CSR avec -newkey rsa:2048 (ou rsa:3072 / rsa:4096 si votre politique exige une clé plus grande).
• Un fichier PEM fullchain est requis. Heroku attend un seul fichier PEM avec le certificat d’entité finale en premier, suivi du bundle CA intermédiaire concaténé à la suite. Un certificat contenant uniquement la feuille sera rejeté lors du téléversement.
• Clé privée non chiffrée. La clé téléversée avec le certificat ne peut pas être protégée par une phrase de passe. La commande OpenSSL ci-dessous utilise -nodes pour écrire la clé en PEM clair.
• Prérequis du domaine personnalisé. Heroku ne liera aucun certificat (ACM ou manuel) tant que le domaine personnalisé n’est pas enregistré auprès de l’application via heroku domains:add et pointé vers la cible DNS *.herokudns.com propre au domaine.

Générer le CSR pour Heroku avec OpenSSL

Si vous avez déjà généré votre CSR et reçu le certificat signé de votre autorité de certification, passez directement à Téléverser le certificat sur Heroku. Vous disposez de deux méthodes pour créer un CSR en vue d’un déploiement Heroku :

• Utiliser le générateur de CSR de SSL Dragon : il produit à la fois le CSR et la clé privée RSA correspondante dans votre navigateur à partir d’un court formulaire, puis vous collez le CSR lors de votre commande SSL.
• Générer le CSR vous-même avec OpenSSL, soit sur votre machine locale, soit dans n’importe quel shell où OpenSSL est installé. Les étapes ci-dessous couvrent cette méthode.

Étape 1 : ouvrir un shell avec OpenSSL

OpenSSL est fourni avec toutes les distributions Linux récentes et avec macOS. Sur Windows, installez-le (voir notre guide sur l’installation d’OpenSSL sur Windows) et exécutez la commande dans PowerShell ou l’invite de commandes. Ouvrez un terminal dans un dossier sur lequel vous avez les droits d’écriture : OpenSSL y créera les fichiers CSR et clé en texte brut, que vous pourrez déplacer hors de la machine une fois l’opération terminée.

Étape 2 : exécuter la commande OpenSSL

Exécutez la commande suivante dans votre shell. Remplacez yourdomain par votre domaine réel (par exemple, example.com) :

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

Le rôle de chaque option :

• -new crée un nouveau CSR.
• -newkey rsa:2048 génère une nouvelle clé privée RSA de 2048 bits en même temps que le CSR. Utilisez rsa:3072 ou rsa:4096 si votre politique exige une clé plus grande. Ne passez pas à l’ECDSA : Heroku rejette les clés ECC lors des téléversements manuels.
• -nodes écrit la clé sans phrase de passe (sur OpenSSL 3.x, l’option équivalente est -noenc ; les deux fonctionnent). Heroku rejettera une clé privée chiffrée lors de heroku certs:add.
• -keyout et -out sont les chemins de sortie pour la clé et le CSR.
• -addext « subjectAltName=DNS:… » intègre directement les Subject Alternative Names (SAN) (nécessite OpenSSL 1.1.1 ou une version ultérieure). Chaque navigateur et chaque autorité de certification modernes exigent l’extension SAN, même pour les certificats à domaine unique, incluez donc à la fois le domaine racine (yourdomain.com) et toute variante www que vous prévoyez de servir sur Heroku. Pour un wildcard, ajoutez également *.yourdomain.com.

Étape 3 : renseigner les détails du CSR

OpenSSL vous invite à saisir les champs d’identité du certificat. Renseignez-les comme suit :

• Country Name : le code ISO à deux lettres du pays où votre organisation est légalement enregistrée (par exemple, US).
• State or Province Name : le nom complet de l’état ou de la région (par exemple, Nevada). N’abrégez pas.
• Locality Name : la ville (par exemple, Las Vegas).
• Organization Name : le nom légal de votre organisation. Pour un certificat Domain Validation, ce champ n’est pas validé et peut être omis, mais n’appuyez pas simplement sur Entrée : OpenSSL renseignera alors la valeur par défaut définie dans sa configuration, et la configuration standard contient Internet Widgits Pty Ltd, qui se retrouverait dans votre CSR. Saisissez un simple point (.) pour le laisser réellement vide.
• Organizational Unit Name : déprécié par le CA/Browser Forum, laissez-le donc vide.
• Common Name : le nom de domaine pleinement qualifié (FQDN) que vous souhaitez sécuriser, par exemple www.yourdomain.com. Pour un wildcard, saisissez *.yourdomain.com. Le Common Name doit également figurer dans la liste SAN.
• Email Address : une adresse e-mail de contact valide (ou laissez vide).
• A challenge password et An optional company name : laissez les deux champs vides. Appuyez sur Entrée pour passer.

OpenSSL écrit deux fichiers dans le répertoire courant :

• yourdomain.csr : le CSR que vous soumettez à votre autorité de certification.
• yourdomain.key : la clé privée. Gardez ce fichier confidentiel et sauvegardez-le ; vous en aurez de nouveau besoin lors du téléversement du certificat émis sur Heroku.

Étape 4 : soumettre le CSR à votre autorité de certification

Ouvrez yourdomain.csr dans n’importe quel éditeur de texte et copiez l’intégralité du bloc, y compris les marqueurs -----BEGIN CERTIFICATE REQUEST----- et -----END CERTIFICATE REQUEST-----. Collez-le dans le champ CSR lors de votre commande SSL.

Avant de le soumettre, vous pouvez vérifier le contenu du CSR avec notre décodeur de CSR : il affiche le Common Name, la liste SAN, le type de clé et la longueur de la clé, afin que vous puissiez repérer les erreurs de saisie avant que l’autorité de certification ne le fasse.

Effectuez les étapes de validation demandées par l’autorité de certification (DNS, basée sur un fichier, ou e-mail). Une fois le certificat émis, l’autorité de certification vous envoie le certificat d’entité finale signé (généralement un fichier .crt) et le bundle CA intermédiaire (souvent un fichier .ca-bundle). Poursuivez avec le téléversement ci-dessous.

Téléverser le certificat sur Heroku

Étape 1 : enregistrer votre domaine personnalisé auprès de l’application

Heroku ne liera aucun certificat tant que le domaine personnalisé n’est pas enregistré auprès de l’application. Depuis un terminal connecté au Heroku CLI, exécutez :

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

Remplacez www.example.com par votre domaine et your-app-name par 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). La commande renvoie une cible DNS propre au domaine, telle que quiet-fire-1234.herokudns.com : vous pointerez votre fournisseur DNS vers cette valeur à l’étape 4.

Étape 2 : construire le fichier PEM fullchain

Heroku attend un seul fichier PEM avec le certificat d’entité finale en premier, suivi de la chaîne intermédiaire. Sous Linux ou macOS, concaténez les fichiers avec cat :

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

Sous Windows, ouvrez les deux fichiers dans un éditeur de texte brut (Notepad++ ou VS Code, pas Word) et collez le contenu du .ca-bundle après le contenu du .crt, dans cet ordre, sans ligne vide entre les blocs. Enregistrez le fichier combiné sous le nom server.crt. Si votre autorité de certification a déjà envoyé la chaîne dans un seul fichier PEM (avec la feuille en haut), vous pouvez utiliser ce fichier tel quel.

Étape 3 : téléverser le certificat avec le Heroku CLI

Pour une toute nouvelle installation, téléversez le fullchain PEM ainsi que la clé privée correspondante avec certs:add :

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

Si vous remplacez un certificat existant sur la même 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 yourdomain.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, glissez le fichier combiné server.crt dans l’emplacement du certificat et le fichier .key dans l’emplacement de la clé privée, puis cliquez sur Next et confirmez.

Si vous voyez une erreur Internal server error lors du téléversement, c’est presque toujours parce que le Heroku CLI installé sur votre machine est obsolète. Exécutez heroku update et réessayez. Si l’erreur persiste, vérifiez que le fichier de certificat est bien un fullchain au format PEM (entité finale en premier, intermédiaires ensuite) et que la clé privée est bien la clé RSA correspondant au CSR que vous avez soumis.

Étape 4 : pointer le DNS vers la cible DNS Heroku

Listez vos domaines et copiez la cible DNS renvoyée par Heroku pour chacun d’eux :

heroku domains -a your-app-name

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 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, migrez votre DNS vers un fournisseur qui le fait (Cloudflare, DNSimple, Route 53, NS1, easyDNS, et autres similaires).

Ne pointez pas le DNS vers your-app-name.herokuapp.com ni vers un nom d’hôte *.herokussl.com : la liaison manuelle ne s’acheminera correctement dans aucun de ces deux cas. Utilisez toujours la cible DNS propre au domaine attribuée par Heroku.

Vérifier le CSR et le certificat déployé

Avant de soumettre le CSR, décodez-le localement pour confirmer le Common Name, la liste SAN, le type de clé et la longueur de la clé :

openssl req -in yourdomain.csr -noout -text

Ou collez le CSR dans notre décodeur de CSR pour obtenir les mêmes informations directement dans votre navigateur.

Après le téléversement, confirmez que le certificat est installé et sert le trafic. Depuis le CLI :

heroku certs:info -a your-app-name

Le résultat affiche le certificat, l’autorité de certification émettrice, la date d’expiration et les domaines couverts. Ouvrez ensuite votre site en https:// dans un navigateur, 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.