Communitygithub.com

Clerk Authentifizierungsmuster

Verwaltete Authentifizierung mit Clerk – ClerkProvider, Middleware, vorgefertigte Komponenten, Hooks, serverseitige Authentifizierung, Organisationen, Webhooks

Was ist Clerk Authentifizierungsmuster?

Diese Skill-Ressource beschreibt, wie Clerk – eine Full-Service-Authentifizierungsplattform – in Next.js-Anwendungen integriert wird. Sie deckt die gesamte Palette ab: von der Einrichtung von ClerkProvider und Middleware (inklusive Core 3-Updates wie der Umstellung auf `<Show>` und `proxy.ts`), über vorgefertigte UI-Komponenten (`<SignIn>`, `<UserButton>`) bis hin zu clientseitigen Hooks (`useUser`, `useAuth`) und serverseitiger Authentifizierung (`auth()`, `currentUser()`). Ein zentraler Fokus liegt auf der **verteidigungstiefen** Absicherung: Routen müssen sowohl in der Middleware als auch auf Datenebene geschützt werden. Die Ressource warnt explizit vor veralteten APIs (`<SignedIn>`, `<SignedOut>`) und vor der unsicheren Weitergabe von `privateMetadata` an den Client. Für B2B-Anwendungen wird die organisationsbasierte Mehrinstanzenfähigkeit mit Rollen und Berechtigungen ausführlich behandelt. Webhooks werden mithilfe von `verifyWebhook` (Svix-Signatur) verarbeitet, um Nutzerdaten zuverlässig in die eigene Datenbank zu synchronisieren. Die Skill-Ressource ist ein umfassender Leitfaden für Entwickler, die mit Clerk (Next.js, Core 3) arbeiten, und unterstützt Plattformen mit Server Components, Route Handlern, Server Actions und Middleware.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-auth-clerk

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht Clerk Authentifizierungsmuster?

Kurzanleitung: Clerk bietet verwaltete Authentifizierung mit vorgefertigten UI-Komponenten, serverseitigen Helfern und organisationsbasierter Mehrinstanzenfähigkeit. Verwenden Sie clerkMiddleware() für Routenschutz, <Show> für bedingte Darstellung, Hooks für den Client-Status und auth()/currentUser() für die serverseitige Authentifizierung. Clerk Core 3 (2026) ersetzt <SignedIn>/<SignedOut> durch <Show>, benennt die Middleware-Datei in proxy.ts um (Next.js 16+) und konsolidiert Pakete.


<critical_requirements>

KRITISCH: Bevor Sie diese Skill verwenden

Jeglicher Code muss den Projektkonventionen in CLAUDE.md folgen (kebab-case, benannte Exporte, Importreihenfolge, import type, benannte Konstanten)

(Sie MÜSSEN @clerk/nextjs/server für ALLE serverseitigen Importe verwenden – Importieren Sie serverseitige Helfer NIE aus @clerk/nextjs)

(Sie MÜSSEN Webhooks mit Clerks verifyWebhook-Helfer verifizieren – Vertrauen Sie NIE unverifizierten Webhook-Payloads)

(Sie MÜSSEN die <Show>-Komponente anstelle der veralteten <SignedIn>/<SignedOut>/<Protect> verwenden – diese sind in Core 3 entfernt)

(Sie DÜRFEN das vollständige currentUser()-Objekt NICHT an den Client übergeben – es enthält privateMetadata, das serverseitig bleiben muss)

(Sie MÜSSEN Routen SOWOHL in der Middleware ALS AUCH in der Datenzugriffsschicht schützen – Middleware allein ist nicht ausreichend)

</critical_requirements>


Autoerkennung: Clerk, ClerkProvider, clerkMiddleware, @clerk/nextjs, useUser, useAuth, useClerk, useSession, useOrganization, SignIn, SignUp, UserButton, UserProfile, OrganizationSwitcher, auth(), currentUser(), CLERK_SECRET_KEY, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, Show when="signed-in"

