Skip to main content

HashiCorp Vault

Visualize Hashicorp Vault users and secret engines, map Vault users to employees, and monitor changes through queries and alerts.

Installation​

This integration ingests HashiCorp Vault accounts, secret engines, secrets, auth backends, users, and OIDC identity entities. It supports both standalone (on-premise) and HashiCorp Vault Cloud (HCP). Three authentication methods are available: a static Vault token, OIDC via Azure Entra ID, or AppRole (Role ID + Secret ID).

Prerequisites​

The Vault token or service principal you configure must have ACL policies granting the capabilities listed below. Add these rules to the policy attached to the token or Vault role.

Token self-lookup (required for all deployments)

path "auth/token/lookup-self" {
  capabilities = ["read"]
}

Mount discovery (required for all deployments)

path "sys/internal/ui/mounts" {
  capabilities = ["read"]
}

Secret engines — one rule per engine you want to ingest (KV v1, KV v2, and Cubbyhole)

# KV v1 example
path "my-kv-engine/*" {
  capabilities = ["list"]
}

# KV v2 example: secrets are listed and their metadata read under the metadata/ sub-path
path "my-kv2-engine/metadata/*" {
  capabilities = ["list", "read"]
}

# Cubbyhole (already granted by Vault's built-in default policy)
path "cubbyhole/*" {
  capabilities = ["list"]
}

JupiterOne walks every folder under each engine, and any folder the token cannot list is skipped along with the secrets under it, so the rule should cover the whole engine. Without read on a KV v2 engine's metadata/* path, secrets are still ingested but without their version, timestamps or custom metadata.

Userpass auth method users — one pair of rules per userpass mount

path "auth/my-userpass/users" {
  capabilities = ["list"]
}

path "auth/my-userpass/users/*" {
  capabilities = ["read"]
}

OIDC identity entities (required when using the OIDC auth section, or the AppRole section on a cluster that has a JWT/OIDC auth method mounted)

path "identity/entity/id" {
  capabilities = ["list"]
}

path "identity/entity/id/*" {
  capabilities = ["read"]
}
info

For more information on HashiCorp Vault ACL policies, see the Vault policies documentation.

Configuration in HashiCorp Vault​

Choose the authentication method that fits your deployment.

Option A: API Token​

  1. Create or identify a Vault token whose policy includes the capabilities listed above.
  2. If you use Vault Enterprise or HCP Vault, note the namespace for your cluster (for example, admin or admin/team-a). The namespace is optional for standalone Vault.
  3. Note the hostname of your Vault cluster, including the https:// scheme (for example, https://vault.example.com:8200).
tip

For more information on Vault tokens, see the Vault tokens guide.

Option B: OIDC via Azure Entra ID​

This method obtains a short-lived Vault token by exchanging an Azure Entra ID client-credentials JWT for a Vault login token via a Vault JWT/OIDC auth method.

  1. In Azure Entra ID, create an app registration for the JupiterOne integration. Note the Tenant ID, Client ID, and create a Client Secret.
  2. In HashiCorp Vault, configure a JWT/OIDC auth method (for example, mounted at jwt or oidc). Create a role with:
    • role_type = "jwt"
    • bound_issuer set to https://sts.windows.net/<your-tenant-id>/
    • bound_audiences set to the Entra Client ID (or the custom audience you specify in Vault Audience)
    • The policy grants listed in the prerequisites above
  3. Note the auth mount path (for example, jwt). If left blank, it defaults to oidc.

Option C: AppRole (Role ID + Secret ID)​

This method exchanges a RoleID and SecretID for a short-lived Vault token at the AppRole login endpoint on each run, so no long-lived token needs to be provisioned for JupiterOne.

  1. In HashiCorp Vault, enable the AppRole auth method if it is not already enabled, and note the mount path without the auth/ prefix (for example, approle, not auth/approle). If left blank in JupiterOne, it defaults to approle. On Vault Enterprise or HCP Vault, enable it in the same namespace you configure in JupiterOne: the login is sent to that namespace.
  2. Create a role whose token_policies grant the capabilities listed in the prerequisites above. The integration logs in again whenever the token nears expiry, so any token_ttl works; a very short TTL only means more logins.
  3. Leave the role's token_num_uses at 0 (unlimited, the default). JupiterOne rejects use-limited tokens, because a token that runs out of uses partway through a sync would silently cut ingestion short.
  4. Read the role's RoleID and generate a SecretID for it.
  5. Note the hostname of your Vault cluster, including the https:// scheme. The SecretID is a bearer credential, so this section requires https://.
