Add support for logout CSRF (#1239)

- New configuration option SECURITY_LOGOUT_CSRF that enables CSRF
checking
- On CSRF failure, return a new logout_user_template which is basically
a confirmation form (with CSRF token)
- Improve CSRF documentation
- Change logout menu to be a POST (and therefore a button)

close #1237

Author: jwag956

CHANGES.rst

@@ -16,6 +16,7 @@ Features & Improvements
 - (:pr:`1235`) Change default LOGOUT_METHODS to be just ``"POST"``
 - (:issue:`1228`) Change default ``csrf`` and ``tf_validity`` cookie config to ``secure=True``
 - (:issue:`1228`) The ``tf_validity`` cookie name is now configurable via :py:data:`SECURITY_TWO_FACTOR_VALIDITY_COOKIE_NAME`
+- (:issue:`1237`) Add support for CSRF on logout
 
 Fixes
 +++++
@@ -32,7 +33,7 @@ Backwards Compatibility Concerns
 - The fix for the inverted `is_locked` logic will require any application using it
   to invert their logic.
 - The change to :py:data:`SECURITY_TOKEN_MAX_AGE` default improves a long-standing
-  'insecure-out-of-the-box' issue. Applications will have to either change the
+  'insecure-out-of-the-box' concern. Applications will have to either change the
   value if they really want a long-lasting token or use the new refresh token
   feature.
 - The default for :py:data:`SECURITY_LOGOUT_METHODS` has been changed to just

docs/configuration.rst

@@ -876,6 +876,28 @@ Login/Logout
 
     Default: ``"security/login_user.html"``.
 
+.. py:data:: SECURITY_LOGOUT_USER_TEMPLATE
+
+    Specifies the path to the template for the logout page.
+    Note this is only returned on POST error.
+
+    Default: ``"security/logout_user.html"``.
+
+    .. versionadded:: 5.9.0
+
+.. py:data:: SECURITY_LOGOUT_CSRF
+
+    Should the logout view enforce CSRF. If set to ``"True"`` and if there is a
+    CSRF token mismatch then the ``"SECURITY_LOGOUT_USER_TEMPLATE"`` will be
+    returned (if request was a form post). For a JSON request, a 400 response will
+    be returned.
+
+    .. danger::
+        Be sure to not configure ``"GET"`` as an accepted method since that is not
+        CSRF protected.
+
+    .. versionadded:: 5.9.0
+
 .. py:data:: SECURITY_VERIFY_URL
 
     Specifies the reauthenticate URL. If :py:data:`SECURITY_FRESHNESS` evaluates to < 0; this
@@ -2185,6 +2207,7 @@ A list of all templates:
 
 * :py:data:`SECURITY_FORGOT_PASSWORD_TEMPLATE`
 * :py:data:`SECURITY_LOGIN_USER_TEMPLATE`
+* :py:data:`SECURITY_LOGOUT_USER_TEMPLATE`
 * :py:data:`SECURITY_VERIFY_TEMPLATE`
 * :py:data:`SECURITY_REGISTER_USER_TEMPLATE`
 * :py:data:`SECURITY_RESET_PASSWORD_TEMPLATE`

docs/customizing.rst

@@ -16,6 +16,7 @@ following is a list of view templates:
 
 * `security/forgot_password.html`
 * `security/login_user.html`
+* `security/logout_user.html`
 * `security/mf_recovery.html`
 * `security/mf_recovery_codes.html`
 * `security/recover_username.html`
@@ -76,6 +77,7 @@ The following is a list of all the available context processor decorators:
 * ``context_processor``: All views
 * ``forgot_password_context_processor``: Forgot password view
 * ``login_context_processor``: Login view
+* ``logout_context_processor``: Logout view
 * ``mf_recovery_codes_context_processor``: Setup recovery codes view
 * ``mf_recovery_context_processor``: Use recovery code view
 * ``register_context_processor``: Register view

docs/openapi.yaml

@@ -211,7 +211,9 @@ paths:
       description: >
         If a refresh-token is supplied, it will be revoked as part
         of logging the user out. If SECURITY_REFRESH_TOKEN_COOKIE_NAME is configured,
-        the refresh token will be deleted as part of logout.
+        the refresh token (as well as the cookie) will be deleted as part of logout.
+        If SECURITY_LOGOUT_CSRF is enabled, a valid CSRF token must be provided and
+        an error can be returned if the token is invalid.
       requestBody:
         required: false
         content:
@@ -223,7 +225,7 @@ paths:
               $ref: "#/components/schemas/Logout"
       responses:
         200:
-          description: Successful logout
+          description: Logout response
           content:
             application/json:
               schema:
@@ -238,13 +240,24 @@ paths:
                         type: integer
                         example: 200
                         description: Http status code
+            text/html:
+              schema:
+                description: Unsuccessful logout.
+                type: string
+                example: render_template(SECURITY_LOGOUT_USER_TEMPLATE) with error values
         302:
           description: Successful logout
           headers:
             Location:
               description: Redirect to ``SECURITY_POST_LOGOUT_VIEW``
               schema:
                 type: string
+        400:
+          description: Errors while validating form (CSRF).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DefaultJsonErrorResponse"
   /verify:
     get:
       summary: GET verify/reauthentication form

docs/patterns.rst

@@ -273,37 +273,51 @@ CSRF
 By default, Flask-Security, via Flask-WTForms protects all form based POSTS
 from CSRF attacks using well vetted per-session hidden-form-field csrf-tokens.
 
-Any web application that relies on session cookies for authentication must have CSRF protection.
+Any web application that uses a session cookie for authentication must have CSRF protection.
 For more details please read this `OWASP CSRF cheatsheet <https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.md>`_.
-A couple important take-aways - first - it isn't about forms versus JSON - it is about
-how the API is authenticated (session cookies versus authentication token). Second there is the
-concern about 'login CSRF' - is protection needed prior to authentication (yes if
-you have a really secure/popular site).
+As mentioned in the OWASP cheatsheet - pure JSON requests should be immune from CSRF exploits ASSUMING that the application
+has a properly set CORS policy. Flask-Security, via Werkzeug, is careful to ONLY accept JSON with an ``"application/+json"`` header.
+However, currently, there is no way to configure Flask-Security to accept ONLY ``"application/json"`` - meaning that it is important
+to properly pass CSRF tokens for ALL requests.
 
 Flask-Security strives to support various options for both its endpoints (e.g. ``/login``)
 and the application endpoints (protected with Flask-Security decorators such as :func:`.auth_required`).
 
 If your application just uses forms that are derived from ``Flask-WTF::Flaskform`` - you are done.
-Note that all of Flask-Security's endpoints are form based (regardless of how the request was made).
-
-.. note::
-  The logout endpoint has never been form-based and has never had CSRF protection. With the addition
-  of the refresh token feature, logout now accepts form/json input - but still does not support
-  CSRF protection.
+All of Flask-Security's endpoints are form based (regardless of how the request was made).
+
+Login CSRF
+++++++++++++
+Read more about this at `OWASP <https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.md#possible-csrf-vulnerabilities-in-login-forms>`_.
+
+Logout CSRF
+++++++++++++
+Prior to release 5.9 the logout endpoint never accepted any input nor enabled CSRF protection so
+there was never any possible errors. Furthermore, both ``"GET"`` and ``"POST"`` were accepted.
+Best practice is to accept only ``"POST"`` requests to avoid trivial 'auto-logout' attacks.
+Requiring CSRF for the logout endpoint is best practice - however there are many
+sources that disagree with this (and in fact, security advisories are usually NOT issued for applications that don't
+support that). The usability issue is that users may or may not be looking for an error when they click the logout button
+and NOT logging them out is worse. Flask-Security supports requiring CSRF for logout with the
+:py:data:`SECURITY_LOGOUT_CSRF` configuration option.
+
+.. warning::
+    Enabling CSRF protection means that the logout endpoint can return an error - be sure your application
+    handles that. For form based applications, Flask-Security will return a 'Confirm Sign Out' template.
 
 Behind-The-Scenes
 ++++++++++++++++++
-Depending on configuration, there are 3 places CSRF tokens can be checked:
+Depending on configuration, there are 3 places CSRF tokens can be checked (in order):
+  #) As part of an @before_request handler that Flask-WTF sets up if CSRFprotect(app) is called. On error
+     this always returns HTTP 400 and small snippet of HTML. This can be disabled
+     by setting app.config["WTF_CSRF_CHECK_DEFAULT"] = False.
+  #) As part of a Flask-Security decorator (:func:`.unauth_csrf`, :func:`.auth_required`). On
+     error, either a JSON response is returned OR CSRFError exception is raised and 400 is returned with the small snippet of HTML
+     (the exception and default response is part of Flask-WTF).
   #) As part of form validation for any form derived from FlaskForm (which all Flask-Security
      forms are). An error here is recorded in the ``csrf_token`` field and the calling view
      decides whether to return 200 or 400.
      This is the default if no other configuration changes are made.