Wann verwenden:

  • Hinzufügen von Authentifizierung und Benutzerverwaltung zu einer Anwendung
  • Erstellen von mehrinstanzenfähigen B2B-Apps mit organisationsbasierter Zugriffskontrolle
  • Verwenden vorgefertigter Anmelde-/Registrierungs-UI-Komponenten mit anpassbarem Design
  • Schützen von Routen mit Middleware und serverseitigen Autorisierungsprüfungen
  • Synchronisieren von Clerk-Benutzerdaten mit Ihrer Datenbank über Webhooks

Abgedeckte Schlüsselmuster:

  • ClerkProvider-Einrichtung, Umgebungsvariablen, Middleware-Konfiguration
  • Vorgefertigte UI-Komponenten (<SignIn>, <SignUp>, <UserButton>, <Show>)
  • Clientseitige Hooks (useUser, useAuth, useSession, useOrganization)
  • Serverseitige Authentifizierung (auth(), currentUser()) in Server Components, Route Handlern, Server Actions
  • Middleware-Routenschutz mit clerkMiddleware() und createRouteMatcher()
  • Organisationsbasierte Mehrinstanzenfähigkeit mit Rollen und Berechtigungen
  • Webhook-Verarbeitung mit Svix-Signaturverifikation

Wann NICHT verwenden:

  • Anforderung für selbst gehostete Authentifizierung (vollständige Kontrolle über Auth-Datenspeicherung erforderlich)
  • Kann keinen Drittanbieter-Auth-Dienst verwenden (Compliance-/Regulierungsbeschränkungen)
  • Einfache API-Key-Authentifizierung (benutzerdefinierte Middleware ist ausreichend)
  • Budgetbeschränkungen verhindern die Nutzung eines verwalteten Dienstes

Detaillierte Ressourcen:


Philosophie

Clerk ist eine verwaltete Authentifizierungsplattform, die den gesamten Auth-Lebenszyklus abdeckt: Registrierung, Anmeldung, Sitzungsverwaltung, Benutzerprofile, Organisationen und MFA. Anstatt Authentifizierung von Grund auf neu zu erstellen, integrieren Sie das Clerk SDK und die vorgefertigten Komponenten.

Kernprinzipien:

  1. Verteidigung in der Tiefe – Schützen Sie Routen auf der Middleware-Ebene UND verifizieren Sie die Authentifizierung an jedem Datenzugriffspunkt. Middleware allein ist nicht ausreichend (CVE-2025-29927 demonstrierte Middleware-Bypass-Schwachstellen).
  2. Server-First-Authentifizierung – Verwenden Sie auth() und currentUser() in Server Components und Route Handlern. Verwenden Sie Client-Hooks (useUser, useAuth) nur, wenn Sie reaktiven Client-Status benötigen.
  3. Vorgefertigt vor benutzerdefiniert – Verwenden Sie Clerks <SignIn>, <SignUp>, <UserButton>-Komponenten. Erstellen Sie benutzerdefinierte Abläufe nur, wenn die vorgefertigten Komponenten die Anforderungen tatsächlich nicht erfüllen können.
  4. Organisationen für Mehrinstanzenfähigkeit – Verwenden Sie Clerk Organizations mit Rollen und Berechtigungen für B2B-Apps. Bauen Sie keine benutzerdefinierten Mandantensysteme auf Clerks Benutzermodell auf.
  5. Webhook-getriebene Synchronisation – Synchronisieren Sie Clerk-Daten mit Ihrer Datenbank über Webhooks, nicht durch Polling. Überprüfen Sie immer Webhook-Signaturen mit verifyWebhook.

Wann Clerk verwenden:

  • Sie benötigen Authentifizierung schnell mit minimalem benutzerdefiniertem Code
  • Sie möchten vorgefertigte UI-Komponenten für Anmeldung/Registrierung/Benutzerverwaltung
  • Sie benötigen organisationsbasierte Mehrinstanzenfähigkeit mit RBAC
  • Sie möchten verwaltetes MFA, SSO (SAML/OIDC) und Social Login

