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

# TLS / HTTPS

> Configure TLS for inbound HTTPS connections, mutual TLS client authentication, and outbound TLS when forwarding to HTTPS backends.

MockServer uses port unification so HTTP and HTTPS are both handled on the same port. When a request arrives over TLS, MockServer detects and decrypts it automatically — no separate port is required.

MockServer supports TLS in three areas:

<CardGroup cols={3}>
  <Card title="Inbound TLS" icon="arrow-down-to-line">
    Accept HTTPS requests from clients connecting to MockServer.
  </Card>

  <Card title="Inbound mTLS" icon="id-card">
    Require connecting clients to present a valid X.509 certificate.
  </Card>

  <Card title="Outbound TLS" icon="arrow-up-from-line">
    Connect to HTTPS backends when forwarding or proxying requests.
  </Card>
</CardGroup>

## Trusting MockServer's certificate

MockServer dynamically generates its TLS certificates, signed by its own Certificate Authority (CA). HTTP clients must trust this CA to establish a TLS connection without errors.

### Add the CA to the JVM trust store

Use the Java `keytool` command to import the MockServer CA certificate:

```bash theme={null}
keytool -import -v \
  -keystore /usr/lib/jvm/java-17-openjdk/lib/security/cacerts \
  -alias mockserver-ca \
  -file CertificateAuthorityCertificate.pem \
  -storepass changeit \
  -trustcacerts \
  -noprompt
```

### Configure the SSL socket factory in tests

For Java test suites, configure the default SSL socket factory to accept MockServer certificates:

```java theme={null}
import org.mockserver.integration.ClientAndServer;
import org.mockserver.logging.MockServerLogger;
import org.mockserver.socket.tls.KeyStoreFactory;
import javax.net.ssl.HttpsURLConnection;

@BeforeClass
public static void startMockServer() {
    HttpsURLConnection.setDefaultSSLSocketFactory(
        new KeyStoreFactory(new MockServerLogger()).sslContext().getSocketFactory()
    );
    mockServer = ClientAndServer.startClientAndServer(1080);
}
```

<Warning>
  Do not add the built-in MockServer CA to your operating system trust store unless you have also enabled `dynamicallyCreateCertificateAuthorityCertificate`. The built-in CA private key is publicly available in the MockServer repository, which would expose your machine to man-in-the-middle attacks.
</Warning>

## Inbound TLS configuration

### Use a dynamically generated CA

By default, MockServer uses a fixed built-in CA. Enable this property to generate a unique CA certificate and private key on first startup instead:

<CodeGroup>
  ```java Java theme={null}
  ConfigurationProperties.dynamicallyCreateCertificateAuthorityCertificate(true);
  ConfigurationProperties.directoryToSaveDynamicSSLCertificate("/etc/mockserver/certs");
  ```

  ```bash System property theme={null}
  -Dmockserver.dynamicallyCreateCertificateAuthorityCertificate=true
  -Dmockserver.directoryToSaveDynamicSSLCertificate=/etc/mockserver/certs
  ```

  ```bash Environment variable theme={null}
  MOCKSERVER_DYNAMICALLY_CREATE_CERTIFICATE_AUTHORITY_CERTIFICATE=true
  MOCKSERVER_CERTIFICATE_DIRECTORY_TO_SAVE_DYNAMIC_SSL_CERTIFICATE=/etc/mockserver/certs
  ```

  ```properties Property file theme={null}
  mockserver.dynamicallyCreateCertificateAuthorityCertificate=true
  mockserver.directoryToSaveDynamicSSLCertificate=/etc/mockserver/certs
  ```
</CodeGroup>

The generated CA certificate and private key are saved to the specified directory. On subsequent restarts, MockServer reuses existing files rather than generating new ones.

### Use a custom CA certificate

To sign MockServer's generated certificates with your own CA, provide both a private key and X.509 certificate in PEM format:

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

  ```bash System property theme={null}
  -Dmockserver.certificateAuthorityPrivateKey=/certs/ca-private-key.pem
  -Dmockserver.certificateAuthorityCertificate=/certs/ca-certificate.pem
  ```

  ```bash Environment variable theme={null}
  MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY=/certs/ca-private-key.pem
  MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE=/certs/ca-certificate.pem
  ```

  ```properties Property file theme={null}
  mockserver.certificateAuthorityPrivateKey=/certs/ca-private-key.pem
  mockserver.certificateAuthorityCertificate=/certs/ca-certificate.pem
  ```
</CodeGroup>

The private key must be in PKCS#8 or PKCS#1 PEM format. To convert a PKCS#1 key to PKCS#8:

```bash theme={null}
openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt
```

### Use a fixed server certificate

To use a specific certificate for all TLS connections into MockServer rather than having one generated, provide both the private key and X.509 certificate:

```properties theme={null}
mockserver.privateKeyPath=/certs/server-private-key.pem
mockserver.x509CertificatePath=/certs/server-certificate.pem
```

Both properties must be set together. The `certificateAuthorityCertificate` must be the CA that signed this X.509 certificate.

### Configure Subject Alternative Names

MockServer automatically updates the Subject Alternative Names (SANs) in its certificate as it sees new hostnames. To lock down SANs to a fixed list:

```properties theme={null}
mockserver.preventCertificateDynamicUpdate=true
mockserver.sslCertificateDomainName=localhost
mockserver.sslSubjectAlternativeNameDomains=localhost,api.example.com
mockserver.sslSubjectAlternativeNameIps=127.0.0.1,0.0.0.0
```

## Inbound mTLS (client certificate authentication)

Require all clients connecting to MockServer to present a valid certificate signed by a trusted CA:

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

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

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

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

`tlsMutualAuthenticationCertificateChain` is the PEM file containing the CA (or chain) that signed trusted client certificates. Any client presenting a certificate not signed by this CA will be rejected.

<Note>
  When `tlsMutualAuthenticationRequired` is enabled, the `tlsMutualAuthenticationCertificateChain` is also used by MockServerClient when it connects to MockServer over TLS.
</Note>

## Outbound TLS (forwarding to HTTPS backends)

When MockServer forwards or proxies requests to HTTPS backends, it needs to establish its own TLS connection outbound.

### Configure which certificates to trust

Control which server certificates MockServer accepts for outbound connections using the trust manager type:

| Value    | Behavior                                                                           |
| -------- | ---------------------------------------------------------------------------------- |
| `ANY`    | Trust all certificates (default). No hostname verification.                        |
| `JVM`    | Trust certificates in the JVM's default trust store.                               |
| `CUSTOM` | Trust only certificates specified by `forwardProxyTLSCustomTrustX509Certificates`. |

<CodeGroup>
  ```java Java theme={null}
  ConfigurationProperties.forwardProxyTLSX509CertificatesTrustManagerType("CUSTOM");
  ConfigurationProperties.forwardProxyTLSCustomTrustX509Certificates("/certs/backend-ca.pem");
  ```

  ```bash System property theme={null}
  -Dmockserver.forwardProxyTLSX509CertificatesTrustManagerType=CUSTOM
  -Dmockserver.forwardProxyTLSCustomTrustX509Certificates=/certs/backend-ca.pem
  ```

  ```bash Environment variable theme={null}
  MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATES_TRUST_MANAGER_TYPE=CUSTOM
  MOCKSERVER_FORWARD_PROXY_TLS_CUSTOM_TRUST_X509_CERTIFICATES=/certs/backend-ca.pem
  ```

  ```properties Property file theme={null}
  mockserver.forwardProxyTLSX509CertificatesTrustManagerType=CUSTOM
  mockserver.forwardProxyTLSCustomTrustX509Certificates=/certs/backend-ca.pem
  ```
</CodeGroup>

### Use a client certificate for outbound mTLS

If the backend requires MockServer to present a client certificate (mTLS), provide the private key and certificate chain for outbound connections:

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

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

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

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

## Reference: TLS properties

| Property                                                      | Environment variable                                                | Default | Description                                        |
| ------------------------------------------------------------- | ------------------------------------------------------------------- | ------- | -------------------------------------------------- |
| `mockserver.dynamicallyCreateCertificateAuthorityCertificate` | `MOCKSERVER_DYNAMICALLY_CREATE_CERTIFICATE_AUTHORITY_CERTIFICATE`   | `false` | Generate a unique CA on first startup              |
| `mockserver.directoryToSaveDynamicSSLCertificate`             | `MOCKSERVER_CERTIFICATE_DIRECTORY_TO_SAVE_DYNAMIC_SSL_CERTIFICATE`  | `null`  | Directory to save the generated CA                 |
| `mockserver.certificateAuthorityPrivateKey`                   | `MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY`                      | `null`  | Custom CA private key (PEM)                        |
| `mockserver.certificateAuthorityCertificate`                  | `MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE`                 | `null`  | Custom CA certificate (PEM)                        |
| `mockserver.privateKeyPath`                                   | `MOCKSERVER_TLS_PRIVATE_KEY_PATH`                                   | `null`  | Fixed server private key (PEM)                     |
| `mockserver.x509CertificatePath`                              | `MOCKSERVER_TLS_X509_CERTIFICATE_PATH`                              | `null`  | Fixed server certificate (PEM)                     |
| `mockserver.tlsMutualAuthenticationRequired`                  | `MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_REQUIRED`                     | `false` | Require client certificates on inbound connections |
| `mockserver.tlsMutualAuthenticationCertificateChain`          | `MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN`            | `null`  | CA chain to validate client certificates           |
| `mockserver.forwardProxyTLSX509CertificatesTrustManagerType`  | `MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATES_TRUST_MANAGER_TYPE` | `ANY`   | Trust policy for outbound connections              |
| `mockserver.forwardProxyTLSCustomTrustX509Certificates`       | `MOCKSERVER_FORWARD_PROXY_TLS_CUSTOM_TRUST_X509_CERTIFICATES`       | `null`  | Custom trusted CAs for outbound connections        |
| `mockserver.forwardProxyPrivateKey`                           | `MOCKSERVER_FORWARD_PROXY_TLS_PRIVATE_KEY`                          | `null`  | Client private key for outbound mTLS               |
| `mockserver.forwardProxyCertificateChain`                     | `MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATE_CHAIN`               | `null`  | Client certificate for outbound mTLS               |