Skip to content
Veltrosecurity

SSO cutover — manual browser checklist

Source of truth: docs/sso-verification.md (synced at build time — edit the original, not this copy). ADR-003 update: Veltro is now the suite identity authority at the origin root. Throughout this checklist read the login as /login (Veltro, not /vectorflow/login) and identity settings as /veltro/.... VectorFlow and Sigmatic both delegate to Veltro; the browser flows are otherwise identical. Full e2e requires images that include the ADR-003 changes (bump versions.env).

Automated checks: scripts/verify-sso.sh (three-zone routing, credentials login, chunked cookie, single logout, raw-listener route isolation, authenticated direct ingest, sigmatic_* keys, SCIM). The direct check uses SIGMATIC_INGEST_URL, or the private http://${SIGMATIC_INGEST_BIND_ADDRESS:-127.0.0.1}:8001 listener by default. The methods below need a browser and, where marked, external IdP/authenticator config — they cannot run in CI.

All steps start from a clean private window at $PUBLIC_BASE_URL.

# Method Steps Expected Env-dependent?
1 Credentials + TOTP Log in at /vectorflow/login with a 2FA-enabled user; enter the TOTP code After TOTP, navigate to /sigmatic/ — Sigmatic dashboard loads with no Sigmatic login page No (enable TOTP on a test user in VF settings)
2 WebAuthn / passkey /vectorflow/login → “Sign in with passkey” Same: /sigmatic/ is authed immediately after the passkey ceremony Yes — needs a registered authenticator (platform or key)
3 OIDC (DB-configured) Configure a provider in VF Settings → SSO; log in via the IdP button Redirect chain ends at VF dashboard; /sigmatic/ authed; Sigmatic role reflects suite_role from org/team roles Yes — needs a reachable OIDC IdP (Okta/Entra/Keycloak)
4 SAML Same via VF’s SAML flow (mints the session cookie in saml.ts — Task 5 stamps suite_role there too) /sigmatic/ authed; check suite_role present via /sigmatic/api/auth/me Yes — needs a SAML IdP
5 Logout from Sigmatic UI While authed, click Logout inside /sigmatic/ Lands on the suite root (/ → launcher); clicking VectorFlow → VF /vectorflow/login; /sigmatic/api/auth/me now 401 No
6 Logout from VF UI Log in again, log out from VF’s user menu Same — /sigmatic/api/auth/me returns 401 No
7 WebSocket Open a Sigmatic page with live updates (alerts) Browser hits /sigmatic/ws; the suite gateway mints X-Veltro-Request-Assertion, strips the shared cookie, and Sigmatic accepts the upgrade. The suite-origin path — assertion gate, rewrite-once to /ws/alerts, cookie stripping, Upgrade/Connection headers, and fail-closed refusal — was covered by the chad-ws-proof CI job (veltro#459/#718) through the real nginx/veltro.conf listener until e2e was retired from CI on 2026-09-23; scripts/verify-sigmatic-ws.sh with compose/ws-proof.yml still runs it by hand; only the browser-visible live alert content (2FA user, seeded stream) remains a manual spot-check No

Chrome parity spot-check

Section titled “Chrome parity spot-check”

On adjacent tabs (/vectorflow vs /sigmatic/), confirm the two apps read as one:

  • Expanded rail 224px, collapsed 56px (inspect computed width) in both.
  • 52px header; identical nav-row density and active style (2px green left border + soft fill + semibold).
  • Footer: version + green “All systems normal” + a Collapse row; ⌘B collapses in both.
  • ⌘K search-button widths match.
  • Change the theme in one app → after reload the other reflects it (shared theme localStorage key).
  • Sidebar AppSwitcher lists VectorFlow + Sigmatic in both; switching keeps the session (no second login).

Direct-ingest verification contract

Section titled “Direct-ingest verification contract”

The raw listener is a separate trust boundary from nginx UI/control-plane ingress. When running scripts/verify-sso.sh against a stack with Sigmatic installed, first require /api/auth/me on the raw listener to return 404, proving a representative control-plane route is absent, then POST a fixture to /api/logs/<suffix> with the per-Data Source bearer and require 200. The listener is supported only over a trusted LAN or encrypted tunnel; public traffic must terminate TLS in a deployer-owned reverse proxy while raw :8001 remains private.

Status

Section titled “Status”

Verified 2026-07-03. The then-current full profile brought up on colima (docker 29.2.1), pinned images vectorflow-server-suite:0.2.6 + chad/chad-{backend,frontend}:0.18.0. The VF suite image is published linux/amd64-only, so the stack runs under amd64 emulation (Rosetta) on Apple Silicon.

Automated — scripts/verify-sso.sh: 7/7 cutover-critical checks PASS

Section titled “Automated — scripts/verify-sso.sh: 7/7 cutover-critical checks PASS”
  • GET / → 302 /vectorflow/launcher; /vectorflow/launcher → 200; /chad/ → 200 (three-zone routing)
  • VF credentials login mints authjs.session-token; /chad/api/auth/me authed as the VF user
  • suite_role admin mapped to CHAD role admin
  • chunked authjs.session-token.0/.1 accepted
  • VF signout → /chad/api/auth/me 401 (single logout)

Machine auth (historical 2026-07-03 run)

Section titled “Machine auth (historical 2026-07-03 run)”
  • SCIM ServiceProviderConfig → 200 with a minted 64-hex bearer (enable + POST /api/scim/token). PASS.
  • Raw :8001 ingest — not exercised in this historical run. The suite compose omitted OpenSearch, so no Data Source/token existed. Current release verification separately requires a 404 for /api/auth/me on the raw listener and a 200 authenticated ingest when the seeded credentials are present.
  • chad_* API key (/chad/api/rules) — the GET path is untouched by the cutover; headless key minting is blocked by CHAD’s HttpOnly CSRF cookie (double-submit requires the CHAD UI), so it was not scripted in this run. Sigmatic API keys were removed later (veltro#1151). The smoke now mints a Veltro personal access token instead and checks it’s accepted on /sigmatic/api/rules and refused once revoked.

Browser checklist (no external IdP)

Section titled “Browser checklist (no external IdP)”
  • First-admin setup wizard completed; credentials login lands authed on the dashboard.
  • Logout (#5/#6): covered by the single-logout check above.
  • Theme sync: toggling VF’s theme writes the shared theme localStorage key.
  • Header height 52px confirmed.
  • Rail widths (224/56) + AppSwitcher: not measured — the capture surface is 626 CSS px, below VF’s 768px rail breakpoint (tooling constraint).
  • TOTP (#1), passkey (#2), OIDC/SAML (#3/#4): still pending a 2FA-enrolled user / reachable IdP. WebSocket (#7): the suite-origin upgrade through nginx is proved by scripts/verify-sigmatic-ws.sh (veltro#459), run by hand since the CI job was retired on 2026-09-23. The browser live-alert content spot-check is manual too.