Authentifizierung & Sicherheit

Uebersicht

Das Authentifizierungs- und Sicherheitssystem in TanStack Ship bietet eine umfassende, produktionsreife Loesung fuer die Benutzeridentitaetsverwaltung. Es unterstuetzt mehrere Authentifizierungsmethoden, darunter Google OAuth 2.0 Single-Sign-On und traditionellen E-Mail/Passwort-Login, alles aufgebaut auf einer Grundlage sicherer Sitzungsverwaltung mit serverseitiger Token-Validierung.

Die Zugriffskontrolle wird auf jeder Ebene der Anwendung durchgesetzt — von Routenguards in TanStack Router (einer typsicheren Weiterentwicklung von React Router) bis hin zu API-Ebene-Autorisierungspruefungen. Das RBAC-System (Rollenbasierte Zugriffskontrolle) stellt sicher, dass Benutzer nur auf Ressourcen zugreifen, die ihrer Rolle entsprechen, waehrend Administratoren die benoetigten Werkzeuge zur effektiven Plattformverwaltung haben.

Als Teil der TanStack Ship Plattform integriert sich das Authentifizierungsmodul in das Abrechnungssystem fuer abonnementgesteuerte Zugriffe, das Einladungssystem fuer Teambildung und das Admin-Dashboard fuer Benutzerverwaltung.

Authentifizierungsablauf

Das Authentifizierungssystem unterstuetzt mehrere Anmeldemethoden, die alle in einer einheitlichen Sitzungsverwaltungsebene zusammenlaufen:

Design-Philosophie

Das Authentifizierungssystem folgt drei Kernprinzipien der Sicherheit:

• Verteidigung in der Tiefe — Die Zugriffskontrolle wird auf mehreren unabhaengigen Ebenen durchgesetzt: Routenguards, API-Autorisierung und UI-Ebene. Selbst wenn eine Ebene kompromittiert wird, bleiben die anderen wirksam. Im Gegensatz zu All-in-One-Auth-Anbietern wie Auth0 oder Clerk, die die Authentifizierung an Drittanbieter-Domaenen auslagern, bleibt bei unserem Ansatz die Sitzungsvalidierung vollstaendig serverseitig innerhalb Ihrer Infrastruktur, wodurch die Abhaengigkeit von externen Diensten fuer kritische Sicherheitsentscheidungen entfaellt.
• Minimale Rechte — Benutzer erhalten die minimalen Berechtigungen, die fuer ihre Rolle erforderlich sind. Das RBAC-System stellt sicher, dass Standardbenutzer keinen Zugriff auf Admin-Funktionen haben, und API-Endpunkte validieren Berechtigungen vor jeder Operation.
• Server-Side-Trust — Die gesamte Sitzungsvalidierung erfolgt serverseitig. JWT-Tokens werden mit einem Servergeheimnis signiert, in HTTP-Only-Cookies gespeichert und bei jeder geschuetzten Anfrage ueberprueft.

Kernfunktionen

Google OAuth 2.0 Integration

Benutzer koennen sich mit ihrem Google-Konto ueber den OAuth 2.0 Autorisierungscode-Ablauf anmelden. Die Implementierung folgt den von Google empfohlenen Sicherheitspraktiken, einschliesslich CSRF-Schutz durch State-Parameter und PKCE (Proof Key for Code Exchange) fuer erhoehte Sicherheit.

OAuth-Ablauf:

1. Benutzer klickt auf "Mit Google anmelden" auf der /login-Seite
2. Anwendung leitet zum Google OAuth-Zustimmungsbildschirm weiter mit konfigurierten Bereichen (openid, email, profile)
3. Benutzer erteilt Berechtigung auf Googles Domain
4. Autorisierungs-Callback bei /api/auth/callback tauscht den Code gegen Tokens aus
5. Server erstellt oder aktualisiert den Benutzereintrag und stellt ein Sitzungstoken aus
6. Benutzer wird zum authentifizierten Dashboard weitergeleitet

Der OAuth-Callback-Endpunkt validiert den State-Parameter, um CSRF-Angriffe zu verhindern, und behandelt sowohl die Erstellung neuer Benutzer als auch die Anmeldung vorhandener Benutzer nahtlos.

E-Mail- & Passwort-Authentifizierung

Traditionelle E-Mail/Passwort-Authentifizierung mit Sicherheit auf Unternehmensniveau:

• Passwort-Hashing — Alle Passwoerter werden mit bcrypt und einem konfigurierbaren Kostenfaktor gehasht
• Registrierungsablauf — Neue Benutzer registrieren sich mit E-Mail, Passwort und optionalem Einladungscode
• E-Mail-Verifizierung — Verifizierte E-Mail-Adressen sind fuer den Zugriff auf geschuetzte Funktionen erforderlich
• Passwort-Zuruecksetzen — Sicherer tokenbasierter Passwort-Zuruecksetzungsablauf mit Ablaufzeit
• Eingabevalidierung — Serverseitige E-Mail-Format- und Passwortstaerkepruefung mit Zod-Schemas

