Skip to content

Authentication Overview

dotvault supports four methods for authenticating to HashiCorp Vault:

Method Best for How it works
OIDC Desktop users with SSO Opens a browser for identity provider login
LDAP Environments with LDAP/AD and MFA Terminal prompt for password + optional MFA
Token Automation, CI/CD, development Uses a pre-existing Vault token
mTLS Long-lived unattended auth A TLS client certificate authenticates; LDAP/OIDC is a one-time bootstrap

Set the method in your config file:

vault:
  address: "https://vault.example.com:8200"
  auth_method: "oidc"    # or "ldap", "token", "mtls"

Any of these methods can additionally seal its cached token at rest under the machine's TPM — append a +tpm suffix (oidc+tpm, ldap+tpm, mtls+tpm). +tpm is a modifier, not a separate method: the login flow is unchanged, only how the token rests on disk. (For mtls+tpm the certificate's private key is sealed too.) See TPM-Backed Protection for what it does, when to use it, and the per-platform requirements.

Authentication flow

CLI mode

When running without the web UI, dotvault authenticates directly:

  • OIDC — opens a browser window and listens on a random localhost port for the callback
  • LDAP — prompts for a password in the terminal; handles MFA challenges inline
  • Token — reads from the DOTVAULT_TOKEN environment variable or ~/.dotvault-token file

Web UI mode

When the web UI is enabled (web.enabled: true), all authentication is handled through the browser-based SPA. If the daemon starts without a valid token, it opens the web UI in the user's browser where they can log in.

Token lifecycle

After successful authentication, dotvault manages the Vault token automatically:

  • Token renewal — the token is renewed at 75% of its remaining TTL
  • TTL monitoring — checked every 5 minutes
  • Automatic re-auth — if the token expires or a 403 Forbidden is received, dotvault triggers re-authentication
  • Exponential backoff — on renewal failure, retries with backoff from 1 second to 5 minutes

In web mode, re-authentication opens the browser to the web UI login page. In CLI mode, re-authentication uses the configured auth method directly.

Token persistence

Vault tokens are persisted to ~/.dotvault-token with 0600 permissions — a dotvault-specific filename rather than Vault's default ~/.vault-token, so a concurrent vault CLI session cannot clobber the daemon's cached token. On restart, dotvault attempts to reuse this token before initiating a new authentication flow. The DOTVAULT_TOKEN environment variable takes precedence if set; the upstream VAULT_TOKEN variable is deliberately ignored for the same isolation reason as the filename.

When the auth method carries the +tpm suffix, the token file holds a TPM-sealed envelope instead of the plaintext token. The file is self-describing, so reuse-on-restart and the public client library unseal it transparently — no extra configuration on the reader side. The DOTVAULT_TOKEN environment variable is always plaintext (an environment value cannot be sealed), so the seal protects the on-disk file only.