Zrozumieć OAuth 2.0: flowy, scope i tokeny w praktyce

Dlaczego OAuth 2.0 jest dziś wszędzie i o co w nim naprawdę chodzi

Większość nowoczesnych aplikacji webowych i mobilnych korzysta z zewnętrznych API: Google, Facebook, GitHub, Microsoft, Stripe, Spotify, Allegro, własne mikroserwisy. Wspólny mianownik to konieczność bezpiecznego delegowania dostępu – aplikacja ma zrobić coś w imieniu użytkownika, ale nie powinna znać jego hasła. Do tego właśnie służy OAuth 2.0.

OAuth 2.0 nie jest protokołem logowania wprost, ale frameworkiem autoryzacji. Pozwala aplikacji (klientowi) uzyskać ograniczony dostęp do zasobu (API) w imieniu użytkownika, używając tokenów, a nie haseł. Tokeny powstają w kontrolowanym procesie nazywanym flow (grant flow) i są ograniczone zakresem uprawnień – scope.

Bez zrozumienia flowów, scope’ów i tokenów trudno debugować problemy, bezpieczeństwo staje się loterią, a integracje są łata na łacie. Dobrze poukładana wiedza o OAuth 2.0 pozwala świadomie wybierać mechanizm, świadomie konfigurować scope’y oraz rozumieć, co tak naprawdę oznacza dany token w logach serwera.

Poniższe sekcje przechodzą przez najważniejsze elementy OAuth 2.0 w praktyce: od ról w systemie, przez podstawowe flowy, po bezpieczne przechowywanie i odświeżanie tokenów w aplikacjach front‑end, backend i mobilnych.

Kluczowe pojęcia: role, endpointy i podstawowa terminologia OAuth 2.0

Główne role w OAuth 2.0

Specyfikacja OAuth 2.0 definiuje cztery podstawowe role. Bez ich rozróżnienia flowy wyglądają jak chaos.

• Resource Owner – właściciel zasobu. Zwykle użytkownik końcowy, którego dane znajdują się na serwerze (np. konto Google, zdjęcia, repozytoria GitHub). Czasami może to być aplikacja lub organizacja, ale w typowych scenariuszach to po prostu człowiek.
• Client – aplikacja, która chce uzyskać dostęp do zasobów w imieniu użytkownika. Może to być:
  • aplikacja serwerowa (backend z tajnym kluczem),
  • single-page app (JS w przeglądarce),
  • aplikacja mobilna,
  • CLI / desktop.
• Authorization Server – serwer autoryzacji. Weryfikuje użytkownika, wyświetla ekran zgody (consent), wydaje tokeny. Często to ten sam system, co dostawca tożsamości (IdP), np. Google Accounts.
• Resource Server – API, które udostępnia chronione zasoby (np. Graph API, Google Calendar API). Weryfikuje tokeny i na ich podstawie wydaje dane.

W praktyce Authorization Server i Resource Server mogą być częścią tej samej implementacji (np. Keycloak, Auth0, Cognito), ale logicznie pełnią inne funkcje. To rozróżnienie jest kluczowe przy debugowaniu: inne logi, inne błędy, inne konfiguracje.

Grant, flow, redirect URI i scope – przegląd pojęć

W rozmowach o OAuth 2.0 często przewijają się terminy, które bywają mylone lub stosowane zamiennie. Warto je rozdzielić:

• Grant Type – sposób, w jaki klient uzyskuje token. Przykłady:
  • authorization_code,
  • client_credentials,
  • refresh_token,
  • device_code,
  • password (przestarzały / legacy).
• Authorization Flow – praktyczny przebieg interakcji między klientem, serwerem autoryzacji i właścicielem zasobu. To „scenariusz rozmowy” z użyciem konkretnego typu grantu oraz dodatkowych zabezpieczeń (np. PKCE).
• Redirect URI – adres URL, pod który serwer autoryzacji odsyła użytkownika po udzieleniu zgody. To newralgiczny element bezpieczeństwa – błędna lub zbyt luźna konfiguracja redirect URI potrafi zniszczyć cały model bezpieczeństwa.
• Scope – żądany zakres uprawnień. To właśnie tu definiuje się, do jakich zasobów i w jakim zakresie token ma mieć dostęp.

Endpointy protokołu OAuth 2.0

Standardowe wdrożenia OAuth 2.0 korzystają z powtarzającego się zestawu endpointów. W dokumentacji dostawców (Google, Azure AD, Keycloak, Auth0) różnią się tylko adresami i czasem drobnymi parametrami:

• /authorize – endpoint autoryzacji:
  • obsługuje przekierowania przeglądarki,
  • weryfikuje użytkownika (login/hasło, MFA),
  • prezentuje ekran zgody na scope’y,
  • zwraca authorization code lub error.
• /token – endpoint tokenów:
  • przyjmuje code, client_id, client_secret / PKCE verifier,
  • wydaje access token, często też refresh token i ID token (OIDC),
  • obsługuje granty: authorization_code, client_credentials, refresh_token, password (legacy).
• /userinfo (OIDC) – endpoint, który na podstawie access tokena (dla odpowiedniego audience) zwraca dane profilu użytkownika.
• /introspect – opcjonalny endpoint introspekcji tokena (częsty w środowiskach enterprise). Pozwala serwerowi zasobów zapytać serwer autoryzacji, co tak naprawdę kryje się w danym tokenie, jeśli token jest opakowanym ID (opaque token).
• /revoke – endpoint unieważniania tokenów (access/refresh) zgodny ze specyfikacją RFC 7009.

