Blacklist/revoke tokens example

Author: vimalloc

README.md

@@ -340,7 +340,127 @@ will only check refresh tokens, and 'all' which will check refresh and access to
 to 'refresh'
 
 ### Blacklist and Token Revoking
-TODO
+This supports blacklisting and token revoking out of the box. This will allow you
+to revoke a specific token so a user can no longer access your endpoints, without
+having to change your secret key and thus revoke all the users tokens. In order
+to revoke a token, we need some storage where we can save a list of all the tokens
+we have created, as well as if they have been blacklisted or not. In order to make
+the underlying storage as agnostic as possible, we use [simplekv] (http://pythonhosted.org/simplekv/)
+to provide assess to a variaty of backends.
+
+In production, it is important to use a backend that can have some sort of
+persistent storage, so we don't forget that we revoked a token, as well as
+something that can be safely used by the multiple thread and processes running
+your application. At present we believe redis is a good fit for this (it has the
+added benefit of removing expired tokens from the store automatically, so it
+wont blow up into something huge). But the choice is of course yours.
+
+We also have to make a choice of if we want to check the blacklist against all
+requests, or only against refresh token requests. There are pros and cons to either
+way (extra overhead on jwt_required endpoints vs someone being able to use an
+access token freely until it expires). In this example, we are going to only check
+refresh tokens, and set the access tokes to a small expires time to help minimize
+damange that could be done.
+```python
+from datetime import timedelta
+
+import simplekv
+import simplekv.memory
+from flask import Flask, request, jsonify
+
+from flask_jwt_extended import JWTManager, jwt_required, \
+    get_jwt_identity, revoke_token, unrevoke_token, \
+    get_stored_tokens, get_all_stored_tokens, create_access_token, \
+    create_refresh_token, jwt_refresh_token_required
+
+# Setup flask
+app = Flask(__name__)
+app.secret_key = 'super-secret'
+
+# Configure access token expires time
+app.config['JWT_ACCESS_TOKEN_EXPIRES'] = timedelta(minutes=5)
+
+# Enable and configure the JWT blacklist / token revoke. We are using an in
+# memory store for this example. In production, you should use something
+# else (csuch as redis, memcached, sqlalchemy). See here for options:
+# http://pythonhosted.org/simplekv/
+app.config['JWT_BLACKLIST_ENABLED'] = True
+app.config['JWT_BLACKLIST_STORE'] = simplekv.memory.DictStore()
+app.config['JWT_BLACKLIST_TOKEN_CHECKS'] = 'refresh'
+
+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' and 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
+
+
+@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 listing tokens that have the same identity as you
+@app.route('/auth/tokens', methods=['GET'])
+@jwt_required
+def list_identity_tokens():
+    username = get_jwt_identity()
+    return jsonify(get_stored_tokens(username)), 200
+
+
+# Endpoint for listing all tokens. In your app, you should either not expose
+# this, or put some addition security on top of it so only trusted users,
+# (administrators, etc) can access it
+@app.route('/auth/all-tokens')
+def list_all_tokens():
+    return jsonify(get_all_stored_tokens()), 200
+
+
+# Endpoint for revoking a token
+@app.route('/auth/tokens/revoke/<string:jti>', methods=['PUT'])
+@jwt_required
+def change_jwt_revoke_state(jti):
+    try:
+        revoke_token(jti)
+        return jsonify({"msg": "Token successfully revoked"}), 200
+    except KeyError:
+        return jsonify({'msg': 'Token not foun'}), 404
+
+
+# Endpoint for un-revoking a token
+@app.route('/auth/tokens/unrevoke/<string:jti>', methods=['PUT'])
+@jwt_required
+def change_jwt_revoke_state(jti):
+    try:
+        unrevoke_token(jti)
+        return jsonify({"msg": "Token successfully unrevoked"}), 200
+    except KeyError:
+        return jsonify({'msg': 'Token not foun'}), 404
+
+
+@app.route('/protected', methods=['GET'])
+@jwt_required
+def protected():
+    return jsonify({'hello': 'world'})
+
+if __name__ == '__main__':
+    app.run()
+```
 
 
 # Testing and Code Coverage
@@ -350,4 +470,4 @@ tox
 ```
 
 # Documentation
-Readthedocs coming soon!
+Readthedocs coming soon(tm)!

examples/blacklist.py

@@ -0,0 +1,98 @@
+from datetime import timedelta
+
+import simplekv
+import simplekv.memory
+from flask import Flask, request, jsonify
+
+from flask_jwt_extended import JWTManager, jwt_required, \
+    get_jwt_identity, revoke_token, unrevoke_token, \
+    get_stored_tokens, get_all_stored_tokens, create_access_token, \
+    create_refresh_token, jwt_refresh_token_required
+
+# Setup flask
+app = Flask(__name__)
+app.secret_key = 'super-secret'
+
+# Configure access token expires time
+app.config['JWT_ACCESS_TOKEN_EXPIRES'] = timedelta(minutes=5)
+
+# Enable and configure the JWT blacklist / token revoke. We are using an in
+# memory store for this example. In production, you should use something
+# else (csuch as redis, memcached, sqlalchemy). See here for options:
+# http://pythonhosted.org/simplekv/
+app.config['JWT_BLACKLIST_ENABLED'] = True
+app.config['JWT_BLACKLIST_STORE'] = simplekv.memory.DictStore()
+app.config['JWT_BLACKLIST_TOKEN_CHECKS'] = 'refresh'
+
+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' and 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
+
+
+@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 listing tokens that have the same identity as you
+@app.route('/auth/tokens', methods=['GET'])
+@jwt_required
+def list_identity_tokens():
+    username = get_jwt_identity()
+    return jsonify(get_stored_tokens(username)), 200
+
+
+# Endpoint for listing all tokens. In your app, you should either not expose
+# this, or put some addition security on top of it so only trusted users,
+# (administrators, etc) can access it
+@app.route('/auth/all-tokens')
+def list_all_tokens():
+    return jsonify(get_all_stored_tokens()), 200
+
+
+# Endpoint for revoking a token
+@app.route('/auth/tokens/revoke/<string:jti>', methods=['PUT'])
+@jwt_required
+def change_jwt_revoke_state(jti):
+    try:
+        revoke_token(jti)
+        return jsonify({"msg": "Token successfully revoked"}), 200
+    except KeyError:
+        return jsonify({'msg': 'Token not foun'}), 404
+
+
+# Endpoint for un-revoking a token
+@app.route('/auth/tokens/unrevoke/<string:jti>', methods=['PUT'])
+@jwt_required
+def change_jwt_revoke_state(jti):
+    try:
+        unrevoke_token(jti)
+        return jsonify({"msg": "Token successfully unrevoked"}), 200
+    except KeyError:
+        return jsonify({'msg': 'Token not foun'}), 404
+
+
+@app.route('/protected', methods=['GET'])
+@jwt_required
+def protected():
+    return jsonify({'hello': 'world'})
+
+if __name__ == '__main__':
+    app.run()