Update more documentation, add cookie and csrf docs

Author: vimalloc

README.md

@@ -1,118 +1,31 @@
 Blacklist and Token Revoking
 ============================
 
-This supports optional blacklisting and token revoking out of the box. This will allow you to revoke a specific token so a user can no longer access your endpoints. In order to revoke a token, we need some storage where we can save a list of all the tokens we have created, as well as if they have been revoked or not. In order to make the underlying storage as agnostic as possible, we use simplekv to provide assess to a variety of backends.
-
-In production, it is important to use a backend that can have some sort of persistent storage, so we don't 'forget' that we revoked a token if the flask process is restarted. We also need something that can be safely used by the multiple thread and processes running your application. At present we believe redis is a good fit for this. It has the added benefit of removing expired tokens from the store automatically, so it wont blow up into something huge.
-
-We also have choose what tokens we want to check against the blacklist. We could check all tokens (refresh and access), or only the refresh tokens. There are pros and cons to either way (extra overhead on jwt_required endpoints vs someone being able to use an access token freely until it expires). In this example, we are going to only check refresh tokens, and set the access tokes to a small expires time to help minimize damage that could be done with a stolen access token.
-
-.. code-block:: python
-
-  from datetime import timedelta
-  
-
-  import simplekv
-  import simplekv.memory
-  from flask import Flask, request, jsonify
-
-  from flask_jwt_extended import JWTManager, jwt_required, \
-      get_jwt_identity, revoke_token, unrevoke_token, \
-      get_stored_tokens, get_all_stored_tokens, create_access_token, \
-      create_refresh_token, jwt_refresh_token_required
-
-  # Setup flask
-  app = Flask(__name__)
-  app.secret_key = 'super-secret'
-
-  # Configure access token expires time
-  app.config['JWT_ACCESS_TOKEN_EXPIRES'] = timedelta(minutes=5)
-
-  # Enable and configure the JWT blacklist / token revoke. We are using an in
-  # memory store for this example. In production, you should use something
-  # persistant (such as redis, memcached, sqlalchemy). See here for options:
-  # http://pythonhosted.org/simplekv/
-  app.config['JWT_BLACKLIST_ENABLED'] = True
-  app.config['JWT_BLACKLIST_STORE'] = simplekv.memory.DictStore()
-  app.config['JWT_BLACKLIST_TOKEN_CHECKS'] = 'refresh'
-
-  jwt = JWTManager(app)
-
-
-  @app.route('/login', methods=['POST'])
-  def login():
-      username = request.json.get('username', None)
-      password = request.json.get('password', None)
-      if username != 'test' and password != 'test':
-          return jsonify({"msg": "Bad username or password"}), 401
-
-      ret = {
-          'access_token': create_access_token(identity=username),
-          'refresh_token': create_refresh_token(identity=username)
-      }
-      return jsonify(ret), 200
-
-
-  @app.route('/refresh', methods=['POST'])
-  @jwt_refresh_token_required
-  def refresh():
-      current_user = get_jwt_identity()
-      ret = {
-          'access_token': create_access_token(identity=current_user)
-      }
-      return jsonify(ret), 200
-
-
-  # Endpoint for listing tokens that have the same identity as you
-  @app.route('/auth/tokens', methods=['GET'])
-  @jwt_required
-  def list_identity_tokens():
-      username = get_jwt_identity()
-      return jsonify(get_stored_tokens(username)), 200
-
-
-  # Endpoint for listing all tokens. In your app, you should either not expose
-  # this endpoint, or put some addition security on top of it so only trusted users,
-  # (administrators, etc) can access it
-  @app.route('/auth/all-tokens')
-  def list_all_tokens():
-      return jsonify(get_all_stored_tokens()), 200
-
-
-  # Endpoint for allowing users to revoke their tokens
-  @app.route('/auth/tokens/revoke/<string:jti>', methods=['PUT'])
-  @jwt_required
-  def change_jwt_revoke_state(jti):
-      username = jwt_get_identity()
-      try:
-          token_data = get_stored_token(jti)
-          if token_data['token']['identity'] != username:
-              raise KeyError
-          revoke_token(jti)
-          return jsonify({"msg": "Token successfully revoked"}), 200
-      except KeyError:
-          return jsonify({'msg': 'Token not found'}), 404
-
-
-  # Endpoint for allowing users to unrevoke their tokens
-  @app.route('/auth/tokens/unrevoke/<string:jti>', methods=['PUT'])
-  @jwt_required
-  def change_jwt_unrevoke_state(jti):
-      username = jwt_get_identity()
-      try:
-          token_data = get_stored_token(jti)
-          if token_data['token']['identity'] != username:
-              raise KeyError
-          unrevoke_token(jti)
-          return jsonify({"msg": "Token successfully unrevoked"}), 200
-      except KeyError:
-          return jsonify({'msg': 'Token not found'}), 404
-
-
-  @app.route('/protected', methods=['GET'])
-  @jwt_required
-  def protected():
-      return jsonify({'hello': 'world'})
-
-  if __name__ == '__main__':
-      app.run()
+This extension supports optional token revoking out of the box. This will
+allow you to revoke a specific token so that it can no longer access your endpoints.
+In order to revoke a token, we need some storage where we can save a list of all
+the tokens we have created, as well as if they have been revoked or not. In order
+to make the underlying storage as agnostic as possible, we use `simplekv
+<http://pythonhosted.org/simplekv/>`_ to provide assess to a variety of backends.
+
+In production, it is important to use a backend that can have some sort of
+persistent storage, so we don't 'forget' that we revoked a token if the flask
+process is restarted. We also need something that can be safely used by the
+multiple thread and processes running your application. At present we believe
+redis is a good fit for this. It has the added benefit of removing expired tokens
+from the store automatically, so it wont blow up into something huge.
+
+We also have choose what tokens we want to check against the blacklist. We could
+check all tokens (refresh and access), or only the refresh tokens. There are pros
+and cons to either way (extra overhead on jwt_required endpoints vs someone being
+able to use an access token freely until it expires). In this example, we are going
+to only check refresh tokens, and set the access tokes to a small expires time to
+help minimize damage that could be done with a stolen access token.
+
+.. literalinclude:: ../examples/blacklist.py
+
+It's worth noting that if your selected backend support the `time to live mixin
+<http://pythonhosted.org/simplekv/#simplekv.TimeToLiveMixin>`_ (such as redis),
+keys will be automatically deleted from the store at some point after they have
+expired. This prevents your store from blowing up with old keys without you having
+to do any work to prune it back down.

