# Connect HashiCorp Vault or OpenBao

Connect a Vault or OpenBao server as a source, so that vault:// references to its KV secrets become synced secrets.

Replace _vault-prod_ with a name for the source and _https://vault.example.com:8200_ with your
server's address.

## Prerequisites

- Permission for `secrets:CreateSecretSource` and `secrets:CreateSecret`. In the console, also
  `secrets:ListSecretSources` to open **Sources**; without it the page says your policies do not
  grant it.
- An enabled encrypt/decrypt KMS key.
- A server reachable from the internet over `https://`, on any port. The platform connects only if
  every address the name resolves to is public, and does not follow redirects.
- A token, or an AppRole (role ID and secret ID), whose policy can read the KV paths your apps
  need. Deutsche Cloud never writes to Vault.

## Connect the source

**Console**
1. Open **Sources** (in the Secrets navigation), and choose **Connect a source**.
2. For **Provider**, choose **HashiCorp Vault / OpenBao**.
3. For **Address**, enter https://vault.example.com:8200.
4. (Optional) For **Namespace**, enter a Vault Enterprise, HCP Vault or OpenBao namespace.
5. For **Login**, choose **Token** or **AppRole**. With AppRole, enter the **Role ID** and, if
   AppRole is not mounted at `approle`, the **AppRole mount**.
6. For **Name**, enter vault-prod.
7. For **Token, or AppRole secret ID**, paste the credential.
8. (Optional) Set **Refresh every (minutes)** and **Encrypt the token with**.
9. Choose **Verify & connect**.

**CLI**
```sh
dcloud secrets sources create --name vault-prod --provider vault \
  --credential "$VAULT_TOKEN" --config address=https://vault.example.com:8200 --config authMethod=token
```

**API**
```http
POST /secrets/api/sources
{ "name": "vault-prod", "provider": "vault", "config": { "address": "https://vault.example.com:8200", "authMethod": "token" }, "credential": "hvs.EXAMPLE" }
```

**Terraform**
```hcl
resource "dcloud_secrets_source" "vault" {
  name          = "vault-prod"
  provider_type = "vault"
  credential    = var.vault_token
  config = {
    address = "https://vault.example.com:8200"
  }
}
```

| Setting        | Meaning                                                                       |
| -------------- | ----------------------------------------------------------------------------- |
| `address`      | Required. Must start with `https://`.                                         |
| `namespace`    | Optional. Sent to Vault as the namespace of every request.                    |
| `authMethod`   | `token` (the default) or `approle` (the credential is the AppRole secret ID). |
| `roleId`       | With `approle`, required: the role ID.                                        |
| `approleMount` | With `approle`: where AppRole is mounted.                                     |

## Result

The connection is checked before anything is stored: the token (or the AppRole login) must be
valid. When the token may list the server's mounts, it must also see at least one KV secrets
engine, and the source's status names the KV mounts it sees and the token's policies (such as
"Connected: 1 KV mount visible (secret); policies default, shop-read"). A token that may not list mounts is accepted without that check. The credential is
stored as the secret `SOURCE_VAULT_PROD_TOKEN`, as for 1Password.

References are `vault://<mount>/<path>#<key>`: the field `<key>` of the secret at `<path>` in the KV
engine mounted at `<mount>`, such as `vault://secret/shop/prod/db#password`. KV version 2 and
version 1 are both read; when the token may not list mounts, every mount is read as version 2.

## Refusals

- `422` "HashiCorp Vault / OpenBao rejected the credential: …", for example "The token is valid
  but sees no KV secrets engine".
- `400` for invalid settings, such as "The address must be https://" or "AppRole needs the role ID".
- `422` "HashiCorp Vault / OpenBao rejected the credential: …" followed by "could not reach Vault:
  …" when the address cannot be reached, resolves to a private address or answers with a redirect.
- `409` for a taken name (or a taken `SOURCE_…_TOKEN` secret), no usable key, or a full quota.

## Related

- [Sync a secret from a source](sync-a-secret-from-a-source.md)
- `secrets.sources.create` · `dcloud_secrets_source`
