Debian Codegraph @

docs/ref/clickjacking.txt

raw
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