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. For Next.js ≤15 name it middleware.ts; otherwise proxy.ts (Clerk docs).
• The minimal recommended middleware attaches Clerk token parsing to requests but does not implicitly protect all routes; protection is opt-in (clerkMiddleware default behavior).

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 App and Pages routers (Clerk docs).
• Prefer calling auth() inside App Router route handlers or server components for authoritative user context rather than making complex auth decisions fully in middleware, unless you need in-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 (required migration)

• Clerk previously documented a "Supabase JWT template" approach. That template-based flow was deprecated by Clerk (deprecation noted in Clerk's Supabase integration guide). Migrate away from relying on pre-configured token templates.

• Recommended pattern: obtain a valid Clerk session token for the current user on the server and pass it as an Authorization: Bearer <token> header when creating the Supabase client. Do NOT expose a Supabase service_role key to the client (Clerk docs + Supabase docs).

Example (server-side):

import { auth } from '@clerk/nextjs/server';
import { createClient } from '@supabase/supabase-js';

export async function getAuthenticatedSupabase() {
  const { getToken } = await auth();
  // request a standard session/JWT token; don't rely on deprecated preconfigured templates
  const userToken = await getToken();
  if (!userToken) throw new Error('Failed to obtain Clerk token');

  return createClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    { global: { headers: { Authorization: `Bearer ${userToken}` } } }
  );
}

• Ensure your RLS policies extract the Clerk user ID (sub claim) from incoming JWT claims. Clerk's guide shows the recommended SQL helpers and RLS examples.

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 in the Authorization header.
• If you used older supabase.auth.setAuth or Clerk "Supabase" token template patterns, migrate to the Authorization header approach (Clerk integration guide).

Reference: Clerk Supabase integration guide (clerk.com/docs/guides/development/integrations/databases/supabase) and Supabase RLS docs (supabase.com/docs/guides/auth/row-level-security).

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 deprecated. Use a server-side token and send it in the Authorization header when creating the Supabase client. Verify the token includes a sub claim used by your RLS functions (Clerk docs, Supabase docs). Deprecation was announced in Clerk's Supabase integration guide.
2. Middleware matcher too broad — matching /(.*) intercepts static assets and causes performance issues. Use the recommended matcher pattern from Clerk's middleware docs.
3. 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).
4. Webhook replay — svix handles deduplication via svix-id, but your handler must be idempotent for retries.
5. 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.
6. Auth in server actions — auth() works in server components and route handlers but must be awaited in Next.js App Router handlers.
7. 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.
8. 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.
9. Dependency supply-chain risk: monitor dependency health and pin/scan critical packages — Snyk's recent Axios compromise writeup illustrates active supply-chain threats (snyk.io blog).
10. 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: OWASP Session Management Cheat Sheet, Clerk docs (clerk.com/docs, clerk.com/docs/guides/development/integrations/databases/supabase), Supabase RLS docs (supabase.com/docs/guides/auth/row-level-security), 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

• Replaced the Supabase token-template example with the Authorization-header pattern and added migration guidance — Clerk documents a Supabase JWT template deprecation and Supabase docs discourage setAuth.
• Clarified middleware guidance to prefer the default clerkMiddleware() file + auth() in handlers; preserved the callback form caveat for older/newer SDK versions.
• 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.