MuleSoft TLS and HTTPS
TLS (Transport Layer Security) encrypts data in transit between clients and your API. Without TLS, anyone monitoring the network can read API credentials, customer data, and business information in plain text. HTTPS is HTTP over TLS — every production MuleSoft API must use HTTPS.
How TLS Works
TLS creates a secure tunnel between two parties using certificates and cryptographic keys. The server presents its certificate to prove its identity. The client verifies the certificate is trusted. Both parties then negotiate a shared encryption key for the session.
TLS Handshake Diagram
Client Server (Mule API) │ │ │──── 1. ClientHello ─────────────────►│ │ (supported TLS versions, │ │ cipher suites) │ │ │ │◄─── 2. ServerHello + Certificate ────│ │ (server's public cert, │ │ chosen cipher suite) │ │ │ │─── 3. Verify certificate ────────────│ │ (Is it from a trusted CA? │ │ Is it expired? Does hostname match?)│ │ │ │──── 4. Key Exchange ────────────────►│ │ (generate shared session key) │ │ │ ├────── 5. Encrypted Communication ───►│ │ All data from here is │ │ encrypted with session key │
TLS Terminology
- Certificate: A digital document that proves the server's identity. Issued by a Certificate Authority (CA) and contains the server's public key.
- Keystore: A file that holds your server's private key and certificate. The server uses it to prove its identity.
- Truststore: A file that holds CA certificates your application trusts. Used to verify the certificates of servers you connect to.
- Self-Signed Certificate: A certificate you create yourself, not signed by a CA. Good for development and testing, never for production.
- Mutual TLS (mTLS): Both the server and client present certificates. Provides the strongest authentication — only clients with a known certificate can connect.
Creating a Self-Signed Certificate for Development
For local development and testing, generate a self-signed certificate using the Java keytool command.
Generate Keystore with Self-Signed Certificate
Command (run in terminal): keytool -genkeypair -alias api-server -keyalg RSA -keysize 2048 -validity 365 -keystore api-keystore.jks -storepass keystorePassword -keypass keyPassword -dname "CN=localhost, OU=Dev, O=MyCompany, L=NYC, S=NY, C=US" This creates: api-keystore.jks Contains: private key + self-signed certificate Valid for: 365 days Alias: api-server
Configuring HTTPS in the HTTP Listener
Place the keystore file in src/main/resources/. Configure the HTTP Listener connector to use HTTPS and reference the keystore.
HTTPS Listener Configuration
HTTP Listener Connector Config:
Name: HTTPS_Listener_Config
Protocol: HTTPS
Host: 0.0.0.0
Port: 8443
TLS Context:
Key Store:
Type: JKS
Path: api-keystore.jks
Password: ${keystore.storePassword}
Key Alias: api-server
Key Password: ${keystore.keyPassword}
Secure Properties (config.yaml):
keystore:
storePassword: "!![encrypted_value_here]"
keyPassword: "!![encrypted_value_here]"
Configuring HTTPS for HTTP Request (Outbound)
When your Mule application calls an external HTTPS endpoint, configure a TLS context in the HTTP Request connector. If the external server uses a certificate from a trusted public CA (like DigiCert or Let's Encrypt), no special configuration is needed — MuleSoft trusts public CAs by default.
For servers with custom or self-signed certificates (common for internal services), add the server's certificate to a truststore and reference it in the HTTP Request connector.
Custom Truststore for Internal Services
Step 1: Export the internal server's certificate
keytool -export -alias internal-server -keystore server-keystore.jks
-file internal-server.cer
Step 2: Import it into a truststore
keytool -import -alias internal-server -file internal-server.cer
-keystore my-truststore.jks -storepass truststorePass
Step 3: Configure HTTP Request connector
TLS Context:
Trust Store:
Type: JKS
Path: my-truststore.jks
Password: ${truststore.password}
Mutual TLS (mTLS)
In mTLS, the server also requests a certificate from the client. Only clients with a certificate signed by a trusted CA can connect. This is the strongest form of API authentication — no tokens or passwords required. The certificate IS the identity.
mTLS Architecture
Normal TLS: Client ──── presents nothing ────────────────► Server (presents cert) Server validates client identity: No validation mTLS: Client (presents cert) ───────────────────────► Server (presents cert) Server validates client cert ✓ Client validates server cert ✓ Both sides verified → connection established Use cases for mTLS: - Service-to-service communication inside a company network - Financial institution API connections - Partner-to-partner data exchange with high security requirements
Enabling mTLS on HTTP Listener
HTTP Listener TLS Context:
Key Store: (server's certificate)
...same as above...
Trust Store: (certificates of allowed clients)
Type: JKS
Path: client-truststore.jks
Password: ${truststore.password}
Require Client Authentication: true
(connection rejected if client does not present a certificate)
TLS Versions and Cipher Suites
Always enforce TLS 1.2 or TLS 1.3. Older versions (TLS 1.0, TLS 1.1, SSL 3.0) have known vulnerabilities and are no longer considered secure. Configure the enabled protocols explicitly in the TLS context.
TLS Context:
Enabled Protocols: TLSv1.2, TLSv1.3
Enabled Cipher Suites:
TLS_AES_128_GCM_SHA256 (TLS 1.3)
TLS_AES_256_GCM_SHA384 (TLS 1.3)
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (TLS 1.2)
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (TLS 1.2)
Certificate Rotation
Certificates expire. Create a process to renew and rotate certificates before expiry. In CloudHub, update the keystore in the application's secure properties and redeploy. Set a calendar reminder 30 days before the certificate expiry date. An expired certificate causes all HTTPS connections to fail immediately — this is a production outage.