46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
# Token rotation
|
||
|
||
Monlet v1 uses a single shared Bearer token (`MONLET_AUTH_TOKEN`) for all agent and UI endpoints (ADR-0007). Per-agent tokens and dual-token acceptance are out of scope for v1.
|
||
|
||
## Why rotation is disruptive in v1
|
||
|
||
The server validates exactly one token at a time. Agents that present the old token after the server has switched receive `401`, which the agent treats as a **non-retryable** failure and drops the affected batch from its local spool (`agent/internal/client/client.go`, `agent/internal/app/app.go`). Events flushed during the mismatch window are lost — they are not re-spooled and not re-sent.
|
||
|
||
Plan rotations during a low-traffic window and either stop the agents first (so spooled events persist on disk until they restart with the new token) or accept the event-loss window.
|
||
|
||
## When to rotate
|
||
|
||
- A suspected leak (token committed, log exposure, lost laptop with `config.toml`).
|
||
- Operator turnover.
|
||
- Routine schedule (e.g., quarterly).
|
||
|
||
## Procedure
|
||
|
||
1. **Generate a new token**:
|
||
|
||
```sh
|
||
openssl rand -hex 32
|
||
```
|
||
|
||
2. **Stop or pause agents** (recommended). Either:
|
||
- `systemctl stop monlet-agent` on each host; spooled events remain on disk and replay after restart, or
|
||
- skip this step and accept that any events sent during steps 3–4 are lost on the `401`.
|
||
|
||
3. **Restart server** with the new `MONLET_AUTH_TOKEN`. Verify:
|
||
|
||
```sh
|
||
curl -sf -H "Authorization: Bearer $NEW" http://server:8000/api/v1/agents | jq .
|
||
```
|
||
|
||
4. **Update agent `config.toml`** (`[server].token`) on each host and start agents.
|
||
|
||
5. **Update Web UI** (`MONLET_API_TOKEN`) and restart.
|
||
|
||
6. **Revoke the old token**: remove the old value from secret stores, CI variables, and operator notes.
|
||
|
||
## Notes
|
||
|
||
- The token is the only auth in v1; protect it like a database password.
|
||
- The token never appears in metrics labels, incident keys, or notification labels (ADR-0007, redaction policy).
|
||
- The server redacts `Authorization`/`Cookie`-style headers before logging (`monlet_server/redaction.py`).
|