# 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 [#the-three-tokens]

| Token | Adresat | Do czego służy | Kto go weryfikuje |
|---|---|---|---|
| **ID token** | Aplikacja (jej client ID jest audience) | Potwierdza, *kto się zalogował*, i niesie claimy profilowe (`sub`, `name`, `email`, ...). | Aplikacja, zwykle przez swoją bibliotekę OIDC. |
| **Access token** | API (jego identyfikator jest audience) | Autoryzuje *wywołania tego API* i niesie przyznane scope'y. | API, przy każdym żądaniu; zobacz [Zabezpieczanie API](https://dts-identity.com/pl/docs/quickstarts/protect-an-api.md). |
| **Refresh token** | Sama platforma | Pozwala 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 [#access-token-formats]

- **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](https://dts-identity.com/pl/docs/integrations/apis.md#role-based-access-control) 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 [#lifetimes]

| Token / artefakt | Czas życia | Gdzie konfigurowane |
|---|---|---|
| Authorization code | 1 minuta, jednorazowe użycie | Stały |
| Access token dla API | Domyślnie 1 dzień (2 godziny w przepływach implicit) | Dla każdego API, na jego karcie ustawień; zobacz [API](https://dts-identity.com/pl/docs/integrations/apis.md) |
| Access token bez docelowego API (UserInfo) | 1 godzina | Stały |
| Token machine-to-machine bez docelowego API | 10 minut | Stały |
| ID token | Domyślnie 1 godzina | Dla każdej aplikacji; zobacz [Aplikacje](https://dts-identity.com/pl/docs/integrations/applications.md#token-lifetimes-and-logout) |
| Refresh token | 14 dni, przedłużane rotacją łącznie do 1 roku | Stały; zobacz niżej |
| Device code | 10 minut | Stały |
| Sesja logowania jednokrotnego | Limit bezczynności i limit bezwzględny | W całej instancji w sekcji **Ustawienia → Logowanie**, z możliwością nadpisania dla każdego katalogu; zobacz [Ustawienia logowania](https://dts-identity.com/pl/docs/settings/login.md) |

## Refresh tokeny [#refresh-tokens]

**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 [#tokens-and-sign-out]

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](https://dts-identity.com/pl/docs/integrations/applications.md#token-lifetimes-and-logout). Zależności między sesją platformy, sesjami aplikacji i sesją nadrzędnego dostawcy tożsamości opisuje [Cykl życia użytkownika: sesje](https://dts-identity.com/pl/docs/directories/user-lifecycle.md#sessions).

## Przechowywanie tokenów [#storing-tokens]

- **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

- [Zabezpieczanie API](https://dts-identity.com/pl/docs/quickstarts/protect-an-api.md): weryfikowanie access tokenów we własnym API.
- [API](https://dts-identity.com/pl/docs/integrations/apis.md): scope'y, audience i ustawienia tokenów dla każdego API.
- [Aplikacje](https://dts-identity.com/pl/docs/integrations/applications.md): ustawienia tokenów i wylogowania dla każdej aplikacji.
- [Ustawienia logowania](https://dts-identity.com/pl/docs/settings/login.md): limity czasu sesji SSO.
