Skip to main content
Configuration defines what the Orchestrator does — which identity providers it connects to, which applications it protects, how it routes authentication traffic, and what policies it enforces. Every Orchestrator deployment starts with configuration.

​
How Configuration Is Delivered

There are two paths to configuring the Orchestrator, and they produce the same result:
  • Console — Build configuration visually in the Maverics Console, then publish it as a signed config bundle that the Orchestrator downloads and applies. This is the recommended path for teams managing multiple deployments.
  • YAML file — Write a configuration file directly and point the Orchestrator at it with the -config flag or MAVERICS_CONFIG environment variable. This path is common for GitOps workflows where configuration lives in version control.
Both paths feed the same configuration model, so the concepts on this page apply regardless of how you deliver configuration. Bundles differ in format (the Console emits JSON rather than YAML) and include extras like cryptographic signatures and bundled service extension files — see Config Publishing for bundle-specific details. Environment variables complement either path. Use {{ env.VAR_NAME }} syntax in your configuration to inject values at runtime — addresses, non-sensitive IDs, and other values that change between environments. Environment variables are resolved when the Orchestrator loads configuration, so the same config file (or bundle) can serve dev, staging, and production.

​
Secret Providers

Sensitive values — client secrets, API keys, TLS private keys, database passwords — should never appear in configuration files or bundles. Instead, the Orchestrator retrieves them at runtime from an external secret provider. Secret providers are configured via the MAVERICS_SECRET_PROVIDER environment variable or the -secretProvider CLI flag, not in YAML. Once configured, reference secrets anywhere in your configuration using angle bracket syntax: 
oauthClientSecret: <vault.oidc-client-secret>
The Orchestrator resolves all secret references during startup by fetching values from the configured provider. Supported providers include HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, CyberArk, Conjur, and Delinea. See the Secret Providers reference for setup and provider-specific options.

​
Key Concepts

  • Connectors bridge identity — Connectors define connections to your identity fabric — the identity providers, directories, and attribute sources your organization uses. Connectors are referenced by name from applications and policies.
  • Applications handle traffic — Each application defines how the Orchestrator handles requests for a specific workload — its upstream target, authentication requirements, and route patterns.
  • Modes define protocol — The Orchestrator’s mode determines which identity protocol it speaks to applications: AI Identity Gateway, OIDC Provider, SAML Provider, HTTP Proxy, or LDAP Provider. A single Orchestrator can run multiple modes simultaneously.
  • Policies enforce rules — Authorization policies determine who can access what, using identity provider connectors, authorization rules, claims enrichment, or custom Service Extensions.
The Field Reference maps each concept to its corresponding configuration keys and links to detailed pages.

​
Config Sources

The Orchestrator can load configuration from multiple sources beyond the local filesystem:
  • Local file — A YAML file on disk, specified via MAVERICS_CONFIG or the -config CLI flag. The Orchestrator reads the file at startup and watches for changes.
  • Console — The Maverics Console publishes signed config bundles that the Orchestrator downloads automatically.
  • Remote storage — S3, Azure Blob, GCS, GitHub, and GitLab repositories, each selected via its own environment variable.
Remote sources support automatic hot-reload via ETag-based change detection when MAVERICS_RELOAD_CONFIG is enabled. Only one config source can be active at a time.

​
Environment Variables

Key environment variables for Orchestrator configuration:
VariablePurpose
MAVERICS_CONFIGPath to the YAML configuration file (defaults to /etc/maverics/maverics.yaml)
MAVERICS_SECRET_PROVIDERSecret provider URL for runtime secret retrieval
MAVERICS_HTTP_ADDRESSOverride the HTTP server bind address
MAVERICS_DEBUG_MODEEnable debug-level logging (true/false)
MAVERICS_RELOAD_CONFIGEnable automatic hot-reload for remote config sources
Environment variables follow the MAVERICS_ prefix convention. The Installation reference documents all CLI flags and environment variables.

​
Runtime Behavior

  • Startup — The Orchestrator loads configuration, validates its structure, resolves secret references, initializes connectors and modes, and begins serving traffic.
  • Hot-reload — Remote config sources and local file changes trigger automatic reload without restarting the process (when enabled).
  • Graceful shutdown — The Orchestrator handles shutdown signals gracefully, allowing in-flight requests to complete before exiting.

Field Reference

Every top-level config key with field tables and links to detailed pages

Secret Providers

Runtime secret retrieval from Vault, AWS, Azure, CyberArk, and others

Config Sources

Load configuration from Console, S3, Azure Blob, GCS, GitHub, or GitLab

Installation

CLI flags, environment variables, and deployment options