0Pricing
FastAPI Backend Development Bootcamp · Lekcja

Autoryzacja oparta na zakresach i strażnicy ról

Wymuszaj uprawnienia dla poszczególnych endpointów za pomocą zakresów OAuth2 i wielokrotnego użytku strażników zależności na potrzeby kontroli dostępu opartej na rolach.

Autoryzacja oparta na zakresach i strażnicy ról to bezpłatna lekcja FastAPI Backend Development Bootcamp na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej FastAPI Backend Development Bootcamp, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs FastAPI Backend Development Bootcamp zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

Authentication vs Authorization

Once a user proves who they are (authentication), you still need to decide what they are allowed to do. That second step is authorization.

  • Authentication answers: who are you? (verify the JWT)
  • Authorization answers: are you permitted to call this endpoint?

In OAuth2, fine-grained permissions are expressed as scopes — short strings like items:read or users:write. Each token carries the scopes that were granted, and each endpoint declares the scopes it requires.

What a Scope Looks Like

A scope is just a label for a permission. By convention they use a resource:action shape, which keeps them readable as your API grows.

  • items:read — list or fetch items
  • items:write — create or update items
  • admin — full administrative access

The JWT stores granted scopes, usually as a space-separated string in a scopes claim. Here is a tiny helper that parses and checks them.

def has_scope(token_scopes: str, required: str) -> bool:
    granted = token_scopes.split()
    return required in granted

claim = "items:read items:write"
print(has_scope(claim, "items:read"))   # True
print(has_scope(claim, "admin"))        # False

Declaring Scopes on the OAuth2 Scheme

FastAPI's OAuth2PasswordBearer accepts a scopes dictionary that documents every scope your API understands. This powers the interactive docs so testers can request specific permissions.

The mapping is { scope_name: human_description }. It does not grant anything by itself — it just describes what exists.

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(
    tokenUrl="token",
    scopes={
        "items:read": "Read items.",
        "items:write": "Create or update items.",
        "admin": "Full administrative access.",
    },
)

Encoding Granted Scopes Into the JWT

When a user logs in, you decide which scopes they get (often based on their role) and embed them in the token. Store them in a scopes claim so every later request carries the permissions.

The token request form includes a scope field; you should grant only scopes the user is actually entitled to — never blindly echo what the client asked for.

from datetime import datetime, timedelta, timezone
import jwt  # PyJWT

SECRET = "change-me"

def create_token(username: str, scopes: list[str]) -> str:
    payload = {
        "sub": username,
        "scopes": scopes,
        "exp": datetime.now(timezone.utc) + timedelta(minutes=30),
    }
    return jwt.encode(payload, SECRET, algorithm="HS256")

Requiring Scopes with the Security Helper

To require a scope on an endpoint, declare the dependency with Security(...) (not plain Depends) and pass a scopes list. FastAPI collects all required scopes along the dependency tree and exposes them via a SecurityScopes object.

Below, the endpoint demands the items:read scope before read_items ever runs.

from fastapi import Depends, Security, FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(
    user=Security(get_current_user, scopes=["items:read"]),
):
    return {"owner": user["username"]}

Validating Scopes in the Dependency

The dependency that resolves the current user receives a SecurityScopes argument listing every scope required by the route. You decode the JWT, read the granted scopes, and reject the request if any required scope is missing.

  • Return 401 if the token is invalid or expired.
  • Return 403 if the token is valid but lacks the scope (the user is known but not permitted).
from fastapi import Depends, HTTPException, status
from fastapi.security import SecurityScopes
import jwt

async def get_current_user(
    security_scopes: SecurityScopes,
    token: str = Depends(oauth2_scheme),
):
    try:
        payload = jwt.decode(token, SECRET, algorithms=["HS256"])
    except jwt.PyJWTError:
        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid token")
    token_scopes = payload.get("scopes", [])
    for scope in security_scopes.scopes:
        if scope not in token_scopes:
            raise HTTPException(
                status.HTTP_403_FORBIDDEN,
                detail=f"Not enough permissions: {scope}",
            )
    return {"username": payload["sub"], "scopes": token_scopes}

The WWW-Authenticate Header

OAuth2 expects a 401 response to include a WWW-Authenticate header describing how to authenticate. When scopes are involved, that header should also list the required scopes so the client knows what to request.

FastAPI's SecurityScopes object builds this string for you via scope_str.

from fastapi.security import SecurityScopes
from fastapi import HTTPException, status

def auth_error(security_scopes: SecurityScopes, detail: str):
    if security_scopes.scopes:
        value = f'Bearer scope="{security_scopes.scope_str}"'
    else:
        value = "Bearer"
    return HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail=detail,
        headers={"WWW-Authenticate": value},
    )

