diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/exceptions.rst | 2 | ||||
| -rw-r--r-- | docs/api/session.rst | 2 | ||||
| -rw-r--r-- | docs/narr/sessions.rst | 8 | ||||
| -rw-r--r-- | docs/narr/viewconfig.rst | 3 |
4 files changed, 15 insertions, 0 deletions
diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst index faca0fbb6..cb411458d 100644 --- a/docs/api/exceptions.rst +++ b/docs/api/exceptions.rst @@ -5,6 +5,8 @@ .. automodule:: pyramid.exceptions + .. autoexception:: BadCSRFOrigin + .. autoexception:: BadCSRFToken .. autoexception:: PredicateMismatch diff --git a/docs/api/session.rst b/docs/api/session.rst index 474e2bb32..56c4f52d7 100644 --- a/docs/api/session.rst +++ b/docs/api/session.rst @@ -9,6 +9,8 @@ .. autofunction:: signed_deserialize + .. autofunction:: check_csrf_origin + .. autofunction:: check_csrf_token .. autofunction:: SignedCookieSessionFactory diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 0e895ff81..7cf96ac7d 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -437,6 +437,14 @@ 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 +``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`` diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 3b8f0353a..cd5b8feb0 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -215,6 +215,9 @@ Non-Predicate Arguments If this option is set to ``False`` then CSRF checks will be disabled regardless of the ``pyramid.require_default_csrf`` setting. + In addition, if this option is set to ``True`` or a string then CSRF origin + checking will be enabled. + See :ref:`auto_csrf_checking` for more information. .. versionadded:: 1.7 |