Securing the Web Console

You can configure the Fuse ESB Enterprise Web console to use SSL/TLS security by adding the relevant configuration properties to the etc/org.ops4j.pax.web.cfg configuration file.

Prerequisites

The Fuse ESB Enterprise Web console is not enabled by default. You can install the web console feature into OSGi by entering the following console command:

karaf@root> features:install webconsole

Create X.509 certificate and private key

Before you can enable SSL, you must create an X.509 certificate and private key for the Web console. The certificate and private key must be in Java keystore format. For details of how to create a signed certificate and private key, see Appendix A.

If you want to run a quick demonstration of SSL/TLS security, you could use a demonstration certificate from one of the examples (see Install sample keystore files).

Enabling SSL/TLS

To enable SSL/TLS:

Open etc/org.ops4j.pax.web.cfg in a text editor.
Disable the insecure HTTP port by adding the org.osgi.service.http.enabled and setting it to false as shown in Example 14.
Example 14. Pax Web Property for Disabling the HTTP Port
```
org.osgi.service.http.enabled=false
```
Enable the secure HTTPS port by adding the org.osgi.service.http.secure.enabled and setting it to true as shown in Example 15.
Example 15. Pax Web Property for Enabling the HTTPS Port
```
org.osgi.service.http.secure.enabled=true
```
Specify the port used for connecting over HTTPS by adding the org.osgi.service.http.port.secure and setting it to an available port as shown in Example 16.
Example 16. Pax Web Property for Enabling the HTTPS Port
```
org.osgi.service.http.port.secure=8183
```
Configure the keystore used to hold the X.509 certificates.
1. Specify the location of the keystore by adding the org.ops4j.pax.web.ssl.keystore.
2. Specify the type of keystore used by adding the org.ops4j.pax.web.ssl.keystore.type and setting it to JKS.
3. Specify the password for unlocking the Java keystore by adding the org.ops4j.pax.web.ssl.password property.
4. Specify the password for decrypting the private key by adding the org.ops4j.pax.web.ssl.keypassword property.
  Tip
  This is typically the same as the password used to unlock the keystore.
5. Specify if certificate-based client authentication at the server is wanted by adding the org.ops4j.pax.web.ssl.clientauthwanted property.
  When set to true the server will request that the client send an X.509 certificate during the SSL handshake.
6. Specify if certificate-based client authentication at the server is required by adding the org.ops4j.pax.web.ssl.clientauthneeded property.
  When set to true an exception is thrown if the client does not present a valid X.509 certificate during the SSL handshake.

Example

Example 17 shows the Pax Web configuration for a server whose X.509 certificate and private key are in the keystore cherry.jks. The keystore has the store password password and the key password password.

Example 17. Configuration for Web Console to use SSL

# Configures the SMX Web Console to use SSL
org.osgi.service.http.enabled=false
org.osgi.service.http.port=8181

org.osgi.service.http.secure.enabled=true
org.osgi.service.http.port.secure=8183

org.ops4j.pax.web.ssl.keystore=etc/certs/cherry.jks
org.ops4j.pax.web.ssl.keystore.type=JKS
org.ops4j.pax.web.ssl.password=password
org.ops4j.pax.web.ssl.keypassword=password
org.ops4j.pax.web.ssl.clientauthwanted=false
org.ops4j.pax.web.ssl.clientauthneeded=false

SSL configuration properties

The following configuration properties are used to configure SSL/TLS:

org.ops4j.pax.web.ssl.keystore: The location of the Java keystore file on the file system. Relative paths are resolved relative to the KARAF_HOME environment variable (by default, the install directory).
org.ops4j.pax.web.ssl.keystore.type: The implementation of the keystore, which is normally JKS. (In principle, the JDK allows you to plug in a custom keystore implementation.)
org.ops4j.pax.web.ssl.password: The store password that unlocks the Java keystore file.
org.ops4j.pax.web.ssl.keypassword: The key password that decrypts the private key stored in the keystore (usually the same as the store password).
org.ops4j.pax.web.ssl.clientauthwanted: When true, during the SSL handshake, the secure socket requests the client to send an X.509 certificate. The client is not necessarily obliged to send the certificate, however.
org.ops4j.pax.web.ssl.clientauthneeded: When true, the SSL protocol throws an exception, if the client does not present a valid certificate during the SSL handshake.

Configuration reference

For the complete list of configuration properties supported by the Web console endpoint, see WebContainerConstants.

Connect to the secure Web console

After configuring the Web console and installing the webconsole feature, you should be able to open the Web console by browsing to the following URL:

https://localhost:8183/system/console

	Tip
	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 prompted to enter a username and a password. Log in with the username smx and the password smx.

Comments powered by Disqus

	Tip
	This is typically the same as the password used to unlock the keystore.