From Scopes to Roles

Scopes are flexible but granular. Most apps also think in roles — admin, editor, viewer — where each role bundles a set of scopes. A clean approach is to map roles to scopes at login time.

This keeps endpoints declaring fine-grained scopes while users are managed by coarse-grained roles.

ROLE_SCOPES = {
    "admin": ["items:read", "items:write", "admin"],
    "editor": ["items:read", "items:write"],
    "viewer": ["items:read"],
}

def scopes_for_role(role: str) -> list[str]:
    return ROLE_SCOPES.get(role, [])

print(scopes_for_role("editor"))  # ['items:read', 'items:write']
print(scopes_for_role("guest"))   # []

A Reusable Role Guard

Sometimes you want to guard by role directly instead of by scope. A guard factory returns a dependency configured for a specific role, so you can reuse it across many endpoints.

Calling require_role("admin") produces a dependency that rejects anyone whose token role is not admin.

from fastapi import Depends, HTTPException, status

def require_role(required_role: str):
    async def guard(user=Depends(get_current_user)):
        if user.get("role") != required_role:
            raise HTTPException(
                status.HTTP_403_FORBIDDEN,
                detail="Insufficient role",
            )
        return user
    return guard

@app.delete("/items/{item_id}")
async def delete_item(item_id: int, user=Depends(require_role("admin"))):
    return {"deleted": item_id, "by": user["username"]}

Guarding by 'Any of' Several Roles

Real endpoints often allow more than one role. Generalize the guard to accept a set of acceptable roles and pass if the user matches any of them.

This pure-Python pattern is easy to unit test without spinning up a server.

def check_access(user_role: str, allowed: set[str]) -> bool:
    return user_role in allowed

print(check_access("editor", {"editor", "admin"}))  # True
print(check_access("viewer", {"editor", "admin"}))  # False
print(check_access("admin", {"admin"}))             # True

Putting It Together

A complete flow looks like this:

  • Login maps the user's role to scopes and signs a JWT.
  • Each endpoint declares required scopes with Security(get_current_user, scopes=[...]).
  • The dependency decodes the token and verifies every required scope is present.
  • Reusable require_role guards handle coarse role checks where scopes are overkill.

Because guards are just dependencies, they compose: an endpoint can require both a scope and a role, and FastAPI runs both before your handler.

@app.post("/admin/reports")
async def make_report(
    admin=Depends(require_role("admin")),
    user=Security(get_current_user, scopes=["admin"]),
):
    return {"status": "generated", "by": user["username"]}

Quick Check

Choose the response that correctly distinguishes authentication failure from authorization failure for scope checks.

Recap

You now know how to enforce per-endpoint permissions in FastAPI:

  • Scopes are granular resource:action permissions stored in the JWT's scopes claim.
  • Declare required scopes with Security(dep, scopes=[...]); FastAPI gathers them into SecurityScopes.
  • The dependency decodes the token, returns 401 for invalid credentials and 403 when a required scope is missing.
  • Add a WWW-Authenticate header (with scope_str) on 401 responses for OAuth2 compliance.
  • Roles bundle scopes; map role to scopes at login, and use a reusable require_role guard factory for coarse role-based access control.

Because guards are ordinary dependencies, they compose cleanly and keep authorization logic out of your handlers.

Często zadawane pytania

Czy lekcja „Autoryzacja oparta na zakresach i strażnicy ról” jest bezpłatna?

Tak — pełny tekst „Autoryzacja oparta na zakresach i strażnicy ról” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu FastAPI Backend Development Bootcamp, przejdź na CoddyKit PRO. Kurs FastAPI Backend Development Bootcamp zawiera 4 lekcji w sumie.

Co nauczysz się w „Autoryzacja oparta na zakresach i strażnicy ról”?

Wymuszaj uprawnienia dla poszczególnych endpointów za pomocą zakresów OAuth2 i wielokrotnego użytku strażników zależności na potrzeby kontroli dostępu opartej na rolach. Ćwiczysz FastAPI Backend Development Bootcamp z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć FastAPI Backend Development Bootcamp?

Nie wymagamy żadnego doświadczenia. FastAPI Backend Development Bootcamp w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Autoryzacja oparta na zakresach i strażnicy ról”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji FastAPI Backend Development Bootcamp?

Tak. Każda lekcja FastAPI Backend Development Bootcamp zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Przepływ haseł OAuth2 i wydawanie tokenów
  2. Podpisywanie i weryfikowanie JWT za pomocą python-jose
  3. Tokeny odświeżania i rotacja tokenów
  4. Autoryzacja oparta na zakresach i strażnicy ról
← Powrót do FastAPI Backend Development Bootcamp