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 undauth()/currentUser()für die serverseitige Authentifizierung. Clerk Core 3 (2026) ersetzt<SignedIn>/<SignedOut>durch<Show>, benennt die Middleware-Datei inproxy.tsum (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()undcreateRouteMatcher() - 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:
- reference.md – Entscheidungsrahmen, Hooks-Kurzreferenz, Core 3 Migrations-Spickzettel
- examples/core.md – ClerkProvider, Umgebungsvariablen, Middleware-Konfiguration
- examples/components.md – Vorgefertigte Komponenten, Anpassung, Appearance-Prop
- examples/hooks.md – useUser, useAuth, useSession, Ladezustände, bedingte Darstellung
- examples/server.md – Server Components, API-Routen, Server Actions, Webhook-Verarbeitung
- examples/organizations.md – Organisationsverwaltung, Rollen, Berechtigungen, RBAC
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:
- 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).
- Server-First-Authentifizierung – Verwenden Sie
auth()undcurrentUser()in Server Components und Route Handlern. Verwenden Sie Client-Hooks (useUser,useAuth) nur, wenn Sie reaktiven Client-Status benötigen. - 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. - 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.
- 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:
ClerkProviderkommt 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.tsunter Next.js 16+ odermiddleware.tsunter Next.js <=15 - Der Webhook-Endpunkt muss in der Liste der öffentlichen Routen sein (wird separat durch
verifyWebhookverifiziert) CLERK_WEBHOOK_SIGNING_SECRETist die Umgebungsvariable für die Webhook-Signierung (nichtCLERK_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 AutorisierunguseOrganization()– Aktive Organisationsdaten, Mitgliedschaft, paginierte MitgliederlisteuseReverification()– 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/nextjsanstatt 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 (gibtprivateMetadatapreis) - Vertrauen von Webhook-Payloads ohne
verifyWebhook-Signaturverifikation - Ausschließliches Verlassen auf Middleware für Routenschutz (Middleware kann umgangen werden)
- Importieren von Typen aus
@clerk/typesanstatt aus@clerk/shared/types(Core 3)
Weniger kritisch, aber wichtig:
- Nicht prüfen von
isLoadedvor 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/SignUpohne 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_SECRETanstelle vonCLERK_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>