Fixed #15354 - provide method to ensure CSRF token is always available for AJAX requests

Thanks to sayane for the report.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16192 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 17 insertions, 0 deletions

diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt
index 8acab718d3..7ff7d53aa0 100644
--- a/docs/ref/contrib/csrf.txt
+++ b/docs/ref/contrib/csrf.txt
@@ -132,6 +132,10 @@ The above code could be simplified by using the `jQuery cookie plugin
 `settings.crossDomain <http://api.jquery.com/jQuery.ajax>`_ in jQuery 1.5 and
 later to replace ``sameOrigin``.
 
+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`.
+
 The decorator method
 --------------------
 
@@ -328,6 +332,10 @@ Utilities
             # ...
             return render(request, "a_template.html", c)
 
+.. function:: ensure_csrf_cookie(view)
+
+    This decorator forces a view to send the CSRF cookie.
+
 Scenarios
 ---------
 
@@ -381,6 +389,15 @@ path within it that needs protection. Example::
         else:
            do_something_else()
 
+Page uses AJAX without any HTML form
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A page makes a POST request via AJAX, and the page does not have an HTML form
+with a :ttag:`csrf_token` that would cause the required CSRF cookie to be sent.
+
+Solution: use :func:`~django.views.decorators.csrf.ensure_csrf_cookie` on the
+view that sends the page.
+
 Contrib and reusable apps
 =========================