FastAPI extension that provides stateless Cross-Site Request Forgery (XSRF) Protection support.
Aimed to be easy to use and lightweight, we adopt Double Submit Cookie mitigation pattern.
If you were familiar with flask-wtf
library this extension suitable for you.
This extension inspired by fastapi-jwt-auth
😀
- Storing
fastapi-csrf-token
in cookies or serve it in template's context
The easiest way to start working with this extension with pip
pip install fastapi-csrf-protect
# or
poetry add fastapi-csrf-protect
The following examples show you how to integrate this extension to a FastAPI App
from fastapi import FastAPI, Request, Depends
from fastapi.responses import JSONResponse
from fastapi.templating import Jinja2Templates
from fastapi_csrf_protect import CsrfProtect
from fastapi_csrf_protect.exceptions import CsrfProtectError
from pydantic import BaseModel
app = FastAPI()
templates = Jinja2Templates(directory="templates")
class CsrfSettings(BaseModel):
secret_key: str = "asecrettoeverybody"
cookie_samesite: str = "none"
@CsrfProtect.load_config
def get_csrf_config():
return CsrfSettings()
@app.get("/login")
def form(request: Request, csrf_protect: CsrfProtect = Depends()):
"""
Returns form template.
"""
csrf_token, signed_token = csrf_protect.generate_csrf_tokens()
response = templates.TemplateResponse(
"form.html", {"request": request, "csrf_token": csrf_token}
)
csrf_protect.set_csrf_cookie(signed_token, response)
return response
@app.post("/login", response_class=JSONResponse)
async def create_post(request: Request, csrf_protect: CsrfProtect = Depends()):
"""
Creates a new Post
"""
await csrf_protect.validate_csrf(request)
response: JSONResponse = JSONResponse(status_code=200, content={"detail": "OK"})
csrf_protect.unset_csrf_cookie(response) # prevent token reuse
return response
@app.exception_handler(CsrfProtectError)
def csrf_protect_exception_handler(request: Request, exc: CsrfProtectError):
return JSONResponse(status_code=exc.status_code, content={"detail": exc.message})
To contribute to the project, fork the repository and clone to your local device and install preferred testing dependency pytest Alternatively, run the following command on your terminal to do so:
pip install -U poetry
poetry install
Testing can be done by the following command post-installation:
poetry install --with test
pytest
- The
generate_csrf
method has now been marked for deprecation - The recommended method is now
generate_csrf_tokens
which returns a tuple of tokens, first unsigned and the latter signed - Recommended pattern is for the first token is aimed for returning as part of context
- Recommended pattern is for the signed token to be set in client's cookie completing Double Submit Cookie
- To prevent token reuse, protected endpoint can unset the signed CSRF Token in client's cookies as per example code and recommended pattern.
- New keys are added at setup
token_location
(eitherbody
orheader
) andtoken_key
is key where form-encoded keeps the csrf token stored, cross-checked with csrf secret in cookies. - Asynchronous
validate_csrf
method now needs to be awaited therefore protected endpoints need to be asynchronous as well.
To run the provided examples, first you must install extra dependencies uvicorn and jinja2 Alternatively, run the following command on your terminal to do so
poetry install --with examples
Running the example utilizing form submission
uvicorn examples.body:app
Running the example utilizing headers via JavaScript
uvicorn examples.header:app
This project is licensed under the terms of the MIT license.