Skip to main content
The HashiCorp Vault secret provider connects the Orchestrator to a Vault server for centralized secrets management. Vault provides encrypted storage, dynamic secret generation, and a comprehensive audit trail for all secret access.
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.

​
Overview

When configured with the HashiCorp Vault provider, the Orchestrator authenticates to Vault at startup and retrieves secrets on demand as they are referenced in configuration. The provider supports multiple authentication methods including token-based, AppRole (for machine-to-machine), and TLS certificate authentication. Secrets are read from Vault’s KV secrets engine using configurable mount paths and secret paths.

​
Use Cases

  • Existing Vault deployments — retrieve Orchestrator secrets from an existing Vault instance without duplicating credentials into another system
  • Audit trail — every secret access is logged in Vault’s audit log for compliance and troubleshooting
  • Centralized credential rotation — rotate secrets in Vault and pick up new values on Orchestrator restart or config reload

​
Configuration

Secret providers are not configured in YAML. They are set via the MAVERICS_SECRET_PROVIDER environment variable or the -secretProvider CLI flag.

​
Configuration via Environment Variable

# Token authentication (HTTPS by default)
export MAVERICS_SECRET_PROVIDER="hashivault://vault.example.com:8200/secret/data/maverics?token=<vault-token>"

# AppRole authentication
export MAVERICS_SECRET_PROVIDER="hashivault://vault.example.com:8200/secret/data/maverics?role_id=<role-id>&secret_id=<secret-id>"

# TLS certificate authentication
export MAVERICS_SECRET_PROVIDER="hashivault://vault.example.com:8200/secret/data/maverics?client_cert=/path/to/cert&client_key=/path/to/key&cert_name=<cert-name>"

# With Vault namespace (for Vault Enterprise)
export MAVERICS_SECRET_PROVIDER="hashivault://vault.example.com:8200/secret/data/maverics?token=<vault-token>&namespace=my-namespace"

# Explicit HTTP connection (for development only)
export MAVERICS_SECRET_PROVIDER="hashivault+http://vault.example.com:8200/secret/data/maverics?token=<vault-token>"

​
Configuration via CLI Flag

maverics -config maverics.yaml -secretProvider "hashivault://vault.example.com:8200/secret/data/maverics?token=<vault-token>"
Both hashivault:// and hashivaults:// connect over HTTPS by default. To connect over plain HTTP (for development only), use hashivault+http://.

​
Referencing Secrets in YAML

Once the secret provider is configured, reference secrets in your Orchestrator YAML configuration using angle bracket syntax: 
connectors:
  - name: my-idp
    oauthClientSecret: <maverics.client_secret>

apps:
  - name: my-app
    tls:
      keyFile: <maverics.tls_private_key>
The namespace (maverics) maps to the secret path configured in the URL, and the key (client_secret) maps to the key within that secret.

​
Configuration Reference

​
URL Structure

hashivault://{host}:{port}/{engine-path}/{secret-path}?{parameters}
Supported schemes: hashivault:// (HTTPS), hashivaults:// (HTTPS), hashivault+https:// (HTTPS), hashivault+http:// (HTTP).

​
URL Parameters

ParameterRequiredDescription
URL host + portYesVault server address (e.g., vault.example.com:8200)
URL pathYesSecret engine mount path and secret path (e.g., /secret/data/maverics)
tokenConditionalVault token for token authentication
role_idConditionalAppRole role ID (requires secret_id)
secret_idConditionalAppRole secret ID (requires role_id)
namespaceNoVault Enterprise namespace
ca_certNoPath to CA certificate file for Vault TLS verification
client_certNoPath to client certificate for mutual TLS
client_keyNoPath to client key for mutual TLS
cert_nameNoCertificate name for TLS cert authentication
win_cert_thumbprintNoWindows certificate store thumbprint
win_cert_subjectNoWindows certificate store subject
win_root_ca_thumbprintNoWindows root CA thumbprint
win_root_ca_subjectNoWindows root CA subject
Provide one of the following authentication methods: token, role_id + secret_id, or client_cert + client_key + cert_name. AppRole is recommended for production machine-to-machine authentication.

​
Troubleshooting

“permission denied” errors from Vault Verify that the token or AppRole credentials have a Vault policy granting read access to the configured secret path. Check the Vault audit log for the denied request. “connection refused” when starting the Orchestrator Confirm the Vault server address and port are correct. If using hashivaults://, ensure the Vault server has TLS enabled and the CA certificate is trusted (use ca_cert if needed). Secrets not resolving in YAML configuration Ensure the angle bracket syntax matches the key names stored in Vault. The namespace in <namespace.key> must match the path segment in the secret provider URL, and the key must exist in that Vault secret.

Secret Providers

Overview of all secret providers

AWS Secrets Manager

Cloud-native secrets for AWS deployments