Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Enabling two-way SSL/TLS for management interfaces and applications

SSL/TLS, or transport layer security (TLS), is a certificates-based security protocol that is used to secure the data transfer between two entities communicating over a network. Use two-way SSL/TLS when you want the server to connect only with trusted clients.

Two-way SSL/TLS provides the following security functions:

Authentication
In one-way SSL/TLS, the server presents its certificate to a client to authenticate itself. In two-way SSL/TLS, the client also presents its certificate to the server for the server to authenticate the client. Two-way SSL/TLS, therefore, is also called mutual authentication.
Confidentiality
The data transferred between the client and the server is encrypted.
Data integrity
The TLS protocol provides data integrity with secure hash functions, which are used for message authentication code (MAC) computations. You can enforce specific algorithms and hash functions for the connections using the cipher-suite-filter and cipher-suite-names attributes of the SSL context resources.

For more information, see server-ssl-context attributes.

You can secure both JBoss EAP management interfaces and deployed applications by using two-way SSL/TLS.

To secure management interfaces with two-way SSL/TLS, use the following procedures:

To secure applications deployed on JBoss EAP with two-way SSL/TLS, use the following procedures:

You can configure certificate revocation checks by following the procedures in Configuring certificate revocation checks in Elytron.

2.1. Generating client certificates

Generate self-signed client certificates using the keytool command, in the CLI, for the purpose of testing and development of a two-way SSL/TLS configuration.

Important

Do not use self-signed certificates in a production environment. Use only the certificates signed by a certificate authority (CA).

Procedure

  1. Generate a client certificate.

    Syntax

    Copy to Clipboard Toggle word wrap 
    $ keytool -genkeypair -alias <keystore_alias> -keyalg <algorithm> -keysize <key_size> -validity <validity_in_days> -keystore <keystore_name> -dname "<distinguished_name>" -keypass <private_key_password> -storepass <keystore_password>

    Example

    Copy to Clipboard Toggle word wrap 
    $ keytool -genkeypair -alias exampleClientKeyStore -keyalg RSA -keysize 2048 -validity 365 -keystore exampleclient.keystore.pkcs12 -dname "CN=client" -keypass secret -storepass secret

  2. Export the client certificate to a file.

    Syntax

    Copy to Clipboard Toggle word wrap 
    $ keytool -exportcert  -keystore <keystore_name> -alias <keystore_alias> -keypass <private_key_password> -storepass <keystore_password> -file <file_path>

    Example

    Copy to Clipboard Toggle word wrap 
    $ keytool -exportcert  -keystore exampleclient.keystore.pkcs12 -alias exampleClientKeyStore -keypass secret -storepass secret -file EAP_HOME/standalone/configuration/client.cer

Certificate stored in file <EAP_HOME/standalone/configuration/client.cer>

You can now use the generated client certificate to configure a server trust store and a trust manager in a server. For more information, see Configuring a trust store and a trust manager for client certificates.

2.2. Configuring a trust store and a trust manager for client certificates

Configure a trust store with the client certificate and a trust manager with a reference to the trust store to verify the client certificate during the TLS handshake.

Prerequisites

Procedure

  1. Configure a trust store with a client certificate by using the management CLI.

    1. Create a server trust store to store the client certificate to trust.

      Syntax

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=<server_trust_store_name>:add(path=<path_to_server_trust_store_file>,credential-reference={<password>})

      Example

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=exampleServerTrustStore:add(path=exampleTLSServer.truststore,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret})
{"outcome" => "success"}

    2. Import the client certificate to the server trust store by specifying the client certificate alias. Only the clients that present a certificate that the server’s trust store trusts can connect to the server.

      Note

      If you are configuring two-way SSL/TLS by using a self-signed certificate, set validate to false because no chain of trust exists for the certificate.

      If you are configuring two-way SSL/TLS in a production environment by using certificates signed by a CA, set validate to true.

      Syntax

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=<server_trust_store_name>:import-certificate(alias=<alias>,path=<certificate_file>,credential-reference={<password>},trust-cacerts=<true_or_false>,validate=<true_false>)

      Example

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=exampleServerTrustStore:import-certificate(alias=client,path=client.cer,relative-to=jboss.server.config.dir,credential-reference={clear-text=serverTrustSecret},trust-cacerts=true,validate=false)
{"outcome" => "success"}

    3. Export the client certificate to a trust store file.

      Syntax

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=<server_trust_store_name>:store()

      Example

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=exampleServerTrustStore:store()
{
    "outcome" => "success",
    "result" => undefined
}

  2. Configure a trust manager to verify the client certificate during the TLS handshake.

    Syntax

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/trust-manager=<trust_manager_name>:add(key-store=<server_trust_store_name>)

    Example

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/trust-manager=exampleTLSTrustManager:add(key-store=exampleServerTrustStore)
{"outcome" => "success"}

