Auth Libraries, OAuth and OIDC

At 4+ years, auth questions go past "what is a JWT?". Interviewers want to know whether you understand the login protocol (code, PKCE, state, tokens), whether you can choose between Auth.js, Better Auth, Clerk and Auth0 and defend it, and whether you know the places where Next.js apps are really broken: a check in only one layer, a Server Action with no check, a tenant id taken from the client.

Where to find the basics: how cookies, localStorage, CSRF and CORS work is in Browser Contract, Lesson 3 and Lesson 4. Sessions versus JWTs are in Browser Contract, Lesson 2. Password storage, ownership checks and RBAC basics are in Backend, Lesson 6. The short library comparison table is in Full-Stack Q&A, Lesson 13. This lesson does not repeat those. It adds the protocol, the library choices, Next.js 16 protection patterns, multi-tenancy, passkeys and MFA.

Every code sample here was run or type-checked: the OAuth and token code ran on Node.js 22 with jose 6, and the Next.js, Auth.js and Better Auth snippets compiled in strict TypeScript against Next.js 16.4, next-auth 5.0.0-beta.32 and better-auth 1.7.

Words used in this lesson

• OAuth 2.0 is a framework (a set of rules) that lets one app get limited, revocable access to a user's data held by another service. Everyday comparison: a hotel key card. You do not give the cleaner your house key. You give a card that opens one door for one day.
• OpenID Connect (OIDC) is a thin layer on top of OAuth 2.0 that adds a standard way to learn who the user is. Difference in one line: OAuth answers "what may this app do?" (authorization); OIDC answers "who is this person?" (authentication).
• The four roles. The resource owner is the user. The client is your app. The authorization server (also called the identity provider, or IdP, such as Google) logs the user in and hands out tokens. The resource server is the API that accepts the tokens.
• A public client is a client that cannot keep a secret, such as a browser SPA or a mobile app. A confidential client can, such as your Next.js server.
• A grant is one way of getting a token. The authorization code grant is the main one for people logging in: the browser carries a short, one-time code, and your server swaps it for tokens.
• PKCE (Proof Key for Code Exchange, said "pixy") is an add-on to the code grant. The client invents a random secret (the verifier), sends only its hash (the challenge) at the start, and shows the real secret when it swaps the code. Only the client that started the flow can finish it.
• state is a random value your app sends at the start and checks at the end. It ties the response to a login that this browser started. nonce is a random value put inside the ID token. It ties the ID token to one login request.
• An access token is a short-lived credential that an API accepts. A refresh token is a longer-lived credential used only to get new access tokens. An ID token is an OIDC token (always a JWT) that tells your app who logged in.
• A JWT (JSON Web Token) is a signed text token that carries claims (facts) such as sub (subject, the user id), iss (issuer), aud (audience), and exp (expiry time). JWKS is a public list of the issuer's signing keys, so anyone can check a signature.
• A scope is a name for a permission the client asks for, such as openid email or repo:read.
• A session is the server's memory that "this browser is logged in". A session strategy is how you keep it: in a database, or inside a signed cookie.
• RBAC (role-based access control) gives permissions to roles, and roles to users. ABAC (attribute-based access control) decides using facts (attributes) about the user, the thing and the situation.
• A tenant is one customer organization in a multi-customer app (SaaS). Multi-tenant means many tenants share one app and one database.
• A passkey is a login credential made of a key pair that lives on your device. MFA (multi-factor authentication) asks for two or more different kinds of proof. TOTP (time-based one-time password) is the six-digit code that changes every 30 seconds in an authenticator app.

OAuth versus OIDC

A common mix-up: "I used OAuth to log in with Google." Strictly, you used OIDC. OAuth alone says "this app may read the user's calendar". It does not promise anything about who the user is. OIDC adds three things: the openid scope, an ID token, and a standard userinfo endpoint.

The authorization code flow with PKCE

This is the flow every library runs for "Sign in with Google" or "Sign in with GitHub".

