Comment installer un certificat SSL sur un serveur JBoss

Ce tutoriel vous montre comment installer un certificat SSL sur JBoss EAP et WildFly en utilisant keytool et le sous-système de sécurité Elytron. Si vous n’avez pas encore vos fichiers de certificat, la première section explique comment générer une CSR.

Remarque sur les versions : les versions modernes de JBoss EAP (7.1 et ultérieures, y compris EAP 8) et les versions récentes de WildFly configurent le HTTPS via le sous-système elytron relié au https-listener d’Undertow. L’ancienne méthode security-realm et les anciens connecteurs Tomcat ou Jetty sont obsolètes, ce guide utilise donc l’approche actuelle.

Nous avons également enregistré une vidéo qui vous guide à travers l’ensemble du processus. Vous pouvez regarder la vidéo, lire les instructions, ou faire les deux. Vous pouvez regarder la vidéo ci-dessous.

Générer un code CSR sur JBoss

Une CSR (Certificate Signing Request) est un bloc de texte encodé que vous envoyez à l’autorité de certification (CA) lorsque vous commandez un certificat. Elle contient les informations de votre domaine et de votre organisation, que la CA utilise pour valider la demande. La génération de la CSR crée également la clé privée correspondante, qui reste sur votre serveur et est requise lors de l’installation.

Vous avez deux options :

• Utilisez notre générateur de CSR pour créer la CSR automatiquement.
• Suivez notre tutoriel étape par étape sur comment générer une CSR sur JBoss.

Sur JBoss, la CSR est générée avec keytool à partir d’un keystore .jks ou .p12. Notez l’alias et le nom du keystore que vous choisissez maintenant : vous importerez plus tard le certificat signé dans cet alias exact. Soumettez la CSR à la CA lors de votre commande, et une fois le certificat émis, poursuivez avec l’installation ci-dessous.

Installer un certificat SSL sur un serveur JBoss

Étape 1 : Préparez vos fichiers de certificat

Après validation, la CA vous envoie par e-mail vos fichiers de certificat, généralement dans une archive ZIP. Extrayez-la. Vous devriez avoir :

• Votre certificat principal (un fichier .crt, .cer, ou .pem).
• Les certificats intermédiaires, souvent fournis sous forme de fichier .ca-bundle (le CA bundle). Certaines CA incluent également la racine.
• Le keystore (.jks ou .p12) que vous avez créé avec la CSR, qui contient votre clé privée sous l’alias que vous avez choisi lors de la génération de la CSR.

Conservez ces fichiers ensemble, et copiez-les sur le serveur, par exemple dans le répertoire de configuration de JBoss ($JBOSS_HOME/standalone/configuration/). Si un fichier s’ouvre en tant que texte, vous pouvez vérifier qu’il contient bien les lignes BEGIN CERTIFICATE et END CERTIFICATE attendues.

Étape 2 : Importez la chaîne CA dans le keystore

Importez d’abord les certificats intermédiaires (et racine, s’il est fourni) afin que keytool puisse construire une chaîne de confiance complète. Utilisez le même keystore qui contient votre clé privée, et donnez à chaque certificat CA son propre alias :

keytool -import -trustcacerts -alias root -file root.crt -keystore your_keystore.jks

keytool -import -trustcacerts -alias intermediate -file intermediate.crt -keystore your_keystore.jks

Si votre CA a fourni un seul fichier .ca-bundle, importez-le sous un seul alias (par exemple -alias intermediate). Lorsque vous y êtes invité, saisissez le mot de passe du keystore et confirmez la confiance. Ces entrées sont des entrées de certificat de confiance, pas des entrées de clé, elles n’affectent donc pas votre clé privée.

Étape 3 : Importez le certificat signé dans votre alias de clé

Importez maintenant votre certificat signé (la réponse de la CA) dans l’alias exact que vous avez utilisé lors de la génération de la CSR. Comme cet alias contient déjà la clé privée, keytool traite cela comme une réponse de certificat et remplace le certificat autosigné temporaire par la chaîne signée par la CA, tout en conservant la clé intacte :

keytool -import -trustcacerts -alias your_csr_alias -file your_domain.crt -keystore your_keystore.jks

Remplacez your_csr_alias par l’alias que vous avez utilisé lors de la génération de la CSR et your_keystore.jks par votre keystore. En cas de succès, keytool affiche Certificate reply was installed in keystore.

