Skip to main content
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");
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");
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");
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:
ValueBehavior
ANYTrust all certificates (default). No hostname verification.
JVMTrust certificates in the JVM’s default trust store.
CUSTOMTrust only certificates specified by forwardProxyTLSCustomTrustX509Certificates.
ConfigurationProperties.forwardProxyTLSX509CertificatesTrustManagerType("CUSTOM");
ConfigurationProperties.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");

​
Reference: TLS properties

PropertyEnvironment variableDefaultDescription
mockserver.dynamicallyCreateCertificateAuthorityCertificateMOCKSERVER_DYNAMICALLY_CREATE_CERTIFICATE_AUTHORITY_CERTIFICATEfalseGenerate a unique CA on first startup
mockserver.directoryToSaveDynamicSSLCertificateMOCKSERVER_CERTIFICATE_DIRECTORY_TO_SAVE_DYNAMIC_SSL_CERTIFICATEnullDirectory to save the generated CA
mockserver.certificateAuthorityPrivateKeyMOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEYnullCustom CA private key (PEM)
mockserver.certificateAuthorityCertificateMOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATEnullCustom CA certificate (PEM)
mockserver.privateKeyPathMOCKSERVER_TLS_PRIVATE_KEY_PATHnullFixed server private key (PEM)
mockserver.x509CertificatePathMOCKSERVER_TLS_X509_CERTIFICATE_PATHnullFixed server certificate (PEM)
mockserver.tlsMutualAuthenticationRequiredMOCKSERVER_TLS_MUTUAL_AUTHENTICATION_REQUIREDfalseRequire client certificates on inbound connections
mockserver.tlsMutualAuthenticationCertificateChainMOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAINnullCA chain to validate client certificates
mockserver.forwardProxyTLSX509CertificatesTrustManagerTypeMOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATES_TRUST_MANAGER_TYPEANYTrust policy for outbound connections
mockserver.forwardProxyTLSCustomTrustX509CertificatesMOCKSERVER_FORWARD_PROXY_TLS_CUSTOM_TRUST_X509_CERTIFICATESnullCustom trusted CAs for outbound connections
mockserver.forwardProxyPrivateKeyMOCKSERVER_FORWARD_PROXY_TLS_PRIVATE_KEYnullClient private key for outbound mTLS
mockserver.forwardProxyCertificateChainMOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATE_CHAINnullClient certificate for outbound mTLS