Initial updates to jwt revoking documentation.

Author: Landon Gilbert-Bland

docs/blocklist_and_token_revoking.rst

@@ -1,47 +1,31 @@
 .. _Blocklist and Token Revoking:
 
-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.
-
-You will have to choose what tokens you want to check against the blocklist. In
-most cases, you will probably want to check both refresh and access tokens, which
-is the default behavior. However, if the extra overhead of checking tokens is a
-concern you could instead only check the refresh tokens, and set the access
-tokens to have a short expires time so any damage a compromised token could
-cause is minimal.
-
-Blocklisting works by is providing a callback function to this extension, using the
+JWT Revoking / Blocklist
+========================
+JWT revoking is a mechanism for preventing an otherwise valid JWT from accessing your
+routes while still letting other valid JWTs in. To utilize JWT revoking in this
+extension, you must defining a callback function via the
 :meth:`~flask_jwt_extended.JWTManager.token_in_blocklist_loader` decorator.
-This method will be called whenever the specified tokens (`access` and/or `refresh`)
-are used to access a protected endpoint. If the callback function says that the
-token is revoked, we will not allow the call to continue, otherwise we will
-allow the call to access the endpoint as normal.
-
+This function is called whenever a valid JWT is used to access a protected route.
+The callback will receive the JWT header and JWT payload as arguments, and must
+return `True` if the JWT has been revoked.
 
 Here is a basic example of this in action.
 
-
 .. literalinclude:: ../examples/blocklist.py
 
-In production, you will likely want to use either a database or in memory store
-(such as redis) to store your tokens. In memory stores are great if you are wanting
-to revoke a token when the users logs out, as they are blazing fast. A downside
-to using redis is that in the case of a power outage or other such event, it's
-possible that you might 'forget' that some tokens have been revoked, depending
-on if the redis data was synced to disk.
+In production, you will want to use some form of persistent storage (database,
+redis, etc) to store your JWTs. It would be bad if your application forgot that
+a JWT was revoked if it was restarted.
 
-In contrast to that, databases are great if the data persistance is of the highest
-importance (for example, if you have very long lived tokens that other developers
-use to access your api), or if you want to add some addition features like showing
-users all of their active tokens, and letting them revoke and unrevoke those tokens.
+If your only requirements are to check if a JWT has been previously revoked,
+our recommendation is to use redis, as it is blazing fast. If you need to keep
+track of information about revoked JWTs (when it was revoked, who revoked it,
+can it be un-revoked, etc), our general recommendation is to utilize your database.
+Ultimately though choice of what persistent storage engine to use will depend on
+your specific application and tech stack.
 
-For more in depth examples of these, check out:
+For more production like examples of toking revoking, check out:
 
-- https://github.com/vimalloc/flask-jwt-extended/blob/master/examples/redis_blocklist.py
-- https://github.com/vimalloc/flask-jwt-extended/tree/master/examples/database_blocklist
+- `Redis Example <https://github.com/vimalloc/flask-jwt-extended/blob/master/examples/redis_blocklist.py>`_
+- `Database Example <https://github.com/vimalloc/flask-jwt-extended/tree/master/examples/database_blocklist>`_

docs/index.rst

@@ -41,8 +41,8 @@ Flask-JWT-Extended's Documentation
    optional_endpoints
    token_locations
    refreshing_tokens
+   blocklist_and_token_revoking
    custom_decorators
    changing_default_behavior
    options
-   blocklist_and_token_revoking
    api

examples/blocklist.py

@@ -1,100 +1,46 @@
 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
-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
 
+# In production make sure to use persistent storage, such as a database or redis
+blocklist = set()
 
-# Setup flask
 app = Flask(__name__)
-
-# Enable blocklisting and specify what kind of tokens to check
-# against the blocklist
 app.config["JWT_SECRET_KEY"] = "super-secret"  # Change this!
 jwt = JWTManager(app)
 
-# A storage engine to save revoked tokens. In production if
-# speed is the primary concern, redis is a good bet. If data
-# persistence is more important for you, postgres is another
-# great option. In this example, we will be using an in memory
-# store, just to show you how this might work. For more
-# complete examples, check out these:
-# https://github.com/vimalloc/flask-jwt-extended/blob/master/examples/redis_blocklist.py
-# https://github.com/vimalloc/flask-jwt-extended/tree/master/examples/database_blocklist
-blocklist = set()
-
 
-# For this example, we are just checking if the tokens jti
-# (unique identifier) is in the blocklist set. This could
-# be made more complex, for example storing all tokens
-# into the blocklist with a revoked status when created,
-# and returning the revoked status in this call. This
-# would allow you to have a list of all created tokens,
-# and to consider tokens that aren't in the blocklist
-# (aka tokens you didn't create) as revoked. These are
-# just two options, and this can be tailored to whatever
-# your application needs.
+# The `jti` claim in the jwt_payload is a unique identifier (string) for the JWT.
 @jwt.token_in_blocklist_loader
-def check_if_token_in_blocklist(decrypted_token):
-    jti = decrypted_token["jti"]
+def check_if_token_in_blocklist(jwt_header, jwt_payload):
+    jti = jwt_payload["jti"]
     return jti in blocklist
 
 
-# Standard login endpoint
 @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
-
-    ret = {
-        "access_token": create_access_token(identity=username),
-        "refresh_token": create_refresh_token(identity=username),
-    }
-    return jsonify(ret), 200
-
+    access_token = create_access_token(identity="example_user")
+    return jsonify(access_token=access_token)
 
-# Standard refresh endpoint. A blocklisted refresh token
-# will not be able to access this endpoint
-@app.route("/refresh", methods=["POST"])
-@jwt_refresh_token_required
-def refresh():
-    current_user = get_jwt_identity()
-    ret = {"access_token": create_access_token(identity=current_user)}
-    return jsonify(ret), 200
 
-
-# Endpoint for revoking the current users access token
+# On logout, add the token to our blocklist.
 @app.route("/logout", methods=["DELETE"])
-@jwt_required
+@jwt_required()
 def logout():
     jti = get_jwt()["jti"]
     blocklist.add(jti)
-    return jsonify({"msg": "Successfully logged out"}), 200
-
-
-# Endpoint for revoking the current users refresh token
-@app.route("/logout2", methods=["DELETE"])
-@jwt_refresh_token_required
-def logout2():
-    jti = get_jwt()["jti"]
-    blocklist.add(jti)
-    return jsonify({"msg": "Successfully logged out"}), 200
+    return jsonify(msg="Successfully logged out")
 
 
-# This will now prevent users with blocklisted tokens from
-# accessing this endpoint
+# A revoked token will not be able to access this route.
 @app.route("/protected", methods=["GET"])
-@jwt_required
+@jwt_required()
 def protected():
-    return jsonify({"hello": "world"})
+    return jsonify(hello="world")
 
 
 if __name__ == "__main__":

tests/test_headers.py

@@ -23,7 +23,6 @@ def access_protected():
 
 
 def test_default_headers(app):
-    app.config
     test_client = app.test_client()
 
     with app.test_request_context():