SupportConsoleDevelopersStart a trialContact

Chapter 3. Securing the Undertow HTTP Server

Abstract

You can configure the built-in Undertow HTTP server to use SSL/TLS security by editing the contents of the etc/undertow.xml configuration file. In particular, you can add SSL/TLS security to the Fuse Console in this way.

3.1. Undertow server

The Fuse container is pre-configured with an Undertow server, which acts as a general-purpose HTTP server and HTTP servlet container. Through a single HTTP port (by default, http://localhost:8181), the Undertow container can host multiple services, for example:

  • Fuse Console (by default, http://localhost:8181/hawtio)
  • Apache CXF Web services endpoints (if the host and port are left unspecified in the endpoint configuration)
  • Some Apache Camel endpoints

If you use the default Undertow server for all of your HTTP endpoints, you can conveniently add SSL/TLS security to these HTTP endpoints by following the steps described here.

3.2. Create X.509 certificate and private key

Before you can enable SSL/TLS on the Undertow server, you must create an X.509 certificate and private key, where the certificate and private key must be in Java keystore format (JKS format). For details of how to create a signed certificate and private key, see Appendix A, Managing Certificates.

3.3. Enabling SSL/TLS for Undertow in an Apache Karaf container

For the following procedure, it is assumed that you have already created a signed X.509 certificate and private key pair in the keystore file, alice.ks, with keystore password, StorePass, and key password, KeyPass.

To enable SSL/TLS for Undertow in a Karaf container:

  1. Make sure that the Pax Web server is configured to take its configuration from the etc/undertow.xml file. When you look at the contents of the etc/org.ops4j.pax.web.cfg file, you should see the following setting: 

    org.ops4j.pax.web.config.file=${karaf.etc}/undertow.xml

  2. Open the file, etc/org.ops4j.pax.web.cfg, in a text editor and add the following line: 

    org.osgi.service.http.port.secure=8443

    Save and close the file, etc/org.ops4j.pax.web.cfg.

  3. Open the file, etc/undertow.xml, in a text editor. The next steps assume you are working with the default undertow.xml file, unchanged since installation time.

  4. Search for the XML elements, http-listener and https-listener. Comment out the http-listener element (by enclosing it between <!-- and -->) and uncomment the https-listener element (spread over two lines). The edited fragment of XML should now look something like this: 

    <!-- HTTP(S) Listener references Socket Binding (and indirectly - Interfaces) -->
<!-- http-listener name="http" socket-binding="http" /> -->
<!-- verify-client: org.xnio.SslClientAuthMode.NOT_REQUESTED, org.xnio.SslClientAuthMode.REQUESTED, org.xnio.SslClientAuthMode.REQUIRED -->
<https-listener name="https" socket-binding="https"
        security-realm="https" verify-client="NOT_REQUESTED" />

  5. Search for the w:keystore element. By default, the w:keystore element is configured as follows: 

    <w:keystore path="${karaf.etc}/certs/server.keystore" provider="JKS" alias="server"
            keystore-password="secret" key-password="secret"
            generate-self-signed-certificate-host="localhost" />

    To install the alice certificate as the Undertow server’s certificate, modify the w:keystore element attributes as follows:

    • Set path to the absolute location of the alice.ks file on the file system.
    • Set provider to JKS.
    • Set alias to the alice certificate alias in the keystore.
    • Set keystore-password to the value of the password that unlocks the key store.
    • Set key-password to the value of the password that encrypts the alice private key.
    • Delete the generate-self-signed-certificate-host attribute setting.

  6. For example, after installing the alice.ks keystore, the modified w:keystore element would look something like this: 

    <w:keystore path="${karaf.etc}/certs/alice.ks" provider="JKS" alias="alice"
            keystore-password="StorePass" key-password="KeyPass" />

  7. Search for the <interface name="secure"> tag, which is used to specify the IP addresses the secure HTTPS port binds to. By default, this element is commented out, as follows: 

    <!--<interface name="secure">-->
    <!--<w:inet-address value="127.0.0.1" />-->
<!--</interface>-->

    Uncomment the element and customize the value attribute to specify the IP address which the HTTPS port binds to. For example, the wildcard value, 0.0.0.0, configures HTTPS to bind to all available IP addresses: 

    <interface name="secure">
    <w:inet-address value="0.0.0.0" />
</interface>

  8. Search for and uncomment the <socket-binding name="https" tag. When this tag is uncommented, it should look something like this: 

    <socket-binding name="https" interface="secure" port="${org.osgi.service.http.port.secure}" />
  9. Save and close the file, etc/undertow.xml.
  10. Restart the Fuse container, in order for the configuration changes to take effect.

3.4. Customizing allowed TLS protocols and cipher suites

You can customize the allowed TLS protocols and cipher suites by modifying the following attributes of the w:engine element in the etc/undertow.xml file:

enabled-cipher-suites
Specifies the list of allowed TLS/SSL cipher suites.
enabled-protocols

Specifies the list of allowed TLS/SSL protocols.

Warning

Do not enable SSL protocol versions, as they are vulnerable to attack. Use only TLS protocol versions.

For full details of the available protocols and cipher suites, consult the appropriate JVM documentation and security provider documentation. For example, for Java 8, see Java Cryptography Architecture Oracle Providers Documentation for JDK 8.

3.5. Connect to the secure console

After configuring SSL security for the Undertow server in the Pax Web configuration file, you should be able to open the Fuse Console by browsing to the following URL: 

https://localhost:8443/hawtio
Note

Remember to type the https: scheme, instead of http:, in this URL.

Initially, the browser will warn you that you are using an untrusted certificate. Skip this warning and you will be presented with the login screen for the Fuse Console.

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.

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.

© 2024 Red Hat, Inc.