Repository navigation
Description
🤖 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,
FooterandVersion, plus the template functionsToUpperandToLower. footer: custom footer HTML. It also stops the page showing the proxy's version.- The chart has no templates value, but
extraVolumesandextraVolumeMountscan mount a ConfigMap.
Proposal
- Add
error.html, based on upstream's ownpkg/app/pagewriter/error.htmlat 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. - Ship it as a ConfigMap, mount it read-only through
extraVolumesandextraVolumeMounts, and
setcustom_templates_dirandfooterinconfig.configFile. - Leave
sign_in.htmlalone; 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.htmlwith 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.
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Start date
Target date
Effort
Projects
- StatusShow more project fields✅ Done
Activity
devantler commentedon Nov 16, 2026
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.htmlandrobots.txtuse the built-in templates) andOAuthProxy configured. Nothing was logged abouterror.html, so the custom template loaded. The Deployment carries the reloader entry foroauth2-proxy-templates.Error page:
https://oauth2-proxy.platform.devantler.tech/oauth2/callbackreturns 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:
platform.devantler.tech) loads the dashboard;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