Easier way (hopefully) for users to handle jwt in cookie and csrf protection

Refs #5

Author: vimalloc

examples/token_in_cookie.py

@@ -1,24 +1,33 @@
-import binascii
-import json
-import os
-
 from flask import Flask, jsonify, request
-from flask import Response
 
 from flask_jwt_extended import JWTManager, jwt_required, create_access_token, \
-    jwt_refresh_token_required, create_refresh_token, get_jwt_identity
+    jwt_refresh_token_required, create_refresh_token, get_jwt_identity,\
+    set_access_cookies, set_refresh_cookie
+
+
+# NOTE: This is being actively worked on, and is not complete yet. At present,
+#       this code will not work! It should be rolled out next week sometime
+
 
 app = Flask(__name__)
 app.secret_key = 'super-secret'  # Change this!
 jwt = JWTManager(app)
 
 
-# TODO add additional_claims as optional arg to create_token methods
-# TODO config option to check for tokens in cookie instead of request headers (or both)
-# TODO config option to do xsrf double submit verification on protected endpoints
+# Configure application to store jwts in cookies with double submit csrf protection
+app.config['JWT_TOKEN_LOCATION'] = 'cookie'
+app.config['JWT_COOKIE_HTTPONLY'] = True
+app.config['JWT_COOKIE_SECURE'] = True
 
-def _create_xsrf_token():
-    return binascii.hexlify(os.urandom(60))
+app.config['JWT_ACCESS_COOKIE_NAME'] = 'access_token_cookie'
+app.config['JWT_ACCESS_COOKIE_PATH'] = '/api/'
+
+app.config['JWT_REFRESH_COOKIE_NAME'] = 'refresh_token_cookie'
+app.config['JWT_REFRESH_COOKIE_PATH'] = '/token/refresh'
+
+app.config['JWT_COOKIE_CSRF_PROTECT'] = True
+app.config['JWT_ACCESS_CSRF_COOKIE_NAME'] = 'x_xsrf_access_token'
+app.config['JWT_REFRESH_CSRF_COOKIE_NAME'] = 'x_xsrf_refresh_token'
 
 
 @app.route('/token/auth', methods=['POST'])
@@ -28,95 +37,27 @@ def login():
     if username != 'test' and password != 'test':
         return jsonify({"msg": "Bad username or password"}), 401
 
-    # Create the x-xsrf-token we will use for CSRF double submit verification
-    x_xsrf_access_token = _create_xsrf_token()
-    x_xsrf_refresh_token = _create_xsrf_token()
-    access_claims = {'X-XSRF-TOKEN': x_xsrf_access_token}
-    refresh_claims = {'X-XSRF-TOKEN': x_xsrf_refresh_token}
-
-    # Create the access and refresh tokens with the x-xsrf-token included
-    access_token = create_access_token(identity=username,
-                                       additional_claims=access_claims)
-    refresh_token = create_refresh_token(identity=username,
-                                         additional_claims=refresh_claims)
-
-    # Create the response we will send back to the caller.
-    data = json.dumps({'login': True})
-    resp = Response(response=data, status=200, mimetype="application/json")
-
-    # Save the access and refresh tokens in a cookie with this request.
-    # The secure option insures that the cookie is only sent over https,
-    # httponly makes it so javascript cannot access this cookie, and prevents
-    # XSS attacks (we are still vulnerable to CSRF though), and path says to
-    # only send this cookie if it matches the path. Using the path, we can have
-    # access tokens only sent when we go to protected endpoints, and refresh
-    # tokens only sent when we go to the refresh endpoint
-    resp.set_cookie('access_token',
-                    value=access_token,
-                    secure=True,
-                    httponly=True,
-                    path='/api/')
-    resp.set_cookie('refresh_token',
-                    value=refresh_token,
-                    secure=True,
-                    httponly=True,
-                    path='/token/refresh')
-
-    # Set the X-XSRF-TOKEN in a not httponly token (which can be accessed by
-    # javascript, but only by javascript running on this domain). From here on
-    # out, we will need to set the X-XSRF-TOKEN header for each request, getting
-    # the xsrf token from this cookie. On the backend, we will be verifying the
-    # xsrf token in the header matches the xsrf token in the JWT. The end result
-    # of this is that attackers will not be able to perform CSRF attacks, as they
-    # could send the JWT back with the request, but without the additional xsrf
-    # header they will not get accepted, and they cannot access the xsrf token
-    # as this cookie can only be accessed by javascript running from the same
-    # domain (and the JWT is httponly and cannot be accessed by any javascript).
-    # Additionally, the users access and refresh token can not be stolen via
-    # XSS (again, because they are httponly), but XSS attacks could still be
-    # used to perform actions for a user without stealing their cookie.
-    resp.set_cookie('x_xsrf_access_token',
-                    value=x_xsrf_access_token,
-                    secure=True,
-                    httponly=False,
-                    path='/api/')
-    resp.set_cookie('x_xsrf_refresh_token',
-                    value=x_xsrf_refresh_token,
-                    secure=True,
-                    httponly=False,
-                    path='/token/refresh')
+    # Create the tokens we will be sending back to the user
+    access_token = create_access_token(identity=username)
+    refresh_token = create_refresh_token(identity=username)
 