Flowy OAuth 2.0: przegląd i zastosowania w praktyce

Authorization Code Flow – złoty standard dla aplikacji z backendem

Authorization Code Flow to podstawowy i najczęściej stosowany flow OAuth 2.0 dla aplikacji serwerowych (confidential clients). Jest bezpieczny, bo:

• użytkownik loguje się tylko na stronie dostawcy (authorization server),
• dane logowania nie podlegają aplikacji klienta,
• client_secret nigdy nie trafia do przeglądarki,
• tokeny odbiera backend przez bezpieczne połączenie HTTP.

W tym flow aplikacja front‑endowa przekierowuje użytkownika na /authorize, serwer autoryzacji po udzieleniu zgody zwraca code na redirect_uri, a aplikacja serwerowa wymienia ten code na access/refresh tokeny uderzając bezpośrednio do /token.

PKCE – Authorization Code Flow dla SPA i mobile

W klasycznym Authorization Code Flow występuje client_secret, który musi być tajny. W przypadku SPA (JS w przeglądarce) i mobilnych aplikacji natywnych nie ma możliwości ukrycia sekretu – kod może zostać zreverse’owany, inspektor DevTools wszystko wyciągnie. Dlatego opracowano rozszerzenie PKCE (Proof Key for Code Exchange).

PKCE zastępuje zaufanie do client_secret zaufaniem do pary code_verifier / code_challenge generowanej dla konkretnej sesji. Dzięki temu:

• authorization code przechwycony przez atakującego jest bezużyteczny,
• aplikacja nie przechowuje żadnego stałego tajnego sekretu,
• Authorization Code Flow staje się bezpieczny dla SPA i aplikacji mobilnych.

Client Credentials Flow – gdy nie ma użytkownika

Client Credentials Flow służy do autoryzacji samej aplikacji, bez użytkownika końcowego. Typowe zastosowania:

• komunikacja między mikroserwisami w infrastrukturze backendowej,
• komendy batch/cron, które działają „jako system”,
• backend integrujący się z zewnętrznym API, gdzie nie ma osobistego kontekstu użytkownika (np. techniczny dostęp do API fakturowego).

W tym flow klient wysyła swoje dane uwierzytelniające (client_id + client_secret, czasem certyfikat) do /token z grant_type=client_credentials i dostaje access token o scope’ach skonfigurowanych dla aplikacji. Nie ma redirectów, nie ma logowania użytkownika, nie ma refresh tokena (zwykle).

Device Code Flow – logowanie na TV, konsolach i urządzeniach bez przeglądarki

Device Authorization Grant (Device Code Flow) to odpowiedź na potrzebę logowania na urządzeniach z ograniczonym UI: SMART TV, konsole, terminale. Użytkownik przepisuje kod z ekranu urządzenia na stronę logowania w normalnej przeglądarce na komputerze lub telefonie, a urządzenie w tle „polluje” endpoint /device token aż do momentu sukcesu.

Scenariusz jest wygodny dla użytkownika i bezpieczny – dane logowania nigdy nie są wprowadzane na ograniczonym, potencjalnie niezaufanym urządzeniu.

Resource Owner Password Credentials – legacy flow do wygaszania

ROPC (Resource Owner Password Credentials) polega na tym, że aplikacja bezpośrednio pyta o login i hasło do zewnętrznego systemu i wysyła je do /token z grant_type=password. Większość dostawców to odradza lub wyłącza w nowych wdrożeniach, bo:

• aplikacja musi mieć dostęp do hasła użytkownika,
• użytkownik przekazuje hasło podmiotowi innemu niż dostawca tożsamości,
• trudniej stosować MFA i nowoczesne mechanizmy bezpieczeństwa.

ROPC bywa używany tymczasowo w legacy środowiskach (np. stare desktopowe aplikacje), ale strategia powinna zakładać przejście na Authorization Code + PKCE lub inne nowoczesne mechanizmy.

Authorization Code Flow z PKCE krok po kroku

Inicjowanie logowania – wysłanie użytkownika na endpoint autoryzacji

W przeglądarce lub aplikacji mobilnej proces zwykle wygląda następująco:

1. Klient generuje code_verifier – losowy, trudny do przewidzenia string.
2. Na jego podstawie oblicza code_challenge (np. base64url(SHA256(code_verifier))).
3. Przekierowuje użytkownika na:

   GET /authorize?
     response_type=code
     &client_id=...
     &redirect_uri=https://twojaappka.pl/callback
     &scope=openid%20profile%20email
     &state=XYZ
     &code_challenge=...
     &code_challenge_method=S256
   

Parametr state służy do ochrony przed atakiem CSRF oraz do przenoszenia wewnętrznego kontekstu (np. ścieżki, na którą użytkownik ma wrócić). Warto implementować solidne generowanie i walidację state, zamiast traktować go jako „jakikolwiek string”.

Ekran logowania i zgody – rola Authorization Server

Authorization server po odebraniu żądania /authorize:

• sprawdza poprawność client_id, redirect_uri, scope, code_challenge,
• weryfikuje sesję użytkownika (być może jest już zalogowany),
• ewentualnie wymusza logowanie (login/hasło, MFA, WebAuthn),
• pokazuje ekran zgody na scope’y, jeżeli jest to wymagane (np. „Aplikacja X chce uzyskać dostęp do twojego kalendarza”).

