FastAPI Backend Development Bootcamp · Pelajaran

Otorisasi Berbasis Cakupan dan Pengawal Peran

Terapkan izin per titik akhir menggunakan cakupan OAuth2 dan pengawal dependensi yang dapat digunakan ulang untuk kendali akses berbasis peran.

Pelajaran 4 dari 413 langkah

Otorisasi Berbasis Cakupan dan Pengawal Peran adalah pelajaran FastAPI Backend Development Bootcamp gratis di CoddyKit. Ini adalah pelajaran 4 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar FastAPI Backend Development Bootcamp, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus FastAPI Backend Development Bootcamp mencakup 4 pelajaran total.

Bagian dari pelajaran ini belum diterjemahkan dan ditampilkan dalam bahasa Inggris.

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.

Jawab di pelajaran interaktif

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.

Gratis untuk memulai

Belajar FastAPI Backend Development Bootcamp dengan tutor AI — gratis

Tulis dan jalankan kode asli di browser kamu, dapatkan bantuan instan dari tutor AI 24/7, dan lanjutkan di mana kamu tinggalkan di web atau aplikasi.

Kursus: 21
Pelajaran: 84

Mulai belajar gratis Lihat kursus lengkapnya

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Otorisasi Berbasis Cakupan dan Pengawal Peran” gratis?

Ya — teks lengkap “Otorisasi Berbasis Cakupan dan Pengawal Peran” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus FastAPI Backend Development Bootcamp, upgrade ke CoddyKit PRO. Kursus FastAPI Backend Development Bootcamp mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Otorisasi Berbasis Cakupan dan Pengawal Peran”?

Terapkan izin per titik akhir menggunakan cakupan OAuth2 dan pengawal dependensi yang dapat digunakan ulang untuk kendali akses berbasis peran. Kamu berlatih FastAPI Backend Development Bootcamp dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai FastAPI Backend Development Bootcamp?

Tidak diperlukan pengalaman sebelumnya. FastAPI Backend Development Bootcamp di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 4 dari 4.

Berapa lama pelajaran “Otorisasi Berbasis Cakupan dan Pengawal Peran” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran FastAPI Backend Development Bootcamp ini?

Ya. Setiap pelajaran FastAPI Backend Development Bootcamp menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

Alur Kata Sandi OAuth2 dan Penerbitan Token
Menandatangani dan Memverifikasi JWT dengan python-jose
Token Penyegaran dan Rotasi Token
Otorisasi Berbasis Cakupan dan Pengawal Peran

← Kembali ke FastAPI Backend Development Bootcamp