Skip to main content
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.
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 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.
  • 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.
  • 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.
  • 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.
Then write the policy:
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:
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:
Copy the token value from the output. Replace 768h with the period your policy allows.
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

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.

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. Allow Oleria’s IP addresses. To get them, contact support@oleria.com.

Contact us

For questions about this integration, contact us at support@oleria.com.