Add support for JWT in query string (#117)

Author: Landon Gilbert-Bland

docs/index.rst

@@ -22,4 +22,5 @@ Flask-JWT-Extended's Documentation
    options
    blacklist_and_token_revoking
    tokens_in_cookies
+   tokens_in_query_string
    api

docs/options.rst

@@ -16,7 +16,7 @@ General Options:
 
 ================================= =========================================
 ``JWT_TOKEN_LOCATION``            Where to look for a JWT when processing a request. The
-                                  options are ``'headers'`` or ``'cookies'``. You can pass
+                                  options are ``'headers'``, ``'cookies'``, or ``'query_string'``. You can pass
                                   in a list to check more then one location, such as: ``['headers', 'cookies']``.
                                   Defaults to ``'headers'``
 ``JWT_ACCESS_TOKEN_EXPIRES``      How long an access token should live before it expires. This
@@ -56,6 +56,17 @@ These are only applicable if ``JWT_TOKEN_LOCATION`` is set to use headers.
 ================================= =========================================
 
 
+Query String Options:
+~~~~~~~~~~~~~~~~~~~~~
+These are only applicable if ``JWT_TOKEN_LOCATION`` is set to use query strings.
+
+.. tabularcolumns:: |p{6.5cm}|p{8.5cm}|
+
+================================= =========================================
+``JWT_QUERY_STRING_NAME``         What query paramater name to look for a JWT in a request. Defaults to ``'jwt'``
+================================= =========================================
+
+
 Cookie Options:
 ~~~~~~~~~~~~~~~
 These are only applicable if ``JWT_TOKEN_LOCATION`` is set to use cookies.

docs/tokens_in_query_string.rst

@@ -0,0 +1,15 @@
+JWT in Query String
+===================
+
+You can also pass the token in as a paramater in the query string instead of as
+a header or a cookie (ex: /protected?jwt=<TOKEN>).  However, in almost all
+cases it is recomended that you do not do this, as it comes with some security
+issues. If you perform a GET request with a JWT in the query param, it is
+possible that the browser will save the URL, which could lead to a leaked
+token. It is also very likely that your backend (such as nginx or uwsgi) could
+log the full url paths, which is obviously not ideal from a security standpoint.
+
+If you do decide to use JWTs in query paramaters, here is an example of how
+it might look:
+
+.. literalinclude:: ../examples/jwt_in_query_string.py

examples/jwt_in_query_string.py

@@ -0,0 +1,44 @@
+from flask import Flask, jsonify, request
+
+from flask_jwt_extended import (
+    JWTManager, jwt_required, create_access_token,
+)
+
+# IMPORTANT NOTE:
+# In most cases this is not recommended! It can lead some some
+# security issues, such as:
+#    - The browser saving GET request urls in it's history that
+#      has a JWT in the query string
+#    - The backend server logging JWTs that are in the url
+#
+# If possible, you should use headers instead!
+
+app = Flask(__name__)
+app.config['JWT_TOKEN_LOCATION'] = ['query_string']
+app.config['JWT_SECRET_KEY'] = 'super-secret'  # Change this!
+
+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
+
+    access_token = create_access_token(identity=username)
+    return jsonify(access_token=access_token)
+
+
+# The default query paramater where the JWT is looked for is `jwt`,
+# and can be changed with the JWT_QUERY_STRING_NAME option. Making
+# a request to this endpoint would look like:
+# /protected?jwt=<ACCESS_TOKEN>
+@app.route('/protected', methods=['GET'])
+@jwt_required
+def protected():
+    return jsonify(foo='bar')
+
+if __name__ == '__main__':
+    app.run()

flask_jwt_extended/config.py

@@ -44,10 +44,13 @@ def token_location(self):
         locations = current_app.config['JWT_TOKEN_LOCATION']
         if not isinstance(locations, list):
             locations = [locations]
+        if not locations:
+            raise RuntimeError('JWT_TOKEN_LOCATION must contain at least one '
+                               'of "headers", "cookies", or "query_string"')
         for location in locations:
-            if location not in ('headers', 'cookies'):
+            if location not in ('headers', 'cookies', 'query_string'):
                 raise RuntimeError('JWT_TOKEN_LOCATION can only contain '
-                                   '"headers" and/or "cookies"')
+                                   '"headers", "cookies", or "query_string"')
         return locations
 
     @property
@@ -58,6 +61,10 @@ def jwt_in_cookies(self):
     def jwt_in_headers(self):
         return 'headers' in self.token_location
 
+    @property
+    def jwt_in_query_string(self):
+        return 'query_string' in self.token_location
+
     @property
     def header_name(self):
         name = current_app.config['JWT_HEADER_NAME']
@@ -69,6 +76,10 @@ def header_name(self):
     def header_type(self):
         return current_app.config['JWT_HEADER_TYPE']
 
+    @property
+    def query_string_name(self):
+        return current_app.config['JWT_QUERY_STRING_NAME']
+
     @property
     def access_cookie_name(self):
         return current_app.config['JWT_ACCESS_COOKIE_NAME']

flask_jwt_extended/jwt_manager.py

@@ -138,6 +138,9 @@ def _set_default_configuration_options(app):
         app.config.setdefault('JWT_HEADER_NAME', 'Authorization')
         app.config.setdefault('JWT_HEADER_TYPE', 'Bearer')
 
+        # Options for JWTs then the TOKEN_LOCATION is query_string
+        app.config.setdefault('JWT_QUERY_STRING_NAME', 'jwt')
+
         # Option for JWTs when the TOKEN_LOCATION is cookies
         app.config.setdefault('JWT_ACCESS_COOKIE_NAME', 'access_token_cookie')
         app.config.setdefault('JWT_REFRESH_COOKIE_NAME', 'refresh_token_cookie')

