HashiCorp Vault

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

Parameter	Required	Description
URL host + port	Yes	Vault server address (e.g., `vault.example.com:8200`)
URL path	Yes	Secret engine mount path and secret path (e.g., `/secret/data/maverics`)
`token`	Conditional	Vault token for token authentication
`role_id`	Conditional	AppRole role ID (requires `secret_id`)
`secret_id`	Conditional	AppRole secret ID (requires `role_id`)
`namespace`	No	Vault Enterprise namespace
`ca_cert`	No	Path to CA certificate file for Vault TLS verification
`client_cert`	No	Path to client certificate for mutual TLS
`client_key`	No	Path to client key for mutual TLS
`cert_name`	No	Certificate name for TLS cert authentication
`win_cert_thumbprint`	No	Windows certificate store thumbprint
`win_cert_subject`	No	Windows certificate store subject
`win_root_ca_thumbprint`	No	Windows root CA thumbprint
`win_root_ca_subject`	No	Windows 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

Console Administration

Orchestration

Overview

Use Cases

Configuration

Configuration via Environment Variable

Configuration via CLI Flag

Referencing Secrets in YAML

Configuration Reference

URL Structure

URL Parameters

Troubleshooting

Secret Providers

AWS Secrets Manager

​Overview

​Use Cases

​Configuration

​Configuration via Environment Variable

​Configuration via CLI Flag

​Referencing Secrets in YAML

​Configuration Reference

​URL Structure

​URL Parameters

​Troubleshooting

​Related Pages

Secret Providers

AWS Secrets Manager

Overview

Use Cases

Configuration

Configuration via Environment Variable

Configuration via CLI Flag

Referencing Secrets in YAML

Configuration Reference

URL Structure

URL Parameters

Troubleshooting

Related Pages