I’ve been working my way through some security topics along WildFly 8 and stumbled upon some configuration options, that are not very well documented. One of them is the TLS/SSL configuration for the new web-subsystem Undertow. There’s plenty of documentation for the older web-subsystem and it is indeed still available to use, but here is the short how-to configure it the new way.
Generate a keystore and self-signed certificate
First step is to generate a certificate. In this case, it’s going to be a self signed one, which is enough to show how to configure everything. I’m going to use the plain Java way of doing it, so all you need is the JRE keytool. Java Keytool is a key and certificate management utility. It allows users to manage their own public/private key pairs and certificates. It also allows users to cache certificates. Java Keytool stores the keys and certificates in what is called a keystore. By default the Java keystore is implemented as a file. It protects private keys with a password. A Keytool keystore contains the private key and any certificates necessary to complete a chain of trust and establish the trustworthiness of the primary certificate.
Please keep in mind, that an SSL certificate serves two essential purposes: distributing the public key and verifying the identity of the server so users know they aren’t sending their information to the wrong server. It can only properly verify the identity of the server when it is signed by a trusted third party. A self signed certificate is a certificate that is signed by itself rather than a trusted authority.
Switch to a command-line and execute the following command which has some defaults set, and also prompts you to enter some more information.
$>keytool -genkey -alias mycert -keyalg RSA -sigalg MD5withRSA -keystore my.jks -storepass secret -keypass secret -validity 9999 What is your first and last name? [Unknown]: localhost What is the name of your organizational unit? [Unknown]: myfear What is the name of your organization? [Unknown]: eisele.net What is the name of your City or Locality? [Unknown]: Grasbrun What is the name of your State or Province? [Unknown]: Bavaria What is the two-letter country code for this unit? [Unknown]: ME Is CN=localhost, OU=myfear, O=eisele.net, L=Grasbrun, ST=Bavaria, C=ME correct? [no]: yes
Make sure to put your desired “hostname” into the “first and last name” field, otherwise you might run into issues while permanently accepting this certificate as an exception in some browsers. Chrome doesn’t have an issue with that though.
The command generates a my.jks file in the folder it is executed. Copy this to your WildFly config directory (%JBOSS_HOME%/standalone/config).
Configure The Additional WildFly Security Realm
The next step is to configure the new keystore as a server identity for ssl in the WildFly security-realms section of the standalone.xml (if you’re using -ha or other versions, edit those).
<management> <security-realms> <!-- ... --> <security-realm name="UndertowRealm"> <server-identities> <ssl> <keystore path="my.keystore" relative-to="jboss.server.config.dir" keystore-password="secret" alias="mycert" key-password="secret"/> </ssl> </server-identities> </security-realm> <!-- ... -->
And you’re ready for the next step.
Configure Undertow Subsystem for SSL
If you’re running with the default-server, add the https-listener to the undertow subsystem:
<subsystem xmlns="urn:jboss:domain:undertow:1.2"> <!-- ... --> <server name="default-server"> <!-- ... --> <https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/> <! -- ... -->
That’s it, now you’re ready to connect to the ssl port of your instance https://localhost:8443/. Note, that you get the privacy error (compare screenshot). If you need to use a fully signed certificate you mostly get a PEM file from the cert authority. In this case, you need to import this into the keystore. This stackoverflow thread may help you with that.
| Reference: | SSL with WildFly 8 and Undertow from our JCG partner Markus Eisele at the Enterprise Software Development with Java blog. |
