generated from coulomb/repo-seed
tegwick
0c1082059b
Document the railiance-platform credential broker as the owner-native path for scoped VAULT_TOKEN needs. Add catalog entry, playbook, and doc updates so warden route find ranks the broker lane first; manual export remains a documented fallback only.
134 lines
3.7 KiB
Markdown
134 lines
3.7 KiB
Markdown
# Operator OpenBao Token Hygiene
|
|
|
|
Date: 2026-06-24
|
|
Workplan: WARDEN-WP-0013 T4
|
|
|
|
Production `warden sign` against OpenBao needs a **scoped** `warden-sign` token in
|
|
`VAULT_TOKEN` — not the cluster root token. Prefer the credential broker so you
|
|
never paste or export the raw token manually.
|
|
|
|
---
|
|
|
|
## Preferred path (credential broker)
|
|
|
|
Use the railiance-platform broker to mint a short-lived child token and inject it
|
|
only into the command that needs it:
|
|
|
|
```bash
|
|
cd ~/railiance-platform
|
|
make credential-exec-ops-warden-smoke # policy-gate smoke, no manual VAULT_TOKEN
|
|
|
|
# Or for a single sign:
|
|
scripts/credential.py exec \
|
|
--grant ops-warden/warden-sign \
|
|
--purpose ops-warden-production-sign-smoke \
|
|
--ttl 15m -- \
|
|
warden sign <actor> --pubkey <path>
|
|
```
|
|
|
|
Routing: `warden route show ops-warden-warden-sign-token --json` · playbook:
|
|
`wiki/playbooks/ops-warden-warden-sign-token.md`.
|
|
|
|
ops-warden does not mint OpenBao tokens — the broker in `railiance-platform` does.
|
|
|
|
---
|
|
|
|
## 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 (manual fallback)
|
|
|
|
Use only when the broker is unavailable and you already hold a scoped token
|
|
out-of-band:
|
|
|
|
```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/playbooks/ops-warden-warden-sign-token.md` — preferred broker path
|
|
- `wiki/OpenBaoSshEngineChecklist.md`
|
|
- `wiki/OpsWardenConfig.md` — Authentication section
|
|
- `examples/warden.production.example.yaml` |