Authentication
Vault verifies an identity through a configured auth method and returns a token.
Chapter contract
Prerequisites:
No prior Vault experience. Docker is needed only when you start the shared lab.
User-visible outcome:
You can trace one Lockbox request from workload identity through policy to a leased response and name each owner.
Learning objectives
- Distinguish authentication, authorization, a secrets engine, and a lease.
- Trace one Project Lockbox request without treating Vault as a generic database.
- Name the application, platform, and Vault-team ownership boundaries.
Consumer flow
Ownership boundary
| Owner | Consumer-facing responsibility |
|---|---|
| You own | Owns how a process consumes, reloads, and stops using secret material. |
| Platform team owns | Provides a trusted runtime identity and reachable Vault endpoint. |
| Vault owns | Operates Vault, auth methods, policies, engines, audit, and recovery. |
Core concepts
Authorization
Policies attached to that token decide which path operations are allowed.
Secrets engine
A mounted backend stores data or generates credentials and certificates.
Lease
Metadata gives generated material a lifetime and usually a revocation handle.
Commands and configuration
export VAULT_ADDR=http://127.0.0.1:8200
vault status
vault auth list
vault secrets listSecret-safety stop
Stop: A Vault token is a bearer credential. Never paste it into a command, ticket, log, chat, screenshot, or repository.
Failure drill
| Symptom | The application reports permission denied. |
|---|---|
| Likely causes | Wrong auth mount, wrong role, missing capability, or a KV v2 path missing its data segment. |
| Inspect safely | Record HTTP status, operation, mount, and redacted path; query token capabilities. |
| Do not print | Token, request body, returned values, or the full environment. |
Break it / fix it
Break it: Treat the auth mount as though it were a secret engine path.
Show diagnosis and fix
Fix it: Separate identity proof, policy evaluation, engine request, and lease in the request trace.
Escalate with time, endpoint, auth path, role, mount, namespace when relevant, status code, request ID, and sanitized error class. Never attach a credential or response body.
Try it
Bootstrap boundary
labs/bootstrap owns the disposable server, auth mounts, policies, roles, and engines; learner actions begin after setup.
Cost:
$0; local containers only
Starting state:
Run labs/bootstrap/setup.sh and source .runtime/learner.env unless the chapter lab says AppRole alone is sufficient.
User actions:
Start the shared disposable lab, inspect enabled auth methods and secret mounts, then map each mount to its Lockbox consumer.
cd learn-vault/labs/bootstrap
./setup.sh
./status.sh
docker compose psSuccess criteria:
Complete every item in the Verify section using metadata-only evidence; no secret value appears in terminal output or tracked files.
Troubleshooting:
Use the Failure drill and Break it / fix it evidence fields. Stop before broadening policy, weakening identity or TLS checks, or copying secret-bearing diagnostics.
Verify
- Vault and PostgreSQL report healthy in the local Compose project.
- The status script reports configured mounts without secret values.
- You can explain which component authenticates and which authorizes.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
Keep the shared lab for Chapter 2, or run ./cleanup.sh. Cleanup removes containers, volumes, and the ignored .runtime directory.
Project Lockbox increment
orders-api will use KV v2 for configuration, dynamic PostgreSQL credentials for data access, and short-lived PKI certificates for service identity.
Quick check
Does an auth method decide every allowed path?
No. It establishes identity and attaches policies; policies authorize operations.
Why is a generated database credential different from KV?
It has an external lifecycle and can be revoked by its lease.
Who decides how an application reloads?
The application team, using a delivery contract supplied by the platform.
What belongs in a safe 403 report?
Operation, redacted path, role, expected capability, time, and correlation metadata.
Gotchas
- Successful login does not imply access to a requested path.
- Healthy Vault does not prove the application can authenticate or renew.
- Token lifetime and secret lifetime are separate clocks.
Recap and next
Vault is a broker of identity-scoped capability, not an excuse to move static secrets from one file to another.