TLS / HTTPS

MockServer uses port unification so HTTP and HTTPS are both handled on the same port. When a request arrives over TLS, MockServer detects and decrypts it automatically — no separate port is required. MockServer supports TLS in three areas:

Inbound TLS

Accept HTTPS requests from clients connecting to MockServer.

Inbound mTLS

Require connecting clients to present a valid X.509 certificate.

Outbound TLS

Connect to HTTPS backends when forwarding or proxying requests.

Trusting MockServer’s certificate

MockServer dynamically generates its TLS certificates, signed by its own Certificate Authority (CA). HTTP clients must trust this CA to establish a TLS connection without errors.

Add the CA to the JVM trust store

Use the Java keytool command to import the MockServer CA certificate:

keytool -import -v \
  -keystore /usr/lib/jvm/java-17-openjdk/lib/security/cacerts \
  -alias mockserver-ca \
  -file CertificateAuthorityCertificate.pem \
  -storepass changeit \
  -trustcacerts \
  -noprompt

Configure the SSL socket factory in tests

For Java test suites, configure the default SSL socket factory to accept MockServer certificates:

import org.mockserver.integration.ClientAndServer;
import org.mockserver.logging.MockServerLogger;
import org.mockserver.socket.tls.KeyStoreFactory;
import javax.net.ssl.HttpsURLConnection;

@BeforeClass
public static void startMockServer() {
    HttpsURLConnection.setDefaultSSLSocketFactory(
        new KeyStoreFactory(new MockServerLogger()).sslContext().getSocketFactory()
    );
    mockServer = ClientAndServer.startClientAndServer(1080);
}

Do not add the built-in MockServer CA to your operating system trust store unless you have also enabled dynamicallyCreateCertificateAuthorityCertificate. The built-in CA private key is publicly available in the MockServer repository, which would expose your machine to man-in-the-middle attacks.

Inbound TLS configuration

Use a dynamically generated CA

By default, MockServer uses a fixed built-in CA. Enable this property to generate a unique CA certificate and private key on first startup instead:

ConfigurationProperties.dynamicallyCreateCertificateAuthorityCertificate(true);
ConfigurationProperties.directoryToSaveDynamicSSLCertificate("/etc/mockserver/certs");

-Dmockserver.dynamicallyCreateCertificateAuthorityCertificate=true
-Dmockserver.directoryToSaveDynamicSSLCertificate=/etc/mockserver/certs

MOCKSERVER_DYNAMICALLY_CREATE_CERTIFICATE_AUTHORITY_CERTIFICATE=true
MOCKSERVER_CERTIFICATE_DIRECTORY_TO_SAVE_DYNAMIC_SSL_CERTIFICATE=/etc/mockserver/certs

mockserver.dynamicallyCreateCertificateAuthorityCertificate=true
mockserver.directoryToSaveDynamicSSLCertificate=/etc/mockserver/certs

The generated CA certificate and private key are saved to the specified directory. On subsequent restarts, MockServer reuses existing files rather than generating new ones.

Use a custom CA certificate

To sign MockServer’s generated certificates with your own CA, provide both a private key and X.509 certificate in PEM format:

ConfigurationProperties.certificateAuthorityPrivateKey("/certs/ca-private-key.pem");
ConfigurationProperties.certificateAuthorityCertificate("/certs/ca-certificate.pem");

-Dmockserver.certificateAuthorityPrivateKey=/certs/ca-private-key.pem
-Dmockserver.certificateAuthorityCertificate=/certs/ca-certificate.pem

MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY=/certs/ca-private-key.pem
MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE=/certs/ca-certificate.pem

mockserver.certificateAuthorityPrivateKey=/certs/ca-private-key.pem
mockserver.certificateAuthorityCertificate=/certs/ca-certificate.pem

The private key must be in PKCS#8 or PKCS#1 PEM format. 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

Use a fixed server certificate

To use a specific certificate for all TLS connections into MockServer rather than having one generated, provide both the private key and X.509 certificate:

mockserver.privateKeyPath=/certs/server-private-key.pem
mockserver.x509CertificatePath=/certs/server-certificate.pem

Both properties must be set together. The certificateAuthorityCertificate must be the CA that signed this X.509 certificate.

Configure Subject Alternative Names

MockServer automatically updates the Subject Alternative Names (SANs) in its certificate as it sees new hostnames. To lock down SANs to a fixed list:

mockserver.preventCertificateDynamicUpdate=true
mockserver.sslCertificateDomainName=localhost
mockserver.sslSubjectAlternativeNameDomains=localhost,api.example.com
mockserver.sslSubjectAlternativeNameIps=127.0.0.1,0.0.0.0

Inbound mTLS (client certificate authentication)

Require all clients connecting to MockServer to present a valid certificate signed by a trusted CA:

ConfigurationProperties.tlsMutualAuthenticationRequired(true);
ConfigurationProperties.tlsMutualAuthenticationCertificateChain("/certs/client-ca.pem");

-Dmockserver.tlsMutualAuthenticationRequired=true
-Dmockserver.tlsMutualAuthenticationCertificateChain=/certs/client-ca.pem

MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_REQUIRED=true
MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=/certs/client-ca.pem

mockserver.tlsMutualAuthenticationRequired=true
mockserver.tlsMutualAuthenticationCertificateChain=/certs/client-ca.pem

tlsMutualAuthenticationCertificateChain is the PEM file containing the CA (or chain) that signed trusted client certificates. Any client presenting a certificate not signed by this CA will be rejected.

When tlsMutualAuthenticationRequired is enabled, the tlsMutualAuthenticationCertificateChain is also used by MockServerClient when it connects to MockServer over TLS.

Outbound TLS (forwarding to HTTPS backends)

When MockServer forwards or proxies requests to HTTPS backends, it needs to establish its own TLS connection outbound.

Configure which certificates to trust

Control which server certificates MockServer accepts for outbound connections using the trust manager type:

Value	Behavior
`ANY`	Trust all certificates (default). No hostname verification.
`JVM`	Trust certificates in the JVM’s default trust store.
`CUSTOM`	Trust only certificates specified by `forwardProxyTLSCustomTrustX509Certificates`.

ConfigurationProperties.forwardProxyTLSX509CertificatesTrustManagerType("CUSTOM");
ConfigurationProperties.forwardProxyTLSCustomTrustX509Certificates("/certs/backend-ca.pem");

-Dmockserver.forwardProxyTLSX509CertificatesTrustManagerType=CUSTOM
-Dmockserver.forwardProxyTLSCustomTrustX509Certificates=/certs/backend-ca.pem

MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATES_TRUST_MANAGER_TYPE=CUSTOM
MOCKSERVER_FORWARD_PROXY_TLS_CUSTOM_TRUST_X509_CERTIFICATES=/certs/backend-ca.pem

mockserver.forwardProxyTLSX509CertificatesTrustManagerType=CUSTOM
mockserver.forwardProxyTLSCustomTrustX509Certificates=/certs/backend-ca.pem

Use a client certificate for outbound mTLS

If the backend requires MockServer to present a client certificate (mTLS), provide the private key and certificate chain for outbound connections:

ConfigurationProperties.forwardProxyPrivateKey("/certs/client-private-key.pem");
ConfigurationProperties.forwardProxyCertificateChain("/certs/client-certificate.pem");

-Dmockserver.forwardProxyPrivateKey=/certs/client-private-key.pem
-Dmockserver.forwardProxyCertificateChain=/certs/client-certificate.pem

MOCKSERVER_FORWARD_PROXY_TLS_PRIVATE_KEY=/certs/client-private-key.pem
MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATE_CHAIN=/certs/client-certificate.pem

mockserver.forwardProxyPrivateKey=/certs/client-private-key.pem
mockserver.forwardProxyCertificateChain=/certs/client-certificate.pem

Reference: TLS properties

Property	Environment variable	Default	Description
`mockserver.dynamicallyCreateCertificateAuthorityCertificate`	`MOCKSERVER_DYNAMICALLY_CREATE_CERTIFICATE_AUTHORITY_CERTIFICATE`	`false`	Generate a unique CA on first startup
`mockserver.directoryToSaveDynamicSSLCertificate`	`MOCKSERVER_CERTIFICATE_DIRECTORY_TO_SAVE_DYNAMIC_SSL_CERTIFICATE`	`null`	Directory to save the generated CA
`mockserver.certificateAuthorityPrivateKey`	`MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY`	`null`	Custom CA private key (PEM)
`mockserver.certificateAuthorityCertificate`	`MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE`	`null`	Custom CA certificate (PEM)
`mockserver.privateKeyPath`	`MOCKSERVER_TLS_PRIVATE_KEY_PATH`	`null`	Fixed server private key (PEM)
`mockserver.x509CertificatePath`	`MOCKSERVER_TLS_X509_CERTIFICATE_PATH`	`null`	Fixed server certificate (PEM)
`mockserver.tlsMutualAuthenticationRequired`	`MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_REQUIRED`	`false`	Require client certificates on inbound connections
`mockserver.tlsMutualAuthenticationCertificateChain`	`MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN`	`null`	CA chain to validate client certificates
`mockserver.forwardProxyTLSX509CertificatesTrustManagerType`	`MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATES_TRUST_MANAGER_TYPE`	`ANY`	Trust policy for outbound connections
`mockserver.forwardProxyTLSCustomTrustX509Certificates`	`MOCKSERVER_FORWARD_PROXY_TLS_CUSTOM_TRUST_X509_CERTIFICATES`	`null`	Custom trusted CAs for outbound connections
`mockserver.forwardProxyPrivateKey`	`MOCKSERVER_FORWARD_PROXY_TLS_PRIVATE_KEY`	`null`	Client private key for outbound mTLS
`mockserver.forwardProxyCertificateChain`	`MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATE_CHAIN`	`null`	Client certificate for outbound mTLS

Get Started

Mocking

Proxying

Configuration

Debugging

Inbound TLS

Inbound mTLS

Outbound TLS

Trusting MockServer’s certificate

Add the CA to the JVM trust store

Configure the SSL socket factory in tests

Inbound TLS configuration

Use a dynamically generated CA

Use a custom CA certificate

Use a fixed server certificate

Configure Subject Alternative Names

Inbound mTLS (client certificate authentication)

Outbound TLS (forwarding to HTTPS backends)

Configure which certificates to trust

Use a client certificate for outbound mTLS

Reference: TLS properties

Inbound TLS

Inbound mTLS

Outbound TLS

​Trusting MockServer’s certificate

​Add the CA to the JVM trust store

​Configure the SSL socket factory in tests

​Inbound TLS configuration

​Use a dynamically generated CA

​Use a custom CA certificate

​Use a fixed server certificate

​Configure Subject Alternative Names

​Inbound mTLS (client certificate authentication)

​Outbound TLS (forwarding to HTTPS backends)

​Configure which certificates to trust

​Use a client certificate for outbound mTLS

​Reference: TLS properties

Trusting MockServer’s certificate

Add the CA to the JVM trust store

Configure the SSL socket factory in tests

Inbound TLS configuration

Use a dynamically generated CA

Use a custom CA certificate

Use a fixed server certificate

Configure Subject Alternative Names

Inbound mTLS (client certificate authentication)

Outbound TLS (forwarding to HTTPS backends)

Configure which certificates to trust

Use a client certificate for outbound mTLS

Reference: TLS properties