Po akceptacji (lub jeśli zgoda była wyrażona wcześniej) użytkownik zostaje przekierowany na skonfigurowany redirect_uri z parametrem code i state:

GET https://twojaappka.pl/callback?
  code=AUTH_CODE_HERE
  &state=XYZ

Na tym etapie jeszcze nie ma tokenów. Aplikacja ma jedynie krótkożyjący authorization code, który musi wymienić na /token.

Wymiana authorization code na access i refresh token

Backend aplikacji (lub zaufana część klienta, np. serwer BFF) wysyła żądanie do /token:

POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_HERE
&redirect_uri=https://twojaappka.pl/callback
&client_id=...
&code_verifier=ORIGINAL_CODE_VERIFIER

Authorization server:

• sprawdza, czy code jest ważny i nieużyty wcześniej,
• weryfikuje, czy code_challenge pasuje do code_verifier,
• sprawdza zgodność redirect_uri z pierwotnym żądaniem,
• wydaje:
  • access_token,
  • refresh_token (opcjonalnie, zależnie od konfiguracji),
  • id_token (w OpenID Connect).

Przykładowa odpowiedź JSON:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9....",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200a3b...",
  "scope": "openid profile email api.read",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
}

Od tego momentu backend może używać access_token do wywołań API (resource server), a refresh_token do uzyskiwania nowych access_tokenów po wygaśnięciu.

Obsługa błędów i bezpieczeństwo redirect URI

Typowe błędy w flow i twarde zasady dla redirect_uri

Przy Authorization Code + PKCE wiele problemów wynika nie z samego protokołu, ale z konfiguracji. Kluczowe jest podejście „wszystko jest inputem od użytkownika lub atakującego”. To dotyczy zwłaszcza parametrów redirect_uri, state i obsługi błędów.

• Brak ścisłego dopasowania redirect_uri – serwer autoryzacji nie powinien akceptować dowolnego redirect_uri z tym samym client_id. Redirect musi być whitelistowany i dopasowywany dokładnie (wiele IdP wspiera patterny, ale wymagają ostrożności).
• Otwarte przekierowania – jeśli aplikacja na callbacku przyjmuje dodatkowy parametr typu returnUrl, trzeba go walidować (np. tylko ścieżki względne), żeby nie stworzyć open redirecta dla ataków phishingowych.
• Ignorowanie parametru error – w razie niepowodzenia serwer autoryzacji przekazuje na redirect_uri parametry error, error_description, state. Brak obsługi skutkuje „magicznie znikającym logowaniem”.

Przykładowe przekierowanie z błędem:

GET https://twojaappka.pl/callback?
  error=access_denied
  &error_description=User%20denied%20consent
  &state=XYZ

Po stronie klienta kroki powinny być jasne:

1. Zawsze zweryfikować state przed jakąkolwiek dalszą logiką.
2. Jeżeli obecny jest error – pokazać kontrolowany komunikat (bez ślepego wyświetlania całego error_description użytkownikowi).
3. Logować błąd techniczny po stronie serwera, ale nie ujawniać szczegółów w UI.

Scope’y w praktyce: jak modelować uprawnienia

Granularność scope’ów – zbyt mało vs zbyt dużo

Scope’y to „słowa kluczowe”, które mówią, do czego ma dostęp klient. Problemem jest zarówno ich nadmiar, jak i zbytni minimalizm. Kilka zasad upraszcza projekt:

• Scope jako zdolność, a nie twarda rola – zamiast role_admin lepiej users.read, users.write, reports.generate. Role mogą żyć w atrybutach użytkownika lub osobnym systemie.
• Unikanie scope’ów typu „god mode” – scope api.full jest wygodny, ale w praktyce często prowadzi do nadawania za szerokiego dostępu.
• Ograniczenie liczby unikalnych scope’ów – setki scope’ów utrudniają administrację, audyt i UX ekranów zgody.

Scope’y użytkownika vs scope’y aplikacji

Inny zestaw scope’ów będzie miał sens dla flow z udziałem użytkownika, a inny dla Client Credentials. Warto rozdzielić te światy:

• dla użytkownika – scope’y opisujące jego możliwości w systemie (np. tasks.read, calendar.write),
• dla klienta technicznego – scope’y związane z integracją i zadaniami systemowymi (np. jobs.process, invoices.sync).

W praktyce dobrze działa strategia: „scope’y techniczne w ogóle nie są dostępne dla flowów z użytkownikiem” – są przypisane wyłącznie do wybranych confidential clients.

Scope’y a audyt i zasada najmniejszych uprawnień

Jeżeli resource server loguje przychodzące żądania wraz ze scope’ami, analiza logów pozwala zobaczyć, które uprawnienia są naprawdę używane. Na tej podstawie można:

• wygaszać stare, nieużywane scope’y,
• dzielić zbyt ogólne scope’y na bardziej granularne,
• wyłapywać podejrzane użycie (np. nagłe pojawienie się rzadkiego scope’a z aplikacji, która zwykle go nie ma).

Access token vs ID token vs refresh token

Rola access tokena w komunikacji z API

Access token to „bilet wstępu” do API. Najczęściej to JWT, ale może być też token nieprzezroczysty (opaque). Z punktu widzenia API ważne są trzy rzeczy:

