Clerk-Authentifizierung

Clerk ist die Authentifizierungs- und Benutzerverwaltungs-Plattform, die alle Identitätsoperationen in CodeCourier übernimmt. Von der Registrierung über die Sitzungsverwaltung bis hin zur webhook- gesteuerten Konto-Bereinigung stellt Clerk eine vollständige Authentifizierungslösung bereit, die sich nahtlos in das Next.js- Frontend und das Convex-Backend integriert. Diese Seite beschreibt, wie CodeCourier Clerk nutzt, die Einrichtungsschritte und Optionen zur Anpassung.

Was Clerk bietet

Clerk ist eine entwicklerorientierte Authentifizierungsplattform mit folgenden Funktionen:

• Mehrere Anmeldemethoden -- E-Mail und Passwort, OAuth-Anbieter (Google, GitHub und weitere), Magic Links und mehr.
• Vorgefertigte UI-Komponenten -- Drop-in- Anmelde- und Registrierungsformulare, die den kompletten Authentifizierungsablauf abdecken.
• JWT-Ausstellung -- Signierte JWTs, die sich in Backend-Dienste wie Convex zur serverseitigen Identitätsprüfung integrieren lassen.
• Benutzerverwaltung -- Benutzerprofile, Metadaten und Kontoeinstellungen über ein gehostetes Dashboard.
• Webhook-Ereignisse -- Benachrichtigungen über Lebenszyklus-Ereignisse wie Kontoerstellung und -löschung.
• Sitzungsverwaltung -- Automatische Sitzungs- erneuerung, Multi-Device-Unterstützung und sicheres Cookie- Handling.

Wie CodeCourier Clerk nutzt

Authentifizierungsablauf

CodeCourier verwendet das @clerk/nextjs SDK (Version 6+) zur Integration von Clerk in den Next.js App Router. Die Integration umfasst:

• Anmelde- und Registrierungsseiten -- Unter /sign-in und /sign-up verwenden diese die vorgefertigten Clerk-Komponenten, die an das Designsystem von CodeCourier angepasst sind.
• Routenschutz -- Der Next.js-Proxy (proxy.ts) fängt Anfragen ab und leitet nicht authentifizierte Benutzer für geschützte Routen zur Anmeldeseite um.
• Convex-Integration -- Die ConvexProviderWithClerk-Komponente umschließt die App und übergibt Clerk-Sitzungs-Tokens automatisch an den Convex-Client zur serverseitigen Authentifizierung.

Synchronisierung von Benutzerdatensätzen

Wenn ein Benutzer sich zum ersten Mal anmeldet, erstellt CodeCourier einen entsprechenden Datensatz in der Convex-Tabelle users. Dieser Datensatz speichert:

• clerkId -- Die Clerk-Benutzer-ID, für Lookups über den Index by_clerk_id.
• email -- Die primäre E-Mail-Adresse des Benutzers.
• name -- Der Anzeigename des Benutzers (optional).
• imageUrl -- Die Avatar-URL des Benutzers aus dem Clerk-Profil oder vom OAuth-Anbieter.
• role -- Eine optionale Rolle auf Anwendungsebene (nicht zu verwechseln mit den Projektmitglieder-Rollen).

Sitzungsverwaltung

Clerk übernimmt den Sitzungslebenszyklus automatisch. Sitzungen werden über sichere HTTP-only-Cookies mit automatischer Erneuerung verwaltet. Das @clerk/nextjs SDK stellt eine Middleware bereit (in Next.js 16 implementiert als proxy.ts), die die Sitzung bei jeder Anfrage validiert und die Benutzeridentität für Server-Components und API-Routen verfügbar macht.

Kontolöschung

Wenn ein Benutzer sein Clerk-Konto löscht, empfängt der Endpoint /clerk/webhook ein user.deleted-Event. Dies stößt die Bereinigung der Benutzerdaten in Convex an. Der Webhook verwendet zur Sicherheit die Svix-Signaturprüfung (siehe Seite Webhooks für Details zur Verifizierung).

Einrichtung und Konfiguration

Umgebungsvariablen

