| 1 |
======================== |
| 2 |
Clickjacking Protection |
| 3 |
======================== |
| 4 |
|
| 5 |
.. module:: django.middleware.clickjacking |
| 6 |
:synopsis: Protects against Clickjacking |
| 7 |
|
| 8 |
The clickjacking middleware and decorators provide easy-to-use protection |
| 9 |
against `clickjacking`_. This type of attack occurs when a malicious site |
| 10 |
tricks a user into clicking on a concealed element of another site which they |
| 11 |
have loaded in a hidden frame or iframe. |
| 12 |
|
| 13 |
.. _clickjacking: https://en.wikipedia.org/wiki/Clickjacking |
| 14 |
|
| 15 |
An example of clickjacking |
| 16 |
========================== |
| 17 |
|
| 18 |
Suppose an online store has a page where a logged-in user can click "Buy Now" to |
| 19 |
purchase an item. A user has chosen to stay logged into the store all the time |
| 20 |
for convenience. An attacker site might create an "I Like Ponies" button on one |
| 21 |
of their own pages, and load the store's page in a transparent iframe such that |
| 22 |
the "Buy Now" button is invisibly overlaid on the "I Like Ponies" button. If the |
| 23 |
user visits the attacker's site, clicking "I Like Ponies" will cause an |
| 24 |
inadvertent click on the "Buy Now" button and an unknowing purchase of the item. |
| 25 |
|
| 26 |
.. _clickjacking-prevention: |
| 27 |
|
| 28 |
Preventing clickjacking |
| 29 |
======================= |
| 30 |
|
| 31 |
Modern browsers honor the `X-Frame-Options`_ HTTP header that indicates whether |
| 32 |
or not a resource is allowed to load within a frame or iframe. If the response |
| 33 |
contains the header with a value of ``SAMEORIGIN`` then the browser will only |
| 34 |
load the resource in a frame if the request originated from the same site. If |
| 35 |
the header is set to ``DENY`` then the browser will block the resource from |
| 36 |
loading in a frame no matter which site made the request. |
| 37 |
|
| 38 |
.. _X-Frame-Options: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options |
| 39 |
|
| 40 |
Django provides a few ways to include this header in responses from your site: |
| 41 |
|
| 42 |
#. A middleware that sets the header in all responses. |
| 43 |
|
| 44 |
#. A set of view decorators that can be used to override the middleware or to |
| 45 |
only set the header for certain views. |
| 46 |
|
| 47 |
The ``X-Frame-Options`` HTTP header will only be set by the middleware or view |
| 48 |
decorators if it is not already present in the response. |
| 49 |
|
| 50 |
How to use it |
| 51 |
============= |
| 52 |
|
| 53 |
Setting ``X-Frame-Options`` for all responses |
| 54 |
--------------------------------------------- |
| 55 |
|
| 56 |
To set the same ``X-Frame-Options`` value for all responses in your site, put |
| 57 |
``'django.middleware.clickjacking.XFrameOptionsMiddleware'`` to |
| 58 |
:setting:`MIDDLEWARE`:: |
| 59 |
|
| 60 |
MIDDLEWARE = [ |
| 61 |
..., |
| 62 |
"django.middleware.clickjacking.XFrameOptionsMiddleware", |
| 63 |
..., |
| 64 |
] |
| 65 |
|
| 66 |
This middleware is enabled in the settings file generated by |
| 67 |
:djadmin:`startproject`. |
| 68 |
|
| 69 |
By default, the middleware will set the ``X-Frame-Options`` header to |
| 70 |
``DENY`` for every outgoing ``HttpResponse``. If you want any other value for |
| 71 |
this header instead, set the :setting:`X_FRAME_OPTIONS` setting:: |
| 72 |
|
| 73 |
X_FRAME_OPTIONS = "SAMEORIGIN" |
| 74 |
|
| 75 |
When using the middleware there may be some views where you do **not** want the |
| 76 |
``X-Frame-Options`` header set. For those cases, you can use a view decorator |
| 77 |
that tells the middleware not to set the header:: |
| 78 |
|
| 79 |
from django.http import HttpResponse |
| 80 |
from django.views.decorators.clickjacking import xframe_options_exempt |
| 81 |
|
| 82 |
|
| 83 |
@xframe_options_exempt |
| 84 |
def ok_to_load_in_a_frame(request): |
| 85 |
return HttpResponse("This page is safe to load in a frame on any site.") |
| 86 |
|
| 87 |
.. note:: |
| 88 |
|
| 89 |
If you want to submit a form or access a session cookie within a frame or |
| 90 |
iframe, you may need to modify the :setting:`CSRF_COOKIE_SAMESITE` or |
| 91 |
:setting:`SESSION_COOKIE_SAMESITE` settings. |
| 92 |
|
| 93 |
Setting ``X-Frame-Options`` per view |
| 94 |
------------------------------------ |
| 95 |
|
| 96 |
To set the ``X-Frame-Options`` header on a per view basis, Django provides these |
| 97 |
decorators:: |
| 98 |
|
| 99 |
from django.http import HttpResponse |
| 100 |
from django.views.decorators.clickjacking import xframe_options_deny |
| 101 |
from django.views.decorators.clickjacking import xframe_options_sameorigin |
| 102 |
|
| 103 |
|
| 104 |
@xframe_options_deny |
| 105 |
def view_one(request): |
| 106 |
return HttpResponse("I won't display in any frame!") |
| 107 |
|
| 108 |
|
| 109 |
@xframe_options_sameorigin |
| 110 |
def view_two(request): |
| 111 |
return HttpResponse("Display in a frame if it's from the same origin as me.") |
| 112 |
|
| 113 |
Note that you can use the decorators in conjunction with the middleware. Use of |
| 114 |
a decorator overrides the middleware. |
| 115 |
|
| 116 |
Limitations |
| 117 |
=========== |
| 118 |
|
| 119 |
The ``X-Frame-Options`` header will only protect against clickjacking in |
| 120 |
`modern browsers`_. |
| 121 |
|
| 122 |
.. _modern browsers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options#browser_compatibility |