Eksploracja grantów OIDC: zrozumienie i diagnozowanie błędu "invalid_grant"

Kontekst#

W naszej społeczności często pojawia się powtarzające sie pytanie od naszych użytkowników: O co chodzi z błędem "invalid_grant" w Logto? Podobnie jak #503

Jest to powszechne wyzwanie i przeszkoda dla niektórych z naszych użytkowników podczas integracji Logto z ich własnymi aplikacjami. Jednak przyczyny tego błędu różnią się od przypadku do przypadku i czasem trudno je wyjaśnić przy ograniczonym kontekście dostarczonym. Dlatego zrozumienie dokładnej koncepcji OIDC i nauczenie się sposobu radzenia sobie z problemem jest kluczowe dla wszystkich.

Teraz spójrzmy na podstawy grantów OIDC.

Wyjaśnienie grantów OIDC#

Jak wprowadziliśmy we wcześniejszym wpisie na blogu, OpenID Connect (OIDC) to protokół oparty na OAuth 2.0.

W kontekście OIDC lub OAuth2, grant to zestaw uprawnień przyznanych przez właściciela zasobu (zazwyczaj użytkownika) do aplikacji klienckiej. Granty są niezbędne dla aplikacji klienta do dostępu do informacji o tożsamości użytkownika i innych chronionych zasobów. OIDC definiuje kilka typów grantów, każdy przystosowany do innego scenariusza i sposobu, w jaki aplikacja otrzymuje token dostępu.

Przygotowaliśmy analogię, która pomoże Ci lepiej zrozumieć granty OIDC.

Wyobraź sobie, że podróżujesz do różnych krajów, a każdy z nich wymaga pieczęci wizowej do wejścia. W tym scenariuszu twój paszport pełni rolę konta użytkownika, zawierającego Twoje dane osobowe. Granty OIDC są jak sposoby, w jaki ubiegasz się o wizę do wejścia do kraju. Kiedy wiza jest wydana, faktycznie otrzymujesz "token" do wejścia do tego kraju.

Podobnie, korzystając z aplikacji, żądanie grantu to czynność, w której żądasz od serwera autoryzacji udzielenia Ci dostępu. Serwer autoryzacji sprawdza Twoją tożsamość i wydaje Ci "wizę" (token dostępu) do zalogowania się do aplikacji.

Najczęściej używane typy grantów OIDC:#

1. Grant kodu autoryzacji: Jest to najczęściej stosowany typ grantu w OIDC. Polega na przekierowaniu użytkownika do serwera autoryzacyjnego, uzyskanie kodu autoryzacji, przekierowanie z powrotem do aplikacji i wymianie kodu na token dostępu. Pomyśl o tym jako o standardowym procesie ubiegania się o wizę w ambasadzie przed wejściem do obcego kraju.
2. Grant tokena odświeżenia: W OIDC, ten typ grantu umożliwia aplikacji klienckiej uzyskanie nowego tokena dostępu za pomocą wcześniej wydanego tokena odświeżania. Jest często używany do przedłużenia sesji użytkownika bez konieczności ponownego wpisywania ich poświadczeń. Wyobraź sobie, że twoja wiza jest z magiczną kartą, która pozwala na przedłużenie pobytu w obcym kraju bez konieczności ponownego przechodzenia przez odprawę celną.
3. Bezwzględny Grant: Ten typ grantu jest używany dla przestarzałych aplikacji działających w przeglądarce i jest mniej bezpieczny niż Grant Kodu Autoryzacyjnego. Zwraca token dostępu bezpośrednio do aplikacji klienckiej. Działa to jak "wiza na przyjazd", gdyż nie wymaga wcześniejszego ubiegania się o wizę.
4. Grant poświadczeń klienta: Przystosowany do komunikacji serwer-serwer, ten typ grantu pozwala aplikacji klienckiej na bezpośrednie uwierzytelnianie się przy serwerze autoryzacji za pomocą jego poświadczeń (identyfikatora klienta i sekretu klienta). To jest jak specjalny agent pokazujący specjalną odznakę służbową do wejścia do kraju bez procedury ubiegania się o wizę.

Model obiektowy grantu:#

W Logto, grant jest zachowywany w bazie danych jako obiekt encji, zawierający informacje takie jak ID konta użytkownika, ID aplikacji, powiązane zasoby OIDC i zakresy, czas wygaśnięcia i więcej. Każdy token odświeżania i token dostępu jest powiązany z określonym obiektem grantu.

Żądania grantu:#

Żądania HTTP wysyłane do serwera autoryzacji przez API. Aplikacja kliencka może wysyłać żądania grantu do punktu końcowego tokena OIDC w różnych celach, w tym ubiegać się o nowy grant (np. logowanie i uzyskiwanie tokenów odświeżania i dostępu), aktualizować szczegóły grantu (np. wymieniać token odświeżania na nowy token dostępu) lub unieważniać grant (np. unieważniać wszystkie tokeny wydane zalogowanym użytkownikom i kończyć ich dostęp).

Typowe żądanie grantu kodu autoryzacji wygląda tak:

Rozumienie błędu "invalid_grant"#

