---
title: "HashiCorp Vault storage"
manual: "Secrets Vault"
version: "1.8"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-vault:operations-hashicorp-adapter@1.8"
source: "Operations/HashiCorpAdapter.rst"
rendered: "2026-11-15T10:38:35+00:00"
---

# HashiCorp Vault storage {#operations-hashicorp-adapter}

With `storageAdapter = hashicorp` the encryption envelope of every new secret
lives in HashiCorp Vault (KV version 2) instead of in the TYPO3 database. The
decision and its trade-offs are in [ADR-053: HashiCorp Vault storage adapter](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-053-hashicorp-storage-adapter@1.8).

**Table of contents**

-   [What lives where](https://docs.typo3.org/permalink/netresearch/nr-vault:what-lives-where@1.8)
-   [Prepare Vault](https://docs.typo3.org/permalink/netresearch/nr-vault:prepare-vault@1.8)
-   [Choose an authentication method](https://docs.typo3.org/permalink/netresearch/nr-vault:choose-an-authentication-method@1.8)
-   [Configure TYPO3](https://docs.typo3.org/permalink/netresearch/nr-vault:configure-typo3@1.8)
-   [Network and TLS](https://docs.typo3.org/permalink/netresearch/nr-vault:network-and-tls@1.8)
-   [Behaviour you should know](https://docs.typo3.org/permalink/netresearch/nr-vault:behaviour-you-should-know@1.8)
-   [Troubleshooting](https://docs.typo3.org/permalink/netresearch/nr-vault:troubleshooting@1.8)

## What lives where {#operations-hashicorp-adapter-model}

| Data | TYPO3 database | Vault KV v2 |
| --- | --- | --- |
| Identifier, description, context, metadata | yes | no |
| Owner, group tiers, expiry, counters, availability | yes | no |
| Pointer to the Vault key (`external_reference`) | yes | no |
| Encrypted value, wrapped data key, nonces, checksum | no (columns are empty) | yes |
| Master key | no | no (see [Key custody](https://docs.typo3.org/permalink/netresearch/nr-vault:operations-key-custody@1.8)) |

The value is encrypted by nr-vault before it is sent. Vault stores ciphertext it
cannot read; the master key never reaches Vault, except wrapped, with the
`transit` provider.

Existing secrets are not migrated. A secret stored locally stays local and keeps
working after you switch; only new secrets go to Vault. Roll back by switching
the setting back: secrets already in Vault become unreadable until you switch to
`hashicorp` again, so do not remove them from Vault.

## Prepare Vault {#operations-hashicorp-adapter-vault}

The adapter needs a KV v2 mount (development servers mount one at `secret/`)
and a policy that is limited to the extension's prefix:

**Policy typo3**

```text
path "secret/data/typo3/*"     { capabilities = ["create", "read", "update"] }
path "secret/metadata/typo3/*" { capabilities = ["read", "delete"] }
```

```bash
vault policy write typo3 typo3-policy.hcl
```

`hashicorp.path` is written as `{mount}/data/{prefix}`, so the policy
above matches the default `secret/data/typo3`. A nested mount such as
`team/kv/data/typo3` is supported: the first path segment named `data`
separates the mount from the prefix.

## Choose an authentication method {#operations-hashicorp-adapter-auth}

Set the method in `hashicorp.authMethod`. The storage adapter implements all
three. The `transit` master key provider still implements `token` only.

### Token {#token}

```bash
vault token create -policy=typo3 -period=24h
```

Export the token to the PHP process as `VAULT_TOKEN` (or the name set in
`hashicorp.tokenEnvVar`). A token stored in `hashicorp.token` also works but
is readable in the Install Tool and lands in configuration exports. A token has
no fallback: when it expires or is revoked, requests fail until you replace it.
Use a periodic token that something renews.

### AppRole {#approle}

```bash
vault auth enable approle
vault write auth/approle/role/typo3 token_policies=typo3 token_ttl=1h
vault read auth/approle/role/typo3/role-id
vault write -f auth/approle/role/typo3/secret-id
```

Put the role id in `hashicorp.roleId`. Export the secret id as
`VAULT_SECRET_ID` (or the name in `hashicorp.secretIdEnvVar`). The secret id
is read from the environment only; there is no setting that stores it. The login
token lives for the request or CLI run, is refreshed before its lease ends, and
is replaced once by a new login if Vault rejects it with 403.

### Kubernetes {#kubernetes}

```bash
vault auth enable kubernetes
vault write auth/kubernetes/config kubernetes_host=https://kubernetes.default.svc
vault write auth/kubernetes/role/typo3 \
    bound_service_account_names=typo3 \
    bound_service_account_namespaces=web \
    token_policies=typo3 token_ttl=1h
```

Set `hashicorp.kubernetesRole` to `typo3`. The adapter reads the pod's
service account token from `hashicorp.kubernetesJwtPath` (default
`/var/run/secrets/kubernetes.io/serviceaccount/token`) on every login.

## Configure TYPO3 {#operations-hashicorp-adapter-config}

**config/system/additional.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_vault']['storageAdapter'] = 'hashicorp';
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_vault']['hashicorp'] = [
    'address'    => 'https://vault.example.com:8200',
    'path'       => 'secret/data/typo3',
    'authMethod' => 'approle',
    'roleId'     => 'b2c1…',
];
```

Every setting is described under [Extension configuration](https://docs.typo3.org/permalink/netresearch/nr-vault:configuration-extension@1.8). The adapter
reads its configuration on each request; nothing is cached across requests.

## Network and TLS {#operations-hashicorp-adapter-network}

-   The address must use `https`. `hashicorp.allowInsecureHttp` allows
    `http` for local development; with it on, the token and every envelope
    cross the network unencrypted.
-   The address must be a bare origin: no credentials, path, query or fragment.
-   Requests use the same client as every other outbound call of the extension.
    It refuses loopback, private, link-local and metadata addresses, follows no
    redirects and logs no requests. A Vault on a private network therefore needs
    a literal entry (a wildcard does not count) in
    `$GLOBALS['TYPO3_CONF_VARS']['HTTP']['allowed_hosts']`:

    **config/system/additional.php**

    ```php
    $GLOBALS['TYPO3_CONF_VARS']['HTTP']['allowed_hosts'][] = 'vault.internal.example.com';
    ```
-   A whole transfer is bounded to ten seconds.

## Behaviour you should know {#operations-hashicorp-adapter-behaviour}

-   **Failure**

    A Vault outage or a rejected token makes the secrets stored in Vault
    unreadable and new secrets unwritable; secrets stored locally are unaffected.
    On store, Vault is written first: a failure leaves no row behind.

-   **Paths that already hold data**

    A new secret claims its KV path with a create-only write, in one request. If
    the path holds anything that is not an nr-vault write for that identifier,
    the store is refused (code `1794400012`), the data is left unchanged and no
    row is written; a key created by someone else at the same moment is refused
    the same way. Use a dedicated `hashicorp.path` so paths cannot collide with
    other users of the mount. The policy needs `create` on the data path (the
    one above has it). An unreferenced key that an interrupted nr-vault write
    of this installation left behind is recognised and reused; a key written by
    another installation is not, so give each installation its own
    `hashicorp.path`. A row whose stored location differs from the one the
    current `hashicorp.path` resolves to is refused (code `1794400015`).
    If the audit write of a create then fails, a reused key is put back as it
    was; a key the call created is removed. A rollback that is skipped because
    somebody wrote to the key since is logged as a warning.

-   **Half-finished writes**

    A crash between the Vault write and the row write leaves an unreferenced key
    in Vault, which the next store of that identifier overwrites. A row whose
    Vault key is missing is reported as an error when the value is read (code
    `1794400009`), never returned as an empty secret. `vault:delete` and
    `vault:rotate` still reach the row, so you can remove it or write a new
    value.

-   **Delete**

    Deleting removes the Vault key with all of its versions, then the row. Run
    `vault:delete` again after an interrupted delete.

-   **Master-key rotation**

    `vault:rotate-master-key` refuses while any secret is stored outside the
    local database. It names the first one it meets and changes nothing. Data
    keys held in Vault are not re-wrapped by this release.

-   **Audit**

    Every operation is written to the nr-vault audit log, and when the audit
    write fails the previous state is restored. Unlike local secrets, the Vault
    write and the database write are not one transaction: a crash after the
    Vault write and before the audit write persists the change without an audit
    entry. Vault's own audit device records every access to the KV paths, so
    monitor it for writes and deletes that have no matching nr-vault entry.
    Vault has no audit device until an operator enables one (`vault audit
    enable file file_path=/var/log/vault_audit.log`), so enable one before you
    rely on this.

-   **Changing `hashicorp.path`**

    The Vault key of a secret is derived from the current setting. Existing
    Vault-backed secrets are not found under a new path, so move the keys in
    Vault first (or keep the old path) before you change it.

-   **Backup**

    The database no longer contains the envelopes. A restore needs the database
    dump, the master key and a Vault that still holds the KV data; back all three
    up, and keep them apart ([Backup and restore](https://docs.typo3.org/permalink/netresearch/nr-vault:operations-backup-and-restore@1.8)).

## Troubleshooting {#operations-hashicorp-adapter-troubleshooting}

| Message | Likely cause |
| --- | --- |
| `address must use https` | The address is `http`. Use https, or set `hashicorp.allowInsecureHttp` on a development machine. |
| `could not be sent` with a blocked-host message | The address is private or loopback and not listed in `allowed_hosts`. |
| `was rejected with HTTP 403` | The token or the policy does not allow the path. Compare the policy with `hashicorp.path`. Under `token` there is no retry. |
| `login was rejected` | Wrong role id, spent secret id, or a Kubernetes role that does not bind the pod's service account. |
| `login credential is missing` | The environment variable or service account file named in the message is not visible to the PHP process. |
| `holds no value for it` | The Vault key was deleted outside nr-vault, or the row points at another Vault. Restore the key from a Vault snapshot. |