+    # Set the JWTs and the CSRF double submit protection cookies in this response
+    resp = jsonify({'login': True}), 200
+    set_access_cookies(resp, access_token)
+    set_refresh_cookie(resp, refresh_token)
     return resp
 
 
 @app.route('/token/refresh', methods=['POST'])
 @jwt_refresh_token_required
 def refresh():
-    # New xsrf token to use with the new jwt
-    x_xsrf_token = _create_xsrf_token()
-
-    # Create the new jwt
-    claims = {'X-XSRF-TOKEN': x_xsrf_token}
+    # Create the new access token
     current_user = get_jwt_identity()
-    access_token = create_access_token(identity=current_user, additional_claims=claims)
-
-    # Create the respons to send back to the caller
-    data = json.dumps({'refresh': True})
-    resp = Response(response=data, status=200, mimetype="application/json")
-
-    # Set the JWT and XSRF TOKEN in the cookie with the same options and
-    # security that we used for the original access token
-    resp.set_cookie('access_token',
-                    value=access_token,
-                    secure=True,
-                    httponly=True,
-                    path='/api/')
-    resp.set_cookie('x_xsrf_access_token',
-                    value=x_xsrf_token,
-                    secure=True,
-                    httponly=False,
-                    path='/api/')
+    access_token = create_access_token(identity=current_user)
 
+    # Set the access JWT and CSRF double submit protection cookies in this response
+    resp = jsonify({'refresh': True}), 200
+    set_access_cookies(resp, access_token)
     return resp
 
 

flask_jwt_extended/__init__.py

@@ -1,6 +1,6 @@
 from .jwt_manager import JWTManager
 from .utils import (jwt_required, fresh_jwt_required, jwt_refresh_token_required,
                     create_refresh_token, create_access_token, get_jwt_identity,
-                    get_jwt_claims)
+                    get_jwt_claims, set_access_cookies, set_refresh_cookie)
 from .blacklist import (revoke_token, unrevoke_token, get_stored_tokens,
                         get_all_stored_tokens, get_stored_token)

flask_jwt_extended/config.py

@@ -10,19 +10,31 @@
 # See: http://pythonhosted.org/simplekv/index.html#simplekv.TimeToLiveMixin
 
 
-# Where to look for the JWT. Available options are cookie and header
-REQUEST_JWT_LOCATION = 'header'
+# TODO support for cookies and headers at the same time. This could be useful
+#      for using cookies in a web browser (more secure), and headers in a mobile
+#      app (don't have to worry about csrf/xss there, and headers are easier to
+#      manage in that environment)
 
-# Options for where to get the JWT if using a header approach
+# Where to look for the JWT. Available options are cookie, header, and either
+TOKEN_LOCATION = 'headers'
+
+# Options for JWTs when the TOKEN_LOCATION is headers
 HEADER_NAME = 'Authorization'
 HEADER_TYPE = 'Bearer'
 
