docs: add autonomous server installation guide

2026-08-05 10:22:02 +02:00
parent df21046472
commit a707fb442c
7 changed files with 1056 additions and 53 deletions
@@ -0,0 +1,132 @@
+# Put ThothII behind Nginx
+
+This example assumes Nginx runs on the Linux host, ThothII `frontend` listens only on
+`127.0.0.1:8080`, and a separate authentication gateway validates the user's real login/session.
+Replace the documentation domain, certificate paths, and auth-gateway address.
+
+## Trust boundary
+
+Nginx is the only public listener. It terminates TLS, performs an `auth_request`, and proxies only
+to `frontend`; frontend then uses its private same-origin `/api` route to reach `core`. Never proxy
+the public listener directly to core port 8787.
+
+The authentication gateway must return 2xx only after validating a real credential or session. It
+returns normalized `X-Thoth-Principal-*` and `X-Thoth-Is-Admin` response headers. Nginx clears all
+client-supplied public and private-hop identity headers and copies only those successful auth
+response values into `X-Thoth-Trusted-*` on the private hop to frontend.
+Forwarding identity headers alone does not authenticate a user.
+
+Do not substitute a static header, network allowlist, or client-provided header for the
+authentication gateway. The admin value must come from reviewed identity-provider authorization,
+not from a username supplied by the browser.
+
+## Example configuration
+
+Install an Nginx build that includes `ngx_http_auth_request_module`. Save a reviewed version of
+this server block under the host's Nginx configuration directory:
+
+```nginx
+server {
+    listen 80;
+    server_name thoth.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    server_name thoth.example.com;
+
+    ssl_certificate /etc/nginx/tls/thoth/fullchain.pem;
+    ssl_certificate_key /etc/nginx/tls/thoth/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    location = /_authenticate {
+        internal;
+        proxy_pass http://auth-gateway:4180/verify;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header X-Original-URI $request_uri;
+        proxy_set_header X-Original-Method $request_method;
+
+        # The auth service derives identity from the real login/session, never these headers.
+        proxy_set_header X-Authenticated-User "";
+        proxy_set_header X-Thoth-Principal-Issuer "";
+        proxy_set_header X-Thoth-Principal-Subject "";
+        proxy_set_header X-Thoth-Principal-Display-Name "";
+        proxy_set_header X-Thoth-Is-Admin "";
+        proxy_set_header X-Thoth-Trusted-Principal-Issuer "";
+        proxy_set_header X-Thoth-Trusted-Principal-Subject "";
+        proxy_set_header X-Thoth-Trusted-Principal-Display-Name "";
+        proxy_set_header X-Thoth-Trusted-Is-Admin "";
+    }
+
+    location / {
+        auth_request /_authenticate;
+        auth_request_set $thoth_principal_issuer
+            $upstream_http_x_thoth_principal_issuer;
+        auth_request_set $thoth_principal_subject
+            $upstream_http_x_thoth_principal_subject;
+        auth_request_set $thoth_principal_display_name
+            $upstream_http_x_thoth_principal_display_name;
+        auth_request_set $thoth_is_admin
+            $upstream_http_x_thoth_is_admin;
+
+        # Discard browser claims. Carry only successful auth-subrequest values to frontend.
+        proxy_set_header X-Authenticated-User "";
+        proxy_set_header X-Thoth-Principal-Issuer "";
+        proxy_set_header X-Thoth-Principal-Subject "";
+        proxy_set_header X-Thoth-Principal-Display-Name "";
+        proxy_set_header X-Thoth-Is-Admin "";
+        proxy_set_header X-Thoth-Trusted-Principal-Issuer $thoth_principal_issuer;
+        proxy_set_header X-Thoth-Trusted-Principal-Subject $thoth_principal_subject;
+        proxy_set_header X-Thoth-Trusted-Principal-Display-Name $thoth_principal_display_name;
+        proxy_set_header X-Thoth-Trusted-Is-Admin $thoth_is_admin;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header Connection "";
+        proxy_pass http://127.0.0.1:8080;
+        proxy_http_version 1.1;
+
+        # SSE must reach the browser without response buffering or cache delay.
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 3600s;
+        add_header X-Accel-Buffering no always;
+    }
+}
+```
+
+Keep the certificate private key outside the ThothII tree. Do not log cookies, authorization
+headers, auth response bodies, or trusted identity headers.
+
+## Validate and reload
+
+First keep the public firewall rule closed. Confirm ThothII responds only on loopback, validate the
+full Nginx configuration, then reload without stopping existing connections:
+
+```sh
+curl --fail http://127.0.0.1:8080/health
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+If `nginx -t` reports that `auth_request` is unknown, install the distribution package/module that
+provides it. Do not remove authentication to make the syntax check pass.
+
+## Test authentication and SSE
+
+Open the firewall only after all of these pass:
+
+1. An unauthenticated HTTPS request is redirected to login or returns 401/403.
+2. Supplying forged `X-Thoth-Principal-*`, `X-Thoth-Is-Admin`, or `X-Thoth-Trusted-*` request
+   headers does not grant access.
+3. A real authenticated non-admin can use the application but cannot open Pi Management.
+4. A real authenticated admin can use Pi Management.
+5. A browser session receives live model updates for longer than the default proxy timeout without
+   batching; a protected `curl --no-buffer` test using a real short-lived login cookie is also
+   acceptable. Delete the cookie jar immediately afterward.
+
+Re-run these checks after changing the identity provider, auth gateway, Nginx, or ThothII release.