Configuring HTTPS in Mule

In this blogpost I aim to clarify some concepts which will show how to configure an HTTPS client and server in Mule for SSL and two-way SSL (Mutual Authentication).

The following is an explanation of the roles both keystore and truststore play in HTTPS as well as how they are referred to in Mule.

Key Store (tls-key-store in Mule): A keystore contains private keys, and the certificates with their corresponding public/private keys. You only need this if Mule is exposing an HTTP endpoint (server) or the remote server requires client authentication. In Mule, this is defined with the ‘tls-key-store’ attribute on the HTTPS connector.

Trust Store (tls-server in Mule): used as a repository of CA (certificate authority) or simple certificates that the client should trust. Note: this is only required if the server we are connecting with, has a certificate which is signed by an authority not recognised in the java truststore or the certificate is self signed. In Mule, this is configured using the ‘tls-server’ attribute on the HTTPS connector.

Note: One main source of ambiguity in using the HTTPS connector is the use of tls-client, this is redundant (see JIRA MULE-5213) and is a known issue. This is not required to configure SSL or two-way SSL.

One-way SSL

For normal SSL, on the server connector we need a keystore where the servers’ certificate and private key reside. In this example we are using self signed certificates, therefore we need a trustore on the client side.

The following are server and client HTTPS connectors for normal SSL with self signed certificate on the server side:

<https:connector name="httpsServerConnector" doc:name="HTTP\HTTPS" validateConnections="true">
<https:tls-key-store path="server-keystore.jks" keyPassword="keypass" storePassword="keypass" />
</https:connector>

<https:connector name="httpsClientConnector" doc:name="HTTP\HTTPS" validateConnections="true">
<https:tls-server path="client-truststore.jks" storePassword="keypass"/>
</https:connector>

Two-way SSL (Mutual Authentication)

When configuring two-way SSL between the HTTPS client and server, in Mule we need to:

1) configure an HTTPS client connector with both client keystore and truststore. The client keystore shall contain the clients public certificate and private key. The client truststore shall contain the servers certificate.

2) configure the server connector with both server keystore and truststore as well as set ‘requireClientAuthentication’ to ‘true’ on the ‘tls-server’ (i.e. truststore) attribute. This shall force the server connector to check client requests in the trust store prior to granting access.

The server keystore shall contain the server’s public certificate and private key. The server truststore shall contain the client’s certificate.

In order to create the self signed certificate, trust store and key store for our HTTPS service, the java keytool was used. However the following graphical tool may prove handy.

The following is HTTPS server connector configuration for two-way SSL:

<https:connector name="httpsServerConnector" doc:name="HTTP\HTTPS" validateConnections="true">
<https:tls-key-store path="server-keystore.jks" keyPassword="keypass" storePassword="keypass" />
<https:tls-server path="server-truststore.jks"  requireClientAuthentication="true" storePassword="keypass" />
</https:connector>

and a flow with inbound HTTPS using the above connector:

<flow name="httpsServer" doc:name="httpsServer">
<https:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8083" connector-ref="httpsServerConnector" doc:name="HTTPS" />
<logger message="accessed https server successfully!" level="INFO" doc:name="Logger" />
</flow>

The following is HTTPS client connector configuration for two-way SSL:

<https:connector name="httpsClientConnector" doc:name="HTTP\HTTPS" validateConnections="true" >
<https:tls-key-store path="client-keystore.jks" keyPassword="keypass" storePassword="keypass" />
<https:tls-server path="client-truststore.jks" storePassword="keypass"/>
</https:connector>

Client flow, accepting HTTP requests and sending to HTTPS server:

<flow name="httpsClient" doc:name="httpsClient">
<http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="HTTP" path="test">
</http:inbound-endpoint>
<logger message="sending request from https client to https server..." level="INFO" doc:name="Logger" />
<https:outbound-endpoint exchange-pattern="request-response" host="localhost" port="8083" connector-ref="httpsClientConnector" doc:name="HTTP" />
</flow>