tip

For more information on this auth method, see the Vault AppRole documentation.

Configuration in JupiterOne​

Navigate to the Integrations tab in JupiterOne and select HashiCorp Vault. Click New Instance and select an authentication section.

API Token​

Creating an instance requires:

  • HashiCorp Vault Hostname — The full URL of your Vault cluster, including the https:// scheme (for example, https://vault.example.com:8200).
  • HashiCorp Vault Namespace — The Vault namespace header value. Required for Vault Enterprise and HCP Vault clusters; leave blank for standalone Vault.
  • HashiCorp Vault Token — A static Vault token whose attached policy grants the capabilities listed in the prerequisites.

OIDC (Azure Entra ID)​

Creating an instance requires:

  • HashiCorp Vault Hostname — The full URL of your Vault cluster, including the https:// scheme.
  • HashiCorp Vault Namespace — The Vault namespace header value. Required for Vault Enterprise and HCP Vault; leave blank for standalone Vault.
  • Entra Tenant ID — The Azure Entra tenant ID (Directory ID) for your app registration.
  • Entra Client ID — The application (client) ID of the Entra app registration.
  • Entra Client Secret — A client secret value for the Entra app registration.
  • Vault JWT/OIDC Role — The name of the Vault JWT/OIDC role to log in as.
  • Vault JWT/OIDC Mount Path (optional) — The auth mount path for the JWT/OIDC method (for example, jwt or oidc). Defaults to oidc when left blank.
  • Vault Audience (optional) — The audience value the Vault role expects in the JWT aud claim. Falls back to the Entra Client ID when left blank.

AppRole (Role ID + Secret ID)​

Creating an instance requires:

  • HashiCorp Vault Hostname — The full URL of your Vault cluster, including the https:// scheme.
  • HashiCorp Vault Namespace — The Vault namespace header value. Required for Vault Enterprise and HCP Vault; leave blank for standalone Vault. The AppRole login is also sent to this namespace, so the AppRole auth method must be enabled in it.
  • Vault AppRole Role ID — The RoleID of the Vault AppRole to log in as.
  • Vault AppRole Secret ID — A SecretID issued for that AppRole. Rotate it in Vault and update it here as your SecretID TTL requires.
  • Vault AppRole Mount Path (optional) — The auth mount path for the AppRole method, without the auth/ prefix (for example, approle). Defaults to approle when left blank.

Click Create once all required fields are provided.

Data Volume Configuration​

These optional settings control which secret metadata is ingested and whether secret values are read to fingerprint embedded certificates. They apply to every authentication method.

Data Filtering Options​

FieldDescriptionDefaultOptions
Custom Metadata KeysA comma-separated list of KV v2 custom metadata keys to ingest as customMetadata.<key> properties on secret entities. Append :boolean, :number, or :date to a key to convert its value (keys without a suffix stay strings). Dates must be ISO 8601 (for example, 2027-10-07 or 2027-10-07T12:00:00Z) and are read as UTC unless they carry an offset; to also accept another layout, add it in parentheses, such as DD-MM-YYYY, DD/MM/YYYY, DD.MM.YYYY, MM-DD-YYYY, or MM/DD/YYYY. Values that do not match are omitted. For example: expires_at:date(DD-MM-YYYY),has_expiry:boolean,owner,type.None (no custom metadata ingested)Any custom metadata key names
Expiry Metadata KeyA custom metadata key whose value is also ingested as the secret's standard expiration property (for example, expires_at). The value is parsed using the date format you declared for that key in Custom Metadata Keys, or ISO 8601 if the key is not listed there.None (no expiration set)A single custom metadata key name
note

Adding a type to a key that is already ingested changes that property's type, so update any queries or rules that compare it as a string.

Advanced Configuration​

FieldDescriptionDefault
Hash CertificatesWhen enabled, JupiterOne reads each KV and Cubbyhole secret value to detect embedded PEM X.509 certificates and records their SHA-256 fingerprints on the secret entity. This requires the Vault token to also have read on the secret data path: path "my-kv2-engine/data/*" { capabilities = ["read"] } for KV v2, or read added to the my-kv-engine/* rule for KV v1. This is a broader grant than the rest of the integration needs, so leave the option off unless you use it. Reading secret values also increases integration run time.Disabled

Next steps​

After creating the instance, it will begin ingesting data on the polling interval you selected. Continue to the Instance management guide to learn more about working with integration instances.