Docs guide: cross-context auth for Next.js apps embedded in enterprise iframes

[azatdavliatshin]

Goals

1. Document a security-conscious pattern for signing in a Next.js / Auth.js app that is embedded as an iframe inside an enterprise host (SharePoint, Teams Tab, Salesforce Lightning, ServiceNow, Confluence/Jira) where third-party cookies are blocked.
2. Give Auth.js users a canonical approach: a one-time, server-side handle exchanged for a CHIPS partitioned cookie, with no session token in any URL instead of ad-hoc workarounds.
3. Cover both the warm path (host SSO session already exists) and the first-time / cold-start path (silent prompt=none against the host SSO).

Non-Goals

1. No change to Auth.js core, adapters, or framework packages, and no new package in the monorepo: this is a docs guide that references an external reference implementation.
2. Not a replacement for the Storage Access API, vendor SDKs, or the Teams Tab SDK: the guide explains when each is the better fit.
3. Not interactive sign-in inside the popup when there is genuinely no host SSO: that case just falls back gracefully.

Background

Third-party-cookie deprecation (Safari ITP, Chrome's 3PC deprecation, Firefox ETP) breaks the embedded sign-in flow for a common B2B shape: a Next.js app distributed through an enterprise host that already has the user signed in to a shared IdP. The user is authenticated at the host but anonymous inside the iframe, and a normal redirect sign-in can't complete inside the frame.

Existing alternatives don't fit cleanly:

• Bare iframe sign-in forces a redundant login the user already completed at the host.
• Storage Access API needs a permission prompt that breaks the silent-SSO UX.
• Pure CHIPS partitioned cookies (no bridge) don't inherit the host session, the iframe gets its own anonymous partition.
• Vendor SDKs (Auth0/Okta/Clerk) assume their hosted identity; the Teams Tab SDK is Teams-only.

There's no documented Auth.js pattern for this today. Prior art: the CHIPS spec, the RFC 8252 shape (a server-side handle store mediating a one-time-code exchange across a trust boundary), and the popup + postMessage handoff.

Proposal

A docs guide under the guides section describing the pattern: a popup runs in the top-level browser context, silent-auths against the host's existing IdP session (prompt=none when SSO is live), mints a 256-bit one-time server-side handle, and posts it back to the embedded app via origin-checked postMessage; the app redeems the handle for a CHIPS partitioned cookie. No session token ever crosses a URL; PKCE is preserved through the handoff; handles are deleted on first read with a short TTL.

The guide is written as a reusable pattern and references next-auth-bridge as one reference implementation (disclosure: I'm the author of that package).

Yes, I'm interested in contributing — a draft is ready, it follows the current guide format, and I'll follow CONTRIBUTING (docs/ placement, lint/format, clean PR title). Verify with a live demo (seeded test user): https://nab-host.vercel.app/ — two real cross-site origins against a self-hosted Keycloak. Package: https://www.npmjs.com/package/next-auth-bridge

Happy to adjust scope, tone, or placement to fit your conventions.

Candor on maturity: the pattern is drawn from a production iframe-SSO integration, but this open-source implementation is new (days old, no adoption yet). It ships with a documented threat model and negative-case tests for each invariant, but it hasn't yet run in production at scale. I'm raising this as a pattern guide precisely so the approach can be scrutinized on its merits; happy for the guide to stand on the pattern, not the package's age.