Documentation for user_loader functionality (refs #49)

Author: vimalloc

docs/changing_default_behavior.rst

@@ -34,3 +34,9 @@ Possible loader functions are:
     * - **revoked_token_loader**
       - Function to call when a revoked token accesses a protected endpoint
       - None
+    * - **user_loader_callback_loader**
+      - Function to call to load a user object from a token
+      - Takes one argument - The identity of the token to load a user from
+    * - **user_loader_error_loader**
+      - Function that is called when the user_loader callback function returns **None**
+      - Takes one argument - The identity of the user who failed to load

docs/complex_objects_from_token.rst

@@ -0,0 +1,19 @@
+Complex Objects from Tokens
+===========================
+
+We can also do the inverse of creating tokens from complex objects like we did
+in the last section. In this case, we can take a token and every time a
+protected endpoint is accessed automatically use the token to load a complex
+object, for example a SQLAlchemy user object. Here's an example of how it
+might look:
+
+.. literalinclude:: ../examples/complex_objects_from_tokens.py
+
+If you do not provide a user_loader_callback in your application, and attempt
+to access the **current_user** LocalProxy, it will simply be None.
+
+One thing to note with this is that you will now call the **user_loader_callback**
+on all of your protected endpoints, which will probably incur the cost of a
+database lookup. In most cases this likely isn't a big deal for your application,
+but do be aware that it could slow things down if your frontend is doing several
+calls to endpoints in rapid succession.

docs/index.rst

@@ -16,6 +16,7 @@ documentation is coming soon!
    basic_usage
    add_custom_data_claims
    tokens_from_complex_object
+   complex_objects_from_token
    refresh_tokens
    token_freshness
    changing_default_behavior

examples/complex_objects_from_tokens.py

@@ -0,0 +1,74 @@
+from flask import Flask, jsonify, request
+from flask_jwt_extended import (
+    JWTManager, jwt_required, create_access_token,  current_user
+)
+
+app = Flask(__name__)
+app.secret_key = 'super-secret'  # Change this!
+jwt = JWTManager(app)
+
+
+# A user object that we will load our tokens
+class UserObject:
+    def __init__(self, username, roles):
+        self.username = username
+        self.roles = roles
+
+# An example store of users. In production, this would likely
+# be a sqlalchemy instance or something similiar
+users_to_roles = {
+    'foo': ['admin'],
+    'bar': ['peasant'],
+    'baz': ['peasant']
+}
+
+
+# This function is called whenever a protected endpoint is accessed.
+# This should return a complex object based on the token identity.
+# This is called after the token is verified, so you can use
+# get_jwt_claims() in here if desired. Note that this needs to
+# return None if the user could not be loaded for any reason,
+# such as not being found in the underlying data store
+@jwt.user_loader_callback_loader
+def user_loader_callback(identity):
+    if identity not in users_to_roles:
+        return None
+
+    return UserObject(
+        username=identity,
+        roles=users_to_roles[identity]
+    )
+
+
+# You can override the error returned to the user if the
+# user_loader_callback returns None. By default, if you don't
+# override this, it will return a 401 status code with the json:
+# {'msg': "Error loading the user <identity>"}. You can use
+# get_jwt_claims() here too if desired
+@jwt.user_loader_error_loader
+def custom_user_loader_error(identity):
+    return jsonify({"msg": "User not found"}), 404
+
+
+# Create a token for any user, so this can be tested out
+@app.route('/login', methods=['POST'])
+def login():
+    username = request.json.get('username', None)
+    access_token = create_access_token(identity=username)
+    ret = {'access_token': access_token}
+    return jsonify(ret), 200
+
+
+# If the user_loader_callback returns None, this method will
+# not get hit, even if the access token is valid. You can
+# access the loaded user via the ``current_user``` LocalProxy,
+# or with the ```get_current_user()``` method
+@app.route('/admin-only', methods=['GET'])
+@jwt_required
+def protected():
+    if 'admin' not in current_user.roles:
+        return jsonify({"msg": "Forbidden"}), 403
+    return jsonify({"secret_msg": "don't forget to drink your ovaltine"})
+
+if __name__ == '__main__':
+    app.run()