-# Options for where to get and handling JWTs if using a cookie approach
-COOKIE_ACCESS_TOKEN_NAME = 'access_token'
-COOKIE_REFRESH_TOKEN_NAME = 'refresh_token'
-COOKIE_CSRF_DOUBLE_SUBMIT = False
-COOKIE_XSRF_ACCESS_NAME = 'xsrf_access_token'
-COOKIE_XSRF_REFRESH_NAME = 'xsrf_refresh_token'
+# Option for JWTs when the TOKEN_LOCATION is cookies
+COOKIE_SECURE = False
+ACCESS_COOKIE_NAME = 'access_token_cookie'
+REFRESH_COOKIE_NAME = 'refresh_token_cookie'
+ACCESS_COOKIE_PATH = None
+REFRESH_COOKIE_PATH = None
+
+# Options for using double submit for verifying CSRF tokens
+COOKIE_CSRF_PROTECT = True
+ACCESS_CSRF_COOKIE_NAME = 'csrf_access_token'
+REFRESH_CSRF_COOKIE_NAME = 'csrf_refresh_token'
+ACCESS_CSRF_HEADER_NAME = 'X-CSRF-ACCESS-TOKEN'
+REFRESH_CSRF_HEADER_NAME = 'X-CSRF-REFRESH-TOKEN'
 
 # How long an a token will live before they expire.
 ACCESS_TOKEN_EXPIRES = datetime.timedelta(minutes=15)
@@ -35,17 +47,64 @@
 
 # Options for blacklisting/revoking tokens
 BLACKLIST_ENABLED = False
-BLACKLIST_STORE = None
+BLACKLIST_STORE = None  # simplekv object: https://pypi.python.org/pypi/simplekv/
 BLACKLIST_TOKEN_CHECKS = 'refresh'  # valid options are 'all', and 'refresh'
 
 
+def get_token_location():
+    location = current_app.config.get('JWT_TOKEN_LOCATION', TOKEN_LOCATION)
+    if location not in ['headers', 'cookies']:
+        raise RuntimeError('JWT_LOCATION_LOCATION must be "headers" or "cookies"')
+    return location
+
+
 def get_jwt_header_name():
     name = current_app.config.get('JWT_HEADER_NAME', HEADER_NAME)
     if not name:
         raise RuntimeError("JWT_HEADER_NAME must be set")
     return name
 
 
+def get_cookie_secure():
+    return current_app.config.get('JWT_COOKIE_SECURE', COOKIE_SECURE)
+
+
+def get_access_cookie_name():
+    return current_app.config.get('JWT_ACCESS_COOKIE_NAME', ACCESS_COOKIE_NAME)
+
+
+def get_refresh_cookie_name():
+    return current_app.config.get('JWT_REFRESH_COOKIE_NAME', REFRESH_COOKIE_NAME)
+
+
+def get_access_cookie_path():
+    return current_app.config.get('JWT_ACCESS_COOKIE_PATH', ACCESS_COOKIE_PATH)
+
+
+def get_refresh_cookie_path():
+    return current_app.config.get('JWT_REFRESH_COOKIE_PATH', REFRESH_COOKIE_PATH)
+
+
+def get_cookie_csrf_protect():
+    return current_app.config.get('JWT_COOKIE_CSRF_PROTECT', COOKIE_CSRF_PROTECT)
+
+
+def get_access_csrf_cookie_name():
+    return current_app.config.get('JWT_ACCESS_CSRF_COOKIE_NAME', ACCESS_CSRF_COOKIE_NAME)
+
+
+def get_refresh_csrf_cookie_name():
+    return current_app.config.get('JWT_REFRESH_CSRF_COOKIE_NAME', REFRESH_CSRF_COOKIE_NAME)
+
+
+def get_access_csrf_header_name():
+    return current_app.config.get('JWT_ACCESS_CSRF_HEADER_NAME', ACCESS_CSRF_HEADER_NAME)
+
+
+def get_refresh_csrf_header_name():
+    return current_app.config.get('JWT_REFRESH_CSRF_HEADER_NAME', REFRESH_CSRF_HEADER_NAME)
+
+
 def get_jwt_header_type():
     return current_app.config.get('JWT_HEADER_TYPE', HEADER_TYPE)
 

flask_jwt_extended/utils.py

@@ -1,20 +1,24 @@
 import datetime
 import json