Das Authentifizierungssystem speichert zu keinem Zeitpunkt Klartext-Passwoerter. Die gesamte Registrierungs- und Login-Pipeline folgt den OWASP-Authentifizierungs-Best-Practices.

Sitzungsverwaltung

Sitzungen werden durch serverseitige JWT-Tokens verwaltet, die als HTTP-Only-Cookies gespeichert sind:

• Sichere Tokens — JWTs, signiert mit einem serverseitigen Geheimnis, enthalten Benutzer-ID, Rolle und Ablaufansprueche
• Server-Validierung — Jede geschuetzte Route ueberprueft die Gueltigkeit und den Ablauf des Tokens auf dem Server
• Konfigurierbarer Ablauf — Sitzungs-TTL ist ueber Umgebungsvariablen konfigurierbar
• Abmeldung — Token-Sperrung bei Abmeldung loescht die serverseitige Sitzung

Die Sitzungs-Middleware ist als TanStack Router-Loader-Guard implementiert, der sicherstellt, dass nicht authentifizierte Benutzer vor dem Rendern geschuetzter Inhalte zur Login-Seite weitergeleitet werden.

Rollenbasierte Zugriffskontrolle (RBAC)

Zwei integrierte Rollen bieten klare Zugriffsgrenzen:

• Benutzer — Standardzugriff auf Dashboard, Abrechnungsverwaltung, Profileinstellungen und Funktionsnutzung
• Administrator — Vollstaendiger Zugriff auf Admin-Panels, Benutzerverwaltung, Abrechnungsadministration, Systemkonfiguration und Analyse-Dashboards

Die Zugriffskontrolle wird auf mehreren Ebenen durchgesetzt:

• Routenebene — TanStack Router-Loader ueberpruefen die Benutzerrolle vor dem Rendern geschuetzter Seiten
• API-Ebene — Serverfunktionen validieren Berechtigungen vor der Ausfuehrung von Operationen
• UI-Ebene — Komponenten rendern Admin-Menues und Aktionen bedingt

Das RBAC-System ist erweiterbar — zusaetzliche Rollen koennen ueber das Datenbankschema und Berechtigungs-Middleware hinzugefuegt werden.

Kontosicherheit & Profilverwaltung

Benutzer koennen ihre Sicherheitseinstellungen ueber das Dashboard verwalten:

• Profilinformationen aktualisieren (Name, Avatar, Kontakt-E-Mail)
• Passwortaenderung mit aktueller Passwortbestaetigung
• Verwaltung verbundener Google-Konten
• Kontoloeschung mit Bestaetigungsablauf

Beispiel — Login-Komponente mit Google OAuth:

import { useNavigate } from '@tanstack/react-router'

export function LoginPage() {
  const navigate = useNavigate()

  const handleGoogleLogin = () => {
    window.location.href = '/api/auth/google'
  }

  const handleEmailLogin = async (e: React.FormEvent) => {
    e.preventDefault()
    const form = new FormData(e.target as HTMLFormElement)
    const res = await fetch('/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: form.get('email'),
        password: form.get('password'),
      }),
    })
    if (res.ok) navigate({ to: '/dashboard' })
  }

  return (
    <div>
      <button onClick={handleGoogleLogin}>Mit Google anmelden</button>
      <hr />
      <form onSubmit={handleEmailLogin}>
        <input name="email" type="email" placeholder="E-Mail" required />
        <input name="password" type="password" placeholder="Passwort" required />
        <button type="submit">Anmelden</button>
      </form>
    </div>
  )
}

Best Practices

Passwortrichtlinien-Durchsetzung

Implementieren Sie eine starke Passwortrichtlinie, die eine Mindestlaenge (12+ Zeichen), gemischte Gross-/Kleinschreibung, Zahlen und Sonderzeichen erfordert. Verwenden Sie Zod-Validierungsschemas sowohl auf Client- als auch auf Serverseite, um waehrend der Registrierung sofortiges Feedback zu geben.

OAuth-State-Parameter-Validierung

Validieren Sie immer den state-Parameter in OAuth-Callbacks, um CSRF-Angriffe zu verhindern. Das System generiert fuer jede Authentifizierungsanfrage einen eindeutigen State-Wert und ueberprueft dessen Uebereinstimmung beim Callback.

Sitzungsrotation bei Berechtigungserweiterung

Stellen Sie ein neues Sitzungstoken aus, wenn sich die Rolle eines Benutzers aendert oder sensible Operationen durchgefuehrt werden (Passwortaenderung, E-Mail-Aktualisierung). Dies begrenzt das Missbrauchsfenster fuer gestohlene Tokens.