Important : n’inventez pas de nouvel alias ici. Importer la réponse sous un nouvel alias crée une entrée de certificat de confiance sans clé privée, la chaîne est perdue, et le serveur ne peut pas terminer la négociation TLS. Si vous voyez Failed to establish chain from reply, cela signifie que le certificat intermédiaire ou racine de l’étape 2 est manquant dans le keystore.

Vous pouvez vérifier le résultat, l’alias devrait maintenant afficher une chaîne de certificats de longueur supérieure à 1 :

keytool -list -v -alias your_csr_alias -keystore your_keystore.jks

Étape 4 : Configurez le HTTPS dans le sous-système Elytron

Placez le keystore dans $JBOSS_HOME/standalone/configuration/, puis définissez un key-store, un key-manager, et un server-ssl-context Elytron. Le moyen le plus rapide est la CLI de gestion. Démarrez le serveur, connectez-vous avec jboss-cli.sh --connect, et exécutez un batch pour que les modifications s’appliquent ensemble :

batch

/subsystem=elytron/key-store=httpsKS:add(path=your_keystore.jks, relative-to=jboss.server.config.dir, credential-reference={clear-text=your_keystore_password}, type=JKS)

/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS, credential-reference={clear-text=your_keystore_password})

/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM, protocols=["TLSv1.3","TLSv1.2"])

run-batch

Ensuite, faites pointer le https-listener d’Undertow vers le nouveau ssl-context. Undertow ne peut pas référencer simultanément un ancien security-realm et un ssl-context Elytron, alors supprimez l’ancienne référence et définissez la nouvelle dans un seul batch :

batch

/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=httpsSSC)

run-batch

Si vous préférez modifier directement standalone.xml (avec le serveur arrêté), la configuration équivalente ressemble à ceci dans le sous-système elytron :

<tls>
    <key-stores>
        <key-store name="httpsKS">
            <credential-reference clear-text="your_keystore_password"/>
            <implementation type="JKS"/>
            <file path="your_keystore.jks" relative-to="jboss.server.config.dir"/>
        </key-store>
    </key-stores>
    <key-managers>
        <key-manager name="httpsKM" key-store="httpsKS">
            <credential-reference clear-text="your_keystore_password"/>
        </key-manager>
    </key-managers>
    <server-ssl-contexts>
        <server-ssl-context name="httpsSSC" key-manager="httpsKM" protocols="TLSv1.3 TLSv1.2"/>
    </server-ssl-contexts>
</tls>

Et l’écouteur correspondant dans le sous-système undertow référence ce ssl-context :

<https-listener name="https" socket-binding="https" ssl-context="httpsSSC" enable-http2="true"/>

Limiter les protocols à TLS 1.3 et TLS 1.2 désactive les protocoles obsolètes TLS 1.0 et 1.1. Le port HTTPS par défaut est 8443; associez-le au port 443 avec un équilibreur de charge ou une redirection de port si vous avez besoin du port standard.

Étape 5 : Redémarrez JBoss

Si vous avez modifié standalone.xml manuellement, redémarrez le serveur afin qu’il charge la nouvelle configuration. Si vous avez utilisé les batchs CLI ci-dessus, les modifications s’appliquent immédiatement, mais un rechargement confirme un démarrage propre :

jboss-cli.sh --connect --command=:reload

Surveillez le journal du serveur pour détecter d’éventuelles erreurs SSL ou Elytron lors du démarrage. Une fois qu’il démarre sans erreur, votre certificat SSL est installé sur JBoss.

Testez votre installation SSL

Après l’installation, confirmez que le certificat et la chaîne sont correctement servis. Ouvrez votre site en HTTPS (par exemple https://www.yourdomain.com:8443) et vérifiez le cadenas, ou lancez une analyse externe avec notre SSL Checker pour obtenir un rapport complet sur le certificat, la chaîne et la prise en charge des protocoles. Vous pouvez également vérifier depuis la ligne de commande :

echo | openssl s_client -connect yourdomain.com:8443 -servername yourdomain.com 2>/dev/null | openssl x509 -noout -issuer -dates

Cela affiche l’émetteur et les dates de validité du certificat que JBoss sert. Si l’émetteur est votre CA (et non une entrée autosignée), la réponse a été correctement importée.

Questions fréquemment posées