Skip to content

Commit 5fa925e

Browse files
vimallocvimalloc
committed
Refact and add new options to documentation page
God, I really hate restructured text sometimes
1 parent 1b429fe commit 5fa925e

File tree

1 file changed

+89
-35
lines changed

1 file changed

+89
-35
lines changed

‎docs/options.rst

Lines changed: 89 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -7,52 +7,106 @@ You can change many options for how this extension works via
77
88
app.config[OPTION_NAME] = new_options
99
10-
The available options are:
10+
General Options:
11+
~~~~~~~~~~~~~~~~
1112

1213
.. tabularcolumns:: |p{6.5cm}|p{8.5cm}|
1314

1415
================================= =========================================
15-
``JWT_TOKEN_LOCATION`` Where to look for a JWT when processing a request. The options are ``'headers'`` or
16-
``'cookies'``. You can pass in a list to check more then one location: ```['headers', 'cookies']```.
16+
``JWT_TOKEN_LOCATION`` Where to look for a JWT when processing a request. The
17+
options are ``'headers'`` or ``'cookies'``. You can pass
18+
in a list to check more then one location, such as: ``['headers', 'cookies']``.
1719
Defaults to ``'headers'``
18-
``JWT_HEADER_NAME`` What header to look for the JWT in a request. Only used if we are sending
19-
the JWT in via headers. Defaults to ``'Authorization'``
20+
``JWT_ACCESS_TOKEN_EXPIRES`` How long an access token should live before it expires. This
21+
takes a ``datetime.timedelta``, and defaults to 15 minutes
22+
``JWT_REFRESH_TOKEN_EXPIRES`` How long a refresh token should live before it expires. This
23+
takes a ``datetime.timedelta``, and defaults to 30 days
24+
``JWT_ALGORITHM`` Which algorithm to sign the JWT with. `See here <https://pyjwt.readthedocs.io/en/latest/algorithms.html>`_
25+
for the options. Defaults to ``'HS256'``. Note that Asymmetric
26+
(Public-key) algorithms are not currently supported.
27+
================================= =========================================
28+
29+
30+
Header Options:
31+
~~~~~~~~~~~~~~~
32+
These are only applicable if ``JWT_TOKEN_LOCATION`` is set to use headers.
33+
34+
.. tabularcolumns:: |p{6.5cm}|p{8.5cm}|
35+
36+
================================= =========================================
37+
``JWT_HEADER_NAME`` What header to look for the JWT in a request. Defaults to ``'Authorization'``
2038
``JWT_HEADER_TYPE`` What type of header the JWT is in. Defaults to ``'Bearer'``. This can be
21-
an empty string, in which case the header only contains the JWT
39+
an empty string, in which case the header contains only the JWT
40+
(insead of something like ``HeaderName: Bearer <JWT>``)
41+
================================= =========================================
42+
43+
44+
Cookie Options:
45+
~~~~~~~~~~~~~~~
46+
These are only applicable if ``JWT_TOKEN_LOCATION`` is set to use cookies.
47+
48+
.. tabularcolumns:: |p{6.5cm}|p{8.5cm}|
49+
50+
================================= =========================================
51+
``JWT_ACCESS_COOKIE_NAME`` The name of the cookie that holds the access token. Defaults to ``access_token_cookie``
52+
``JWT_REFRESH_COOKIE_NAME`` The name of the cookie that holds the refresh token. Defaults to ``refresh_token_cookie``
53+
``JWT_ACCESS_COOKIE_PATH`` What ``path`` should be set for the access cookie. Defaults to ``'/'``,
54+
which will cause this access cookie to be sent in with every request.
55+
Should be modified for only the paths that need the access cookie
56+
``JWT_REFRESH_COOKIE_PATH`` What ``path`` should be set for the refresh cookie.
57+
Defaults to ``'/'``, which will cause this refresh cookie
58+
to be sent in with every request. Should be modified
59+
for only the paths that need the refresh cookie
2260
``JWT_COOKIE_SECURE`` If the secure flag should be set on your JWT cookies. This will only allow
2361
the cookies to be sent over https. Defaults to ``False``, but in production
24-
this should likely be set to ``True``. Only used when sending the JWT in via cookies.
25-
``JWT_ACCESS_COOKIE_NAME`` What the cookie that hold the access JWT will be called. Only used
26-
when sending the JWT in via cookies. Defaults to ``access_token_cookie``
27-
``JWT_REFRESH_COOKIE_NAME`` What the cookie that hold the refresh JWT will be called. Only used
28-
when sending the JWT in via cookies. Defaults to ``refresh_token_cookie``
29-
``JWT_ACCESS_COOKIE_PATH`` What ``path`` should be set for the access cookie. Defaults to ``None``, which
30-
will cause this access cookie to be sent in with every request. Should be modified
31-
for only the paths that need the access cookie
32-
``JWT_REFRESH_COOKIE_PATH`` What ``path`` should be set for the refresh cookie. Defaults to ``None``, which
33-
will cause this access cookie to be sent in with every request. Should be modified
34-
for only the paths that need the refresh cookie
35-
``JWT_SESSION_COOKIE`` Whether to set session (deleted when the browser is closed) or persistent cookies.
36-
Defaults to ``True`` (sets session cookies).
37-
``JWT_COOKIE_CSRF_PROTECT`` Enable/disable CSRF protection. Only used when sending the JWT in via cookies
62+
this should likely be set to ``True``.
63+
``JWT_SESSION_COOKIE`` If the cookies should be session cookies (deleted when the
64+
browser is closed) or persistent cookies (never expire).
65+
Defaults to ``True`` (session cookies).
66+
``JWT_COOKIE_CSRF_PROTECT`` Enable/disable CSRF protection when using cookies. Defaults to ``True``.
67+
================================= =========================================
68+
69+
Cross Site Request Forgery Options:
70+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71+
These are only applicable if ``JWT_TOKEN_LOCATION`` is set to use cookies and
72+
``JWT_COOKIE_CSRF_PROTECT`` is True.
73+
74+
.. tabularcolumns:: |p{6.5cm}|p{8.5cm}|
75+
76+
================================= =========================================
3877
``JWT_CSRF_METHODS`` The request types that will use CSRF protection. Defaults to
39-
```['POST', 'PUT', 'PATCH', 'DELETE']```
40-
``JWT_ACCESS_CSRF_COOKIE_NAME`` Name of the CSRF access cookie. Defaults to ``'csrf_access_token'``. Only used
41-
if using cookies with CSRF protection enabled
42-
``JWT_REFRESH_CSRF_COOKIE_NAME`` Name of the CSRF refresh cookie. Defaults to ``'csrf_refresh_token'``. Only used
43-
if using cookies with CSRF protection enabled
44-
``JWT_CSRF_HEADER_NAME`` Name of the header that we will look for the CSRF double submit token in.
45-
Defaults to ``X-CSRF-TOKEN``. Only used if using cookies with CSRF protection enabled
46-
``JWT_ACCESS_TOKEN_EXPIRES`` How long an access token should live before it expires. This takes a
47-
``datetime.timedelta``, and defaults to 15 minutes
48-
``JWT_REFRESH_TOKEN_EXPIRES`` How long a refresh token should live before it expires. This takes a
49-
``datetime.timedelta``, and defaults to 30 days
50-
``JWT_ALGORITHM`` Which algorithm to sign the JWT with. `See here
51-
<https://pyjwt.readthedocs.io/en/latest/algorithms.html>`_ for the options. Defaults
52-
to ``'HS256'``. Note that Asymmetric (Public-key) Algorithms are not currently supported.
78+
``['POST', 'PUT', 'PATCH', 'DELETE']``
79+
``JWT_ACCESS_CSRF_HEADER_NAME`` Name of the header that should contain the CSRF double submit value
80+
for access tokens. Defaults to ``X-CSRF-TOKEN``.
81+
``JWT_REFRESH_CSRF_HEADER_NAME`` Name of the header that should contains the CSRF double submit value
82+
for refresh tokens. Defaults to ``X-CSRF-TOKEN``.
83+
``JWT_CSRF_IN_COOKIES`` If we should store the CSRF double submit value in
84+
another cookies when using ``set_access_cookies()`` and
85+
``set_refresh_cookies()``. Defaults to ``True``. If this is
86+
False, you are responsible for getting the CSRF value to the
87+
callers (see: ``get_csrf_token(encoded_token)``).
88+
``JWT_ACCESS_CSRF_COOKIE_NAME`` Name of the CSRF access cookie. Defaults to ``'csrf_access_token'``.
89+
Only applicable if ``JWT_CSRF_IN_COOKIES`` is ``True``
90+
``JWT_REFRESH_CSRF_COOKIE_NAME`` Name of the CSRF refresh cookie. Defaults to ``'csrf_refresh_token'``.
91+
Only applicable if ``JWT_CSRF_IN_COOKIES`` is ``True``
92+
``JWT_ACCESS_CSRF_COOKIE_PATH`` Path for the CSRF access cookie. Defaults to ``'/'``.
93+
Only applicable if ``JWT_CSRF_IN_COOKIES`` is ``True``
94+
``JWT_REFRESH_CSRF_COOKIE_PATH`` Path of the CSRF refresh cookie. Defaults to ``'/'``.
95+
Only applicable if ``JWT_CSRF_IN_COOKIES`` is ``True``
96+
================================= =========================================
97+
98+
99+
Blacklist Options:
100+
~~~~~~~~~~~~~~~~~~
101+
102+
.. tabularcolumns:: |p{6.5cm}|p{8.5cm}|
103+
104+
================================= =========================================
53105
``JWT_BLACKLIST_ENABLED`` Enable/disable token blacklisting and revoking. Defaults to ``False``
54106
``JWT_BLACKLIST_STORE`` Where to save created and revoked tokens. `See here
55107
<http://pythonhosted.org/simplekv/>`_ for options.
108+
Only used if blacklisting is enabled.
56109
``JWT_BLACKLIST_TOKEN_CHECKS`` What token types to check against the blacklist. Options are
57-
``'refresh'`` or ``'all'``. Defaults to ``'refresh'``. Only used if blacklisting is enabled.
110+
``'refresh'`` or ``'all'``. Defaults to ``'refresh'``.
111+
Only used if blacklisting is enabled.
58112
================================= =========================================

0 commit comments

Comments
 (0)