Skip to content

Brand the single sign-on proxy's error page (oauth2-proxy) #5056

Description

@devantler

🤖 Generated by the Agentic Engineer (interactive Claude Code session)

Part of #5053.

Problem

The single sign-on proxy (oauth2-proxy) shows its own page only when something goes wrong. That
happens when someone outside the maintainers team is turned away, a login expires or gets out of
step, or an app behind the proxy fails (502). That page is the stock oauth2-proxy page, with its
logo and version number. The normal sign-in page never appears, because the configuration skips
it (skip_provider_button = true), so the error page is the only one to brand.

What the deployed version supports

oauth2-proxy v7.15.5, Helm chart 10.7.1 (k8s/bases/infrastructure/controllers/oauth2-proxy/helm-release.yaml):

  • custom_templates_dir: a directory of replacement templates (sign_in.html, error.html).
    Upstream source at this version uses a file only when it exists. A missing file falls back to
    the built-in page and logs an error. A file that fails to parse returns an error while the
    templates load, which stops the proxy from starting.
  • The error template gets Title, Message, ProxyPrefix, StatusCode, Redirect, RequestID,
    Footer and Version, plus the template functions ToUpper and ToLower.
  • footer: custom footer HTML. It also stops the page showing the proxy's version.
  • The chart has no templates value, but extraVolumes and extraVolumeMounts can mount a ConfigMap.

Proposal

  1. Add error.html, based on upstream's own pkg/app/pagewriter/error.html at v7.15.5 so that the
    "sign in again" link and the request ID stay. Restyle it with the brand kit's values and an
    inline orb logo. The proxy serves no files of its own, so the styles and logo are inlined, and
    the brand kit's drift check covers them.
  2. Ship it as a ConfigMap, mount it read-only through extraVolumes and extraVolumeMounts, and
    set custom_templates_dir and footer in config.configFile.
  3. Leave sign_in.html alone; it is never shown.

Risk: high

Every app behind single sign-on depends on this proxy. The rolling update (two replicas,
maxUnavailable: 0) keeps the old pods serving while a broken new pod crash-loops, but that is a
last line of defence, not the plan. The template must be proven before it reaches production:

Acceptance criteria

  • An offline Go test parses and runs error.html with the same template functions and sample data for 403, 500 and 502. It runs in CI whenever the template changes, and a deliberately broken copy makes it fail.
  • Tried on the local cluster first (its default set includes the sign-on stack): open an error page, for example the callback path with no login in progress, and attach a screenshot.
  • After the production deploy, sign-in still works end to end on at least three fronted apps (the front page, a dashboard and the OpenBao UI), shown by opening each.
  • A screenshot of the production error page shows the brand, the status, the message and the request ID, with readable contrast (at least 4.5:1 for body text).
  • The page no longer shows the proxy's version.

This is permanent configuration, so it needs no feature flag. Rollback is removing
custom_templates_dir, which brings back the built-in page.

Size: M.

Activity

  1. moved this to 📥 Backlog in 🌊 Project Boardon Oct 18, 2026
  2. moved this from 📥 Backlog to 🏃🏻‍♂️ In Progress in 🌊 Project Boardon Nov 16, 2026
  3. moved this from 🏃🏻‍♂️ In Progress to ✅ Done in 🌊 Project Boardon Nov 16, 2026
  4. devantler commented on Nov 16, 2026

    @devantler
    ContributorAuthor

    Verified live after #6413 deployed (both oauth2-proxy pods rolled over at 12:11 UTC):

    • Startup: each pod logged only the two expected fallbacks (sign_in.html and robots.txt use the built-in templates) and OAuthProxy configured. Nothing was logged about error.html, so the custom template loaded. The Deployment carries the reloader entry for oauth2-proxy-templates.

    • Error page: https://oauth2-proxy.platform.devantler.tech/oauth2/callback returns the branded 500 page. It shows the wordmark, the status, the title, the message, the Go back / Sign in buttons and the request ID. It does not show the proxy's name or version. The body text is about 8:1 contrast.

    • Signed-in access, through the proxy with an existing session:

      • the front page (platform.devantler.tech) loads the dashboard;
      • the Hubble dashboard loads;
      • the OpenBao UI loads. It then asks to re-authenticate OpenBao's own token, which expired on 7 November and is separate from the proxy.

      A fresh login round trip through GitHub was not repeated, because that needs the maintainer's own GitHub sign-in. Nothing in the proxy's routes, cookies or provider configuration changed.

    🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Fields

    Priority

    None yet

    Start date

    None yet

    Target date

    None yet

    Effort

    None yet

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions