railiance-platform/helm/openbao-ui-overlay/README.md

OpenBao KeyCape login overlay

Streamlines the browser login mask reached through the named openbao-ui-railiance01 operator tunnel at http://127.0.0.1:18200 to a single Sign in with KeyCape action. Namespace, auth method, mount path, and role are preset in presets.json and hidden by overlay.css / overlay.js.

Mechanism (T01 decision)

OpenBao ships UI assets inside the container image. There is no supported API to customize the login form (/sys/config/ui only configures response headers).

We use an nginx UI gateway (openbao-ui-gateway) that:

1. Proxies all traffic to openbao.openbao.svc.cluster.local:8200.
2. Serves overlay assets from a ConfigMap at /ui/platform-overlay/.
3. Injects overlay.css and overlay.js into HTML responses via sub_filter.

Overlay assets live entirely in this directory. Upgrading OpenBao does not require hand-editing files inside the OpenBao pod.

Track upstream openbao/openbao#2936 for native custom CSS. When available, keep presets.json and branding assets and retire nginx sub_filter injection if the upstream API covers the same behaviour.

Layout

File	Purpose
VERSION	OpenBao image tag this overlay targets (openbao-values.yaml)
presets.json	Hidden login defaults (netkingdom, platform-admin, …)
overlay.css	Hide raw OpenBao login fields
overlay.js	Apply presets, branding on post-login Ember pages
login.html / login.js / login.css	Standalone KeyCape login at /ui/vault/auth
callback.html / callback.js	OIDC code exchange at /ui/vault/auth/*/oidc/callback
nginx.conf	Gateway proxy + standalone auth page + HTML injection
patches/<version>/manifest.sha256	Upstream UI fingerprints for drift detection

Deploy

From railiance-platform:

make openbao-overlay-apply   # overlay only
make openbao-deploy          # middleware + overlay + Helm upgrade
make openbao-verify-login-overlay

Reapply after an OpenBao upgrade

1. Bump server.image.tag in helm/openbao-values.yaml.

2. Deploy: make openbao-deploy.

3. Fetch live UI assets and compare hashes:

   curl -sS http://127.0.0.1:18200/ui/ -o /tmp/index.html
   # locate vault-*.js path in /tmp/index.html, then:
   curl -sS "http://127.0.0.1:18200/ui/assets/vault-....js" -o /tmp/vault.js
   sha256sum /tmp/index.html /tmp/vault.js
   

4. If hashes differ from patches/<old-version>/manifest.sha256, update overlay.css / overlay.js selectors against the new Ember templates.

5. Write patches/<new-version>/manifest.sha256, update VERSION.

6. Run make openbao-verify-login-overlay CHECK_UPSTREAM_DRIFT=1.

7. Attended browser login through KeyCape MFA. The OpenBao role and KeyCape client must both allow the exact loopback callback http://127.0.0.1:18200/ui/vault/auth/netkingdom/oidc/callback before the former public listener is retracted.

Workplan: helix-forge/workplans/HF-WP-0003-openbao-keycape-login-overlay.md