Skip to content

Site OAuth2

site-oauth2 runs OAuth2 Proxy on port 4180. The served prefix is <site-path>s/oauth2 (proxy_prefix in oauth2.cfg).

This application is the only one that exposes a Service port and owns the public route for the Site path. Browser traffic reaches it first; it forwards to site-proxy on 127.0.0.1:8080 after the browser session is established (the upstream is in the rendered alpha-oauth2.cfg). The liveness probe is HTTP GET /ping (initial delay 10 seconds, period 60 seconds).

The operator renders three files into the Site files ConfigMap:

  • oauth2.cfg: the redirect URL, trusted IPs, session settings, and the proxy prefix. The skip-auth route list depends on the Site type: a public Site skips OAuth2 for every path except /s/admin; a private Site skips it for the machine paths /s/api, /s/dav, /s/s3, /s/signed, /s/session, /s/healthz, /s/_m2m, and /s/metrics (only when metrics is enabled). The proxy still enforces its own authentication rules on those paths (site proxy).
  • alpha-oauth2.cfg: the HTTP server wiring (bindAddress 0.0.0.0:4180, upstream http://127.0.0.1:8080 with a 600-second timeout), the OpenID Connect (OIDC) provider definition (client credentials, scope, issuer URL, and explicit login, redeem, profile, and JSON Web Key Set (JWKS) endpoints when discovery is skipped), the request-header injection rules, and the claim mapping (06 — OAuth2 Proxy identity wiring).
  • oauth2-error.html: the branded sign-in/error page, mounted read-only over the page in the image.

oauth2.cfg also sets operational behaviour: skip_provider_button (single IdP, no chooser; the browser goes straight to the provider login page), silence_ping_logging (the /ping probe stays out of the logs), show_debug_on_error set to false (the error page never shows debug details, also when the platform-wide debug setting is on), and custom_templates_dir pointing at the image's oauth2/templates/ (sign_in.html and robots.txt), which keeps oauth2-proxy from logging about default templates. Because of skip_provider_button, the sign_in.html template is never rendered: the branded page users see is oauth2-error.html. The identity-provider email domain filter is ["*"]: any verified email passes the proxy, and Site access rules make the real decisions.

The OIDC endpoint rules and session cookie behaviour are defined in security design.

Use cases

  • Browser access to a private Site: a user logs in once, and the Hub and the Site then share the identity.
  • A public Site with a protected administration path: everything is anonymous except /s/admin.
  • Machine traffic that must not pass an interactive login: the skip-auth list keeps the token paths outside OAuth2, and the proxy authenticates them itself.

Example usage

A private Site redirects an unauthenticated browser request to the identity provider. A token request on a machine path answers directly:

curl -H "Authorization: Bearer ${SITE_TOKEN}" \
  "https://<domain>/<space>/<site>/s/api/v2/health/"

The Site type selects the skip-auth list: private (the default) keeps the machine paths token-only, and public skips OAuth2 for everything except /s/admin. The operator sets site.default_view_groups to the least-privilege group of the organisation (application settings).

Request flow

flowchart LR
    B["Browser"] --> O["site-oauth2 :4180"]
    O -- "no session" --> I["OIDC provider"]
    I -- "authorization code" --> O
    O --> P["site-proxy 127.0.0.1:8080"]
    C["Token client"] --> P