> ## 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.
**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
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 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.
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.
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.
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 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.
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"
```
`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.
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 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.
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.
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.
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"
```
`maxVersion` requires Orchestrator v2026.02.3 or later. Earlier versions only support `minVersion`.
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
```
**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
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.
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.
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.
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`.
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
Return to the Security guides hub for TLS, secrets, policies, and compliance
Complete configuration reference for TLS profiles, cipher suites, mTLS, OCSP, and CRL settings
Production deployment guide including TLS best practices and high availability
Store TLS private keys and other credentials in an external secret provider