Skip to content

feat(server)!: sign in through a trusted reverse proxy - #1574

Merged
kvlonge merged 11 commits into
mainfrom
feat/trusted-proxy-sign-in
Nov 18, 2026
Merged

kvlonge merged 11 commits into
mainfrom
feat/trusted-proxy-sign-in

Conversation

@kvlonge

@kvlonge kvlonge commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Why

Teams with a stock reverse proxy and its own login in front of internal tools want sqb server to trust the username the proxy sends, without setting up OIDC or listing every person in advance.

Changes

  • [trusted_proxy] gains username_header (default X-SQB-User), optional display_name_header and email_header, unknown_users (provision_viewer, the default, or reject), proxy_logout_url and allowed_hosts. Identities become optional pre-bindings.
  • A newcomer is provisioned as a viewer under their canonical username. A username that matches another principal's name in any case is refused, never taken over.
  • trusted_peers defaults to 127.0.0.1 and ::1. A peer outside it that sends the username header is ignored and logged once, without header values.
  • Breaking: a request from a trusted peer, reads included, is served only when its real Host is a loopback name, the origin's host or a name in allowed_hosts. This closes DNS rebinding; X-Forwarded-Host never counts. A refused Host gets 403, logged once. A proxy that keeps the browser's host name or reaches the server by another name must list it in allowed_hosts.
  • Writes from trusted peers need X-SQB-CSRF (the UI always sends it) or the configured Origin. Password and OIDC checks are unchanged.
  • The UI shows the proxy's display name and sign-out link. Change feeds skip proxy buffering.
  • Authorization modules move into roles, decisions and people.
  • Server docs cover proxy setup, headers and access removal.

Verification

  • Orchestration lib tests on SQLite and PostgreSQL, including a peer-trust table and Host checks for rebound reads and writes, loopback and IPv6 hosts, forged X-Forwarded-Host and allowed_hosts.
  • CLI test_proxy: a non-loopback peer's username header and a refused Host are each logged once.
  • UI vitest (581) and make check-ci passed on the final head.
  • No DuckShop edge case: sign-in is not a project shape, data value or model lifecycle.

[trusted_proxy] gains username_header (default X-SQB-User), optional
display_name_header and email_header, unknown_users (provision_viewer,
the default, or reject) and proxy_logout_url; identities become optional
pre-bindings. The origin may be plain HTTP, with a start-up warning.

A newcomer gets a principal named by the canonical username, with an id
derived from it, and the installation-wide viewer role; a username that
already names another principal is refused rather than taken over.
Requests from trusted peers may report the browser host in
X-Forwarded-Host, as Apache's mod_proxy does without ProxyPreserveHost.
Each untrusted peer that sends the username header is logged once,
without header values. Change feeds send Cache-Control: no-cache,
no-transform and X-Accel-Buffering: no.
… by default, case-insensitive name check

- A request from a trusted peer may use any host name the proxy serves;
  a write needs the X-SQB-CSRF header, which the UI now always sends,
  or the configured Origin. The server still allows no cross-origin
  requests, so a cross-site page cannot send the header. Password, OIDC
  and untrusted-peer requests keep the exact Host and Origin checks.
- trusted_peers defaults to 127.0.0.1 and ::1 when unset.
- A newcomer whose username matches another principal's name in any
  case is refused rather than provisioned, without a schema change.
- Proxy-Authorization, Via, X-Forwarded-Proto, X-Real-IP and any Sec-
  header are reserved identity-header names.
… by default

Drive the sign-in routes in process with a chosen socket peer, so the
default `trusted_peers` is checked against real non-loopback IPv4, IPv6
and IPv4-mapped peers, against forwarding headers that claim loopback,
and against a server without `[trusted_proxy]`. State in the server docs
that the default lets any process on the host assert an identity, and
that listing the proxy's own address narrows it.
The trusted-proxy resolver made `authorization/main` hold 21 modules, one
over the container limit. Group them one level deep, as `credentials/main`
already is: `roles` for role definitions, assignments and administrator
grants; `decisions` for per-person, scope and row decisions and the
security audit; `people` for the first administrator, proxy usernames and
each person's access. Only module paths change.
…nd ignored

Start the server on this machine's routed address with the default
trusted peers and send the username header to it, with a forwarding
header claiming loopback. The server refuses both requests, logs the
peer once and never logs the username. Drop history wording from the
server page.
A DNS-rebinding page in a browser on a trusted-peer host reaches the
server under its own host name, and could then send the username and
CSRF headers. Refuse every request from a trusted peer, reads included,
unless its real Host is 127.0.0.1, localhost or [::1] with any port,
the host of `origin`, or a name in the new `allowed_hosts` list, which
only a proxy that keeps the browser's host name needs. X-Forwarded-Host
never counts. A refused Host gets 403 and is logged once with the
setting that allows it. The CSRF rule and the loopback trusted_peers
default are unchanged.
…lowed_hosts

A stock proxy on another host forwards with its backend address as Host,
which is not a loopback name, so it needs allowed_hosts too. Say so in
the docs and in the refused-Host warning.
@kvlonge
kvlonge marked this pull request as ready for review November 18, 2026 13:23
@kvlonge
kvlonge enabled auto-merge November 18, 2026 13:23
@kvlonge
kvlonge added this pull request to the merge queue Nov 18, 2026
Merged via the queue into main with commit 7e09416 Nov 18, 2026
63 of 91 checks passed
@kvlonge
kvlonge deleted the feat/trusted-proxy-sign-in branch November 18, 2026 14:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant