Skip to main content
By default, anyone who can reach MockServer’s port can create or modify expectations. In shared or production-like environments you may want to restrict this. MockServer supports authentication on the control plane — the REST API used to create expectations, clear state, verify requests, and so on. Data plane requests (the mocked responses your application receives) are not affected by control plane authentication.

​
Authentication methods

You can enable either or both authentication methods:

JWT

Clients include a bearer token in the authorization header. MockServer validates the token against a JWKS source.

mTLS

Clients present an X.509 certificate. MockServer validates it against a trusted CA chain.
If both are enabled, mTLS is validated first.

​
JWT authentication

When JWT authentication is enabled, all control plane requests must include an Authorization: Bearer <token> header. MockServer validates the JWT signature using keys from the configured JWKS source.

​
Enable JWT authentication

1

Configure the JWKS source

Provide a URL, file system path, or classpath location for the JSON Web Key Set used to verify token signatures:
2

Optionally restrict by audience

Require the JWT to include a specific aud claim:
3

Optionally require specific claims

Require the JWT to contain particular claims with specific values (comma-separated key=value pairs):
Or require claims to be present with any value:

​
JWT property reference

​
mTLS authentication

When mTLS authentication is enabled, all control plane requests must arrive over a mutual TLS connection. MockServer validates the client’s X.509 certificate against the configured CA chain.

​
Enable mTLS authentication

1

Configure the trusted CA chain

Provide the CA certificate (or chain) that signed the client certificates you want to allow:
2

Configure client credentials for MockServerClient

If you use MockServerClient to manage expectations programmatically, provide the client private key and certificate it should present:
The private key and certificate must be a valid pair, and the certificate must be signed by one of the CAs in controlPlaneTLSMutualAuthenticationCAChain.

​
mTLS property reference

​
Other security options

In addition to control plane authentication, consider these measures for production environments:
  • Restrict network access — run MockServer on localhost or a private network so it is not reachable from outside your test infrastructure.
  • Short-lived instances — start MockServer just before your tests and stop it immediately after to minimize the window of exposure.
  • Restrict CORS — keep enableCORSForAPI and enableCORSForAllResponses disabled unless your use case requires cross-origin requests.
  • Restrict templates — limit what JavaScript, Velocity, or Mustache templates can do using the template restriction configuration properties.
  • All-connections mTLS — use tlsMutualAuthenticationRequired to require client certificates on all TLS connections, not just control plane requests. See TLS / HTTPS for details.