Ensuring that the sites you build are secure is of the utmost importance to a professional web applications developer.
The Django framework is now very mature and the majority of common security issues are addressed in some way by the framework itself, however no security measure is 100% guaranteed and there are new threats emerging all the time, so it's up to you as a web developer to ensure that your websites and applications are secure.
web security is too large a subject to cover in depth in a single book chapter. This chapter includes an overview of Django's security features and advice on securing a Django-powered site that will protect your sites 99% of the time, but it's up to you to keep abreast of changes in web security.
For more detailed information on web security, Django's archive of security issues(for more information visit https://docs.djangoproject.com/en/1.8/releases/security/) is a good place to start, along with Wikipedia's web application security page (https://en.wikipedia.org/wiki/web_application_security).
Cross Site Scripting (XSS) attacks allow a user to inject client side scripts into the browsers of other users.
This is usually achieved by storing the malicious scripts in the database where it will be retrieved and displayed to other users, or by getting users to click a link which will cause the attacker's JavaScript to be executed by the user's browser. However, XSS attacks can originate from any untrusted source of data, such as cookies or web services, whenever the data is not sufficiently sanitized before including in a page.
Using Django templates protects you against the majority of XSS attacks. However, it is important to understand what protections it provides and its limitations.
Django templates escape specific characters which are particularly dangerous to HTML. While this protects users from most malicious input, it is not entirely foolproof. For example, it will not protect the following:
<style class={{ var }}>...</style>
If var
is set to 'class1 onmouseover=javascript:func()'
, this can result in unauthorized JavaScript execution, depending on how the browser renders imperfect HTML. (Quoting the attribute value would fix this case).
It is also important to be particularly careful when using is_safe
with custom template tags, the safe
template tag, mark_safe
, and when autoescape
is turned off.
In addition, if you are using the template system to output something other than HTML, there may be entirely separate characters and words which require escaping.
You should also be very careful when storing HTML in the database, especially when that HTML is retrieved and displayed.
Cross Site Request Forgery (CSRF) attacks allow a malicious user to execute actions using the credentials of another user without that user's knowledge or consent.
Django has built-in protection against most types of CSRF attacks, providing you have enabled and used it where appropriate. However, as with any mitigation technique, there are limitations.
For example, it is possible to disable the CSRF module globally or for particular views. You should only do this if you know what you are doing. There are other limitations if your site has subdomains that are outside of your control.
CSRF protection works by checking for a nonce in each POST
request. This ensures that a malicious user cannot simply replay a form POST
to your website and have another logged in user unwittingly submit that form. The malicious user would have to know the nonce, which is user specific (using a cookie).
When deployed with HTTPS, CsrfViewMiddleware
will check that the HTTP referrer header is set to a URL on the same origin (including subdomain and port). Because HTTPS provides additional security, it is imperative to ensure connections use HTTPS where it is available by forwarding insecure connection requests and using HSTS for supported browsers.
Be very careful with marking views with the csrf_exempt
decorator unless it is absolutely necessary.
Django's CSRF middleware and template tag provides easy-to-use protection against Cross Site Request Forgeries.
The first defense against CSRF attacks is to ensure that GET
requests (and other 'safe' methods, as defined by 9.1.1 Safe Methods, HTTP 1.1, RFC 2616 (for more information visit https://tools.ietf.org/html/rfc2616.html#section-9.1.1)) are side-effect free. Requests via 'unsafe' methods, such as POST
, PUT
and DELETE
, can then be protected by following the steps below.
To take advantage of CSRF protection in your views, follow these steps:
MIDDLEWARE_CLASSES
setting. If you override that setting, remember that 'django.middleware.csrf.CsrfViewMiddleware'
should come before any view middleware that assume that CSRF attacks have been dealt with.csrf_protect()
on particular views you want to protect (see below).POST
form, use the csrf_token
tag inside the <form>
element if the form is for an internal URL, for example:<form action="." method="post">{% csrf_token %}
POST
forms that target external URLs, since that would cause the CSRF token to be leaked, leading to a vulnerability.'django.template.context_processors.csrf'
context processor is being used. Usually, this can be done in one of two ways:RequestContext
, which always uses 'django.template.context_processors.csrf'
(no matter what template context processors are configured in the TEMPLATES
setting). If you are using generic views or contrib apps, you are covered already, since these apps use RequestContext
throughout.from django.shortcuts import render_to_response from django.template.context_processors import csrf def my_view(request): c = {} c.update(csrf(request)) # ... view code here return render_to_response("a_template.html", c)
render_to_response()
wrapper that takes care of this step for you.While the above method can be used for AJAX POST requests, it has some inconveniences: you have to remember to pass the CSRF token 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.
As a first step, you must get the CSRF token itself. The recommended source for the token is the csrftoken
cookie, which will be set if you've enabled CSRF protection for your views as outlined above.
The CSRF token cookie is named csrftoken
by default, but you can control the cookie name via the CSRF_COOKIE_NAME
setting.
Acquiring the token is straightforward:
// using jQuery function getCookie(name) { var cookieValue = null; if (document.cookie && document.cookie != '') { var cookies = document.cookie.split(';'); for (var i = 0; i < cookies.length; i++) { var cookie = jQuery.trim(cookies[i]); // Does this cookie string begin with the name we want? if (cookie.substring(0, name.length + 1) == (name + '=')) { cookieValue = decodeURIComponent(cookie.substring(name.length + 1)); break; } } } return cookieValue; } var csrftoken = getCookie('csrftoken');
The above code could be simplified by using the jQuery cookie plugin (http://plugins.jquery.com/cookie/) to replace getCookie
:
var csrftoken = $.cookie('csrftoken');
The CSRF token is also present in the DOM, but only if explicitly included using csrf_token
in a template. The cookie contains the canonical token; the CsrfViewMiddleware
will prefer the cookie to the token in the DOM. Regardless, you're guaranteed to have the cookie if the token is present in the DOM, so you should use the cookie!
If your view is not rendering a template containing the csrf_token
template tag, Django might not set the CSRF token cookie. This is common in cases where forms are dynamically added to the page. To address this case, Django provides a view decorator which forces setting of the cookie: ensure_csrf_cookie()
.
Finally, you'll have to actually set the header on your AJAX request, while protecting the CSRF token from being sent to other domains using settings.crossDomain
in jQuery 1.5.1 and newer:
function csrfSafeMethod(method) { // these HTTP methods do not require CSRF protection return (/^(GET|HEAD|OPTIONS|TRACE)$/.test(method)); } $.ajaxSetup({ beforeSend: function(xhr, settings) { if (!csrfSafeMethod(settings.type) && !this.crossDomain) { xhr.setRequestHeader("X-CSRFToken", csrftoken); } } });
When using a different template engine than Django's built-in engine, you can set the token in your forms manually after making sure it's available in the template context.
For example, in the Jinja2 template language, your form could contain the following:
<div style="display:none"> <input type="hidden" name="csrfmiddlewaretoken" value="{{ csrf_token }}"> </div>
You can use JavaScript similar to the AJAX code above to get the value of the CSRF token.
Rather than adding CsrfViewMiddleware
as a blanket protection, you can use the csrf_protect
decorator, which has exactly the same functionality, on particular views that need the protection. It must be used both on views that insert the CSRF token in the output, and on those that accept the POST
form data. (These are often the same view function, but not always).
Use of the decorator by itself is not recommended, since if you forget to use it, you will have a security hole. The belt and braces strategy of using both is fine, and will incur minimal overhead.
django.views.decorators.csrf.csrf_protect(view)
Decorator that provides the protection of CsrfViewMiddleware
to a view.
Usage:
from django.views.decorators.csrf import csrf_protect from django.shortcuts import render @csrf_protect def my_view(request): c = {} # ... return render(request, "a_template.html", c)
If you are using class-based views, you can refer to Decorating class-based views.
By default, a 403 Forbidden response is sent to the user if an incoming request fails the checks performed by CsrfViewMiddleware
. This should usually only be seen when there is a genuine Cross Site Request Forgery, or when, due to a programming error, the CSRF token has not been included with a POST
form.
The error page, however, is not very friendly, so you may want to provide your own view for handling this condition. To do this, simply set the CSRF_FAILURE_VIEW
setting.
The CSRF protection is based on the following things:
CsrfViewMiddleware
. It is meant to be permanent, but since there is no way to set a cookie that never expires, it is sent with every response that has called django.middleware.csrf.get_token()
(the function used internally to retrieve the CSRF token).GET
, HEAD
, OPTIONS
, or TRACE
, a CSRF cookie must be present, and the csrfmiddlewaretoken field must be present and correct. If it isn't, the user will get a 403 error.CsrfViewMiddleware
.CsrfViewMiddleware
. This is necessary to address a Man-In-The-Middle attack that is possible under HTTPS when using a session independent nonce, due to the fact that HTTP 'Set-Cookie' headers are (unfortunately) accepted by clients that are talking to a site under HTTPS. (Referer checking is not done for HTTP requests because the presence of the Referer header is not reliable enough under HTTP.)This ensures that only forms that have originated from your website can be used to POST
data back.
It deliberately ignores GET
requests (and other requests that are defined as 'safe' by RFC 2616). These requests ought never to have any potentially dangerous side effects, and so a CSRF attack with a GET
request ought to be harmless. RFC 2616 defines POST
, PUT
, and DELETE
as 'unsafe', and all other methods are assumed to be unsafe, for maximum protection.
If the csrf_token
template tag is used by a template (or the get_token
function is called some other way), CsrfViewMiddleware
will add a cookie and a Vary: Cookie
header to the response. This means that the middleware will play well with the cache middleware if it is used as instructed (UpdateCacheMiddleware
goes before all other middleware).
However, if you use cache decorators on individual views, the CSRF middleware will not yet have been able to set the Vary
header or the CSRF cookie, and the response will be cached without either one.
In this case, on any views that will require a CSRF token to be inserted you should use the django.views.decorators.csrf.csrf_protect()
decorator first:
from django.views.decorators.cache import cache_page from django.views.decorators.csrf import csrf_protect @cache_page(60 * 15) @csrf_protect def my_view(request): ...
If you are using class-based views, you can refer to decorating class-based views in the Django documentation (https://docs.djangoproject.com/en/1.8/topics/class-based-views/intro/#decorating-class-based-views).
The CsrfViewMiddleware
will usually be a big hindrance to testing view functions, due to the need for the CSRF token which must be sent with every POST
request. For this reason, Django's HTTP client for tests has been modified to set a flag on requests which relaxes the middleware and the csrf_protect
decorator so that they no longer rejects requests. In every other respect (for example, sending cookies and so on), they behave the same.
If, for some reason, you want the test client to perform CSRF checks, you can create an instance of the test client that enforces CSRF checks:
>>> from django.test import Client >>> csrf_client = Client(enforce_csrf_checks=True)
Subdomains within a site will be able to set cookies on the client for the whole domain. By setting the cookie and using a corresponding token, subdomains will be able to circumvent the CSRF protection. The only way to avoid this is to ensure that subdomains are controlled by trusted users (or, are at least unable to set cookies).
Note that even without CSRF, there are other vulnerabilities, such as session fixation, that make giving subdomains to untrusted parties a bad idea, and these vulnerabilities cannot easily be fixed with current browsers.
Certain views can have unusual requirements that mean they don't fit the normal pattern envisaged here. A number of utilities can be useful in these situations. The scenarios they might be needed in are described in the following section.
The examples below assume you are using function-based views. If you are working with class-based views, you can refer to decorating class-based views in the Django documentation.
Most views require CSRF protection, but a few do not. Rather than disabling the middleware and applying csrf_protect
to all the views that need it, enable the middleware and use csrf_exempt()
.
This decorator marks a view as being exempt from the protection ensured by the middleware. Example:
from django.views.decorators.csrf import csrf_exempt from django.http import HttpResponse @csrf_exempt def my_view(request): return HttpResponse('Hello world')
There are cases when CsrfViewMiddleware.process_view
may not have run before your view is run-404 and 500 handlers, for example-but you still need the CSRF token in a form.
Normally the csrf_token
template tag will not work if CsrfViewMiddleware.process_view
or an equivalent like csrf_protect
has not run. The view decorator requires_csrf_token
can be used to ensure the template tag does work. This decorator works similarly to csrf_protect
, but never rejects an incoming request.
Example:
from django.views.decorators.csrf import requires_csrf_token from django.shortcuts import render @requires_csrf_token def my_view(request): c = {} # ... return render(request, "a_template.html", c)
There may also be some views that are unprotected and have been exempted by csrf_exempt
, but still need to include the CSRF token. In these cases, use csrf_exempt()
followed by requires_csrf_token()
. (that is, requires_csrf_token
should be the innermost decorator).
A final example is where a view needs CSRF protection under one set of conditions only, and mustn't have it for the rest of the time. A solution is to use csrf_exempt()
for the whole view function, and csrf_protect()
for the path within it that needs protection.
For example:
from django.views.decorators.csrf import csrf_exempt, csrf_protect @csrf_exempt def my_view(request): @csrf_protect def protected_path(request): do_something() if some_condition(): return protected_path(request) else: do_something_else()
This decorator forces a view to send the CSRF cookie. A scenario where this would be used is if a page makes a POST request via AJAX, and the page does not have an HTML form with a csrf_token
that would cause the required CSRF cookie to be sent. The solution would be to use ensure_csrf_cookie()
on the view that sends the page.
Because it is possible for the developer to turn off the CsrfViewMiddleware
, all relevant views in contrib apps use the csrf_protect
decorator to ensure the security of these applications against CSRF. It is recommended that the developers of other reusable apps that want the same guarantees also use the csrf_protect
decorator on their views.
A number of settings can be used to control Django's CSRF behavior:
CSRF_COOKIE_AGE
CSRF_COOKIE_DOMAIN
CSRF_COOKIE_HTTPONLY
CSRF_COOKIE_NAME
CSRF_COOKIE_PATH
CSRF_COOKIE_SECURE
CSRF_FAILURE_VIEW
See Appendix D, Settings, for more information on each of these settings.
SQL injection is a type of attack where a malicious user is able to execute arbitrary SQL code on a database. This can result in records being deleted or data leakage.
By using Django's querysets, the resulting SQL will be properly escaped by the underlying database driver. However, Django also gives developers power to write raw queries or execute custom SQL. These capabilities should be used sparingly and you should always be careful to properly escape any parameters that the user can control. In addition, you should exercise caution when using extra()
.
Clickjacking is a type of attack where a malicious site wraps another site in a frame. This type of attack occurs when a malicious site tricks a user into clicking on a concealed element of another site which they have loaded in a hidden frame or iframe.
Django contains clickjacking protection in the form of the X-Frame-Options middleware
which in a supporting browser can prevent a site from being rendered inside a frame. It is possible to disable the protection on a per view basis or to configure the exact header value sent.
The middleware is strongly recommended for any site that does not need to have its pages wrapped in a frame by third party sites, or only needs to allow that for a small section of the site.
Suppose an online store has a page where a logged in user can click Buy Now to purchase an item. A user has chosen to stay logged into the store all the time for convenience. An attacker site might create an I Like Ponies button on one of their own pages, and load the store's page in a transparent iframe
such that the Buy Now button is invisibly overlaid on the I Like Ponies button. If the user visits the attacker's site, clicking I Like Ponies will cause an inadvertent click on the Buy Now button and an unknowing purchase of the item.
Modern browsers honor the X-Frame-Options (for more information visit https://developer.mozilla.org/en/The_X-FRAME-OPTIONS_response_header) HTTP header that indicates whether or not a resource is allowed to load within a frame or iframe. If the response contains the header with a value of SAMEORIGIN
then the browser will only load the resource in a frame if the request originated from the same site. If the header is set to DENY
then the browser will block the resource from loading in a frame no matter which site made the request.
Django provides a few simple ways to include this header in responses from your site:
To set the same X-Frame-Options
value for all responses in your site, put 'django.middleware.clickjacking.XFrameOptionsMiddleware'
to MIDDLEWARE_CLASSES
:
MIDDLEWARE_CLASSES = [ # ... 'django.middleware.clickjacking.XFrameOptionsMiddleware', # ... ]
This middleware is enabled in the settings file generated by startproject
.
By default, the middleware will set the X-Frame-Options
header to SAMEORIGIN
for every outgoing HttpResponse
. If you want DENY
instead, set the X_FRAME_OPTIONS
setting:
X_FRAME_OPTIONS = 'DENY'
When using the middleware there may be some views where you do not want the X-Frame-Options
header set. For those cases, you can use a view decorator that tells the middleware not to set the header:
from django.http import HttpResponse from django.views.decorators.clickjacking import xframe_options_exempt @xframe_options_exempt def ok_to_load_in_a_frame(request): return HttpResponse("This page is safe to load in a frame on any site.")
To set the X-Frame-Options
header on a per view basis, Django provides these decorators:
from django.http import HttpResponse from django.views.decorators.clickjacking import xframe_options_deny from django.views.decorators.clickjacking import xframe_options_sameorigin @xframe_options_deny def view_one(request): return HttpResponse("I won't display in any frame!") @xframe_options_sameorigin def view_two(request): return HttpResponse("Display in a frame if it's from the same origin as me.")
Note that you can use the decorators in conjunction with the middleware. Use of a decorator overrides the middleware.
The X-Frame-Options
header will only protect against clickjacking in a modern browser. Older browsers will quietly ignore the header and need other clickjacking prevention techniques.
It is always better for security, though not always practical in all cases, to deploy your site behind HTTPS. Without this, it is possible for malicious network users to sniff authentication credentials or any other information transferred between client and server, and in some cases-active network attackers-to alter data that is sent in either direction.
If you want the protection that HTTPS provides, and have enabled it on your server, there are some additional steps you may need:
SECURE_PROXY_SSL_HEADER
, ensuring that you have understood the warnings there thoroughly. Failure to do this can result in CSRF vulnerabilities, and failure to do it correctly can also be dangerous!SECURE_PROXY_SSL_HEADER
. For the case of a reverse proxy, it may be easier or more secure to configure the main web server to do the redirect to HTTPS.SESSION_COOKIE_SECURE
and CSRF_COOKIE_SECURE
settings to True
. This instructs the browser to only send these cookies over HTTPS connections. Note that this will mean that sessions will not work over HTTP, and the CSRF protection will prevent any POST
data being accepted over HTTP (which will be fine if you are redirecting all HTTP traffic to HTTPS).For sites that should only be accessed over HTTPS, you can instruct modern browsers to refuse to connect to your domain name via an insecure connection (for a given period of time) by setting the Strict-Transport-Security header. This reduces your exposure to some SSL-stripping Man-In-The-Middle (MITM) attacks.
SecurityMiddleware
will set this header for you on all HTTPS responses if you set the SECURE_HSTS_SECONDS
setting to a non-zero integer value.
When enabling HSTS, it's a good idea to first use a small value for testing, for example, SECURE_HSTS_SECONDS = 3600
for one hour. Each time a web browser sees the HSTS header from your site, it will refuse to communicate non-securely (using HTTP) with your domain for the given period of time.
Once you confirm that all assets are served securely on your site (that is, HSTS didn't break anything), it's a good idea to increase this value so that infrequent visitors will be protected (31536000 seconds, that is, 1 year, is common).
Additionally, if you set the SECURE_HSTS_INCLUDE_SUBDOMAINS
setting to True
, SecurityMiddleware
will add the includeSubDomains
tag to the Strict-Transport-Security
header. This is recommended (assuming all subdomains are served exclusively using HTTPS), otherwise your site may still be vulnerable via an insecure connection to a subdomain.
The HSTS policy applies to your entire domain, not just the URL of the response that you set the header on. Therefore, you should only use it if your entire domain is served via HTTPS only.
Browsers properly respecting the HSTS header will refuse to allow users to bypass warnings and connect to a site with an expired, self-signed, or otherwise invalid SSL certificate. If you use HSTS, make sure your certificates are in good shape and stay that way!
If you are deployed behind a load-balancer or reverse-proxy server, and the Strict-Transport-Security
header is not being added to your responses, it may be because Django doesn't realize that it's on a secure connection; you may need to set the SECURE_PROXY_SSL_HEADER
setting.
Django uses the Host
header provided by the client to construct URLs in certain cases. While these values are sanitized to prevent Cross Site Scripting attacks, a fake Host
value can be used for Cross-Site Request Forgery, cache poisoning attacks, and poisoning links in emails.Because even seemingly-secure web server configurations are susceptible to fake Host
headers, Django validates Host
headers against the ALLOWED_HOSTS
setting in the django.http.HttpRequest.get_host()
method.This validation only applies via get_host()
; if your code accesses the Host
header directly from request.META
you are bypassing this security protection.
Similar to the CSRF limitations requiring a site to be deployed such that untrusted users don't have access to any subdomains, django.contrib.sessions
also has limitations. See the session topic guide section on security for details.
LimitRequestBody
directive.mod_php
, which would execute static files as code, are disabled. You don't want users to be able to execute arbitrary code by uploading and requesting a specially crafted file.ImageField
image processing (Pillow). When this file is subsequently displayed to a user, it may be displayed as HTML depending on the type and configuration of your web server.No bulletproof technical solution exists at the framework level to safely validate all user uploaded file content, however, there are some other steps you can take to mitigate these attacks:
example.com
, you would want to serve uploaded content (the MEDIA_URL
setting) from something like usercontent-example.com
. It's not sufficient to serve content from a subdomain like usercontent.example.com
.