fix(deploy): enable uvicorn --proxy-headers so OIDC works behind reverse proxies

Without ``--proxy-headers``, uvicorn ignores the X-Forwarded-Proto
header set by an upstream reverse proxy (AWS ALB, Nginx, Cloudflare,
…) and ``request.url.scheme`` inside the container reads "http" even
when the user hit "https". Every scheme-aware code path then silently
builds wrong URLs — most visibly the OIDC redirect_uri, which fails
to match what's registered with the IdP. Entra returns AADSTS50011;
Google / Okta / Auth0 surface equivalents. Login is dead on arrival.

The fix is a one-line addition to the production CMD in Dockerfile.
``--forwarded-allow-ips=*`` is safe behind ECS+ALB (and any equivalent
shape) because the network controls ensure only the proxy can reach
:8080 and the proxy strips client-supplied X-Forwarded-* before
forwarding.

Caught while planning the UIC production rollout of PR2 (#129) before
any wrong URI ever reached Entra.

Also adds a "Behind a reverse proxy" section to the SSO how-to so
other OSS operators don't rediscover this. The fix is now baked into
the shipped Dockerfile, but operators who replace the CMD need to
keep the flag.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bbertucc

Dockerfile

@@ -95,5 +95,16 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
 # Expose API port
 EXPOSE 8080
 
-# Production command (no reload for stability)
-CMD ["uv", "run", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "1"]
+# Production command (no reload for stability).
+#
+# --proxy-headers + --forwarded-allow-ips=* tells uvicorn to honour the
+# X-Forwarded-Proto / X-Forwarded-For headers set by an upstream reverse
+# proxy (ALB, Nginx, Cloudflare). Without this, request.url.scheme inside
+# the container reads "http" even when the user hit "https", so any
+# scheme-aware code path silently builds wrong URLs — most visibly the
+# OIDC redirect_uri, which then mismatches what's registered with the IdP
+# and login fails with AADSTS50011 (or the equivalent on Google/Okta/...).
+# The "*" allowlist is safe behind ECS+ALB because the security group
+# restricts ingress on :8080 to the ALB only, and the ALB strips any
+# client-supplied X-Forwarded-* before forwarding.
+CMD ["uv", "run", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "1", "--proxy-headers", "--forwarded-allow-ips=*"]

docs/how-to/configure-sso.md

@@ -126,6 +126,20 @@ AUTH_OIDC_PROVIDERS=[
 ]
 ```
 
+## Behind a reverse proxy (ALB, Nginx, Cloudflare)
+
+OIDC redirect URIs are **scheme-sensitive** — Entra (and all other IdPs) reject the round-trip if the `redirect_uri` we send doesn't match what's registered byte-for-byte. When the app sits behind a reverse proxy that terminates HTTPS, the container itself sees only HTTP, and naive `request.url.scheme` reads return `"http"` — building an `http://...` redirect URI for a service the user actually reached over `https://...`. Login fails with `AADSTS50011` on Entra, equivalent codes elsewhere.
+
+The shipped Dockerfile already addresses this: the production CMD includes `--proxy-headers --forwarded-allow-ips=*`, which tells uvicorn to read `X-Forwarded-Proto` and reflect it back into `request.url.scheme`.
+
+What you must verify in your deployment:
+
+- **Your reverse proxy sets `X-Forwarded-Proto`.** AWS ALB, GCP Cloud Load Balancer, Azure App Gateway, and Cloudflare all do this by default. Nginx needs an explicit `proxy_set_header X-Forwarded-Proto $scheme;`.
+- **The container is reachable only via the proxy.** Otherwise a direct caller could spoof `X-Forwarded-Proto: https` and trick the app into building wrong URIs. ECS security groups, Nginx upstream configs, and equivalent network controls handle this.
+- **You're not running uvicorn with custom flags that drop `--proxy-headers`.** If you've replaced the Dockerfile CMD, keep the flag.
+
+If a working local OIDC round-trip suddenly fails the moment you put the app behind a proxy, this is almost certainly the cause. Confirm by checking the kickoff redirect URL — `redirect_uri=https%3A%2F%2F…` is correct; `redirect_uri=http%3A%2F%2F…` against an HTTPS-fronted host means proxy headers aren't being honoured.
+
 ## Common pitfalls
 
 - **AADSTS50011: redirect URI does not match.** The URI registered with Entra must match the request's host + scheme + path *exactly*. If your deployment is behind an ALB that terminates HTTPS, register `https://...` even though the FastAPI process internally sees HTTP. Confirm the ALB sets `X-Forwarded-Proto: https` and that Starlette is reading it (otherwise our `_redirect_uri_for` builds the wrong URL).