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.

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.

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

maverics.yaml

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:

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.

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.

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.

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)

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.

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

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.

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

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.

A minimal TLS configuration that enables HTTPS on the Orchestrator listener:

maverics.yaml

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 for a step-by-step walkthrough including backend TLS and verification.

Configuration Reference

Named TLS Profiles

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

maverics.yaml

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 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`)

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.

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

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.

maverics.yaml

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"

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.

maverics.yaml

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"

maxVersion requires Orchestrator v2026.02.3 or later.

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.

maverics.yaml

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"

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.

maverics.yaml

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"

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.

maverics.yaml

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"

enabledCiphers only affects TLS 1.2 connections. TLS 1.3 cipher suites are defined by the protocol specification and cannot be restricted.

Configure TLS

Step-by-step guide to setting up TLS for HTTPS, backend connections, and version pinning

Configuration

Top-level Orchestrator settings including HTTP server configuration

Secret Providers

Store TLS certificates and keys securely using secret providers

Identity Fabric

Connectors that reference TLS profiles for secure IdP communication

Console Administration

Orchestration

How It Works

Key Concepts

Named Profiles

TLS Version Control

Client Authentication (mTLS)

Cipher Suites

Default cipher suites

Additional cipher suites

Cipher suite validation

Certificate Revocation

Windows Certificate Store

Setup

Configuration Reference

Named TLS Profiles

Profile Fields

Client Authentication (mTLS)

OCSP Configuration

CRL Configuration

Windows Certificate Store

Validation Rules

Examples

Configure TLS

Configuration

Secret Providers

Identity Fabric

Console Administration

Orchestration

​How It Works

​Key Concepts

​Named Profiles

​TLS Version Control

​Client Authentication (mTLS)

​Cipher Suites

​Default cipher suites

​Additional cipher suites

​Cipher suite validation

​Certificate Revocation

​Windows Certificate Store

​Setup

​Configuration Reference

​Named TLS Profiles

​Profile Fields

​Client Authentication (mTLS)

​OCSP Configuration

​CRL Configuration

​Windows Certificate Store

​Validation Rules

​Examples

​Related Pages

Configure TLS

Configuration

Secret Providers

Identity Fabric

How It Works

Key Concepts

Named Profiles

TLS Version Control

Client Authentication (mTLS)

Cipher Suites

Default cipher suites

Additional cipher suites

Cipher suite validation

Certificate Revocation

Windows Certificate Store

Setup

Configuration Reference

Named TLS Profiles

Profile Fields

Client Authentication (mTLS)

OCSP Configuration

CRL Configuration

Windows Certificate Store

Validation Rules

Examples

Related Pages