More documentation updates

Author: vimalloc

docs/add_custom_data_claims.rst

@@ -1,16 +1,15 @@
-Adding Custom Data (Claims) to the Access Token
-===============================================
+Storing Data in Access Tokens
+=============================
 
-You may want to store additional information in the access token. Perhaps you
-want to save the permissions this user has so you can access them in the view
-functions, without having to make a database call each time. This can be done
-with the user_claims_loader decorator, and accessed later with the
-'get_jwt_claims()' method (in a protected endpoint).
+You may want to store additional information in the access token which you could
+later access in the protected views. This can be done with the **user_claims_loader**
+decorator, and the data can be accessed later in a protected endpoint
+with the **get_jwt_claims()** method.
 
 .. literalinclude:: ../examples/additional_data_in_access_token.py
 
 Storing data in an access token can be good for performance. If you store data
 in the token, you wont need to look it up from disk next time you need it in
-a protected endpoint. But be warned, any data in the access token can be easily
-viewed with anyone who has access to said token, so refrain from storing
-critical data there!
+a protected endpoint. However, you should take care what data you put in the
+token. Any data in the access token can be easily viewed with anyone who has
+access to the token. Take care to avoid storing sensative information in here!

docs/basic_usage.rst

@@ -1,13 +1,13 @@
 Basic Usage
 ===========
 
-
 In its simplest form, there is not much to using flask_jwt_extended.
 
-
 .. literalinclude:: ../examples/simple.py
 
-To access a jwt_required protected view, all we have to do is send an authorization head with the request that include the token. The header looks like this:
+To access a jwt_required protected view, all we have to do is send in the
+JWT with the request. By default, this is done with an authorization header
+that looks like:
 
 .. code-block :: bash
 
@@ -35,3 +35,8 @@ We can see this in action using CURL:
   {
     "hello": "world"
   }
+
+NOTE: Remember to change the secret key of your application, and insure that no
+one is able to view it. The json web tokens are signed with the secret key, so
+if someone gets that, they can create arbitrary tokens, and in essence log in
+as any user.

docs/changing_default_behavior.rst