Napotkanie błędu invalid_grant w OIDC zazwyczaj oznacza, że typ grantu lub dane związane z żądaniem grantu są nieprawidłowe lub nieobsługiwane. Oto kilka najczęstszych przyczyn tego błędu:

1. Nieprawidłowy typ grantu: użycie niewłaściwego typu grantu dla Twojej aplikacji może skutkować błędem invalid_grant. Upewnij się, że używasz odpowiedniego typu grantu, wykorzystując SDK Logto.
2. Niezgodne adresy URI przekierowania: podczas wymiany kodu autoryzacji na tokeny, adres URI przekierowania używany w żądaniu musi być zgodny z tym używanym podczas początkowego żądania autoryzacji. Niedopasowanie może skutkować błędem invalid_grant.
3. Wygasły lub zużyty kod autoryzacji: w procesie logowania z kodem autoryzacji, kod autoryzacji ma ograniczony czas życia i zostaje oznaczony jako "zużyty" po uzyskaniu tokenów. Próba wymiany wygasłego lub zużytego kodu na token dostępu skutkuje błędem invalid_grant.
4. Wygasły lub obrócony token odświeżania: podczas wymiany tokena odświeżania na token dostępu, błąd invalid_grant występuje, jeśli token odświeżania jest już wygasły. Dodatkowo, dla zwiększenia bezpieczeństwa, Logto domyślnie aktywuje obrót tokenów odświeżenia. Żądanie punktu końcowego tokena z tym samym tokenem odświeżenia po raz drugi jest uważane za użycie "obróconego" tokena odświeżania i zostanie odrzucone.
5. Brakujące obowiązkowe dane lub nagłówki żądań: podczas tworzenia żądania grantu, obowiązkowe parametry i nagłówki żądań muszą być dostarczone dla danego typu grantu. Na przykład, ID klienta musi być dostarczone we wszystkich żądaniach grantu, a ID klienta i sekret klienta muszą być dostarczone dla Grantu Poświadczeń Klienta. Ten ryzyko można także zminimalizować, korzystając z SDK Logto.
6. Inne przyczyny: Ten błąd może wystąpić również z powodu błędów takich jak niedopasowanie poświadczeń klienta, wygaśnięcie grantu lub nieznalezienie go, nieznalezienie tokena odświeżania itp.

Diagnoza#

Kilka wskazówek, jak skutecznie radzić sobie z błędem "invalid_grant":

1. Zawsze używaj klienta SDK Logto do integracji Logto z Twoją aplikacją, aby upewnić się, że żądanie grantu jest wysyłane do odpowiedniego punktu końcowego i z poprawnymi danymi.
2. Sprawdź, czy poświadczenia Twojej aplikacji i adresy URI przekierowań są zgodne z konfiguracjami w konsoli administracyjnej.
3. Unikaj wysyłania nadmiarowych żądań, szczególnie dla SPA, takich jak React i Vue, gdzie komponenty strony mogą być ponownie renderowane z powodu zmian zależności. Upewnij się, że funkcje używane do wymiany kodów lub tokenów odświeżania na tokeny dostępu nie są uruchamiane wielokrotnie z tymi samymi parametrami żądań. Jest to powszechny błąd popełniany przez niektórych z naszych użytkowników. Zazwyczaj, jeśli widzisz wiele żądań "token" w swojej konsoli debugowania, pierwsze jest pomyślne, ale kolejne wszystkie nie powiodły się, sprawdź ich parametry żądań, aby zobaczyć, czy używają tego samego "kodu" lub "tokena odświeżania". Pamiętaj, że możesz używać kodu i tokena odświeżania TYLKO RAZ w żądaniach grantu.
4. Sprawdź czasy wygaśnięcia. Na przykład, jeśli Twój token odświeżenia wygasł (domyślnie po 14 dniach) i występuje błąd invalid_grant, powinieneś odpowiednio na to zareagować, ponownie inicjując proces logowania użytkownika. Jeśli korzystasz z SDK Logto, możesz ponownie wywołać funkcję signIn(), aby przekierować swoich użytkowników z powrotem na stronę logowania.
5. Monitoruj dzienniki audytu. Przejdź do Konsoli Administratora → Dzienniki Audytu, znajdź dziennik błędów związany z incydentem i sprawdź szczegółowy ślad stosu błędów. Zazwyczaj, za błędem invalid_grant kryje się bardziej szczegółowy powód, taki jak "Nie znaleziono grantu" lub "Token odświeżania wygasł".

Końcówka#

Błąd invalid_grant może być wyzwaniem i problemem dla początkujących, ale z klarownym zrozumieniem grantów OIDC i uwagą na szczegóły, możesz samodzielnie zidentyfikować i rozwiązać problem. Dołącz do naszych dyskusji na Discordzie lub GitHubie i daj nam znać, czy ten wpis pomógł Ci rozwiać zamętanie i zidentyfikować problemy, które napotykasz. Zespół deweloperski Logto jest zawsze chętny do pomocy.

Razem budujmy bezproblemowe i bezpieczne doświadczenia autoryzacyjne dla Twoich ukochanych aplikacji.