Loader examples

Author: vimalloc

README.md

@@ -218,7 +218,58 @@ The only real things to note here is the new @fresh_jwt_required decorator, and
 the optional 'fresh=' keyword passed to the 'create_access_token' methods.
 
 ### Changing Default Behaviors
-TODO
+We provide what we think are sensible behaivors when attempting to access a protected
+endpoint. If the endpoint could not be used for any reason (missing/expired/invalid/etc
+access token) we will return json in the format of {'msg': <why accesing endpoint failed>}
+along with an appropiate http status code (generally 401 or 422). However, you may want
+to cusomize what is sent back in these cases. We can do that with the jwt_manager
+'loader' functions. 
+```python
+from flask import Flask, jsonify, request
+from flask_jwt_extended import JWTManager, jwt_required, create_access_token
+
+app = Flask(__name__)
+app.secret_key = 'super-secret'  # Change this!
+jwt = JWTManager(app)
+
+
+@jwt.expired_token_callback
+def my_expired_token_callback():
+    return jsonify({
+        'status': 401,
+        'sub_status': 101,
+        'msg': 'The token has expired'
+    }), 200
+
+
+@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(username)}
+    return jsonify(ret), 200
+
+
+@app.route('/protected', methods=['GET'])
+@jwt_required
+def protected():
+    return jsonify({'hello': 'world'}), 200
+
+if __name__ == '__main__':
+    app.run()
+```
+Now if an expired token tries to access the protected endpoint, we will get the
+json we specified back instead of our default behaivor.
+
+The available loader functions are:
+* expired_token_loader
+* invalid_token_loader  (function takes one arg, which is an error string of why its invalid)
+* unauthorized_loader
+* needs_fresh_token_loader
+* revoked_token_loader  (see Blacklist and Token Revoking bellow)
 
 ### Adding Custom Claims to the Access Token
 TODO

examples/loaders.py

@@ -0,0 +1,35 @@
+from flask import Flask, jsonify, request
+from flask_jwt_extended import JWTManager, jwt_required, create_access_token
+
+app = Flask(__name__)
+app.secret_key = 'super-secret'  # Change this!
+jwt = JWTManager(app)
+
+
+@jwt.expired_token_callback
+def my_expired_token_callback():
+    return jsonify({
+        'status': 401,
+        'sub_status': 101,
+        'msg': 'The token has expired'
+    }), 200
+
+
+@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(username)}
+    return jsonify(ret), 200
+
+
+@app.route('/protected', methods=['GET'])
+@jwt_required
+def protected():
+    return jsonify({'hello': 'world'}), 200
+
+if __name__ == '__main__':
+    app.run()

flask_jwt_extended/jwt_manager.py

@@ -29,7 +29,7 @@ def __init__(self, app=None):
 
         # Function that will be called when attempting to access a fresh_jwt_required
         # endpoint with a valid token that is not fresh
-        self.token_needs_refresh_callback = lambda: (
+        self.needs_fresh_token_callback = lambda: (
             jsonify({'msg': 'Fresh token required'}), 401
         )
 
@@ -100,7 +100,7 @@ def unauthorized_loader(self, callback):
         self.unauthorized_callback = callback
         return callback
 
-    def token_needs_refresh_loader(self, callback):
+    def needs_fresh_token_loader(self, callback):
         """
         Sets the callback method to be called if a valid and non-fresh token
         attempts to access an endpoint protected with @fresh_jwt_required.
@@ -110,7 +110,7 @@ def token_needs_refresh_loader(self, callback):
 
         Callback must be a function that takes no arguments.
         """
-        self.token_needs_refresh_callback = callback
+        self.needs_fresh_token_callback = callback
         return callback
 
     def revoked_token_loader(self, callback):

flask_jwt_extended/utils.py

@@ -179,7 +179,7 @@ def wrapper(*args, **kwargs):
         except RevokedTokenError:
             return m.revoked_token_callback()
         except FreshTokenRequired:
-            return m.token_needs_refresh_callback()
+            return m.needs_fresh_token_callback()
     return wrapper
 
 

tests/test_jwt_manager.py

@@ -62,10 +62,10 @@ def test_default_unauthorized_callback(self):
             self.assertEqual(status_code, 401)
             self.assertEqual(data, {'msg': 'Missing Authorization Header'})
 
-    def test_default_token_needs_refresh_callback(self):
+    def test_default_needs_fresh_token_callback(self):
         with self.app.test_request_context():
             m = JWTManager(self.app)
-            result = m.token_needs_refresh_callback()
+            result = m.needs_fresh_token_callback()
             status_code, data = self._parse_callback_result(result)
 
             self.assertEqual(status_code, 401)
@@ -133,15 +133,15 @@ def custom_unauthorized():
             self.assertEqual(status_code, 200)
             self.assertEqual(data, {'err': 'GOTTA LOGIN FOOL'})
 
-    def test_custom_token_needs_refresh_callback(self):
+    def test_custom_needs_fresh_token_callback(self):
         with self.app.test_request_context():
             m = JWTManager(self.app)
 
-            @m.token_needs_refresh_loader
+            @m.needs_fresh_token_loader
             def custom_token_needs_refresh():
                 return jsonify({'sub_status': 101}), 200
 
-            result = m.token_needs_refresh_callback()
+            result = m.needs_fresh_token_callback()
             status_code, data = self._parse_callback_result(result)
 
             self.assertEqual(status_code, 200)