Authentication flow comparison

Workflow (updated)

Step 1: Set up Clerk Middleware (recommended current pattern)

• Clerk's middleware integrates with Next.js via a proxy file. Name the file proxy.ts at the project root (or src/) as shown in Clerk docs. Note: when using older Next.js releases (<=15), Next.js expects the filename middleware.ts — the code is identical; only the filename differs (Clerk docs).

Example (proxy.ts):

import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware()

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
  ],
}

• Use createRouteMatcher() when you need to protect multiple route groups or build complex matchers. The middleware supports both App and Pages routers (Clerk docs).
• By default, clerkMiddleware() does not protect routes — protection is opt-in. Prefer calling auth() inside App Router route handlers or server components for authoritative user context unless you need middleware redirects or proxying.

Reference: Clerk middleware docs (clerk.com/docs/reference/nextjs/clerk-middleware).

Step 2: Protect API routes with server-side auth checks

• Prefer calling auth() inside App Router route handlers (or server components) to get a trustworthy user context.
• Return 401 for missing auth, 403 for insufficient permissions.

Example:

import { auth } from '@clerk/nextjs/server';
import { NextResponse } from 'next/server';

export async function GET() {
  const { userId, orgId, orgRole } = await auth();

  if (!userId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  if (orgRole !== 'org:admin') return NextResponse.json({ error: 'Forbidden' }, { status: 403 });

  return NextResponse.json({ userId, orgId });
}

Step 3: Integrate Clerk tokens with Supabase RLS (migration and current recommended pattern)

• Background: older public examples and community guides showed using supabase.auth.setAuth or Clerk-provided Supabase JWT templates to inject a Supabase-compatible token into the client. These approaches are no longer dependable: the supabase-js v2 client no longer exposes setAuth, and Clerk has shifted guidance toward server-side token provisioning and customized session claims (see sources below).

  • Evidence: supabase-js v2 issue reporting setAuth() missing (supabase/supabase#8490) and Clerk's session token customization docs.

• Recommended pattern (server-mediated Authorization header):

  • Ensure the client sends the user's Clerk session token in the Authorization: Bearer <token> header when making requests that need database access.
  • On the server, create a Supabase client that forwards that Authorization header to Supabase so RLS policies can evaluate the token claims.
  • Do NOT expose a Supabase service_role key to any client — service_role bypasses RLS.

Example (server-side request handler that forwards client's bearer token to Supabase client):

import { createClient } from '@supabase/supabase-js';

export async function handler(req) {
  const authHeader = req.headers.get('authorization') || '';
  if (!authHeader.startsWith('Bearer ')) {
    return new Response(JSON.stringify({ error: 'Missing token' }), { status: 401 });
  }

  const supabase = createClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      global: {
        headers: {
          Authorization: authHeader,
        },
      },
    }
  );

  // Now RLS will evaluate the incoming Clerk JWT claims (e.g. `sub`) when the query runs.
  const { data, error } = await supabase.from('user_profiles').select('*').limit(1);
  return new Response(JSON.stringify({ data, error }), { status: error ? 500 : 200 });
}

• RLS policy guidance: design your RLS policies to read the Clerk user identifier from JWT claims (commonly sub) or from custom session claims you generate via Clerk's session customization features. Example helper and policy below.

Example SQL helper and RLS policy:

CREATE OR REPLACE FUNCTION auth.clerk_user_id()
RETURNS TEXT AS $$
  SELECT coalesce(
    current_setting('request.jwt.claims', true)::json->>'sub',
    (current_setting('request.jwt.claims', true)::json->>'userId')::text
  );
$$ LANGUAGE sql STABLE;

CREATE POLICY "users_own_data" ON public.user_profiles
  FOR ALL USING (clerk_user_id = auth.clerk_user_id());

Notes:

• Do not use the Supabase service_role key in clients — it bypasses RLS entirely. Use the anon key with the user's token included in the Authorization header for user-scoped requests.
• If you used older supabase.auth.setAuth or a Clerk "Supabase" token template, migrate to the Authorization header approach (supabase-js v2 removed setAuth and Clerk docs emphasize server-side claim management).

Reference: supabase-js v2 issue #8490 (GitHub), Clerk session token customization docs, Supabase Auth & RLS docs.

Step 4: Implement RBAC with organization roles

• Keep a small role hierarchy map instead of string-equality checks.
• Be aware Clerk caches org roles in session tokens; role changes might not be immediate until a token refresh. Design UI and backend checks to tolerate short propagation delays.

Example:

import { auth } from '@clerk/nextjs/server';
import { NextResponse } from 'next/server';

type OrgRole = 'org:admin' | 'org:member' | 'org:viewer';
const ROLE_HIERARCHY: Record<OrgRole, number> = { 'org:admin': 3, 'org:member': 2, 'org:viewer': 1 };

export function requireRole(minimumRole: OrgRole) {
  return async function checkRole() {
    const { userId, orgRole } = await auth();
    if (!userId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
    const userLevel = ROLE_HIERARCHY[orgRole as OrgRole] ?? 0;
    if (userLevel < ROLE_HIERARCHY[minimumRole]) return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
    return null;
  };
}

Step 5: Handle Clerk webhooks securely

• Verify Svix signatures before processing. Be idempotent and handle replay safely.

Example (svix verifier):

import { Webhook } from 'svix';

const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET!;

// inside your POST handler
const payload = await request.text();
const wh = new Webhook(WEBHOOK_SECRET);
let event;
try { event = wh.verify(payload, request.headers as any); }
catch { return NextResponse.json({ error: 'Invalid signature' }, { status: 401 }); }
// handle event types idempotently

Examples

• Protected page with org switching
• Multi-tenant RLS policies

Decision tree

• New Next.js app → use Clerk with middleware-based auth
• Enterprise SSO requirement → use Clerk Organizations or Auth0
• Supabase data access → integrate Clerk token in Authorization header, use RLS
• Public API → use API keys with rate limiting, not session auth
• Webhook from Clerk → verify svix signature before processing
• Multi-tenant app → use Clerk Organizations with org-scoped RLS
• Server component data fetch → use auth() to get user context
• If unsure about auth provider → start with Clerk for fastest iteration

Edge cases and gotchas (updated)

1. Clerk token templates & Supabase: the older "Supabase JWT template" flow and client-side supabase.auth.setAuth usage are no longer dependable. Migrate to forwarding a valid Clerk session token in an Authorization: Bearer <token> header and let Supabase evaluate RLS on that token. Evidence: supabase-js v2 removed setAuth (issue referenced) and Clerk documents session customization and preview features.
2. Preview Custom Session Claims: Clerk added a "Preview" feature for custom session claims so you can validate template expressions and resulting claims for a selected user before saving (Clerk changelog). This reduces migration risk when changing claim shapes.
3. Cookie size limit for custom claims: Clerk stores session tokens in cookies; browsers cap cookie size (~4KB). After Clerk default claims, roughly 1.2KB remains for custom claims. Exceeding this will prevent the cookie from being set and will break authentication (Clerk docs).
4. Middleware matcher too broad — matching /(.*) intercepts static assets and causes performance issues. Use the recommended matcher pattern from Clerk's middleware docs.
5. Organization role caching — Clerk caches org roles in the session token. Role changes may not reflect immediately until token refresh (short cache windows are common — check your session TTL).
6. Webhook replay — svix handles deduplication via svix-id, but your handler must be idempotent for retries.
7. RLS with service role key — the Supabase service role key bypasses RLS entirely. Never expose it to the client; use the anon key with user JWTs forwarded in Authorization.
8. Auth in server actions — auth() works in server components and route handlers but must be awaited in Next.js App Router handlers.
9. Cross-domain / multi-domain setups — Clerk sessions are domain-scoped. For multi-domain apps, use Clerk's multi-domain guidance or a backend auth proxy.
10. Session security (OWASP guidance):

• Set cookies with HttpOnly and Secure flags; use SameSite="Lax" or stricter where appropriate.
• Rotate session identifiers on privilege elevation and on login (prevent session fixation).
• Keep short-lived access tokens and refresh securely on the server.
• Do not store long-lived auth tokens in localStorage.

11. Dependency supply-chain risk: monitor dependency health and pin/scan critical packages — Snyk's Axios compromise writeup illustrates active supply-chain threats (snyk.io blog).
12. URL validation & input handling: recent PortSwigger research shows novel URL-validation bypass payloads — ensure strict validation and normalization on auth-related endpoints (portswigger.net research).

References: Clerk changelog (Preview Custom Session Claims), Clerk session token customization docs (cookie size and claim editor), Clerk middleware docs (clerkMiddleware), supabase-js issue #8490 (setAuth removal), Supabase Auth & RLS docs, PortSwigger Research, Snyk Blog.

Evaluation criteria

• Middleware protects all non-public routes
• API routes verify userId before processing requests
• RBAC checks use role hierarchy, not string equality
• Supabase RLS policies reference the Clerk JWT user ID
• Webhook endpoint verifies svix signature before processing
• No auth tokens stored in localStorage (HTTP-only cookies only)
• Organization-scoped queries filter by orgId from the auth context
• Error responses distinguish 401 (unauthenticated) from 403 (unauthorized)
• Auth state is not duplicated between Clerk and application database
• Token refresh and session expiry are handled gracefully in the UI

Research-backed changes

• Added guidance about Clerk's Preview Custom Session Claims feature so templates can be validated before being saved.
• Called out Clerk cookie size limitation for custom session claims (approx. 1.2KB remaining for custom claims after default claims).
• Replaced/clarified the Supabase token-template example with a server-forwarded Authorization-header pattern and added migration guidance referencing supabase-js v2 changes.
• Clarified middleware guidance to prefer the default clerkMiddleware() file + auth() in handlers; preserved the filename caveat for older Next.js versions per Clerk docs.
• Added OWASP session-management reminders for cookie attributes and session rotation.
• Added supply-chain and URL-validation reminders referencing Snyk and PortSwigger signals.

Notes

• Keep this pattern operational: tests should exercise role changes, webhook idempotency, and RLS enforcement end-to-end.
• When changing session claim shapes, use Clerk's Preview feature and run integration tests against your RLS policies to prevent accidental lockouts.