CsrfMiddleware - simple Cross Site Request Forgery protection

PLEASE NOTE

CsrfMiddleware is now available in 'contrib' in current Django development version. See the CSRF documentation. If you are using an older version of Django, this page might still be useful.

Summary

CsrfMiddleware is a very easy to use middleware module for the Django web framework that provides protection against Cross Site Request Forgeries.

It really does work perfectly, plug-in and done :-). Even Ajax-Stuff didn't make any problems (the only thing I had to think of was to set the form method _in_ the form and not to rely on setting the XMLHttpRequest query method). Thanks!

Andreas Stuhlmüller

How it works

CsrfMiddleware does two things:

it modifies outgoing requests by adding a hidden form field to all 'POST' forms, with name 'csrfmiddlewaretoken' and a value which is a hash of the session ID plus a secret. If there is no session ID set, this modification of the response isn't done, so there is very little performance penalty for those requests that don't have a session.
on all incoming POST requests that have the session cookie set, it checks that the 'csrfmiddlewaretoken' is present and correct. If it isn't, you get a 403 error

CsrfMiddleware requires Django's session framework to work. If you have a custom authentication system that manually sets cookies and the like, it won't help you.

It deliberately only targets HTTP POST requests (and the corresponding POST forms). GET requests ought never to have side effects (if you are using HTTP GET and POST correctly), and so a CSRF attack with a GET request will always be harmless.

It also checks the Content-Type before modifying the response, and only modifies 'text/html' and 'application/xml+xhtml'.

Limitations

If your app creates HTML pages and forms in some unusual way, (e.g. it sends fragments of HTML in javascript document.write statements) you might bypass the filter that adds the hidden field to the form, in which case form submission will always fail. You will need to think carefully about the 'How it works' section. If you need a public method added to the module to work around this (e.g. to get the csrf token manually), let me know what you need.

Download

Download csrfmiddleware 1.1
Or browse the source
Or download the source with Bazaar-NG:
bzr branch http://files.lukeplant.fastmail.fm/public/python/lukeplant_me_uk/
(includes other python code)

Installation and usage

Extract the package and place it somewhere in your python path, as with all middleware classes. You then need to add two lines to your Django settings file:

Add the middleware to your list of middleware classes, MIDDLEWARE_CLASSES. It needs to process the response after the SessionMiddleware, so must come before it in the list. It also must process the response before things like compression happen to the response, so it must come after GZipMiddleware (and similar). In my project it looks something like this:
```
MIDDLEWARE_CLASSES = (
    "django.middleware.gzip.GZipMiddleware",
    "lukeplant_me_uk.django.middleware.csrf.CsrfMiddleware",
    "django.middleware.sessions.SessionMiddleware",
)
                
```
Add a setting CSRF_MIDDLEWARE_SECRET to your settings file. This must be a secret string which is used to do hashing, with a length equal to your paranoia.

LICENSE

MIT (which means in short that it is open source and free of charge for any use)

TODO

Add the ability to selectively turn it off for some requests (identifed by path). Email me if you want this — I haven't had a need for it myself yet, and YAGNI tells me not do bother doing it yet.

Changelog

Version 1.1 - 2005-12-14

Added setup.py
Avoid unnecessary work/exceptions if the request isn't a POST.

Version 1.0 - 2005-11-19

Changed packaging

2005-11-04

Initial release