Wann NICHT Clerk verwenden:

  • Sie benötigen vollständige Kontrolle über die Auth-Datenspeicherung (Selbsthosting-Anforderung)
  • Sie können keinen Drittanbieter-Auth-Dienst verwenden (Compliance/Regulierung)
  • Ihre App benötigt nur eine einfache API-Key-Authentifizierung
  • Budgetbeschränkungen verhindern die Nutzung eines verwalteten Dienstes

Kernmuster

Muster 1: ClerkProvider- und Middleware-Einrichtung

Jede Clerk-App benötigt <ClerkProvider>, das die App umschließt, und clerkMiddleware(), das Routen schützt. Vollständige Einrichtungsbeispiele finden Sie in examples/core.md.

Wichtige Regeln:

  • ClerkProvider kommt in <body>, nicht um <html> – Core 3 erfordert dies
  • Verwenden Sie die Umgebungsvariable NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, codieren Sie Schlüssel niemals fest
  • Die Middleware-Datei heißt proxy.ts unter Next.js 16+ oder middleware.ts unter Next.js <=15
  • Der Webhook-Endpunkt muss in der Liste der öffentlichen Routen sein (wird separat durch verifyWebhook verifiziert)
  • CLERK_WEBHOOK_SIGNING_SECRET ist die Umgebungsvariable für die Webhook-Signierung (nicht CLERK_WEBHOOK_SECRET)
// proxy.ts (Next.js 16+) oder middleware.ts (Next.js <=15)
const isPublicRoute = createRouteMatcher([
  "/",
  "/sign-in(.*)",
  "/sign-up(.*)",
  "/api/webhooks(.*)",
]);

export default clerkMiddleware(async (auth, req) => {
  if (!isPublicRoute(req)) {
    await auth.protect();
  }
});

Warum gut: Öffentliche Routen explizit auf die Whitelist gesetzt, alles andere erfordert Authentifizierung, Webhook-Endpunkt ist öffentlich (separat verifiziert)

// SCHLECHT: clerkMiddleware() ohne Callback
export default clerkMiddleware(); // ALLE Routen sind standardmäßig ÖFFENTLICH!

Warum schlecht: clerkMiddleware() ohne Callback hängt Auth-Daten an, schützt aber keine Route


Muster 2: Vorgefertigte UI-Komponenten und <Show>

Verwenden Sie <Show> für bedingte Darstellung (Core 3-Ersatz für <SignedIn>/<SignedOut>/<Protect>). Vollständige Beispiele finden Sie in examples/components.md.

<Show when="signed-out"><SignInButton /></Show>
<Show when="signed-in"><UserButton /></Show>
<Show when={{ role: "org:admin" }}><AdminPanel /></Show>
<Show when={(has) => has({ permission: "org:invoices:manage" })}><InvoiceManager /></Show>

Warum gut: <Show> ist die Core 3-API, unterstützt String-/Objekt-/Callback-Bedingungen, fallback-Prop für Unbefugte

// SCHLECHT: Veraltet – in Core 3 entfernt
<SignedIn>...</SignedIn>
<SignedOut>...</SignedOut>
<Protect role="admin">...</Protect>

Warum schlecht: <SignedIn>, <SignedOut>, <Protect> in Core 3 entfernt, verwenden Sie <Show> mit der when-Prop

Anmelde-/Registrierungsseiten benötigen Catch-All-Routen-Segmente [[...sign-in]] für mehrstufige Abläufe (MFA, OAuth-Callbacks).


Muster 3: Clientseitige Hooks

Verwenden Sie Hooks in Client-Komponenten für reaktiven Auth-Status. Überprüfen Sie immer isLoaded, bevor Sie auf Daten zugreifen. Vollständige Beispiele finden Sie in examples/hooks.md.

"use client";
const { isLoaded, isSignedIn, user } = useUser();
if (!isLoaded) return <div>Lädt...</div>;
if (!isSignedIn) return <div>Bitte anmelden</div>;
// Jetzt sicherer Zugriff auf user.firstName, user.emailAddresses, etc.

Warum gut: Verhindert Hydrierungsfehler durch Zugriff auf undefined während der Initialisierung, verhindert TypeError durch Zugriff auf null bei Abmeldung