Drei Umgebungsvariablen sind für die Clerk-Integration erforderlich:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY -- Der öffentliche Schlüssel aus Ihrem Clerk-Dashboard. Wird vom Frontend-SDK für clientseitige Operationen verwendet.
• CLERK_SECRET_KEY -- Der geheime Schlüssel aus Ihrem Clerk-Dashboard. Wird vom serverseitigen SDK für Sitzungs- validierung und API-Aufrufe verwendet.
• CLERK_WEBHOOK_SECRET -- Das Svix-Signaturgeheimnis für die Webhook-Verifizierung. Sie erhalten es im Webhooks- Bereich Ihres Clerk-Dashboards.

Konfiguration im Clerk-Dashboard

1. Erstellen Sie eine Clerk-Anwendung unter clerk.com.
2. Konfigurieren Sie die gewünschten Anmeldemethoden (E-Mail/ Passwort, Google OAuth, GitHub OAuth usw.).
3. Kopieren Sie den Publishable Key und den Secret Key in Ihre Umgebungsvariablen.
4. Richten Sie einen Webhook-Endpoint ein, der auf Ihre Convex- Deployment-URL gefolgt von /clerk/webhook verweist.
5. Abonnieren Sie das user.deleted-Event (und alle weiteren Events, die Sie verarbeiten möchten).
6. Kopieren Sie das Webhook-Signaturgeheimnis in Ihre Umgebungs- variable CLERK_WEBHOOK_SECRET.

Benutzerverwaltung

Benutzerprofile

Benutzerprofilinformationen werden primär über Clerk verwaltet. Die von Clerk gehostete Profilseite ermöglicht Benutzern:

• Aktualisierung von Anzeigename und Avatar
• Änderung der E-Mail-Adresse
• Verwaltung verknüpfter OAuth-Konten
• Änderung des Passworts
• Aktivierung oder Deaktivierung der Zwei-Faktor-Authentifizierung

CodeCourier liest Profilinformationen über das Sitzungs-JWT aus Clerk und zeigt sie im Dashboard-Header, in der Benutzer-Avatar- Komponente und in Projektmitgliederlisten an.

Benutzereinstellungen

Anwendungsspezifische Einstellungen (zum Beispiel das zuletzt aktive Projekt) werden in der Convex-Tabelle userSettings gespeichert, getrennt vom Clerk-Profil. Diese Trennung lässt Clerk sich auf Identität konzentrieren, während Convex den Anwendungs- zustand verwaltet.

OAuth und Social Authentication

Clerk unterstützt zahlreiche OAuth-Anbieter out of the box. So fügen Sie eine Social-Sign-in-Option hinzu:

1. Navigieren Sie zu User & Authentication > Social Connections im Clerk-Dashboard.
2. Aktivieren Sie den gewünschten Anbieter (Google, GitHub usw.).
3. Konfigurieren Sie die OAuth-Anmeldedaten (Client-ID und Secret) für Produktions-Deployments.

In CodeCourier sind keine Code-Änderungen nötig -- die Clerk- Anmeldekomponenten zeigen automatisch Schaltflächen für alle aktivierten Anbieter an.

Anpassung

Theme-Integration

CodeCourier passt die Clerk-Anmelde- und Registrierungskomponenten mithilfe des Pakets @clerk/themes an. Die Erscheinungs- bild-Konfiguration ist in lib/clerk-appearance.ts definiert und stellt sicher, dass Clerk-Komponenten zum Design- system von CodeCourier passen, einschließlich Dark-Mode-Unter- stützung und konsistenter Typografie.

Auth Guard

Die Komponente AuthGuard bietet clientseitigen Routenschutz. Sie prüft den Clerk-Sitzungsstatus und leitet nicht authentifizierte Benutzer zur Anmeldeseite um. Dies ergänzt den serverseitigen Proxy im Sinne einer mehrstufigen Verteidigung.

DSGVO und Datenschutz

CodeCourier implementiert neben der Clerk-Authentifizierung ein Einwilligungsmanagement-System. Die Tabellen consents und consentHistory erfassen die Benutzereinwilligungen für essenzielle, analytische, Marketing- und funktionale Datenverarbeitung. Benutzer können Datenanfragen (Export, Löschung, Einschränkung, Widerspruch, Berichtigung) über das System dataRequests stellen.

Wenn ein Benutzer über CodeCourier die Kontolöschung anfordert, verarbeitet das System die Anfrage intern und kann bei Bedarf auch die Löschung des Clerk-Kontos auslösen. Umgekehrt sorgt der Webhook dafür, dass CodeCourier informiert wird und entsprechend aufräumen kann, wenn ein Benutzer sein Clerk-Konto direkt löscht.