Skip to Content

Tokeny

Do czego służą tokeny ID, access i refresh, kto który weryfikuje, jak długo żyją oraz jak działają rotacja i bezpieczne przechowywanie.

Pojedyncze logowanie może wytworzyć trzy różne tokeny, a większość problemów integracyjnych bierze się z pomylenia tego, do czego służy każdy z nich. Ta strona jest tabelą do wyszukiwania: przeznaczenie, audience, czas życia i zasady obchodzenia się z każdym typem tokenu.

Trzy tokeny

TokenAdresatDo czego służyKto go weryfikuje
ID tokenAplikacja (jej client ID jest audience)Potwierdza, kto się zalogował, i niesie claimy profilowe (sub, name, email, ...).Aplikacja, zwykle przez swoją bibliotekę OIDC.
Access tokenAPI (jego identyfikator jest audience)Autoryzuje wywołania tego API i niesie przyznane scope'y.API, przy każdym żądaniu; zobacz Zabezpieczanie API.
Refresh tokenSama platformaPozwala aplikacji odnowić później swój access token bez odsyłania użytkownika na stronę logowania.Platforma, na punkcie końcowym tokenu.

Najczęstszym błędem jest wysłanie ID tokenu do API. ID token uwierzytelnia użytkownika wobec aplikacji, a jego audience to client ID aplikacji, więc poprawnie zaimplementowane API go odrzuci. Do API wysyłaj access token i traktuj go wewnątrz klienta jako nieprzejrzysty: jego zawartość jest kontraktem między platformą a API, a nie aplikacją.

Formaty access tokenów

  • Dla zarejestrowanego API (klient przekazał identyfikator API jako resource indicator): podpisany JWT z identyfikatorem API w aud, przyznanymi scope'ami w scope i wywołującym w sub. API weryfikuje go offline względem opublikowanych kluczy platformy. Przy włączonym RBAC niesie dodatkowo claimy permissions / roles.
  • Bez docelowego API: token nieprzejrzysty, użyteczny wyłącznie na punkcie końcowym UserInfo platformy. Tokeny nieprzejrzyste (oraz refresh tokeny) można sprawdzić na standardowym punkcie końcowym token introspection i unieważnić na punkcie końcowym revocation; oba są wymienione w dokumencie discovery. Klient może introspekcjonować własne tokeny; tokeny innych klientów może sprawdzać tylko aplikacja utworzona w konsoli administracyjnej z client secret lub kluczem (serwer zasobów), a nie aplikacja zarejestrowana dynamicznie.

Czasy życia

Token / artefaktCzas życiaGdzie konfigurowane
Authorization code1 minuta, jednorazowe użycieStały
Access token dla APIDomyślnie 1 dzień (2 godziny w przepływach implicit)Dla każdego API, na jego karcie ustawień; zobacz API
Access token bez docelowego API (UserInfo)1 godzinaStały
Token machine-to-machine bez docelowego API10 minutStały
ID tokenDomyślnie 1 godzinaDla każdej aplikacji; zobacz Aplikacje
Refresh token14 dni, przedłużane rotacją łącznie do 1 rokuStały; zobacz niżej
Device code10 minutStały
Sesja logowania jednokrotnegoLimit bezczynności i limit bezwzględnyW całej instancji w sekcji Ustawienia → Logowanie, z możliwością nadpisania dla każdego katalogu; zobacz Ustawienia logowania

Refresh tokeny

Kiedy jest wystawiany. Aplikacja musi mieć włączony typ grantu refresh token. Aplikacje first-party (bez ekranu zgody) otrzymują go wtedy automatycznie; aplikacje z włączoną opcją Wymagaj zgody użytkownika otrzymują go tylko wtedy, gdy użytkownik przyznał scope offline_access.

Rotacja. Refresh tokeny podlegają rotacji, zamiast żyć wiecznie:

  • Klient public (aplikacja jednostronicowa lub natywna, bez client secret) otrzymuje zastępczy refresh token przy każdym użyciu. W klientach przeglądarkowych token zastępczy zachowuje pozostały czas życia, więc rotacja go nie wydłuża.
  • Klient confidential zachowuje swój refresh token, dopóki nie upłynie około 70% jego czasu życia; kolejne użycie wystawia wtedy świeży token na 14 dni.
  • Niezależnie od sposobu rotacji łańcuch refresh tokenów kończy się najpóźniej rok po pierwotnym logowaniu; potem użytkownik musi zalogować się ponownie.

Wyrotowany (użyty) refresh token jest nieważny; jeśli Twój klient utrwala tokeny, zapisuj zawsze najnowszy z każdej odpowiedzi.

Unieważnianie. Aplikacja może z wyprzedzeniem unieważnić refresh token na punkcie końcowym revocation (wymienionym w dokumencie discovery), co jest dobrą praktyką podczas własnego wylogowania. Użytkownicy mogą kończyć swoje sesje w portalu konta („wyloguj się wszędzie"), a tokeny związane z sesją kończą się razem z nią; zobacz następną sekcję.

Tokeny a wylogowanie

Wylogowanie kończy sesję SSO platformy, ale tokeny rządzą się własnymi regułami:

  • Tokeny wystawione bez offline_access są związane z sesją. Tokeny nieprzejrzyste przestają działać w chwili zakończenia sesji.
  • Access tokenu w formacie JWT nie da się odwołać: API weryfikują go offline, więc pozostaje technicznie użyteczny aż do wygaśnięcia, nawet po wylogowaniu. Jeśli to okno czasowe ma znaczenie dla danego API, skróć jego czas życia access tokenu, zamiast polegać na wylogowaniu.
  • Refresh tokeny uzyskane ze scope'em offline_access przetrwają wylogowanie, i tak ma być (dokładnie to oznacza dostęp offline). Kończą się, gdy wygasną, osiągną roczny limit albo zostaną unieważnione.
  • Aplikacje mogą zostać poinformowane o wylogowaniu przez back-channel logout; zobacz Czasy życia tokenów i wylogowanie. Zależności między sesją platformy, sesjami aplikacji i sesją nadrzędnego dostawcy tożsamości opisuje Cykl życia użytkownika: sesje.

Przechowywanie tokenów

  • Przed skryptami działającymi na stronie (cross-site scripting): token w localStorage albo sessionStorage może odczytać każdy wstrzyknięty skrypt. Aplikacje przeglądarkowe trzymają tokeny wyłącznie w pamięci i pokrywają krótki czas życia access tokenu rotacją refresh tokenów.
  • Przed innym oprogramowaniem na urządzeniu: token w zwykłym pliku albo magazynie ustawień jest oddalony o jedno odczytanie pliku. Aplikacje natywne korzystają z chronionego magazynu systemu operacyjnego (Keychain, Keystore, credential locker).
  • Przed przeglądarką jako całością: aplikacja serwerowa nigdy nie potrzebuje przeglądarki do przechowywania tokenu. Trzymaj tokeny na serwerze, powiązane z własnym ciasteczkiem sesji.
  • Przed wyciekami w transmisji i w logach: wysyłaj tokeny wyłącznie przez TLS w nagłówku Authorization, nigdy w adresach URL (trafiają wtedy do logów proxy i serwerów) i nigdy nie zapisuj ich samodzielnie w logach.

Powiązane tematy

Na tej stronie