generated from coulomb/repo-seed
tegwick
90007c2cda
Ship flex-auth policy gate registry and smoke evidence, archive WP-0009 through WP-0013, and add integration docs: ops-bridge cert_command migration playbook, operator OpenBao token hygiene, principals drift check script, and 2026-06-24 INTENT/SCOPE gap analysis.
105 lines
2.8 KiB
Markdown
105 lines
2.8 KiB
Markdown
# Operator OpenBao Token Hygiene
|
|
|
|
Date: 2026-06-24
|
|
Workplan: WARDEN-WP-0013 T4
|
|
|
|
Daily `warden sign` against production OpenBao requires a **scoped** API token in
|
|
`VAULT_TOKEN` — not the cluster root token.
|
|
|
|
---
|
|
|
|
## Rules
|
|
|
|
| Rule | Rationale |
|
|
| --- | --- |
|
|
| Never commit `VAULT_TOKEN` | Tokens are secrets |
|
|
| Never paste tokens in chat, State Hub, or workplans | Same |
|
|
| Do not use root token for daily `warden sign` | Break-glass only |
|
|
| Prefer short-lived tokens | Limit blast radius |
|
|
| Refresh on HTTP 403 | Token expired or policy mismatch |
|
|
|
|
---
|
|
|
|
## Scoped token for warden
|
|
|
|
Production signing needs permission to call the SSH engine sign endpoint for the
|
|
roles mapped in `warden.yaml` (`adm-role`, `agt-role`, `atm-role`).
|
|
|
|
Illustrative policy shape (create in OpenBao policy admin — adjust names to match
|
|
your cluster):
|
|
|
|
```hcl
|
|
# warden-sign — least privilege for ops-warden CLI
|
|
path "ssh/sign/agt-role" {
|
|
capabilities = ["create", "update"]
|
|
}
|
|
path "ssh/sign/adm-role" {
|
|
capabilities = ["create", "update"]
|
|
}
|
|
path "ssh/sign/atm-role" {
|
|
capabilities = ["create", "update"]
|
|
}
|
|
```
|
|
|
|
Issue a token bound to `warden-sign` (operator procedure in `railiance-platform` /
|
|
OpenBao admin runbooks).
|
|
|
|
---
|
|
|
|
## Session pattern
|
|
|
|
```bash
|
|
# Set for current shell only — do not add to ~/.bashrc with a literal token
|
|
export VAULT_TOKEN="<scoped-token>"
|
|
|
|
warden status agt-state-hub-bridge
|
|
warden sign agt-state-hub-bridge --pubkey ~/.ssh/agt-state-hub-bridge_ed25519.pub
|
|
```
|
|
|
|
`warden` reads the env var named in `vault.token_env` (default `VAULT_TOKEN`).
|
|
|
|
---
|
|
|
|
## OIDC / interactive login
|
|
|
|
For human operators, prefer platform OIDC login that yields a short-lived OpenBao
|
|
token instead of copying long-lived secrets.
|
|
|
|
| Need | Route to |
|
|
| --- | --- |
|
|
| Interactive login, OIDC, MFA | key-cape / Keycloak — `warden route show key-cape-oidc-login` |
|
|
|
|
ops-warden does not implement login; it documents the route only.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Likely cause | Action |
|
|
| --- | --- | --- |
|
|
| `Vault token not found` | `VAULT_TOKEN` unset | Export scoped token |
|
|
| `HTTP 403` / `permission denied` | Expired token or insufficient policy | Re-issue `warden-sign` token |
|
|
| `Signing failed` + connection error | Wrong `vault.addr` or network | Check `warden.yaml`, tunnel/VPN |
|
|
| Suggest `--backend local` | OpenBao unreachable | Fix connectivity; local is lab-only |
|
|
|
|
After fixing token issues, re-run:
|
|
|
|
```bash
|
|
warden sign <actor> --pubkey <path>
|
|
```
|
|
|
|
---
|
|
|
|
## Root token (break-glass only)
|
|
|
|
Cluster root tokens bypass all policy. Use only for one-time engine setup
|
|
(`wiki/OpenBaoSshEngineChecklist.md` § One-time SSH engine setup), then revoke
|
|
from daily shell profile.
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
- `wiki/OpenBaoSshEngineChecklist.md`
|
|
- `wiki/OpsWardenConfig.md` — Authentication section
|
|
- `examples/warden.production.example.yaml` |