The following diagram shows where TLS/mTLS configuration settings are used:
Enable dynamic creation of Certificate Authority X.509 Certificate and Private Key
Enable this property to increase the security of trusting the MockServer Certificate Authority X.509 by ensuring a local dynamic value is used instead of the public value in the MockServer git repo.
These PEM files will be created and saved in the directory specified with configuration property directoryToSaveDynamicSSLCertificate.
A Certificate Authority X.509 Certificate and Private Key will only be created if the files used to save them are not already present. Therefore, if MockServer is re-started multiple times with the same value for directoryToSaveDynamicSSLCertificate. the Certificate Authority X.509 Certificate and Private Key will only be created once.
Type: boolean Default: false
Java Code:
ConfigurationProperties.dynamicallyCreateCertificateAuthorityCertificate(boolean enable)System Property:
-Dmockserver.dynamicallyCreateCertificateAuthorityCertificate=...Environment Variable:
MOCKSERVER_DYNAMICALLY_CREATE_CERTIFICATE_AUTHORITY_CERTIFICATE=...Property File:
mockserver.dynamicallyCreateCertificateAuthorityCertificate=...Example:
-Dmockserver.dynamicallyCreateCertificateAuthorityCertificate="true"Directory used to save the dynamically generated Certificate Authority X.509 Certificate and Private Key.
This directory will only be used if MockServer is configured to create a dynamic Certificate Authority X.509 certificate and private key using dynamicallyCreateCertificateAuthorityCertificate.
By default the certificate and private key are written to the current working directory (.) of the MockServer process.
Type: string Default: . (current working directory)
Java Code:
ConfigurationProperties.directoryToSaveDynamicSSLCertificate(String directoryToSaveDynamicSSLCertificate)System Property:
-Dmockserver.directoryToSaveDynamicSSLCertificate=...Environment Variable:
MOCKSERVER_CERTIFICATE_DIRECTORY_TO_SAVE_DYNAMIC_SSL_CERTIFICATE=...Property File:
mockserver.directoryToSaveDynamicSSLCertificate=...Example:
-Dmockserver.directoryToSaveDynamicSSLCertificate="/some/existing/path"Proactively initialise TLS during start to ensure that if dynamicallyCreateCertificateAuthorityCertificate is enabled the Certificate Authority X.509 Certificate and Private Key will be created during start up and not when the first TLS connection is received.
This setting will also ensure any configured private key and X.509 will be loaded during start up and not when the first TLS connection is received to give immediate feedback on any related TLS configuration errors.
Type: boolean Default: false
Java Code:
ConfigurationProperties.proactivelyInitialiseTLS(boolean enable)System Property:
-Dmockserver.proactivelyInitialiseTLS=...Environment Variable:
MOCKSERVER_PROACTIVELY_INITIALISE_TLS=...Property File:
mockserver.proactivelyInitialiseTLS=...Example:
-Dmockserver.proactivelyInitialiseTLS="true"Comma separated list of TLS protocol versions to enable for both inbound and outbound TLS connections.
The default value is TLSv1.2,TLSv1.3. TLSv1 and TLSv1.1 are deprecated by RFC 8996 (they are vulnerable to the BEAST and POODLE attacks) and are no longer enabled by default, and TLSv1.3 is now enabled by default.
Breaking change: a client that can only negotiate TLSv1 or TLSv1.1 will no longer be able to complete a handshake with MockServer. If you genuinely need the legacy protocols for an old client, set tlsProtocols back to TLSv1,TLSv1.1,TLSv1.2 and set tlsAllowInsecureProtocols to true — both are required, because the insecure-protocol filter strips TLSv1/TLSv1.1 unless they are explicitly allowed.
Type: string Default: TLSv1.2,TLSv1.3
Java Code:
ConfigurationProperties.tlsProtocols("TLSv1.2,TLSv1.3")System Property:
-Dmockserver.tlsProtocols=...Environment Variable:
MOCKSERVER_TLS_PROTOCOLS=...Property File:
mockserver.tlsProtocols=...Example (enable TLS 1.2 and 1.3 only):
-Dmockserver.tlsProtocols="TLSv1.2,TLSv1.3"Example (Docker environment variable):
MOCKSERVER_TLS_PROTOCOLS="TLSv1.2,TLSv1.3"Whether to honour deprecated TLSv1 / TLSv1.1 entries that appear in tlsProtocols.
The default is false, so even if TLSv1 or TLSv1.1 are present in tlsProtocols they are stripped before the SSL context is built. Set this to true only if a legacy client genuinely cannot negotiate TLSv1.2/TLSv1.3, together with adding the protocols back to tlsProtocols.
Type: boolean Default: false
Java Code:
ConfigurationProperties.tlsAllowInsecureProtocols(true)System Property:
-Dmockserver.tlsAllowInsecureProtocols=...Environment Variable:
MOCKSERVER_TLS_ALLOW_INSECURE_PROTOCOLS=...Property File:
mockserver.tlsAllowInsecureProtocols=...Example:
-Dmockserver.tlsAllowInsecureProtocols="true"MockServer dynamically updates the Subject Alternative Name (SAN) values for its TLS certificate to add domain names and IP addresses from request Host headers and Host headers in expectations, this configuration setting disables this automatic update and only uses SAN value provided in TLS Subject Alternative Name Domains and TLS Subject Alternative Name IPs configuration properties.
When this property is enabled the generated X.509 Certificate and Private Key pair are saved to the directoryToSaveDynamicSSLCertificate as Certificate.pem and PKCS8PrivateKey.pem
Type: boolean Default: false
Java Code:
ConfigurationProperties.preventCertificateDynamicUpdate(boolean prevent)System Property:
-Dmockserver.preventCertificateDynamicUpdate=...Environment Variable:
MOCKSERVER_PREVENT_CERTIFICATE_DYNAMIC_UPDATE=...Property File:
mockserver.preventCertificateDynamicUpdate=...Example:
-Dmockserver.preventCertificateDynamicUpdate="true"The domain name for auto-generate TLS certificates
Type: string Default: localhost
Java Code:
ConfigurationProperties.sslCertificateDomainName(String domainName)System Property:
-Dmockserver.sslCertificateDomainName=...Environment Variable:
MOCKSERVER_SSL_CERTIFICATE_DOMAIN_NAME=...Property File:
mockserver.sslCertificateDomainName=...Example:
-Dmockserver.sslCertificateDomainName="localhost"The Subject Alternative Name (SAN) domain names for auto-generate TLS certificates as a comma separated list
Type: string Default: localhost
Java Code:
ConfigurationProperties.addSslSubjectAlternativeNameDomains(String... additionalSubjectAlternativeNameDomains)ConfigurationProperties.clearSslSubjectAlternativeNameDomains()System Property:
-Dmockserver.sslSubjectAlternativeNameDomains=...Environment Variable:
MOCKSERVER_SSL_SUBJECT_ALTERNATIVE_NAME_DOMAINS=...Property File:
mockserver.sslSubjectAlternativeNameDomains=...Example:
-Dmockserver.sslSubjectAlternativeNameDomains="localhost,www.foo.bar"The Subject Alternative Name (SAN) IP addresses for auto-generate TLS certificates as a comma separated list
Type: string Default: 127.0.0.1,0.0.0.0
Java Code:
ConfigurationProperties.addSslSubjectAlternativeNameIps(String... additionalSubjectAlternativeNameIps)ConfigurationProperties.clearSslSubjectAlternativeNameIps()System Property:
-Dmockserver.sslSubjectAlternativeNameIps=...Environment Variable:
MOCKSERVER_SSL_SUBJECT_ALTERNATIVE_NAME_IPS=...Property File:
mockserver.sslSubjectAlternativeNameIps=...Example:
-Dmockserver.sslSubjectAlternativeNameIps="127.0.0.1,0.0.0.0"The maximum number of dynamically-discovered Subject Alternative Names (SANs) the auto-generated server certificate will accumulate. MockServer adds a SAN for each new hostname it observes via SNI or the Host header and regenerates the leaf certificate each time. Without a cap, a client sending many distinct hostnames could grow the SAN list without bound, causing unbounded memory and CPU use and eventually producing a certificate too large to complete a TLS handshake.
When the cap is reached, the oldest dynamically-discovered entry is evicted and a warning is logged. Explicitly configured names — including the default localhost and any names set via sslSubjectAlternativeNameDomains or sslSubjectAlternativeNameIps — are never evicted.
Raise this value if you are proxying more than 100 distinct hostnames in a single MockServer instance and are seeing eviction warnings or intermittent certificate name-mismatch errors for hosts used earlier in a long-running session.
Type: integer Default: 100
Java Code:
ConfigurationProperties.maxSubjectAlternativeNames(int maxSubjectAlternativeNames)System Property:
-Dmockserver.maxSubjectAlternativeNames=...Environment Variable:
MOCKSERVER_MAX_SUBJECT_ALTERNATIVE_NAMES=...Property File:
mockserver.maxSubjectAlternativeNames=...Example:
-Dmockserver.maxSubjectAlternativeNames=200Number of days the auto-generated server (leaf) TLS certificate is valid for. The default of 397 keeps the certificate inside Apple's 825-day maximum for TLS server certificates (iOS 13 / macOS 10.15); the previous 10-year certificate exceeded this limit and can cause TLS handshakes to fail on Apple platforms. MockServer automatically regenerates the certificate well before it expires, so a long-running server never serves an expired certificate.
Raise this (for example to 3650) only if you depend on the previous long-lived certificate. A non-positive value falls back to the default. The dynamically generated Certificate Authority is unaffected and keeps its long (10 year) life.
Type: integer Default: 397
Java Code:
ConfigurationProperties.sslCertificateLeafValidityInDays(int sslCertificateLeafValidityInDays)System Property:
-Dmockserver.sslCertificateLeafValidityInDays=...Environment Variable:
MOCKSERVER_SSL_CERTIFICATE_LEAF_VALIDITY_IN_DAYS=...Property File:
mockserver.sslCertificateLeafValidityInDays=...Example:
-Dmockserver.sslCertificateLeafValidityInDays=3650Location of custom file for Certificate Authority for TLS, the private key must be a PKCS#8 or PKCS#1 PEM file and must match the TLS Certificate Authority X.509 Certificate.
To convert a PKCS#1 PEM file (i.e. default for Bouncy Castle) to a PKCS#8 PEM file the following command can be used: openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt
Type: string Default: the built-in MockServer CA private key (org/mockserver/socket/PKCS8CertificateAuthorityPrivateKey.pem on the classpath)
Java Code:
ConfigurationProperties.certificateAuthorityPrivateKey(String certificateAuthorityPrivateKey)System Property:
-Dmockserver.certificateAuthorityPrivateKey=...Environment Variable:
MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY=...Property File:
mockserver.certificateAuthorityPrivateKey=...Example:
-Dmockserver.certificateAuthorityPrivateKey="/some/existing/path"Location of custom file for Certificate Authority for TLS, the certificate must be a X.509 PEM file and must match the TLS Certificate Authority Private Key.
Type: string Default: the built-in MockServer CA certificate (org/mockserver/socket/CertificateAuthorityCertificate.pem on the classpath)
Java Code:
ConfigurationProperties.certificateAuthorityCertificate(String certificateAuthorityCertificate)System Property:
-Dmockserver.certificateAuthorityCertificate=...Environment Variable:
MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE=...Property File:
mockserver.certificateAuthorityCertificate=...Example:
-Dmockserver.certificateAuthorityCertificate="/some/existing/path"File system path or classpath location of a fixed custom private key for TLS connections into MockServer.
The private key must be a PKCS#8 or PKCS#1 PEM file and must be the private key corresponding to the x509CertificatePath X.509 (public key) configuration.
The certificateAuthorityCertificate configuration must be the Certificate Authority for the corresponding X.509 certificate (i.e. able to valid its signature), see: x509CertificatePath.
To convert a PKCS#1 (i.e. default for Bouncy Castle) to a PKCS#8 the following command can be used: openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt
This configuration will be ignored unless x509CertificatePath is also set.
Type: string Default: null
Java Code:
ConfigurationProperties.privateKeyPath(String privateKeyPath)System Property:
-Dmockserver.privateKeyPath=...Environment Variable:
MOCKSERVER_TLS_PRIVATE_KEY_PATH=...Property File:
mockserver.privateKeyPath=...Example:
-Dmockserver.privateKeyPath="/some/existing/path"File system path or classpath location of a fixed custom X.509 Certificate for TLS connections into MockServer
The certificate must be a X.509 PEM file and must be the public key corresponding to the privateKeyPath private key configuration.
The certificateAuthorityCertificate configuration must be the Certificate Authority for this certificate (i.e. able to valid its signature).
This configuration will be ignored unless privateKeyPath is also set.
Type: string Default: null
Java Code:
ConfigurationProperties.x509CertificatePath(String x509CertificatePath)System Property:
-Dmockserver.x509CertificatePath=...Environment Variable:
MOCKSERVER_TLS_X509_CERTIFICATE_PATH=...Property File:
mockserver.x509CertificatePath=...Example:
-Dmockserver.x509CertificatePath="/some/existing/path"Require mTLS (also called client authentication and two-way TLS) for all TLS connections / HTTPS requests to MockServer
Type: boolean Default: false
Java Code:
ConfigurationProperties.tlsMutualAuthenticationRequired(boolean enable)System Property:
-Dmockserver.tlsMutualAuthenticationRequired=...Environment Variable:
MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_REQUIRED=...Property File:
mockserver.tlsMutualAuthenticationRequired=...Example:
-Dmockserver.tlsMutualAuthenticationRequired="true"File system path or classpath location of custom mTLS (TLS client authentication) X.509 Certificate Chain for Trusting (i.e. signature verification of) Client X.509 Certificates, the certificate chain must be a X.509 PEM file.
This certificate chain will be used if MockServer performs mTLS (client authentication) for inbound TLS connections because tlsMutualAuthenticationRequired is enabled
This configuration property is also used for MockServerClient to trust outbound TLS X.509 certificates i.e. TLS connections to MockServer
Type: string Default: null
Java Code:
ConfigurationProperties.tlsMutualAuthenticationCertificateChain(String certificateChain)System Property:
-Dmockserver.tlsMutualAuthenticationCertificateChain=...Environment Variable:
MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=...Property File:
mockserver.tlsMutualAuthenticationCertificateChain=...Example:
-Dmockserver.tlsMutualAuthenticationCertificateChain="/some/existing/path"Configure trusted set of certificates for forwarded or proxied requests (i.e. TLS connections out of MockServer).
MockServer will only be able to establish a TLS connection to endpoints that have a trusted X.509 certificate according to the trust manager type, as follows:
Type: string Default: ANY
Java Code:
ConfigurationProperties.forwardProxyTLSX509CertificatesTrustManagerType(String trustManagerType)System Property:
-Dmockserver.forwardProxyTLSX509CertificatesTrustManagerType=...Environment Variable:
MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATES_TRUST_MANAGER_TYPE=...Property File:
mockserver.forwardProxyTLSX509CertificatesTrustManagerType=...Example:
-Dmockserver.forwardProxyTLSX509CertificatesTrustManagerType="CUSTOM"Whether to verify the upstream host name against its certificate when MockServer forwards or proxies over TLS with a validating trust manager (forwardProxyTLSX509CertificatesTrustManagerType of JVM or CUSTOM).
The default is true. Without host name verification, any certificate signed by a trusted CA — for any host name — would be accepted, which would leave MockServer open to a man-in-the-middle it believes it is protected from. So when you opt into real upstream validation (JVM or CUSTOM) the upstream host name is verified against the certificate as well.
This has no effect for the ANY trust manager type (the default), which deliberately trusts everything and performs no host name verification. Set this to false when you legitimately need to connect to an upstream whose certificate host name does not match the address you connect to (a common testing scenario) while still validating the certificate chain.
Type: boolean Default: true
Java Code:
ConfigurationProperties.forwardProxyTLSHostnameVerificationEnabled(false)System Property:
-Dmockserver.forwardProxyTLSHostnameVerificationEnabled=...Environment Variable:
MOCKSERVER_FORWARD_PROXY_TLS_HOSTNAME_VERIFICATION_ENABLED=...Property File:
mockserver.forwardProxyTLSHostnameVerificationEnabled=...Example:
-Dmockserver.forwardProxyTLSHostnameVerificationEnabled="false"File system path or classpath location of custom file for trusted X.509 Certificate Authority roots for forwarded or proxied requests (i.e. TLS connections out of MockServer), the certificate chain must be a X.509 PEM file.
MockServer will only be able to establish a TLS connection to endpoints that have an X.509 certificate chain that is signed by one of the provided custom certificates, i.e. where a path can be established from the endpoints X.509 certificate to one or more of the custom X.509 certificates provided.
This configuration only take effect if forwardProxyTLSX509CertificatesTrustManagerType is configured as CUSTOM otherwise this value is ignored.
Type: string Default: null
Java Code:
ConfigurationProperties.forwardProxyTLSCustomTrustX509Certificates(String customX509Certificates)System Property:
-Dmockserver.forwardProxyTLSCustomTrustX509Certificates=...Environment Variable:
MOCKSERVER_FORWARD_PROXY_TLS_CUSTOM_TRUST_X509_CERTIFICATES=...Property File:
mockserver.forwardProxyTLSCustomTrustX509Certificates=...Example:
-Dmockserver.forwardProxyTLSCustomTrustX509Certificates="/some/existing/path"File system path or classpath location of custom Private Key for forwarded or proxied requests (i.e. TLS connections out of MockServer), the private key must be a PKCS#8 or PKCS#1 PEM file
To convert a PKCS#1 (i.e. default for Bouncy Castle) to a PKCS#8 the following command can be used: openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt
This private key will be used if MockServer needs to perform mTLS (client authentication) for outbound TLS connections.
Type: string Default: null
Java Code:
ConfigurationProperties.forwardProxyPrivateKey(String privateKey)System Property:
-Dmockserver.forwardProxyPrivateKey=...Environment Variable:
MOCKSERVER_FORWARD_PROXY_TLS_PRIVATE_KEY=...Property File:
mockserver.forwardProxyPrivateKey=...Example:
-Dmockserver.forwardProxyPrivateKey="/some/existing/path"File system path or classpath location of custom X.509 Certificate Chain for forwarded or proxied requests (i.e. TLS connections out of MockServer), the certificates must be a X.509 PEM file
This certificate chain will be used if MockServer needs to perform mTLS (client authentication) for outbound TLS connections.
Type: string Default: null
Java Code:
ConfigurationProperties.forwardProxyCertificateChain(String certificateChain)System Property:
-Dmockserver.forwardProxyCertificateChain=...Environment Variable:
MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATE_CHAIN=...Property File:
mockserver.forwardProxyCertificateChain=...Example:
-Dmockserver.forwardProxyCertificateChain="/some/existing/path"Present a different client certificate and key for outbound mTLS depending on which upstream host MockServer is connecting to. By default the fixed outbound client key/certificate above are used for every upstream; this property lets you override them per host.
The value is a comma-separated list of host=certificateChainPath;privateKeyPath entries. When MockServer opens a TLS connection to a matching upstream host (matched case-insensitively), it presents that host's certificate/key pair; any host that is not listed falls back to the fixed outbound client key/certificate (or, if those are not set, MockServer's own generated certificate). Each certificate chain is an X.509 PEM file and each private key a PKCS#8 or PKCS#1 PEM file.
Type: string Default: null
Java Code:
ConfigurationProperties.forwardProxyClientCertificatesByHost(String clientCertificatesByHost)System Property:
-Dmockserver.forwardProxyClientCertificatesByHost=...Environment Variable:
MOCKSERVER_FORWARD_PROXY_CLIENT_CERTIFICATES_BY_HOST=...Property File:
mockserver.forwardProxyClientCertificatesByHost=...Example:
-Dmockserver.forwardProxyClientCertificatesByHost="api.internal=/certs/api-chain.pem;/certs/api-key.pem,billing.internal=/certs/billing-chain.pem;/certs/billing-key.pem"File system path or classpath location of custom mTLS (TLS client authentication) X.509 Certificate Chain for Trusting (i.e. signature verification of) MockServer X.509 Certificates, the certificate chain must be a X.509 PEM file. This certificate chain will only be used if MockServerClient performs TLS to calls to MockServer.
This settings is particularly used when connecting to MockServer via a load-balancer or other TLS terminating network infrastructure with its own X.509 Certificate.
This configuration property is also used for MockServer to trust inbound mTLS client authentication X.509 certificates
Type: string Default: null
Java Code:
ConfigurationProperties.tlsMutualAuthenticationCertificateChain(String certificateChain)System Property:
-Dmockserver.tlsMutualAuthenticationCertificateChain=...Environment Variable:
MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=...Property File:
mockserver.tlsMutualAuthenticationCertificateChain=...Example:
-Dmockserver.tlsMutualAuthenticationCertificateChain="/some/existing/path"