Comment générer une CSR sur GlassFish

Ce tutoriel vous montre comment générer une CSR (Certificate Signing Request) pour GlassFish (désormais Eclipse GlassFish) à l’aide de l’utilitaire Java keytool.

GlassFish est particulier d’une manière pratique : une installation fraîche est déjà livrée avec un keystore (keystore.p12 sur Eclipse GlassFish 7.1 et versions ultérieures, ou keystore.jks sur les versions plus anciennes) et une entrée de certificat par défaut sous l’alias s1as. Vous pouvez générer la CSR directement à partir de cette clé existante, ou la remplacer par une nouvelle clé sous le même alias. Dans les deux cas, le même alias est réutilisé lors de l’importation du certificat signé, de sorte que la clé, la CSR et le certificat émis se trouvent tous au même endroit.

Ce dont vous aurez besoin

• Une installation GlassFish (ou Eclipse GlassFish) fonctionnelle. Le keystore par défaut se trouve dans le répertoire de configuration du domaine, par exemple glassfish/domains/domain1/config/keystore.p12 sur Eclipse GlassFish 7.1 et versions ultérieures, ou keystore.jks sur les versions plus anciennes.
• Une installation Java pour que la commande keytool soit disponible. GlassFish est livré avec un JDK, donc keytool est normalement déjà dans le path. Vérifiez avec keytool -help.
• Un accès shell ou terminal sur le serveur GlassFish. La clé privée doit rester sur ce serveur.
• Le nom de domaine pleinement qualifié (FQDN) exact que vous souhaitez sécuriser, par exemple www.yourdomain.com, ainsi que tout nom d’hôte supplémentaire pour le champ SAN.
• Les informations légales de votre organisation (pays, état, localité, nom de l’organisation) pour le Distinguished Name de la CSR.
• Le mot de passe maître GlassFish du domaine. La valeur par défaut d’usine est changeit ; changez-la sur les systèmes de production avec asadmin change-master-password.

Deux façons de générer la CSR

Si vous avez déjà généré votre CSR, passez directement à soumettre la CSR, puis à installer votre certificat SSL sur GlassFish.

Il existe deux flux keytool courants sur GlassFish. Choisissez celui qui correspond à votre situation :

• Option A : Générer la CSR à partir de la clé s1as existante (recommandé). Un nouveau domaine GlassFish possède déjà une clé privée sous l’alias s1as dans le keystore par défaut (keystore.p12 sur 7.1+, keystore.jks sur les versions plus anciennes). Le chemin le plus rapide et le moins risqué consiste à laisser cette clé en place et à simplement en exporter une CSR. Passez à l’Option A.
• Option B : Remplacer la clé s1as par défaut par une nouvelle clé, puis générer la CSR. Utilisez cette option si vous voulez une taille de clé et un DN connus et actuels, ou si vous soupçonnez que la clé par défaut a été utilisée ou exposée. Passez à l’Option B.

Quelle que soit l’option choisie, l’alias doit rester s1as (ou, si vous le modifiez, vous devez également mettre à jour domain.xml en conséquence). L’écouteur HTTPS de GlassFish recherche le certificat par alias, donc un alias incompatible signifie que GlassFish ne peut pas trouver la clé et que TLS ne démarrera pas.

Option A : Générer la CSR à partir de la clé s1as existante

Étape 1 : Passer au répertoire de configuration GlassFish

Ouvrez un terminal et déplacez-vous dans le répertoire qui contient le keystore de votre domaine. Sur une installation par défaut, il s’agit du dossier config de domain1 :

cd /opt/glassfish7/glassfish/domains/domain1/config

Ajustez le chemin selon l’endroit où vous avez installé GlassFish (les anciennes versions de GlassFish 4 imbriquent l’installation sous un dossier racine glassfish4/ ; Eclipse GlassFish 6, 7 et 8 s’installent généralement sous glassfish7/, glassfish8/ ou similaire). Si vous avez créé votre propre domaine, remplacez domain1 par le nom de ce domaine. Exécutez ls *.p12 *.jks dans ce répertoire pour confirmer le nom du fichier keystore : sur Eclipse GlassFish 7.1 et versions ultérieures, vous verrez keystore.p12 ; sur les versions plus anciennes, vous verrez keystore.jks. Substituez ce nom de fichier partout où les commandes ci-dessous indiquent keystore.jks.

Étape 2 : Confirmer que l’entrée s1as existe

Listez le contenu du keystore et vérifiez que s1as est présent et qu’il s’agit d’une PrivateKeyEntry :

keytool -list -v -keystore keystore.jks -alias s1as

