abrown38andClaude Opus 5.5
8a69038ab5
- stewardd init asks for the first administrator's name on a terminal.
- Tokens can be rotated (steward token rotate, POST /tokens/{id}/rotate,
Rotate in the web UI), with a grace period for the old secret, as in
Jarl. Schema migration 2 adds the token columns.
- Read-only users see the settings and a subnet's settings locked,
instead of editable fields without a Save button.
- The New token dialog only offers roles within what the user may do.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
74 lines
2.7 KiB
Markdown
74 lines
2.7 KiB
Markdown
# Users, permissions and tokens
|
||
|
||
## Users
|
||
|
||
**Administrators** may do everything, including managing users. Everyone
|
||
else gets **grants**, `resource:access`:
|
||
|
||
| Resource | read | write |
|
||
|---|---|---|
|
||
| `config` | settings, subnets, reservations, history, interfaces (the web UI shows the forms locked) | change them, undo, import |
|
||
| `leases` | leases and DHCP activity | delete a lease (making a reservation from one needs `config:write` too) |
|
||
| `audit` | the audit log | – |
|
||
| `*` | all of the above | |
|
||
|
||
**Roles** are ready-made sets of grants:
|
||
|
||
| Role | Grants |
|
||
|---|---|
|
||
| `viewer` | `config:read leases:read` |
|
||
| `operator` | `config:write leases:write audit:read` |
|
||
| `leases` | `leases:read`, e.g. for a monitoring script |
|
||
|
||
```sh
|
||
steward user add sam --role operator
|
||
steward user add monitor --no-password --role leases # tokens only
|
||
steward user update sam --grant config:read --grant leases:write
|
||
```
|
||
|
||
The last administrator can't be removed, demoted or disabled.
|
||
|
||
## API tokens
|
||
|
||
A token has its user's permissions, or fewer. A token made with `--role`
|
||
or `--grant` can do only that, even if its user can do more:
|
||
|
||
```sh
|
||
steward token create backup-script --role leases --expires 365d
|
||
```
|
||
|
||
The secret is shown once; only its hash is stored. A restricted token can
|
||
only create tokens with a subset of its own grants. The web UI only offers
|
||
roles within what your account may do; a token with more would get no
|
||
more than its user anyway.
|
||
|
||
**Rotating** gives a token a new secret, keeping its ID, name and
|
||
permissions, so only the programs that use it need updating:
|
||
|
||
```sh
|
||
steward token rotate 7 --grace 1h # the old secret works for another hour
|
||
steward token rotate --current --save # this CLI's own token
|
||
```
|
||
|
||
A token that expires gets its lifetime again, from now (`--expires 90d`
|
||
or `never` to change it). Without `--grace` the old secret stops at once:
|
||
use that when it may have leaked. Using an old secret during its grace
|
||
period is logged, naming the token and the address, so you can find the
|
||
programs still to update. A restricted token may rotate itself and tokens
|
||
no wider than itself. `steward token list`
|
||
shows when each token was last used, and from where. `steward token revoke
|
||
ID` stops one at once.
|
||
|
||
## The local socket
|
||
|
||
On the server, `/run/steward/steward.sock` lets root and the `steward`
|
||
user act as administrator without a token. The audit log shows them by
|
||
their system user name. Both can already read the database, so this adds
|
||
convenience, not power. Anyone else on the socket needs a token.
|
||
|
||
## The audit log
|
||
|
||
Logins (and failed ones), users, tokens, every configuration change (with
|
||
its history entry), lease deletions and imports are recorded with who, from
|
||
where and how: `session`, `token` or `socket`.
|