# 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`