Hawkular - Securing Communications

Securing Communications

Please follow the instructions in the Quick Start document for the server itself, followed by the instructions below.

These instructions will tell you how to prepare the Hawkular Server to support secure communications via SSL/https. Following these instructions will enable browsers to access the Hawkular GUI over https as well as allowing the UI clients and feeds to access the Hawkular Server over "wss" (WebSockets over SSL).

Generating A Self-Signed Certificate (if needed)

If you do not have a keystore with your own private key/certificate, you can generate a self-signed cert. Since it will be assumed you are doing this for testing and demo purposes only, the below instructions will generate a valid certificate for your localhost only (see "CN=localhost" and the Subject Alternative Name of 127.0.0.1):

keytool -genkey -keystore hawkular.keystore -alias hawkular -dname "CN=localhost" -keyalg RSA -storepass hawkular -keypass hawkular -validity 36500 -ext san=ip:127.0.0.1

Make sure your new "hawkular.keystore" is copied to your Hawkular Server’s standalone/configuration directory.

Make Your Certificate Trusted

If you created your own self-signed certificate (or you have one signed by your own CA that your Java VM does not yet know about or trust), you will need to tell your Java VM that it can trust it. You do this by adding your certificate to the "cacerts" file.

First, export your certificate from your keystore file (hawkular.keystore if you followed instructions in step 1) into a file called hawkular.cert:

keytool -export -alias hawkular -file hawkular.cert -storepass hawkular -keystore hawkular.keystore

Now import your certificate into your Java’s CA certificates file - this makes your certificate trusted by your Java apps (note this assumes the default password of "changeit" in your Java install’s cacerts file - obviously, you’ll want to use the correct password if you changed it):

keytool -import -keystore $JAVA_HOME/jre/lib/security/cacerts -alias hawkular -storepass changeit -file hawkular.cert

You can examine your certificate and answer the prompt to indicate you do trust that certificate. If you want to automate this, you can pass in the -noprompt command line argument and it will automatically add the certificate without asking you for confirmation.

Configure Hawkular Server

Now that your keystore is generated and trusted, you have to tell the Hawkular Server to use your keystore when using SSL.

First, you must add two security-realm elements in standalone/configuration/standalone.xml. Note that we create one for use by the Undertow web connector and one for use by the Hawkular Agent that comes with the Hawkular Server.

<management>
  <security-realms>
    <security-realm name="UndertowRealm">
      <server-identities>
        <ssl>
          <keystore path="hawkular.keystore" relative-to="jboss.server.config.dir" keystore-password="hawkular" key-password="hawkular" alias="hawkular" />
        </ssl>
      </server-identities>
    </security-realm>
    <security-realm name="HawkularAgentRealm">
      <authentication>
        <truststore path="hawkular.keystore" relative-to="jboss.server.config.dir" keystore-password="hawkular" />
      </authentication>
    </security-realm>

Next add an HTTPS listener to standalone.xml, using your new security-realm that is configured with your new keystore:

  <subsystem xmlns="urn:jboss:domain:undertow:2.0" statistics-enabled="true">
  ...
    <server name="default-server">
      <https-listener name="https" security-realm="UndertowRealm" socket-binding="https"/>

Finally, turn on SSL in the agent by adding these two attributes to the <storage-adapter> element in standalone.xml:

  <storage-adapter use-ssl="true" security-realm="HawkularAgentRealm" ... />

Ready

You are now ready to access the Hawkular Server via "https://localhost:8443". The agent and any other feeds that want to send data to the Hawkular Server can do so over "wss://localhost:8443".

More Details

For more details, see the Keycloak documentation here: http://keycloak.github.io/docs/userguide/html_single/index.html#ssl_modes

Securing Communications Between Agent and a Managed WildFly Server

The above instructions tell you how to secure your Hawkular Server and how the Hawkular WildFly Agent can talk to the Hawkular Server over that secured communications channel. But this does nothing to secure the communications between the agent and the remote WildFly Servers the agent is monitoring. To secure this communications channel, the following must be performed.

Securing the Management Interface of the Managed WildFly Server

You first must ensure that the managed WildFly Server provides a secure management interface. You do this by changing its configured management interface. In the managed WildFly Server standalone.xml:

<management-interfaces>
  <http-interface http-upgrade-enabled="true" security-realm="ManagementRealm">
    <socket-binding https="management-https">
  </http-interface>
</management-interfaces>

This is essentially the same as the out-of-box WildFly management interface except for two changes:

The socket-binding now has an attribute "https" to denote the management interface must be accessed over HTTPS.
The socket-binding’s https attribute has a value of "management-https" (as opposed to management-http) to denote the port that the management interface should listen to is that of the secure HTTPS port. "management-https" is a defined <socket-binding> that you will find out-of-box in the <socket-binding-group> section.

The next thing you must do is provide a keystore for the ManagementRealm to use now that you are requiring SSL. This is the same kind of configuration that was performed above when securing the Hawkular Server, but instead of creating a new security-realm, you normally only have to add a <server-identities> section to the already existing, out-of-box, security-realm called "ManagementRealm". You need to obtain a keystore with your managed WildFly Server’s certificate, put it in the managed WildFly Server’s configuration directory, and add a server-identities element to the ManagementRealm security-realm in standalone.xml:

<management>
  <security-realms>
    <security-realm name="ManagementRealm">
      ...
      <server-identities>
        <ssl>
          <keystore path="your-wildfly.keystore" relative-to="jboss.server.config.dir" keystore-password="your-password" key-password="your-password" alias="your-alias" />
        </ssl>
      </server-identities>
    </security-realm>

At this point, your managed WildFly Server will only accept secure communications over its management interface.

Configuring the Agent For Secure Communications to Managed WildFly Server

The above only configured the managed WildFly Server itself. You then have to tell the Hawkular WildFly Agent to talk to that managed server over the secure interface. You do this by first creating a security-realm in the agent’s WildFly Server container with the managed WildFly Server’s certificate in the given keystore (remember this is now editing the agent’s WildFly Server standalone.xml):

<management>
  <security-realms>
    <security-realm name="ManagedWildFlyRealm">
      <authentication>
        <truststore path="your-wildfly.keystore" relative-to="jboss.server.config.dir" keystore-password="your-password"/>
      </authentication>
    </security-realm>

Now tell the agent to talk to the managed WildFly Server securely by setting the "use-ssl" and "security-realm" attributes in the appropriate <remote-dmr> server entry in standalone.xml:

<managed-servers>
  <remote-dmr use-ssl="true" security-realm="ManagedWildFlyRealm" ... />

At this point, the agent will be able to talk to the managed WildFly Server over the secure management interface.