+import os
 import uuid
-
 from functools import wraps
 
+import binascii
 import jwt
 import six
-from werkzeug.local import LocalProxy
-from flask import request, jsonify, current_app
+from flask import request, current_app
 try:
     from flask import _app_ctx_stack as ctx_stack
 except ImportError:  # pragma: no cover
     from flask import _request_ctx_stack as ctx_stack
 
 from flask_jwt_extended.config import get_access_expires, get_refresh_expires, \
-    get_algorithm, get_blacklist_enabled, get_blacklist_checks, get_jwt_header_type
+    get_algorithm, get_blacklist_enabled, get_blacklist_checks, get_jwt_header_type, \
+    get_access_cookie_name, get_cookie_secure, get_access_cookie_path, \
+    get_cookie_csrf_protect, get_access_csrf_cookie_name, \
+    get_refresh_cookie_name, get_refresh_cookie_path, \
+    get_refresh_csrf_cookie_name
 from flask_jwt_extended.exceptions import JWTEncodeError, JWTDecodeError, \
     InvalidHeaderError, NoAuthHeaderError, WrongTokenError, RevokedTokenError, \
     FreshTokenRequired
@@ -37,6 +41,11 @@ def get_jwt_claims():
     return getattr(ctx_stack.top, 'jwt_user_claims', {})
 
 
+# TODO set csrf token in jwt when creating tokens (if enabled)
+def _create_xsrf_token():
+    return binascii.hexlify(os.urandom(60))
+
+
 def _encode_access_token(identity, secret, algorithm, token_expire_delta,
                          fresh, user_claims):
     """
@@ -303,6 +312,7 @@ def create_access_token(identity, fresh=True):
     access_expire_delta = get_access_expires()
     algorithm = get_algorithm()
     user_claims = current_app.jwt_manager.user_claims_callback(identity)
+
     access_token = _encode_access_token(identity, secret, algorithm, access_expire_delta,
                                         fresh=fresh, user_claims=user_claims)
     return access_token
@@ -313,3 +323,56 @@ def _get_secret_key():
     if not key:
         raise RuntimeError('flask SECRET_KEY must be set')
     return key
+
+
+def _get_csrf_token(encoded_token):
+    secret = _get_secret_key()
+    algorithm = get_algorithm()
+    token = _decode_jwt(encoded_token, secret, algorithm)
+    try:
+        return token['csrf']
+    except KeyError:
+        raise RuntimeError('JWT does not have csrf token set. Is '
+                           'JWT_COOKIE_CSRF_PROTECT set to True?')
+
+
+def set_access_cookies(response, encoded_access_token):
+    """
+    Takes a flask response object, and configures it to set the encoded access
+    token in a cookie (as well as a csrf access cookie if enabled)
+    """
+    # Set the access JWT in the cookie
+    response.set_cookie(get_access_cookie_name(),
+                        value=encoded_access_token,
+                        secure=get_cookie_secure(),
+                        httponly=True,
+                        path=get_access_cookie_path())
+
+    # If enabled, set the csrf double submit access cookie
+    if get_cookie_csrf_protect():
+        response.set_cookie(get_access_csrf_cookie_name(),
+                            value=_get_csrf_token(encoded_access_token),
+                            secure=get_cookie_secure(),
+                            httponly=False,
+                            path=get_access_cookie_path())
+
+
+def set_refresh_cookie(response, encoded_refresh_token):
+    """
+    Takes a flask response object, and configures it to set the encoded refresh
+    token in a cookie (as well as a csrf refresh cookie if enabled)
+    """
+    # Set the refresh JWT in the cookie
+    response.set_cookie(get_refresh_cookie_name(),
+                        value=encoded_refresh_token,
+                        secure=get_cookie_secure(),
+                        httponly=True,
+                        path=get_refresh_cookie_path())
+
+    # If enabled, set the csrf double submit refresh cookie
+    if get_cookie_csrf_protect():
+        response.set_cookie(get_refresh_csrf_cookie_name(),
+                            value=_get_csrf_token(encoded_refresh_token),
+                            secure=get_cookie_secure(),
+                            httponly=False,
+                            path=get_refresh_cookie_path())