Implementing a

Cloudhub MuleSoft
HTTPS Endpoint
Michael Oakes
October 2016

HTTP and HTTPS Primer

HyperText Transfer Protocol (HTTP) is the World Wide Webs
underlying transfer protocol and determines how messages are
formatted and transmitted between a URL and the Browser.
Unfortunately regular HTTP communication is sent unencrypted and so can be vulnerable to unwanted access and
tampering.
A secure version of HTTP was introduced enabling messages
between the URL and the Browser to be encrypted - HyperText
Transfer Protocol Secure (HTTPS).

How does HTTPS work?

Message sent via HTTPS are encrypted after an initial handshake
process between the server and client, briefly outlined in the
following steps:
1. The server and client initially exchange messages to agree on
encryption method.
2. Server sends certificate with details about itself and a public
key to decrypt its data
3. Client sends message saying start encrypting
4. Server sends message saying start encrypting
5. All messages now encrypted using the agreed encryption

Certification Process
Company can request a certificate from an authorized Certification
Authority (CA).
Certification Authority validates the company requesting the certificate
and create and issue them a cryptographically signed certificate.
Company installs the issued and signed certificate on their server and is
sent out to connecting browsers as part of the HTTPS handshake process.
Browsers will use root certificates it is shipped with to verify that the
signed certificate sent by the server is correct and valid and can be
trusted.

What does HTTPS give us?

Encryption Messages between the server and the browser
are encrypted using the key provided by the server ensuring
they are both secure and have originated from the server untampered.
Identification Using certificates signed by an authorized
certification authority in the HTTPS handshake ensures that
we can authenticate and identify the originator of the
message.
Secure and trusted end to end communication.

Mule Cloudhub HTTPS Endpoints

For the same reasons as we would websites, we should secure our
exposed APIs/Resources and MuleSoft allows us to use HTTPS
endpoints to do this. We have a number of options when
Implementing HTTPS to our exposed resources on Cloudhub.
Expose our resource as a Direct HTTPS endpoint.
Expose our resource through a Proxy as a Proxy to API HTTPS
endpoint.
Expose our resource through a Proxy as a Client to Proxy HTTPS
endpoint.

Cloudhub HTTPS Implementation

Options
The following sections will describe
how to implement these options in
more detail but first a quick outline
of the implementation options
1. Direct HTTPS Endpoint Endpoint of the API is
exposed directly as a HTTPS service.

2. Proxy to API HTTPS Endpoint API is exposed via

HTTP Proxy with all communication between the Proxy
and API via HTTPS.

3. Client to Proxy API is exposed via HTTPS Proxy.

3
Client

Proxy

API

Implementing Direct and Proxy to

API HTTPS Endpoints
We follow the same steps to implement Direct or Proxy to API
HTTPS Endpoints on our Cloudhub service. In both cases we first
expose our service as Direct APIs through HTTPS, the difference
being for Proxy to API we would then generate the Proxy service
afterwards to point to the HTTPS API. We achieve as follows:
1.
2.
3.

Use Java JDKs Keytool utility to generate a keystore for your service.
In your global mule configuration create a HTTPS connector that uses this keystore.
In your service endpoint configure a HTTP listener that uses the HTTPS connector.

Generating the Keystore

First we will use a command line tool (shipped with Java JDK ) called Keytool to
create our keystore. Our keystore is a secure repository that stores public/private
key pairs and certificates, protecting private keys using a password.
1.

We create our keystore from the command line using the command below - this will create keystore for us in the
form of a .jks file and will contain our private key and a self-signed public certificate. In the example below the
KeyPassword and StorePassword can either be different passwords or the same but you need to take note of them
as they will be provided as part of the HTTPS Connector configuration. Also the hostname must be specified in the
ext parameter which is 127.0.0.1 in our example below.
keytool -genkeypair -keystore keystore.jks -dname
"CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown"
-keypass <KeyPassword> -storepass
<StorePassword>-keyalg DSA -sigalg SHA1withDSA -keysize 1024 -alias <MyAlias> -ext SAN=DNS:localhost,IP:127.0.0.1 -validity
9999

2.

The generated keystore should now be copied into a folder within your MuleSoft project that is included within the
projects Classpath such as /src/main/resources.

Reference Certificates from the

Keystore
As detailed, the previous step will generate a Keystore that contains a
self-signed certificate but it may be that we would like to use a
certificate certified by a Certification Authority (CA).
The Keytool gives us the ability to import certificates into the Keystore
using a import flag and a file flag to point to the certificates .cer file
so if you have a CA signed certificate this can be achieved.
The Keytool is very powerful and allows us to export certificates to be
signed, import signed certificates, check certificate/keystore entries,
delete certificates and much more which is not covered in this
document but is detailed in the Keytool documentation.

