Dowiedz się, czym są tokeny bearer, jak działają w OAuth 2.0 i JWT, czym różnią się od tokenów dostępu oraz poznaj najlepsze praktyki ich użycia.
Za niemal każdym nowoczesnym logowaniem do aplikacji lub żądaniem API stoi cichy bohater: token bearer. Możesz go nie zauważać, ale jest tam za każdym razem, gdy łączysz usługi, logujesz się lub pobierasz dane z chmury.
W tym przewodniku wyjaśniamy, do czego służą tokeny bearer, dlaczego są ważne i jak bezpiecznie się nimi posługiwać.
Token bearer to fragment danych, zwykle ciąg znaków, który potwierdza, że jego posiadacz ma prawo dostępu do zasobu. Ważne jest to, że każdy, kto niesie (ang. bear) ten token, może z niego skorzystać bez dodatkowego udowadniania swojej tożsamości.
Pomyśl o karcie pokładowej linii lotniczych. Gdy masz ją w ręce, możesz przejść przez kontrolę bezpieczeństwa i wejść do samolotu. Nikt nie prosi cię już o dowód, jeśli karta jest ważna. Podobnie token bearer pozwala twojej aplikacji „wejść na pokład API” bez ponownego sprawdzania tożsamości przy każdym żądaniu.
Na przykład, gdy zalogujesz się do Spotify na swoim telefonie, nie musisz podawać hasła za każdym razem, gdy uruchamiasz piosenkę. Zamiast tego aplikacja przechowuje token bearer, który mówi serwerom Spotify: „to żądanie pochodzi od autoryzowanego użytkownika”.
Przepływ użycia tokenów bearer można podzielić na kilka kroków:
Użytkownik się loguje
Załóżmy, że logujesz się do aplikacji bankowej swoim loginem i hasłem.
Dostawca tożsamości wydaje token
Po zweryfikowaniu dane logowania serwer uwierzytelniający odsyła token bearer. Może on wyglądać tak:
Klient używa tokenu
Za każdym razem, gdy klikniesz „Sprawdź saldo” lub „Przelej środki”, aplikacja dołącza token do żądania HTTP:
API go weryfikuje
Serwer sprawdza, czy token jest ważny, nie wygasł oraz czy zawiera odpowiednie uprawnienia (np. read:balance lub write:transfer).
Dostęp zostaje udzielony
Jeśli wszystko się zgadza, serwer zwraca żądane informacje.
Ten model jest szeroko wykorzystywany w usługach takich jak API GitHub, gdzie programiści uwierzytelniają się tokenem bearer zamiast podawać dane logowania przy każdym żądaniu.
Tokeny bearer stały się popularne, ponieważ rozwiązały typowe problemy bezpieczeństwa w sieci. W przeciwieństwie do sesji po stronie serwera, nie trzeba dla każdego zalogowanego użytkownika przechowywać oddzielnych danych sesyjnych. Zamiast tego token sam zawiera wystarczającą informację, by serwer mógł zweryfikować żądania.
Na przykład w architekturze mikrousług, gdzie dziesiątki usług rozmawiają ze sobą, centralny magazyn sesji byłby trudny w utrzymaniu i nieefektywny. Dzięki tokenom bearer każda usługa może niezależnie weryfikować żądania, a system pozostaje lekki i skalowalny.
Konkretna sytuacja: API Slacka w dużej mierze opierają się na tokenach bearer. Gdy budujesz bota Slacka, dostajesz token, który umożliwia botowi wykonywanie zapytań do API Slacka bez konieczności utrzymywania sesji dla każdego użytkownika.
Wiele tokenów bearer jest implementowanych jako JWT (JSON Web Tokens). Są to zakodowane ciągi zawierające informacje o użytkowniku i jego uprawnieniach.
Rozkodujmy przykładowy JWT:
Co to znaczy:
sub: Podmiot, czyli unikalny ID użytkownika.name: Imię i nazwisko użytkownika.iat: Czas wygenerowania tokenu (issued at).exp: Czas ważności (do kiedy token jest ważny).scope: Zakres uprawnień — w tym przypadku aplikacja może zarówno czytać, jak i zapisywać wiadomości.W praktyce, jeśli token Jane miałby tylko zakres read:messages, aplikacja mogłaby pobierać jej wiadomości, ale nie wysyłać nowych w jej imieniu.
Łatwo pomylić tokeny bearer z tokenami dostępu, ponieważ oba pojęcia często pojawiają się razem. Są powiązane, ale nieidentyczne.
Token dostępu to dane poświadczające, że użytkownik jest uprawniony do uzyskania dostępu do zasobu. Zawiera informacje takie jak:
To jak zgoda podpisana przez dyrektora szkoły. Mówi nauczycielowi (API), że możesz jechać na wycieczkę (uzyskać dostęp do zasobu).
Na przykład po zalogowaniu do usługi przechowywania plików w chmurze system wydaje token dostępu z zakresem read:files. Ten token mówi API: „Ten użytkownik może czytać pliki, ale nie może ich usuwać”.
Token bearer to rodzaj tokenu dostępu. Słowo bearer opisuje sposób użycia tokenu: ten, kto go przedstawia, może uzyskać dostęp do zasobów bez dalszego udowadniania tożsamości.
Innymi słowy:
Istnieją też inne typy tokenów, np. holder-of-key, które wymagają od klienta udowodnienia posiadania określonego klucza kryptograficznego oprócz samego tokenu. Tokeny bearer pomijają ten krok, co czyni je prostszymi, ale też bardziej ryzykownymi w razie kradzieży.
<token>.Oznacza to, że kiedy w tutorialach OAuth pojawia się „token dostępu”, prawie zawsze chodzi o token bearer, o ile nie wskazano inaczej.
Aby lepiej zobaczyć różnice, zerknijmy na porównanie tokenów bearer z innymi popularnymi typami:
Tokeny bearer i tokeny dostępu nie są przeciwieństwami — łączy je zakres:
Weryfikacja tokenu bearer chroni API przed nieautoryzowanym dostępem. Jeśli używasz JWT, walidacja odbywa się lokalnie i szybko — API może sprawdzić token bez każdorazowej konsultacji z wystawcą.
Potraktuj to jako instrukcję do użycia przy budowie gateway'a API lub middleware.
Podpis
Zweryfikuj podpis wykorzystując algorytm w nagłówku (np. RS256). Pobierz endpoint JWKS wystawcy, wybierz klucz po kid i cachuj go.
Issuer (iss)
Porównaj iss zaufanego wystawcy z URL tokenu, dokładnie i z odpowiednim schematem.
Audience (aud)
Sprawdź, czy token był przeznaczony dla twojego API. Porównaj z identyfikatorem API, jak https://api.example.com lub logicznym ciągiem audience.
Expiration (exp) i Not-Before (nbf)
Odrzucaj tokeny po wygaśnięciu. Uwzględnij nbf, by token nie działał przed czasem startu. Dopuszczalny jest mały margines (typowo 30–60 sekund).
Issued-At (iat)
Przydaje się przy debugowaniu i odrzucaniu bardzo starych tokenów w rygorystycznych ustawieniach.
Typ tokenu
Upewnij się, że to token dostępu. Niektórzy dostawcy umieszczają typ: "at+jwt" lub podobne. Nie akceptuj tokenów ID jako dostępu do API.
Zakresy / uprawnienia
Odczytaj scope lub claims specyficzne dla dostawcy (np. permissions, roles). Zastosuj zasadę najmniejszych uprawnień na każdym endpointzie.
Subjekt (sub)
Stabilne ID użytkownika lub klienta. Używaj do łączenia zasobów i do audytu.
Replay i cofnięcie (opcjonalnie, ale warto)
Dla wrażliwych endpointów sprawdź krótkotrwałą denylistę wartości jti, lub aktywny rekord sesji. Pomaga to po wylogowaniu lub podejrzeniu naruszenia.
Ponieważ tokeny bearer oznaczają „kto je ma, ten korzysta”, należy traktować je jak klucze do domu. Jeśli ktoś je ukradnie, ma dostęp dopóki nie zmienisz zamka.
Typowe zagrożenia to:
W praktyce do wycieków dochodziło, gdy deweloperzy przez przypadek zamieszczali tokeny bearer w publicznych repozytoriach GitHub. Atakujący mogą je łatwo odnaleźć i natychmiast wykorzystać.
Aby używać tokenów bearer bezpiecznie, warto trzymać się najlepszych praktyk. Oto ich przegląd z przykładami:
Zawsze używaj HTTPS
Wyobraź sobie wysyłanie tokenu po zwykłym HTTP w kawiarni. Każdy, kto podsłuchuje sieć, mógłby przechwycić token i zalogować się jako ty.
Krótkoterminowe tokeny dostępu
Większość platform wydaje tokeny ważne przez najwyżej godzinę. Przykładowo tokeny OAuth Google wygasają zwykle po godzinie i wymagają odświeżenia.
Uważnie przechowuj tokeny odświeżania
Token odświeżania może żądać nowych tokenów dostępu bez ponownego logowania. Należy jednak przechowywać go bezpiecznie (np. w zaszyfrowanej bazie na serwerze), nie po stronie klienta.
Przyznawaj tokenom tylko niezbędne uprawnienia
Jeśli twoja aplikacja musi tylko odczytywać kalendarz użytkownika, nie proś o write:calendar. Ogranicza to szkody w razie przechwycenia tokenu.
Unieważniaj token, gdy trzeba
Wiele aplikacji SaaS pozwala użytkownikom przeglądać aktywne sesje i unieważniać je. Na przykład GitHub pozwala w każdej chwili cofnąć własne tokeny osobiste.
Monitoruj użycie
Logowanie użycia tokenów może ujawnić podejrzane działania. Jeśli ten sam token nagle używany jest w Londynie i Nowym Jorku w przeciągu kilku minut, to niepokojący sygnał.
Warto porównać tokeny bearer z innymi popularnymi rozwiązaniami:
Cookies & Sesje
Tradycyjne strony internetowe korzystają z sesji po stronie serwera, identyfikowanych ciasteczkiem. To dobrze działa w aplikacjach przeglądarkowych, ale jest mniej efektywne dla API czy aplikacji mobilnych. Przykładowo, logowanie do Facebooka na komputerze to głównie cookies, a w API mobilnym — tokeny.
Klucze API
Klucz API to statyczny ciąg znaków uwierzytelniający aplikację, nie użytkownika. Na przykład aplikacja pogodowa używa klucza API do pobierania danych, ale ten klucz nie pozwala serwerowi ustalić, który użytkownik prosi o prognozę. Tokeny bearer mogą przenosić dane o użytkowniku, co czyni je bardziej uniwersalnymi.
Mutual TLS (mTLS)
W systemach wymagających wysokiego poziomu zabezpieczeń stosuje się certyfikaty zarówno po stronie klienta, jak i serwera. Takie rozwiązanie jest bezpieczne, ale trudne do wdrożenia na dużą skalę. Dla większości platform SaaS tokeny bearer są kompromisem między użytecznością a bezpieczeństwem.