Update documentation for refreshing tokens and freshness pattern

Author: Landon Gilbert-Bland

docs/blocklist_and_token_revoking.rst

@@ -3,6 +3,9 @@
 Blocklist and Token Revoking
 ============================
 
+NOTE: THIS DOCUMENTATION HAS NOT YET BEEN UPDATED
+
+
 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.
 

docs/changing_default_behavior.rst

@@ -1,6 +1,9 @@
 Changing Default Behaviors
 ==========================
 
+NOTE: THIS DOCUMENTATION HAS NOT YET BEEN UPDATED
+
+
 Changing callback functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/custom_decorators.rst

@@ -1,6 +1,9 @@
 Custom Decorators
 =================
 
+NOTE: THIS DOCUMENTATION HAS NOT YET BEEN UPDATED
+
+
 You can create your own decorators that extend the functionality of the
 decorators provided by this extension. For example, you may want to create
 your own decorator that verifies a JWT is present as well as verifying that

docs/index.rst

@@ -42,8 +42,6 @@ Flask-JWT-Extended's Documentation
    token_locations
    refreshing_tokens
    custom_decorators
-   refresh_tokens
-   token_freshness
    changing_default_behavior
    options
    blocklist_and_token_revoking

docs/options.rst

@@ -3,6 +3,9 @@
 Configuration Options
 =====================
 
+NOTE: THIS DOCUMENTATION HAS NOT YET BEEN UPDATED
+
+
 You can change many options for how this extension works via
 
 .. code-block:: python

docs/refresh_tokens.rst

@@ -3,8 +3,8 @@ Refreshing Tokens
 In most web applications, it would not be ideal if a user was logged out in the
 middle of doing something because their JWT expired. Unfortunately we can't just
 change the expires time on a JWT on each request, as once a JWT is created it
-cannot be modified, only replaced with a new JWT. Lets take a look at how we can
-simulate these behaviors.
+cannot be modified. Lets take a look at some options for solving this problem
+by refreshing JWTs.
 
 Implicit Refreshing With Cookies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -24,6 +24,59 @@ This is our recommended approach when your frontend is a website.
 
 Explicit Refreshing With Refresh Tokens
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-TODO
+Alternatively, this extension comes out of the box with refresh token support.
+A refresh token is a long lived JWT that can only be used to creating new access
+tokens.
+
+You have a couple choices about how to utilize a refresh token. You could store
+the expires time of your access token on your frontend, and each time you make
+an API request first check if the current access token is near or already
+expired, and refresh it as needed. This approach is pretty simple and will work
+fine in most cases, but do be aware that if your frontend has a clock that is
+significantly off, you might run into issues.
+
+An alternative approach involves making an API request with your access token
+and then checking the result to see if it worked. If the result of the request
+is an error message saying that your token is expired, use the refresh token to
+generate a new access token and redo the request with the new token. This approach
+will work regardless of the clock on your frontend, but it does require having
+some potentially more complicated logic.
+
+Using refresh tokens is our recommended approach when your frontend is not a
+website (mobile, api only, etc).
 
 .. literalinclude:: ../examples/refresh_tokens.py
+
+Making a request with a refresh token looks just like making a request with
+an access token. Here is an example using `HTTPie <https://httpie.io/>`_.
+
+.. code-block :: bash
+
+ $ http POST :5000/refresh Authorization:"Bearer $REFRESH_TOKEN"
+
+
+Token Freshness Pattern
+~~~~~~~~~~~~~~~~~~~~~~~
+The token freshness pattern is a very simple idea. Every time a user authenticates
+by providing a username and password, they receive a `fresh` access token that
+can access any route. But after some time, that token should no longer be considered
+`fresh`, and some critical or dangerous routes will be blocked until the user
+verifies their password again. All other routes will still work normally for
+the user even though their token is no longer `fresh`. As an example, we might
+not allow users to change their email address unless they have a `fresh` token,
+but we do allow them use the rest of our Flask application normally.
+
+The token freshness pattern is built into this extension, and works seamlessly
+with both token refreshing strategies discussed above. Lets take a look at this
+with the explicit refresh example (it will look basically same in the implicit
+refresh example).
+
+.. literalinclude:: ../examples/token_freshness.py
+
+We also support marking a token as fresh for a given amount of time after it
+is created. You can do this by passing a `datetime.timedelta` to the `fresh`
+option when creating JWTs:
+
+.. code-block :: python
+
+  create_access_token(identity, fresh=datetime.timedelta(minutes=15))

docs/refreshing_tokens.rst

@@ -102,6 +102,7 @@ out as invalid too. Lets look at how to do that:
   async function makeRequestWithJWT() {
     const options = {
       method: 'post',
+      credentials: 'same-origin',
       headers: {
         'X-CSRF-TOKEN': getCookie('csrf_access_token'),
       },

docs/token_freshness.rst

@@ -1,54 +1,43 @@
+from datetime import timedelta
+
 from flask import Flask
 from flask import jsonify
-from flask import request
 
 from flask_jwt_extended import create_access_token
 from flask_jwt_extended import create_refresh_token
 from flask_jwt_extended import get_jwt_identity
-from flask_jwt_extended import jwt_refresh_token_required
 from flask_jwt_extended import jwt_required
 from flask_jwt_extended import JWTManager
 
 app = Flask(__name__)
 
 app.config["JWT_SECRET_KEY"] = "super-secret"  # Change this!
+app.config["JWT_ACCESS_TOKEN_EXPIRES"] = timedelta(hours=1)
+app.config["JWT_REFRESH_TOKEN_EXPIRES"] = timedelta(days=30)
 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" or 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 token, and use the create_access_token() function again
-# to make a new access token for this identity.
+    access_token = create_access_token(identity="example_user")
+    refresh_token = create_refresh_token(identity="example_user")
+    return jsonify(access_token=access_token, refresh_token=refresh_token)
+
+
+# We are using the `refresh=True` options in jwt_required to only allow
+# refresh tokens to access this route.
 @app.route("/refresh", methods=["POST"])
-@jwt_refresh_token_required
+@jwt_required(refresh=True)
 def refresh():
-    current_user = get_jwt_identity()
-    ret = {"access_token": create_access_token(identity=current_user)}
-    return jsonify(ret), 200
+    identity = get_jwt_identity()
+    access_token = create_access_token(identity=identity)
+    return jsonify(access_token=access_token)
 
 
 @app.route("/protected", methods=["GET"])
-@jwt_required
+@jwt_required()
 def protected():
-    username = get_jwt_identity()
-    return jsonify(logged_in_as=username), 200
+    return jsonify(foo="bar")
 
 
 if __name__ == "__main__":