Scope w autoryzacji — co to jest i jaką pełni rolę?

Czym jest scope?

Scope to jeden z najczęściej źle rozumianych elementów nowoczesnej autoryzacji. W skrócie: scope to lista ciągów tekstowych, którymi aplikacja kliencka deklaruje, jakiego poziomu dostępu potrzebuje, a serwer autoryzacyjny decyduje, ile z tego faktycznie przyzna.

Kluczowa intuicja, od której warto zacząć: scope nie opisuje tożsamości użytkownika ani jego pełni uprawnień w systemie. Scope opisuje co aplikacja może osiągnąć z konkretnym tokenem. To rozróżnienie brzmi subtelnie, ale jest fundamentem całej delegowanej autoryzacji. Gdy logujesz się do zewnętrznego narzędzia „przez Google", to narzędzie nie staje się Tobą — dostaje wąsko zdefiniowany token, który pozwala mu na przykład czytać Twój kalendarz, ale nie zmieniać hasła ani usuwać konta.

Formalnie scope został zdefiniowany w specyfikacji OAuth 2.0, czyli dokumencie RFC 6749, w sekcji 3.3. Standard mówi, że scope to lista stringów rozdzielonych spacjami, w których wielkość liter ma znaczenie (case-sensitive). Co istotne, RFC 6749 celowo nie narzuca, jak te ciągi mają wyglądać ani co mają znaczyć — to każdy serwer autoryzacyjny definiuje własny słownik zakresów, na przykład read:messages, contacts_write czy v1.users.read.