The client certificate in the configured trust store is used to verify the certificate that a client presents during TLS handshake with the server.

Additional resources

2.3. Configuring a server certificate for two-way SSL/TLS

Configure a server certificate, which will be presented to clients during the TLS handshake.

Prerequisites

  • JBoss EAP is running.

Procedure

  1. Generate a self-signed server certificate to use for testing and development purposes. If you have obtained a certificate from a certificate authority (CA), skip this step.

    Important

    Do not use self-signed certificates in a production environment. Use only the certificates signed by a certificate authority (CA).

    1. Create a key store to store server certificate.

      Syntax

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=<key_store_name>:add(path=<path>,credential-reference={<password>},type=<key_store_type>)

      Example

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=exampleServerKeyStore:add(path=server.keystore.pkcs12,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=PKCS12)
{"outcome" => "success"}

    2. Generate a server certificate in the key store.

      Syntax

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=<key_store_name>:generate-key-pair(alias=<alias>,algorithm=<algorithm>,key-size=<key_size>,validity=<validaity_in_days>,credential-reference={<password>},distinguished-name="<distinguished_name_in_certificate>")

      Example

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=exampleServerKeyStore:generate-key-pair(alias=localhost,algorithm=RSA,key-size=2048,validity=365,credential-reference={clear-text=secret},distinguished-name="CN=localhost")
{"outcome" => "success"}

    3. Store the key store to a file.

      Syntax

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=<key_store_name>:store()

      Example

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=exampleServerKeyStore:store()
{
    "outcome" => "success",
    "result" => undefined
}

    4. Export the server certificate.

      Syntax

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=<key_store_name>:export-certificate(alias=<alias>,path=<path_to_certificate>,pem=true)

      Example

      Copy to Clipboard Toggle word wrap 
      /subsystem=elytron/key-store=exampleServerKeyStore:export-certificate(alias=localhost,path=server.cer,pem=true,relative-to=jboss.server.config.dir)
{"outcome" => "success"}

  2. Create a key manager referencing the server key store.

    Syntax

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/key-manager=<key_manager_name>:add(credential-reference={<password>},key-store=<key_store_name>)

    Example

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/key-manager=exampleServerKeyManager:add(credential-reference={clear-text=secret},key-store=exampleServerKeyStore)
{"outcome" => "success"}

    The server presents this certificate to the client when SSL/TLS is enabled.

  3. Import the server certificate to the client’s trust store so that the client can verify the server certificate during SSL handshake.

    Syntax

    Copy to Clipboard Toggle word wrap 
    $ keytool -import -file <server_certificate_file> -alias <alias> -keystore <client_trust_store_file> -storepass <password>

    Example

    Copy to Clipboard Toggle word wrap 
    $ keytool -import -file EAP_HOME/standalone/configuration/server.cer -alias server -keystore client.truststore.p12 -storepass secret

Owner: CN=localhost
Issuer: CN=localhost
Serial number: 52679016fbb54f46
Valid from: Fri Sep 30 18:25:29 IST 2022 until: Sat Sep 30 18:25:29 IST 2023
Certificate fingerprints:
	 SHA1: 4B:68:24:9E:2A:2D:01:4E:23:69:94:C8:9A:1C:8F:A5:D4:27:CB:98
	 SHA256: C0:AF:74:12:90:66:25:B2:65:4E:6B:4B:89:81:2D:6B:D5:2A:F4:04:BC:85:DA:1C:AB:26:6D:57:9F:9F:EE:15
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 1024-bit RSA key (disabled)
Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 59 13 DC 6A 81 B9 27 18   6E 72 17 0E 67 FC 9F 8F  Y..j..'.nr..g...
0010: 04 01 74 8F                                        ..t.
]
]


Warning:
The input uses a 1024-bit RSA key which is considered a security risk and is disabled.

Trust this certificate? [no]:

    Enter yes. You get the following output:

    Copy to Clipboard Toggle word wrap 
    Certificate was added to keystore

Next steps

Additional resources

2.4. Configuring SSL context to secure JBoss EAP management interfaces with SSL/TLS

