Multiple techniques can be used to lock down MockServer deployments, as follows:

  • limit network access to MockServer, i.e. only available on localhost
  • launch MockServer on-demand, i.e. just before tests, and shutdown immediately after
  • disable or restrict cross-site requests using CORS
  • restrict content or functionality of javascript, velocity or mustache templates
  • authenticate all TCP connections using mTLS
  • authenticate all REST API i.e. control plane requests using mTLS
  • authenticate all REST API i.e. control plane requests using JWT
  • set security-focused configuration property values — see Configuration Hardening below

Important: MockServer does not currently support HTTP proxy authentication (Proxy-Authenticate / Proxy-Authorization headers). The authentication mechanisms described on this page secure the control plane (expectation management, verification, retrieval, etc.), not the data plane when MockServer is used as an HTTP proxy. If you need to test proxy authentication, you must use a different proxy server that supports it.

Common confusion: The MockServerClient.withProxyConfiguration() method configures how the client connects to MockServer through an upstream proxy—it does not add authentication to MockServer itself. See the client documentation for details.

 

Control Plane Authentication

Authentication can be enabled for all control plane requests (i.e. create expectations, clear, reset, verify, retrieve, stop, etc) using either mTLS, JWT or both.

If both mTLS and JWT are enabled mTLS will be validated first.

 

Control Plane mTLS Authentication

When mTLS authentication is enabled all control plane requests need to be received over a mTLS connection where the client's X509 certificates can be validated using the controlPlaneTLSMutualAuthenticationCAChain

Enable mTLS authentication for control plane interactions (i.e. create expectations, clear, reset, verify, retrieve, stop, etc)

If enabled then all control plane requests need to be received over a mTLS connection where the client's X509 certificates will be validated using the controlPlaneTLSMutualAuthenticationCAChain

It is possible to enable both controlPlaneJWTAuthenticationRequired and controlPlaneTLSMutualAuthenticationRequired but the mTLS will be checked first.

Type: boolean Default: false

Java Code:

ConfigurationProperties.controlPlaneTLSMutualAuthenticationRequired(boolean controlPlaneTLSMutualAuthenticationRequired)

System Property:

-Dmockserver.controlPlaneTLSMutualAuthenticationRequired=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_REQUIRED=...

Property File:

mockserver.controlPlaneTLSMutualAuthenticationRequired=...

Example:

-Dmockserver.controlPlaneTLSMutualAuthenticationRequired="true"

File system path or classpath location of the CA (i.e. trust) chain to use to validate client X509 certificates if controlPlaneTLSMutualAuthenticationRequired is enabled

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneTLSMutualAuthenticationCAChain(String controlPlaneTLSMutualAuthenticationCAChain)

System Property:

-Dmockserver.controlPlaneTLSMutualAuthenticationCAChain=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=...

Property File:

mockserver.controlPlaneTLSMutualAuthenticationCAChain=...

Example:

-Dmockserver.controlPlaneTLSMutualAuthenticationCAChain="/some/existing/path"

File system path or classpath location of the private key used by MockServerClient when controlPlaneTLSMutualAuthenticationRequired is enabled to ensure control plane request are correctly authorised

For control plane requests to be authorised the private key controlPlanePrivateKeyPath and certificate controlPlanePrivateKeyPath must:

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlanePrivateKeyPath(String controlPlanePrivateKeyPath)

System Property:

-Dmockserver.controlPlanePrivateKeyPath=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_TLS_PRIVATE_KEY_PATH=...

Property File:

mockserver.controlPlanePrivateKeyPath=...

Example:

-Dmockserver.controlPlanePrivateKeyPath="/some/existing/path"

File system path or classpath location of the certificate used by MockServerClient when controlPlaneTLSMutualAuthenticationRequired is enabled to ensure control plane request are correctly authorised

For control plane requests to be authorised the private key controlPlanePrivateKeyPath and certificate controlPlanePrivateKeyPath must:

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneX509CertificatePath(String controlPlaneX509CertificatePath)

System Property:

-Dmockserver.controlPlaneX509CertificatePath=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_TLS_X509_CERTIFICATE_PATH=...

Property File:

mockserver.controlPlaneX509CertificatePath=...

Example:

-Dmockserver.controlPlaneX509CertificatePath="/some/existing/path"
 

Control Plane JWT Authentication

When JWT authentication is enabled all control plane requests need and JWT via a authorization header which is validated using the controlPlaneJWTAuthenticationJWKSource

Enable JWT authentication for control plane interactions (i.e. create expectations, clear, reset, verify, retrieve, stop, etc)

If enabled then all control plane requests need and JWT via a authorization header which is validated using the controlPlaneJWTAuthenticationJWKSource

It is possible to enable both controlPlaneJWTAuthenticationRequired and controlPlaneTLSMutualAuthenticationRequired but the mTLS will be checked first.

Type: boolean Default: false

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationRequired(boolean controlPlaneJWTAuthenticationRequired)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationRequired=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_REQUIRED=...

Property File:

