Ticket #16936: ajax_csrf.patch

docs/ref/contrib/csrf.txt

@@ -86 +86 @@
 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
-``ajaxSend`` event as follows:
+that allow headers to be set on every request.
+
+As a first step, you must get a hold of the CSRF token itself. If you've got
+a form which was rendered with the :ttag:`csrf_token`, then you can extract the
+token from there:
+
+.. code-block:: javascript
+
+    // jQuery
+    var csrftoken = $("input[name=csrfmiddlewaretoken]").val();
+
+If the CSRF token is not present in markup by use of the :ttag:`csrf_token`
+template tag, it must be supplied to the client by other means. This is common
+in cases where the form is dynamically added to the page, and Django supplies
+a decorator which will set a cookie containing the CSRF token:
+:func:`~django.views.decorators.csrf.ensure_csrf_cookie`. Use the decorator
+on any view which will need access to the CSRF token, but doesn't include the
+token in the actual markup sent to the client.
 
 .. code-block:: javascript
 
-    $(document).ajaxSend(function(event, xhr, settings) {
-        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;
-                    }
+    // once again, 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;
-        }
-        function sameOrigin(url) {
-            // url could be relative or scheme relative or absolute
-            var host = document.location.host; // host + port
-            var protocol = document.location.protocol;
-            var sr_origin = '//' + host;
-            var origin = protocol + sr_origin;
-            // Allow absolute or scheme relative URLs to same origin
-            return (url == origin || url.slice(0, origin.length + 1) == origin + '/') ||
-                (url == sr_origin || url.slice(0, sr_origin.length + 1) == sr_origin + '/') ||
-                // or any other URL that isn't scheme relative or absolute i.e relative.
-                !(/^(\/\/|http:|https:).*/.test(url));
-        }
-        function safeMethod(method) {
-            return (/^(GET|HEAD|OPTIONS|TRACE)$/.test(method));
         }
+        return cookieValue;
+    }
+    var csrftoken = getCookie('csrftoken');
 
-        if (!safeMethod(settings.type) && sameOrigin(settings.url)) {
-            xhr.setRequestHeader("X-CSRFToken", getCookie('csrftoken'));
-        }
-    });
+The above code could be simplified by using the `jQuery cookie plugin
+<http://plugins.jquery.com/project/Cookie>`_ to replace ``getCookie``:
 
-.. note::
+.. code-block:: javascript
 
-    Due to a bug introduced in jQuery 1.5, the example above will not work
-    correctly on that version. Make sure you are running at least jQuery 1.5.1.
+    var csrftoken = $.cookie('csrftoken');
 
-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.
+Finally, you'll have to actually set the header on your AJAX request, while
+protecting the CSRF token from being sent to other domains:
 
-The above code could be simplified by using the `jQuery cookie plugin
-<http://plugins.jquery.com/project/Cookie>`_ to replace ``getCookie``, and
-`settings.crossDomain <http://api.jquery.com/jQuery.ajax>`_ in jQuery 1.5 and
-later to replace ``sameOrigin``.
+.. code-block:: javascript
+
+    function safeMethod(method) {
+        return (/^(GET|HEAD|OPTIONS|TRACE)$/.test(method));
+    }
+    $.ajaxSetup({
+        beforeSend: function(xhr, settings) {
+            if (!(/^https?:.*/.test(settings.url)) && safeMethod(settings.type) ) {
+                // Only send the token to relative URLs i.e. locally.
+                // Only send the token when using a safe HTTP method.
+                // Using the csrftoken value acquired earlier.
+                xhr.setRequestHeader("X-CSRFToken", csrftoken);
+            }
+        }
+    });
+
+You can use `settings.crossDomain <http://api.jquery.com/jQuery.ajax>`_ in
+jQuery 1.5 and newer in order to simplify the above code:
 
-In addition, if the CSRF cookie has not been sent to the client by use of
-:ttag:`csrf_token`, you may need to ensure the client receives the cookie by
-using :func:`~django.views.decorators.csrf.ensure_csrf_cookie`.
+.. code-block:: javascript
+
+    $.ajaxSetup({
+        crossDomain: false,
+        beforeSend: function(xhr, settings) {
+            if (safeMethod(settings.type) {
+                xhr.setRequestHeader("X-CSRFToken", csrftoken);
+            }
+        }
+    });
 
 The decorator method
 --------------------