@@ -5,8 +5,8 @@ We provide what we think are sensible behaviors when attempting to access a
 protected endpoint. If the access token is not valid for any reason (missing,
 expired, tampered with, etc) we will return json in the format of {'msg': 'why
 accessing endpoint failed'} along with an appropriate http status code
-(generally 401 or 422). However, you may want to customize what you returned in
-these situations. We can do that with the jwt_manager loader functions.
+(generally 401 or 422). However, you may want to customize what you return in
+some situations. We can do that with the jwt_manager loader functions.
 
 
 .. literalinclude:: ../examples/loaders.py
@@ -16,21 +16,21 @@ Possible loader functions are:
 .. list-table::
     :header-rows: 1
 
-    * - Decorator
+    * - Loader Decorator
       - Description
-      - Callback Function Arguments
-    * - expired_token_loader
-      - Function to call when an expired token accesses a protected view
+      - Function Arguments
+    * - **expired_token_loader**
+      - Function to call when an expired token accesses a protected endpoint
       - None
-    * - invalid_token_loader
-      - Function to call when an invalid token accesses a protected view
-      - One argument: error string of why it is invalid
-    * - unauthorized_loader
-      - Function to call when a request with no JWT accesses a protected view
+    * - **invalid_token_loader**
+      - Function to call when an invalid token accesses a protected endpoint
+      - Takes one argument - an error string indicating why the token is invalid
+    * - **unauthorized_loader**
+      - Function to call when a request with no JWT accesses a protected endpoint
       - None
-    * - needs_fresh_token_loader
-      - Function to call when a non-fresh token tries to access a **fresh_jwt_required** view
+    * - **needs_fresh_token_loader**
+      - Function to call when a non-fresh token accesses a **fresh_jwt_required** endpoint
       - None
-    * - revoked_token_loader
-      - Function to call when a revoked token accesses a protected view
+    * - **revoked_token_loader**
+      - Function to call when a revoked token accesses a protected endpoint
       - None

docs/options.rst

@@ -1,8 +1,40 @@
 Configuration Options
 =====================
 
-.. literalinclude:: ../flask_jwt_extended/config.py
-  :language: python
+You can change many options for how this extension works via
 
-.. .. automodule:: flask_jwt_extended.config
-..   :members:
+.. code-block:: python
+
+  app.config[OPTION_NAME] = new_options
+
+The available options are:
+
+.. tabularcolumns:: |p{6.5cm}|p{8.5cm}|
+================================= =========================================
+``JWT_TOKEN_LOCATION``            Where to find the JWT in the request. The options are ``'headers'`` or
+                                  ``'cookies'``. Defaults to ``'headers'``
+``JWT_HEADER_NAME``               What header to look for the JWT in a request. Only has an effect if
+                                  JWT_TOKEN_LOCATION is 'headers'. Defaults to ``'Authorization'``
+``JWT_HEADER_TYPE``               What type of header the JWT is in. Defaults to ``'Bearer'``. This can be
+                                  an empty string, in which case the header only contains the JWT
+``JWT_COOKIE_CSRF_PROTECT``       Enable/disable CSRF protection when using 'cookies' as the JWT_TOKEN_LOCATION.
+                                  This has no affect if using 'headers' as the JWT_TOKEN_LOCATION
+``JWT_ACCESS_CSRF_COOKIE_NAME``   Name of the CSRF access cookie. Defaults to ``'csrf_access_token'``. Only used
+                                  if using cookies with CSRF protection enabled
+``JWT_REFRESH_CSRF_COOKIE_NAME``  Name of the CSRF refresh cookie. Defaults to ``'csrf_refresh_token'``. Only used
+                                  if using cookies with CSRF protection enabled
+``JWT_CSRF_HEADER_NAME``          Name of the header that we will look for the CSRF double submit token in.
+                                  Defaults to ``X-CSRF-TOKEN``. Only used if using cookies with CSRF protection enabled
+``JWT_ACCESS_TOKEN_EXPIRES``      How long an access token should live before it expires. This takes a
+                                  ``datetime.timedelta``, and defaults to 15 minutes
+``JWT_REFRESH_TOKEN_EXPIRES``     How long a refresh token should live before it expires. This takes a
+                                  ``datetime.timedelta``, and defaults to 30 days
+``JWT_ALGORITHM``                 Which algorithm to sign the JWT with. `See here
+                                  <https://pyjwt.readthedocs.io/en/latest/algorithms.html>`_ for the options. Defaults
+                                  to ``'HS256'``. Note that Asymmetric (Public-key) Algorithms are not currently supported.
+``JWT_BLACKLIST_ENABLED``         Enable/disable token blackliting and revoking. Defaults to ``False``
+``JWT_BLACKLIST_STORE``           Where to save revoked tokens. `See here 
+                                  <http://pythonhosted.org/simplekv/>`_ for options.
+``JWT_BLACKLIST_CHECKS``          What token types to check against the blacklist. Options are
+                                  ``'refresh'`` or  ``'all'``. Defaults to ``'refresh'``
+================================= =========================================

docs/refresh_tokens.rst

@@ -1,12 +1,17 @@
 Refresh Tokens
 ==============
 
-Flask-JWT-Extended supports refresh tokens out of the box. These are longer
-lived token which cannot access a jwt_required protected endpoint, but can be
-used to create new access tokens once an old access token has expired.
+Flask-JWT-Extended supports refresh tokens out of the box. These are long
+lived tokens which can be used to create new access tokens once an old access
+token has expired. Refresh tokens cannot access a **jwt_requred** protected
+endpoint.
 
 .. literalinclude:: ../examples/refresh_tokens.py
 
 By setting the access tokens to a shorter lifetime (see Configuration Options),
-and utilizing fresh tokens for critical views (see Token Freshness next) we can
-help reduce the damage done if an access token is stolen.
+and utilizing refresh tokens we can help reduce the damage that can be done if
+an access token is stolen. However, we need to take extra care to prevent the
+refresh token from being stolen. If an attacker gets his hands on this, he can
+keep generating new access tokens and accessing protected endpoints as though
+he was that user. We can help combat this by using fresh tokens, discussed in
+the next section.

docs/token_freshness.rst

@@ -1,25 +1,21 @@
 Token Freshness
 ===============
 
-
-
 We have the idea of token freshness built into this extension. In a nutshell,
 you can choose to mark some access tokens as fresh and others as non-fresh, and
-use the fresh_jwt_required decorator to only allow fresh tokens to access some
-views.
+use the **fresh_jwt_required** decorator to only allow fresh tokens to access some
+endpoints.
 
 This is useful for allowing fresh tokens to do some critical things (maybe
 change a password, or complete an online purchase), but to deny those features
-to non-fresh tokens without forcing them to re-authenticate. This still allows
-your users to access any of the normal jwt_protected endpoints while using a
-non-fresh token. This can lead to a more secure site, without creating a
-burden on the users experiences by forcing them to always be re-authenticating.
+to non-fresh tokens (until they re-authenticate and get a new fresh token).
+Fresh tokens can lead to a more secure site, without creating a bad users
+experience by making users re-authenticate all the time.
 
-The provided API gives you the power to use the token freshness however you may
-want to. A very natural way to do this would be to mark a token as fresh when
-they first login, mark any tokens generated with the refresh token to as not
+The provided API gives you the power to create and use fresh tokens however you
+want. A very natural way to utilize them is to mark a token as fresh when
+someone first logs in, and mark tokens generated by a refresh token as not
 fresh.
 
-
 .. literalinclude:: ../examples/token_freshness.py
 

examples/loaders.py

@@ -7,9 +7,9 @@
 jwt = JWTManager(app)
 
 
-# Use the expired_token_loader to call this function whenever an
-# expired but # otherwise valid access token tries to access
-# an endpoint
+# Using the expired_token_loader decorator, we will now call
+# this function whenever an expired but otherwise valid access
+# token attempts to access an endpoint
 @jwt.expired_token_loader
 def my_expired_token_callback():
     return jsonify({

examples/refresh_tokens.py

@@ -27,7 +27,7 @@ def login():
 # The jwt_refresh_token_required decorator insures a valid refresh
 # token is present in the request before calling this endpoint. We
 # can use the get_jwt_identity() function to get the identity of
-# the refresh toke, and use the create_access_token() function again
+# the refresh token, and use the create_access_token() function again
 # to make a new access token for this identity.
 @app.route('/refresh', methods=['POST'])
 @jwt_refresh_token_required

examples/token_freshness.py

@@ -29,10 +29,10 @@ def login():
 
 
 # Fresh login endpoint. This is designed to be used if we need to
-# make a fresh # token for a user (by verifying they have the
+# make a fresh token for a user (by verifying they have the
 # correct username and password). Unlike the standard login endpoint,
-# this will only return a new access token (so that we don't keep
-# generating new refresh tokens, which defeats their point)
+# this will only return a new access token, so that we don't keep
+# generating new refresh tokesn, which entirely defeats their point.
 @app.route('/fresh-login', methods=['POST'])
 def fresh_login():
     username = request.json.get('username', None)

flask_jwt_extended/config.py

@@ -29,6 +29,8 @@
 ACCESS_COOKIE_PATH = None
 REFRESH_COOKIE_PATH = None
 
+# TODO only one header for both access and refresh tokens, as we will only be
+#      checking one of those at a time
 # Options for using double submit for verifying CSRF tokens
 COOKIE_CSRF_PROTECT = True
 ACCESS_CSRF_COOKIE_NAME = 'csrf_access_token'