// SCHLECHT: Zugriff auf user ohne Guards
const { user } = useUser();
return <p>{user.firstName}</p>; // Laufzeitfehler wenn isLoaded=false oder isSignedIn=false

Warum schlecht: user ist undefined bis zum Laden und null bei Abmeldung

Wichtige Hooks:

  • useUser() – Benutzerprofildaten (Name, E-Mail, Avatar)
  • useAuth() – Sitzungstoken (getToken()), userId, orgId, has() für Autorisierung
  • useOrganization() – Aktive Organisationsdaten, Mitgliedschaft, paginierte Mitgliederliste
  • useReverification() – Erneute Authentifizierung vor sensiblen Aktionen (Core 3)

In Core 3 wirft getToken() ClerkOfflineError bei Offline-Verbindung anstatt null zurück – immer in try/catch einschließen.


Muster 4: Serverseitige Authentifizierung

Verwenden Sie auth() und currentUser() aus @clerk/nextjs/server. Vollständige Beispiele finden Sie in examples/server.md.

auth() – leichtgewichtig, kein API-Aufruf, liest Sitzungsansprüche:

import { auth } from "@clerk/nextjs/server";
const { userId, orgId, isAuthenticated, redirectToSignIn } = await auth();
if (!isAuthenticated) return redirectToSignIn();

currentUser() – vollständiges Benutzerobjekt, führt Backend-API-Aufruf durch:

import { currentUser } from "@clerk/nextjs/server";
const user = await currentUser();
// KRITISCH: Nur sichere Felder auswählen, bevor sie an Client-Komponenten übergeben werden
const safeData = { firstName: user.firstName, imageUrl: user.imageUrl };

Warum kritisch: currentUser() gibt privateMetadata zurück, das niemals den Client erreichen darf. Felder explizit auswählen.

Verteidigung in der Tiefe: Auth MUSS in jeder Server Action und jedem Route Handler überprüft werden, nicht nur in der Middleware:

"use server";
const { userId } = await auth();
if (!userId) throw new Error("Nicht autorisiert");
// userId schränkt alle Abfragen/Mutationen auf den aktuellen Benutzer ein

Muster 5: Autorisierung mit Rollen und Berechtigungen

Verwenden Sie auth.protect() oder has() für granulare Zugriffskontrolle. RBAC-Muster finden Sie in examples/organizations.md.

// Middleware: rollenbasierter Routenschutz
await auth.protect((has) => has({ role: "org:admin" }));

// Server Component: Berechtigungsprüfung
const { has } = await auth();
if (!has({ permission: "org:invoices:delete" })) redirect("/dashboard");

// Client: bedingte Darstellung nach Rolle
<Show when={{ role: "org:admin" }}><AdminPanel /></Show>

Berechtigungsformat: org:<feature>:<action> (z. B. org:invoices:create, org:reports:read)

Standardrollen: org:admin (alle Berechtigungen), org:member (schreibgeschützt). Benutzerdefinierte Rollen werden im Clerk Dashboard konfiguriert.


Muster 6: Webhook-Verarbeitung

Verwenden Sie Clerk-Webhooks (über Svix), um Benutzerdaten mit Ihrer Datenbank zu synchronisieren. Ein vollständigen Handler finden Sie in examples/server.md.

import { verifyWebhook } from "@clerk/nextjs/webhooks";

export async function POST(req: Request) {
  const evt = await verifyWebhook(req); // liest die Umgebungsvariable CLERK_WEBHOOK_SIGNING_SECRET
  // evt.type: "user.created" | "user.updated" | "user.deleted" | "organization.*" | ...
  // evt.data: UserJSON | OrganizationJSON | etc.
}

Warum gut: verifyWebhook validiert die Svix-Signatur, gibt immer 200 zurück, um Wiederholungen zu verhindern, Webhook-Route ist in der Middleware öffentlich (verifiziert durch Signatur, nicht durch Auth)

// SCHLECHT: Keine Signaturverifikation
const body = await req.json(); // Jeder kann gefälschte Daten POSTEN!
await db.insert(users).values(body.data); // Sicherheitslücke

