Skip to content
Browse files

switch to `Form.Meta` from deprecated `SecureForm`, close #216

* deprecate `csrf_enabled` in `Form.__init__`
* remove `SecureForm` attributes and methods
* add `WTF_CSRFF_FIELD_NAME` config
* rename `CsrfError` to `CSRFError`
* `validate_csrf` raises `ValidationError` with specific error message,
  ref #239
  • Loading branch information...
davidism committed Jan 3, 2017
1 parent b1d6f04 commit 42befd0420d1f4896a70339de3d474044461a1c9
Showing with 297 additions and 261 deletions.
  1. +1 −1 docs/api.rst
  2. +17 −0 docs/changelog.rst
  3. +30 −40 docs/config.rst
  4. +1 −1 docs/csrf.rst
  5. +118 −50 flask_wtf/
  6. +75 −113 flask_wtf/
  7. +6 −5 tests/
  8. +15 −26 tests/
  9. +12 −2 tests/
  10. +2 −2 tests/
  11. +4 −4 tests/
  12. +1 −1 tests/
  13. +15 −16 tests/
@@ -34,7 +34,7 @@ CSRF Protection
.. autoclass:: CsrfProtect

.. autoclass:: CsrfError
.. autoclass:: CSRFError

.. autofunction:: generate_csrf
@@ -20,16 +20,33 @@ In development
- The same CSRF token is generated for the lifetime of a request. It is exposed
as ``request.csrf_token`` for use during testing. (`#227`_, `#264`_)
- ``CsrfProtect.error_handler`` is deprecated. (`#264`_)

- Handlers that return a response work in addition to those that raise an
error. The behavior was not clear in previous docs.
- (`#200`_, `#209`_, `#243`_, `#252`_)

- Use ``Form.Meta`` instead of deprecated ``SecureForm`` for CSRF (and
everything else). (`#216`_, `#271`_)

- ``csrf_enabled`` parameter is still recognized but deprecated. All other
attributes and methods from ``SecureForm`` are removed. (`#271`_)

- Provide ``WTF_CSRF_FIELD_NAME`` to configure the name of the CSRF token.
- ``CsrfError`` is renamed to ``CSRFError``. (`#271`_)
- ``validate_csrf`` raises ``wtforms.ValidationError`` with specifc messages
instead of returning ``True`` or ``False``. This breaks anything that was
calling the method directly. (`#239`_, `#271`_)

.. _`#200`:
.. _`#209`:
.. _`#216`:
.. _`#227`:
.. _`#239`:
.. _`#243`:
.. _`#252`:
.. _`#264`:
.. _`#271`:

Version 0.13.1
@@ -1,47 +1,37 @@

Here is the full table of all configurations.

Forms and CSRF

The full list of configuration for Flask-WTF. Usually, you don't need
to configure any of them. It just works.

======================= ==============================================
WTF_CSRF_ENABLED Disable/enable CSRF protection for forms.
Default is True.
WTF_CSRF_CHECK_DEFAULT Enable CSRF checks for all views by default.
Default is True.
WTF_I18N_ENABLED Disable/enable I18N support. This should work
together with Flask-Babel. Default is True.
WTF_CSRF_HEADERS CSRF token HTTP headers checked. Default is
**['X-CSRFToken', 'X-CSRF-Token']**
WTF_CSRF_SECRET_KEY A random string for generating CSRF token.
Default is the same as SECRET_KEY.
WTF_CSRF_TIME_LIMIT CSRF token expiring time. Default is **3600**
seconds. If set to ``None``, the CSRF token
is then bound to the life-time of the session.
WTF_CSRF_SSL_STRICT Strictly protection on SSL. This will check
the referrer, validate if it is from the same
origin. Default is True.
WTF_CSRF_METHODS CSRF protection on these request methods.
Default is **['POST', 'PUT', 'PATCH']**
======================= ==============================================

========================== =====================================================
``WTF_CSRF_ENABLED`` Set to ``False`` to disable all CSRF protection.
``WTF_CSRF_CHECK_DEFAULT`` When using the CSRF protection extension, this
controls whether every view is protected by default.
Default is ``True``.
``WTF_CSRF_SECRET_KEY`` Random data for generating secure tokens. If this is
not set then ``SECRET_KEY`` is used.
``WTF_CSRF_METHODS`` HTTP methods to protect from CSRF. Default is
``{'POST', 'PUT', 'PATCH', 'DELETE'}``.
``WTF_CSRF_FIELD_NAME`` Name of the form field and session key that holds the
CSRF token.
``WTF_CSRF_HEADERS`` HTTP headers to search for CSRF token when it is not
provided in the form. Default is
``['X-CSRFToken', 'X-CSRF-Token']``.
``WTF_CSRF_TIME_LIMIT`` Max age in seconds for CSRF tokens. Default is
``3600``. If set to ``None``, the CSRF token is valid
for the life of the session.
``WTF_CSRF_SSL_STRICT`` Whether to enforce the same origin policy by checking
that the referrer matches the host. Only applies to
HTTPS requests. Default is ``True``.
``WTF_I18N_ENABLED`` Set to ``False`` to disable Flask-Babel I18N support.
========================== =====================================================


You have already learned these configuration at :ref:`recaptcha`.
This table is only designed for a convience.

======================= ==============================================
RECAPTCHA_USE_SSL Enable/disable recaptcha through ssl.
Default is False.
RECAPTCHA_PUBLIC_KEY **required** A public key.
RECAPTCHA_PRIVATE_KEY **required** A private key.
RECAPTCHA_OPTIONS **optional** A dict of configuration options.
======================= ==============================================
========================= ==============================================
``RECAPTCHA_USE_SSL`` Enable/disable recaptcha through SSL. Default is
``RECAPTCHA_PUBLIC_KEY`` **required** A public key.
``RECAPTCHA_PRIVATE_KEY`` **required** A private key.
``RECAPTCHA_OPTIONS`` **optional** A dict of configuration options.
========================= ==============================================
@@ -77,7 +77,7 @@ For example, in jQuery you can configure all requests to send the token.
Customize the error response

When CSRF validation fails, it will raise a :class:`CsrfError`.
When CSRF validation fails, it will raise a :class:`CSRFError`.
By default this returns a response with the failure reason and a 400 code.
You can customize the error response using Flask's
:meth:`~flask.Flask.errorhandler`. ::

0 comments on commit 42befd0

Please sign in to comment.
You can’t perform that action at this time.