abrown38andClaude Opus 5.5
7b3f0f764c
tls.acme names the certificate and jarl: the Jarl server and a token that may only write the challenge record. Steward gets the certificate with DNS-01 (lego), writing the record through Jarl's API into every view that has the zone, renews it with a third of its lifetime left and swaps it in without a restart. A check runs before every order: Jarl, the zone, the token's permission, a test record, the zone's name servers, public resolvers, clean-up; each step says what to fix. Staging by default. With a certificate, each listener serves HTTPS and plain HTTP on one port (redirecting plain HTTP, except from the server itself). steward cert / cert check / cert renew, Server -> Certificate in the web UI, GET /certificate, POST /certificate/check|renew. docs/certificates.md and docs/jarl.md (the Jarl user and the token's grant). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
76 lines
2.8 KiB
Markdown
76 lines
2.8 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 | – |
|
||
|
||
The certificate (`steward cert`, Server → Certificate) is for administrators only.
|
||
| `*` | 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`.
|