flask_jwt_extended/view_decorators.py

@@ -170,27 +170,52 @@ def _decode_jwt_from_cookies(request_type):
     return decode_token(encoded_token, csrf_value=csrf_value)
 
 
+def _decode_jwt_from_query_string():
+    query_param = config.query_string_name
+    encoded_token = request.args.get(query_param)
+    if not encoded_token:
+        raise NoAuthorizationError('Missing "{}" query paramater'.format(query_param))
+
+    return decode_token(encoded_token)
+
+
 def _decode_jwt_from_request(request_type):
-    # We have three cases here, having jwts in both cookies and headers is
-    # valid, or the jwt can only be saved in one of cookies or headers. Check
-    # all cases here.
-    if config.jwt_in_cookies and config.jwt_in_headers:
+    # All the places we can get a JWT from in this request
+    decode_functions = []
+    if config.jwt_in_cookies:
+        decode_functions.append(lambda: _decode_jwt_from_cookies(request_type))
+    if config.jwt_in_query_string:
+        decode_functions.append(_decode_jwt_from_query_string)
+    if config.jwt_in_headers:
+        decode_functions.append(_decode_jwt_from_headers)
+
+    # Try to find the token from one of these locations. It only needs to exist
+    # in one place to be valid (not every location).
+    errors = []
+    decoded_token = None
+    for decode_function in decode_functions:
         try:
-            decoded_token = _decode_jwt_from_cookies(request_type)
-        except NoAuthorizationError:
-            try:
-                decoded_token = _decode_jwt_from_headers()
-            except NoAuthorizationError:
-                raise NoAuthorizationError("Missing JWT in headers and cookies")
-    elif config.jwt_in_headers:
-        decoded_token = _decode_jwt_from_headers()
-    else:
-        decoded_token = _decode_jwt_from_cookies(request_type)
+            decoded_token = decode_function()
+            break
+        except NoAuthorizationError as e:
+            errors.append(str(e))
+
+    # Do some work to make a helpful and human readable error message if no
+    # token was found in any of the expected locations.
+    if not decoded_token:
+        token_locations = config.token_location
+        multiple_jwt_locations = len(token_locations) != 1
+
+        if multiple_jwt_locations:
+            err_msg = "Missing JWT in {start_locs} or {end_locs} ({details})".format(
+                start_locs=", ".join(token_locations[:-1]),
+                end_locs=token_locations[-1],
+                details= "; ".join(errors)
+            )
+            raise NoAuthorizationError(err_msg)
+        else:
+            raise NoAuthorizationError(errors[0])
 
-    # Make sure the type of token we received matches the request type we expect
     verify_token_type(decoded_token, expected_type=request_type)
-
-    # If blacklisting is enabled, see if this token has been revoked
     verify_token_not_blacklisted(decoded_token, request_type)
-
     return decoded_token

tests/test_config.py

@@ -19,11 +19,15 @@ def app():
 def test_default_configs(app):
     with app.test_request_context():
         assert config.token_location == ['headers']
+        assert config.jwt_in_query_string is False
         assert config.jwt_in_cookies is False
         assert config.jwt_in_headers is True
+
         assert config.header_name == 'Authorization'
         assert config.header_type == 'Bearer'
 
+        assert config.query_string_name == 'jwt'
+
         assert config.access_cookie_name == 'access_token_cookie'
         assert config.refresh_cookie_name == 'refresh_token_cookie'
         assert config.access_cookie_path == '/'
@@ -61,10 +65,12 @@ def test_default_configs(app):
 
 
 def test_override_configs(app):
-    app.config['JWT_TOKEN_LOCATION'] = ['cookies']
+    app.config['JWT_TOKEN_LOCATION'] = ['cookies', 'query_string']
     app.config['JWT_HEADER_NAME'] = 'TestHeader'
     app.config['JWT_HEADER_TYPE'] = 'TestType'
 
+    app.config['JWT_QUERY_STRING_NAME'] = 'banana'
+
     app.config['JWT_ACCESS_COOKIE_NAME'] = 'new_access_cookie'
     app.config['JWT_REFRESH_COOKIE_NAME'] = 'new_refresh_cookie'
     app.config['JWT_ACCESS_COOKIE_PATH'] = '/access/path'
@@ -100,12 +106,15 @@ class CustomJSONEncoder(JSONEncoder):
     app.json_encoder = CustomJSONEncoder
 
     with app.test_request_context():
-        assert config.token_location == ['cookies']
+        assert config.token_location == ['cookies', 'query_string']
+        assert config.jwt_in_query_string is True
         assert config.jwt_in_cookies is True
         assert config.jwt_in_headers is False
         assert config.header_name == 'TestHeader'
         assert config.header_type == 'TestType'
 
+        assert config.query_string_name == 'banana'
+
         assert config.access_cookie_name == 'new_access_cookie'
         assert config.refresh_cookie_name == 'new_refresh_cookie'
         assert config.access_cookie_path == '/access/path'
@@ -208,6 +217,10 @@ def test_default_with_asymmetric_secret_key(app):
 # noinspection PyStatementEffect
 def test_invalid_config_options(app):
     with app.test_request_context():
+        app.config['JWT_TOKEN_LOCATION'] = []
+        with pytest.raises(RuntimeError):
+            config.token_location
+
         app.config['JWT_TOKEN_LOCATION'] = 'banana'
         with pytest.raises(RuntimeError):
             config.token_location