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

# Configure TLS

By the end of this guide, you will have a Maverics Orchestrator with TLS encryption on all connections -- HTTPS for client-facing traffic and optionally TLS for backend connections to upstream applications.

> [!NOTE]
>
> **Console terminology:** In the Maverics Console, Orchestrator instances and
> configuration delivery are managed through **Deployments**. When working directly
> with YAML, configuration is managed as files delivered via the `-config` flag or
> `MAVERICS_CONFIG` environment variable.

## What Is TLS?

TLS (Transport Layer Security) is the protocol that encrypts data as it travels between two systems over a network. When you see "HTTPS" in a browser URL, that is HTTP running over TLS -- meaning the connection between the browser and the server is encrypted so that no one in between can read or tamper with the data.

For the Maverics Orchestrator, TLS matters in two places. First, the connection between your users' browsers and the Orchestrator -- this is called **TLS termination** because the Orchestrator accepts the encrypted HTTPS connection and decrypts it. Second, the connection between the Orchestrator and your upstream applications -- this is called **backend TLS** and is optional but recommended in production environments where the Orchestrator and your apps are on different networks.

## Prerequisites

* **A running Maverics Orchestrator** -- If you have not installed it yet, follow the [Quick Start guide](/guides/getting-started/quick-start) first.
* **A TLS certificate and private key** -- You can use a certificate from a certificate authority (CA) like Let's Encrypt, your organization's internal CA, or a self-signed certificate for testing. The certificate should be in PEM format.

## Configure TLS

**1. Define a TLS profile**

The Orchestrator uses **named TLS profiles** to manage certificates and encryption settings in one place. Each profile is a named entry under the `tls` top-level key. Once defined, a profile can be referenced by the HTTP listener, identity connectors, and [external cache](/reference/orchestrator/caches) connections -- so you configure your certificate paths and TLS constraints once and reuse them wherever encrypted connections are needed.

A TLS certificate is a file that proves your server's identity to clients. It comes in a pair: a **certificate file** (the public part, often ending in `.crt` or `.pem`) and a **private key file** (the secret part, often ending in `.key`). The certificate authority that issued your certificate vouches that it belongs to your domain.

