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

Proxy Authentication: When MockServer is used as an HTTP proxy, it supports HTTP Basic proxy authentication (RFC 7235) on the data plane via three configuration properties: proxyAuthenticationUsername, proxyAuthenticationPassword, and proxyAuthenticationRealm. When these are configured, MockServer responds with 407 Proxy Authentication Required and a Proxy-Authenticate: Basic realm="…" header to any CONNECT or forwarded request that does not include valid Proxy-Authorization credentials. The authentication mechanisms described below secure the control plane (expectation management, verification, retrieval, etc.), which is separate from this data-plane proxy authentication.

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 controlPlaneX509CertificatePath 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 controlPlaneX509CertificatePath 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="mockserver-control-plane"

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"
 

Control Plane OIDC Authentication

When OIDC authentication is enabled all control plane requests need a Bearer access token via an authorization header issued by an external OpenID Connect identity provider. The token signature is verified against the provider's JWK set (configured directly via controlPlaneOidcJwksUri or discovered from controlPlaneOidcIssuer), and its issuer, audience, expiry and required scopes are checked. The verified subject is recorded as the principal in the control plane audit log.

Enable verified OIDC authentication for control plane interactions (i.e. create expectations, clear, reset, verify, retrieve, stop, etc) using access tokens issued by an external OpenID Connect identity provider

If enabled then all control plane requests must include a Bearer access token via an authorization header. The token signature is verified against the provider's JWK set, and its issuer, audience, expiry and required scopes are checked. The verified subject (sub) is recorded as the principal in the control plane audit log.

For security, the OIDC handler enforces the following secure-by-default requirements (MockServer will refuse to start the OIDC handler, and fail every control plane request closed with a 401, if any are not met):

  • At least one of controlPlaneOidcIssuer or controlPlaneOidcAudience must be set — without either, any validly-signed token from the JWK set would be accepted regardless of who it was issued for.
  • A remote controlPlaneOidcJwksUri (or issuer used for discovery) must use https://. Plaintext http:// is allowed only for localhost/loopback (local testing).
  • Tokens must carry an exp (expiry) claim, and are verified only against asymmetric signing algorithms (RS*, PS*, ES*, EdDSA) — HMAC and unsigned (alg=none) tokens are always rejected.

When a control plane request fails OIDC authentication the client receives a generic Unauthorized for control plane response; the detailed reason (e.g. expected issuer/audience/scopes) is written only to the MockServer server log.

It is possible to enable controlPlaneOidcAuthenticationRequired alongside controlPlaneTLSMutualAuthenticationRequired and/or controlPlaneJWTAuthenticationRequired, in which case every enabled handler must pass.

Type: boolean Default: false

Java Code:

ConfigurationProperties.controlPlaneOidcAuthenticationRequired(boolean controlPlaneOidcAuthenticationRequired)

System Property:

-Dmockserver.controlPlaneOidcAuthenticationRequired=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_AUTHENTICATION_REQUIRED=...

Property File:

mockserver.controlPlaneOidcAuthenticationRequired=...

Example:

-Dmockserver.controlPlaneOidcAuthenticationRequired="true"

Issuer (i.e. iss) required on control plane OIDC tokens. When controlPlaneOidcJwksUri is not set, the JWKS URI is discovered from this issuer's OIDC discovery document at {issuer}/.well-known/openid-configuration.

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneOidcIssuer(String controlPlaneOidcIssuer)

System Property:

-Dmockserver.controlPlaneOidcIssuer=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_ISSUER=...

Property File:

mockserver.controlPlaneOidcIssuer=...

Example:

-Dmockserver.controlPlaneOidcIssuer="https://idp.example.com"

JWKS URI used to verify control plane OIDC token signatures. If not set, it is discovered from the issuer's OIDC discovery document. A remote URI must use https:// (plaintext http:// is permitted only to localhost/loopback); a file or classpath path may also be used.

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneOidcJwksUri(String controlPlaneOidcJwksUri)

System Property:

-Dmockserver.controlPlaneOidcJwksUri=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_JWKS_URI=...

Property File:

mockserver.controlPlaneOidcJwksUri=...

Example:

-Dmockserver.controlPlaneOidcJwksUri="https://idp.example.com/.well-known/jwks.json"

Audience claim (i.e. aud) required on control plane OIDC tokens.

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneOidcAudience(String controlPlaneOidcAudience)

System Property:

-Dmockserver.controlPlaneOidcAudience=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_AUDIENCE=...

Property File:

mockserver.controlPlaneOidcAudience=...

Example:

-Dmockserver.controlPlaneOidcAudience="mockserver-control-plane"

Scopes that must all be present in a control plane OIDC token before it is accepted.

Value should be a string with comma separated values, for example: mockserver.read,mockserver.write

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneOidcRequiredScopes(Set<String> controlPlaneOidcRequiredScopes)

System Property:

-Dmockserver.controlPlaneOidcRequiredScopes=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_REQUIRED_SCOPES=...

Property File:

mockserver.controlPlaneOidcRequiredScopes=...

Example:

-Dmockserver.controlPlaneOidcRequiredScopes="mockserver.read,mockserver.write"

Name of the claim holding granted scopes on a control plane OIDC token. Default scope is read as a space-delimited string; array claims such as scp, roles or groups are also supported.

Type: string Default: scope

