> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  **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.
</Note>

## 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

```bash theme={null}
# 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

```bash theme={null}
maverics -config maverics.yaml -secretProvider "hashivault://vault.example.com:8200/secret/data/maverics?token=<vault-token>"
```

<Note>
  Both `hashivault://` and `hashivaults://` connect over HTTPS by default. To
  connect over plain HTTP (for development only), use `hashivault+http://`.
</Note>

### Referencing Secrets in YAML

Once the secret provider is configured, reference secrets in your Orchestrator YAML configuration using angle bracket syntax:

```yaml theme={null}
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}
```

<Note>
  Supported schemes: `hashivault://` (HTTPS), `hashivaults://` (HTTPS),
  `hashivault+https://` (HTTPS), `hashivault+http://` (HTTP).
</Note>

### 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                                                  |

<Note>
  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.
</Note>

## 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.

## Related Pages

<CardGroup cols={2}>
  <Card title="Secret Providers" icon="vault" href="/reference/orchestrator/configuration/secret-providers">
    Overview of all secret providers
  </Card>

  <Card title="AWS Secrets Manager" icon="cloud" href="/reference/orchestrator/configuration/secret-providers/aws-secrets-manager">
    Cloud-native secrets for AWS deployments
  </Card>
</CardGroup>