Warto od razu zaklasyfikować, czym scope nie jest. Scope nie jest technologią ani produktem — to element protokołu i standard projektowy. Nie jest też mechanizmem uwierzytelniania (nie odpowiada na pytanie „kim jesteś"), lecz mechanizmem ograniczania uprawnień delegowanych aplikacji.

Tu kryje się częste nieporozumienie: scope nie jest związany z metodą logowania, lecz z autoryzacją opartą na tokenach. Przy klasycznym logowaniu email i hasłem z sesją — gdy aplikacja uwierzytelnia własnego użytkownika i nie wydaje tokenu osobnej aplikacji — scope w ogóle nie występuje, a dostępem rządzą wtedy role i uprawnienia sprawdzane po stronie serwera. Scope wkracza dopiero, gdy istnieje token wydany aplikacji działającej wobec osobnego serwera zasobów. Co istotne, samo hasło tego nie wyklucza: jeśli logowanie hasłem jest częścią przepływu OAuth (na przykład w aplikacji SPA^?SPA: Single-Page Application — aplikacja webowa działająca w przeglądarce w obrębie jednej strony, dynamicznie wołająca API zamiast przeładowywać całe strony wołającej API), powstały token i tak nosi scope. Decyduje więc nie sposób logowania, lecz to, czy w grze jest token delegowany do osobnego API.

Kto za tym stoi?

Scope nie ma jednego twórcy w sensie firmy czy osoby — jest wytworem prac standaryzacyjnych prowadzonych w ramach IETF (Internet Engineering Task Force). Podstawą jest wspomniany RFC 6749 z 2012 roku, opisujący framework OAuth 2.0^?OAuth 2.0: otwarty standard autoryzacji delegowanej, pozwalający aplikacji uzyskać ograniczony dostęp do zasobów użytkownika bez przekazywania jej hasła. Z czasem wokół scope narosła rodzina rozszerzeń, które łatały kolejne braki pierwotnej specyfikacji.

Najważniejsze z nich to:

• OpenID Connect — warstwa tożsamości zbudowana na OAuth 2.0, rozwijana przez OpenID Foundation.
• profil tokenu JWT jako access tokenu (RFC 9068).
• wskaźniki zasobów wiążące token z konkretnym odbiorcą (RFC 8707).
• standard wymiany tokenów (RFC 8693).

Każdy z tych dokumentów dokłada coś do sposobu, w jaki scope jest wydawany, przenoszony i ograniczany.

W praktyce to jednak wielcy dostawcy — Google, Microsoft, GitHub, Auth0 czy Okta — kształtują codzienne doświadczenie deweloperów ze scope, bo to oni projektują konkretne słowniki zakresów i ekrany zgody, z którymi miliony użytkowników mają do czynienia.

Jak to działa?

Cały sens scope ujawnia się w trójstronnej relacji OAuth. Biorą w niej udział trzy strony:

• klient (aplikacja) — to on prosi o dostęp,
• serwer autoryzacyjny — wydawca tokenów,
• serwer zasobów — API, które chroni dane.

Gdy aplikacja chce uzyskać dostęp, wysyła do serwera autoryzacyjnego żądanie z parametrem scope, w którym wymienia żądane uprawnienia.

Serwer autoryzacyjny ma tu pełną władzę. Może przyznać dokładnie to, o co poproszono, może przyznać mniej (węższy zestaw), ale nigdy nie powinien przyznać czegoś, na co nie zgodził się właściciel zasobów. Jeśli aplikacja w ogóle pominie parametr scope, serwer może użyć wartości domyślnej zdefiniowanej przy rejestracji klienta albo odrzucić żądanie.

Po stronie serwera zasobów scope staje się warunkiem dostępu. Gdy token to nieprzezroczysty ciąg (opaque token), API musi go zweryfikować poprzez odpytanie serwera autoryzacyjnego. Gdy token jest w formacie JWT, API odczytuje go lokalnie, w trzech krokach:

1. weryfikuje podpis za pomocą kluczy publicznych udostępnianych jako JWKS,
2. sprawdza ważność tokenu (claim exp),
3. szuka wymaganego zakresu w polu scope.

Jeśli endpoint wymaga v1.write, API sprawdza, czy ten ciąg faktycznie znajduje się w claimie scope tokenu. Brak wymaganego zakresu kończy się odpowiedzią o niewystarczających uprawnieniach.

Z jakich elementów się składa?

Na ekosystem scope składa się kilka warstw, które łatwo pomylić.

Warstwa 1: parametr scope

Pierwsza to sam parametr scope — surowa lista ciągów. W tokenie JWT, zgodnie z RFC 9068, trafia ona do payloadu jako pojedyncze pole tekstowe z zakresami rozdzielonymi spacjami.

{
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "sub": "user-123",
  "exp": 1735689600,
  "scope": "openid profile email invoices:read invoices:create"
}

Warstwa 2: scope tożsamości (OpenID Connect)

Druga warstwa to scope tożsamości z OpenID Connect. OIDC wprowadził ustandaryzowany zestaw zakresów, które mapują się wprost na dane profilu użytkownika:

• openid — wymusza zgodną z OIDC procedurę i zwrócenie tokenu tożsamości (ID Token).
• profile — daje dostęp do podstawowych oświadczeń, takich jak name czy picture.
• email — daje adres oraz flagę email_verified.
• address i phone — dają odpowiednie dane kontaktowe.
• offline_access — nie mapuje się na żadne dane, lecz wymusza wydanie refresh tokenu, dzięki któremu aplikacja może odnawiać sesję bez udziału użytkownika.

{
  "iss": "https://auth.example.com",
  "aud": "client-app-123",
  "sub": "user-123",
  "exp": 1735689600,
  "name": "Jan Kowalski",
  "picture": "https://example.com/jan.jpg",
  "email": "jan.kowalski@example.com",
  "email_verified": true,
  "address": {
    "locality": "Warszawa",
    "country": "PL"
  },
  "phone_number": "+48 600 100 200"
}

Warstwa 3: claims

claims (oświadczenia) to pojedyncze pola wewnątrz tokenu, z których każde coś stwierdza o samym tokenie albo o jego właścicielu. Trzecia warstwa to właśnie one. Scope jest jednym z takich claimów, ale stoi obok wielu innych. Najczęstsze to:

• scope — jakie uprawnienia niesie token (np. openid profile email).
• iss (issuer) — kto wystawił token.
• aud (audience) — dla kogo token jest przeznaczony, czyli docelowe API.
• sub (subject) — identyfikator podmiotu, którego token dotyczy.
• exp (expiration) — do kiedy token jest ważny.

Rozdzielenie scope od pozostałych claimów jest ważne, bo to właśnie aud staje się kluczowy przy ograniczaniu zasięgu tokenu — wskazuje, które API ma prawo ten token przyjąć.

Do czego może być używane?

Najbardziej widoczne zastosowanie scope to logowanie społecznościowe i delegowany dostęp do danych. Kiedy aplikacja prosi o dostęp do Twojego Dysku Google, robi to przez konkretne zakresy. Szeroki drive daje wgląd we wszystkie pliki, podczas gdy węższy drive.file pozwala aplikacji widzieć wyłącznie te dokumenty, które sam jej udostępniłeś przez okno wyboru plików lub które ta aplikacja utworzyła. To podręcznikowy przykład tego, jak dobór scope wprost przekłada się na ryzyko.

Drugie zastosowanie to autoryzacja API w architekturach mikroserwisowych. Tu scope często działa dwuwarstwowo: serwer zasobów najpierw sprawdza, czy token w ogóle ma odpowiedni zakres (na przykład platform:write), a dopiero potem, czy powiązany użytkownik ma uprawnienia do konkretnego zasobu czy obszaru roboczego.

Trzecie, coraz ważniejsze pole to integracje z agentami AI. Narzędzia oparte na Model Context Protocol (MCP) działają na cudzych tokenach, więc to, jak szerokie scope dostaną, decyduje o tym, jak duże szkody może wyrządzić błędnie pokierowany albo przejęty agent.

Czym różni się od innych rozwiązań?

Najwięcej nieporozumień bierze się z mylenia scope z rolami, uprawnieniami i claimami.

Rola (w modelu RBAC^?RBAC: Role-Based Access Control — model kontroli dostępu, w którym uprawnienia przypisuje się rolom (np. admin, viewer), a użytkownikom nadaje się role) opisuje funkcję użytkownika w organizacji — ADMIN, MANAGER, VIEWER. Rola mówi, co użytkownik ma prawo zrobić. Scope natomiast mówi, co aplikacja może zrobić w jego imieniu. Jeśli administrator firmy loguje się do prostego narzędzia do synchronizacji kalendarza, to narzędzie powinno dostać zakres calendar.read, a nie odziedziczyć jego rolę ADMIN.

Uprawnienia (permissions) to ostateczna decyzja podejmowana na serwerze zasobów: czy dana operacja na konkretnym wierszu w bazie może się wykonać. Scope jest bramką wcześniejszą i grubszą — przepustką, nie pełnym regulaminem dostępu.

Claim to dowolna para klucz-wartość w tokenie. Scope jest jednym ze szczególnych claimów, ale nie każdy claim jest scope. Dobrze pokazuje to model Microsoft Graph^?Microsoft Graph: ujednolicone API Microsoftu do danych i usług Microsoft 365 (m.in. Entra ID, Outlook, Teams, SharePoint), z osobnym modelem uprawnień delegowanych i aplikacyjnych, który dzieli uprawnienia na dwa rodzaje:

• uprawnienia delegowane (scopes) — działają w imieniu zalogowanego użytkownika i są ograniczone przecięciem z jego realnymi prawami.
• uprawnienia aplikacyjne — działają bez użytkownika, w reżimie systemowym.

Scope poza OAuth

Jako nazwany parametr scope to konstrukcja OAuth 2.0^?OAuth 2.0: Open Authorization 2.0 — otwarty standard autoryzacji delegowanej (RFC 6749), pozwalający aplikacji uzyskać ograniczony dostęp do zasobów użytkownika bez jego hasła i OIDC^?OIDC: OpenID Connect — warstwa uwierzytelniania zbudowana na OAuth 2.0, dodająca tożsamość użytkownika przez ID Token (które jest warstwą na OAuth). Ale sam pomysł zawężania tego, co poświadczenie może zrobić, żyje też poza OAuth pod innymi nazwami: własne tokeny JWT z claimem scope wydawane bez przepływu OAuth, klucze API z przypisanymi uprawnieniami (na przykład Stripe restricted keys^?Stripe restricted keys: klucze API Stripe z ograniczonym, definiowanym per zasób zakresem uprawnień, zamiast pełnego dostępu klucza sekretnego), „abilities” tokenów w frameworkach takich jak Laravel Sanctum^?Laravel Sanctum: pakiet do uwierzytelniania API w Laravel, w którym tokenom przypisuje się „abilities” (zakresy) ograniczające ich uprawnienia, caveats w macaroons^?macaroons: bearer tokeny (Google) z „caveats”, czyli zagnieżdżonymi warunkami, które stopniowo zawężają uprawnienia tokenu czy bilety Kerberos^?Kerberos: sieciowy protokół uwierzytelniania, w którym bilet (ticket) jest ważny tylko dla konkretnej usługi zawężone do konkretnej usługi.

Należy uważać na pułapkę językową: słowo „scope” w innych technologiach znaczy coś zupełnie innego niż w OAuth i nie ma nic wspólnego z uprawnieniami:

• W SAML^?SAML: Security Assertion Markup Language — oparty na XML standard wymiany danych uwierzytelniania i autoryzacji między dostawcą tożsamości a usługą, używany m.in. w SSO element <Scoping> wskazuje, którego dostawcy tożsamości (IdP^?IdP: Identity Provider — system uwierzytelniający użytkowników i wystawiający ich tożsamość aplikacjom, np. w SSO) użyć — nie określa uprawnień.
• W LDAP^?LDAP: Lightweight Directory Access Protocol — protokół dostępu do katalogów (np. drzewa użytkowników i grup), powszechny w usługach katalogowych jak Active Directory „search scope” mówi, jak głęboko przeszukać drzewo katalogu (tylko obiekt, jeden poziom albo całe poddrzewo) — to zasięg wyszukiwania, nie dostęp.

Najważniejsze ograniczenia i wyzwania

Pierwotny model scope z RFC 6749 ma wbudowane słabości, które branża łata do dziś.

Consent theater

Najgłośniejsza słabość to consent theater^?consent theater: teatr zgody — pozorna zgoda: ekran uprawnień jest tak ogólny i działa w trybie „wszystko albo nic”, że użytkownik klika „Zezwól” bez zrozumienia, na co naprawdę się godzi. Na ekranie zgody uprawnienia są opisane bardzo ogólnie i działają na zasadzie „wszystko albo nic" — albo godzisz się na cały zakres, albo nie skorzystasz z aplikacji. Aplikacja, która potrzebuje znaleźć jeden e-mail, prosi o gmail.readonly, co technicznie oznacza dożywotni wgląd w całe archiwum poczty — łącznie z wiadomościami do resetu hasła, które inne serwisy przysyłają na Twoją skrzynkę. Samo odczytanie takich wiadomości wystarczy, by przejąć konta w tych serwisach. Użytkownik widzi tylko „aplikacja chce czytać Twoje maile" i niemal odruchowo klika „Zezwól". Ta iluzoryczna zgoda jest stałym wektorem ataków phishingowych^?phishing: phishing — atak socjotechniczny, w którym oszust podszywa się pod zaufaną stronę lub aplikację, by wyłudzić dane logowania albo nakłonić ofiarę do nadania uprawnień.

Confused deputy

Druga słabość to problem zdezorientowanego zastępcy. Token wydany dla jednego API, jeśli ma zbyt ogólny zakres i nie jest związany z konkretnym odbiorcą, może zostać użyty przez skompromitowaną usługę do odpytania zupełnie innego API tego samego wydawcy. Odpowiedzią jest RFC 8707 (Resource Indicators^?Resource Indicators: rozszerzenie OAuth (RFC 8707), w którym klient parametrem resource wskazuje docelowe API, a serwer wpisuje je do claimu aud, wiążąc token z konkretnym odbiorcą), który każe klientowi z góry wskazać — parametrem resource — dla którego konkretnie API prosi o token. Serwer autoryzacyjny zapisuje ten adres w tokenie jako claim aud (czyli odbiorcę tokenu). Dzięki temu każde API może sprawdzić, czy token wystawiono właśnie dla niego, a jeśli claim aud wskazuje inne API, token zostaje odrzucony.

Scope creep

Trzecie wyzwanie to scope creep i martwe integracje. Ponieważ delegacje OAuth domyślnie nie wygasają, porzucone aplikacje latami trzymają nadane im wysokie uprawnienia. Gdy firma zamyka domenę, a ktoś inny ją wykupuje, przejęte integracje mogą stać się furtką do danych użytkowników. Lekarstwem jest wymiana tokenów (RFC 8693) pozwalająca celowo zawężać uprawnienia (downscoping) zamiast przekazywać „gruby" token w głąb infrastruktury, oraz regularne czyszczenie nieużywanych zgód.

Dlaczego to jest istotne?

Scope to jeden z tych elementów infrastruktury, których przeciętny użytkownik nie widzi, a które codziennie decydują o bezpieczeństwie jego danych. Każde kliknięcie „Zaloguj przez Google", każda wtyczka podpięta do firmowego Microsoft 365, każdy agent AI sięgający do Twojej poczty — wszystko to opiera się na tym, jak zaprojektowano i przyznano zakresy.

Znaczenie scope rośnie wraz z dwoma trendami. Pierwszy to architektury rozproszone, w których jeden token wędruje przez łańcuch mikroserwisów i każdy zbędny zakres powiększa promień rażenia po ewentualnym wycieku. Drugi to eksplozja agentów AI, które działają autonomicznie na cudzych uprawnieniach — tu różnica między zakresem tylko do odczytu a zakresem do zapisu może decydować o tym, czy błędny prompt skończy się nieszkodliwie, czy katastrofą.

Branża wyraźnie zmierza w stronę większej ziarnistości: fine-grained tokeny^?fine-grained tokeny: precyzyjne tokeny dostępu (np. w GitHubie), w których nadaje się wąskie, wybrane uprawnienia do konkretnych zasobów, zamiast jednego szerokiego zakresu w GitHubie zastępujące toporny zakres repo, węższe zakresy Google, a docelowo Rich Authorization Requests^?Rich Authorization Requests: rozszerzenie OAuth (RFC 9396), w którym zamiast prostej listy scope przekazuje się strukturalny obiekt JSON precyzyjnie opisujący żądane uprawnienia (np. kwotę i odbiorcę przelewu) (RFC 9396), które pozwalają zamiast jednego słowa wyrazić strukturalną zgodę w stylu „przelew do 500 zł dla kontrahenta Y". Kierunek jest jasny — od grubego scope do precyzyjnej, czytelnej zgody. Kto rozumie scope dziś, łatwiej odnajdzie się w tej ewolucji.

Scope zaczął jako prosta lista słów oddzielonych spacjami, a stał się rdzeniem delegowanej autoryzacji w całym internecie. Jego poprawne zaprojektowanie — z poszanowaniem zasady najmniejszego uprzywilejowania — to dziś jedna z miar dojrzałości inżyniera budującego bezpieczne systemy.

Źródła

• IETF — RFC 6749: The OAuth 2.0 Authorization Framework — link
• IETF — RFC 9068: JSON Web Token Profile for OAuth 2.0 Access Tokens — link
• IETF — RFC 8707: Resource Indicators for OAuth 2.0 — link
• IETF — RFC 8693: OAuth 2.0 Token Exchange — link
• OpenID Foundation — OpenID Connect Core (Standard Scopes and Claims) — link
• Google — Using OAuth 2.0 Scopes (Drive scopes) — link
• GitHub Docs — Scopes for OAuth apps and fine-grained tokens — link