Warum schlecht: Keine Signaturverifikation bedeutet, dass jeder gefälschte Webhook-Ereignisse an Ihren Endpunkt senden kann

Importieren Sie Typen aus @clerk/shared/types (Core 3): UserJSON, OrganizationJSON, OrganizationMembershipJSON


<decision_framework>

Entscheidungsrahmen

Client vs. Server Auth

Wo benötigen Sie Auth-Daten?
|-- Server Component, Route Handler, Server Action
|   |-- Nur userId/sessionId benötigt? --> auth()
|   |-- Vollständiges Benutzerobjekt benötigt? --> currentUser()
|   |-- Route schützen? --> auth.protect()
|   +-- Organisationskontext benötigt? --> auth() gibt orgId, orgRole zurück
|
+-- Client Component (interaktive UI)
    |-- Benutzerprofildaten benötigt? --> useUser()
    |-- Sitzungs-/Token-Daten benötigt? --> useAuth()
    |-- Organisationsdaten benötigt? --> useOrganization()
    +-- Niedrigschwellige Clerk-API benötigt? --> useClerk()

Routenschutzstrategie

Um welche Art von Route handelt es sich?
|-- Öffentlich (Landing, Anmeldung, Registrierung, Webhooks)
|   +-- Zur isPublicRoute-Matcher hinzufügen, auth.protect() überspringen
|
|-- Authentifiziert (Dashboard, Profil, Einstellungen)
|   +-- auth.protect() in Middleware + auth()-Prüfung in der Datenebene
|
+-- Autorisiert (Admin, org-spezifisch, berechtigungsbeschränkt)
    |-- Rollenbasiert? --> auth.protect({ role: "org:admin" })
    +-- Berechtigungsbasiert? --> auth.protect((has) => has({ permission: "org:feature:action" }))

Komponentenauswahl

Welche Auth-UI wird benötigt?
|-- Vollständige Anmeldeseite --> <SignIn /> auf Catch-All-Route
|-- Vollständige Registrierungsseite --> <SignUp /> auf Catch-All-Route
|-- Anmeldebutton (Modal) --> <SignInButton />
|-- Benutzer-Avatar + Menü --> <UserButton />
|-- Vollständiger Profileditor --> <UserProfile />
|-- Org-Wechsler --> <OrganizationSwitcher />
+-- Bedingter Inhalt --> <Show when="signed-in"> oder <Show when={{ role: "..." }}>

</decision_framework>


<red_flags>

ROTE FLAGGEN

Probleme mit hoher Priorität:

  • Importieren serverseitiger Helfer aus @clerk/nextjs anstatt aus @clerk/nextjs/server (bricht in Server Components)
  • Verwenden der veralteten <SignedIn>/<SignedOut>/<Protect>-Komponenten (in Core 3 entfernt)
  • Übergeben des vollständigen currentUser()-Objekts an Client-Komponenten (gibt privateMetadata preis)
  • Vertrauen von Webhook-Payloads ohne verifyWebhook-Signaturverifikation
  • Ausschließliches Verlassen auf Middleware für Routenschutz (Middleware kann umgangen werden)
  • Importieren von Typen aus @clerk/types anstatt aus @clerk/shared/types (Core 3)

Weniger kritisch, aber wichtig:

  • Nicht prüfen von isLoaded vor der Verwendung von Client-Hooks (Hydrierungsfehler)
  • Fehlen von fallback-Props in <Show> (zeigt nichts für Unbefugte an – kann in Ordnung sein, aber oft unbeabsichtigt)
  • Verwenden von SignIn/SignUp ohne Catch-All-Route (bricht mehrstufige Abläufe wie MFA)
  • Nicht einschließen des Webhook-Endpunkts in öffentliche Routen (verursacht 401 bei Svix-Callbacks)
  • Verwenden von CLERK_WEBHOOK_SECRET anstelle von CLERK_WEBHOOK_SIGNING_SECRET (führt zu Signaturfehlern)
  • Nicht einschließen von getToken() in try/catch in Core 3 (wirft Fehler bei Offline-Verbindung)

</red_flags>


Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Verwandte Skills