plexsphere

Appearance

Run behind a reverse proxy ​

When a TLS-terminating proxy speaks plain HTTP to the API, the session cookie is only issued Secure if the binary trusts the proxy's forwarded scheme. This is configuration, not a plexctl operation.

Prerequisites ​

  • A reverse proxy (NGINX, Envoy, Traefik) terminating TLS in front of the API.
  • The proxy able to set X-Forwarded-Proto: https on every forwarded request.

Steps ​

Enable proxy-header trust on the deployment:

shell
export PLEXSPHERE_AUTH_TRUST_PROXY_HEADERS=true

Pin the forwarded scheme on the proxy — for NGINX:

nginx
proxy_set_header X-Forwarded-Proto $scheme;

The binary then issues the session cookie with Secure, scoped to Path=/v1/ with SameSite=Strict. Serve the SPA from the same public origin so the SameSite=Strict cookie is attached. For local HTTP development, leave PLEXSPHERE_AUTH_TRUST_PROXY_HEADERS unset.

Verification ​

shell
curl -sI https://plexsphere.example/v1/auth/whoami | grep -i set-cookie
# Set-Cookie: … Path=/v1/; Secure; HttpOnly; SameSite=Strict

The cookie must carry Secure and SameSite=Strict.

See also ​