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

# Transport Layer Security (TLS)

TLS configuration in the Maverics Orchestrator secures every connection -- from the HTTPS listener that faces your users, to the backend connections reaching your identity providers and cache infrastructure. Named TLS profiles let you define certificates, version constraints, and cipher restrictions once, then apply them consistently wherever encrypted connections are needed.

<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.
</Note>

## How It Works

The Orchestrator uses a **named profile** approach for TLS configuration. All TLS profiles are defined under the `tls` top-level key as a map where each entry is a named profile. Other configuration sections reference these profiles by name:

* **`http.tls`** -- The HTTP server listener uses a named profile for its TLS certificate and settings
* **Connector `tls` fields** -- Identity connectors reference a profile for secure communication with upstream identity providers
* **Cache `tls` fields** -- [External cache](/reference/orchestrator/caches) connections reference a profile for encrypted cache communication

Profiles serve two roles depending on where they are referenced:

* **Server profiles** (referenced by `http.tls` or `http.hosts`) define the certificate the Orchestrator presents to clients and control which TLS versions and ciphers clients can negotiate.
* **Client profiles** (referenced by connectors and cache connections) control how the Orchestrator verifies upstream servers and optionally presents a client certificate for mutual TLS.

This design allows multiple TLS configurations for different purposes -- one for the HTTP listener, another for upstream IdP connections, and another for external cache connections. Profile names are user-chosen strings. For example, setting `http.tls: "default"` tells the HTTP server to use the TLS profile named `"default"`.

The Orchestrator validates all TLS profile references at startup. If any configuration section references a profile name that does not exist under the `tls` key, the Orchestrator refuses to start and logs the invalid reference.

## Key Concepts

### Named Profiles

Each TLS profile is an entry in the `tls` map with a user-chosen name. Profiles contain certificate paths, CA bundles, TLS version constraints, and cipher restrictions. You create as many profiles as needed for different connection types.

Use descriptive names that reflect the profile's purpose -- for example, `"https-listener"`, `"upstream-idp"`, or `"cache"`. When a deployment only needs a single profile, `"default"` is a common convention. For multi-profile deployments, naming by purpose makes it clear which profile applies where:

```yaml maverics.yaml theme={null}
tls:
  "https-listener":
    certFile: "/etc/maverics/certs/server.pem"
    keyFile: "/etc/maverics/certs/server-key.pem"
  "upstream-idp":
    caFile: "/etc/maverics/certs/idp-ca.pem"
  "cache":
    caFile: "/etc/maverics/certs/cache-ca.pem"
```

### TLS Version Control

The `minVersion` and `maxVersion` fields control which TLS protocol versions the Orchestrator accepts or offers. By default, the Orchestrator accepts TLS 1.2 through TLS 1.3.

* **`minVersion`** sets a floor -- the Orchestrator rejects connections using a version below this value. The default is `"1.2"`, which excludes the deprecated TLS 1.0 and 1.1 protocols.
* **`maxVersion`** sets a ceiling -- the Orchestrator does not offer or accept versions above this value. The default is `"1.3"`.

Together, these fields enable **version pinning** -- restricting a profile to a single TLS version. For example, setting both `minVersion` and `maxVersion` to `"1.2"` forces TLS 1.2 only, which some compliance frameworks and legacy systems require:

```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`.
</Note>

### Client Authentication (mTLS)

Mutual TLS requires both the server and client to present certificates. The `clientAuth` field controls whether the Orchestrator requests or requires client certificates, enabling zero-trust network patterns where every connection is verified.

Common use cases for mTLS include:

* **Zero-trust architectures** -- Verify the identity of every connecting client, not just the server
* **Service-to-service authentication** -- Ensure only authorized services communicate with the Orchestrator
* **Regulated environments** -- Meet compliance requirements that mandate mutual certificate verification (e.g., PCI DSS, FedRAMP)

### Cipher Suites

The `enabledCiphers` field restricts which cipher suites the Orchestrator offers during the TLS handshake. When omitted, the Orchestrator uses the default cipher suites listed below, which provide a strong security baseline for most deployments.

Override the defaults only when a compliance framework or security policy mandates a specific set of ciphers.

#### Default cipher suites

The following TLS 1.2 cipher suites are enabled by default. All use ECDHE key exchange, which provides forward secrecy:

