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:
ConfigurationProperties.controlPlaneJWTAuthenticationRequired(true);
ConfigurationProperties.controlPlaneJWTAuthenticationJWKSource("https://auth.example.com/.well-known/jwks.json");
2

Optionally restrict by audience

Require the JWT to include a specific aud claim:
mockserver.controlPlaneJWTAuthenticationExpectedAudience=https://mockserver.example.com
3

Optionally require specific claims

Require the JWT to contain particular claims with specific values (comma-separated key=value pairs):
mockserver.controlPlaneJWTAuthenticationMatchingClaims=scope=internal,sub=mockserver-admin
Or require claims to be present with any value:
mockserver.controlPlaneJWTAuthenticationRequiredClaims=scope,sub

​
JWT property reference

PropertyEnvironment variableDefaultDescription
mockserver.controlPlaneJWTAuthenticationRequiredMOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_REQUIREDfalseEnable JWT authentication
mockserver.controlPlaneJWTAuthenticationJWKSourceMOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_JWK_SOURCEnullURL or path to JWKS
mockserver.controlPlaneJWTAuthenticationExpectedAudienceMOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_EXPECTED_AUDIENCEnullRequired aud claim value
mockserver.controlPlaneJWTAuthenticationMatchingClaimsMOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_MATCHING_CLAIMSnullRequired claims as key=value pairs
mockserver.controlPlaneJWTAuthenticationRequiredClaimsMOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_REQUIRED_CLAIMSnullClaims that must be present (any value)

​
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:
ConfigurationProperties.controlPlaneTLSMutualAuthenticationRequired(true);
ConfigurationProperties.controlPlaneTLSMutualAuthenticationCAChain("/certs/client-ca.pem");
2

Configure client credentials for MockServerClient

If you use MockServerClient to manage expectations programmatically, provide the client private key and certificate it should present:
ConfigurationProperties.controlPlanePrivateKeyPath("/certs/client-private-key.pem");
ConfigurationProperties.controlPlaneX509CertificatePath("/certs/client-certificate.pem");
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

PropertyEnvironment variableDefaultDescription
mockserver.controlPlaneTLSMutualAuthenticationRequiredMOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_REQUIREDfalseEnable mTLS for control plane
mockserver.controlPlaneTLSMutualAuthenticationCAChainMOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAINnullCA chain to validate client certificates
mockserver.controlPlanePrivateKeyPathMOCKSERVER_CONTROL_PLANE_TLS_PRIVATE_KEY_PATHnullClient private key for MockServerClient
mockserver.controlPlaneX509CertificatePathMOCKSERVER_CONTROL_PLANE_TLS_X509_CERTIFICATE_PATHnullClient certificate for MockServerClient

​
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.