March 17 2020

Overview

When applications are deployed to CloudHub and exposed using SSL via the shared load balancer or a dedicated load balancer, the HTTP listener within the Mule application must also be configured for SSL.

One issue that arises when enabling SSL for the listener is being able to provide valid certificates for local testing before deploying to Cloudhub. Tools such as mkcert can make this process much easier.

 

Cloudhub Load Balancer Networking 

When deploying apps to CloudHub you must be aware that the apps use a share load balancer unless you obtain a dedicated load balancer. Mule apps deployed in CloudHub must listen on host 0.0.0.0 and to either the HTTP port (8081) or to the HTTPS port (8082).

The following ports are assigned on the Mule worker by default:

  • http.port is set to 8081

  • https.port is set to 8082

CloudHub load balancers only forward the HTTP(:80) traffic to port 8081 and HTTPS (:443) to port 8082 on the worker. Forwarded traffic still uses HTTP and HTTPS protocols, which means it can’t listen for HTTPS on ${http.port} or plain HTTP on ${https.port}.

You must reference these ports using the reserved properties ${http.port} and ${https.port} respectively in your mule application as to property placeholders when you configure the port in your HTTP listener configuration. Since CloudHub services will allocate 8081 for HTTP and 8082 for HTTPS traffic at deployment time any custom values are provided for the above placeholder in mule-app properties they will be overwritten during deployment by CloudHub. If you have issues using these port numbers in the studio or local environment you could pass a required port number as VM arguments or have a different set of properties for deployments in the studio or local environment.

In order for the Load Balancers to forward the HTTPS traffic to the application, you need to configure your HTTP listener with a certificate, public-private key pair. The CloudHub load balancer does not validate the certificate you configure in your application so any self-signed certificate can be used irrespective of the host that it is generated for. When using a DLB you need to configure your DLB with a trusted certificate that the client validates with their trust store. You may need to provide them the certificate if you are using a self-signed certificate and not one signed by a trusted CA.

 

Configuring an HTTPS endpoint in MuleSoft

The following Mulesoft documentation will provide all the information required for building an HTTPS endpoint. This includes generating a Keystore, self-signed certificate and how to configure your HTTP listener with TLS configuration. Refer to the below table for the required fields.

Field

Description

Type

Select the type of keystore from the drop down

Path

Path to your keystore in your src/main/resources

Alias

When the key store contains many private keys, this attribute indicates alias of the key that should be used. If not defined, the first key in the file will be used by default.

Key Password

Password for your key

Password

Password for your keystore

 

Installing Trusted Certificate for Local Studio Use

The steps below will guide you through the steps to configure a root CA certificate into your system’s truststore so certificates generated using that will work in the local Studio environment as a Trusted Certificate for the API development team.

 

Working with self-signed certificates

It is difficult to work with self-signed certificates as they cause trust errors. Managing your own CA is the best solution, but usually involves arcane commands, specialized knowledge, and manual steps.

The mkcert utility can be installed in all development environments and it facilitates working with self-signed certificates much easier. The mkcert utility installs a trusted root CA into your system’s trust store. All the certificates generated using mkcert are signed using this root CA. This make’s all the certificates generated using mkcert as trusted. You need not make any configuration. Once you complete installing mkcert and setting required environment variables run the following command this will install a root CA into your system truststore.

mkcert -install

Root certificate will be added to Browser’s Truststore, OS truststore and to JAVA truststore which is at ${JAVA_HOME}/jre/lib/security/cacerts

Here are the screenshots for the browser’s and Windows system’s truststore which have a mkcert’s rootCA as trusted.

 

List the entries in the cacerts truststore present in the ${JAVA_HOME} you will see a new entry with mkcert. Navigate to the above folder and run the following to inspect the system truststore if an entry for mkcert is added to it.

keytool -list -keystore cacerts

 

Building PKCS#12 Key Store using mkcert

Since Java 9 the default Keystore format is PKCS12. The biggest difference between JKS and PKCS12 is that JKS is a format specific to Java, while PKCS12 is a standardized and language-neutral way of storing encrypted private keys and certificates. PKCS12 is supported by Mule.

Generating the PKCS#12 Keystore

Generating a Keystore using the following command by providing the type of keystore and the domain as arguments to the command.

mkcert -pkcs12 localhost

 

This creates a PKCS#12 Keystore with localhost in your current directory location with default password “changeit

 

Inspecting the Keystore

By default, the alias name for the generated key pair in the Keystore is “1” we need to update these default in our further steps. For this, we need to use “keytool” which is by default installed with JAVA. Following is the command for viewing all the contents of the Keystore. Enter the default password “changeit“when prompted.

keytool -list -keystore C:\Users\TejaChowdary\Desktop\demo\localhost.p12

 

Updating Alias and Default Password

Use the following command to generate a new Keystore by updating and importing all the certificates and keys from the Keystore generated in the previous step.

keytool -importkeystore -srckeystore localhost.p12 -destkeystore NewDestinationKeystoreName -srcstoretype pkcs12 -deststoretype pkcs12 -alias 1 -destalias NewDestinationAlias -destkeypass NewDestinationPassword

Update the above -destkeystore -destalias and -destkeypass values with your required parameter from the snippet and run the command. Enter the destination password and source password “changeit“ in this case when prompted. Run the list command provided above with an updated path as an argument for -keystore to view the contents of the new Keystore.

Now that the default alias name and password are updated we can configure this new Keystore into our mule applications. Use this Mulesoft documentation to configure your mule apps.

For PKCS#12 type of keystores the password for the Keystore and the key are the same and can’t be different

 

Working in Teams

When working in a team, team members need to use a single rootCA.pem file and install that in their system locally. This will make sure that a common root certificate entry is present in the systems' Truststore of people working with the same certificates.

You can find the location for the rootCA certificate using the following command.

mkcert -CAROOT

 

Go to the folder location returned by the above command and share the rootCA.pem with members of the team.

To install the shared CA on a different system install mkcert on the new system and retrieve CAROOT using the “mkcert -CAROOT”. Navigate to the CAROOT, paste the rootCA.pem and run this following command.

mkcert -install

This will add the same rootCA entry on your system as trusted on to the new system's truststore.

 

Configuring Postman

In order to work with self-signed certificates using Postman. Go to Postman settings, click on the certificates tab. In CA certificates add the rootCA.pem. If you are using a different certificate for each app since each certificate is signed by the same rootCA in your settings in postman they are then marked as valid during SSL verification.

After your development if you want to uninstall the rootCA that you installed to your Java, OS, browser truststores run mkcert -uninstall. You may want to do this if each customer/project is using its own trusted root CA. If you delete the whole mkcert folder (Show when running mkcert -CAROOTmkcert -uninstall won't work, so you will have to remove the certificate manually from the Java, OS and browser truststores.

 

About the Author

Teja Chowdary

I am working as a Mulesoft developer for over 3 years. Have experience in providing Mulesoft based solutions to clients in different domains retail, health care and manufacturing.

 

Join the Conversation

Enter your first name. It will only be used to display with your comment.
Enter your email. This will be used to validate you as a real user but will NOT be displayed with the comment.