--- title: API Security description: Secure the MockServer control plane with mTLS client certificate authentication, JWT bearer tokens, or both, plus network and CORS hardening tips. layout: page pageOrder: 8 section: 'General' subsection: true sitemap: priority: 0.7 changefreq: 'monthly' lastmod: 2026-05-30T08:00:00+00:00 ---

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

{% include_subpage _includes/control_plane_authentication_mtls_configuration.html %}

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

{% include_subpage _includes/control_plane_authentication_jwt_configuration.html %}

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.