FastAPI-Topaz

FastAPI-Topaz asks a Topaz authorizer whether each request may proceed, and returns HTTP 403 Forbidden when the answer is no.

Full documentation: jmanteau.github.io/fastapi-topaz

Upgrading from 1.x? See Upgrading to 2.0.

How it works

Your FastAPI app sends the user's identity and the route to Topaz. Topaz evaluates a policy and returns allowed or denied.

flowchart LR
    C[Client] --> F[FastAPI route]
    F --> D["Dependency<br/>or TopazMiddleware"]
    D --> TC[TopazConfig]
    TC -->|"gRPC"| T[Topaz authorizer]
    T --> P["Policies (Rego)"]
    T --> R["Directory (relationships)"]
    TC -.->|"denied"| X[HTTP 403]

Requirements

• Python 3.10 or later
• FastAPI 0.100 or later (except 0.137.0 and 0.137.1)
• A running Topaz instance

Install

pip install fastapi-topaz

Quick start

This example protects GET /documents. Topaz evaluates the policy myapp.GET.documents for the user in request.state.user_id.

from fastapi import Depends, FastAPI, Request
from fastapi_topaz import (
    AuthorizerOptions,
    Identity,
    IdentityType,
    TopazConfig,
    require_policy_allowed,
)

config = TopazConfig(
    authorizer_options=AuthorizerOptions(url="localhost:8282"),
    policy_path_root="myapp",
    identity_provider=lambda req: Identity(
        type=IdentityType.IDENTITY_TYPE_SUB,
        value=req.state.user_id,
    ),
    policy_instance_name="myapp",
)

app = FastAPI()

@app.get("/documents")
async def list_documents(
    request: Request,
    _: None = Depends(require_policy_allowed(config, "myapp.GET.documents")),
):
    return {"documents": [...]}

Choose a check

Pick the check that matches your question. Not sure which one? Read Choosing an authorization approach.

require_policy_auto() builds the policy name from the HTTP method and the route template:

Example of a relationship check: the user must have the can_write relation on the document whose ID is in the {id} path parameter.

@app.put("/documents/{id}")
async def update_document(
    id: int,
    _: None = Depends(require_rebac_allowed(config, "document", "can_write")),
):
    ...

Production features

Turn each feature on by passing an object to TopazConfig. All are optional.

Command-line tool

The package installs a fastapi-topaz command. Each subcommand reads your app from module:attribute.

fastapi-topaz policy-diff --app myapp.main:app --policies policies/

Full options: CLI reference. Source: cli.py L329.

Terms

Documentation

The documentation follows the Diátaxis framework.

Related: Topaz documentation · FastAPI documentation

License

Apache 2.0