replace pyramid.require_default_csrf setting with config.set_default_csrf_options

3 files changed, 66 insertions, 36 deletions

diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst
index af7d0a349..babfa0a98 100644
--- a/docs/narr/extconfig.rst
+++ b/docs/narr/extconfig.rst
@@ -261,6 +261,7 @@ Pre-defined Phases
 - :meth:`pyramid.config.Configurator.add_view_predicate`
 - :meth:`pyramid.config.Configurator.add_view_deriver`
 - :meth:`pyramid.config.Configurator.set_authorization_policy`
+- :meth:`pyramid.config.Configurator.set_default_csrf_options`
 - :meth:`pyramid.config.Configurator.set_default_permission`
 - :meth:`pyramid.config.Configurator.set_view_mapper`
 
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index 98315ac9f..c9fecd4f4 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -337,6 +337,31 @@ introspectables in categories not described here.
 
     The permission name passed to ``set_default_permission``.
 
+``default csrf options``
+
+  There will be one and only one introspectable in the ``default csrf options``
+  category. It represents a call to the
+  :meth:`pyramid.config.Configurator.set_default_csrf_options` method. It
+  will have the following data.
+
+  ``require_csrf``
+
+    The default value for ``require_csrf`` if left unspecified on calls to
+    :meth:`pyramid.config.Configurator.add_view`.
+
+  ``token``
+
+    The name of the token searched in ``request.POST`` to find a valid CSRF
+    token.
+
+  ``header``
+
+    The name of the request header searched to find a valid CSRF token.
+
+  ``safe_methods``
+
+    The list of HTTP methods considered safe and exempt from CSRF checks.
+
 ``views``
 
   Each introspectable in the ``views`` category represents a call to
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 7cf96ac7d..bfc908396 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -396,13 +396,13 @@ named ``X-CSRF-Token``.
 
 .. code-block:: python
 
-    from pyramid.session import check_csrf_token
+   from pyramid.session import check_csrf_token
 
-    def myview(request):
-        # Require CSRF Token
-        check_csrf_token(request)
+   def myview(request):
+       # Require CSRF Token
+       check_csrf_token(request)
 
-        # ...
+       # ...
 
 .. _auto_csrf_checking:
 
@@ -414,41 +414,45 @@ Checking CSRF Tokens Automatically
 :app:`Pyramid` supports automatically checking CSRF tokens on requests with an
 unsafe method as defined by RFC2616. Any other request may be checked manually.
 This feature can be turned on globally for an application using the
-``pyramid.require_default_csrf`` setting.
-
-If the ``pyramid.required_default_csrf`` setting is a :term:`truthy string` or
-``True`` then the default CSRF token parameter will be ``csrf_token``. If a
-different token is desired, it may be passed as the value. Finally, a
-:term:`falsey string` or ``False`` will turn off automatic CSRF checking
-globally on every request.
-
-No matter what, CSRF checking may be explicitly enabled or disabled on a
-per-view basis using the ``require_csrf`` view option. This option is of the
-same format as the ``pyramid.require_default_csrf`` setting, accepting strings
-or boolean values.
-
-If ``require_csrf`` is ``True`` but does not explicitly define a token to
-check, then the token name is pulled from whatever was set in the
-``pyramid.require_default_csrf`` setting. Finally, if that setting does not
-explicitly define a token, then ``csrf_token`` is the token required. This token
-name will be required in ``request.POST`` which is the submitted form body.
-
-It is always possible to pass the token in the ``X-CSRF-Token`` header as well.
-There is currently no way to define an alternate name for this header without
-performing CSRF checking manually.
-
-In addition to token based CSRF checks, the automatic CSRF checking will also
-check the referrer of the request to ensure that it matches one of the trusted
-origins. By default the only trusted origin is the current host, however
-additional origins may be configured by setting
+:meth:`pyramid.config.Configurator.set_default_csrf_options` directive.
+For example:
+
+.. code-block:: python
+
+   from pyramid.config import Configurator
+
+   config = Configurator()
+   config.set_default_csrf_options(require_csrf=True)
+
+CSRF checking may be explicitly enabled or disabled on a per-view basis using
+the ``require_csrf`` view option. A value of ``True`` or ``False`` will
+override the default set by ``set_default_csrf_options``. For example:
+
+.. code-block:: python
+
+   @view_config(route_name='hello', require_csrf=False)
+   def myview(request):
+       # ...
+
+When CSRF checking is active, the token and header used to find the
+supplied CSRF token will be ``csrf_token`` and ``X-CSRF-Token``, respectively,
+unless otherwise overridden by ``set_default_csrf_options``. The token is
+checked against the value in ``request.POST`` which is the submitted form body.
+If this value is not present, then the header will be checked.
+
+In addition to token based CSRF checks, if the request is using HTTPS then the
+automatic CSRF checking will also check the referrer of the request to ensure
+that it matches one of the trusted origins. By default the only trusted origin
+is the current host, however additional origins may be configured by setting
 ``pyramid.csrf_trusted_origins`` to a list of domain names (and ports if they
 are non standard). If a host in the list of domains starts with a ``.`` then
 that will allow all subdomains as well as the domain without the ``.``.
 
-If CSRF checks fail then a :class:`pyramid.exceptions.BadCSRFToken` exception
-will be raised. This exception may be caught and handled by an
-:term:`exception view` but, by default, will result in a ``400 Bad Request``
-response being sent to the client.
+If CSRF checks fail then a :class:`pyramid.exceptions.BadCSRFToken` or
+:class:`pyramid.exceptions.BadCSRFOrigin` exception will be raised. This
+exception may be caught and handled by an :term:`exception view` but, by
+default, will result in a ``400 Bad Request`` response being sent to the
+client.
 
 Checking CSRF Tokens with a View Predicate
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~