mockserver.controlPlaneJWTAuthenticationRequired=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationRequired="true"

URL, file system path or classpath location of the JWK source when controlPlaneJWTAuthenticationRequired is enabled to validate JWT signatures

For control plane requests to be authorised:

  • they must include an authorization header, with a Bearer auth scheme, containing a JWT
  • the JWT should be validated by a key in the JWK source

For details of JWK see the JWK specification

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationJWKSource(String controlPlaneJWTAuthenticationJWKSource)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationJWKSource=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_JWK_SOURCE=...

Property File:

mockserver.controlPlaneJWTAuthenticationJWKSource=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationJWKSource="/some/existing/path"

Audience claim (i.e. aud) required when JWT authentication is enabled for control plane requests

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationExpectedAudience(String controlPlaneJWTAuthenticationExpectedAudience)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationExpectedAudience=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_EXPECTED_AUDIENCE=...

Property File:

mockserver.controlPlaneJWTAuthenticationExpectedAudience=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationExpectedAudience="/some/existing/path"

Matching claims expected when JWT authentication is enabled for control plane requests

Value should be string with comma separated key=value items, for example: scope=internal public,sub=some_subject

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationMatchingClaims(Map<String, String> controlPlaneJWTAuthenticationMatchingClaims)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationMatchingClaims=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_MATCHING_CLAIMS=...

Property File:

mockserver.controlPlaneJWTAuthenticationMatchingClaims=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationMatchingClaims="scope=internal,sub=user-123"

Required claims that should exist (i.e. with any value) when JWT authentication is enabled for control plane requests

Value should be string with comma separated values, for example: scope,sub

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationRequiredClaims(Set<String> controlPlaneJWTAuthenticationRequiredClaims)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationRequiredClaims=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_REQUIRED_CLAIMS=...

Property File:

mockserver.controlPlaneJWTAuthenticationRequiredClaims=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationRequiredClaims="scope,sub"
 

Configuration Hardening

For the most security-focused deployment, set the configuration properties below to the values shown. Each can be set as a Java system property (-Dmockserver.<name>=<value>), an environment variable (MOCKSERVER_<NAME>), or in a properties file — see Configuration Properties for the exact syntax and full description of each.

 

Network exposure

  • mockserver.localBoundIP=127.0.0.1 — bind the listener to the loopback interface so MockServer is reachable only from the local host. When running inside a container, set this to 0.0.0.0 and restrict access at the container, network, or orchestration layer instead.
  • mockserver.attemptToProxyIfNoMatchingExpectation=false — return 404 Not Found for any request that matches no expectation, so MockServer serves only the traffic you have explicitly defined and does not forward unmatched requests upstream.
 

Forwarding & proxying

  • mockserver.forwardProxyBlockPrivateNetworks=true — reject forward and proxy targets that resolve to loopback, link-local, RFC 1918 private, or cloud-metadata addresses (e.g. 169.254.169.254), keeping forwarded requests off internal networks (SSRF protection).
  • mockserver.forwardProxyTLSX509CertificatesTrustManagerType=JVM — validate upstream HTTPS certificates against the JDK trust store, exactly as a standard Java HTTPS client would. To trust a specific private CA, use =CUSTOM together with mockserver.forwardProxyTLSCustomTrustX509Certificates pointing at your CA bundle.
 

TLS protocols

  • mockserver.tlsAllowInsecureProtocols=false — negotiate TLSv1.2 and above only, excluding the deprecated TLSv1 and TLSv1.1 protocols. Add TLSv1.3 to mockserver.tlsProtocols to require the most modern protocol.
 

Response template execution

If you use response templates, restrict what they can reach (templates you do not use carry no risk):

  • mockserver.velocityDisallowClassLoading=true — run Velocity templates with a secure uberspector so they cannot load arbitrary Java classes.
  • mockserver.javascriptDisallowedClasses=... — restrict the Java classes JavaScript templates may reach via Java.type(...); deny high-risk classes such as java.lang.Runtime, java.lang.ProcessBuilder, java.lang.System, java.lang.Class, java.lang.ClassLoader, java.io.File, and java.nio.file.Files.
 

Request parsing limits

Bound the size of inbound request lines, headers, and chunks so a single client cannot exhaust memory with an oversized request:

  • mockserver.maxInitialLineLength=8192 — cap the request line (method + URI + version) at 8 KiB.
  • mockserver.maxHeaderSize=16384 — cap the combined request headers at 16 KiB.
  • mockserver.maxChunkSize=16384 — cap a single chunked-transfer-encoding chunk at 16 KiB.

The body-size limits mockserver.maxRequestBodySize and mockserver.maxResponseBodySize provide complementary bounds on payload size.

 

Control plane & CORS

  • Require authentication on every control-plane request — enable mTLS and/or JWT as described above.
  • mockserver.corsAllowOrigin — set this to the specific origin(s) you trust rather than allowing any origin, and keep mockserver.corsAllowCredentials=false unless credentialed cross-origin requests are genuinely required. See CORS.

See Also