TLS configuration in the Maverics Orchestrator controls encrypted communication for HTTP listeners, identity provider connections, and cache backends. Using named profiles, you define TLS settings once and reference them wherever encrypted connections are needed — enabling mutual TLS (mTLS), certificate revocation checking, and cipher suite restrictions across your deployment.
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
redis.tls fields — Redis cache connections reference a profile for encrypted cache communication
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. Profile names are user-chosen strings. For example, setting http.tls: "default" tells the HTTP server to use the TLS profile named "default".
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, minimum TLS versions, and cipher restrictions. You create as many profiles as needed for different connection types.
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.
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.
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.
Configuration Reference
Named TLS Profiles
The tls key is a map where each entry defines a named profile:
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
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" |
insecureSkipVerify | boolean | false | No | Skip server certificate verification (development only) |
enabledCiphers | array | (Go defaults) | No | Allowed cipher suites using Go crypto/tls suite 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) |
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; 0 disables caching) |
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 subjecthttp.tls and http.hosts are mutually exclusive at the HTTP server level — use one or the other
Example
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 configuration with a default TLS profile for the HTTP listener and an mTLS profile with OCSP for client certificate verification:tls:
"default":
certFile: "/etc/maverics/certs/server.pem"
keyFile: "/etc/maverics/certs/server-key.pem"
minVersion: "1.2"
"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"
enabledCiphers:
- "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
- "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
ocsp:
enabled: true
cacheTimeout: 86400
crl:
enabled: true
cacheTimeout: 86400
"windows-profile":
windowsCertStore:
thumbprint: "A1B2C3D4E5F6..."
http:
address: "0.0.0.0:9443"
tls: "default"
Related Pages