Saisissez le mot de passe du keystore (valeur par défaut d’usine changeit ; sur un serveur de production, il doit correspondre au mot de passe maître du domaine). La sortie doit inclure la ligne Entry type: PrivateKeyEntry. Si vous obtenez à la place le message Alias <s1as> does not exist, passez à l’Option B et créez une nouvelle entrée.

Étape 3 : Exporter la CSR avec SAN

Les navigateurs et clients TLS modernes valident les certificats par rapport à l’extension Subject Alternative Name (SAN), et non par rapport au seul Common Name. Demandez les SAN directement dans la CSR pour que la CA les inclue dans le certificat émis :

keytool -certreq 
  -alias s1as 
  -keystore keystore.jks 
  -file glassfish.csr 
  -ext san=dns:yourdomain.com,dns:www.yourdomain.com

Signification des paramètres :

• -alias s1as : l’alias de certificat GlassFish existant. La clé privée sous cet alias signe la demande.
• -keystore keystore.jks : le fichier keystore par défaut de GlassFish. Eclipse GlassFish 7.1 et versions ultérieures sont livrées avec un keystore PKCS12 nommé keystore.p12 ; les versions plus anciennes utilisent un keystore JKS nommé keystore.jks. Utilisez le nom de fichier qui existe réellement dans ce répertoire. La commande elle-même est identique dans les deux cas ; keytool détecte le format.
• -file glassfish.csr : le nom de fichier de sortie pour la CSR. Choisissez le nom que vous voulez.
• -ext san=dns:… : l’extension Subject Alternative Name. Listez chaque nom d’hôte que le certificat doit couvrir, y compris le domaine nu (yourdomain.com) et le sous-domaine www. Ajoutez d’autres entrées séparées par des virgules, par exemple dns:api.yourdomain.com.

keytool demande le mot de passe du keystore et écrit la CSR dans glassfish.csr dans le répertoire courant. Le Subject (Distinguished Name) de la CSR est repris de ce qui est stocké dans l’entrée s1as ; sur une installation GlassFish fraîche, il s’agit du certificat auto-signé généré automatiquement, donc le DN ne correspondra pas à votre entreprise. La plupart des CA vérifient uniquement le Common Name et la liste SAN et vous laissent remplacer le reste du DN dans le formulaire de commande, mais si vous avez besoin d’une CSR dont le DN comporte déjà les informations légales de votre entreprise, utilisez l’Option B.

Option B : Remplacer la clé s1as par défaut par une nouvelle

Utilisez cette option lorsque vous voulez un contrôle total sur la taille de clé et le DN, ou lorsque vous préférez ne pas réutiliser la clé générée en usine. Le flux est le suivant : supprimer l’entrée s1as par défaut, créer une nouvelle clé sous le même alias, puis exporter la CSR. Garder l’alias s1as signifie que vous n’aurez pas à toucher à domain.xml par la suite.

Étape 1 : Sauvegarder le keystore

Avant de supprimer quoi que ce soit, copiez le keystore actuel afin de pouvoir revenir en arrière si nécessaire. Depuis le répertoire config du domaine :

cp keystore.jks keystore.jks.bak

Étape 2 : Supprimer l’entrée s1as par défaut

keytool -delete -alias s1as -keystore keystore.jks

Saisissez le mot de passe du keystore lorsqu’il vous est demandé.

Étape 3 : Créer une nouvelle clé privée sous le même alias

Générez une nouvelle clé RSA de 2048 bits sous l’alias s1as et fournissez le DN directement en ligne pour que la commande soit non interactive :

keytool -genkeypair 
  -alias s1as 
  -keyalg RSA -keysize 2048 
  -keystore keystore.jks 
  -dname "CN=www.yourdomain.com, O=Your Company LLC, L=San Jose, ST=California, C=US" 
  -validity 825

Signification des paramètres :

• -alias s1as : réutilise l’alias GlassFish par défaut afin qu’aucune modification de domain.xml ne soit nécessaire.
• -keyalg RSA -keysize 2048 : une clé RSA de 2048 bits est le minimum public actuel. Pour de nouvelles clés que vous prévoyez de conserver plusieurs années, 3072 bits constitue une mise à niveau raisonnable. La plupart des CA publiques acceptent également ECDSA (-keyalg EC -groupname secp256r1) pour une clé plus petite et plus rapide.
• -keystore keystore.jks : le keystore GlassFish par défaut. Remplacez par keystore.p12 sur Eclipse GlassFish 7.1 et versions ultérieures. keytool conserve le format de keystore existant (JKS sur les installations plus anciennes, PKCS12 sur les 7.1+) ; les deux conviennent ici.
• -dname « CN=… » : les champs Distinguished Name inscrits dans la CSR. Utilisez les informations exactes et légales de votre entreprise :

