> ## Documentation Index
> Fetch the complete documentation index at: https://moeck.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Security

> Restrict who can create and modify expectations using JWT bearer token or mutual TLS authentication on the MockServer control plane.

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:

<CardGroup cols={2}>
  <Card title="JWT" icon="key">
    Clients include a bearer token in the `authorization` header. MockServer validates the token against a JWKS source.
  </Card>

  <Card title="mTLS" icon="certificate">
    Clients present an X.509 certificate. MockServer validates it against a trusted CA chain.
  </Card>
</CardGroup>

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

<Steps>
  <Step title="Configure the JWKS source">
    Provide a URL, file system path, or classpath location for the JSON Web Key Set used to verify token signatures:

    <CodeGroup>
      ```java Java theme={null}
      ConfigurationProperties.controlPlaneJWTAuthenticationRequired(true);
      ConfigurationProperties.controlPlaneJWTAuthenticationJWKSource("https://auth.example.com/.well-known/jwks.json");
      ```

      ```bash System property theme={null}
      -Dmockserver.controlPlaneJWTAuthenticationRequired=true
      -Dmockserver.controlPlaneJWTAuthenticationJWKSource=https://auth.example.com/.well-known/jwks.json
      ```

      ```bash Environment variable theme={null}
      MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_REQUIRED=true
      MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_JWK_SOURCE=https://auth.example.com/.well-known/jwks.json
      ```

      ```properties Property file theme={null}
      mockserver.controlPlaneJWTAuthenticationRequired=true
      mockserver.controlPlaneJWTAuthenticationJWKSource=https://auth.example.com/.well-known/jwks.json
      ```
    </CodeGroup>
  </Step>

  <Step title="Optionally restrict by audience">
    Require the JWT to include a specific `aud` claim:

    ```properties theme={null}
    mockserver.controlPlaneJWTAuthenticationExpectedAudience=https://mockserver.example.com
    ```
  </Step>

  <Step title="Optionally require specific claims">
    Require the JWT to contain particular claims with specific values (comma-separated `key=value` pairs):

    ```properties theme={null}
    mockserver.controlPlaneJWTAuthenticationMatchingClaims=scope=internal,sub=mockserver-admin
    ```

    Or require claims to be present with any value:

    ```properties theme={null}
    mockserver.controlPlaneJWTAuthenticationRequiredClaims=scope,sub
    ```
  </Step>
</Steps>

### JWT property reference

| Property                                                   | Environment variable                                            | Default | Description                             |
| ---------------------------------------------------------- | --------------------------------------------------------------- | ------- | --------------------------------------- |
| `mockserver.controlPlaneJWTAuthenticationRequired`         | `MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_REQUIRED`          | `false` | Enable JWT authentication               |
| `mockserver.controlPlaneJWTAuthenticationJWKSource`        | `MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_JWK_SOURCE`        | `null`  | URL or path to JWKS                     |
| `mockserver.controlPlaneJWTAuthenticationExpectedAudience` | `MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_EXPECTED_AUDIENCE` | `null`  | Required `aud` claim value              |
| `mockserver.controlPlaneJWTAuthenticationMatchingClaims`   | `MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_MATCHING_CLAIMS`   | `null`  | Required claims as `key=value` pairs    |
| `mockserver.controlPlaneJWTAuthenticationRequiredClaims`   | `MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_REQUIRED_CLAIMS`   | `null`  | Claims 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

<Steps>
  <Step title="Configure the trusted CA chain">
    Provide the CA certificate (or chain) that signed the client certificates you want to allow:

    <CodeGroup>
      ```java Java theme={null}
      ConfigurationProperties.controlPlaneTLSMutualAuthenticationRequired(true);
      ConfigurationProperties.controlPlaneTLSMutualAuthenticationCAChain("/certs/client-ca.pem");
      ```

      ```bash System property theme={null}
      -Dmockserver.controlPlaneTLSMutualAuthenticationRequired=true
      -Dmockserver.controlPlaneTLSMutualAuthenticationCAChain=/certs/client-ca.pem
      ```

      ```bash Environment variable theme={null}
      MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_REQUIRED=true
      MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=/certs/client-ca.pem
      ```

      ```properties Property file theme={null}
      mockserver.controlPlaneTLSMutualAuthenticationRequired=true
      mockserver.controlPlaneTLSMutualAuthenticationCAChain=/certs/client-ca.pem
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure client credentials for MockServerClient">
    If you use `MockServerClient` to manage expectations programmatically, provide the client private key and certificate it should present:

    <CodeGroup>
      ```java Java theme={null}
      ConfigurationProperties.controlPlanePrivateKeyPath("/certs/client-private-key.pem");
      ConfigurationProperties.controlPlaneX509CertificatePath("/certs/client-certificate.pem");
      ```

      ```bash System property theme={null}
      -Dmockserver.controlPlanePrivateKeyPath=/certs/client-private-key.pem
      -Dmockserver.controlPlaneX509CertificatePath=/certs/client-certificate.pem
      ```

      ```bash Environment variable theme={null}
      MOCKSERVER_CONTROL_PLANE_TLS_PRIVATE_KEY_PATH=/certs/client-private-key.pem
      MOCKSERVER_CONTROL_PLANE_TLS_X509_CERTIFICATE_PATH=/certs/client-certificate.pem
      ```

      ```properties Property file theme={null}
      mockserver.controlPlanePrivateKeyPath=/certs/client-private-key.pem
      mockserver.controlPlaneX509CertificatePath=/certs/client-certificate.pem
      ```
    </CodeGroup>

    The private key and certificate must be a valid pair, and the certificate must be signed by one of the CAs in `controlPlaneTLSMutualAuthenticationCAChain`.
  </Step>
</Steps>

### mTLS property reference

| Property                                                 | Environment variable                                                   | Default | Description                              |
| -------------------------------------------------------- | ---------------------------------------------------------------------- | ------- | ---------------------------------------- |
| `mockserver.controlPlaneTLSMutualAuthenticationRequired` | `MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_REQUIRED`          | `false` | Enable mTLS for control plane            |
| `mockserver.controlPlaneTLSMutualAuthenticationCAChain`  | `MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN` | `null`  | CA chain to validate client certificates |
| `mockserver.controlPlanePrivateKeyPath`                  | `MOCKSERVER_CONTROL_PLANE_TLS_PRIVATE_KEY_PATH`                        | `null`  | Client private key for MockServerClient  |
| `mockserver.controlPlaneX509CertificatePath`             | `MOCKSERVER_CONTROL_PLANE_TLS_X509_CERTIFICATE_PATH`                   | `null`  | Client 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](/configuration/tls) for details.