OAuth

OAuth providers (Google OIDC, Facebook OAuth 2.0) feed through the multi-tenant Prisma adapter and reuse the JWT/session callbacks documented in authentication. This page covers the OAuth-specific pieces.

Flow

User clicks button (login or join)
  → Social component onClick(provider)
  → store callback URL (3 layers: server cookie, sessionStorage, client cookie)
  → signIn(provider, { callbackUrl, state })
  → Provider (Google / Facebook) → consent → redirect
  → /api/auth/callback/{provider}
  → MultiTenantPrismaAdapter creates / links user
  → JWT issued, session populated
  → redirect callback resolves destination

The <Social /> component (src/components/auth/social.tsx) is used by both /login and /join.

Social component

Two branches in onClick(provider):

Subdomain context

When on a subdomain (e.g. demo.localhost:3000) or ?tenant=:

1. Extract subdomain from hostname or tenant search param.
2. Store in sessionStorage (oauth_tenant, oauth_callback_url).
3. signIn(provider, { callbackUrl: dashboardUrl?tenant=... }).

Copyconst isProdSubdomain =
  currentHost.endsWith(".databayt.org") && currentHost !== "ed.databayt.org"
const isDevSubdomain =
  currentHost.includes(".localhost") && currentHost !== "localhost"

Main domain

When on ed.databayt.org or localhost:3000:

1. Resolve callbackUrl from search params or fall back to DEFAULT_LOGIN_REDIRECT.
2. Triple-store callback URL.
3. Add base64-encoded state { callbackUrl, timestamp }.
4. signIn(provider, { callbackUrl, redirect: true, state }).

Facebook #_=_ cleanup

Facebook appends #_=_ to the redirect. cleanUrlHash() strips it on mount; the redirect callback strips it again server-side.

Copyif (window.location.hash === "#_=_") {
  const cleanUrl = window.location.href.replace(/#.*$/, "")
  window.history.replaceState({}, document.title, cleanUrl)
}

Providers

src/auth.config.ts registers Google and Facebook. The canonical pattern (Google):

CopyGoogle({
  clientId: env.GOOGLE_CLIENT_ID || "",
  clientSecret: env.GOOGLE_CLIENT_SECRET || "",
  authorization: {
    params: {
      prompt: "consent",
      access_type: "offline",
      response_type: "code",
    },
  },
  profile(profile) {
    return {
      id: profile.sub,
      username: profile.name,
      email: profile.email,
      image: profile.picture,
      emailVerified: new Date(), // Google emails pre-verified
    }
  },
})

Google forces prompt: "consent" + access_type: "offline" for refresh tokens. Facebook follows the same shape with clientId/clientSecret; it does not require a custom profile mapper.

Multi-tenant adapter

The User model uses @@unique([email, schoolId]), not @unique email. The standard adapter's findUnique({ where: { email } }) fails. MultiTenantPrismaAdapter overrides four methods:

OAuth users start with schoolId: null; assigned during onboarding.

Account linking

Copymodel Account {
  id                String  @id @default(cuid())
  userId            String
  type              String
  provider          String
  providerAccountId String
  refresh_token     String? @db.Text
  access_token      String? @db.Text
  expires_at        Int?
  token_type        String?
  scope             String?
  id_token          String? @db.Text
  session_state     String?
  user              User    @relation(fields: [userId], references: [id], onDelete: Cascade)
  @@unique([provider, providerAccountId])
}

First sign-in:

1. getUserByAccount — not found.
2. getUserByEmail — checks for existing user (schoolId: null).
3. If exists → linkAccount. Otherwise → createUser then linkAccount.

Repeat sign-in: getUserByAccount finds the row, returns the user, no writes.

OAuthAccountNotLinked: returned when a credentials user tries OAuth with the same email — security feature; user must sign in with their original provider first.

Callback URL preservation

OAuth bounces the user to the provider, then back to /api/auth/callback/{provider} — the original destination is lost. social.tsx triple-stores it before redirect:

Copy// /api/auth/store-callback
cookieStore.set({
  name: "oauth_callback_intended",
  value: callbackUrl,
  httpOnly: true,
  sameSite: "lax",
  secure: process.env.NODE_ENV === "production",
  maxAge: 900,
  path: "/",
})

resolveCallbackUrl() (in auth.ts) reads back, first match wins:

1. Server cookie oauth_callback_intended
2. URL searchParams (callbackUrl, redirect)
3. Regex match for callbackUrl=...
4. baseUrl searchParams

JWT and session for OAuth

src/auth.ts callbacks:

signIn callback always returns true. Provider checks: Facebook logs error if no email (missing email scope); Google logs warning if email_verified is false.

Key implication: the first request after OAuth login may have an incomplete session (no role/schoolId); it auto-refreshes from the DB on the next request.

Redirect callback

Full priority chain in authentication. OAuth-relevant helpers:

Cookie configuration

All auth cookies share domain: ".databayt.org" in production for SSO across ed.databayt.org and every school subdomain. Development uses domain: undefined — scoped to single hostname.

sameSite: "lax" everywhere (required for OAuth redirects); secure: true in production. trustHost: true is required for Vercel proxy environments.

Environment

auth-config-validator.ts validates at module load.

Errors

OAuth failures redirect to /error?error={code}. ErrorCard (src/components/auth/error-card.tsx) maps codes:

File map

UI
  src/components/auth/social.tsx        # Social login buttons
  src/components/auth/error-card.tsx    # Error display

Config
  src/auth.config.ts                    # Provider configs
  src/auth.ts                           # Callbacks, cookie config

Adapter
  src/lib/multi-tenant-prisma-adapter.ts

API
  src/app/api/auth/store-callback/route.ts
  src/app/api/auth/[...nextauth]/route.ts

Validation
  src/lib/auth-config-validator.ts
  src/env.mjs

Middleware
  src/proxy.ts                          # Skips /api/auth/*

Routes / models / pages
  src/routes.ts
  prisma/models/auth.prisma             # User, Account
  src/app/[lang]/(auth)/{error,login,join}/page.tsx

See also

• Authentication
• Credentials
• Flow diagrams