Auf die Warteliste
Alle Artikel
OAuthlocal developmentauthenticationcallbacks

OAuth-Callbacks lokal testen: Anleitung

Um OAuth-Callbacks lokal zu testen, brauchst du eine öffentliche HTTPS-URL, die auf deine lokale App zeigt. OAuth-Provider leiten Nutzer nach der Authentifizierung an eine registrierte Callback-URL zurück – und die meisten Provider verlangen HTTPS, das reines localhost ohne Zusatzaufwand nicht bieten kann.

Warum OAuth-Redirect-URIs localhost blockieren

OAuth-2.0-Provider validieren den Parameter redirect_uri gegen eine Whitelist registrierter URLs. Während der Entwicklung könnte dein Callback so aussehen:

https://your-app.portpreview.dev/auth/callback

Ohne Tunnel registrierst du entweder http://localhost:3000/auth/callback (von manchen Providern erlaubt, aber nicht von allen) oder deployst für jede Auth-Änderung auf Staging. Ein Localhost-Tunnel gibt dir einen echten HTTPS-Endpunkt auf deinem Rechner.

Was du zum lokalen OAuth-Testen brauchst

  • OAuth-App-Zugangsdaten (Client-ID und Secret) von deinem Provider.
  • Eine lokale App mit Auth-Routen für Login-Start und Callback-Behandlung.
  • Eine Tunnel-URL, die im Provider-Dashboard als erlaubte Redirect-URI registriert ist.
  • Umgebungsvariablen, die während der Entwicklung auf die Tunnel-URL zeigen.

Schritt für Schritt: OAuth lokal testen mit PortPreview

  1. Starte deine App lokal mit aktivierten OAuth-Routen.
  2. Führe npx portpreview 3000 aus, um eine öffentliche HTTPS-URL zu erhalten.
  3. Füge die Callback-URL (zum Beispiel https://your-app.portpreview.dev/auth/callback) zu den erlaubten Redirect-URIs deines OAuth-Providers hinzu.
  4. Stelle deine lokale Umgebung so ein, dass sie die Tunnel-URL als Basis-URL verwendet.
  5. Starte den OAuth-Flow im Browser und durchlaufe den kompletten Redirect-Zyklus.
  6. Prüfe Token-Austausch, Session-Erstellung und Fehlerbehandlung.

Provider-spezifische Tipps

Google OAuth

Google erlaubt http://localhost für die Entwicklung, aber Tests mit HTTPS-Tunneln validieren produktionsnahes Verhalten inklusive Secure-Cookie-Flags und Mixed-Content-Richtlinien.

GitHub OAuth

GitHub verlangt exakte Übereinstimmung der Redirect-URI. Registriere deine Tunnel-URL in den OAuth-App-Einstellungen und aktualisiere sie bei einem Sitzungswechsel des Tunnels – oder nutze eine stabile Subdomain, falls dein Tunnel-Anbieter das unterstützt.

Auth0 und Enterprise-IdPs

Enterprise-Identity-Provider verlangen oft HTTPS-Callbacks und sperren localhost teilweise komplett. Tunnel sind der Standard-Workaround für lokale SAML- und OIDC-Integrationstests.

Häufige Fehler beim lokalen OAuth-Testen

  • Redirect-URI-Mismatch: Die Callback-URL muss exakt übereinstimmen, inklusive abschließendem Slash und Groß-/Kleinschreibung im Pfad.
  • Veraltete Tunnel-URL: Wenn sich deine Tunnel-URL zwischen Sitzungen ändert, aktualisiere die Provider-Whitelist.
  • State-Parameter nicht validiert: Prüfe den state-Parameter immer, um CSRF-Angriffe zu verhindern, auch in der Entwicklung.
  • Cookie-Domain-Probleme: Session-Cookies bleiben womöglich nicht erhalten, wenn die Domain-Einstellungen mit dem Tunnel-Hostnamen kollidieren.

Sicherheitsaspekte

OAuth-Callbacks tragen Autorisierungscodes, die serverseitig ausgetauscht werden müssen. Lege Client-Secrets niemals im Frontend-Code offen und behandle Tunnel-URLs als temporäre Entwicklungs-Endpunkte – nicht als Produktionsdomains. Lies unseren Leitfaden zur Localhost-Tunnel-Sicherheit für Best Practices.

OAuth-Flows mit dem Team teilen

Wenn Produkt oder QA Social Login testen müssen, teile die Tunnel-URL, statt auf Staging zu deployen. Siehe wie du deinen lokalen Dev-Server teilst für Kollaborations-Workflows.

Tritt der PortPreview-Warteliste bei, um OAuth- und Webhook-Tests aus einem Tunnel zu vereinfachen.

Häufig gestellte Fragen

Kann man OAuth auf localhost testen?
Ja. Die meisten OAuth-Provider erlauben http://localhost-Redirect-URIs, aber viele verlangen HTTPS für produktionsnahes Testen. Ein Localhost-Tunnel liefert eine öffentliche HTTPS-URL, die auf deine lokale App zeigt.
Warum verlangen OAuth-Provider HTTPS-Redirect-URIs?
HTTPS schützt Autorisierungscodes und Tokens während des Redirects im Transit. Viele Provider erzwingen HTTPS, um das Abfangen sensibler Anmeldedaten in unsicheren Netzwerken zu verhindern.
Wie registriere ich eine Tunnel-URL als OAuth-Redirect-URI?
Kopiere deine HTTPS-Tunnel-URL, hänge deinen Callback-Pfad an und füge die vollständige URL zur Liste der erlaubten Redirect-URIs im Entwickler-Dashboard deines Providers hinzu.