• CN : le FQDN exact que vous sécurisez, par exemple www.yourdomain.com, ou un joker tel que *.yourdomain.com. Ne saisissez pas le nom d’une personne, malgré la formulation de l’invite de keytool en mode interactif.
• O : le nom légal complet de votre entreprise.
• L : le nom complet de la ville (ne pas abréger).
• ST : le nom complet de l’état ou de la province (ne pas utiliser un code à deux lettres).
• C : le code pays ISO à deux lettres, par exemple US, GB, DE.
• OU (Organizational Unit) : ce champ n’est plus émis par les CA publiques. Ne l’incluez pas dans le DN.

keytool demande le mot de passe du keystore et le mot de passe de la clé. Sur un domaine GlassFish, le mot de passe du keystore, le mot de passe de la clé et le mot de passe maître du domaine doivent tous correspondre, sinon GlassFish ne peut pas déverrouiller la clé au démarrage et HTTPS échouera. Appuyez sur Entrée à l’invite du mot de passe de la clé pour réutiliser le mot de passe du keystore.

Étape 4 : Exporter la CSR avec SAN

Même commande que pour l’Option A, exécutée sur votre nouvelle clé :

keytool -certreq 
  -alias s1as 
  -keystore keystore.jks 
  -file glassfish.csr 
  -ext san=dns:yourdomain.com,dns:www.yourdomain.com

Saisissez le mot de passe du keystore. keytool écrit la CSR dans glassfish.csr dans le répertoire courant.

Essentiel : conserver l’alias s1as

L’erreur keytool la plus courante sur GlassFish est de modifier l’alias à un moment donné du processus, que ce soit lors de la génération de la clé ou lors de l’importation du certificat signé. Deux modes d’échec apparaissent :

• Alias incorrect sur la clé. L’écouteur HTTPS de GlassFish est câblé sur s1as dans domain.xml. Si vous générez une clé sous un alias différent, GlassFish ne peut pas la trouver et l’écouteur revient au certificat auto-signé par défaut (ou ne démarre pas). Si vous voulez vraiment un alias différent, vous devez mettre à jour chaque référence s1as dans domain.xml en conséquence.
• Alias incorrect à l’importation. Lorsque la CA renvoie votre certificat signé, vous devez le réimporter dans le même alias qui contient la clé privée. Importer sous un tout nouvel alias stocke le certificat comme une entrée de confiance autonome sans clé privée associée, et TLS ne fonctionnera pas.

Notez ces trois valeurs avant de fermer le terminal :

• L’alias (par défaut s1as ; conservez-le).
• Le chemin du fichier keystore, par exemple glassfish/domains/domain1/config/keystore.p12 (ou keystore.jks sur les versions plus anciennes).
• Le mot de passe du keystore (qui doit être identique au mot de passe maître du domaine).

Vérifier la CSR avant de la soumettre

Repérez les fautes de frappe dans le DN ou les SAN manquants avant que la CA ne les valide. Affichez la CSR avec keytool :

keytool -printcertreq -file glassfish.csr

Ou, si OpenSSL est installé, utilisez-le à la place :

openssl req -noout -text -in glassfish.csr

Vérifiez trois éléments dans la sortie : le Subject affiche votre DN exact, le Subject Alternative Name liste chaque nom d’hôte dont vous avez besoin, et la taille de la Public-Key correspond à ce que vous avez demandé (RSA 2048 bits, ou ce que vous avez choisi). Vous pouvez également coller la CSR dans notre Décodeur CSR pour effectuer la même vérification dans un navigateur.

Soumettre la CSR à votre autorité de certification

Ouvrez glassfish.csr dans un éditeur de texte quelconque. Le fichier est du texte brut, commençant par —–BEGIN CERTIFICATE REQUEST—– et se terminant par —–END CERTIFICATE REQUEST—–. Copiez l’intégralité du bloc, y compris ces lignes d’en-tête et de pied de page, et collez-le dans le champ CSR lors de la commande auprès de votre CA. Sur Windows, utilisez Ctrl + A puis Ctrl + C pour récupérer le texte complet ; sur macOS, utilisez Cmd + A puis Cmd + C.

Une fois que la CA a validé votre demande et émis le certificat, poursuivez avec comment installer votre certificat SSL sur GlassFish. Vous importerez la chaîne de la CA en tant que chaîne de confiance, puis vous réimporterez le certificat signé dans l’alias s1as du même fichier keystore (keystore.p12 sur les 7.1+, keystore.jks sur les versions plus anciennes), et enfin vous configurerez l’écouteur HTTPS pour qu’il pointe vers cet alias.