Secure the JBoss EAP management interfaces with two-way SSL/TLS so that only the clients that present a certificate trusted by the server can connect to the server’s management interfaces.

Prerequisites

Procedure

  1. Configure a server SSL context to enable two-way SSL.

    Syntax

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/server-ssl-context=<server_ssl_context_name>:add(key-manager=<key_manager_name>,trust-manager=<trust_manager_name>,need-client-auth=true)

    Example

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/server-ssl-context=exampleServerSSLContext:add(key-manager=exampleServerKeyManager,trust-manager=exampleTLSTrustManager,need-client-auth=true)
{"outcome" => "success"}

    By default, the SSL context uses TLSv1.2. You can configure the protocols attribute to use TLSv1.3 as follows:

    Syntax

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/server-ssl-context=<server-ssl-context-name>:add(key-manager=<key_manager_name>,trust-manager=<trust_manager_name>,need-client-auth=true,protocols=[TLSv1.3])

  2. Add a reference to the SSLContext to use for the http management interface.

    Syntax

    Copy to Clipboard Toggle word wrap 
    /core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=<server_ssl_context_name>)

    Example

    Copy to Clipboard Toggle word wrap 
    /core-service=management/management-interface=http-interface:write-attribute(name=ssl-context,value=exampleServerSSLContext)
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}

  3. Define the socket binding configuration to use for the HTTPS management interface’s socket.

    Syntax

    Copy to Clipboard Toggle word wrap 
    /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=<socket_binding>)

    Example

    Copy to Clipboard Toggle word wrap 
    /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}

  4. Reload the server.

    Copy to Clipboard Toggle word wrap 
    reload

...
Accept certificate? [N]o, [T]emporarily, [P]ermanently :

    Enter T or P to accept the certificate provided by the server either temporarily or permanently.

    The management CLI disconnects because it expects a client certificate to be presented.

Verification

  • Verify that management console is protected.

    1. Verify using the CLI:

      Syntax

      Copy to Clipboard Toggle word wrap 
      $ curl --verbose --location --cacert <server_certificate> --cert <client_keystore>:<password> --cert-type P12 https://localhost:9993

      Example

      Copy to Clipboard Toggle word wrap 
      $ curl --verbose --location --cacert server.cer --cert EAP_HOME/standalone/configuration/exampleclient.keystore.pkcs12:secret --cert-type P12 https://localhost:9993
...
< HTTP/1.1 200 OK
...

    2. Verify using a browser.

      1. Import the client certificate into your browser. The example certificate created in the Generating client certificates procedure is called exampleclient.keystore.pkcs12 and the example password to import it is secret.

        Refer to your browser’s documentation for information about importing certificates to the browser.

      2. Access https://localhost:9993 in a browser.

        The browser prompts you to present a certificate to identify with the server.

      3. Choose the certificate you imported to the browser. For example, exampleclient.keystore.pkcs12.

        If you use a self-signed certificate, the browser presents a warning that the certificate presented by the server is unknown.

      4. Inspect the certificate and verify that the fingerprints shown in your browser match the fingerprints of the certificate in your keystore. You can view the certificate in a keystore with the following command:

        Syntax

        Copy to Clipboard Toggle word wrap 
        /subsystem=elytron/key-store=<server_keystore_name>:read-alias(alias=<alias>)

        Example

        Copy to Clipboard Toggle word wrap 
        /subsystem=elytron/key-store=exampleServerKeyStore:read-alias(alias=localhost)
...
"sha-1-digest" => "5e:3e:ad:c8:df:d7:f6:63:38:05:e2:a3:a7:31:07:82:c8:c8:94:47",
"sha-256-digest" => "11:b6:8f:00:42:e1:7f:6c:16:ef:db:08:5e:13:d9:b8:16:6e:a0:3c:2e:d4:e5:fd:cb:53:90:88:d2:9c:b1:99",

    After you accept the server certificate, you are prompted for login credentials. You can login using user credentials of existing JBoss EAP users.

  • Verify that management CLI is protected.

    • Create the file wildfly-config.xml with the following content:

      Example

      Copy to Clipboard Toggle word wrap 
      <?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:client:1.7">
        <key-stores>
            <key-store name="truststore" type="PKCS12">
                <file name="${path_to_client_truststore}/client.truststore.p12"/>
                <key-store-clear-password password="secret" />
            </key-store>
            <key-store name="keystore" type="PKCS12">
                <file name="${path_to_client_truststore}/exampleclient.keystore.pkcs12"/>
                <key-store-clear-password password="secret" />
            </key-store>
        </key-stores>
        <ssl-contexts>
            <ssl-context name="client-context">
                <trust-store key-store-name="truststore"/>
                <key-store-ssl-certificate key-store-name="keystore">
                    <key-store-clear-password password="secret" />
                </key-store-ssl-certificate>
                <providers>
                    <global/>
                </providers>
            </ssl-context>
        </ssl-contexts>
        <ssl-context-rules>
            <rule use-ssl-context="client-context" />
        </ssl-context-rules>
    </authentication-client>