| Cipher Suite                                    | Key Exchange | Encryption        |
| ----------------------------------------------- | ------------ | ----------------- |
| `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`         | ECDHE-RSA    | AES-128-GCM       |
| `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`         | ECDHE-RSA    | AES-256-GCM       |
| `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`       | ECDHE-ECDSA  | AES-128-GCM       |
| `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`       | ECDHE-ECDSA  | AES-256-GCM       |
| `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`   | ECDHE-RSA    | ChaCha20-Poly1305 |
| `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256` | ECDHE-ECDSA  | ChaCha20-Poly1305 |
| `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`            | ECDHE-RSA    | AES-128-CBC       |
| `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`            | ECDHE-RSA    | AES-256-CBC       |
| `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`          | ECDHE-ECDSA  | AES-128-CBC       |
| `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`          | ECDHE-ECDSA  | AES-256-CBC       |

For TLS 1.3 connections, the Orchestrator always uses the protocol's mandatory cipher suites (`TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`). These cannot be changed via `enabledCiphers`.

<Tip>
  For the strongest security posture, restrict `enabledCiphers` to only the ECDHE+AES-GCM and ECDHE+ChaCha20 suites (the first six in the table above). These provide both forward secrecy and authenticated encryption.
</Tip>

#### Additional cipher suites

The following cipher suites are **not enabled by default** due to known weaknesses but can be explicitly configured when required for backwards compatibility with legacy systems:

| Cipher Suite                              | Weakness                                    |
| ----------------------------------------- | ------------------------------------------- |
| `TLS_RSA_WITH_AES_128_GCM_SHA256`         | No forward secrecy (RSA key exchange)       |
| `TLS_RSA_WITH_AES_256_GCM_SHA384`         | No forward secrecy (RSA key exchange)       |
| `TLS_RSA_WITH_AES_128_CBC_SHA`            | No forward secrecy (RSA key exchange)       |
| `TLS_RSA_WITH_AES_256_CBC_SHA`            | No forward secrecy (RSA key exchange)       |
| `TLS_RSA_WITH_AES_128_CBC_SHA256`         | No forward secrecy (RSA key exchange)       |
| `TLS_RSA_WITH_RC4_128_SHA`                | RC4 is broken                               |
| `TLS_RSA_WITH_3DES_EDE_CBC_SHA`           | 3DES has a small block size (Sweet32)       |
| `TLS_ECDHE_ECDSA_WITH_RC4_128_SHA`        | RC4 is broken                               |
| `TLS_ECDHE_RSA_WITH_RC4_128_SHA`          | RC4 is broken                               |
| `TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA`     | 3DES has a small block size (Sweet32)       |
| `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`   | CBC with SHA-256 (potential padding oracle) |
| `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256` | CBC with SHA-256 (potential padding oracle) |

<Warning>
  These cipher suites have known security weaknesses. Only enable them when connecting to legacy systems that do not support modern cipher suites, and plan to migrate away from them.
</Warning>

#### Cipher suite validation

The Orchestrator validates `enabledCiphers` at startup:

* **Unrecognized names** are logged as errors and skipped -- the Orchestrator still starts with the remaining valid ciphers
* **All names invalid** -- the Orchestrator falls back to the default secure cipher suites
* **`minVersion` set to `"1.3"`** -- `enabledCiphers` is ignored because TLS 1.3 cipher suites are fixed by the protocol specification

<Note>
  `enabledCiphers` only affects TLS 1.2 connections. TLS 1.3 cipher suites are fixed by the protocol specification and cannot be configured -- the Orchestrator automatically uses TLS 1.3's mandatory ciphers regardless of this setting.
</Note>

### Certificate Revocation

The Orchestrator supports two certificate revocation mechanisms:

* **OCSP (Online Certificate Status Protocol)** -- Real-time revocation checking against an OCSP responder
* **CRL (Certificate Revocation List)** -- Periodic checking against published revocation lists

Both can be enabled per profile with configurable cache timeouts, allowing different revocation policies for different connection types -- for example, strict OCSP checking on the client-facing listener but no revocation checking on a trusted internal backend connection.

### Windows Certificate Store

On Windows deployments, the Orchestrator can load certificates directly from the Windows Certificate Store instead of file paths, integrating with enterprise certificate management infrastructure.

## Setup

<Tabs>
  <Tab title="Console UI">
    <Info>
      **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.
    </Info>
  </Tab>

  <Tab title="Configuration">
    A minimal TLS configuration that enables HTTPS on the Orchestrator listener:

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

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

    This defines a single TLS profile named `"default"` with a certificate and private key, sets a minimum TLS version of 1.2, and binds it to the HTTP listener on port 9443. The Orchestrator serves all incoming traffic over HTTPS using this profile.

    See the [Configure TLS guide](/guides/security/tls) for a step-by-step walkthrough including backend TLS and verification.
  </Tab>