Java Code:

ConfigurationProperties.controlPlaneOidcScopeClaim(String controlPlaneOidcScopeClaim)

System Property:

-Dmockserver.controlPlaneOidcScopeClaim=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_SCOPE_CLAIM=...

Property File:

mockserver.controlPlaneOidcScopeClaim=...

Example:

-Dmockserver.controlPlaneOidcScopeClaim="scp"

Enable coarse role-based authorization of control plane requests. Once a request is authenticated, the verified principal's scopes/groups are mapped (via Control Plane Scope Mapping) to one of three hierarchical roles — read, mutate or admin (admin satisfies mutate satisfies read). Reads (retrieve/verify/diff and all GETs) require read; every other operation (creating expectations, clear, reset, etc.) requires mutate. A principal without a sufficient role is rejected with 403 Forbidden and the denial is audited with outcome FORBIDDEN.

Authorization requires a verified principal with mapped scopes, so it should be used together with control plane OIDC authentication. It is off by default; when disabled, an authenticated request is never additionally authorized.

Type: boolean Default: false

Java Code:

ConfigurationProperties.controlPlaneAuthorizationEnabled(boolean enable)

System Property:

-Dmockserver.controlPlaneAuthorizationEnabled=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_AUTHORIZATION_ENABLED=...

Property File:

mockserver.controlPlaneAuthorizationEnabled=...

Example:

-Dmockserver.controlPlaneAuthorizationEnabled="true"

Mapping from a verified scope/group value to a coarse control plane role (read, mutate or admin), used when Control Plane Authorization Enabled is true.

Value should be a comma separated list of value=role pairs, for example: platform-admins=admin,qa-team=mutate,viewers=read. Unrecognised roles and malformed pairs are ignored.

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneScopeMapping(Map<String, ControlPlaneRole> controlPlaneScopeMapping)

System Property:

-Dmockserver.controlPlaneScopeMapping=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_SCOPE_MAPPING=...

Property File:

mockserver.controlPlaneScopeMapping=...

Example:

-Dmockserver.controlPlaneScopeMapping="platform-admins=admin,qa-team=mutate,viewers=read"
 

Control Plane Authorization

Once a principal has been authenticated, you can layer a coarse role-based authorization check on top. Authorization maps the verified principal's OIDC scopes or groups to one of three hierarchical roles and enforces them on every control-plane operation.

Prerequisite: Authorization requires a verified principal, so OIDC authentication must be configured. Without authentication there is no principal and authorization has nothing to enforce.

Important limitations:

  • The endpoints /mockserver/bind, /mockserver/stop, and /mockserver/status are neither authenticated nor authorized — they are always reachable.
  • MockServer's own MCP control plane (/mockserver/mcp) is authenticated (the bearer token is validated), but per-tool authorization is not yet enforced. Treat any authenticated MCP session as mutate-capable.
 

Roles

The three roles form a strict hierarchy. A principal granted a higher role satisfies every requirement at or below it:

RolePermitsExamples
readRead-only control-plane operationsretrieve, verify, verifySequence, explainUnmatched, debugMismatch
mutateEverything read permits, plus all mutating operationsexpectation, clear, reset, configuration, chaosExperiment, LLM endpoints
adminEverything mutate permits (reserved for future fine-grained admin operations)Currently identical to mutate
 

Configuration

Enable authorization with controlPlaneAuthorizationEnabled (default false) and map scope/group values to roles with controlPlaneScopeMapping:

PropertyEnvironment VariableDefaultDescription
mockserver.controlPlaneAuthorizationEnabled MOCKSERVER_CONTROL_PLANE_AUTHORIZATION_ENABLED false Enable coarse role-based authorization of all control-plane requests. Requires a verified principal (OIDC authentication must be configured).
mockserver.controlPlaneScopeMapping MOCKSERVER_CONTROL_PLANE_SCOPE_MAPPING empty Comma-separated scope=role pairs mapping a principal's OIDC scope or group value to a role (read, mutate, or admin). Example: platform-admins=admin,qa-team=mutate,viewers=read

Example — system property configuration:

-Dmockserver.controlPlaneAuthorizationEnabled=true
-Dmockserver.controlPlaneScopeMapping=platform-admins=admin,qa-team=mutate,viewers=read

Example — Java programmatic configuration:

ConfigurationProperties.controlPlaneAuthorizationEnabled(true);
ConfigurationProperties.controlPlaneScopeMapping(Map.of(
    "platform-admins", ControlPlaneRole.ADMIN,
    "qa-team",         ControlPlaneRole.MUTATE,
    "viewers",         ControlPlaneRole.READ
));
 

Behaviour

  • Fail-closed: a principal whose scopes do not map to any role in controlPlaneScopeMapping is denied every mutation (and every read unless a read-or-higher role is mapped). An unmapped or blank role value grants nothing.
  • Denied mutations return HTTP 403. The response body is a generic Forbidden for control plane message. The detailed reason (granted role vs. required role) is logged server-side only so authorization policy is not disclosed to the client.
  • Denials are recorded in the audit log with outcome=FORBIDDEN. Successful authorized requests are recorded with outcome=AUTHORIZED.
  • A principal may hold multiple scopes. The highest-ranked role from all matched scopes wins (e.g. a token with both viewers and qa-team scopes is granted mutate from the example mapping above).
 

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