docs/blacklist_and_token_revoking.rst

@@ -11,17 +11,13 @@ Welcome to flask-jwt-extended's documentation!
 
    installation
    basic_usage
-
    add_custom_data_claims
    refresh_tokens
    token_freshness
    changing_default_behavior
    options
    blacklist_and_token_revoking
-   testing_and_coverage
-
-   documentation
-
+   tokens_in_cookies
 
 
 Indices and tables

docs/index.rst

@@ -10,15 +10,15 @@ You can change many options for how this extension works via
 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_NAME``               What header to look for the JWT in a request. Only used if we are sending
+                                  the JWT in via 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_COOKIE_CSRF_PROTECT``       Enable/disable CSRF protection. Only used when sending the JWT in via cookies
 ``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
@@ -33,7 +33,7 @@ The available options are:
                                   <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 
+``JWT_BLACKLIST_STORE``           Where to save created and 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/options.rst

@@ -0,0 +1,46 @@
+JWT in Cookies
+==============
+If the frontend that is consuming this backend is a website, you may be tempted
+to store your JWTs in the browser localStorage or sessionStorage. There is nothing
+necessarily wrong with this, but if you have any sort of XSS vulnerability on your
+site, an attacker will be able to trivially steal your refresh and access tokens.
+If you want some additional security on your site, you can save your JWTs in a
+httponly cookie instead, which keeps javascript from being able to access the
+cookie. See this great blog for a more in depth analysis between these options:
+https://stormpath.com/blog/where-to-store-your-jwts-cookies-vs-html5-web-storage.
+
+Here is a basic example of how to store JWTs in cookies:
+
+.. literalinclude:: ../examples/jwt_in_cookie.py
+
+This isn't the full story however. We can now keep our cookie from being stolen via XSS
+attacks, but have traded that for a vulnerability to CSRF attacks. To combat
+CSRF, we are going to use a technique called double submit verification.
+
+When we create a JWT, we will also create a random string and store it in the JWT. This token is saved
+in a cookie with httponly set to True, so it cannot be accessed via javascript.
+We will then create a secondary cookie that contains only the random string, but
+has httponly set to False, so that it can be accessed via javascript running on
+your website. Now in order to access a protected endpoint,
+you will need to add a custom header that contains the the random string in it,
+and if that header doesn't exist or it doesn't match the string that is stored
+in the JWT, the request will be kicked out as unauthorized.
+
+To break this down, if an attacker attempts to perform a CSRF attack they will
+send the JWT (via the cookie) to a protected endpoint, but without the random
+string in the requests header, they wont be able to access the endpoint. They
+cannot access the random string, unless they can run javascript on your website
+(likely via an XSS attack), and if they are able to perform an XSS attack, they
+will not be able to steal the actual access and refresh JWTs, as javascript is
+still not able to access those httponly cookies.
+
+This obviously isn't a golden bullet. If an attacker can perform an XSS attack they can
+still access protected endpoint from people who visit your site. However, it is better
+then if they were able to steal the access and refresh tokens tokens from
+local/session storage, and do whatever they wanted with them. If this additional
+security is worth the added complexity of using cookies and double submit CSRF
+protection is a choice you will have to make.
+
+Here is an example of what this would look like:
+
+.. literalinclude::  ../examples/csrf_protection_with_cookies.py

