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.
• A minimal, recommended middleware file delegates protection to route handlers and the auth() helper rather than protecting everything in middleware.

Example (proxy.ts):

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

// Default usage attaches Clerk to requests but does not implicitly block routes
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 in-middleware route-level decisions. If you use the callback form of clerkMiddleware((auth, req) => {...}), ensure the SDK version you're using supports the callback signature; otherwise prefer auth() in route handlers.

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 (important update)

• Clerk previously documented a "Supabase JWT template" approach. That template-based flow has been deprecated in favor of using Clerk as a third-party provider or sending a valid user token in the Authorization header. See Clerk's Supabase integration guide for details.

• Recommended pattern now: obtain a valid Clerk token for the current user and pass it as an Authorization header when creating the Supabase client. Do NOT expose a Supabase service_role key to the client.

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 from the incoming JWT claims. Clerk's docs show how to use the request JWT claims in Supabase functions to derive clerk_user_id.

Example SQL helper and RLS policy (same pattern):

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. Use the anon key with the user's token in the Authorization header.
• If you used the older supabase.auth.setAuth or Clerk "supabase" token template patterns, migrate to the Authorization header approach and Clerk's official Supabase integration setup.

Reference: Clerk Supabase integration guide (clerk.com/docs/guides/development/integrations/databases/supabase) and Supabase 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.

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 (same as before)
• Multi-tenant RLS policies (same as before)

Decision tree (unchanged)

• 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).
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.

References: OWASP Session Management Cheat Sheet (cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html), Clerk docs (clerk.com/docs), Supabase JWT/RLS docs.

Evaluation criteria (unchanged)

• 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 (see Clerk Supabase integration guide and Supabase repo issue).
• 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.