Manage Secrets

By the end of this guide, you will have a Maverics Orchestrator that retrieves all sensitive configuration values — API keys, client secrets, certificates — from your organization’s secret management system rather than from files or environment variables.

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.

Why External Secret Providers?

Secrets are sensitive values that your Orchestrator needs to function — things like identity provider client secrets, API keys for upstream services, TLS private keys, and database passwords. Storing these directly in configuration files or environment variables creates risk: anyone with access to the file system or process environment can read them, and they are easy to accidentally commit to version control. External secret providers solve this problem by storing secrets in a dedicated, access-controlled system. The Orchestrator fetches secrets at runtime using authenticated API calls, which means the actual secret values never appear in your config files. Providers like HashiCorp Vault, AWS Secrets Manager, and Azure Key Vault also offer features like automatic rotation, audit logging, and fine-grained access policies — giving you centralized control over who and what can access each secret.

Prerequisites

A running Maverics Orchestrator — If you have not installed it yet, follow the Quick Start guide first.
Access to a secret provider — You need an account and appropriate permissions on one of the supported providers: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, Delinea Secret Server, CyberArk Conjur, CyberArk CCP, or a Secret File for development.

Integrate a Secret Provider

Choose your secret provider

The Maverics Orchestrator supports 7 secret provider types, each suited to different environments and organizational requirements.

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.

Secret provider selection screen in Maverics Console showing supported providers

Secret providers are not configured in YAML. They are configured via the MAVERICS_SECRET_PROVIDER environment variable or the -secretProvider CLI flag. The table below lists all supported providers.

Provider	URL Scheme	Best For
HashiCorp Vault	`hashivault://` or `hashivaults://`	Multi-cloud, on-premises — dynamic secrets, automatic rotation
AWS Secrets Manager	`awssecretsmanager://`	AWS-native deployments — IAM integration, cross-region replication
Azure Key Vault	`azurekeyvault://`	Azure-native deployments — managed identity, HSM backing
Delinea Secret Server	`delinea://`	Enterprise PAM — session recording, approval workflows
CyberArk Conjur	`conjur://`	DevOps-oriented secrets for CI/CD and containers
CyberArk CCP	`cyberarkccp://`	CyberArk Central Credential Provider
Secret File	`secretfile://`	Development and testing — local file-based secrets

For most production deployments, choose the provider that matches your cloud platform or existing secret management infrastructure.See Secret Providers Reference for detailed configuration documentation for each provider.

Configure the secret provider

Secret providers are configured via the MAVERICS_SECRET_PROVIDER environment variable or the -secretProvider CLI flag — not in YAML configuration. Only one secret provider may be active at a time.The Orchestrator authenticates to the secret provider at startup and maintains the connection for the lifetime of the process. If the connection drops, the Orchestrator retries automatically.

Console UI
Configuration

Secret provider connection configuration screen showing authentication fields

Secret providers are configured via environment variable or CLI flag, not in YAML. The examples below show shell commands for the three most common providers.

HashiCorp Vault:

export MAVERICS_SECRET_PROVIDER="hashivault://vault.example.com:8200/secret/data/maverics?token=<VAULT_TOKEN>"

AWS Secrets Manager:

export MAVERICS_SECRET_PROVIDER="awssecretsmanager://us-east-1"

Azure Key Vault:

export MAVERICS_SECRET_PROVIDER="azurekeyvault://my-vault.vault.azure.net"

You can also pass the provider via the CLI flag instead of an environment variable:

maverics \
  -config /etc/maverics/maverics.yaml \
  -secretProvider "hashivault://vault.example.com:8200/secret/data/maverics?token=<VAULT_TOKEN>"

See Secret Providers Reference for provider-specific URL parameters and authentication options.

The credentials used to connect to the secret provider itself (like a Vault token or Azure service principal) should have the minimum permissions needed — typically read-only access to the specific secrets the Orchestrator uses. Follow the principle of least privilege.

Reference secrets in your Orchestrator configuration

Once the secret provider is configured, replace hardcoded secret values in your Orchestrator configuration with secret references. A secret reference uses angle bracket syntax: <namespace.key>. The Orchestrator resolves these references at startup by fetching the value from the configured provider.

