Update blacklist documentation

Author: vimalloc

docs/blacklist_and_token_revoking.rst

@@ -17,13 +17,19 @@ from the store automatically, so it wont blow up into something huge.
 
 We also have to 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.
+and cons to either way, namely extra overhead on jwt_required endpoints vs someone
+being able to use an access token freely until it expires. In this example, we are
+looking at all tokens:
 
 .. literalinclude:: ../examples/blacklist.py
 
+If you want better performance (ie, not having to check the blacklist store
+with every request), you could check only the refresh tokens. This makes it
+so any call to a jwt_required endpoint does not need to check the blacklist
+store, but on the flip side would allow a compromised access token to be used
+until it expired. If using the approach, you should set the access tokens to
+have a very short lifetime to help combat this.
+
 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

examples/blacklist.py

@@ -21,11 +21,11 @@
 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)
+# Check all tokens (access and refresh) to see if they have been revoked.
+# You can alternately check only the refresh tokens here, by setting this
+# to 'refresh' instead of 'all'
+app.config['JWT_BLACKLIST_TOKEN_CHECKS'] = 'all'
+app.config['JWT_ACCESS_TOKEN_EXPIRES'] = datetime.timedelta(minutes=5)
 
 jwt = JWTManager(app)
 
@@ -56,23 +56,42 @@ def refresh():
     return jsonify(ret), 200
 
 
-# Endpoint for revoking an access token when logging out.
-# Please make sure JWT_BLACKLIST_TOKEN_CHECKS is set to 'all'
+# Helper method to revoke the current token used to access
+# a protected endpoint
+def _revoke_current_token():
+    current_token = get_raw_jwt()
+    jti = current_token['jti']
+    revoke_token(jti)
+
+
+# Endpoint for revoking the current users access token
 @app.route('/logout', methods=['POST'])
 @jwt_required
 def logout():
-    jwt = get_raw_jwt()
-    jti = jwt['jti']
     try:
-        revoke_token(jti)
+        _revoke_current_token()
+    except KeyError:
+        return jsonify({
+            'msg': 'Access token not found in the blacklist store'
+        }), 500
+    return jsonify({"msg": "Successfully logged out"}), 200
+
+
+# Endpoint for revoking the current users refresh token
+@app.route('/logout2', methods=['POST'])
+@jwt_refresh_token_required
+def logout2():
+    try:
+        _revoke_current_token()
     except KeyError:
         return jsonify({
-            'msg': 'Requires access tokens to be blacklisted'
+            'msg': 'Refresh token not found in the blacklist store'
         }), 500
     return jsonify({"msg": "Successfully logged out"}), 200
 
 
 # Endpoint for listing tokens that have the same identity as you
+# NOTE: This is currently very inefficient.
 @app.route('/auth/tokens', methods=['GET'])
 @jwt_required
 def list_identity_tokens():