</Tabs>

## Configuration Reference

### Named TLS Profiles

The `tls` key is a map where each entry defines a named profile:

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

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

### Profile Fields

Each named TLS profile supports the following fields:

| Key                  | Type    | Default           | Required    | Description                                                                       |
| -------------------- | ------- | ----------------- | ----------- | --------------------------------------------------------------------------------- |
| `certFile`           | string  | --                | Conditional | Path to PEM-encoded certificate file (mutually exclusive with `windowsCertStore`) |
| `keyFile`            | string  | --                | Conditional | Path to PEM-encoded private key file (required when `certFile` is set)            |
| `caFile`             | string  | --                | No          | CA certificate bundle for server certificate verification                         |
| `clientAuth`         | string  | `"NoClientCert"`  | No          | Client certificate authentication mode (see values below)                         |
| `clientCAFiles`      | array   | `[]`              | No          | Root CA files for client certificate verification                                 |
| `minVersion`         | string  | `"1.2"`           | No          | Minimum TLS version: `"1.2"` or `"1.3"` (TLS 1.0 and 1.1 are not supported)       |
| `maxVersion`         | string  | `"1.3"`           | No          | Maximum TLS version: `"1.2"` or `"1.3"` (TLS 1.0 and 1.1 are not supported)       |
| `insecureSkipVerify` | boolean | `false`           | No          | Skip server certificate verification (development only)                           |
| `enabledCiphers`     | array   | (secure defaults) | No          | Allowed cipher suites (see [Cipher Suites](#cipher-suites) for supported names)   |

### Client Authentication (mTLS)

The `clientAuth` field controls whether the Orchestrator requires client certificates for mutual TLS. It accepts the following values:

| Value                        | Description                                                      |
| ---------------------------- | ---------------------------------------------------------------- |
| `NoClientCert`               | No client certificate is requested or required (default)         |
| `RequestClientCert`          | Request a client certificate but do not require one              |
| `RequireAnyClientCert`       | Require any client certificate without verifying it              |
| `VerifyClientCertIfGiven`    | Verify the client certificate if one is provided (optional mTLS) |
| `RequireAndVerifyClientCert` | Require and verify a client certificate (full mutual TLS)        |

When using `VerifyClientCertIfGiven` or `RequireAndVerifyClientCert`, you must also configure `clientCAFiles` with one or more root CA certificates for verification.

### OCSP Configuration

Online Certificate Status Protocol (OCSP) checking can be enabled per profile to verify certificate revocation status in real time:

| Key                 | Type    | Default | Description                                                  |
| ------------------- | ------- | ------- | ------------------------------------------------------------ |
| `ocsp.enabled`      | boolean | `false` | Enable OCSP revocation checking                              |
| `ocsp.cacheTimeout` | integer | `86400` | OCSP response cache timeout in seconds (default is 24 hours) |

### CRL Configuration

Certificate Revocation List (CRL) checking can be enabled per profile to verify certificates against published revocation lists:

| Key                | Type    | Default | Description                                        |
| ------------------ | ------- | ------- | -------------------------------------------------- |
| `crl.enabled`      | boolean | `false` | Enable CRL revocation checking                     |
| `crl.cacheTimeout` | integer | `86400` | CRL cache timeout in seconds (default is 24 hours) |

### Windows Certificate Store

On Windows, the Orchestrator can load certificates directly from the Windows Certificate Store instead of using file paths:

| Key                           | Type   | Default | Description                                                                     |
| ----------------------------- | ------ | ------- | ------------------------------------------------------------------------------- |
| `windowsCertStore.thumbprint` | string | --      | Certificate thumbprint to find in the store (mutually exclusive with `subject`) |
| `windowsCertStore.subject`    | string | --      | Certificate subject to find in the store (mutually exclusive with `thumbprint`) |

<Note>
  `windowsCertStore` is mutually exclusive with `certFile` and `keyFile`. You cannot use both file-based and Windows Certificate Store certificates in the same profile. This feature is available on Windows only.
</Note>

### Validation Rules

* Cannot define both `certFile` and `windowsCertStore` in the same profile
* If `certFile` is set, `keyFile` is required (and vice versa)
* `windowsCertStore` requires exactly one of `thumbprint` or `subject`
* `http.tls` and `http.hosts` are mutually exclusive at the HTTP server level -- use one or the other
* `minVersion` must be less than or equal to `maxVersion` -- if `minVersion` is `"1.3"` and `maxVersion` is `"1.2"`, the Orchestrator will not start
* `enabledCiphers` only affects TLS 1.2 connections -- TLS 1.3 cipher suites are fixed by the protocol and cannot be configured

## Examples

<AccordionGroup>
  <Accordion title="HTTPS listener with production defaults">
    The most common TLS configuration: a single profile with a certificate and private key bound to the HTTP listener. This gives you HTTPS with TLS 1.2+ and secure default cipher suites, which is appropriate for most production deployments.

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

    http:
      address: "0.0.0.0:9443"
      tls: "default"
    ```
  </Accordion>

  <Accordion title="TLS 1.2-only pinning for legacy systems">
    Some legacy systems or compliance frameworks require connections to use TLS 1.2 exclusively -- they cannot use TLS 1.3 due to compatibility constraints or certification requirements. Setting both `minVersion` and `maxVersion` to `"1.2"` pins the profile to TLS 1.2 only.

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

    http:
      address: "0.0.0.0:9443"
      tls: "tls12-pinned"
    ```

    <Note>
      `maxVersion` requires Orchestrator v2026.02.3 or later.
    </Note>
  </Accordion>

  <Accordion title="Mutual TLS with OCSP revocation checking">
    An mTLS configuration that requires clients to present a valid certificate and verifies revocation status in real time via OCSP. This pattern is common in zero-trust architectures and regulated environments where every connection must be authenticated and certificate validity must be continuously verified.

    ```yaml maverics.yaml theme={null}
    tls:
      "mtls-profile":
        certFile: "/etc/maverics/certs/server.pem"
        keyFile: "/etc/maverics/certs/server-key.pem"
        caFile: "/etc/maverics/certs/ca-bundle.pem"
        clientAuth: "RequireAndVerifyClientCert"
        clientCAFiles:
          - "/etc/maverics/certs/client-ca.pem"
        minVersion: "1.2"
        ocsp:
          enabled: true
          cacheTimeout: 86400

    http:
      address: "0.0.0.0:9443"
      tls: "mtls-profile"
    ```
  </Accordion>

  <Accordion title="SNI-based virtual hosting with per-domain certificates">
    When the Orchestrator serves multiple domains, use `http.hosts` instead of `http.tls` to assign different TLS profiles per server name. Each host entry maps a domain to a named TLS profile, enabling SNI-based (Server Name Indication) certificate selection.

    ```yaml maverics.yaml theme={null}
    tls:
      "app-cert":
        certFile: "/etc/maverics/certs/app.example.com.pem"
        keyFile: "/etc/maverics/certs/app.example.com-key.pem"
        minVersion: "1.2"
      "api-cert":
        certFile: "/etc/maverics/certs/api.example.com.pem"
        keyFile: "/etc/maverics/certs/api.example.com-key.pem"
        minVersion: "1.2"

    http:
      address: "0.0.0.0:443"
      hosts:
        - serverName: "app.example.com"
          tls: "app-cert"
        - serverName: "api.example.com"
          tls: "api-cert"
    ```
  </Accordion>

  <Accordion title="Restricted cipher suites for compliance">
    Some compliance frameworks (e.g., PCI DSS, FedRAMP) require limiting the cipher suites to a specific approved set. This configuration restricts TLS 1.2 to only ECDHE+AES-GCM ciphers, which provide forward secrecy and authenticated encryption.

    ```yaml maverics.yaml theme={null}
    tls:
      "compliance":
        certFile: "/etc/maverics/certs/server.pem"
        keyFile: "/etc/maverics/certs/server-key.pem"
        minVersion: "1.2"
        enabledCiphers:
          - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
          - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
          - "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
          - "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"

    http:
      address: "0.0.0.0:9443"
      tls: "compliance"
    ```

    <Note>
      `enabledCiphers` only affects TLS 1.2 connections. TLS 1.3 cipher suites are defined by the protocol specification and cannot be restricted.
    </Note>
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup cols={2}>
  <Card title="Configure TLS" icon="lock" href="/guides/security/tls">
    Step-by-step guide to setting up TLS for HTTPS, backend connections, and version pinning
  </Card>

  <Card title="Configuration" icon="gear" href="/reference/orchestrator/configuration">
    Top-level Orchestrator settings including HTTP server configuration
  </Card>

  <Card title="Secret Providers" icon="vault" href="/reference/orchestrator/configuration/secret-providers">
    Store TLS certificates and keys securely using secret providers
  </Card>

  <Card title="Identity Fabric" icon="compass" href="/reference/orchestrator/identity-fabric">
    Connectors that reference TLS profiles for secure IdP communication
  </Card>
</CardGroup>