Console UI
Configuration

Secret reference configuration screen showing how to reference secrets in connector settings

Use <namespace.key> syntax to reference secrets anywhere a sensitive value is needed:

maverics.yaml

connectors:
  - name: my-idp
    type: oidc
    oauthClientID: "my-client-id"
    oauthClientSecret: <maverics.oidc-client-secret>
    oidcWellKnownURL: "https://idp.example.com/.well-known/openid-configuration"

caches:
  - name: "shared-redis"
    type: "redis"
    redis:
      addresses:
        - "redis.example.com:6379"
      password: <maverics.redis-password>

tls:
  "default":
    certFile: "/etc/maverics/certs/server.pem"
    keyFile: "/etc/maverics/certs/server-key.pem"

In this example:

<maverics.oidc-client-secret> — The maverics namespace and oidc-client-secret key map to the secret path in your provider
<maverics.redis-password> — Same namespace, different key for the Redis password

The Orchestrator resolves all <namespace.key> references during startup. The rest of the system works exactly the same — the only difference is where the value comes from.

Secret references work in any string field in the YAML configuration. Use them for client secrets, passwords, API keys, encryption keys, and any other sensitive value.

Verify secrets are resolving

After configuring secret references, restart the Orchestrator and verify that it successfully retrieves all secrets from the provider. The Orchestrator resolves secret references during startup, so any issues will appear in the startup logs.Start (or restart) the Orchestrator:

maverics -config /etc/maverics/maverics.yaml

Check the logs for successful secret resolution. The Orchestrator logs when it connects to the secret provider and when it resolves each secret reference. Look for confirmation that all secrets were retrieved without errors.Verify the health endpoint to confirm the Orchestrator started successfully with resolved secrets:

curl -s https://localhost:9443/status | jq .

If the health endpoint returns {"status": "up"}, your secrets are resolving correctly — the Orchestrator was able to use the retrieved credentials to connect to your identity providers and other services.

Success! Your Orchestrator is retrieving secrets from your external provider at runtime. No sensitive values are stored in configuration files, and your secrets benefit from the provider’s rotation, access control, and audit logging features.

Troubleshooting

Secret not found

The Orchestrator logs an error if it cannot find a secret at the referenced path in the provider. Verify that the secret path in your configuration exactly matches the path in your provider — paths are case-sensitive and must include the full hierarchy (for Vault, this includes the mount path and secret path). Also check that the secret has been created in the provider before the Orchestrator tries to read it.

Authentication to secret provider fails

If the Orchestrator cannot authenticate to your secret provider, check that the connection credentials are correct and have not expired. For Vault, verify the token has not been revoked. For AWS, verify the IAM role or access keys have the correct permissions. For Azure, verify the service principal credentials and that the Key Vault access policy grants the necessary permissions. The Orchestrator logs the specific authentication error during startup.

Secret rotation not picking up new values

By default, the Orchestrator resolves secrets at startup. If your provider rotates a secret while the Orchestrator is running, the Orchestrator continues using the previously fetched value until it is restarted. For production deployments that require seamless rotation, check whether your secret provider supports a notification mechanism or configure the Orchestrator’s secret refresh interval to periodically re-fetch values.

Security Overview

Return to the Security guides hub for TLS, secrets, policies, and compliance

Secret Providers Reference

Detailed configuration for each supported provider — Vault, AWS, Azure, Delinea, CyberArk Conjur, CyberArk CCP, and Secret File

Configure TLS

Store TLS certificates and private keys as secrets for secure certificate management

Operations Guides

Deploy and monitor the Orchestrator in production — including secret management best practices

Getting Started

Authentication

AI Identity

Operations

Security

Why External Secret Providers?

Prerequisites

Integrate a Secret Provider

Troubleshooting

Security Overview

Secret Providers Reference

Configure TLS

Operations Guides

Getting Started

Authentication

AI Identity

Operations

Security

​Why External Secret Providers?

​Prerequisites

​Integrate a Secret Provider

​Troubleshooting

​Related Pages

Security Overview

Secret Providers Reference

Configure TLS

Operations Guides

Why External Secret Providers?

Prerequisites

Integrate a Secret Provider

Troubleshooting

Related Pages