-  #) As part of an @before_request handler that Flask-WTF sets up if CSRFprotect() is called. On error
-     this always returns HTTP 400 and small snippet of HTML. This can be disabled
-     by setting config["WTF_CSRF_CHECK_DEFAULT"] = False.
-  #) As part of a Flask-Security decorator (:func:`.unauth_csrf`, :func:`.auth_required`). On
-     error either a JSON response is returned OR CSRFError exception is raised and 400 is returned with the small snippet of HTML
-     (the exception and default response is part of Flask-WTF).
 
 CSRF: Single-Page-Applications and AJAX/XHR
 ++++++++++++++++++++++++++++++++++++++++++++

flask_security/core.py

@@ -196,6 +196,8 @@
     "TWO_FACTOR_POST_SETUP_VIEW": ".two_factor_setup",  # endpoint or URL
     "TWO_FACTOR_ERROR_VIEW": ".login",
     "LOGOUT_METHODS": ["POST"],
+    "LOGOUT_CSRF": False,
+    "LOGOUT_USER_TEMPLATE": "security/logout_user.html",
     "POST_LOGIN_VIEW": "/",
     "POST_LOGOUT_VIEW": "/",
     "LOGIN_ERROR_VIEW": None,  # spa
@@ -2031,7 +2033,6 @@ def _csrf_init(app):
             )
 
         if csrf:
-            csrf.exempt("flask_security.views.logout")
             # Add configured header to WTF_CSRF_HEADERS
             if ch := cv("CSRF_HEADER", app=app):
                 if ch not in app.config["WTF_CSRF_HEADERS"]:
@@ -2285,6 +2286,9 @@ def forgot_password_context_processor(
     def login_context_processor(self, fn: t.Callable[[], dict[str, t.Any]]) -> None:
         self._add_ctx_processor("login", fn)
 
+    def logout_context_processor(self, fn: t.Callable[[], dict[str, t.Any]]) -> None:
+        self._add_ctx_processor("logout", fn)
+
     def register_context_processor(self, fn: t.Callable[[], dict[str, t.Any]]) -> None:
         self._add_ctx_processor("register", fn)
 

flask_security/forms.py

@@ -657,9 +657,11 @@ class LogoutForm(Form):
     """The logout form.
     No data is required to logout - however, if a refresh token
     is provided, it will be revoked.
+    Also - CSRF will be checked - whether that will cause an error is up to
+    the view.
     """
 
-    refresh_token = StringField(
+    refresh_token = HiddenField(
         get_form_field_xlate(_("Refresh Token")),
         validators=[Optional()],
     )
@@ -679,13 +681,12 @@ def __init__(self, *args: t.Any, **kwargs: t.Any):
     def validate(self, **kwargs: t.Any) -> bool:
         from .tokens import verify_refresh_token
 
-        if not super().validate(**kwargs):  # pragma: no cover
+        if not super().validate(**kwargs):
             return False
         if not self.refresh_token.data:
             return True
 
         assert isinstance(self.refresh_token.errors, list)
-
         self.refresh_tracker, self.refresh_errors, uid = verify_refresh_token(
             self.refresh_token.data
         )

flask_security/templates/security/_menu.html

@@ -3,11 +3,13 @@
   security.username_recovery %}
   <hr>
   <h2>{{ _fsdomain('Menu') }}</h2>
-  <ul>
+  <menu>
     {% if _fs_is_user_authenticated(current_user) %}
       {# already authenticated user #}
-      <li>
-        <a href="{{ url_for_security('logout') }}">{{ _fsdomain("Sign out") }}</a>
+      <li class="fs-button">
+        <form action="{{ url_for_security('logout') }}" method="post" name="logout_form">
+          <button type="submit">Sign Out</button>
+        </form>
       </li>
       {% if security.changeable %}
         <li>
@@ -76,5 +78,5 @@ <h2>{{ _fsdomain('Menu') }}</h2>
         </li>
       {% endif %}
     {% endif %}
-  </ul>
+  </menu>
 {% endif %}

flask_security/templates/security/base.html

@@ -22,6 +22,7 @@
           .fs-gap { margin-top: 20px; }
           .fs-div { margin: 4px; }
           .fs-error-msg { color: darkred; }
+          .fs-button form {margin: 0}
         </style>
       {%- endblock styles %}
     {%- endblock head %}

flask_security/templates/security/logout_user.html

@@ -0,0 +1,16 @@
+{% set title = title|default(_fsdomain("Confirm Sign Out")) %}
+{% extends "security/base.html" %}
+{% from "security/_macros.html" import render_field_with_errors, render_field, render_field_errors, render_form_errors %}
+
+{% block content %}
+  {% include "security/_messages.html" %}
+  <h1>{{ _fsdomain('Confirm Sign Out') }}</h1>
+  <form action="{{ url_for_security('logout') }}" method="post" name="logout_form">
+    {{ logout_form.hidden_tag() }}
+    {{ render_form_errors(logout_form) }}
+    {{ render_field(logout_form.refresh_token) }}
+    {{ render_field(logout_form.csrf_token) }}
+    {{ render_field(logout_form.submit) }}
+  </form>
+  {% include "security/_menu.html" %}
+{% endblock content %}