1. Your server creates a random verifier, hashes it into a challenge, and also creates state (and a nonce for OIDC). It stores them (in a short-lived, HttpOnly cookie or a server store) and redirects the browser to the provider's /authorize URL with response_type=code, client_id, redirect_uri, scope, state, code_challenge and code_challenge_method=S256.
2. The user logs in at the provider and approves the scopes.
3. The provider redirects the browser back to your redirect_uri with ?code=...&state=....
4. Your server checks that state matches the one it stored. Then it calls the provider's /token endpoint directly (server to server) with the code, the verifier and its client credentials.
5. The provider hashes the verifier, compares it to the challenge from step 1, and returns an access token, a refresh token and (for OIDC) an ID token.
6. Your server validates the ID token, finds or creates the user, and starts your own session (a cookie).

The key idea: the code travels through the browser, where it can leak (a browser extension, a log, a proxy). On its own it is useless, because swapping it needs the verifier, which never left your server.

Here is the PKCE part, run against the official test vector from RFC 7636:

import { createHash, randomBytes } from 'node:crypto'const b64url = (buf) => Buffer.from(buf).toString('base64url')const challengeOf = (verifier) =>  b64url(createHash('sha256').update(verifier).digest())// RFC 7636 appendix B test vectorchallengeOf('dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk')// -> 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'const verifier = b64url(randomBytes(32)) // 43 charactersconst challenge = challengeOf(verifier)  // sent at /authorize; the verifier is sent only at /token

I also ran a small in-memory authorization server around this. A stolen code with a wrong verifier was rejected (PKCE failed). A code used a second time was rejected (code reuse). So the code alone is not enough for an attacker.

Why state and nonce if we have PKCE?

They solve different problems.

PKCE also protects against some CSRF-style attacks, so some servers treat it as a replacement for state. Auth.js uses PKCE by default and adds state where it is needed. Keeping both is cheap and safe. Do not argue that one is "enough" in an interview. Say what each one is for.

Tokens: access, refresh, ID

The best place for the provider's tokens is on your server, not in the browser. If your Next.js server calls the GitHub or Google API, store the access and refresh tokens in your database or an encrypted HttpOnly cookie, and give the browser only your own session cookie. This is the "backend for frontend (BFF)" idea from Browser Contract, Lesson 3.

Refresh token rotation and reuse detection

Refresh token rotation means: each time you use a refresh token, the server gives you a new refresh token and cancels the old one. The server remembers which tokens belong together (a family). If an old token appears again, somebody copied it. The server cannot know whether it is the thief or the real user, so it cancels the whole family. The user must log in again, and the thief is out.

// simplified server side (from the script I ran)function tokenFromRefresh(rt) {  const r = refresh.get(rt)  if (!r) throw new Error('invalid_grant')  const fam = families.get(r.familyId)  if (fam.revoked) throw new Error('family revoked')  if (r.used) { fam.revoked = true; throw new Error('reuse detected') }  r.used = true  return { access_token: newAccessToken(), refresh_token: issueRefresh(r.familyId) }}

In my test: refresh once, get a new token; replay the first one, get reuse detected; then even the newest token fails with family revoked.

The trade-off, which the Auth.js docs also warn about: with rotation, two parallel requests that both try to refresh will race. One wins, the other presents an already-used token and may log the user out. On your side, make refresh a single place guarded by a lock, or refresh in the background before expiry.

Validating an ID token

Your server must check the ID token before trusting it. A library does this, but you should know the list:

1. The signature, using the keys from the issuer's JWKS, and the allowed algorithm (never trust the alg in the token header).
2. iss equals the issuer you expected.
3. aud contains your client_id.
4. exp is in the future (small clock tolerance).
5. nonce equals the one you stored.

