Skip to main content
Version: 0.15

HashiCorp Vault

TokenTimer scans Vault KV v2 and PKI mounts over the REST API to discover secrets and certificates with expiration dates. No SDK or agent is required.

Vault URL format: https://vault.example.com:8200

The address must use http or https. For a private Vault CA, set NODE_EXTRA_CA_CERTS on the API (Node reads it at process start).

Authenticate with a static token or AppRole (role ID and secret ID). The two modes are exclusive. AppRole works for manual scans on Core and Enterprise. Where Enterprise auto-sync is entitled, AppRole credentials can be stored for scheduled scans the same way a token can. Core scheduled auto-sync stays GitHub and GitLab; Vault auto-sync is not a Core capability.

Optional Vault Enterprise or HCP namespace applies to both Token and AppRole (X-Vault-Namespace on every Vault call, including AppRole login).

Credential setup​

Option A: Vault token​

  1. Go to Vault UI → Access → Tokens → Create Token
  2. Attach a policy with at least read/list on the KV v2 and PKI mounts you scan (see Permissions)
  3. Set a TTL (recommended: 1-7 days for one-time use on Core; longer or renewable as needed if Enterprise stores credentials for auto-sync)
  4. Copy the token immediately (it will not be shown again)
  5. In TokenTimer, choose Token auth, paste the token, and set Namespace if your Vault uses one
  6. On Core, revoke after use: the token is used once and never stored. On Enterprise auto-sync, credentials may be stored where entitled (see the info box below).

Option B: AppRole​

  1. Enable AppRole auth in Vault (default mount path approle, or note your custom path)
  2. Create a role whose token policies cover the mounts you scan
  3. Generate a role ID and secret ID for that role
  4. In TokenTimer, choose AppRole auth and enter:
    • Role ID and Secret ID (required)
    • Auth mount (optional; default approle; no leading or trailing slashes)
    • Namespace (optional; same field as Token auth; Vault Enterprise or HCP)
  5. A reusable SecretID (secret_id_num_uses=0) is practical when TokenTimer must authenticate more than once (listing mounts and scanning each use a login; Enterprise auto-sync). HashiCorp prefers finite or single-use SecretIDs with external rotation when available. TokenTimer does not issue or rotate secret IDs.
  6. On Core, credentials are used for the manual scan only and never stored. On Enterprise, AppRole is available for auto-sync where entitled.

Token and AppRole cannot be combined in one scan. For AppRole, when auth.lease_duration is greater than 0, TokenTimer refreshes the client token after about 80% of that TTL. A Vault 403 is treated as a permission or revocation failure, not as token expiry to retry. A failed AppRole refresh aborts the scan.

A scan that cannot list mounts after a successful login is HTTP 403 with code: VAULT_PERMISSION_DENIED, not 502. A scan that can list a mount but cannot read some objects reports hasErrors / permissionDenied on that mount. The import UI shows a warning, not a green success badge.

Permissions required​

Minimum capabilities (example paths; adjust mount names to match your engines):

  • sys/mounts: read
  • KV v2 secret/metadata/*: list
  • KV v2 secret/data/*: read
  • PKI pki/certs: list
  • PKI pki/cert/*: read

TokenTimer GETs KV v2 secret data (and PKI public certificate PEM) to discover expiration and type heuristics. It does not persist secret values.

What is discovered​

  • KV v2 secrets: path, name, expiration (if present), auto-detected category/type
  • PKI certificates: serial, subject, issuer, expiration (notAfter)

PEM and base64 DER formats are supported. Smart heuristics auto-map types (for example certificates map to ssl_cert, API keys to api_key).

Scan options​

  • Filter rules: optional include/exclude rules (exact or regex, on name or description) applied to the scan preview and the import. See Filter rules.
  • Remove obsolete items: opt-in cleanup that deletes previously imported tokens no longer found at the source. See Obsolete-token cleanup.
info

Vault does not support auto-sync on self-hosted TokenTimer Core. Each scan is a one-time, manual action; credentials (token or AppRole) are used once and never stored. TokenTimer Enterprise adds scheduled auto-sync for this provider under a per-provider license entitlement, including AppRole auth; see Enterprise auto-sync.