Added 'settings' section to CSRF docs, eliminating the unneeded 'Subdomains' section

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16199 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Luke Plant 2011-05-09 23:00:10 +00:00
parent d3641d889b
commit a75120927e
1 changed files with 47 additions and 19 deletions

View File

@ -166,18 +166,6 @@ both is fine, and will incur minimal overhead.
# ...
return render(request, "a_template.html", c)
Subdomains
----------
By default, CSRF cookies are specific to the subdomain they are set for. This
means that a form served from one subdomain (e.g. server1.example.com) will not
be able to have a target on another subdomain (e.g. server2.example.com). This
restriction can be removed by setting :setting:`CSRF_COOKIE_DOMAIN` to be
something like ``".example.com"``.
Please note that, with or without use of this setting, this CSRF protection
mechanism is not safe against cross-subdomain attacks -- see `Limitations`_.
Rejected requests
=================
@ -189,13 +177,7 @@ 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
:setting:`CSRF_FAILURE_VIEW` setting to a dotted path to your own view function,
which should have the following signature::
def csrf_failure(request, reason="")
where ``reason`` is a short message (intended for developers or logging, not for
end users) indicating the reason the request was rejected.
:setting:`CSRF_FAILURE_VIEW` setting.
How it works
============
@ -409,3 +391,49 @@ 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.
Settings
========
A number of settings can be used to control Django's CSRF behaviour.
CSRF_COOKIE_DOMAIN
------------------
.. versionadded:: 1.2
Default: ``None``
The domain to be used when setting the CSRF cookie. This can be useful for
easily allowing cross-subdomain requests to be exluded from the normal cross
site request forgery protection. It should be set to a string such as
``".lawrence.com"`` to allow a POST request from a form on one subdomain to be
accepted by accepted by a view served from another subdomain.
Please note that, with or without use of this setting, this CSRF protection
mechanism is not safe against cross-subdomain attacks -- see `Limitations`_.
CSRF_COOKIE_NAME
----------------
.. versionadded:: 1.2
Default: ``'csrftoken'``
The name of the cookie to use for the CSRF authentication token. This can be
whatever you want.
CSRF_FAILURE_VIEW
-----------------
.. versionadded:: 1.2
Default: ``'django.views.csrf.csrf_failure'``
A dotted path to the view function to be used when an incoming request
is rejected by the CSRF protection. The function should have this signature::
def csrf_failure(request, reason="")
where ``reason`` is a short message (intended for developers or logging, not for
end users) indicating the reason the request was rejected.