docs/tokens_in_cookies.rst

@@ -1,6 +1,5 @@
-from datetime import timedelta
+import datetime
 
-import simplekv
 import simplekv.memory
 from flask import Flask, request, jsonify
 
@@ -9,24 +8,28 @@
     get_stored_tokens, get_all_stored_tokens, create_access_token, \
     create_refresh_token, jwt_refresh_token_required, get_stored_token
 
+
 # Setup flask
 app = Flask(__name__)
 app.secret_key = 'super-secret'
 
-# Configure access token expires time
-app.config['JWT_ACCESS_TOKEN_EXPIRES'] = timedelta(minutes=5)
-
-# Enable and configure the JWT blacklist / token revoke. We are using an in
-# memory store for this example. In production, you should use something
-# persistant (such as redis, memcached, sqlalchemy). See here for options:
-# http://pythonhosted.org/simplekv/
+# Enable and configure the JWT blacklist / token revoke. We are using
+# an in memory store for this example. In production, you should
+# use something persistent (such as redis, memcached, sqlalchemy).
+# See here for options: http://pythonhosted.org/simplekv/
 app.config['JWT_BLACKLIST_ENABLED'] = True
 app.config['JWT_BLACKLIST_STORE'] = simplekv.memory.DictStore()
+
+# Only check the refresh token for being revoked, and set a small time to live
+# on the access tokens to prevent a compromised one from being used for a long
+# period of time
 app.config['JWT_BLACKLIST_TOKEN_CHECKS'] = 'refresh'
+app.config['JWT_ACCESS_TOKEN_EXPIRES'] = datetime.timedelta(minutes=3)
 
 jwt = JWTManager(app)
 
 
+# Standard login endpoint
 @app.route('/login', methods=['POST'])
 def login():
     username = request.json.get('username', None)
@@ -41,6 +44,7 @@ def login():
     return jsonify(ret), 200
 
 
+# Standard refresh endpoint
 @app.route('/refresh', methods=['POST'])
 @jwt_refresh_token_required
 def refresh():
@@ -59,15 +63,15 @@ def list_identity_tokens():
     return jsonify(get_stored_tokens(username)), 200
 
 
-# Endpoint for listing all tokens. In your app, you should either not expose
-# this endpoint, or put some addition security on top of it so only trusted users,
-# (administrators, etc) can access it
+# Endpoint for listing all tokens. In your app, you should either
+# not expose this endpoint, or put some addition security on top
+# of it so only trusted users (administrators, etc) can access it
 @app.route('/auth/all-tokens')
 def list_all_tokens():
     return jsonify(get_all_stored_tokens()), 200
 
 
-# Endpoint for allowing users to revoke their tokens
+# Endpoint for allowing users to revoke their own tokens.
 @app.route('/auth/tokens/revoke/<string:jti>', methods=['PUT'])
 @jwt_required
 def change_jwt_revoke_state(jti):
@@ -82,6 +86,7 @@ def change_jwt_revoke_state(jti):
         return jsonify({'msg': 'Token not found'}), 404
 
 
+# Endpoint for allowing users to un-revoke their own tokens.
 @app.route('/auth/tokens/unrevoke/<string:jti>', methods=['PUT'])
 @jwt_required
 def change_jwt_unrevoke_state(jti):