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.
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.
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.
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
Configuration
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 in Maverics Console
Define one or more named TLS profiles under the tls top-level key:
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 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 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
Configuration
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 in Maverics Console
Reference the named TLS profile from the http configuration:
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:
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 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
Configuration
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 in Maverics Console
Create a TLS profile for upstream connections and reference it in your app configuration:
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.
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:
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:
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:
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:
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.
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.