For production deployments, use a certificate from a trusted certificate authority. [Let's Encrypt](https://letsencrypt.org/) provides free certificates that are trusted by all major browsers. Your organization may also have an internal CA that issues certificates for internal services.

**Console UI**

> [!NOTE]
>
> **Console UI documentation is coming soon.** This section will walk you
> through configuring this component using the Maverics Console's visual
> interface, including step-by-step screenshots and field descriptions.

![TLS certificate upload screen in Maverics Console showing certificate and key file fields](https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max\&auto=format\&n=yo114yy_clZj7p9v\&q=85\&s=ea8d2ec72a69d5a8c7955d78abba6a30)

**Configuration**

Define one or more named TLS profiles under the `tls` top-level key:

```yaml maverics.yaml theme={null}
tls:
  "default":
    certFile: "/etc/maverics/certs/server.pem"
    keyFile: "/etc/maverics/certs/server-key.pem"
    minVersion: "1.2"

  "upstream-idp":
    caFile: "/etc/maverics/certs/idp-ca.pem"
    insecureSkipVerify: false
```

The key fields are `certFile` and `keyFile` for the certificate pair, `minVersion` to set the minimum TLS version (defaults to `"1.2"`), and `caFile` when connecting to upstream servers with custom CA certificates. You can also set `maxVersion` to cap the TLS version -- for example, setting both `minVersion` and `maxVersion` to `"1.2"` restricts the profile to TLS 1.2 only.

See the [TLS Reference](/reference/orchestrator/tls-security#profile-fields) for the complete list of profile fields including mTLS, OCSP, CRL, and cipher suite options.

> [!TIP]
>
> Store your private key securely. If you are managing multiple secrets, consider using a [secret provider](/guides/security/secrets-management) to keep the private key out of the filesystem and retrieve it at runtime from HashiCorp Vault, AWS Secrets Manager, or another provider.

**2. Enable HTTPS on the Orchestrator**

With your TLS profile defined, bind it to the Orchestrator's HTTP listener. This is where **TLS termination** happens -- the Orchestrator accepts encrypted connections from clients and decrypts them internally.

Set `http.tls` to the name of the TLS profile you defined in the previous step. This is the critical wiring step that connects your certificate to the HTTP server.

**Console UI**

> [!NOTE]
>
> **Console UI documentation is coming soon.** This section will walk you
> through configuring this component using the Maverics Console's visual
> interface, including step-by-step screenshots and field descriptions.

![HTTPS listener configuration screen in Maverics Console showing port, certificate path, and key path](https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max\&auto=format\&n=yo114yy_clZj7p9v\&q=85\&s=ea8d2ec72a69d5a8c7955d78abba6a30)

**Configuration**

Reference the named TLS profile from the `http` configuration:

```yaml maverics.yaml theme={null}
http:
  address: "0.0.0.0:9443"
  tls: "default"

tls:
  "default":
    certFile: "/etc/maverics/certs/server.pem"
    keyFile: "/etc/maverics/certs/server-key.pem"
    minVersion: "1.2"
```

The `http.tls` field takes the name of a profile defined under the `tls` key -- in this case, `"default"`. The Orchestrator uses this profile for all incoming HTTPS connections.

If you need to serve multiple domains with different certificates, use `http.hosts` instead of `http.tls` for SNI-based certificate selection:

```yaml maverics.yaml theme={null}
http:
  address: "0.0.0.0:443"
  hosts:
    - serverName: "app.example.com"
      tls: "app-cert"
    - serverName: "api.example.com"
      tls: "api-cert"
```

> [!NOTE]
>
> `http.tls` and `http.hosts` are mutually exclusive. Use `http.tls` for a single TLS profile on all connections, or `http.hosts` for SNI-based virtual hosting with different TLS profiles per server name.

See the [TLS Reference](/reference/orchestrator/tls-security) for the complete set of TLS configuration options -- including cipher suite selection, minimum TLS version, and client certificate authentication.

**3. Configure backend TLS**

Backend TLS secures the connection between the Orchestrator and your upstream applications. This step is optional -- if the Orchestrator and your apps run on the same host or in a trusted private network, you may not need it. But if traffic crosses network boundaries or your compliance requirements mandate encryption everywhere, backend TLS ensures data stays encrypted for the entire journey.

When you enable backend TLS, the Orchestrator connects to your upstream application over HTTPS instead of HTTP. If your upstream uses a self-signed certificate or an internal CA, you will need to provide the CA certificate so the Orchestrator can verify the connection.

**Console UI**

> [!NOTE]
>
> **Console UI documentation is coming soon.** This section will walk you
> through configuring this component using the Maverics Console's visual
> interface, including step-by-step screenshots and field descriptions.

![Backend TLS configuration screen in Maverics Console showing upstream certificate verification settings](https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max\&auto=format\&n=yo114yy_clZj7p9v\&q=85\&s=ea8d2ec72a69d5a8c7955d78abba6a30)

**Configuration**

Create a TLS profile for upstream connections and reference it in your app configuration:

```yaml maverics.yaml theme={null}
tls:
  "default":
    certFile: "/etc/maverics/certs/server.pem"
    keyFile: "/etc/maverics/certs/server-key.pem"
    minVersion: "1.2"

  "upstream":
    caFile: "/etc/maverics/certs/upstream-ca.pem"
    insecureSkipVerify: false

http:
  address: "0.0.0.0:9443"
  tls: "default"

apps:
  - name: my-app
    type: proxy
    upstream: https://backend.example.com
    tls: "upstream"
    routePatterns:
      - "app.example.com"
```

The proxy app's `tls` field references a named TLS profile used for the connection to the upstream backend. The `caFile` in the profile lets the Orchestrator verify the upstream server's certificate.

For mutual TLS (mTLS) with the upstream, include `certFile` and `keyFile` in the upstream profile to present a client certificate.

> [!WARNING]
>
> Never set `insecureSkipVerify: true` in production. This disables certificate verification, making the connection vulnerable to man-in-the-middle attacks. Use it only for local development with self-signed certificates.

**4. Pin TLS versions for compliance**

Some compliance frameworks and legacy integrations require specific TLS version constraints. The `minVersion` and `maxVersion` fields let you control exactly which TLS versions the Orchestrator accepts.

Three common patterns:

**Production default (TLS 1.2+)** -- Accept TLS 1.2 and above. This is the default when only `minVersion` is set:

```yaml maverics.yaml theme={null}
tls:
  "default":
    certFile: "/etc/maverics/certs/server.pem"
    keyFile: "/etc/maverics/certs/server-key.pem"
    minVersion: "1.2"
```

**TLS 1.3 only** -- Require the latest protocol version. Clients that do not support TLS 1.3 will be rejected:

```yaml maverics.yaml theme={null}
tls:
  "tls13-only":
    certFile: "/etc/maverics/certs/server.pem"
    keyFile: "/etc/maverics/certs/server-key.pem"
    minVersion: "1.3"
```

**TLS 1.2 only** -- Pin to TLS 1.2 for systems that require it. Setting both `minVersion` and `maxVersion` to `"1.2"` prevents TLS 1.3 negotiation:

```yaml maverics.yaml theme={null}
tls:
  "tls12-only":
    certFile: "/etc/maverics/certs/server.pem"
    keyFile: "/etc/maverics/certs/server-key.pem"
    minVersion: "1.2"
    maxVersion: "1.2"
```

> [!NOTE]
>
> `maxVersion` requires Orchestrator v2026.02.3 or later. Earlier versions only support `minVersion`.

**5. Verify TLS is working**

With TLS configured, restart the Orchestrator and verify that HTTPS connections are working correctly. A simple test confirms that the certificate is being served and the connection is encrypted.

Start (or restart) the Orchestrator to pick up your TLS configuration:

```bash theme={null}
maverics -config /etc/maverics/maverics.yaml
```

Test the HTTPS endpoint with curl:

```bash theme={null}
curl -v https://your-orchestrator-domain:9443/status
```

The `-v` (verbose) flag shows the TLS handshake details. Look for lines showing the certificate subject, issuer, and that the handshake completed successfully. If you are using a self-signed certificate for testing, add the `-k` flag to skip certificate verification:

```bash theme={null}
curl -vk https://localhost:9443/status
```

To verify the negotiated TLS version specifically, use `openssl`:

```bash theme={null}
openssl s_client -connect localhost:9443 < /dev/null 2>/dev/null | grep "Protocol"
```

This outputs the protocol version (e.g., `TLSv1.2` or `TLSv1.3`), confirming your version constraints are in effect.

You can also verify the full certificate details:

```bash theme={null}
openssl s_client -connect localhost:9443 -showcerts < /dev/null
```

> [!TIP]
>
> **Success!** Your Orchestrator is serving traffic over HTTPS with TLS
> encryption. Client connections are encrypted, and if you configured
> backend TLS, the connection to your upstream applications is encrypted
> too.

## Troubleshooting

> **Certificate not found**
>
> The Orchestrator logs an error at startup if it cannot find the certificate
> or key file at the configured path. Verify that the file paths in your
> configuration are absolute paths (not relative) and that the files are
> readable by the user running the Orchestrator. Common causes include typos
> in the file path, incorrect file permissions, or the certificate being
> stored in a different directory than expected.

> **TLS handshake failure**
>
> A TLS handshake failure means the client and server could not agree on how
> to encrypt the connection. This can happen when the certificate does not
> match the domain the client is connecting to (a hostname mismatch), when
> the certificate has expired, or when the client and server do not support
> any common TLS versions or cipher suites. Check the Orchestrator logs for
> the specific handshake error and verify that your certificate's Common Name
> (CN) or Subject Alternative Name (SAN) matches the domain you are
> connecting to.

> **Certificate chain incomplete**
>
> Browsers and clients need the full certificate chain -- your certificate
> plus any intermediate certificates from the CA -- to verify trust. If
> clients see a "certificate not trusted" error even though your certificate
> is valid, you may be missing intermediate certificates. Concatenate your
> certificate and the intermediate certificate(s) into a single PEM file,
> with your certificate first and the intermediates following in order.

> **Version mismatch between client and server**
>
> If clients receive "protocol version" or "no protocols available" errors,
> the client and server do not share a supported TLS version. Check your
> profile's `minVersion` and `maxVersion` settings against what the client
> supports. For example, if `minVersion` is `"1.3"` but the client only
> supports TLS 1.2, the handshake will fail. Use `openssl s_client -connect
>         host:port` to see which protocol version is negotiated, or test with a
> specific version using `openssl s_client -tls1_2` or `-tls1_3`.

> **Cipher suite negotiation failure**
>
> If the Orchestrator and client cannot agree on a cipher suite, the
> connection fails with a "no cipher suites in common" error. This typically
> happens when `enabledCiphers` is set to a restrictive list that does not
> overlap with the client's supported ciphers. Verify your cipher list
> against the client's capabilities. Remember that `enabledCiphers` only
> affects TLS 1.2 -- TLS 1.3 cipher suites are fixed by the protocol and
> cannot be restricted.

## Related Pages

> **[Security Overview](/guides/security/overview)**
>
> Return to the Security guides hub for TLS, secrets, policies, and compliance

> **[Transport Layer Security (TLS) Reference](/reference/orchestrator/tls-security)**
>
> Complete configuration reference for TLS profiles, cipher suites, mTLS, OCSP, and CRL settings

> **[Deploy to Production](/guides/operations/deploy)**
>
> Production deployment guide including TLS best practices and high availability

> **[Manage Secrets](/guides/security/secrets-management)**
>
> Store TLS private keys and other credentials in an external secret provider