How to Install an SSL Certificate on JBoss Server

This tutorial shows you how to install an SSL certificate on JBoss EAP and WildFly using keytool and the Elytron security subsystem. If you do not have your certificate files yet, the first section covers generating a CSR.

Note on versions: modern JBoss EAP (7.1 and later, including EAP 8) and recent WildFly releases configure HTTPS through the elytron subsystem wired into the Undertow https-listener. The old security-realm method and the legacy Tomcat or Jetty connectors are deprecated, so this guide uses the current approach.

We also recorded a video that walks you through the entire process. You can watch the video, read the instructions, or do both. You can watch the video below.

Generate a CSR code on JBoss

A CSR (Certificate Signing Request) is a block of encoded text you send to the Certificate Authority (CA) when you order a certificate. It carries your domain and organization details, which the CA uses to validate the request. Generating the CSR also creates the matching private key, which stays on your server and is required during installation.

You have two options:

• Use our CSR Generator to create the CSR automatically.
• Follow our step-by-step tutorial on how to generate a CSR on JBoss.

On JBoss the CSR is generated with keytool from a .jks or .p12 keystore. Note the alias and keystore name you choose now: you will import the signed certificate back into that exact alias later. Submit the CSR to the CA during your order, and once the certificate is issued, continue with the installation below.

Install an SSL certificate on JBoss Server

Step 1: Prepare your certificate files

After validation, the CA emails your certificate files, usually in a ZIP archive. Extract it. You should have:

• Your primary certificate (a .crt, .cer, or .pem file).
• The intermediate certificates, often delivered as a .ca-bundle file (the CA bundle). Some CAs include the root as well.
• The keystore (.jks or .p12) you created with the CSR, which holds your private key under the alias you chose when generating the CSR.

Keep these files together, and copy them to the server, for example into the JBoss configuration directory ($JBOSS_HOME/standalone/configuration/). If a file opens as text, you can confirm it contains the expected BEGIN CERTIFICATE and END CERTIFICATE lines.

Step 2: Import the CA chain into the keystore

Import the intermediate (and root, if provided) certificates first so keytool can build a complete chain of trust. Use the same keystore that holds your private key, and give each CA certificate its own 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

If your CA shipped a single .ca-bundle file, import it under one alias (for example -alias intermediate). When prompted, enter the keystore password and confirm trust. These entries are trusted-certificate entries, not key entries, so they do not affect your private key.

Step 3: Import the signed certificate into your key alias

Now import your signed certificate (the reply from the CA) into the exact alias you used when generating the CSR. Because that alias already holds the private key, keytool treats this as a certificate reply and replaces the temporary self-signed certificate with the CA-signed chain, keeping the key intact:

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

Replace your_csr_alias with the alias you used when generating the CSR and your_keystore.jks with your keystore. On success keytool prints Certificate reply was installed in keystore.

Important: do not invent a new alias here. Importing the reply under a new alias creates a trusted-certificate entry with no private key, the chain is lost, and the server cannot complete the TLS handshake. If you see Failed to establish chain from reply, it means the intermediate or root from Step 2 is missing from the keystore.

You can verify the result, the alias should now show a certificate chain of length greater than 1:

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

Step 4: Configure HTTPS in the Elytron subsystem

Place the keystore in $JBOSS_HOME/standalone/configuration/, then define an Elytron key-store, key-manager, and server-ssl-context. The fastest way is the management CLI. Start the server, connect with jboss-cli.sh --connect, and run a batch so the changes apply together:

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

Next, point the Undertow https-listener at the new ssl-context. Undertow cannot reference a legacy security-realm and an Elytron ssl-context at the same time, so remove the old reference and set the new one in a single 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

If you prefer to edit standalone.xml directly (with the server stopped), the equivalent configuration looks like this inside the elytron subsystem:

<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>

And the matching listener in the undertow subsystem references that ssl-context:

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

Limiting protocols to TLS 1.3 and TLS 1.2 disables the obsolete TLS 1.0 and 1.1. The default HTTPS port is 8443; map it to 443 with a load balancer or a port redirect if you need the standard port.

Step 5: Restart JBoss

If you edited standalone.xml by hand, restart the server so it loads the new configuration. If you used the CLI batches above, the changes apply immediately, but a reload confirms a clean startup:

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

Watch the server log for SSL or Elytron errors during startup. Once it boots cleanly, your SSL certificate is installed on JBoss.

Test your SSL installation

After installation, confirm the certificate and chain are served correctly. Open your site over HTTPS (for example https://www.yourdomain.com:8443) and check the padlock, or run an external scan with our SSL Checker for a full report on the certificate, chain, and protocol support. You can also check from the command line:

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

This prints the issuer and validity dates of the certificate JBoss is serving. If the issuer is your CA (not a self-signed entry), the reply imported correctly.

Frequently Asked Questions