The CsrfMiddleware class provides easy-to-use protection against Cross Site Request Forgeries. This type of attack occurs when a malicious Web site creates a link or form button that is intended to perform some action on your Web site, using the credentials of a logged-in user who is tricked into clicking on the link in their browser.
The first defense against CSRF attacks is to ensure that GET requests are side-effect free. POST requests can then be protected by adding this middleware into your list of installed middleware.
Add the middleware 'django.contrib.csrf.middleware.CsrfMiddleware' 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 in the list.
The CsrfMiddleware class is actually composed of two middleware: CsrfViewMiddleware which performs the checks on incoming requests, and CsrfResponseMiddleware which performs post-processing of the result. This allows the individual components to be used and/or replaced instead of using CsrfMiddleware.
While the above method can be used with AJAX POST requests, it has some inconveniences: you have to remember to get the CSRF token from the HTML document and pass it in as POST data with every POST request. For this reason, there is an alternative method: on each XMLHttpRequest, set a custom X-CSRFToken header to the value of the CSRF token. This is often easier, because many javascript frameworks provide hooks that allow headers to be set on every request. In jQuery, you can use the beforeSend hook as follows:
$.ajaxSetup({
beforeSend: function(xhr, settings) {
if (!(/^http:.*/.test(settings.url) || /^https:.*/.test(settings.url))) {
// Only send the token to relative URLs i.e. locally.
xhr.setRequestHeader("X-CSRFToken",
$("#csrfmiddlewaretoken").val());
}
}
});
Adding this to a javascript file that is included on your site will ensure that AJAX POST requests that are made via jQuery will not be caught by the CSRF protection. This will only work if you remember to include a form on the page, so that the input with id 'csrfmiddlewaretoken' will be found.
To manually exclude a view function from being handled by the CsrfMiddleware, you can use the csrf_exempt decorator, found in the django.contrib.csrf.middleware module. For example:
from django.contrib.csrf.middleware import csrf_exempt
def my_view(request):
return HttpResponse('Hello world')
my_view = csrf_exempt(my_view)
Like the middleware itself, the csrf_exempt decorator is composed of two parts: a csrf_view_exempt decorator and a csrf_response_exempt decorator, found in the same module. These disable the view protection mechanism (CsrfViewMiddleware) and the response post-processing (CsrfResponseMiddleware) respectively. They can be used individually if required.
CsrfMiddleware does two things:
This ensures that only forms that have originated from your Web site can be used to POST data back.
It deliberately only targets HTTP POST requests (and the corresponding POST forms). GET requests ought never to have any potentially dangerous side effects (see 9.1.1 Safe Methods, HTTP 1.1, RFC 2616), and so a CSRF attack with a GET request ought to be harmless.
POST requests that are not accompanied by a session cookie are not protected, but they do not need to be protected, since the 'attacking' Web site could make these kind of requests anyway.
The Content-Type is checked before modifying the response, and only pages that are served as 'text/html' or 'application/xml+xhtml' are modified.
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.
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. It may still be possible to use the middleware, provided you can find some way to get the CSRF token and ensure that is included when your form is submitted.
Mar 05, 2013