Aby testować callbacki OAuth lokalnie, potrzebujesz publicznego adresu HTTPS wskazującego na twoją lokalną aplikację. Dostawcy OAuth po uwierzytelnieniu przekierowują użytkownika z powrotem na zarejestrowany adres callbacku — a większość wymaga HTTPS, którego samo localhost nie zapewnia bez dodatkowej konfiguracji.
Dlaczego redirect URI blokują localhost
Dostawcy OAuth 2.0 walidują parametr redirect_uri względem białej listy zarejestrowanych adresów. Podczas developmentu twój callback może wyglądać tak:
https://your-app.portpreview.dev/auth/callbackBez tunelu albo rejestrujesz http://localhost:3000/auth/callback (dozwolone u niektórych dostawców, ale nie u wszystkich), albo wdrażasz na staging przy każdej zmianie auth. Tunel do localhost daje prawdziwy endpoint HTTPS na twojej maszynie.
Czego potrzebujesz do lokalnego testu OAuth
- Danych uwierzytelniających aplikacji OAuth (client ID i secret) od dostawcy.
- Lokalnej aplikacji z trasami auth do rozpoczęcia logowania i obsługi callbacku.
- Adresu tunelu zarejestrowanego jako dozwolony redirect URI w panelu dostawcy.
- Zmiennych środowiskowych wskazujących na adres tunelu podczas developmentu.
Krok po kroku: lokalny test OAuth z PortPreview
- Uruchom aplikację lokalnie z włączonymi trasami OAuth.
- Wykonaj
npx portpreview 3000, aby uzyskać publiczny adres HTTPS. - Dodaj adres callbacku (na przykład
https://your-app.portpreview.dev/auth/callback) do dozwolonych redirect URI u twojego dostawcy OAuth. - Zaktualizuj lokalne środowisko, aby używało adresu tunelu jako bazowego URL.
- Rozpocznij flow OAuth w przeglądarce i przejdź pełny cykl przekierowań.
- Zweryfikuj wymianę tokenów, utworzenie sesji i obsługę błędów.
Wskazówki dla poszczególnych dostawców
Google OAuth
Google dopuszcza http://localhost do developmentu, ale testowanie z tunelami HTTPS waliduje zachowanie zbliżone do produkcji, w tym flagi secure cookie i polityki mixed content.
GitHub OAuth
GitHub wymaga dokładnego dopasowania redirect URI. Zarejestruj adres tunelu w ustawieniach aplikacji OAuth i aktualizuj go przy zmianie sesji tunelu lub użyj stabilnej subdomeny, jeśli twój dostawca tunelu ją obsługuje.
Auth0 i firmowe IdP
Firmowi dostawcy tożsamości często wymagają callbacków HTTPS, a czasem całkowicie blokują localhost. Tunele to standardowe obejście dla lokalnych testów integracji SAML i OIDC.
Częste błędy w lokalnym teście OAuth
- Niedopasowany redirect URI: adres callbacku musi pasować dokładnie, łącznie z końcowymi ukośnikami i wielkością liter w ścieżce.
- Nieaktualny adres tunelu: jeśli adres tunelu zmienia się między sesjami, zaktualizuj białą listę dostawcy.
- Niewalidowany parametr state: zawsze weryfikuj parametr
state, aby zapobiec atakom CSRF, nawet w developmencie. - Problemy z domeną cookie: ciasteczka sesji mogą nie być zachowywane, jeśli ustawienia domeny kolidują z nazwą hosta tunelu.
Kwestie bezpieczeństwa
Callbacki OAuth przenoszą kody autoryzacji, które muszą być wymieniane po stronie serwera. Nigdy nie ujawniaj client secretów w kodzie frontendu i traktuj adresy tuneli jako tymczasowe endpointy developerskie, a nie domeny produkcyjne. Przeczytaj nasz przewodnik o bezpieczeństwie tuneli do localhost, aby poznać dobre praktyki.
Udostępnianie flow OAuth zespołowi
Gdy product lub QA muszą przetestować logowanie społecznościowe, udostępnij adres tunelu zamiast wdrażać na staging. Zobacz jak udostępnić lokalny serwer deweloperski, aby poznać workflow współpracy.
Dołącz do listy oczekujących PortPreview, aby usprawnić testowanie OAuth i webhooków z jednego tunelu.