Clerk: Authentifizierung und OAuth von Dev zu Produktion

Überblick

Deine App braucht jetzt Nutzer: Leute, die sich registrieren, einloggen und ihre eigenen Daten haben. Das ist Authentifizierung, und es ist eine Stelle, an der ein kleiner Fehler jedes Kundenpasswort leakt, das du hältst. Der richtige Zug 2026 ist eindeutig: bau sie nicht selbst, nutze einen Dienst. Clerk ist dieser Dienst für die meisten Builder, für die dieser Kurs gedacht ist. Diese Lektion erklärt das eine Konzept, das du verstehen musst (OAuth), bringt Clerk in deine App und führt dich dann durch den Teil, den alle fummelig finden - von Development-Keys zu einer echten Produktions-Instanz mit Google-Login auf deiner eigenen Domain.

Was du lernst

Du lernst, was OAuth in klarer Sprache ist, warum selbstgebaute Auth eine Falle ist, in die selbst grosse Firmen tappen, wie Clerk zu deiner App passt, den entscheidenden Unterschied zwischen einer Development-Instanz und einer Produktions-Instanz und die genauen Schritte, um Google OAuth in Produktion zu aktivieren, inklusive Google-Consent-Screen, Credentials und der DNS-Records, die es auf deiner Domain laufen lassen.

Voraussetzungen

Eine funktionierende App aus Kurs 1 und die Architektur-Karte aus der vorigen Lektion, denn Auth lebt auf der App-Seite, nicht der Marketing-Seite. Du brauchst auch die Secrets-Disziplin aus Kurs 1: Auth-Keys sind hochsensibel und dürfen nie committet werden. Die nächste Lektion zu Secrets geht tiefer, aber die Grundregel (Keys in .env, .env in .gitignore) muss bereits in Fleisch und Blut sein.

Das Problem

Auth selbst zu bauen klingt wie eine Mutprobe. Es ist eigentlich ein Minenfeld. Du musst Passwörter korrekt hashen und salten, Sessions und Tokens managen, Passwort-Resets behandeln, dich gegen Credential Stuffing und Brute Force wehren, alles sicher speichern und ewig mit neuen Angriffstechniken Schritt halten. Mach ein Detail falsch und du leakst Kundendaten, was eine juristische und reputative Katastrophe ist. Derweil haben deine Konkurrenten mit Clerk den Login an einem Nachmittag geshippt und sind weitergezogen, ihr eigentliches Produkt zu bauen. Es gibt keinen Preis für die selbstgebaute Version. Das ist ein gelöstes Problem, und dein Job ist, die Lösung zu nutzen, nicht sie neu zu erfinden.

Was OAuth tatsächlich ist

OAuth ist das Protokoll hinter jedem "Sign in with Google"- oder "Sign in with GitHub"-Button. Die Kernidee ist Delegation, ohne dein Passwort zu teilen. Wenn ein Nutzer "Sign in with Google" klickt, sieht deine App nie sein Google-Passwort. Stattdessen reicht deine App ihn an Google weiter, Google bestätigt, wer er ist, und bittet ihn, das Teilen seiner E-Mail und seines Namens mit deiner App zu genehmigen, und Google schickt einen Token zurück, der beweist "ja, das ist wirklich er". Deine App vertraut Googles Wort. Das ist das ganze Konzept: ein vertrauenswürdiger Dritter bürgt für den Nutzer, sodass du sein Passwort nie speichern oder prüfen musst. Es ist sicherer (du hältst keine Passwörter), bequemer (ein Klick, kein neuer Account) und es ist, was Nutzer erwarten. Clerk wickelt den gesamten OAuth-Tanz für dich ab - du aktivierst einfach die Provider, die du willst.

• OAuth = einen vertrauenswürdigen Provider (Google, GitHub, Apple) für den Nutzer bürgen lassen, sodass du sein Passwort nie anfässt.
• Deine App bekommt einen Token, der die Identität beweist, plus grundlegende Profil-Infos, deren Teilen der Nutzer genehmigt hat.
• Sicherer für dich (keine Passwörter gespeichert), bequemer für sie (ein Klick).
• Clerk fährt den OAuth-Flow; du aktivierst einen Provider und fügst seine Credentials hinzu.

Clerk zu deiner App hinzufügen

Clerk gibt dir Drop-in-Komponenten für Registrierung, Login, Nutzerprofil und Session-Management plus die Backend-Teile, um deine Routen zu schützen. Du installierst sein Paket, fügst deine Keys in deine Umgebung ein, umhüllst deine App mit seinem Provider und lässt die vorgefertigten Komponenten fallen. Die Keys kommen in zwei Geschmacksrichtungen: ein Publishable Key (sicher in Frontend-Code, er identifiziert nur deine App) und ein Secret Key (nur Backend). Die genauen Import-Pfade hängen von deinem Framework ab, also folge Clerks Docs für die präzisen Zeilen.

# .env.local - dev keys, never committed (.env* is gitignored)
VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxx
CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxx

Beachte die Test-Präfixe. Eine Development-Instanz gibt Keys aus, die mit pk_test und sk_test beginnen; eine Produktions-Instanz gibt pk_live und sk_live aus. Dieses Präfix ist dein Auf-einen-Blick-Check, zu welcher Umgebung ein Key gehört, und es ist das mit Abstand häufigste, das Leute verwechseln. Sobald deine Keys gesetzt sind, umhüllst du deine App mit Clerks Provider und nutzt seine Komponenten.

// A protected page: only signed-in users see the content.
import { SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/clerk-react'

export function AppShell() {
  return (
    <header>
      <SignedOut>
        <SignInButton />
      </SignedOut>
      <SignedIn>
        <UserButton />
      </SignedIn>
    </header>
  )
}

Development-Instanz versus Produktions-Instanz

Clerk trennt dein Projekt in zwei völlig unabhängige Instanzen. Die Development-Instanz ist fürs Bauen: sie nutzt Test-Keys, läuft auf einer von Clerk bereitgestellten geteilten Domain und kommt mit gelockerten Einstellungen, damit du schnell iterieren kannst. Sie ist nicht für echte Nutzer gedacht. Die Produktions-Instanz ist das echte Ding: Live-Keys, deine eigene Domain, strengere Sicherheit und der Ort, an dem echte Kunden sich einloggen. Die beiden teilen keine Nutzer oder Einstellungen - sie sind separate Welten. Der Fehler, den Einsteiger machen, ist, die Development-Instanz als gut genug zu behandeln und echte Nutzer darauf zu zeigen, oder mit pk_test-Keys noch in ihrer Produktionsumgebung zu shippen. Der saubere Ablauf ist: alles auf der Development-Instanz bauen und testen, dann die Produktions-Instanz erstellen, sie konfigurieren (inklusive einer Custom Domain und OAuth) und deine deployten Umgebungsvariablen auf die pk_live- und sk_live-Keys umstellen.

• Development-Instanz: pk_test / sk_test Keys, geteilte Clerk-Domain, gelockerte Einstellungen, nur fürs Bauen.
• Produktions-Instanz: pk_live / sk_live Keys, deine eigene Domain, strenge Einstellungen, für echte Nutzer.
• Sie sind separate Welten - Nutzer und Konfiguration übertragen sich nicht automatisch.
• Live gehen = die Produktions-Instanz erstellen, sie konfigurieren, die deployten env vars auf die Live-Keys umstellen.

Google-OAuth-Produktionsdurchgang

Auf der Development-Instanz lässt Clerk dich Google-Login mit geteilten Dev-Credentials aktivieren, sodass du sofort testen kannst. Für Produktion verlangt Google, dass du deine eigenen Google-Credentials und einen verifizierten Consent Screen nutzt, sodass deine Nutzer deinen App-Namen (nicht Clerks) sehen, wenn sie sich einloggen. Das ist der Teil, der Leute stolpern lässt, also hier die Reihenfolge, die funktioniert. Die genauen Button-Beschriftungen in der Google Cloud Console verschieben sich mit der Zeit, also vertrau dem Ablauf und folge Clerks und Googles aktuellen Docs für die präzisen Klicks.

• Erstelle (oder wähle) in der Google Cloud Console ein Projekt für deine App.
• Konfiguriere den OAuth-Consent-Screen: setze den App-Namen, die Support-E-Mail und deine Domain. Füge die Scopes für E-Mail und Profil hinzu. Veröffentliche ihn, damit er nicht im Testmodus festhängt.
• Erstelle OAuth-Credentials vom Typ "OAuth client ID" für eine Web-Anwendung. Google gibt dir eine Client ID und ein Client Secret.
• Füge die autorisierte Redirect-URI hinzu, die Clerk dir in seinen Google-Provider-Einstellungen zeigt - dorthin schickt Google den Nutzer zurück, nachdem er genehmigt hat.
• Füg die Google Client ID und das Client Secret in Clerks Google-Provider-Einstellungen auf deiner Produktions-Instanz ein und aktiviere es.
• Test: logge dich mit Google auf deiner Produktions-Domain ein. Nutzer sollten deinen App-Namen auf dem Google-Consent-Screen sehen, nicht einen generischen.

Ein subtiler Gotcha: die Redirect-URI muss exakt übereinstimmen, inklusive https und keiner Unterschiede beim abschliessenden Slash. Wenn der Login mit einem redirect_uri_mismatch-Fehler scheitert, ist diese Exakt-Übereinstimmung fast immer die Ursache. Kopiere die URI wortwörtlich aus Clerk.

Custom Domain und DNS-Records

Eine Produktions-Clerk-Instanz läuft auf deiner eigenen Domain, sodass Auth zum Beispiel bei accounts.yoursite.com oder clerk.yoursite.com passiert statt unter einer generischen Clerk-URL. Damit das funktioniert, fügst du DNS-Records, die Clerk dir gibt, bei deinem Domain-Anbieter (oder Cloudflare, aus Kurs 1) hinzu. Das sind meist CNAME-Records, die eine Subdomain auf Clerks Server zeigen, sodass Clerk diese Subdomain ausliefern und absichern kann. Du fügst sie hinzu, wartest auf die DNS-Propagation, und Clerk verifiziert sie und stellt die Zertifikate aus. Hier ist die Form dessen, was du hinzufügst - deine echten Werte kommen aus dem Clerk-Dashboard.

; DNS records you add at your provider (example shape - copy real values from Clerk)
; Type   Name (host)              Value (target)
CNAME    clerk                    frontend-api.clerk.services
CNAME    accounts                 accounts.clerk.services
CNAME    clkmail                  mail.xxxxx.clerk.services
CNAME    clk._domainkey           dkim1.xxxxx.clerk.services
CNAME    clk2._domainkey          dkim2.xxxxx.clerk.services

Wenn du DNS über Cloudflare verwaltest, füge diese als DNS-only (graue Wolke, nicht proxied) hinzu, sofern Clerk nichts anderes sagt - das Proxen von Auth-Subdomains kann den TLS-Handshake brechen. Nachdem du die Records gespeichert hast, kann die Verifizierung von ein paar Minuten bis zu ein paar Stunden dauern. Es ist nicht kaputt, DNS ist nur langsam, genau wie du es beim Verbinden einer Domain in Kurs 1 gelernt hast.

Typische Fehler

Die Klassiker: mit pk_test-Keys noch gesetzt in Produktion shippen, sodass echte Nutzer auf deiner Development-Instanz landen; vergessen, den Google-Consent-Screen zu veröffentlichen, sodass er im Testmodus bleibt, in dem sich nur freigeschaltete Accounts einloggen können; ein redirect_uri_mismatch durch eine Redirect-URI, die um einen Slash oder http versus https danebenliegt; die Clerk-DNS-Records durch Cloudflare proxen und Zertifikate brechen; und der tiefste von allen, Auth von Grund auf bauen zu wollen "um zu lernen" und ein Sicherheitsloch zu shippen. Nutze den Dienst, prüf deine Key-Präfixe, kopiere Redirect-URIs wortwörtlich.

Business-ROI

Auth ist reines Abwärtsrisiko, wenn du sie baust, und reine Hebelwirkung, wenn du sie kaufst. Eine geleakte Passwort-Tabelle ist ein juristischer Albtraum unter der DSGVO und den US-Datenschutzgesetzen, plus eine Vertrauenskatastrophe, die ein junges Produkt beenden kann. Clerk entfernt diese ganze Risikokategorie für moderate monatliche Kosten und gibt dir Social Login, das die Registrierungs-Conversion messbar hebt, weil Nutzer es hassen, noch ein Passwort anzulegen. Du shippst den Login an einem Nachmittag statt in zwei Wochen, du schläfst nachts, und dein Registrierungs-Funnel konvertiert besser. Es gibt keine Version der Rechnung, in der selbstgebaute Auth für eine Gründerin gewinnt, die mit Agents baut.

Checkliste

Du bist bereit weiterzugehen, wenn all das in einer echten App stimmt, nicht nur in der Theorie.

• Du kannst OAuth in einem Satz erklären: ein vertrauenswürdiger Provider bürgt für den Nutzer, sodass du sein Passwort nie hältst.
• Clerk ist installiert, Keys sind in .env (gitignored), und die Eingeloggt- / Ausgeloggt-UI funktioniert.
• Du kennst den Unterschied zwischen pk_test und pk_live und zu welcher Umgebung jeder gehört.
• Google OAuth funktioniert auf deiner Produktions-Domain mit deinem eigenen Consent Screen und den richtigen DNS-Records.

Ressourcen

Halt die Clerk-Docs und den Google-Cloud-Console-OAuth-Guide offen, während du das Produktions-Setup machst - beide ändern ihre genaue UI mit der Zeit, und die Docs sind immer aktuell. Die Grundlagen-Seiten dazu, was OAuth ist und was DNS ist, untermauern die zwei kniffligsten Konzepte hier. Als Nächstes gibst du deinen eingeloggten Nutzern etwas zu tun: echte Daten mit Convex.

Deine Aufgabe

Füge Clerk zu einer Test-App auf der Development-Instanz hinzu und bring den Login zum Laufen, aktiviere dann Google-Login. Wenn du eine Domain besitzt, geh einen Schritt weiter: erstelle eine Produktions-Instanz, richte den Google-Consent-Screen und die Credentials ein, füge die DNS-Records hinzu und bestätige, dass ein echter Google-Login auf deiner Domain mit deinem App-Namen auf dem Consent Screen funktioniert. Den Produktionspfad einmal zu gehen nimmt die Angst für jede App, die du danach baust.

Nächste Lektion

Nutzer können sich einloggen. Die nächste Lektion gibt ihnen Daten mit Convex, einer reaktiven, typsicheren Datenbank, in der deine Backend-Logik und deine UI automatisch synchron bleiben, und in der du auch das Soft-Delete-Muster lernst, das dich einen Nutzerfehler rückgängig machen lässt, statt Daten für immer zu verlieren.