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.
Type: string Default: null
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,TLSv1.1,TLSv1.2 which includes TLSv1 and TLSv1.1 for backward compatibility. These older protocols are deprecated and considered insecure by most security standards.
To enable TLS 1.3, add TLSv1.3 to the list. To use only modern protocols, set the value to TLSv1.2,TLSv1.3.
Note: TLS 1.3 requires Java 11 or later. MockServer's default includes TLSv1 and TLSv1.1 for backward compatibility but you should restrict protocols to TLSv1.2 and TLSv1.3 in production-like environments.
Type: string Default: TLSv1,TLSv1.1,TLSv1.2
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"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"Location 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: null
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: null
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"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"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"