• audience – do kogo jest adresowany token (np. api://orders),
• scope – lista uprawnień,
• exp – data ważności, raczej liczona w minutach niż godzinach.

API powinno odrzucać token, który nie jest do niego adresowany (audience), nawet jeśli jest poprawnie podpisany i nie wygasł.

ID token – tylko do identyfikacji użytkownika

ID token pochodzi z OpenID Connect i opisuje użytkownika oraz kontekst logowania. Nie służy jako „bilet do API” – to rola access tokena. Typowe pola ID tokena:

• sub – unikalny identyfikator użytkownika,
• name, preferred_username, email,
• auth_time, amr (metody uwierzytelnienia),
• nonce – ochrona przed atakami replay w aplikacjach front‑endowych.

Aplikacja może przechowywać ID token w sesji, ale nie powinna używać go do autoryzacji żądań do backendu zamiast access tokena.

Refresh token – jak bezpiecznie wydłużyć sesję

Refresh token ma dłuższy czas życia i służy do wydawania nowych access tokenów. Tu dochodzi kolejna warstwa bezpieczeństwa:

• w SPA refresh token nie powinien trafiać do localStorage – lepsze są httpOnly secure cookies lub BFF,
• warto stosować refresh token rotation – każdy refresh token jest jednorazowy, a w razie użycia starego system wykrywa możliwe przejęcie.

Przykładowe odświeżenie tokena:

POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=def50200a3b...
&client_id=...

Odpowiedź może zawierać nowy refresh token (w modelu rotacji) lub tylko nowy access token (przy prostszej konfiguracji).

Bezpieczne przechowywanie tokenów w aplikacjach web

SPA: localStorage, sessionStorage, cookie czy BFF?

W aplikacjach przeglądarkowych decyzja, gdzie trzymać tokeny, ma duży wpływ na odporność na ataki XSS/CSRF:

• localStorage/sessionStorage – wygodne, ale podatne na XSS; jeśli napastnik może wykonywać JS, ma token.
• Cookies httpOnly + SameSite – chronią przed dostępem przez JS, ale wymagają ochrony przed CSRF (np. dodatkowy nagłówek, synchronizowany token anty-CSRF).
• BFF (Backend‑For‑Frontend) – przeglądarka nigdy nie „widzi” access tokena; backend mapuje sesję użytkownika na tokeny trzymane po stronie serwera.

Model BFF jest obecnie jednym z bezpieczniejszych wzorców dla SPA: przeglądarka ma tradycyjną sesję cookies, a cały OAuth 2.0 dzieje się po stronie dedykowanego backendu.

Mobile: secure storage i custom URI schemes

W aplikacjach mobilnych tokeny lądują zazwyczaj w natywnym secure storage (Keychain, Keystore). Osobnym wyzwaniem jest powrót z przeglądarki do aplikacji (redirect_uri):

• custom URI scheme (np. myapp://callback) – prosty, ale wymaga dodatkowych zabezpieczeń przed przechwyceniem URI przez złośliwą aplikację,
• app links / universal links – powiązanie domeny z aplikacją poprzez plik konfiguracyjny na serwerze i w manifestach aplikacji.

W poważniejszych wdrożeniach łączy się PKCE, secure storage i uniwersalne linki, a sam proces logowania odbywa się w systemowej przeglądarce lub dedykowanym „auth tab”, nie w osadzonym WebView.

Walidacja tokenów po stronie Resource Server

JWT: weryfikacja podpisu i kluczy publicznych

Jeżeli access token jest JWT, resource server musi zweryfikować co najmniej:

• podpis – z użyciem klucza publicznego pobranego z /.well-known/jwks.json,
• iss – czy pochodzi z oczekiwanego serwera autoryzacji,
• aud – czy token jest wystawiony dla tego API,
• exp – czy token nie wygasł (z niewielkim marginesem na zegary),
• opcjonalnie nbf, iat, azp (authorized party), jeśli IdP ich używa.

Klucze publiczne (JWKS) można cache’ować, ale API musi reagować na ich rotację. Większość bibliotek klienta potrafi odświeżać JWKS na podstawie nagłówków HTTP lub błędów weryfikacji podpisu.

Opaque tokeny i endpoint introspekcji

Gdy access token jest nieprzezroczystym identyfikatorem, resource server nie ma czego zweryfikować lokalnie – musi zapytać serwer autoryzacji na endpoint /introspect:

POST /introspect
Authorization: Basic <client_credentials>
Content-Type: application/x-www-form-urlencoded

token=2YotnFZFEjr1zCsicMWpAA

Odpowiedź zawiera informację, czy token jest aktywny oraz jakie ma scope’y i właściciela:

{
  "active": true,
  "scope": "api.read api.write",
  "client_id": "my-backend",
  "username": "user@example.com",
  "exp": 1680000000,
  "sub": "1234567890"
}

Taki model bywa preferowany w środowiskach enterprise z centralną kontrolą sesji i natychmiastowym unieważnianiem dostępu.

OAuth 2.0 i OIDC w scenariuszach mikrousług

Tokeny per‑service i gateway jako strażnik

W architekturze mikroserwisowej nie ma sensu, by każdy serwis samodzielnie prowadził złożone integracje z IdP. Typowe wzorce to:

• API Gateway – przyjmuje żądania z access tokenem, weryfikuje go i przekazuje do serwisów informację o kontekście użytkownika w nagłówkach (np. X-User-Id, X-Scopes).
• Token exchange – gateway lub BFF wymienia zewnętrzny token użytkownika na „wewnętrzny” token techniczny, pasujący do modelu uprawnień backendu.

Takie podejście ogranicza podatność serwisów na zmiany IdP oraz upraszcza logikę bezpieczeństwa wewnątrz klastra.

Delegacja między serwisami i „on‑behalf‑of”

Kiedy serwis A wywołuje serwis B „w imieniu użytkownika”, prosty forwarding tego samego access tokena bywa niewystarczający. Pojawiają się problemy z audytem i zakresem uprawnień. Niektórzy dostawcy wspierają specjalny grant typu on‑behalf‑of lub token exchange (RFC 8693):

• serwis A przesyła do IdP swój własny credential + token użytkownika,
• IdP wystawia nowy token dla serwisu B z odpowiednio ograniczonym zakresem (audience = B, specyficzne scope’y),
• trasa audytu jest czytelna: kto kogo i w czyim imieniu wywołał.

Bezpieczeństwo i typowe anty‑wzorce w OAuth 2.0

Najczęstsze pułapki implementacyjne

W realnych projektach regularnie powtarzają się te same błędy:

• traktowanie OAuth 2.0 jako „logowania” zamiast protokołu autoryzacji – brak OIDC, ID tokena, nonce itd.,
• przechowywanie access tokenów w logach aplikacyjnych lub systemowych,
• brak weryfikacji audience w API – każdy poprawnie podpisany token jest akceptowany, nawet jeśli dotyczy innego systemu,
• używanie tego samego client_id/secret w wielu środowiskach (dev, test, prod) lub między różnymi aplikacjami,
• stawianie własnego „mini IdP” bez zrozumienia pełni konsekwencji, zamiast użycia sprawdzonego dostawcy.

Reagowanie na incydenty: rotacja kluczy i odwoływanie tokenów

Gdy dojdzie do wycieku klucza prywatnego lub client_secret, czas reakcji jest kluczowy. Dobrze zaprojektowana infrastruktura OAuth 2.0 zakłada:

• możliwość szybkiej rotacji kluczy (publikacja nowego JWKS, stopniowe wyłączanie starego),
• centralny mechanizm revocation (endpoint /revoke + listy unieważnionych tokenów lub bardzo krótkie TTL),
• automatyczną re‑konfigurację klientów po stronie aplikacji (np. pobieranie metadanych z /.well-known/openid-configuration).

W praktyce taki incydent jest testem, czy procesy DevOps i bezpieczeństwa są przygotowane na życie, a nie tylko na „zielony” scenariusz demo.

Projektowanie scope’ów i modeli uprawnień

Scope jako kontrakt między klientem a API

Dobrze zaprojektowane scope’y ułatwiają życie wszystkim – klientowi, API i zespołowi bezpieczeństwa. Scope pełni rolę uproszczonego kontraktu: „na co aplikacja może sobie pozwolić w API”.

Przy definiowaniu scope’ów zwykle rozważa się kilka osi podziału:

• według domeny biznesowej – np. orders.read, orders.write, profile.read,
• według poziomu dostępu – np. read, write, admin jako prefiksy lub sufiksy,
• według typu klienta – osobne scope’y dla aplikacji mobilnej, panelu admina i integracji partnerskich.

Zbyt ogólne scope’y (api.full) praktycznie uniemożliwiają ograniczanie dostępu. Zbyt szczegółowe (orders.read.basic, orders.read.advanced, orders.refund.partial itd.) szybko wymykają się spod kontroli – każdy nowy endpoint wymaga nowej nazwy.

Scope a role i uprawnienia domenowe

Scope nie musi odwzorowywać pełnego modelu RBAC z systemu. Często stosuje się dwustopniowy model:

• scope’y odzwierciedlają rodzaj operacji na API (czy klient może wywołać daną kategorię endpointów),
• szczegółowe uprawnienia (role, organizacje, tenanty) są egzekwowane wewnątrz API, na podstawie dodatkowych claimów w tokenie (roles, org_id, permissions).

API weryfikuje więc zarówno scope (czy operacja jest w ogóle dozwolona dla klienta), jak i kontekst użytkownika (czy konkretny użytkownik może wykonać ją na danym zasobie). Takie rozdzielenie zmniejsza konieczność ciągłej redefinicji scope’ów przy zmianach w logice biznesowej.

Scope’y „publiczne” i „konfidencjalne”

Zakresy dostępne dla publicznych klientów (SPA, mobile) powinny być naturalnie ograniczone – brak krytycznych operacji administracyjnych, brak możliwości eskalacji uprawnień. Scope’y dla confidential clients (serwisy backendowe) mogą być szersze, ale zwykle są dodatkowo chronione politykami po stronie IdP (np. wymóg konkretnego rodzaju klienta, certyfikatu mTLS).

Dobrą praktyką jest oznaczenie technicznych scope’ów zgodnie z przeznaczeniem, np. internal.* dla integracji wewnętrznych, których nie dostają zewnętrzni partnerzy ani publiczne aplikacje.

Granty mniej oczywiste: device flow, client credentials, CIBA

Device Authorization Grant (tzw. device flow)

Urządzenia bez wygodnej klawiatury lub przeglądarki (telewizory, konsole, IoT) często korzystają z Device Authorization Grant (RFC 8628). Zamiast logowania bezpośrednio na urządzeniu:

• urządzenie wywołuje endpoint /device_authorization i otrzymuje device_code oraz user_code,
• na ekranie pojawia się komunikat w stylu: „Wejdź na https://example.com/device i wpisz kod ABCD-EFGH”,
• użytkownik loguje się na telefonie lub laptopie, wprowadza kod i potwierdza dostęp dla urządzenia,
• urządzenie w tle „polluje” endpoint /token z device_code, aż otrzyma access token.

Kluczowe zabezpieczenia:

• stosowne limity i wygasanie device_code,
• regulacja częstotliwości odpytywania (slow_down w odpowiedziach IdP),
• brak wyświetlania pełnego URI z tokenem na ekranie – jedynie prosty kod użytkownika.

Client Credentials Grant – czyste machine‑to‑machine

Client Credentials Grant służy do uwierzytelniania samych aplikacji/serwisów, bez udziału użytkownika. Access token reprezentuje tu klienta, nie człowieka. Typowy scenariusz:

• serwis backendowy uzyskuje token z IdP, używając client_id i client_secret lub mTLS,
• API waliduje token i przypisuje wywołania do danego klienta/serwisu.

Mieszanie tego trybu z operacjami w imieniu użytkownika prowadzi do nieczytelnego audytu. Jeśli API wymaga kontekstu użytkownika, trzeba użyć jednego z grantów „user‑based” (np. authorization code + PKCE, on‑behalf‑of, token exchange), a nie próbować „doklejać” identyfikator użytkownika w customowym claime.

CIBA – logowanie „na żądanie” pushowane na inne urządzenie

Coraz częściej spotykany w bankowości i systemach o podwyższonym poziomie bezpieczeństwa jest OIDC CIBA (Client‑Initiated Backchannel Authentication). Zamiast klasycznego redirectu:

• klient backendowy inicjuje żądanie uwierzytelnienia do IdP z identyfikatorem użytkownika (np. login, numer telefonu),
• IdP wysyła powiadomienie push/tekstowe do zaufanego urządzenia użytkownika (np. aplikacja mobilna),
• użytkownik zatwierdza lub odrzuca żądanie na tym urządzeniu,
• klient otrzymuje wynik przez kanał back‑channel (polling, webhook).

CIBA upraszcza logowanie w kanałach, gdzie redirect do przeglądarki jest kłopotliwy (call center, aplikacje kioskowe), jednak wymaga dojrzałego IdP i dobrze przemyślanej UX na urządzeniu autoryzującym.

Praktyczne wzorce integracji z IdP

Wykorzystanie OpenID Connect Discovery

Manualne wpisywanie adresów /authorize, /token, /jwks w konfiguracji każdej aplikacji szybko staje się uciążliwe. OIDC wprowadza mechanizm Discovery pod URL-em /.well-known/openid-configuration. Typowy klient:

• pobiera dokument discovery raz na start aplikacji lub przy cache miss,
• czyta z niego adresy endpointów, algorytmy podpisu, URI do JWKS, obsługiwane granty i scope’y,
• dostosowuje się automatycznie do części zmian po stronie IdP (np. nowy adres endpointu token).

To prosty sposób, aby uniknąć „konfiguracyjnego betonu” i ręcznych zmian w dziesiątkach serwisów przy każdej większej modyfikacji IdP.

Konfiguracja wielu IdP w jednej aplikacji

Systemy B2B i platformy SaaS często muszą współpracować z wieloma dostawcami tożsamości – np. własnym IdP oraz IdP klientów korporacyjnych. Typowe podejścia:

• broker tożsamości – wewnętrzny IdP pełni rolę pośrednika; klienci integrują się z nim, a on z kolei z różnymi zewnętrznymi IdP (Azure AD, Keycloak, Ping, itd.),
• dedykowane konfiguracje tenantów – każda organizacja ma oddzielny zestaw metadanych (discovery, klucze, polityki logowania), wybierany np. na podstawie domeny e‑mail lub subdomeny (org1.example.com).

W obu przypadkach kluczowe jest jednoznaczne mapowanie użytkownika i organizacji oraz spójna polityka scope’ów. Chaos zaczyna się wtedy, gdy różni dostawcy zwracają sprzeczne lub niespójne nazwy claimów, a aplikacja próbuje je „łatać” ad‑hoc w kodzie.

Ataki na OAuth 2.0 i OIDC oraz sposoby obrony

Manipulacja redirect_uri i open redirect

Jednym z częstszych ataków są próby manipulacji parametrem redirect_uri. Napastnik próbuje:

• wskazać własną domenę jako miejsce powrotu po logowaniu,
• wstrzyknąć parametry przekazywane dalej do aplikacji (np. redirect_uri=https://app.example.com/callback?next=//evil.com).

Podstawowe zabezpieczenia po stronie IdP i klienta:

• whitelistowanie konkretnych redirect_uri (pełne URL‑e, nie wzorce z *),
• porównywanie przekazanego redirect_uri z konfiguracją klienta metodą exact match lub ścisłych reguł dopasowania,
• walidacja parametrów „wewnętrznych” redirectów (next, continue) w aplikacji, aby uniemożliwić open redirect do zewnętrznych domen.

Token substitution i zmiana audience

W środowisku z wieloma API pojawia się ryzyko, że token wystawiony dla jednego serwisu („audience = A”) zostanie użyty w innym („audience = B”). Jeśli oba API ufają temu samemu IdP i nie weryfikują aud, napastnik może uzyskać nieautoryzowany dostęp.

Broni przed tym:

• konsekwentna walidacja aud w każdym resource serverze,
• stosowanie dedykowanych audience/scope’ów dla każdego API (brak „uniwersalnych” tokenów dla wszystkich serwisów),
• oddzielne konfiguracje klientów dla poszczególnych integracji.

Replay i kradzież kodu autoryzacyjnego

Bez PKCE napastnik, który przechwyci authorization_code (np. przez złośliwy proxy, modyfikację konfiguracji DNS, błędny redirect), może wymienić go na access token w swojej aplikacji. PKCE wymusza dopasowanie code_verifier i code_challenge, co praktycznie uniemożliwia użycie kodu w innym kliencie niż ten, który go wygenerował.

Dodatkowo:

• kody autoryzacyjne muszą być jednorazowe i krótko żyjące (sekundy–minuty),
• IdP powinien powiązać authorization_code z konkretnym client_id i redirect_uri i odmówić wymiany, jeśli coś się nie zgadza.

CSRF w flow opartych o przeglądarkę

W klasycznym authorization code flow z przeglądarką pojawia się ryzyko CSRF podczas powrotu z IdP do aplikacji. Standardowy mechanizm ochrony to parametr state:

• przed przekierowaniem do IdP aplikacja generuje losowy, trudny do odgadnięcia state,
• przechowuje go w sesji lub ciasteczku powiązanym z użytkownikiem,
• po powrocie z IdP porównuje otrzymany state z zapisanym; jeśli nie pasuje – odrzuca żądanie.

Brak lub błędna implementacja state (np. stała wartość dla wszystkich żądań) otwiera drogę do wymuszania logowania użytkownika na konto napastnika lub do wstrzykiwania cudzych kodów autoryzacyjnych.

Monitorowanie i obserwowalność w systemach z OAuth 2.0

Logowanie zdarzeń po stronie IdP

IdP jest centralnym punktem, w którym widać większość prób nadużyć. Przydatne kategorie logów to m.in.:

• nieudane logowania i anomalie (nietypowe geolokacje, próby brute‑force),
• odrzucone żądania autoryzacji (złe redirect_uri, nieobsługiwane scope’y),
• masowe próby wymiany refresh tokenów lub nadmierne użycie endpointu /token,
• rotacje kluczy i zmiany konfiguracji klientów.

Logi te zwykle trafiają do centralnego systemu SIEM, gdzie można korelować je z logami API, WAF czy firewalla.

Ślady w API: korelacja żądań z tokenami

Resource serwery powinny zapisywać minimalne, ale użyteczne informacje o tokenach:

• skrót (hash) tokena lub skróconą wersję jti / sub, aby móc powiązać wiele żądań z tym samym tokenem bez ryzyka wycieku,
• audit trail: sub, client_id, scope’y oraz kluczowe parametry żądania (metoda, URI, wynik),
• identyfikator korelacji (trace_id) przekazywany przez gateway lub BFF.

W praktyce, gdy pojawia się incydent, taki ślad jest bezcenny – pozwala szybko ustalić, czy wyciekł pojedynczy token, czy np. cały client_secret i ktoś masowo generuje własne tokeny.

Migracje i ewolucja istniejących systemów do OAuth 2.0

Przesiadka z sesji „cookie‑only” na tokeny

Starsze aplikacje webowe często bazują wyłącznie na własnych sesjach HTTP. Migracja do OAuth 2.0 i OIDC nie musi oznaczać rewolucji w jednym kroku. Sprawdza się podejście etapowe:

1. wprowadzenie centralnego IdP jako źródła tożsamości (SSO) przy zachowaniu dotychczasowego mechanizmu sesji,
2. stopniowe przełączanie części aplikacji na BFF korzystający z IdP,
3. zastępowanie wewnętrznych mechanizmów autoryzacji scope’ami i claimami w tokenach.

W pewnym momencie aplikacja przestaje „wiedzieć”, jak użytkownik się uwierzytelnił; wie jedynie, że ma ważny token z IdP i odpowiednie claimy, które autoryzuje według własnych zasad.

Zmiana IdP: ryzyka i strategia

Najczęściej zadawane pytania (FAQ)

Czym jest OAuth 2.0 i do czego służy?

OAuth 2.0 to framework autoryzacji, który pozwala aplikacji (klientowi) uzyskać ograniczony dostęp do zasobów użytkownika (np. API Google, GitHuba) bez potrzeby poznawania jego hasła. Zamiast haseł używane są tokeny wydawane przez serwer autoryzacji.

Dzięki OAuth 2.0 aplikacja może wykonywać operacje „w imieniu użytkownika” w kontrolowany, precyzyjnie ograniczony zakresem (scope) sposób. Jest to standard wykorzystywany w większości nowoczesnych aplikacji webowych, mobilnych i mikroserwisów.

Jakie są główne flowy (grant types) w OAuth 2.0 i kiedy ich używać?

Najczęściej stosowane grant types w OAuth 2.0 to:

• authorization_code – standard dla aplikacji z backendem (confidential clients); bezpieczny, bo client_secret nie trafia do przeglądarki.
• authorization_code + PKCE – zalecany dla SPA (JS w przeglądarce) i aplikacji mobilnych, gdzie nie da się ukryć client_secret.
• client_credentials – gdy nie ma użytkownika, tylko sama aplikacja (np. mikroserwisy, batch, integracje system–system).
• device_code – dla urządzeń z ograniczonym UI (TV, konsole, terminale).
• password (ROPC) – flow legacy, którego należy unikać i wygaszać.

Dobór flow zależy od typu klienta (backend, SPA, mobile, urządzenie) oraz tego, czy operujemy w kontekście użytkownika, czy tylko aplikacji.

Co to jest scope w OAuth 2.0 i jak go poprawnie dobrać?

Scope określa zakres uprawnień, o które prosi klient – definiuje, do jakich zasobów i w jakim zakresie uzyskany token będzie miał dostęp. Przykładowo: odczyt kalendarza, zapis plików, dostęp tylko do profilu użytkownika.

Poprawny dobór scope’ów to zasada najmniejszych uprawnień: żądaj tylko tych zakresów, które są niezbędne dla danej funkcji aplikacji. Dzięki temu ograniczasz skutki ewentualnego wycieku tokena oraz minimalizujesz powody, dla których użytkownik mógłby odrzucić zgodę na dostęp.

Jaka jest różnica między Authorization Server a Resource Server?

Authorization Server zajmuje się uwierzytelnieniem użytkownika, wyświetleniem ekranu zgody (consent) i wydawaniem tokenów. To on obsługuje typowe endpointy takie jak /authorize, /token, /revoke, a w środowiskach z OIDC także /userinfo.

Resource Server to API udostępniające chronione zasoby (np. Google Calendar API, Graph API). Weryfikuje przesłany access token i na jego podstawie decyduje, czy zwrócić dane. W wielu produktach (np. Keycloak, Auth0) oba serwery są częścią tej samej platformy, ale logicznie pełnią inne funkcje i mają inne logi oraz konfigurację.

Na czym polega Authorization Code Flow i dlaczego jest uznawany za bezpieczny?

W Authorization Code Flow użytkownik jest przekierowywany do /authorize na serwerze autoryzacji, gdzie się loguje i wyraża zgodę na scope’y. Po akceptacji serwer odsyła do aplikacji tymczasowy authorization code na zdefiniowany redirect URI.

Backend aplikacji wymienia ten code na access token (i często refresh token) przez bezpośrednie połączenie z /token, używając swojego client_id i client_secret. Dane logowania użytkownika nigdy nie trafiają do klienta, a client_secret nie opuszcza backendu, co istotnie podnosi bezpieczeństwo.

Co to jest PKCE w OAuth 2.0 i kiedy należy go używać?

PKCE (Proof Key for Code Exchange) to rozszerzenie Authorization Code Flow zaprojektowane dla publicznych klientów, takich jak SPA i aplikacje mobilne, które nie mogą bezpiecznie przechowywać client_secret. Zamiast stałego sekretu używa się pary code_verifier / code_challenge generowanej na czas konkretnej sesji.

Dzięki PKCE przechwycenie samego authorization code przez atakującego nie pozwala mu wymienić go na token, ponieważ nie posiada właściwego code_verifier. PKCE jest obecnie rekomendowanym mechanizmem dla wszystkich klientów bez backendu.

Do czego służą endpointy /authorize, /token, /userinfo, /introspect i /revoke?

Typowe wdrożenia OAuth 2.0 udostępniają zestaw standardowych endpointów:

• /authorize – obsługuje przekierowania przeglądarki, logowanie użytkownika i ekran zgody, zwraca authorization code lub błąd.
• /token – wymienia authorization code lub dane klienta na tokeny (access/refresh, czasem ID token), obsługuje różne grant types.
• /userinfo (OIDC) – zwraca dane profilu użytkownika na podstawie ważnego access tokena.
• /introspect – pozwala sprawdzić ważność i zawartość (claims) opaque tokena po stronie serwera zasobów.
• /revoke – służy do unieważniania access i refresh tokenów zgodnie z RFC 7009.

Zrozumienie roli tych endpointów pomaga w diagnozowaniu błędów integracji oraz świadomym projektowaniu ścieżek logowania i autoryzacji.

Najważniejsze punkty

• OAuth 2.0 jest frameworkiem autoryzacji, a nie logowania – służy do delegowania dostępu do API za pomocą tokenów zamiast haseł użytkownika.
• Zrozumienie czterech ról (Resource Owner, Client, Authorization Server, Resource Server) jest kluczowe, bo każda odpowiada za inne zadania, logi i typy błędów.
• Grant type, authorization flow, redirect URI i scope to różne pojęcia: grant to techniczny mechanizm uzyskania tokena, flow to cały scenariusz interakcji, redirect URI to krytyczny element bezpieczeństwa, a scope definiuje zakres uprawnień tokena.
• Standardowe endpointy (/authorize, /token, /userinfo, /introspect, /revoke) powtarzają się u różnych dostawców – zmieniają się głównie adresy i drobne parametry, ale logika pozostaje podobna.
• Authorization Code Flow jest złotym standardem dla aplikacji z backendem, ponieważ utrzymuje client_secret i wymianę tokenów wyłącznie po stronie serwera, z dala od przeglądarki.
• Dla SPA i aplikacji mobilnych konieczne jest użycie Authorization Code Flow z PKCE, ponieważ w tych środowiskach nie da się bezpiecznie przechowywać client_secret.
• Bez dobrej znajomości flowów, scope’ów i rodzaju tokenów trudno zapewnić bezpieczeństwo i skutecznie debugować integracje OAuth 2.0 w systemach web, mobilnych i mikroserwisach.