import { jwtVerify, createRemoteJWKSet } from 'jose'const JWKS = createRemoteJWKSet(new URL('https://idp.example/.well-known/jwks.json'))const { payload } = await jwtVerify(idToken, JWKS, {  issuer: 'https://idp.example',  audience: process.env.CLIENT_ID,  algorithms: ['RS256'], // pin it})if (payload.nonce !== storedNonce) throw new Error('bad nonce')

I ran this with a local key set. A token with the wrong audience failed with unexpected "aud" claim value, a wrong issuer failed the same way for iss, and a forged token with alg: none was rejected because only RS256 was allowed. Note that jose does not check the nonce for you. That line is yours.

Choosing: Auth.js, Better Auth, Clerk, Auth0, or your own

A short comparison table is already in Full-Stack Q&A, Lesson 13. This section is about how to decide and what to say.

Auth.js (NextAuth) v5

Auth.js is the long-running open-source library for Next.js (the project started in 2018). You run it inside your app. It handles the OAuth flow, cookies and CSRF, and it can store users in your database through adapters (small packages for Prisma, MongoDB and others).

Three facts that popular tutorials get wrong:

• Version 5 is still a beta on npm. next-auth@latest is 4.24, and v5 is published as 5.0.0-beta.32. Many tutorials say "use v5" without saying this.
• The Auth.js README now says the project is part of Better Auth and recommends Better Auth for new projects, except when you need stateless sessions with no database. Better Auth keeps fixing security problems in Auth.js.
• Passkeys in Auth.js are experimental. The provider needs experimental: { enableWebAuthn: true }.

A v5 setup, type-checked against Next.js 16:

// auth.tsimport NextAuth from 'next-auth'import Google from 'next-auth/providers/google'import GitHub from 'next-auth/providers/github'export const { handlers, auth, signIn, signOut } = NextAuth({  providers: [Google, GitHub], // reads AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET, ...  session: { strategy: 'jwt', maxAge: 60 * 60 * 24 * 30 },  callbacks: {    jwt({ token, user }) {      if (user) token.role = (user as { role?: string }).role ?? 'member' // runs with `user` only at sign-in      return token    },    session({ session, token }) {      session.user.id = token.sub!      return session    },  },})// app/api/auth/[...nextauth]/route.ts// import { handlers } from '@/auth'// export const { GET, POST } = handlers

Defaults worth knowing (from the source): the session strategy is database if you pass an adapter, otherwise jwt; the session lasts 30 days, refreshed at most once a day; the JWT is encrypted in an HttpOnly cookie (cookies over about 4 KB are split into chunks); you need an AUTH_SECRET of at least 32 random characters.

Better Auth (newer)

Better Auth is a TypeScript library that keeps users, accounts and sessions in your own database and adds features as plugins: two-factor, passkeys, organizations (for multi-tenancy), and more.

import { betterAuth } from 'better-auth'import { nextCookies } from 'better-auth/next-js'import { twoFactor, organization } from 'better-auth/plugins'import { passkey } from '@better-auth/passkey'export const auth = betterAuth({  socialProviders: {    github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET! },  },  session: {    expiresIn: 60 * 60 * 24 * 7,  // 7 days (the default)    updateAge: 60 * 60 * 24,      // extend at most once a day (the default)    cookieCache: { enabled: true, maxAge: 5 * 60 },  },  account: { accountLinking: { enabled: true, trustedProviders: [] } },  plugins: [twoFactor({ issuer: 'My App' }), organization(), passkey(), nextCookies()],})

Facts from its docs: sessions are database rows and the cookie holds the session token; the cookie cache is a short-lived signed cookie so you skip the database on most reads, with the warning that a revoked session may stay valid on other devices until the cache expires; it protects against CSRF with Origin checks, Fetch Metadata headers and SameSite=Lax; and it uses state and PKCE for OAuth.

Clerk and Auth0: hosted services

Clerk and Auth0 are hosted identity services (IDaaS, identity as a service). They store the users, run the login pages and send the emails. Your app uses their SDK and checks their tokens.

My rule: use a hosted service when auth is not your product and the team is small, and when enterprise needs (SAML single sign-on, audit logs) are coming. Use a library when you need data ownership, a custom model (like complex tenants) or low cost at scale. Write your own only for learning; the Next.js docs themselves recommend a library.

A hosted service does not remove your work: you still check the session on every server entry point, keep roles and tenants consistent between their data and yours, and plan for the day you need to leave (can you export users, and what happens to password hashes?). I treat the export rules as something to confirm with the vendor, not assume.

Session strategies: database or JWT

You have seen the general difference in Browser Contract, Lesson 2. The library view in one table:

I ran a small proof: after "logout", a JWT session still verified successfully (it was valid until exp), while a deleted session row returned nothing at once. If you choose JWT, keep it short (minutes) and add refresh, or accept that bans take time. In both Auth.js and Better Auth the cookie-cache idea is the middle path: database truth, with a short signed cache.

Protecting a Next.js 16 app

The Next.js authentication guide gives three layers. Use all three, because each one covers what the others miss.

1. Optimistic check in proxy.ts (called middleware.ts before Next.js 16). Cheap. It only looks at the cookie and redirects. It is for user experience, not for security.
2. A data access layer (DAL): one server-only module with getSession() that every Server Component, Server Action and Route Handler calls, close to the data.
3. Checks in the query: ownership and tenant are part of the database query.

The session helper

// lib/session.tsimport 'server-only'import { cookies } from 'next/headers'import { cache } from 'react'import { jwtVerify, SignJWT } from 'jose'const key = new TextEncoder().encode(process.env.SESSION_SECRET)export type Session = { userId: string; role: 'member' | 'admin'; orgId: string }export async function createSession(s: Session) {  const token = await new SignJWT(s)    .setProtectedHeader({ alg: 'HS256' })    .setIssuedAt()    .setExpirationTime('15m')    .sign(key)  ;(await cookies()).set('session', token, {    httpOnly: true, secure: true, sameSite: 'lax', path: '/', maxAge: 15 * 60,  })}// cache() = one lookup per request, shared by layout, page and actionsexport const getSession = cache(async (): Promise<Session | null> => {  const token = (await cookies()).get('session')?.value  if (!token) return null  try {    const { payload } = await jwtVerify(token, key, { algorithms: ['HS256'] })    return payload as unknown as Session  } catch {    return null  }})

cache from React remembers (memoizes) the result for one request only, so five components can call getSession() and the cookie is verified once. In Next.js 16, cookies() is async, so you await it.

The proxy

// proxy.tsimport { NextRequest, NextResponse } from 'next/server'// Optimistic check only: is there a session cookie at all? No database here.export function proxy(request: NextRequest) {  const hasCookie = request.cookies.has('session')  if (!hasCookie && request.nextUrl.pathname.startsWith('/dashboard')) {    const url = new URL('/login', request.url)    url.searchParams.set('next', request.nextUrl.pathname)    return NextResponse.redirect(url)  }  return NextResponse.next()}export const config = {  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],}

Facts from the Next.js 16 docs: the file exports a function named proxy (or a default export); it runs on the Node.js runtime; without a matcher it runs on every request including static files, so exclude them; and it also runs on prefetches, so do not call the database in it.

Server Actions and Route Handlers

Treat both as public HTTP endpoints. Anyone can send a request to them with curl, no matter what your UI shows.

// app/actions/orders.ts'use server'import { getSession } from '@/lib/session'import { db } from '@/lib/db'export async function cancelOrder(orderId: string) {  const session = await getSession()  if (!session) throw new Error('UNAUTHENTICATED')  // ownership and tenant are part of the query, not an `if` after it  const result = await db.order.updateMany({    where: {      id: orderId,      orgId: session.orgId,      ...(session.role === 'admin' ? {} : { userId: session.userId }),    },    data: { status: 'cancelled' },  })  if (result.count === 0) throw new Error('NOT_FOUND') // hides other tenants' ids}

// app/api/orders/[id]/route.tsimport { getSession } from '@/lib/session'import { db } from '@/lib/db'export async function GET(_req: Request, ctx: { params: Promise<{ id: string }> }) {  const session = await getSession()  if (!session) return Response.json({ error: 'unauthenticated' }, { status: 401 })  const { id } = await ctx.params  const order = await db.order.findFirst({ where: { id, orgId: session.orgId } })  if (!order) return Response.json({ error: 'not found' }, { status: 404 })  return Response.json(order)}

Both compiled in strict TypeScript against Next.js 16. Notes:

• In a Route Handler you return 401 / 404 yourself. Next.js also has unauthorized() and forbidden() helpers, but they are experimental and need experimental.authInterrupts: true. Do not build on them without saying so.
• Server Actions get a built-in CSRF check: Next.js compares the Origin header with Host (or X-Forwarded-Host) and only accepts POST. Behind a proxy or CDN on another domain, list it in serverActions.allowedOrigins.
• A Server Action is a POST to the page's own URL. If your proxy matcher skips that path, the proxy also skips the action. So never rely on the proxy for actions.

A word about Cache Components

If you turn on Cache Components, reading the session at request time cannot be part of the static page shell. Put the part of the page that reads cookies() inside <Suspense>. For caching per-user data, the docs use 'use cache: private', which can read cookies and keeps the result in the browser only. Never put user data into a shared cache without the user id as part of the key.

RBAC, ABAC and multi-tenant authorization

Backend, Lesson 6 has the first look at RBAC and ABAC. The deeper points:

• RBAC is simple to understand and audit: admin, editor, viewer. It breaks when you need rules like "an editor can edit only drafts in their own team". Roles explode (editor-team-a, editor-team-b).
• ABAC answers with a rule over attributes: user.orgId == doc.orgId && (user.role == 'admin' || doc.ownerId == user.id). It is flexible, but harder to audit, so keep rules in one function and test them with a table of cases.
• In practice, I use RBAC for coarse feature access and ABAC-style checks for per-record decisions. The result is one function, can(user, action, resource), instead of if statements spread over the code.

Multi-tenant isolation

In a multi-tenant app the worst bug is one customer seeing another customer's data. The rules:

1. The tenant id comes from the verified session (or the verified membership), never from a request body, query string or a header the client controls.
2. Every query includes the tenant filter. Wrap it so people cannot forget: a repository function forTenant(orgId) or a Prisma client extension that adds where: { orgId }. For stronger safety, use PostgreSQL row-level security (RLS), where the database itself refuses cross-tenant rows.
3. A user can belong to many tenants. Keep a current organization in the session, and check the user's membership and role in that organization on every request, not a global role.
4. Return 404 for another tenant's id, so ids do not leak existence.
5. Test it: a test that logs in as tenant A and requests tenant B's id for every endpoint.

Subdomain-based tenants (acme.example.com) need the cookie scope thought out: a cookie set for .example.com is sent to all tenants' subdomains. Better Auth and Auth.js both let you configure cookie domains, but shared cookies widen the blast radius of an XSS bug on any one subdomain. The Next.js docs only point to a "platforms starter kit" for this topic, so treat it as an architecture decision you own.

Passkeys and MFA

Passkeys (WebAuthn)

WebAuthn is the browser standard behind passkeys. When the user registers, their device makes a key pair for your site. The private key stays on the device (often protected by a fingerprint or face check). Your server stores the public key. At login your server sends a random challenge, the device signs it, and your server checks the signature with the public key.

Why this is strong:

• There is no shared secret on your server. A database leak gives attackers only public keys.
• The credential is tied to your domain (the relying party id, rpID). A fake site on another domain cannot ask for it, so phishing does not work.
• Many passkeys sync across the user's devices through the platform account (Apple, Google, Microsoft, password managers). So losing one phone is not losing the account.

The library @simplewebauthn/server makes the options for you:

import { generateRegistrationOptions } from '@simplewebauthn/server'const options = await generateRegistrationOptions({  rpName: 'My App', rpID: 'example.com', userName: 'ada@example.com',})// keys: challenge, rp, user, pubKeyCredParams, timeout (60000), attestation ('none'),//       excludeCredentials, authenticatorSelection (residentKey 'preferred'), ...

You must save the challenge on the server for the user's session, and check it when the browser sends the signed result back. Using the same challenge twice, or not checking it, is the classic mistake. In Better Auth, the passkey plugin does this and supports browser autofill ("conditional UI": the passkey appears in the username field). Remember rpID and origin must match your real domain, and localhost needs explicit settings.

Always keep a recovery path (another passkey, an email link, backup codes). Without it, a lost device becomes a support ticket.

MFA and TOTP

MFA combines different factors: something you know (password), something you have (phone, security key), something you are (fingerprint). Two passwords are not two factors.

TOTP is simple: the server and the app share a secret; both compute HMAC(secret, floor(time / 30)) and take six digits from the result. I wrote it by hand (about ten lines with node:crypto) and it matched the RFC 6238 test value 94287082 for time 59 with 8 digits. In production use a library (Better Auth's twoFactor plugin, or otplib), accept one step before and after for clock drift, rate limit attempts, and never accept the same code twice.

CSRF with OAuth state, and account linking

Login CSRF and state

In a login CSRF attack, the attacker starts an OAuth login with their own account and gets a code. They trick your victim's browser into opening the callback URL with that code. Without state, your app finishes the login and the victim is now logged in as the attacker. They may then save their card or files into the attacker's account.

state fixes it. Your app puts a random value in a cookie when it starts the flow and sends the same value to the provider. At the callback, the value from the URL must equal the cookie. The attacker cannot set a cookie in the victim's browser, so the check fails. Compare it in constant time and expire it after a few minutes. Libraries do this for you; Auth.js and Better Auth both store it in a short-lived cookie. The general CSRF defences for your own endpoints are in Browser Contract, Lesson 3.

Also check the redirect_uri on the provider side by exact match, and validate any callbackUrl or next parameter in your own app, so it cannot become an open redirect (a link on your domain that sends the user to an attacker's site).

Account linking

Account linking means attaching a second login method (Google, GitHub, password) to the same user. The risk is account takeover by email: an attacker creates an account on a weak provider with your victim's email and, if your app links by email without checking, takes over the existing account.

• Auth.js refuses by default. If another account has the same email, the user gets an OAuthAccountNotLinked error. The flag allowDangerousEmailAccountLinking turns on automatic linking, and its name is a warning. Use it only for providers that you know verify email.
• Better Auth links automatically only if the provider reports the email as verified (or the provider is in trustedProviders). disableImplicitLinking: true turns off linking on sign-in; then users link from their settings page while logged in with linkSocial.
• The safe rule: link on sign-in only when the email is verified by a provider you trust; otherwise ask the user to log in with the old method first and link from the settings page. Also, when the email is unverified on the existing account, an attacker may have pre-registered it, so do not trust it.

Common mistakes

Interview questions

Key takeaways

• OAuth gives limited access with tokens; OIDC adds "who logged in" with an ID token. Use the authorization code flow with PKCE; the implicit and password grants are out.
• state stops login CSRF, PKCE stops code theft, nonce stops ID token replay. Validate iss, aud, exp, signature with a pinned algorithm, and nonce.
• Keep provider tokens on the server. Use refresh token rotation with reuse detection, and lock your refresh calls.
• Database sessions can be revoked at once; JWT sessions cannot. A short cookie cache is the middle road.
• Auth.js v5 is still a beta and its README recommends Better Auth for new projects; Better Auth is newer but established enough to use with care. Hosted services trade money and lock-in for speed.
• In Next.js 16: proxy.ts is an optimistic check only; real checks live in a server-only DAL, in every Server Action and Route Handler, and inside the query.
• Multi-tenant: tenant from the session, in every query, 404 for other tenants, and test it.
• Passkeys are phishing-resistant; TOTP is good but phishable; always have recovery. Link accounts only on verified emails.

What's next

• Browser Contract, Lessons 2 to 4 for session storage, CSRF and CORS in depth.
• Backend, Lesson 6 for password storage, ownership checks and the first look at RBAC and ABAC.
• Full-Stack Q&A, Lesson 13 for the wider library comparison.