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

Define a TLS profile

The Orchestrator uses named TLS profiles to manage certificates. Each profile is a named entry under the tls top-level key, and can be referenced by the HTTP listener, connectors, and cache connections. This design allows multiple TLS configurations for different purposes — one for the HTTP listener, another for upstream IdP connections, and another for Redis cache connections.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 screen in Maverics Console showing certificate and key file fields

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

maverics.yaml

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

Field	Required	Description
`certFile`	Conditional	Path to PEM-encoded certificate file
`keyFile`	Conditional	Path to PEM-encoded private key (required when `certFile` is set)
`caFile`	No	CA certificate bundle for server verification
`clientAuth`	No	Client certificate mode: `"NoClientCert"`, `"RequestClientCert"`, `"RequireAndVerifyClientCert"`, etc.
`clientCAFiles`	No	Root CA files for client certificate verification (mTLS)
`minVersion`	No	Minimum TLS version: `"1.2"` (default) or `"1.3"`
`insecureSkipVerify`	No	Skip server certificate verification (development only)
`enabledCiphers`	No	Allowed cipher suites using Go `crypto/tls` suite names

See Transport Layer Security (TLS) Reference for all TLS profile fields including OCSP, CRL, and Windows Certificate Store 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.

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

HTTPS listener configuration screen in Maverics Console showing port, certificate path, and key path

Reference the named TLS profile from the http configuration:

maverics.yaml

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.

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 Transport Layer Security (TLS) Reference for the complete set of TLS configuration options — including cipher suite selection, minimum TLS version, and client certificate authentication.

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

Backend TLS configuration screen in Maverics Console showing upstream certificate verification settings

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

maverics.yaml

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.

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

You can also verify the certificate details with openssl:

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

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.

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

Getting Started

Authentication

AI Identity

Operations

Security

Configure TLS

What Is TLS?

Prerequisites

Configure TLS

Troubleshooting

Security Overview

Transport Layer Security (TLS) Reference

Deploy to Production

Manage Secrets

Getting Started

Authentication

AI Identity

Operations

Security

​What Is TLS?

​Prerequisites

​Configure TLS

​Troubleshooting

​Related Pages

Security Overview

Transport Layer Security (TLS) Reference

Deploy to Production

Manage Secrets

What Is TLS?

Prerequisites

Configure TLS

Troubleshooting

Related Pages