Update examples and README.md

Author: vimalloc

README.md

@@ -7,9 +7,12 @@
 jwt = JWTManager(app)
 
 
+# Using the user_claims_loader, we can specify a method that will be called
+# when creating access tokens, and add these claims to the said token. This
+# method is passed the identity of who the token is being created for, and
+# must return data that is json serializable
 @jwt.user_claims_loader
 def add_claims_to_access_token(identity):
-    # These must be json serializable
     return {
         'hello': identity,
         'foo': ['bar', 'baz']
@@ -27,6 +30,8 @@ def login():
     return jsonify(ret), 200
 
 
+# In a protected view, get the claims you added to the jwt with the
+# get_jwt_claims() method
 @app.route('/protected', methods=['GET'])
 @jwt_required
 def protected():

examples/additional_data_in_access_token.py

@@ -7,7 +7,7 @@
 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
+    create_refresh_token, jwt_refresh_token_required, get_stored_token
 
 # Setup flask
 app = Flask(__name__)
@@ -18,7 +18,7 @@
 
 # Enable and configure the JWT blacklist / token revoke. We are using an in
 # memory store for this example. In production, you should use something
-# else (csuch as redis, memcached, sqlalchemy). See here for options:
+# 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()
@@ -60,33 +60,40 @@ def list_identity_tokens():
 
 
 # Endpoint for listing all tokens. In your app, you should either not expose
-# this, or put some addition security on top of it so only trusted users,
+# 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 revoking a token
+# 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 = get_jwt_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 foun'}), 404
+        return jsonify({'msg': 'Token not found'}), 404
 
 
-# Endpoint for un-revoking a token
 @app.route('/auth/tokens/unrevoke/<string:jti>', methods=['PUT'])
 @jwt_required
-def change_jwt_revoke_state(jti):
+def change_jwt_unrevoke_state(jti):
+    username = get_jwt_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 foun'}), 404
+        return jsonify({'msg': 'Token not found'}), 404
 
 
 @app.route('/protected', methods=['GET'])

examples/app.py

@@ -6,7 +6,9 @@
 jwt = JWTManager(app)
 
 
-@jwt.expired_token_callback
+# Use the expired_token_loader to call this function whenever an expired but
+# otherwise valid access token tries to access an endpoint
+@jwt.expired_token_loader
 def my_expired_token_callback():
     return jsonify({
         'status': 401,

examples/blacklist.py

@@ -14,13 +14,20 @@ def login():
     if username != 'test' and password != 'test':
         return jsonify({"msg": "Bad username or password"}), 401
 
+    # Use create_access_token() and create_refresh_token() to create our
+    # access and refresh tokens
     ret = {
         'access_token': create_access_token(identity=username),
         'refresh_token': create_refresh_token(identity=username)
     }
     return jsonify(ret), 200
 
 
+# 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 to make a new access token for this
+# identity.
 @app.route('/refresh', methods=['POST'])
 @jwt_refresh_token_required
 def refresh():

examples/loaders.py

@@ -3,9 +3,13 @@
 
 app = Flask(__name__)
 app.secret_key = 'super-secret'  # Change this!
+
+# Setup the Flask-JWT-Extended extension
 jwt = JWTManager(app)
 
 
+# Provide a method to create access tokens. The create_access_token() function
+# is used to actually generate the token
 @app.route('/login', methods=['POST'])
 def login():
     username = request.json.get('username', None)
@@ -17,6 +21,8 @@ def login():
     return jsonify(ret), 200
 
 
+# Protect a view with jwt_required, which requires a valid access token in the
+# request to access.
 @app.route('/protected', methods=['GET'])
 @jwt_required
 def protected():

examples/refresh_tokens.py

@@ -8,22 +8,30 @@
 jwt = JWTManager(app)
 
 
+# Standard login endpoint. Will return a fresh access token and a refresh token
 @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
 
+    # create_access_token supports an optional 'fresh' argument, which marks the
+    # token as fresh or non-fresh accordingly. As we just verified their username
+    # and password, we are going to mark the token as fresh here.
     ret = {
         'access_token': create_access_token(identity=username, fresh=True),
         'refresh_token': create_refresh_token(identity=username)
     }
     return jsonify(ret), 200
 
 
-@app.route('/login', methods=['POST'])
-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 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)
+@app.route('/fresh-login', methods=['POST'])
+def fresh_login():
     username = request.json.get('username', None)
     password = request.json.get('password', None)
     if username != 'test' and password != 'test':
@@ -33,6 +41,9 @@ def login():
     return jsonify(ret), 200
 
 
+# Refresh token endpoint. This will generate a new access token from the refresh
+# token, but will mark that access token as non-fresh (so that it cannot access
+# any endpoint protected via the fresh_jwt_required decorator)
 @app.route('/refresh', methods=['POST'])
 @jwt_refresh_token_required
 def refresh():
@@ -43,13 +54,15 @@ def refresh():
     return jsonify(ret), 200
 
 
+# Any valid jwt can access this endpoint
 @app.route('/protected', methods=['GET'])
 @jwt_required
 def protected():
     username = get_jwt_identity()
     return jsonify({'hello': 'from {}'.format(username)}), 200
 
 
+# Only fresh jwts can access this endpoint
 @app.route('/protected-fresh', methods=['GET'])
 @fresh_jwt_required
 def protected_fresh():

examples/simple.py

@@ -3,4 +3,4 @@
                     create_refresh_token, create_access_token, get_jwt_identity,
                     get_jwt_claims)
 from .blacklist import (revoke_token, unrevoke_token, get_stored_tokens,
-                        get_all_stored_tokens)
+                        get_all_stored_tokens, get_stored_token)