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

# HashiCorp Vault

> Connect HashiCorp Vault to Oleria to see which identities and ACL policies can reach your KV secrets, and the secrets themselves as non-human identities.

Connect a HashiCorp Vault cluster to Oleria to see who can reach which secret, which ACL policies each identity holds, and the stored secrets as non-human identities (NHIs). Oleria connects to your cluster's Vault server API with a Vault token. The connection is read-only, and Oleria never reads secret values.

> [!NOTE]
>
> This integration connects to the Vault server API at your own cluster address. It doesn't use the HCP control-plane API.

## What Oleria discovers

Oleria reads your Vault cluster on its [regular sync schedule](https://docs.oleria.com/integrations/overview.md#sync-model):

* **Users** - Vault identity entities. An entity is disabled in Oleria when Vault marks it `disabled`. Vault doesn't report MFA or SSO for an entity, so Oleria shows both as unavailable. Oleria records no email or last sign-in for an entity.
* **Groups** - Vault identity groups and their members. Internal groups appear as custom groups, and external groups as synced groups. Oleria also records a group nested in another group, so members of a subgroup show the policies of the parent group.
* **Roles** - Vault ACL policies, and which entities and groups hold each one. The built-in `default` and `root` policies are standard roles, and every other policy is a custom role.
* **Resources** - KV secrets-engine mounts, and the secrets in KV version 2 (KV v2) mounts. A KV version 1 mount appears without its secrets.
* **Access to secrets** - which policy grants which capabilities on which secret. See [How Oleria reads ACL policies](#how-oleria-reads-acl-policies).
* **Non-human identities** - each KV v2 secret appears as a token NHI linked to its secret resource. When the secret's current version is destroyed or past its deletion time, Oleria shows the NHI as disabled and the secret resource as deleted.

Oleria reads only the secrets' metadata, such as versions and deletion state. Mounts of other secrets engines, such as AWS, GCP, or database engines, aren't discovered.

## Prerequisites

* A Vault cluster with a public `https` address that Oleria can reach. Oleria refuses `http`, `localhost`, and loopback, private, link-local, and CGNAT addresses, so a cluster reachable only on a private network isn't supported.
* If your cluster or a firewall in front of it only allows known source IP addresses, allow Oleria's IP addresses. To get them, contact [support@oleria.com](mailto:support@oleria.com).
* A Vault user who can write ACL policies and create an orphan, periodic token. Vault requires `sudo` permission to create one. Without it, ask a Vault administrator to create a token role, as described in [Create a token in Vault](#create-a-token-in-vault).
* For Vault Enterprise or HCP Vault, the namespace to read. Oleria reads one namespace for each connection.
* Admin access on the Oleria platform to add a new integration.

## Create a token in Vault

**1. Create an ACL policy**

Save the following policy to a file, such as `oleria.hcl`. Add one `metadata/*` rule for each KV v2 mount you want Oleria to inventory, and replace `secret` with the mount path.

```hcl theme={null}
path "sys/mounts"           { capabilities = ["read"] }
path "identity/entity/id"   { capabilities = ["list"] }
path "identity/entity/id/*" { capabilities = ["read"] }
path "identity/group/id"    { capabilities = ["list"] }
path "identity/group/id/*"  { capabilities = ["read"] }
path "sys/policies/acl"     { capabilities = ["list"] }
path "sys/policies/acl/*"   { capabilities = ["read"] }
path "secret/metadata/*"    { capabilities = ["read", "list"] }
```

Then write the policy:

```bash theme={null}
vault policy write oleria oleria.hcl
```

> [!WARNING]
>
> Grant both the `list` paths and the matching `/*` read paths. Oleria lists entities, groups, and policies, and then reads each one individually. With only the `list` paths, every read returns `403`, and the sync fails with a permission error that names the missing `/*` path.

**2. Create a token for the policy**

Create an orphan, periodic token, so that Vault doesn't revoke it when the token that created it expires:

```bash theme={null}
vault token create -orphan -period=768h -policy=oleria
```

Vault requires `sudo` permission to set `-orphan` and `-period`. If you don't have it, a Vault administrator can create a token role that you then create the token against:

```bash theme={null}
vault write auth/token/roles/oleria allowed_policies=oleria orphan=true period=768h
vault token create -role=oleria
```

Copy the `token` value from the output. Replace `768h` with the period your policy allows.

> [!WARNING]
>
> Oleria never renews the token. Renew it before each period ends, for example by calling `auth/token/renew-self` on a schedule. Vault expires a token that isn't renewed, and the integration stops syncing when it expires.

**3. Note the cluster address and namespace**

Copy your cluster address, for example `https://vault.example.com:8200`. For Vault Enterprise or HCP Vault, also note the namespace.

## Connect HashiCorp Vault to Oleria

**1. Open the integration**

Sign in to your Oleria workspace, go to **Integrations**, and select the **HashiCorp Vault** tile.

**2. Complete the connection form**

| Field | Notes |
| :- | :- |
| **Vault Address** | Required. The cluster address, such as `https://vault.example.com:8200`. It must use `https`, and it must be a public address. |
| **Vault Token** | Required. The token you created in Vault. |
| **Namespace (optional)** | Optional. The Vault Enterprise or HCP Vault namespace to read. For HCP Vault Dedicated, enter `admin` or the child namespace your token belongs to, because HCP doesn't give customers access to the root namespace. For other clusters, leave it blank for the root namespace. |
| **Skip TLS Verification (for HCP Vault with private CA)** | Optional. Cleared by default. Select it only if your cluster's TLS certificate comes from a private certificate authority (CA). |

> [!WARNING]
>
> **Skip TLS Verification** turns off certificate checks completely, and Oleria sends the token on every request. Use a publicly trusted certificate on your cluster instead, if you can.

When you edit the integration, enter the Vault token again. The edit form requires it, even if you change only another field.

**3. Save the integration**

Select **Authenticate**. Oleria validates the token by listing your secrets-engine mounts, and stores the token securely.

## Verify the integration

Confirm the new instance appears on the **Connected** tab of your **Integrations** page. After the first sync completes, you can review the discovered entities, groups, policies, mounts, and secrets in your Oleria workspace.

## Troubleshooting

Some connection errors appear after `connection validation failed. actual error:` or `received invalid inputs. actual error:`. Errors about reaching the cluster appear in Oleria's own wording instead.

| Error | Cause and fix |
| :- | :- |
| `vault: vaultAddr "<address>" uses http, which would send the Vault token unencrypted; use https` | **Vault Address** starts with `http://`. Oleria sends the token on every request, so it accepts only `https`. Enter the `https` address. |
| `vault: vaultAddr "<address>" points at an internal address (localhost, loopback, private, link-local or CGNAT); use the cluster's public address` | **Vault Address** is `localhost`, an internal IP address, or a host name that resolves to an internal address. Enter the cluster's public address. |
| `vault: vaultAddr "<address>" must be an absolute https URL with a host (e.g. https://vault.example.com:8200)` | **Vault Address** isn't a full URL. Include `https://` and the host name. |
| `vault: GET /v1/sys/mounts status 403` (the message continues with Vault's own text, such as `permission denied`) | Vault refused the request. Check these causes: the token is mistyped, expired, or revoked, the token's policy lacks `read` on `sys/mounts`, **Namespace** isn't the namespace the token belongs to, or, on HCP Vault Dedicated, **Namespace** is blank. HCP doesn't give customers access to the root namespace, so enter `admin` or a child namespace. Fix the cause, then enter the token again. |
| `Oleria can't reach HashiCorp Vault at the address you entered. Check that the server is running and reachable from Oleria, then try again.` | Oleria couldn't connect to the **Vault Address**: the host is down, DNS doesn't resolve it, a firewall blocks Oleria, or the TLS handshake failed. Check the address and your firewall rules, and allow Oleria's IP addresses. If your cluster's certificate comes from a private certificate authority, select **Skip TLS Verification (for HCP Vault with private CA)**. |
| `Oleria can't connect to HashiCorp Vault at the address you entered because it's a private network address. ...` | The host name resolves to a private address. Vault doesn't connect through the Oleria agent, so enter the cluster's public address. |
| `vault: accounts (identity entities): all N per-item reads returned 403; the token's policy must grant read on "identity/entity/id/*"` | The token's policy has the `list` path but not the matching `/*` read path. The same error appears for `identity/group/id/*` (memberships) and `sys/policies/acl/*` (access). Add the path named in the message to the policy. Oleria still discovers the secrets and mounts. |

## How Oleria reads ACL policies

Oleria parses each ACL policy and matches its `path` rules against every discovered secret, then records an access relationship from the policy's role to each secret it covers.

* **Most specific rule wins.** For each secret, one rule in a policy applies. An exact path beats a glob, then the longer literal prefix, and so on, in Vault's priority order. At equal specificity, a `deny` wins.
* **All KV v2 paths count.** Vault checks the `data/`, `metadata/`, `delete/`, `destroy/`, and `undelete/` paths of a secret separately. Oleria matches all five and merges them into one entry for each role and secret. A policy that can permanently delete a secret through `metadata/` or `destroy/` shows delete access.
* **Browse-only access isn't access.** A policy that can only read or list `metadata/` shows no access to the secret.
* **Deny.** A `deny` cancels only the capabilities on the same path type. A role is shown as denied only when a path is denied and nothing is granted on another path.
* **Root.** The built-in `root` policy shows every capability, including `sudo`, on every secret.

## Known limitations

* **Read-only:** Oleria has no remediation actions for Vault, so you can't change Vault from Oleria.
* **No direct access to secrets:** access appears as a policy role that reaches a secret, plus the memberships of entities and groups in that role. Oleria doesn't draw a direct line from an entity or group to a secret.
* **Policy holders:** Oleria records who holds a policy only for policies attached directly to an identity entity or an identity group. A policy granted through an auth method role (such as `token_policies` on an AppRole, Kubernetes, or OIDC role), directly on a token, or implicitly as `default` appears as a role with access to secrets but with no members.
* **Policies across roles:** Oleria evaluates each policy on its own. Vault merges all of a token's policies before it matches a path, so a deny in one policy and a more specific grant in another appear as two separate entries.
* **KV secrets engine only:** Oleria doesn't discover other secrets engines.
* **One namespace:** each connection reads one namespace. Oleria doesn't read other namespaces.
* **No activity:** Vault writes its audit log to a streaming audit device, not to an API Oleria can read, so Oleria shows no Vault activity.
* **Source IP allowlists:** if your cluster only allows known source IP addresses, a blocked connection fails with the "Oleria can't reach" error described in [Troubleshooting](#troubleshooting). Allow Oleria's IP addresses. To get them, contact [support@oleria.com](mailto:support@oleria.com).

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.