diff options
Diffstat (limited to 'docs/access.md')
| -rw-r--r-- | docs/access.md | 32 |
1 files changed, 32 insertions, 0 deletions
diff --git a/docs/access.md b/docs/access.md index db86e21..e8c5455 100644 --- a/docs/access.md +++ b/docs/access.md @@ -73,6 +73,38 @@ A user the node lets in but the registry doesn't have may do nothing (`403`). whole swarm (its members, its remakes, its users), so it is given apart, never by accident with the data. A user who may do both has both. +## Tokens + +A user logs in on any node, by what that node checks (its `--htpasswd`, or a proxy's +`--user-header`), and gets a token every node of the swarm takes, sent as +`Authorization: Bearer <token>` instead of a password: + +```sh +curl -u alice -X POST http://localhost:3000/auth/login # {"token": "ct1.…", …} +curl -H "Authorization: Bearer ct1.…" http://other-node:3000/store +``` + +* **Who signs it**: the node it logged in on, with its node key. Every node takes a + token signed by a member of the swarm (the member list gives the keys: a node ID is + its key), and none signed by another or since forgotten. +* **What it says**: who, how it proved it, when it ends, and optionally less than the + user may do (`limit`, capabilities as `POST /admin/users/{name}` takes them): never + what the user may do. Every node judges a request by the registry it holds then, so + a capability granted or revoked counts on a node as soon as the change reaches it. +* **How long**: `--token-lifetime` (12 hours), refreshed (`POST /auth/refresh`, on any + node, which signs the new one) until `--session-lifetime` (7 days) after the login; + then the user logs in again. A refreshed token may say less (`limit`), never more. +* **Revoking**: a user disabled or removed is refused at once; all of a user's tokens, + by the user (`POST /auth/logout`) or by one who may manage users (`DELETE + /admin/users/{name}/tokens`), which sets `tokensNotBefore` in its entry: tokens issued + before aren't taken any more. A token of a node forgotten by the swarm isn't taken + either. In a swarm without a registry, a token is taken until it expires. +* **What it means to trust**: any member could sign a token for any user, as it could + write anything as anyone ([`trust.md`](trust.md)). A token is a bearer's: whoever holds it is + the user until it ends, so it goes over TLS only, as passwords do. + +`GET /auth/whoami` says who a request's user is, how it proved it, and what it may do. + ## Managing users Through `/admin/users` ([`openapi.yaml`](openapi.yaml), Users): looking needs `read` on |