</configuration>

      Note

      You can use masked passwords in the key-store-clear-password element, in place of clear text, for obfuscation.

    • Access management CLI by presenting the client certificate.

      Copy to Clipboard Toggle word wrap 
      $ ./jboss-cli.sh --controller=remote+https://127.0.0.1:9993 -Dwildfly.config.url=/path/to/wildfly-config.xml --connect

Both the clients: the client’s web browser, and management CLI, trust the server’s certificate, and the server trusts both clients. The communication between the client and server is over SSL/TLS.

Additional resources

2.5. Configuring server-ssl-context to secure applications deployed on JBoss EAP with SSL/TLS

Elytron provides a default server-ssl-context called applicationSSC, which you can use to configure SSL/TLS. Alternately, you can create your own SSL context in Elytron. The following procedure demonstrates using the default SSL context - applicationSSC, to configure SSL/TLS for applications.

Prerequisites

Procedure

  1. Configure the default server SSL context to enable two-way SSL.

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=need-client-auth,value=true)
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}

    By default, the SSL context uses TLSv1.2. You can configure the protocols attribute to use TLSv1.3 as follows:

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=protocols,value=[TLSv1.3])

  2. Configure a trust manager for the server SSL context.

    Syntax

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=trust-manager,value=<server_trust_manager>)

    Example

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=trust-manager,value=exampleTLSTrustManager)
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}

  3. Configure a key manager of the server SSL context.

    Syntax

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=key-manager,value=<key_manager_name>)

    Example

    Copy to Clipboard Toggle word wrap 
    /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=key-manager,value=exampleServerKeyManager)
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}

  4. Reload the server.

    Copy to Clipboard Toggle word wrap 
    reload

Verification

  • Verify that you can access the JBoss EAP welcome page.

    1. Verify using the CLI:

      Syntax

      Copy to Clipboard Toggle word wrap 
      $ curl --verbose --location --cacert <server_certificate> --cert <client_keystore>:<password> --cert-type P12 https://localhost:8443

      Example

      Copy to Clipboard Toggle word wrap 
      $ curl --verbose --location --cacert server.cer --cert exampleclient.keystore.pkcs12:secret --cert-type P12 https://localhost:8443
...
<h3>Your Red Hat JBoss Enterprise Application Platform is running.</h3>
...

    2. Verify using a browser.

      1. Import the client certificate into your browser. The example certificate created in the Generating client certificates procedure is called exampleclient.keystore.pkcs12 and the example password to import it is secret.

        Refer to your browser’s documentation for information about importing certificates to the browser.

      2. Navigate to https://localhost:8443 in a browser.

        The browser prompts you to present a certificate to identify with the server.

      3. Choose the certificate you imported to the browser. For example, exampleclient.keystore.pkcs12.

        If you use a self-signed certificate, the browser presents a warning that the certificate presented by the server is unknown.

      4. Inspect the certificate and verify that the fingerprints shown in your browser match the fingerprints of the certificate in your keystore. You can view the certificate in a keystore with the following command:

        Syntax

        Copy to Clipboard Toggle word wrap 
        /subsystem=elytron/key-store=<server_keystore_name>:read-alias(alias=<alias>)

        Example

        Copy to Clipboard Toggle word wrap 
        /subsystem=elytron/key-store=exampleServerKeyStore:read-alias(alias=localhost)
...
"sha-1-digest" => "5e:3e:ad:c8:df:d7:f6:63:38:05:e2:a3:a7:31:07:82:c8:c8:94:47",
"sha-256-digest" => "11:b6:8f:00:42:e1:7f:6c:16:ef:db:08:5e:13:d9:b8:16:6e:a0:3c:2e:d4:e5:fd:cb:53:90:88:d2:9c:b1:99",

    After you accept the server certificate, you can access JBoss EAP welcome page.

Two-way SSL/TLS is now configured for applications.

Additional resources

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat, Inc.