Documentation around implict token refreshing with cookies

Author: Landon Gilbert-Bland

docs/index.rst

@@ -40,6 +40,7 @@ Flask-JWT-Extended's Documentation
    add_custom_data_claims
    optional_endpoints
    token_locations
+   refreshing_tokens
    custom_decorators
    refresh_tokens
    token_freshness

docs/refreshing_tokens.rst

@@ -0,0 +1,29 @@
+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.
+
+Implicit Refreshing With Cookies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+One huge benefit to storing your JWTs in cookies (when your frontend is a website)
+is that the frontend does not have to handle any logic when it comes to refreshing
+a token. It can all happen implicitly with the cookies your Flask application sets.
+
+The basic idea here is that at the end of every request, we will check if there
+is a JWT that is close to expiring. If we find a JWT that is nearly expired,
+we will replace the current cookie containing the JWT with a new JWT that has a
+longer time until it expires.
+
+This is our recommended approach when your frontend is a website.
+
+.. literalinclude:: ../examples/implicit_refresh.py
+
+
+Explicit Refreshing With Refresh Tokens
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TODO
+
+.. literalinclude:: ../examples/refresh_tokens.py

examples/implicit_refresh.py

@@ -0,0 +1,67 @@
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+
+from flask import Flask
+from flask import jsonify
+
+from flask_jwt_extended import create_access_token
+from flask_jwt_extended import get_jwt
+from flask_jwt_extended import get_jwt_identity
+from flask_jwt_extended import jwt_required
+from flask_jwt_extended import JWTManager
+from flask_jwt_extended import set_access_cookies
+from flask_jwt_extended import unset_jwt_cookies
+
+app = Flask(__name__)
+
+# If true this will only allow the cookies that contain your JWTs to be sent
+# over https. In production, this should always be set to True
+app.config["JWT_COOKIE_SECURE"] = False
+app.config["JWT_TOKEN_LOCATION"] = ["cookies"]
+app.config["JWT_SECRET_KEY"] = "super-secret"  # Change this in your code!
+app.config["JWT_ACCESS_TOKEN_EXPIRES"] = timedelta(hours=1)
+
+jwt = JWTManager(app)
+
+
+# Using an `after_request` callback, we refresh any token that is within 30
+# minutes of expiring. Change the timedeltas to match the needs of your application.
+@app.after_request
+def refresh_expiring_jwts(response):
+    try:
+        exp_timestamp = get_jwt()["exp"]
+        now = datetime.now(timezone.utc)
+        target_timestamp = datetime.timestamp(now + timedelta(minutes=30))
+        if target_timestamp > exp_timestamp:
+            access_token = create_access_token(identity=get_jwt_identity())
+            set_access_cookies(response, access_token)
+        return response
+    except (RuntimeError, KeyError):
+        # Case where there is not a valid JWT. Just return the original respone
+        return response
+
+
+@app.route("/login", methods=["POST"])
+def login():
+    response = jsonify({"msg": "login successful"})
+    access_token = create_access_token(identity="example_user")
+    set_access_cookies(response, access_token)
+    return response
+
+
+@app.route("/logout", methods=["POST"])
+def logout():
+    response = jsonify({"msg": "logout successful"})
+    unset_jwt_cookies(response)
+    return response
+
+
+@app.route("/protected")
+@jwt_required()
+def protected():
+    return jsonify(foo="bar")
+
+
+if __name__ == "__main__":
+    app.run()