Skip to content

Commit

Permalink
Update the list of configuration variables (#104)
Browse files Browse the repository at this point in the history
* Update the list of configuration variables

The only way to tell the default behavior of the extension was to look in the code.

This commit changes the structure of the doc section related to config variables to be presented as a table and to list default values. Some of the missing config variables were added along the way.

* Update index.rst
  • Loading branch information
killthekitten committed Aug 3, 2021
1 parent 4dd3ee0 commit ac71b13
Showing 1 changed file with 55 additions and 12 deletions.
67 changes: 55 additions & 12 deletions docs/index.rst
Expand Up @@ -43,18 +43,61 @@ then passing your application object back to the extension, like this:
csrf = SeaSurf(app)
This extension is configurable via a set of configuration variables which can
be added to the Flask app's config file:

- `CSRF_COOKIE_NAME` for the cookie name
- `CSRF_COOKIE_TIMEOUT` for the cookie timeout
- `CSRF_COOKIE_HTTPONLY` for setting the cookie HTTPOnly flag
- `CSRF_COOKIE_SECURE` for setting the cookie secure flag
- `CSRF_COOKIE_PATH` for setting the cookie path
- `CSRF_COOKIE_DOMAIN` for setting the cookie domain
- `CSRF_COOKIE_SAMESITE` for setting the cookie samesite
- `CSRF_DISABLE` to disable CSRF prevention

Except for the last option, all values are passed verbatim to the `Response.set_cookie
be added to the Flask app's config:

.. list-table:: Title
:widths: 25 50 25
:header-rows: 1

* - 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
<http://flask.pocoo.org/docs/0.12/api/#flask.Response.set_cookie>`_ method.

Corresponding code will need to be added to the templates where `POST`, `PUT`,
Expand Down

0 comments on commit ac71b13

Please sign in to comment.