Ratenbegrenzung bei Auth-Endpunkten

Wenden Sie Ratenbegrenzung auf Login-, Registrierungs- und Passwort-Zuruecksetzungs-Endpunkte an, um Brute-Force-Angriffe zu verhindern. Die Middleware des Systems kann fehlgeschlagene Versuche pro IP-Adresse verfolgen und uebermaessige Anfragen voruebergehend blockieren.

Haeufig gestellte Fragen

Wie richte ich Google OAuth fuer meine Domain ein? Erstellen Sie ein Projekt in der Google Cloud Console, konfigurieren Sie den OAuth-Zustimmungsbildschirm, erstellen Sie Anmeldedaten mit der Callback-URL Ihrer Domain (https://yourdomain.com/api/auth/callback) und setzen Sie die Client-ID und das Geheimnis in Ihrer .dev.vars-Datei.

Kann ich weitere OAuth-Anbieter wie GitHub oder Microsoft hinzufuegen? Ja. Die Authentifizierungsarchitektur unterstuetzt mehrere OAuth-Anbieter. Jeder Anbieter benoetigt seinen eigenen Callback-Endpunkt und seine Anmeldedatenkonfiguration. Das Benutzerdatenbankschema unterstuetzt mehrere Anbieter-IDs pro Benutzerkonto.

Wie lange sind Sitzungen gueltig? Die Sitzungs-TTL ist ueber die Umgebungsvariable JWT_EXPIRES_IN konfigurierbar. Der Standardwert betraegt 7 Tage. Sitzungen koennen bei jeder authentifizierten Anforderung verlaengert werden, um aktive Benutzer angemeldet zu halten.

Was passiert, wenn ein JWT ablaeuft? Die Sitzungs-Middleware erkennt abgelaufene Tokens und leitet den Benutzer mit einer Meldung zur abgelaufenen Sitzung zur Login-Seite weiter. Der Benutzer kann sich erneut authentifizieren, um ein neues Sitzungstoken zu erhalten.

Kann ich den E-Mail/Passwort-Login deaktivieren und nur OAuth verwenden? Ja. Das Authentifizierungssystem ist modular. Sie koennen den E-Mail/Passwort-Login deaktivieren, indem Sie die entsprechenden Routen-Handler und UI-Komponenten entfernen. Die Login-Seite passt sich automatisch an, um nur konfigurierte Authentifizierungsmethoden anzuzeigen.

Wie werden Benutzerrollen anfangs zugewiesen? Neue Benutzer erhalten standardmaessig die Rolle user. Admin-Erhoehung kann ueber die Datenbank, ein Seed-Skript fuer die anfaengliche Superadmin-Erstellung oder ueber eine Admin-Verwaltungsoberflaeche erfolgen.

Wie funktioniert die einladungsbasierte Registrierung? Vorhandene Benutzer koennen ueber das Einladungssystem Einladungscodes generieren. Neue Benutzer koennen sich mit einem Einladungscode registrieren, der sie mit dem einladenden Benutzer verknuepft und optional eine vordefinierte Rolle zuweist.

Konfiguration

Konfigurieren Sie die folgenden Umgebungsvariablen in .dev.vars:

GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...
JWT_SECRET=your-secure-secret-key-min-32-chars
JWT_EXPIRES_IN=7d

Erstellen Sie fuer Google OAuth ein Projekt in der Google Cloud Console, konfigurieren Sie den OAuth-Zustimmungsbildschirm und fuegen Sie Ihre Callback-URL zu den autorisierten Weiterleitungs-URIs hinzu.

Integrationspunkte

Das Authentifizierungssystem integriert sich mit den folgenden TanStack Ship Plattformmodulen:

• Abrechnung — Der Abonnementstatus ist mit dem Benutzerkonto verknuepft; der Zugriff auf Premium-Funktionen ist durch ein aktives Abonnement beschraenkt
• Einladungssystem — Neue Benutzer koennen per E-Mail mit Einladungscodes eingeladen werden; eingeladene Benutzer werden automatisch mit dem Einladenden verknuepft
• Admin-Dashboard — Die Admin-Rolle gewaehrt Zugriff auf Benutzerverwaltung, Systemkonfiguration und Analysen
• Dashboard-Routen — Die Sitzungs-Middleware schuetzt alle Dashboard-Routen und leitet nicht authentifizierte Benutzer zur Login-Seite weiter
• Kampagnen-Angebote — Die Benutzerauthentifizierung ist erforderlich, um Werbeaktionen zu beanspruchen und Rabattcodes anzuwenden
• Blog-CMS — Autoren und Editoren sind authentifizierte Benutzer mit Inhaltsverwaltungsberechtigungen