MockServer uses port unification to simplify the configuration so all protocols (i.e. HTTP, HTTPS / SSL, SOCKS, etc) are supported on the same port. This means when a request is sent over TLS (i.e. an HTTPS request) MockServer dynamically detects that the request is encrypted.
MockServer has support for TLS (i.e. HTTPS) in three areas:
The majority of HTTP clients perform the following steps when making an HTTPS request:
MockServer is able to mock the behaviour of multiple hostnames (i.e. servers) and present a valid X.509 Certificates for them. MockServer achieves this by dynamically generating its X.509 Certificate using an in-memory list of hostnames and ip addresses, this is described in more detail below.
It is important to ensure that any client calling MockServer over TLS trust MockServer as a Certificate Authority (CA) (i.e. trust the MockServer CA X.509) the different approaches to establishing this trust is described below.
MockServer provides multiple ways its TLS can be configured. The following things can be configured:
Note: when proxying HTTPS traffic, MockServer performs man-in-the-middle (MITM) TLS termination. It decrypts incoming TLS connections, inspects the HTTP request content for expectation matching, and then re-encrypts traffic when forwarding to the upstream server. MockServer does not support TLS passthrough (where encrypted traffic is forwarded without decryption). This is by design — MockServer needs to inspect request content to match expectations, record requests for verification, and apply response actions.
The MockServer CA X.509 must be considered a valid trust root to ensure MockServer's dynamically generate X.509 certificates are trusted by an HTTP Client. This means the CA X.509 needs to be added into the JVM, HTTP Client or operating system as appropriate.
The MockServer CA X.509 can be found (in PEM format) in the MockServer github repo or can be loaded from the classpath location /org/mockserver/socket/CertificateAuthorityCertificate.pem
It is possible to add the MockServer CA X.509 as a trusted root CA to your operating system, this will make most clients applications running on your OS (such as browsers) trust dynamically generated certificates from MockServer.
This is only an acceptable risk if it is done for a short period and the configuration setting dynamicallyCreateCertificateAuthorityCertificate is enabled to generate a local unique CA X.509 and Private Key that is saved to your local disk in the folder configured using directoryToSaveDynamicSSLCertificate.
If the configuration setting dynamicallyCreateCertificateAuthorityCertificate is not enabled, and your OS trusts the MockServer CA X.509, then this would leave your machine open to man-in-the-middle attacks because the corresponding Private Key is in the MockServer github repository. This would allow hackers to compromise all sensitive communicates such as to your bank or other sensitive sites.
Browsers (such as Chrome, Firefox or IE) may not always trust dynamically generated certificates from MockServer because of Certificate Transparency and Public Key Pinning both of which make it hard to dynamically generate certificates that are trusted.
Some sites will work but others (such as google sites) won't work due to certificate pinning.
Browser that rely on Certificate Transparency will likely not trust dynamically generated certificates from MockServer
The following code shows how to load a file from the classpath or a relative filesystem location:
public void doSomething() {
String mockServerCA = loadFileFromLocation("/org/mockserver/socket/CertificateAuthorityCertificate.pem");
}
public String loadFileFromLocation(String location) {
location = location.trim().replaceAll("\\\\", "/");
Path path;
if (location.toLowerCase().startsWith("file:")) {
path = Paths.get(URI.create(location));
} else {
path = Paths.get(location);
}
if (Files.exists(path)) {
// org.apache.commons.io.FileUtils
return FileUtils.readFileToString(path.toFile(), "UTF-8");
} else {
return loadFileFromClasspath(location);
}
}
private String loadFileFromClasspath(String location) {
try {
InputStream inputStream = this.getClass().getResourceAsStream(location);
try {
if (inputStream == null) {
inputStream = this.getClass().getClassLoader().getResourceAsStream(location);
}
if (inputStream == null) {
inputStream = ClassLoader.getSystemResourceAsStream(location);
}
if (inputStream != null) {
try {
// org.apache.commons.io.IOUtils
return IOUtils.toString(inputStream, Charsets.UTF_8);
} catch (IOException e) {
throw new RuntimeException("Could not read " + location + " from the classpath", e);
}
}
throw new RuntimeException("Could not find " + location + " on the classpath");
} finally {
if (inputStream != null) {
inputStream.close();
}
}
} catch (IOException ioe) {
throw new RuntimeException("Exception closing input stream for " + location, ioe);
}
}Another mechanism to ensure the MockServer X.509 is trusted is to configure the DefaultSSLSocketFactory in the JVM using the following line:
HttpsURLConnection.setDefaultSSLSocketFactory(new KeyStoreFactory(new MockServerLogger()).sslContext().getSocketFactory());This can be used in a test case, as follows:
import org.junit.AfterClass;
import org.junit.BeforeClass;
import org.junit.Test;
import org.mockserver.integration.ClientAndServer;
import org.mockserver.logging.MockServerLogger;
import org.mockserver.socket.PortFactory;
import org.mockserver.socket.tls.KeyStoreFactory;
import javax.net.ssl.HttpsURLConnection;
public class ExampleTestClass {
private static ClientAndServer mockServer;
@BeforeClass
public static void startMockServer() {
// ensure all connection using HTTPS will use the SSL context defined by
// MockServer to allow dynamically generated certificates to be accepted
HttpsURLConnection.setDefaultSSLSocketFactory(new KeyStoreFactory(new MockServerLogger()).sslContext().getSocketFactory());
mockServer = ClientAndServer.startClientAndServer(PortFactory.findFreePort());
}
@AfterClass
public static void stopMockServer() {
mockServer.stop();
}
@Test
public void shouldDoSomething() {
// test system
}
}If you cannot modify the JVM's default SSLSocketFactory, you can programmatically create a custom TrustStore that trusts MockServer's dynamically generated certificates and use it with a specific HTTP client:
import org.mockserver.logging.MockServerLogger;
import org.mockserver.socket.tls.KeyStoreFactory;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManagerFactory;
import java.net.HttpURLConnection;
import java.net.URL;
import java.security.KeyStore;
KeyStoreFactory keyStoreFactory = new KeyStoreFactory(new MockServerLogger());
KeyStore trustStore = keyStoreFactory.loadOrCreateKeyStore();
TrustManagerFactory trustManagerFactory =
TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
trustManagerFactory.init(trustStore);
SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(null, trustManagerFactory.getTrustManagers(), null);
HttpsURLConnection connection =
(HttpsURLConnection) new URL("https://localhost:1080/some/path").openConnection();
connection.setSSLSocketFactory(sslContext.getSocketFactory());This approach is useful when you need to trust MockServer's certificates for a specific connection without affecting other HTTPS connections in the JVM.
The Java keytool command can also be used to add the MockServer CA X.509 certificate to the list of trust CA Certificates for a JVM, as follows:
keytool -import -v -keystore /usr/lib/jvm/java-8-openjdk-amd64/jre/lib/security/cacerts -alias mockserver-ca -file CertificateAuthorityCertificate.pem -storepass changeit -trustcacerts -nopromptAn example bash script showing how this can be done can be found in the MockServer github repo
MockServer is able to mock the behaviour of multiple hostnames (i.e. servers) and present a valid X.509 Certificates for them. MockServer achieves this by dynamically generating its X.509 Certificate using an in-memory list of hostnames and ip addresses. When the list of hostnames or ips addresses changes a new certificate is generated. The list of hostnames is updated, when:
Note: if a request is received with a Host header for a hostname not seen before the first request will fail validation because the TLS connection has already been established before the Host header can be read, any subsequent requests with that hostname will pass hostname validation.
The following examples show how to configure MockServer with mutual TLS (mTLS / client authentication) using self-generated certificates. A complete Docker Compose example is available in the MockServer repository.
This example uses one CA to sign both server and client certificates. In production, server and client certificates may be issued by separate trusted CAs. The three certificate sets are:
MockServer accepts private keys in both PKCS#8 (-----BEGIN PRIVATE KEY-----) and PKCS#1 RSA (-----BEGIN RSA PRIVATE KEY-----) PEM format. The examples below use PKCS#8 for consistency. To convert a PKCS#1 key to PKCS#8:
openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt#!/usr/bin/env bash
set -euo pipefail
DAYS=3650
KEY_SIZE=2048
# 1. Generate Certificate Authority (CA)
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:${KEY_SIZE} -out ca-key.pem
openssl req -new -x509 -key ca-key.pem -out ca.pem -days ${DAYS} \
-subj "/C=UK/ST=England/L=London/O=MockServer/CN=MockServer CA"
# 2. Generate server certificate signed by CA
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:${KEY_SIZE} -out server-key-pkcs8.pem
openssl req -new -key server-key-pkcs8.pem -out server.csr \
-subj "/C=UK/ST=England/L=London/O=MockServer/CN=localhost"
cat > server-ext.cnf <<EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage=digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth
subjectAltName=DNS:localhost,DNS:mockserver,DNS:host.docker.internal,IP:127.0.0.1,IP:0.0.0.0
EOF
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
-out server-cert.pem -days ${DAYS} -extfile server-ext.cnf
# Create certificate chain (leaf + CA)
cat server-cert.pem ca.pem > server-cert-chain.pem
# 3. Generate client certificate signed by CA
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:${KEY_SIZE} -out client-key-pkcs8.pem
openssl req -new -key client-key-pkcs8.pem -out client.csr \
-subj "/C=UK/ST=England/L=London/O=MockServer/CN=MockServer Client"
cat > client-ext.cnf <<EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage=digitalSignature,keyEncipherment
extendedKeyUsage=clientAuth
EOF
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
-out client-cert.pem -days ${DAYS} -extfile client-ext.cnf
cat client-cert.pem ca.pem > client-cert-chain.pem
# Clean up CSR and temp files
rm -f server.csr server-ext.cnf client.csr client-ext.cnf ca.srlCFSSL is CloudFlare's PKI toolkit. Install with brew install cfssl.
#!/usr/bin/env bash
set -euo pipefail
# 1. Generate CA
cat > ca-csr.json <<EOF
{
"key": { "algo": "rsa", "size": 2048 },
"names": [{ "C": "UK", "L": "London", "O": "MockServer", "CN": "MockServer CA" }]
}
EOF
cfssl genkey -initca ca-csr.json | cfssljson -bare ca
rm -f ca.csr
# 2. Create signing config with explicit profiles and expiry
cat > cfssl-config.json <<EOF
{
"signing": {
"default": { "expiry": "87600h" },
"profiles": {
"server": {
"expiry": "87600h",
"usages": ["signing", "key encipherment", "server auth"]
},
"client": {
"expiry": "87600h",
"usages": ["signing", "key encipherment", "client auth"]
}
}
}
}
EOF
# 3. Generate server certificate
cat > server-csr.json <<EOF
{
"CN": "localhost",
"hosts": ["localhost", "mockserver", "host.docker.internal", "127.0.0.1", "0.0.0.0"],
"key": { "algo": "rsa", "size": 2048 },
"names": [{ "C": "UK", "L": "London", "O": "MockServer" }]
}
EOF
cfssl gencert -ca ca.pem -ca-key ca-key.pem -config cfssl-config.json -profile server \
server-csr.json | cfssljson -bare server
rm -f server.csr
openssl pkcs8 -topk8 -inform PEM -in server-key.pem -out server-key-pkcs8.pem -nocrypt
mv server.pem server-cert.pem
cat server-cert.pem ca.pem > server-cert-chain.pem
# 4. Generate client certificate
cat > client-csr.json <<EOF
{
"CN": "MockServer Client",
"key": { "algo": "rsa", "size": 2048 },
"names": [{ "C": "UK", "L": "London", "O": "MockServer" }]
}
EOF
cfssl gencert -ca ca.pem -ca-key ca-key.pem -config cfssl-config.json -profile client \
client-csr.json | cfssljson -bare client
rm -f client.csr
openssl pkcs8 -topk8 -inform PEM -in client-key.pem -out client-key-pkcs8.pem -nocrypt
mv client.pem client-cert.pem
cat client-cert.pem ca.pem > client-cert-chain.pem
# Clean up
rm -f ca-csr.json cfssl-config.json server-csr.json client-csr.json server-key.pem client-key.pemBoth approaches produce the same output files:
| File | Purpose |
|---|---|
ca-key.pem, ca.pem | CA private key and certificate (root of trust) |
server-key-pkcs8.pem, server-cert.pem | Server private key (PKCS#8) and certificate |
server-cert-chain.pem | Server certificate chain (leaf + CA) |
client-key-pkcs8.pem, client-cert.pem | Client private key (PKCS#8) and certificate |
client-cert-chain.pem | Client certificate chain (leaf + CA) |
Data-plane mTLS requires every HTTPS client to present a valid certificate. Non-TLS (HTTP) requests receive a 426 Upgrade Required response. This is the most common mTLS setup.
version: "2.4"
services:
mockserver:
image: mockserver/mockserver:latest
ports:
- "1080:1080"
environment:
MOCKSERVER_LOG_LEVEL: INFO
MOCKSERVER_SERVER_PORT: 1080
# Enable mTLS — require client certificates for all TLS connections
MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_REQUIRED: "true"
# CA certificate used to verify client certificates
MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN: /certs/ca.pem
# Custom CA for signing MockServer's own server certificate
MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY: /certs/ca-key.pem
MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE: /certs/ca.pem
# Custom server certificate and key (signed by the CA above)
MOCKSERVER_TLS_PRIVATE_KEY_PATH: /certs/server-key-pkcs8.pem
MOCKSERVER_TLS_X509_CERTIFICATE_PATH: /certs/server-cert-chain.pem
# Validate TLS configuration at startup
MOCKSERVER_PROACTIVELY_INITIALISE_TLS: "true"
# Load expectations from file
MOCKSERVER_INITIALIZATION_JSON_PATH: /config/expectationInitialiser.json
volumes:
- ./certs:/certs:ro
- ./config:/config:roSuccessful mTLS request (client presents certificate):
curl --cacert certs/ca.pem \
--cert certs/client-cert.pem \
--key certs/client-key-pkcs8.pem \
https://localhost:1080/helloFailed request without client certificate (TLS handshake fails):
curl --cacert certs/ca.pem https://localhost:1080/hello
# Error varies by TLS backend, e.g.: alert bad certificate / certificate required / handshake failureFailed request over HTTP (returns 426 Upgrade Required):
curl http://localhost:1080/hello
# 426 Upgrade RequiredWhen data-plane mTLS is enabled, creating expectations via the MockServer API also requires mTLS:
curl --cacert certs/ca.pem \
--cert certs/client-cert.pem \
--key certs/client-key-pkcs8.pem \
-X PUT https://localhost:1080/mockserver/expectation \
-H "Content-Type: application/json" \
-d '[{
"httpRequest": { "method": "GET", "path": "/api/users" },
"httpResponse": {
"statusCode": 200,
"headers": { "Content-Type": ["application/json"] },
"body": "[{\"id\": 1, \"name\": \"Alice\"}]"
}
}]'Control-plane mTLS secures only the MockServer management API (expectations, verification, reset, etc.) while leaving the data plane accessible without client certificates. This is useful when you want to protect who can configure MockServer without requiring mTLS for all test traffic.
version: "2.4"
services:
mockserver:
image: mockserver/mockserver:latest
ports:
- "1080:1080"
environment:
MOCKSERVER_LOG_LEVEL: INFO
MOCKSERVER_SERVER_PORT: 1080
# Control-plane mTLS — only management API requires client certificates
MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_REQUIRED: "true"
MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN: /certs/ca.pem
# Custom CA for signing MockServer's server certificate
MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY: /certs/ca-key.pem
MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE: /certs/ca.pem
# Custom server certificate and key
MOCKSERVER_TLS_PRIVATE_KEY_PATH: /certs/server-key-pkcs8.pem
MOCKSERVER_TLS_X509_CERTIFICATE_PATH: /certs/server-cert-chain.pem
MOCKSERVER_PROACTIVELY_INITIALISE_TLS: "true"
MOCKSERVER_INITIALIZATION_JSON_PATH: /config/expectationInitialiser.json
volumes:
- ./certs:/certs:ro
- ./config:/config:roData-plane requests work without client certificates:
# This works — data plane does not require mTLS
curl --cacert certs/ca.pem https://localhost:1080/helloManagement API requires client certificates:
# This fails — control plane requires mTLS
curl --cacert certs/ca.pem \
-X PUT https://localhost:1080/mockserver/expectation \
-H "Content-Type: application/json" \
-d '[{"httpRequest": {"path": "/test"}, "httpResponse": {"body": "ok"}}]'
# 401 Unauthorized
# This works — client certificate provided
curl --cacert certs/ca.pem \
--cert certs/client-cert.pem \
--key certs/client-key-pkcs8.pem \
-X PUT https://localhost:1080/mockserver/expectation \
-H "Content-Type: application/json" \
-d '[{"httpRequest": {"path": "/test"}, "httpResponse": {"body": "ok"}}]'When using MockServerClient with control-plane mTLS, configure the client certificate paths:
import org.mockserver.client.MockServerClient;
import org.mockserver.configuration.ConfigurationProperties;
// Enable control-plane mTLS on the client side
ConfigurationProperties.controlPlaneTLSMutualAuthenticationRequired(true);
// Client certificate and key for authenticating to MockServer
ConfigurationProperties.controlPlanePrivateKeyPath("/path/to/client-key-pkcs8.pem");
ConfigurationProperties.controlPlaneX509CertificatePath("/path/to/client-cert-chain.pem");
// CA certificate to verify MockServer's server certificate
ConfigurationProperties.controlPlaneTLSMutualAuthenticationCAChain("/path/to/ca.pem");
// Connect over HTTPS
MockServerClient client = new MockServerClient("localhost", 1080)
.withSecure(true);MockServer supports BouncyCastle FIPS (bc-fips) as a drop-in alternative to the standard BouncyCastle provider (bcprov-jdk18on). This is useful in environments that require FIPS 140-2 compliant cryptographic modules.
MockServer automatically detects which BouncyCastle provider is available at runtime — no configuration changes are needed. To use FIPS mode:
bcprov-jdk18on) from your classpathbc-fips) insteadjava.security configuration or programmatically)Example Maven dependency replacement:
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bc-fips</artifactId>
<version>1.0.2.5</version>
</dependency>MockServer will use whichever provider it finds on the classpath. If both are present, the standard (non-FIPS) provider is used. If neither is available, MockServer falls back to the JVM's default cryptographic provider.
The following are common TLS-related issues and their solutions:
If you see an error like javax.net.ssl.SSLException: java.lang.RuntimeException: Unexpected error: java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty, this means the JVM's trust store is empty or misconfigured. This is common in minimal Docker images or Linux systems where the CA certificates package is not installed.
Solution:
# Debian/Ubuntu
apt-get install -y ca-certificates-java
update-ca-certificates -f
# Alpine
apk add --no-cache ca-certificates java-cacertsIf your HTTP client rejects MockServer's certificate, ensure the MockServer CA certificate is trusted. See Ensure MockServer Certificates Are Trusted above for multiple approaches (OS trust store, JVM keytool, programmatic SSLContext).
When MockServer receives a request with a Host header for a hostname it has not seen before, the first request may fail TLS hostname validation. This is because the TLS handshake completes before MockServer can read the Host header and regenerate its certificate. Subsequent requests with that hostname will succeed. To avoid this, pre-configure the expected hostnames using the sslSubjectAlternativeNameDomains configuration property.
If you see "Connection reset" or "Broken pipe" errors during TLS connections, common causes include:
If you see java.security.KeyStoreException: Certificate chain is not valid, the server certificate is not signed by the configured Certificate Authority. This commonly happens when:
MOCKSERVER_TLS_X509_CERTIFICATE_PATH was not signed by the CA in MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE. Regenerate the server certificate using the same CA.cat server-cert.pem ca.pem > server-cert-chain.pem-----BEGIN PRIVATE KEY-----). PKCS#1 keys (beginning with -----BEGIN RSA PRIVATE KEY-----) must be converted:
openssl pkcs8 -topk8 -inform PEM -in key-pkcs1.pem -out key-pkcs8.pem -nocryptWhen tlsMutualAuthenticationRequired is enabled, MockServer requires all connections to use TLS. If a plain HTTP request is received, MockServer returns 426 Upgrade Required to indicate that the client must use HTTPS with a client certificate. Change your request URL from http:// to https:// and provide a client certificate.
If curl reports sslv3 alert bad certificate or SSL_ERROR_HANDSHAKE_FAILURE_ALERT, the client certificate was rejected by MockServer. Check that:
MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN--cert and --key to curl