diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/sessions.rst | 52 |
1 files changed, 28 insertions, 24 deletions
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 842b838cd..0ed52b563 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -298,24 +298,6 @@ post. To use CSRF token support, you must enable a :term:`session factory` as described in :ref:`using_the_default_session_factory` or :ref:`using_alternate_session_factories`. -Using the ``session.new_csrf_token`` Method -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To add a CSRF token to the session, use the ``session.new_csrf_token()`` method. - -.. code-block:: python - - token = request.session.new_csrf_token() - -The ``new_csrf_token()`` method accepts no arguments. It returns a *token* -string, which will be opaque and randomized. This token will also be set -into the session, awaiting pickup by the ``session.get_csrf_token()`` method. -You can subsequently use the returned token as the value of a hidden field in -a form that posts to a method that requires elevated privileges. The handler -for the form post should use ``session.get_csrf_token()`` (explained below) to -obtain the current CSRF token related to the user from the session, and -compare it to the value of the hidden form field. - Using the ``session.get_csrf_token`` Method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -326,12 +308,20 @@ To get the current CSRF token from the session, use the token = request.session.get_csrf_token() -The ``get_csrf_token()`` method accepts no arguments. It returns the "current" -*token* string generated by the last call to ``session.new_csrf_token()``. You can -then use it to compare against the token provided within form post hidden -value data. For example, if your form rendering included the CSRF token -obtained via ``session.new_csrf_token()`` as a hidden input field named -``csrf_token()``: +The ``session.get_csrf_token()`` method accepts no arguments. It returns a +CSRF *token* string. If ``session.get_csrf_token()`` or +``session.new_csrf_token()`` was invoked previously for this session, the +existing token will be returned. If no CSRF token previously existed for +this session, a new token will be will be set into the session and returned. +The newly created token will be opaque and randomized. + +You can use the returned token as the value of a hidden field in a form that +posts to a method that requires elevated privileges. The handler for the +form post should use ``session.get_csrf_token()`` *again* to obtain the +current CSRF token related to the user from the session, and compare it to +the value of the hidden form field. For example, if your form rendering +included the CSRF token obtained via ``session.get_csrf_token()`` as a hidden +input field named ``csrf_token``: .. code-block:: python :linenos: @@ -340,3 +330,17 @@ obtained via ``session.new_csrf_token()`` as a hidden input field named if token != request.POST['csrf_token']: raise ValueError('CSRF token did not match') +Using the ``session.new_csrf_token`` Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To explicitly add a new CSRF token to the session, use the +``session.new_csrf_token()`` method. This differs only from +``session.get_csrf_token()`` inasmuch as it clears any existing CSRF token, +creates a new CSRF token, sets the token into the session, and returns the +token. + +.. code-block:: python + + token = request.session.new_csrf_token() + + |