Flask-SeaSurf¶
SeaSurf is a Flask extension for preventing cross-site request forgery (CSRF).
CSRF vulnerabilities have been found in large and popular sites such as YouTube. These attacks are problematic because the mechanism they use is relatively easy to exploit. This extension attempts to aid you in securing your application from such attacks.
This extension is based on the excellent Django middleware.
Installation¶
Install the extension with one of the following commands:
$ easy_install flask-seasurf
or alternatively if you have pip installed:
$ pip install flask-seasurf
Usage¶
Using SeaSurf is fairly straightforward. Begin by importing the extension and then passing your application object back to the extension, like this:
import Flask
from flask_seasurf import SeaSurf
app = Flask(__name__)
csrf = SeaSurf(app)
This extension is configurable via a set of configuration variables which can be added to the Flask app’s config:
Variable name |
Description |
Default |
---|---|---|
CSRF_COOKIE_NAME |
The cookie name, also used as the session variable name. |
‘_csrf_token’ |
CSRF_COOKIE_TIMEOUT |
After what time the cookie expires. |
timedelta(days=5) |
CSRF_COOKIE_SECURE |
Whether the cookie is required to be transferred over a secure connection. |
False |
CSRF_COOKIE_HTTPONLY |
HttpOnly flag of the cookie. Whether it can be read by JS. |
False |
CSRF_COOKIE_PATH |
Indicates a URL path that must exist in the requested URL in order to send the Cookie header |
‘/’ |
CSRF_COOKIE_DOMAIN |
Setting the cookie domain. |
None |
CSRF_COOKIE_SAMESITE |
Setting the cookie SameSite policy. |
‘Lax’ |
CSRF_CHECK_REFERER |
Enable checking the Referer header. |
True |
CSRF_DISABLE |
Disables CSRF protection globally. |
False unless app.config[‘TESTING’] is set to True |
CSRF_HEADER_NAME |
The header that would contain the token. |
‘X-CSRFToken’ |
SEASURF_INCLUDE_OR_EXEMPT_VIEWS |
Possible values: ‘exempt’, ‘include’. |
‘exempt’ |
All the values prefixed with CSRF_COOKIE_ are passed verbatim to the Response.set_cookie method.
Corresponding code will need to be added to the templates where POST, PUT, and DELETE HTTP methods are anticipated. In the case of POST requests a hidden field should be added, something like this:
<form method="POST">
...
<input type="hidden" name="_csrf_token" value="{{ csrf_token() }}">
</form>
The extension adds a global function to the Jinja template engine called csrf_token. This is a function that retrieves the current token and will be matched against the request token.
By default all requests that are not GET, HEAD, OPTIONS, or TRACE are validated against the CSRF token sent by the client and as rendered on the page. However a view may be completely exempted from validation using the exempt decorator. For instance it’s possible to decorate a view as shown below:
@csrf.exempt
@app.route('/exempt_view', methods=['POST'])
def exempt_view():
'''This view is exempted from CSRF validation.'''
return 'foobar'
By default when a request is determined to be secure, i.e. using HTTPS, then we use strict referer checking to prevent a man-in-the-middle attack from being plausible. To disable checking the Referer header, set the Flask app’s config CSRF_CHECK_REFERER to False.
Note
Setting
TESTING = True
in config will disable the token generation!If you are getting
None
as token check ifTESTING = True
in config.
AJAX Usage¶
AJAX is not exempted from CSRF validation as it is a plausible vector for cross-site request forgery. As such, POSTing with AJAX can make use of the aforementioned method, but other HTTP methods, such as PUT and DELETE might be better suited to using the X-CSRFToken header instead.
Essentially this header is passed back to the backend by way of extracting the token from the cookie using JavaScript. For a better explanation of how this might be done please refer to the Django CSRF documentation.
Flask-WTForms Usage¶
If you would like to use Flask-Seasurf with a form generator, such as WTForms, it is possible to do so. Below is a simple example.
First we will define a custom SeaSurfForm object in a seasurf_form module like so:
from wtforms import Form, HiddenField
from flask import g
# import your app here
from your_project import app
class SeaSurfForm(Form):
@staticmethod
@app.before_request
def add_csrf():
csrf_name = app.config.get('CSRF_COOKIE_NAME', '_csrf_token')
setattr(SeaSurfForm,
csrf_name,
HiddenField(default=getattr(g, csrf_name)))
Now assume we define a module forms as such:
from wtforms.validators import DataRequired, StringField, PasswordField, Email
from seasurf_form import SeaSurfForm
class LoginForm(SeaSurfForm):
email = StringField('email', validators=[DataRequired(), Email()])
password = PasswordField('password', validators=[DataRequired()])
This is the basis of our login form which we will serve up in a view to the user. Finally we can use this in our template login.html:
<form method="POST" action="{{ url_for('login') }}">
{{ form.hidden_tag() }}
<p>
{{form.email.label }} {{ form.email(size=50) }}
</p>
<p>
{{form.password.label }} {{ form.password(size=50) }}
</p>
<p>
<input type="submit" value="Login">
</p>
</form>