36 lines
4.2 KiB
Markdown
36 lines
4.2 KiB
Markdown
# Administration authentication and API access
|
||
|
||
## Default exposure and setup
|
||
|
||
The administration listener uses **HTTP loopback (`127.0.0.1:9090`) by default** and is separate from normal Vhost listeners. No administrator password is bundled. Use the local CLI `admin setup-token` or `admin init` to complete first-time setup. For access from another workstation, prefer an SSH tunnel; for direct remote operation, enable **administration HTTPS**, configure a trusted certificate and narrow network access before binding outside loopback.
|
||
|
||
## Session security
|
||
|
||
Administrator sessions use an HttpOnly, SameSite=Strict cookie, with Secure on HTTPS. Expiry is bounded by the configured absolute lifetime (7–30 days, default 30). Logout, password changes and revoke-all terminate sessions. API mutations are validated for Host/Origin, CSRF token and request marker; a cookie copied into automation is not an approved general-purpose API token.
|
||
|
||
Unauthenticated endpoints intentionally expose only minimal setup/sign-in and health behavior. Configuration, operational status, dashboard assets, file logs, the API specification and the documentation Reader require authentication. Admin responses use no-store and security headers, and the browser does not expose the full application state before sign-in.
|
||
|
||
## `/docs` Reader and Swagger
|
||
|
||
The authenticated documentation page has two tabs: **Reader**, embedding the registered Markdown guides at compile time, and **API**, displaying the bundled OpenAPI schema. Both are local assets; no runtime CDN access is required for viewing the reference. A document edit affects the shipped reader **only after rebuilding** RustProxy.
|
||
|
||
Swagger uses the current signed-in session, not a new broad credential. It requires explicit confirmation for write operations. Treat the OpenAPI schema as a request guide and RustProxy's field/authorization validation as the final authority.
|
||
|
||
## Publishing the panel behind a reverse proxy
|
||
|
||
This is a **special-risk topology**, not the default. Configure a fixed HTTPS public origin/allowed hostname and a trusted forwarding boundary. RustProxy has an explicit narrowly constrained local-listener exception, but a normal public Vhost must not pass administration cookies to an ordinary upstream. Forwarded Host/Proto values are trusted only when the direct peer satisfies the configured trust rules. Test CSRF/Origin validation and cookie security after a topology change.
|
||
|
||
## General administration API tokens (0.34.1 DEV)
|
||
|
||
Settings → **Security → API tokens (RO/RW)** generates a one-time-displayed opaque Bearer credential, with `ro` (read) or `rw` (read/write) permission and a **mandatory allowlist of client IPs or CIDRs**. The token is stored only as a hash; save it securely at creation or generate a replacement. Deleting a token revokes it immediately. The existing browser session workflow is unchanged; this is not a browser login/password substitute.
|
||
|
||
Send `Authorization: Bearer <token>` to the administration listener over HTTPS outside loopback. IP checks use the transport peer, not spoofable forwarded headers. Only the narrowly allowlisted `/api/*` resource routes are usable: RO is read-only, RW adds selected configuration and operational operations. Tokens cannot access authentication, backups, documentation, other token creation/revocation, certificate API management, or unrestricted administrator endpoints. The separate certificate-only API credentials work independently. The **Settings → Administration** page includes a direct link to token management.
|
||
|
||
## Certificate-only credentials
|
||
|
||
Certificate API Key ID + Bearer credentials are limited by certificate ID and by allowed action (reload by default; deploy opt-in). They do not grant login or administrative configuration access. Revocation/rotation are administrator-only actions. Keep tokens out of logs and pass them over HTTPS outside loopback.
|
||
|
||
## Offline build assets
|
||
|
||
Swagger JavaScript/stylesheets are prepared by the build and embedded behind authentication. If compilation fails during Swagger asset preparation, inspect `build.rs` and `scripts/build/swagger_assets.py` and ensure the required checked/downloaded asset inputs are available. Do not replace these authenticated assets with an unaudited public CDN workaround.
|