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:- 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
defaultandrootpolicies 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.
- 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.
Prerequisites
- A Vault cluster with a public
httpsaddress that Oleria can reach. Oleria refuseshttp,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.
- A Vault user who can write ACL policies and create an orphan, periodic token. Vault requires
sudopermission to create one. Without it, ask a Vault administrator to create a token role, as described in 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 Then write the policy:
oleria.hcl. Add one metadata/* rule for each KV v2 mount you want Oleria to inventory, and replace secret with the mount 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:Vault requires Copy the
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:token value from the output. Replace 768h with the period your policy allows.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
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 afterconnection validation failed. actual error: or received invalid inputs. actual error:. Errors about reaching the cluster appear in Oleria’s own wording instead.
How Oleria reads ACL policies
Oleria parses each ACL policy and matches itspath 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
denywins. - All KV v2 paths count. Vault checks the
data/,metadata/,delete/,destroy/, andundelete/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 throughmetadata/ordestroy/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
denycancels 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
rootpolicy shows every capability, includingsudo, 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_policieson an AppRole, Kubernetes, or OIDC role), directly on a token, or implicitly asdefaultappears 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. Allow Oleria’s IP addresses. To get them, contact support@oleria.com.

