Kategoria: Supabase i bazy danych

Supabase: odświeżanie sesji nie działa — diagnostyka przy wygasłym tokenie refresh

Poradnik techniczny · Kacper Bernecki

Ten dokument opisuje szczegółowo przypadek, gdy aplikacja korzystająca z Supabase zaczyna zwracać błędy autoryzacji związane z odświeżaniem sesji: np. 401/403 przy próbie użycia refresh token, logowanie przerywane po krótkim czasie lub brak odświeżania po restarcie serwera. Nie zakładam jednej przyczyny — przygotowałem listę możliwych źródeł problemu (konfiguracja klienta, polityka wygasania po stronie Supabase, wycieki / zmiany kluczy, błędy implementacji cookie/localStorage, problemy z proxy lub CORS). Dla każdego wariantu podaję jak go jednoznacznie przetestować i co poprawić. Instrukcje są praktyczne: wykonasz je w środowisku deweloperskim i produkcyjnym bez ryzyka utraty danych użytkownika.

Jak rozpoznać przyczynę

Sprawdź, czy problem dotyczy tylko refresh tokenów czy też całego flow auth. Użyj konsoli sieci w przeglądarce lub narzędzia curl, aby wywołać endpoint /auth/v1/token z grant_type=refresh_token i obserwuj odpowiedź. Jeśli serwer zwraca 401 z komunikatem o nieważnym tokenie, to najprawdopodobniej token wygasł lub został odwołany po stronie Supabase.

Zweryfikuj konfigurację JWT i polityki wygasania (JWT expiry) w panelu Supabase: jeśli refresh token przyznawany był z krótkim TTL albo opcja 'Enable Refresh Token Rotation' została zmieniona, to istnieje scenariusz, że rotation unieważnił poprzedni token. Również sprawdź, czy klucz serwisowy lub anon/public key nie został zresetowany — to unieważnia sesje.

Nie pomijaj warstwy klienckiej: błędy w zapisie refresh tokena do cookie (HttpOnly, path, domain, secure), lub nadpisywanie localStorage/sessionStorage mogą powodować, że aplikacja wysyła nieaktualny token. Przy aplikacjach serwerowych sprawdź, czy nie używasz jednocześnie wielu instancji SupabaseClient z różnymi ustawieniami.

Rozwiązanie krok po kroku

1. Zaloguj się testowym kontem i zapisz wartości access_token i refresh_token z odpowiedzi /auth/v1/token. Wykonaj żądanie POST /auth/v1/token z grant_type=refresh_token używając curl: curl -X POST 'https://<project>.supabase.co/auth/v1/token' -d 'grant_type=refresh_token&refresh_token=<token>' i zapisz odpowiedź oraz kod HTTP.

2. Jeżeli żądanie zwraca 200, porównaj issuance time i expires_in w odpowiedzi z tym, co robi klient SDK. Upewnij się, że SDK otrzymuje i zachowuje oba tokeny — nie nadpisuj refresh_token nowym access_token. W przypadku SDK JS sprawdź supabase.auth.getSession() i supabase.auth.onAuthStateChange().

3. Jeżeli żądanie zwraca 401 lub 400 z powodem 'invalid_grant' lub 'token_revoked', sprawdź w panelu Supabase: czy nie było rotacji kluczy (Project Settings -> API -> Keys) lub ręcznego wyrejestrowania sesji. Zmiana klucza serwisowego unieważnia sesje — odtwórz sesję po wygenerowaniu nowych kluczy.

4. Sprawdź politykę refresh rotation: jeżeli rotation jest włączone, każdy refresh wypisuje nowy refresh_token i unieważnia poprzedni. Przetestuj przepływ sekwencyjnie: wykonaj 2 kolejne refreshy używając tego samego tokena — drugi powinien zostać odrzucony. Jeśli aplikacja równolegle wywołuje refreshy, dodaj lock/mutex, żeby wykonywać je sekwencyjnie.

5. Przy aplikacjach SSR lub proxy: sprawdź, czy cookie z refresh_token nie jest skracane przez pośrednika (SameSite, path, domain). W narzędziach devtools sprawdź obecność HttpOnly cookie i jego wartość po restarcie serwera. Dla Next.js/Node upewnij się, że przy SSR odczyt i zapis cookie są wykonywane z tego samego domenowego scope.

6. Jeżeli używasz custom JWT lub zewnętrznego provider'a OAuth, upewnij się, że callbacky poprawnie mapują i zapisują refresh_token. W przypadku providerów (Google, GitHub) czasami refresh_token jest wydawany tylko przy pierwszym autoryzowaniu — przetestuj pełny flow OAuth i loguj odebrane tokeny.

7. Jeśli problem występuje nieregularnie, włącz logowanie request/response przy refreshu (tylko w środowisku testowym) i porównaj trace-id/headers. Sprawdź, czy proxy lub CDN nie cache'uje endpointu auth — endpointy autoryzacji nie powinny być cache'owane.

Jak sprawdzić, czy problem zniknął

Test 1: Ręczny refresh przez curl powinien zwracać 200 i nowy access_token oraz refresh_token (jeśli rotation włączone). Powtórz natychmiastowe ponowne użycie starego refresh_token — jeśli rotation on działa, drugie wywołanie powinno zwrócić błąd.

Test 2: Odtwórz scenariusz produkcyjny: wyloguj się i zaloguj ponownie, potem zrestartuj backend/SSR i spróbuj wykonać operację wymagającą odświeżonej sesji. Monitoruj logi serwera: jeśli aplikacja wysyła poprawny aktualny refresh_token, operacja powinna przejść bez 401.

Test 3: Symulacja równoległych refreshy — wywołaj kilka równoczesnych requestów refresh z tym samym tokenem. Jeśli aplikacja nie serializuje refreshy, spodziewaj się, że tylko pierwszy przejdzie; po naprawie wszystkie żądania powinny skorzystać z jednego sekwencyjnego procesu odświeżania.

Czego nie robić

Nie loguj ani nie wystawiaj refresh_tokenów w logach produkcyjnych; loguj jedynie statusy i trace-id. Wycieki tokenów umożliwiają przejęcie sesji.

Nie spodziewaj się, że refresh_token będzie trwały wiecznie — sprawdź TTL i polityki rotacji zamiast zakładać niewyczerpalność.

Unikanie serializacji operacji refresh (równoległe refreshy) to częsta przyczyna nagłego odrzucenia tokenów przy rotation — stosuj mutex/queue.