Self-hosted Breeze behind Cloudflare Access: optional JWT trust on /auth/login to dedupe double-login

[bdunncompany]

Self-hosted Breeze behind Cloudflare Access — login dedup proposal

Context (verified 2026-05-14)

Breeze ships a working OIDC SSO implementation (apps/api/src/services/sso.ts:418 defines PROVIDER_PRESETS including the Google preset; SAML presets at :817; OIDC callback + Breeze-session mint in apps/api/src/routes/sso.ts). User auth on every other request is the Breeze JWT verified in apps/api/src/middleware/auth.ts:290 (authMiddleware). Agent connections are a separate path entirely — apps/api/src/middleware/agentAuth.ts:160 validates brz_* tokens against devices.agentTokenHash. Mobile hits the same /auth/login endpoint at apps/mobile/src/services/api.ts:315.

Inbound Cloudflare Access JWT trust is not implemented. grep -rE 'Cf-Access-Jwt-Assertion|cloudflare-access|cf_access' apps/api/src/ returns zero hits. The only CF-Access-* references are outbound in apps/api/src/services/msiSigning.ts:94-95 (calling an MSI signing service that's itself behind CF Access — inverse direction).

The friction

Self-hosters who put Breeze behind Cloudflare Access today end up with a double login when CF Access uses the same IdP Breeze is configured with: user authenticates to their IdP at the CF Access edge, then hits Breeze's login form and authenticates to the same IdP again. Same identity, two cookies, two MFA prompts.

Proposal: opt-in CF Access JWT short-circuit on POST /api/v1/auth/login

A small, gated middleware that activates only when the self-hoster explicitly turns it on.

1. Env-flagged: CF_ACCESS_TRUST_ENABLED=true, CF_ACCESS_TEAM_DOMAIN=<team>.cloudflareaccess.com, CF_ACCESS_AUD=<application-aud>. Hosted SaaS never sets these; validator gates on the same IS_HOSTED pattern already used in the API config.
2. Scope: middleware mounts on POST /api/v1/auth/login only. Every other endpoint still requires a Breeze JWT from authMiddleware. CF Access keeps doing edge gating on UI paths; /api/v1/* and the agent WS continue to bypass CF Access at the edge as is already the deployed shape on a real install I tested against (UI paths 302 to <team>.cloudflareaccess.com; API + health + agent-WS return Hono status codes directly).
3. JWT verification: fetch JWKS from https://<team>.cloudflareaccess.com/cdn-cgi/access/certs (Cloudflare's documented validation endpoint), verify RS256 signature, validate aud and iss, validate exp/nbf/iat. Match the email claim to an existing active users row.
4. No auto-provision — if email doesn't match an existing user, return 401. Edge identity is not allowed to create Breeze users.
5. MFA: partner-level setting. The CF Access JWT does NOT include an MFA claim (per Cloudflare's docs, the JWT contains aud, email, exp, iat, nbf, iss, type, identity_nonce, sub, country only — auth_status lives at /cdn-cgi/access/get-identity, not in the JWT). So this is a policy-trust decision, not a JWT parse: the self-hoster checks a partner-setting toggle cfAccessTrustsMfa if their CF Access policy enforces MFA at the edge. When on, the minted Breeze JWT gets mfa: true and requireMfa() is satisfied without a second TOTP. When off, Breeze still requires its own MFA on protected routes — defense in depth.
6. Sign-out: independent. Clearing the Breeze session doesn't touch the CF_AppSession cookie. Documented in the deploy notes; the UI shows a hint when CF Access trust is on.
7. No agent-path involvement. Agents continue authenticating with brz_* tokens. CF Access service tokens for /api/v1/* are explicitly NOT proposed — the current edge bypass for the API + agent-WS paths is the right shape and avoids adding a CF-side credential the agent fleet would depend on (a CF outage would otherwise become a fleet outage).

Code shape (rough)

File	Change
apps/api/src/config/validate.ts	Add three optional env vars + validation when trust is enabled
apps/api/src/services/cfAccessJwt.ts (new)	JWKS fetcher (cached, refreshed on kid miss), RS256 verifier via jose, claim-shape types
apps/api/src/services/cfAccessJwt.test.ts (new)	Mocked JWKS, expired token, wrong AUD, wrong issuer
apps/api/src/middleware/cfAccessLogin.ts (new)	Hono middleware: verify JWT, look up user by email, mint Breeze tokens, read partner setting for mfa: true decision
apps/api/src/middleware/cfAccessLogin.test.ts (new)	Handler-level tests
apps/api/src/routes/auth/login.ts	Mount the middleware before the password handler (early-return on success)
Partner-settings schema	Add cfAccessTrustsMfa boolean column (location: wherever per-partner toggles live today — happy to take guidance)
Migration	One-line column add, defaulting false
Docs	Self-hosted deploy doc: Application AUD, team domain, env vars, partner-setting toggle, sign-out caveat

No changes to agent code, mobile, or the existing OIDC flow.

Open questions

1. Partner setting placement: I'm proposing cfAccessTrustsMfa on partner settings. If you'd rather have it on the per-org ssoProviders row (since CF Access conceptually maps to "this org's IdP fronts everything"), say so — same code, different home.
2. JWKS failure mode: fail closed (login refused) or fail open (fall back to password)? I'd lean fail-closed since the operator opted into CF Access trust, but say if you'd rather degrade gracefully.
3. Multi-AUD support: one CF Access app = one AUD. If a deployment fronts multiple Breeze partners behind one CF Access app, do you want a comma-separated AUD list or insist on one-app-per-partner?

Happy to put together the PR once these settle.

[ToddHebebrand]

Thanks @bdunncompany — careful, well-scoped proposal, and the verification work (confirming inbound CF Access trust isn't implemented today, mapping the existing OIDC/JWT/agent-auth paths) is appreciated. Green light on the shape, with decisions on your three open questions:

1. cfAccessTrustsMfa → fourth env var, not a partner setting.

The reasoning is the JWT shape you documented in point 5: the CF Access JWT carries no MFA claim (email, aud, exp, iss, sub, country only — auth_status/auth-method lives at /cdn-cgi/access/get-identity, not the token). So Breeze, verifying just the JWT, cannot observe whether a given user passed an MFA-enforcing CF Access policy. That makes "trust CF Access MFA" unavoidably a deployment-wide operator assertion — "I've configured my CF Access policies so everyone holding a valid JWT for this AUD has done MFA" — not something Breeze can derive or vary per user. A deployment-wide posture statement belongs in env, not a per-partner DB row.

(A per-partner setting is technically implementable — you resolve the user from the email claim, so you know their partner and could key trust off it after lookup. We're declining it for v1 as speculative: the only use case is "CF enforces MFA for everyone, but I additionally want Breeze to double-MFA one partner," which no one has asked for. Revisit if a real deployment does.)

Keep your three env vars as proposed, including the explicit CF_ACCESS_TRUST_ENABLED — an authentication short-circuit should be opted into deliberately, not activated implicitly by the presence of other vars. cf. issue #570, where an implicit security-gate default caused a silent auth bypass on a misconfigured deploy; same failure class. Add CF_ACCESS_TRUSTS_MFA (optional, default false) as the fourth var. config/validate.ts validates the group: when CF_ACCESS_TRUST_ENABLED=true, the two strings are required and it errors if either is missing — refuses a turned-on-but-broken state, same as every other gated feature.

Net change to your env surface: just the added CF_ACCESS_TRUSTS_MFA, moved out of partner-settings. Drop the partner-settings schema + migration rows from your file table; everything else in the table stands. This also makes your open question 1 (partner-settings vs ssoProviders row) moot.

2. JWKS failure — split into two rules, no separate knob.

Don't model this as binary fail-open/fail-closed:

• Fail-closed on trust: never accept an unverified JWT. If JWKS can't be fetched and the signature can't be checked, the short-circuit does not apply — no exceptions, no signature-skip path ever.
• Fail-open on availability: when the short-circuit is unavailable, fall through to the standard password+MFA /auth/login handler. A Cloudflare JWKS blip must not become a total Breeze lockout when Breeze's own auth is healthy — the user just types their password (the thing the feature saved them).

Don't add a fail-mode env var. Let the behavior follow from whether password login is enabled on that deployment: password path present → fall through; operator has disabled password auth entirely → JWKS failure blocks, which is then their explicit choice. Combined with the cached-JWKS-refresh-on-kid-miss you already planned, transient blips shouldn't reach the fallback in practice.

3. Single AUD now.

Have the verifier do AUD validation as an internal set-membership check (so a list is a trivial later change), but expose only a single CF_ACCESS_AUD. Multi-AUD only matters for one Breeze fronting multiple partners each behind a different CF app — a rare topology where one-app-per-hostname is the cleaner answer anyway. Widening accepted audiences without a concrete need just enlarges the trust surface. Add the comma-separated form when a real deployment requires it.

Through-line: this is per-install infrastructure config — keep it all in env, no DB/UI surface, no speculative multi-tenant knobs. Revised file table is the four files you listed (cfAccessJwt.ts + test, cfAccessLogin.ts + test), the config/validate.ts additions (now four vars), the login.ts mount, and the deploy doc — minus the partner-settings schema and migration.

Open as a draft and I'll review.

[bdunncompany]

Implemented and live on a self-host. Branch: feat/702-cf-access-jwt-trust-on-login on bdunncompany/breeze. Full test suite + tsc --noEmit clean on every commit.

Heads-up before opening the PR: the original spec (XHR header trust on POST /auth/login) doesn't actually solve the browser SPA case it was meant to, and the working SPA path turned out to need a sibling redirect endpoint. Both code paths now exist on the branch.

What I learned by exercising the XHR path

I built the original spec exactly as agreed: verifier service, RS256 JWKS, four env vars with conditional config/validate.ts checks, fail-closed on trust + fail-open on availability, single AUD plumbed as set-membership. Then deployed, set the flag, and tried to use it.

Empirical finding: on a CF Access topology where the root app protects breeze.example.com and a Bypass policy on breeze.example.com/api/* exempts the agent fleet, the Cf-Access-Jwt-Assertion header is not attached by Cloudflare on the bypassed /api/v1/auth/login path. The CF docs phrase header injection as a side-effect of Access evaluation, and Bypass paths skip evaluation. Verified by inspection on a live deployment.

To make the JWT reach /auth/login, I added a more-specific Access app at exactly breeze.example.com/api/v1/auth/login (same IdP, same email_domain policy as root). The result in a fresh browser:

1. Google sign-in at root: works, root-app session established.
2. SPA loads, user enters Breeze credentials, SPA fetch()s POST /api/v1/auth/login.
3. CF Access sees the new per-app needs its own JWT cookie. Even though identity transfers without UI, CF returns a 302 to set that cookie.
4. The JSON fetch() follows the 302, gets HTML / non-JSON back, surfaces as "Network error" in the SPA.

The XHR-header pattern can't survive CF Access's per-app-cookie redirect when the auth endpoint itself is Access-enforced. Deleting the narrow app restored login. The XHR middleware remains correct for non-browser callers (CLI, server-to-server, MCP-style consumers presenting the header directly), it just doesn't get exercised by the SPA flow.

The redirect-style endpoint that does work

Added a sibling route + SPA wiring that solves the same problem via top-level navigation, which does survive CF Access's redirects. Now also live on the same self-host.

Flow:

1. Fresh browser hits https://breeze.example.com. CF Access auto-redirects to the IdP. User signs in once.
2. SPA loads, LoginPage fetches /api/v1/config. When the deployment-wide cfAccessLogin.enabled flag is true and no Breeze session cookie is present, the SPA does window.location.assign('/api/v1/auth/cf-access-login') (top-level nav).
3. The new GET endpoint at that path is CF-Access-enforced (carved out of /api/* Bypass via a more-specific Access app with the same IdP + same policy). CF transfers identity from the root-app session silently (per CF docs), forwards the JWT header to origin.
4. Endpoint verifies the JWT (reuses the verifier service from the XHR work), mints a Breeze session, sets the refresh cookie, 302s to /?cf-access-login=success.
5. SPA's AuthOverlay detects the marker, trades the cookie for tokens via the existing /auth/refresh path, fetches /users/me, populates the auth store. URL gets cleaned via history.replaceState.

Live result: fresh private browser → one Google sign-in → user lands logged into the dashboard. Zero Breeze password prompt.

Logout

Without something extra, "Sign out" only clears the Breeze session. CF Access holds its own cookies, so visiting /login immediately silently re-enters the user via the SSO redirect. Effectively a no-op logout.

Per https://developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/, each domain's /cdn-cgi/access/logout endpoint clears only its own domain's cookies. CF Access stores cookies on TWO domains per session: the per-app cookie on the app domain (CF_Authorization, CF_Binding, CF_Device, CF_Session on breeze.example.com) and the global session token on the team domain (bdunnco.cloudflareaccess.com). To fully clear both, the new GET /api/v1/auth/cf-access-logout endpoint chains them:

app-logout (clears per-app cookies on app domain)
  └─ returnTo=team-logout (clears global on team domain)
     └─ returnTo=/login?signedOut=1

The /cdn-cgi/access/* paths are reserved by Cloudflare and intercepted at the edge, so they're unaffected by any /api/* Bypass policy. LoginPage's redirect skip-list honours ?signedOut=1, so the user lands on the password form rather than bouncing back through the SSO redirect.

Honest limitation: this is the strongest logout possible within the SSO contract. It clears all Breeze and CF Access state. But if the user's IdP (Google in my test deployment) still has an active session AND CF Access policy still passes for that identity, the very next visit to the app will mint a fresh JWT silently, with no user interaction. That's not a bug in this implementation; it's the SSO model working as designed. Fully ending the session in that browser requires also signing out at the IdP.

Header.handleSignOut routes through the new endpoint via top-level navigation when CF Access is enabled (XHR fetch can't survive CF Access's redirect chain, same root cause as the original XHR-login problem above), otherwise falls back to the existing XHR apiLogout.

Open shape questions before opening the PR

1. Single PR or split? The verifier service is shared by all three paths (XHR middleware + redirect login + redirect logout). One PR feels cleaner. Happy to split if you'd rather keep this issue scoped tight and file the redirect endpoints as a follow-up.

2. MFA on the redirect path. For POC the redirect endpoint emits ?error=mfa-required and the user falls back to password login when they have Breeze MFA enrolled and CF_ACCESS_TRUSTS_MFA=false. Cleaner UX would be a tempToken-via-URL handoff to the existing MFAVerifyForm. I can wire that before the PR or defer to a follow-up. Preference?

3. SPA config surface. /api/v1/config (previously features-only) now also exposes cfAccessLogin: { enabled } so the SPA can decide at mount time whether to redirect. Are you OK with that shape, or would you prefer a dedicated /api/v1/auth/config endpoint to keep /config purely feature flags?

Will open as draft once you confirm the shape. No client names anywhere in the PR.

---

[ToddHebebrand]

Thanks @bdunncompany — that's an excellent piece of empirical work, and the writeup of why the XHR path fails for browser SPAs (Bypass policies skip header injection; narrowing the Access app triggers per-app cookie redirects that JSON fetch can't follow) is exactly the kind of finding that saves the next person a week. Glad you ran it to ground on a real deployment instead of trusting the docs.

Decisions on your three questions:

1. Single PR. Land all three endpoints + the shared verifier together. The verifier service is the load-bearing piece for all three paths, the XHR middleware doesn't stand alone meaningfully (non-browser callers are a small fraction of the audience this feature is for), and the CSRF/cookie behavior of the redirect login + logout chain is best reviewed as one coherent flow. Total ~280 LOC for the auth surface is well within the scope of recent auth PRs in this repo (#781 was 9 security fixes in one). Subsection comments in the route file are fine; what I don't want is the XHR middleware merging then sitting unused for weeks waiting on the SPA-facing piece that actually solves the problem.

2. MFA handoff: defer to a follow-up PR. Keep the ?error=mfa-required fallback for v1, but improve the SPA-side messaging so users hit with this don't think login is broken — surface something like "MFA is enrolled for your account. Complete sign-in with your Breeze password to verify your second factor." on the login page when ?error=mfa-required is present.

The reason to defer: the current MFA flow returns a tempToken in a JSON response (apps/api/src/routes/auth/login.ts:179–195) that the SPA stores in component state and posts to /auth/mfa/verify (apps/api/src/routes/auth/mfa.ts:110–251). A redirect endpoint can't return JSON, so the handoff needs some out-of-band channel — URL fragment, query param, or short-lived cookie. None are wrong, but each has tradeoffs (fragment is XSS-readable but not server-logged; query is server-logged; cookie is cleanest but adds a new endpoint to consume it). That's a real design decision worth its own PR with its own tests, not a thing to bolt onto the initial landing.

When we do it, my preference is a short-lived (300s) httpOnly+sameSite=strict breeze_mfa_pending cookie set by the redirect endpoint, consumed by a new GET /auth/mfa/from-cookie that returns { tempToken, mfaMethod } for the existing MFAVerifyForm. No tempToken in the URL at all.

3. Dedicated /api/v1/auth/config endpoint. Move cfAccessLogin: { enabled } there rather than expanding /api/v1/config. The existing apps/api/src/routes/config.ts is intentionally features-only (billing/support — derived purely from server env, user-agnostic) and I want to keep that clean. Auth-time signals are a genuinely separate category — cfAccessLogin is the first, but the same endpoint is the right home for the SSO provider list (when we expose it), org-wide MFA policy, password policy, captcha enablement, and the registration-disabled flag we currently leak as a URL search param. Better to define the namespace once than retrofit later.

Concretely: new apps/api/src/routes/auth/config.ts exposing GET /config, mounted under authRoutes in apps/api/src/routes/auth/index.ts. SPA fetches it at mount in the same place it currently fetches /api/v1/config. The endpoint must be public (pre-auth) and must not leak per-user info — public deployment-wide flags only.

One cross-cutting flag for your PR: when the redirect endpoint sets the refresh cookie and 302s to /, double-check the SPA's CSRF token cookie is correctly populated by the time /auth/refresh fires (apps/api/src/routes/auth/helpers.ts:240–277). If the user's first visit is the CF-Access-protected redirect endpoint rather than the SPA root, the CSRF token may not be set yet, and the refresh call will fail. An integration test of fresh-browser → CF Access redirect → refresh → /users/me would catch this.

Open as draft when ready — happy to review.

[ToddHebebrand]

Shipped in #1058 (merged 2026-06-08). Self-hosted Breeze behind Cloudflare Access can now trust the Cf-Access-Jwt-Assertion on login and skip the second password prompt. The JWT signature is genuinely verified (jose, RS256-pinned JWKS for the team domain, iss/aud/exp/iat/sub all enforced — alg-confusion/none blocked), the user must already exist and be active (no auto-provisioning), and safeNext blocks open-redirect/CRLF on the redirect path.

Opt-in / fail-closed: off unless CF_ACCESS_TRUST_ENABLED is set, and every failure path falls back to normal password+MFA login. Test the enabled path against a real CF Access tunnel before flipping it on in prod. Closing as resolved.