diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/access.md | 8 | ||||
| -rw-r--r-- | docs/dashboard.md | 10 | ||||
| -rw-r--r-- | docs/openapi.yaml | 50 |
3 files changed, 66 insertions, 2 deletions
diff --git a/docs/access.md b/docs/access.md index 83c39f9..cc35565 100644 --- a/docs/access.md +++ b/docs/access.md @@ -125,6 +125,14 @@ the signature must be by one of the user's keys, as the registry the node holds says, and the user enabled (`401` if not, saying why). A swarm without a registry has no keys (`409`). +A browser keeps a token as its session: `POST /auth/session`, with a token, answers as +`/auth/refresh` does and sets a cookie holding the new one (`HttpOnly`, +`SameSite=Strict`: no script reads it, no other site's page sends it), which lets in +requests without `Authorization`; `DELETE /auth/session` forgets it. The login page +(`/login`, without authentication, with the dashboard) begins one by password or from a +token pasted, from a login by key, say; the dashboard renews it while open +([`dashboard.md`](dashboard.md)). + `GET /auth/whoami` says who a request's user is, how it proved it, and what it may do. Pages of other origins, the dashboards of other members, may call a node with a token: diff --git a/docs/dashboard.md b/docs/dashboard.md index 05069d1..df2d4f9 100644 --- a/docs/dashboard.md +++ b/docs/dashboard.md @@ -14,8 +14,14 @@ cargo build --release --features mycelium,dashboard ``` It is at `/admin/dashboard` on the node's HTTP API, by default -`http://127.0.0.1:3000/admin/dashboard`, and asks for a user from `--htpasswd` (or one -a reverse proxy names, `--user-header`), as the rest of the API does. The API listens on localhost unless `--bind-addr` says otherwise; +`http://127.0.0.1:3000/admin/dashboard`, for a user a reverse proxy names +(`--user-header`) or one logged in on the page `/login`, which a browser opening the +dashboard without one is sent to. There, a user logs in with its password +(`--htpasswd`), or with a token: from `continuum-signed login` (by key, +[`access.md`](access.md), Tokens), or any other. The page keeps a session for the +browser, a cookie no script reads and no other site's page sends, renewed while the +dashboard is open; it ends with the token's lifetime, or with "Log out of this +browser". The API listens on localhost unless `--bind-addr` says otherwise; to look at a node on another machine, forward the port (`ssh -L 3000:localhost:3000 <machine>`) or put a TLS proxy in front ([`operations.md`](operations.md), Behind a reverse proxy). diff --git a/docs/openapi.yaml b/docs/openapi.yaml index ab14710..bb1d34b 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -895,6 +895,56 @@ paths: '409': { description: No user registry, which holds the keys. } '503': { description: Not ready yet. } + /auth/session: + post: + tags: [Auth] + summary: Keep a token as the browser's session + description: | + As `POST /auth/refresh`, and the new token set as the session cookie + (`continuum-token`, `HttpOnly`, `SameSite=Strict`, for as long as the token is + valid): requests without `Authorization` that bring it are its user's. + security: + - bearer: [] + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/Limit' + responses: + '200': + description: The token, also set as the cookie. + content: + application/json: + schema: { $ref: '#/components/schemas/TokenAnswer' } + '400': { description: No token, or a limit that isn't one or says more than the token's. } + '401': { description: 'The token isn''t taken, or its login ended.' } + '503': { description: Not ready yet. } + delete: + tags: [Auth] + summary: Forget the browser's session + description: The session cookie cleared. The token stays valid until it expires (`POST /auth/logout` ends them all). + responses: + '204': { description: Forgotten. } + '401': + $ref: '#/components/responses/Unauthorized' + + /login: + get: + tags: [Auth] + summary: The page to log in on + description: | + With the dashboard: a page to log in on by password or with a token, without + authentication. It keeps a session (`POST /auth/session`) and opens + `/admin/dashboard`, where a browser without a user is sent (`303`). + security: [] + responses: + '200': + description: The page. + content: + text/html: {} + '404': { description: A build without the dashboard. } + /auth/refresh: post: tags: [Auth] |