Skip to main content
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 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 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 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.
TLS certificate upload screen in Maverics Console showing certificate and key file fields
Store your private key securely. If you are managing multiple secrets, consider using a secret provider 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 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
See the TLS Reference 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 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
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:
maverics.yaml
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:
maverics.yaml
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:
maverics.yaml
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.
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:
maverics -config /etc/maverics/maverics.yaml
Test the HTTPS endpoint with curl:
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:
curl -vk https://localhost:9443/status
To verify the negotiated TLS version specifically, use openssl:
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:
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.

Security Overview

Return to the Security guides hub for TLS, secrets, policies, and compliance

Transport Layer Security (TLS) Reference

Complete configuration reference for TLS profiles, cipher suites, mTLS, OCSP, and CRL settings

Deploy to Production

Production deployment guide including TLS best practices and high availability

Manage Secrets

Store TLS private keys and other credentials in an external secret provider