# 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.