Create a HTTPS Listener Connector 1

Now we have a keystore in place we can create our HTTPS connector (preferably
a global configuration to make it globally accessible) that references our keystore.
1.

In Global Elements of your global.xml (or other mule config file) create an HTTP Listener Configuration, setting
the Protocol to HTTPS and configuring name, host, port either directly or referencing from a properties file:
<http:listener-config name="<ConfigName>" host="<Host>" port="<Port>" doc:name="HTTP Listener Configuration" />

2.

Edit Configuration XML to include the code in green below which references the keystore. Ensure the Keystore jks
file is copied into /src/main/resources folder or the project as Mule will try to find the resource within the application
class-path. The StorePassword and KeyPassword properties should be set to the corresponding the KeyPassword and
StorePassword values assigned when generating the Keystore using Keytool .
<http:listener-config name="<ConfigName>" host="<Host>" port="<Port>" doc:name="HTTP Listener Configuration" >
<tls:context name="<ContextName>" doc:name="TLS Context">
<tls:key-store path="<KeystoreFileName.jks>" password="<StorePassword>" keyPassword="<KeyPassword>" />
</tls:context>
</http:listener-config>

Create a HTTPS Listener Connector 2

3.

Now configure a HTTP Listener in your service endpoint to use the HTTPS Listener Connector
we just created in the global mule configuration. To do this set the config-ref property to
reference the name property of our HTTPS Listener Connector this should be available in the
Connector Configuration dropdown list on the properties form of the HTTP Listener.
<http:listener configref="<HTTPSListenerConnectorConfigName>" path="<APIURLPath>" doc:name="HTTPS" />

Create a HTTPS Request Connector 1

If there is a requirement to make external HTTP requests using HTTPS then a
HTTPS Request connector can be created in a similar manner using the following
steps:
1.

In Global Elements of your global.xml (or other mule config file) create an HTTP Request Configuration, setting
the Protocol to HTTPS and configuring name, host, port either directly or referencing from a properties file:
<http:request-config name="<ConfigName>" host="<Host>" port="<Port>" doc:name="HTTP Request Configuration" />

2.

Edit Configuration XML to include the code in green below which references the keystore. Ensure the Keystore jks
file is copied into /src/main/resources folder or the project as Mule will try to find the resource within the application
class-path. The StorePassword and KeyPassword properties should be set to the corresponding the KeyPassword and
StorePassword values assigned when generating the Keystore using Keytool .
<http:request-config name="<ConfigName>" host="<Host>" port="<Port>" doc:name="HTTP Request Configuration" >
<tls:context name="<ContextName>" doc:name="TLS Context">
<tls:key-store path="<KeystoreFileName.jks>" password="<StorePassword>" keyPassword="<KeyPassword>" />
</tls:context>
</http:request-config>

Create a HTTPS Request Connector 2

3.

Now configure a HTTP Request component in your service to use the HTTPS Request
Connector we just created in the global mule configuration. To do this set the config-ref
property to reference the name property of our HTTPS Request Connector this should be
available in the Connector Configuration dropdown list on the properties form of the HTTP
Request.
<http:request config-ref="<HTTPSRequestConnectorConfigName>" path="<TARGETURLPath>"
doc:name="HTTPS REQ" method="GET" followRedirects="true" parseResponse="false"/>

Direct and Proxy to API HTTPS

Your Direct or Proxy to API HTTPS service is now ready to be
deployed on CloudHub in the usual manner, and its URI will be
accessible via HTTPS.
For the Proxy to API HTTPS service, the additional step of
setting up and configuring the proxy through API Manager is
required, ensuring that the proxy configuration is pointing at the
URI of our newly deployed HTTPS service.

Implementing Client to Proxy

HTTPS Endpoints
To be continued..

Sources and References

The following is a list of sources and references used for research in
compiling this document and are recommended for further reading:

http://blogs.mulesoft.com/dev/api-dev/secure-api/
http://blogs.mulesoft.com/dev/mule-dev/working-with-certificates /
https://www.digitalocean.com/community/tutorials/java-keytool-essentials-working-with-java-keystores
https://docs.mulesoft.com/api-manager/https-api-proxy-example
https://docs.mulesoft.com/api-manager/setting-up-an-api-proxy#using-https
https://docs.mulesoft.com/runtime-manager/building-an-https-service
https://www.javacodegeeks.com/2014/07/java-keystore-tutorial.html