Package: asgi-csrf
asgi-csrfASGI middleware for protecting against CSRF attacksInstallationpip install asgi-csrfBackgroundSee theOWASP guide to Cross Site Request Forgery (CSRF)and theirCross-Site Request Forgery (CSRF) Prevention Cheat Sheet.This middleware implements theDouble Submit Cookie pattern, where a cookie is set that is then compared to acsrftokenhidden form field or ax-csrftokenHTTP header.UsageDecorate your ASGI application like this:fromasgi_csrfimportasgi_csrffrom.my_asgi_appimportappapp=asgi_csrf(app,signing_secret="secret-goes-here")The middleware will set acsrftokencookie, if one is missing. The value of that token will be made available to your ASGI application through thescope["csrftoken"]function.Your application code should include that value as a hidden form field in any POST forms:<formaction="/login"method="POST">...<inputtype="hidden"name="csrftoken"value="{{ request.scope.csrftoken() }}"></form>Note thatrequest.scope["csrftoken"]()is a function that returns a string. Calling that function also lets the middleware know that the cookie should be set by that page, if the user does not already have that cookie.If the cookie needs to be set, the middleware will add aVary: Cookieheader to the response to ensure it is not incorrectly cached by any CDNs or intermediary proxies.The middleware will return a 403 forbidden error for any POST requests that do not include the matchingcsrftoken- either in the POST data or in ax-csrftokenHTTP header (useful for JavaScriptfetch()calls).Thesigning_secretis used to sign the tokens, to protect against subdomain vulnerabilities.If you do not pass in an explicitsigning_secretparameter, the middleware will look for aASGI_CSRF_SECRETenvironment variable.If it cannot find that environment variable, it will generate a random secret which will persist for the lifetime of the server.This means that if you do not configure a specific secret your user'scsrftokencookies will become invalid every time the server restarts! You should configure a secret.Always setting the cookie if it is not already setBy default this middleware only sets thecsrftokencookie if the user encounters a page that needs it - due to that page calling therequest.scope["csrftoken"]()function, for example to populate a hidden field in a form.If you would like the middleware to set that cookie for any incoming request that does not already provide the cookie, you can use thealways_set_cookie=Trueargument:app=asgi_csrf(app,signing_secret="secret-goes-here",always_set_cookie=True)Other cases that skip CSRF protectionIf the request includes anAuthorization: Bearer ...header, commonly used by OAuth and JWT authentication, the request will not be required to include a CSRF token. This is because browsers cannot send those headers in a context that can be abused.If the request has no cookies at all it will be allowed through, since CSRF protection is only necessary for requests from authenticated users.always_protectIf you have paths that should always be protected even without cookies - your login form for example (to avoidlogin CSRFattacks) you can protect those paths by passing them as thealways_protectparameter:app=asgi_csrf(app,signing_secret="secret-goes-here",always_protect={"/login"})skip_if_scopeThere may be situations in which you want to opt-out of CSRF protection even for authenticated POST requests - this is often the case for web APIs for example.Theskip_if_scope=parameter can be used to provide a callback function which is passed an ASGI scope and returnsTrueif CSRF protection should be skipped for that request.This example skips CSRF protection for any incoming request where the request path starts with/api/:defskip_api_paths(scope)returnscope["path"].startswith("/api/")app=asgi_csrf(app,signing_secret="secret-goes-here",skip_if_scope=skip_api_paths)