flask-praetorian Documentation

Transcription

1 flask-praetorian Documentation Release Tucker Beck Jun 21, 2018

2

3 Contents: 1 Table of Contents Quickstart Notes Tutorial flask-praetorian Developer Guide flask_praetorian package Python Module Index 35 i

4 ii

5 Strong, Simple, and Precise security for Flask APIs API security should be strong, simple, and precise like a Roman Legionary. This package aims to provide that. Using JWT tokens as implemented by PyJWT, flask-praetorian uses a very simple interface to make sure that the users accessing your API s endpoints are provisioned with the correct roles for access. This project was heavily influenced by Flask-Security, but intends to supply only essential functionality. Instead of trying to anticipate the needs of all users, flask-praetorian will provide a simple and secure mechanism to provide security for APIs specifically. The flask-praetorian package can be used to: Encrypt (hash) passwords for storing in your database Verify plaintext passwords against the encrypted, stored versions Generate authorization tokens upon verification of passwords Check requests to secured endpoints for authorized tokens Ensure that the users associated with tokens have necessary roles for access Parse user information from request headers for use in client route handlers All of this is provided in a very simple to configure and initialize flask extension. Though simple, the security provided by flask-praetorian is strong due to the usage of the proven security technology of JWT and python s PassLib package. The flask-praetorian source code is hosted on github. If you find issues that you wish to report or want to add features via a pull-request, please do so there. Pull-requests welcome! Contents: 1

6 2 Contents:

7 CHAPTER 1 Table of Contents 1.1 Quickstart Requirements Python 3.4, 3.5, 3.6, or 3.7 Note on Requirements I do not currently plan to support older versions of python. Python 2 support is very unlikely to arrive as the original author is a die-hard believer in python 3. As for older versions of python 3, my test harnesses depend on some features only available in python 3.4 and up Installation Note: flask-praetorian does not support distutils or setuptools because the author has very strong feelings about python packaging and the role pip plays in taking us into a bright new future of standardized and usable python packaging Install from pypi This will install the latest release of flask-praetorian from pypi via pip: $ pip install flask-praetorian 3

8 Install latest version from github If you would like a version other than the latest published on pypi, you may do so by cloning the git repository: $ git clone Next, checkout the branch or tag that you wish to use: $ cd flask-praetorian $ git checkout integration Finally, use pip to install from the local directory: $ pip install Example A minimal example of how to use the flask-praetorian decorators is included: import flask import tempfile import flask_sqlalchemy import flask_praetorian import flask_cors db = flask_sqlalchemy.sqlalchemy() guard = flask_praetorian.praetorian() cors = flask_cors.cors() # A generic user model that might be used by an app powered by flask-praetorian class User(db.Model): id = db.column(db.integer, primary_key=true) username = db.column(db.text, unique=true) password = db.column(db.text) roles = db.column(db.text) is_active = db.column(db.boolean, default=true, def rolenames(self): try: return self.roles.split(',') except Exception: return def lookup(cls, username): return def identify(cls, id): return def identity(self): return self.id (continues on next page) 4 Chapter 1. Table of Contents

9 (continued from previous page) def is_valid(self): return self.is_active # Initialize flask app for the example app = flask.flask( name ) app.debug = True app.config['secret_key'] = 'top secret' app.config['jwt_access_lifespan'] = {'hours': 24} app.config['jwt_refresh_lifespan'] = {'days': 30} # Initialize the flask-praetorian instance for the app guard.init_app(app, User) # Initialize a local database for the example local_database = tempfile.namedtemporaryfile(prefix='local', suffix='.db') app.config['sqlalchemy_database_uri'] = 'sqlite:///{}'.format(local_database) db.init_app(app) # Initializes CORS so that the api_tool can talk to the example app cors.init_app(app) # Add users for the example with app.app_context(): db.create_all() db.session.add(user( username='thedude', password=guard.encrypt_password('abides'), )) db.session.add(user( username='walter', password=guard.encrypt_password('calmerthanyouare'), roles='admin' )) db.session.add(user( username='donnie', password=guard.encrypt_password('iamthewalrus'), roles='operator' )) db.session.add(user( username='maude', password=guard.encrypt_password('andthorough'), roles='operator,admin' )) db.session.commit() # Set up some routes for the methods=['post']) def login(): Logs a user in by parsing a POST request containing user credentials and issuing a JWT token... example:: (continues on next page) 1.1. Quickstart 5

10 $ curl -X POST \ -d '{"username":"walter","password":"calmerthanyouare"}' req = flask.request.get_json(force=true) username = req.get('username', None) password = req.get('password', None) user = guard.authenticate(username, password) ret = {'access_token': guard.encode_jwt_token(user)} return (flask.jsonify(ret), 200) (continued from def protected(): A protected endpoint. The auth_required decorator will require a header containing a valid JWT.. example:: $ curl -X GET \ -H "Authorization: Bearer <your_token>" return flask.jsonify(message='protected endpoint (allowed user {})'.format( def protected_admin_required(): A protected endpoint that requires a role. The roles_required decorator will require that the supplied JWT includes the required roles.. example:: $ curl -X GET \ -H "Authorization: Bearer <your_token>" return flask.jsonify( message='protected_admin_required endpoint (allowed user {})'.format( flask_praetorian.current_user().username, 'admin') def protected_operator_accepted(): A protected endpoint that accepts any of the listed roles. The roles_accepted decorator will require that the supplied JWT includes at least one of th accepted roles.. example:: $ curl -X GET \ -H "Authorization: Bearer <your_token>" (continues on next page) 6 Chapter 1. Table of Contents

11 (continued from previous page) return flask.jsonify( message='protected_operator_accepted endpoint (allowed usr {})'.format( flask_praetorian.current_user().username, ) ) # Run the example if name == ' main ': app.run(host=' ', port=5000) The above code can be found in example/basic.py. 1.2 Notes Error Handling By default, flask-praetorian will add an error handler to Flask for PraetorianErrors. This error handler produces nicely formatted json responses with status codes that reflect the failures. The flask-praetorian package s custom exception type PraetorianError derives from the FlaskBuzz base exception type from the flask-buzz exceptions package. The flask-buzz package provides convenience methods for error handlers. The error handling may be disabled by adding a configuration setting for DISABLE_PRAETORIAN_ERROR_HANDLER. You may wish to do this if you want to customize your error handling even further. For example, you may wish to have the error handler log messages about failures prior to returning an error response. In this case, you can still take advantage of flask-buzz s features to do so: app.register_error_handler( PraetorianError, PraetorianError.build_error_handler(lambda e: logger.error(e.message)), ) Flask-Restplus compatibility Flask-Restplus s error handler is not compatible with the normal Flask error handler. What s more, prior to Flask- Restplus , Flask-Restplus s error handler did not automatically handle derived exception classes, so you would need to handle each and every PraetorianError type in your handler. The flask-buzz exceptions package provides a helper method for registering error handlers with flask-restplus: PraetorianError.register_error_handler_with_flask_restplus(api) Like the normal Flask error handler, additional tasks may be passed to this method to be executed on the error prior to returning the response 1.2. Notes 7

12 1.2.3 Configuration Settings Table 1: Configuration Settings Flag Description Default Value SECRET_KEY A secret string value used to salt encryptions and hashes for the app. ABSOLUTELY MUST BE SET TO SOMETHING OTHER THAN DEFAULT IN PRODUCTION. DO NOT USE THE DEFAULT IN PRO- DUCTION PRAETORIAN_HASH_SCHEME The hash scheme used to encrypt passwords in the database. If unset, 'pbkdf2_sha512' passlib will use the default scheme which is pbkdf2_sha512 JWT_ALLOWED_ALGORITHMS A list of allowed algorithms that may be used to hash the JWT. See ['HS256'] the PyJWT docs for more details. JWT_ALGORITHM The jwt hashing algorithm to be used to encode tokens 'HS256' JWT_ACCESS_LIFESPAN The default length of time that a JWT may be used to access a protected endpoint. See the PyJWT docs for more details. {'minutes': 15} JWT_REFRESH_LIFESPAN The default length of time that a JWT may be refreshed. JWT may also not be refreshed if its access lifespan is not expired. {'days': 30} JWT_HEADER_NAMEThe name of the header in HTTP requests where the JWT will be 'Authorization' found JWT_HEADER_TYPEA string describing the type of the header. Usually Bearer but may 'Bearer' be customized by the user USER_CLASS_VALIDATION_METHOD The name of the method on a user instance that should be used to 'is_valid' validate that the user is active in the system. DISABLE_PRAETORIAN_ERROR_HANDLER Do not register the flask error handler automatically. The user may None wish to configure the error handler themselves Requirements for the user_class The user_class argument supplied during initialization represents the class that should be used to check for authorization for decorated routes. The class itself may be implemented in any way that you see fit. It must, however, satisfy the following requirements: Provide a lookup class method that: should take a single argument of the name of the user should return an instance of the user_class or None Provide an identify class method should take a single argument of the unique id of the user should return an instance of the user_class or None Provide a rolenames instance attribute should return a list of string roles assigned to the user Provide a password instance attribute should return the hashed password assigned to the user Provide an identity instance attribute should return the unique id of the user Although the example given in the documentation uses a SQLAlchemy model for the userclass, this is not a requirement. 8 Chapter 1. Table of Contents

13 1.3 Tutorial This tutorial will use the example code provided in the example/ code directory., Download the entire directory and save it on your machine where you will be running through the tutorial Requirements This tutorial requires (outside of the normal python dependencies): sqlite a web-browser About the api-tool The custom api gui tool is itself a flask-app that uses html and javascript to render the website. If you are curious about the code feel free to explore, but don t let the implementation distract you: the author of flask-praetorian is a back-end dev and javascript is not his strong-suit. The main thing to focus on as you go through the tutorial is the structure of the requests and responses. These will be shown by two text boxes at the bottom of the gui tool. If you do not wish to use the api tool for this tutorial, you could use a tool designed for sending requests to an API such as Postman or curl. In either case, the requests described in the request box in the screenshots of the api-tool can be used with the tool of your choice Starting up the servers We will need to start up 4 different python/flask applications: example/basic.py is an api that shows basic jwt security concepts example/refresh.py is an api that shows jwt refreshing concepts example/blacklist.py is an api that shows jwt blacklisting concepts example/api_tool.py is the demonstration flask-app that accesses the apis All four of these should be started. You may kick them off in separate terminals, or as daemons. It s nice to watch the output from the apps in terminals, but the api_tool should display all of the request/response info that you need for this tutorial The flask applications are started easily: $ python example/basic.py Each of the api applications runs on a different port to avoid collision. The api-tool runs on port 5050, and that is where you will access the ui Accessing the tool Once you ve started up all four flask apps, you can checkout the gui tool by navigating to localhost: Tutorial 9

14 1.3.5 Tutorial Sections Basic Tutorial This section of the tutorial covers concepts demonstrated by example/basic.py. These concepts include: Logging in Protected endpoints Role-required endpoints Role-accepted endpoints Logging in To access protected endpoints of our example app, we will need to provision a JWT token from our server for the selected user. This token will be used to access any protected endpoints in our app. Usually, you will want to add some endpoint, such as login, to your api. This endpoint will parse user credentials from a request, authenticate the user and then encode a JWT for future requests. In our example application, the login endpoint looks like this: Listing 1: from methods=['post']) def login(): Logs a user in by parsing a POST request containing user credentials and issuing a JWT token... example:: $ curl -X POST \ -d '{"username":"walter","password":"calmerthanyouare"}' req = flask.request.get_json(force=true) username = req.get('username', None) password = req.get('password', None) user = guard.authenticate(username, password) ret = {'access_token': guard.encode_jwt_token(user)} return (flask.jsonify(ret), 200) Of course, to authenticate users, they must be added to whatever data store that your application uses. Though flaskpraetorian does not depend on a particular data mapper (usually an ORM like SQLAlchemy), it does require that the user class supplies specific methods and properties. See Requirements for the user_class. The example source code uses SQLAlchemy as the data store, and users are added as shown: Listing 2: from example/basic.py # Add users for the example with app.app_context(): db.create_all() db.session.add(user( username='thedude', password=guard.encrypt_password('abides'), (continues on next page) 10 Chapter 1. Table of Contents

15 )) db.session.add(user( username='walter', password=guard.encrypt_password('calmerthanyouare'), roles='admin' )) db.session.add(user( username='donnie', password=guard.encrypt_password('iamthewalrus'), roles='operator' )) db.session.add(user( username='maude', password=guard.encrypt_password('andthorough'), roles='operator,admin' )) db.session.commit() (continued from previous page) For convenience, the api-tool pre-populates a drop-down with users and automatically fills in the passwords, too. Our most basic user is TheDude with the password abides. We ll log in with this user first Select TheDude user in the api-tool: 1.3. Tutorial 11

16 Note that the password can be manually changed. You may find it interesting to explore the requests/responses that happen by changing the password prior to log-in or attempting to log in as TheStranger Next, we ll click the button to log in: 12 Chapter 1. Table of Contents

17 The response is a simple json object with one field: access_token. This is the token that will be used to access protected endpoints. Note that when the token is granted, the Remaining Access Lifespan timer and the Remaining Refresh Lifespan timers begin counting down. We ll dive more into the lifespan concepts in the Refresh section. If you are using flask-praetorian in your app, and create a login endpoint that accepts user credentials like this, you should obviously use https so that your password isn t sent across to the api in the clear. Accessing a protected endpoint Once your user has logged in by securing a JWT, they can access flask-praetorian protected endpoints by including the token in the request header. These endpoints are protected, because they ve been decorated with flask-praetorian decorator. This means that a request to these endpoints must carry a valid jwt to gain access: Listing 3: def protected(): (continues on next page) 1.3. Tutorial 13

18 A protected endpoint. The auth_required decorator will require a header containing a valid JWT (continued from previous page).. example:: $ curl -X GET \ -H "Authorization: Bearer <your_token>" return flask.jsonify(message='protected endpoint (allowed user {})'.format( flask_praetorian.current_user().username, )) Let s try to access the protected endpoint in the example app Assuming that you still have the token that you acquired by logging in, all you need to do is click the protected button which sends a request to the protected endpoint: In this case, the authorization works, and the response carries the JSON payload returned from the app s protected endpoint. The flask-praetorian extension by default registers an error_handler with the flask app when it is initialized. This error handler automatically converts any PraetorianError exceptions (or derived exceptions) into a json response that carries the status code, message, and error type. The status code and error type can be very useful for applications that need 14 Chapter 1. Table of Contents

19 to handle specific error responses. The available exception types are listed in the exceptions module Accessing an endpoint with required roles In addition to decorator, flask-praetorian also provides decorators that require users to have certain roles to access them. Each of the decorators do not require decorator to be explicitly added. They will implicitly prior to checking the roles. However, explicitly adding decorator as well will not cause any issues (in fact, this was required in earlier versions). decorator keeps users that do not have all of the required roles from accessing the endpoint: Listing 4: def protected_admin_required(): A protected endpoint that requires a role. The roles_required decorator will require that the supplied JWT includes the required roles.. example:: $ curl -X GET \ -H "Authorization: Bearer <your_token>" return flask.jsonify( message='protected_admin_required endpoint (allowed user {})'.format( flask_praetorian.current_user().username, ) ) Let s try to access a protected endpoint with required roles. First, try to access the protected_admin_required endpoint with our basic user TheDude Tutorial 15

20 Even though our request has a valid token in the headers, access is not granted because our user lacks the required role for access. Next, let s log in as a user with the admin role and see what happens: 16 Chapter 1. Table of Contents

21 This time, our admin user Walter is granted access to the protected endpoint. Requests does not have to include any human readable indication of who the user is. Instead, everything your app needs to identify the user is embedded in the JWT token. It s also worth noting that with decorator, each one of the required roles must be possessed by the user or access will not be granted. This means that even if a user has an admin role, they could not access an endpoint that required admin and flunky. They would have to have a flunky role. There is no concept of role hierarchy in flask-praetorian. Accessing an endpoint with accepted roles The last decorator to note is Instead of requiring all the listed roles, this decorator allows access to users that have any one of the listed roles: Listing 5: 'admin') def protected_operator_accepted(): A protected endpoint that accepts any of the listed roles. The roles_accepted decorator will require that the supplied JWT includes at (continues on next page) 1.3. Tutorial 17

22 least one of th accepted roles (continued from previous page).. example:: $ curl -X GET \ -H "Authorization: Bearer <your_token>" return flask.jsonify( message='protected_operator_accepted endpoint (allowed usr {})'.format( flask_praetorian.current_user().username, ) ) The protected_operator_accepted endpoint accepts users that have either the admin role or the operator role. Let s try out the protected_operator_accepted endpoint First, try accessing it with TheDude. You ll see that you are not granted access because TheDude does not have either the admin or the operator role. Next, let s try accessing this endpoint with the Donnie user. This user does not have the admin role, but he does have the operator role: You should try accessing this endpoint with Maude as well. Maude is both an admin and an operator. 18 Chapter 1. Table of Contents

23 In Conclusion Logging in entails checking for valid user credentials and granting a jwt The flask-praetorian decorators protect endpoints from unauthorized grants access to requests carrying a valid grants access to users that have all the listed grants access to users that have one of the listed roles PraetorianErrors are automatically handled and packaged as responses Refresh Tutorial This section of the tutorial covers concepts demonstrated by example/refresh.py. These concepts include: Access and refresh lifespans of the jwt Refreshing a token Disabling users Concept The basic concept of JWT is that essential user information is embedded in the authorization token that can be very quickly accessed from any route that needs to be protected. The advantage to this is that the application does not need to access the data-store at all to check for authorization. In most applications, accessing the data-store can be one of the most costly operations. So, JWT offers a nice work around so that routes that do not need to access the store can do so very quickly and simply. Because we re using the token alone to authorize a user, and because the token is issued once with all the information that s needed, logging out a user is not so straight-forward. Thus, tokens need to have an expiration. This is where the concept of refreshing a token comes in. We want to make sure that we check the status of a user regularly (to make sure they haven t been removed from the system), but we don t want to do this on every api request. We also don t want to make the user have to regularly enter their credentials to access the API. Ideally, entering credentials would be an infrequent operation. So, flask-praetorian adds the ability to refresh a token. The general guidelines are that a token should need to be refreshed relatively frequently (the default is 15 minutes) and issuing new tokens should not have to happen very frequently at all (the default is 30 days). Lifespans The JWTs provisioned by flask-praetorian have two distinct lifespans: The access lifespan is the length of time that a token can access protected endpoints before it needs to be refreshed. The refresh lifespan is the length of time that a token can be refreshed before an entirely new token must be provisioned by logging in. Both of these lifespans are encoded directly in the JWT. The lifespans that are provisioned are configured with the JWT_ACCESS_LIFESPAN and JWT_REFRESH_LIFESPAN configuration settings for the flask app. The example app configures these like so: 1.3. Tutorial 19

24 Listing 6: from example/refresh.py app.config['jwt_access_lifespan'] = {'seconds': 30} app.config['jwt_refresh_lifespan'] = {'minutes': 2} However, in a real app, these are settings that you will probably want added to the config prior to initializing the app. To accelerate the demonstration of these lifespans expiring, the refresh tutorial has much shorter lifespans. Our demo app includes two countdown timers to help you see how much lifespan is left for the provisioned JWT: If you want to use curl for this section, you will have to have quick fingers! Refreshing a Token When a token s access lifespan expires, the token needs to be refreshed before protected endpoints can be accessed again. Let s try logging in as our normal user TheDude, waiting for the access lifespan to expire, and then accessing the protected endpoint: 20 Chapter 1. Table of Contents

25 When we try to access the endpoint, we get a 401 error response that reports that access has expired. When this happens, the token should be refreshed. The recommended way to do this is to have a refresh endpoint in your app that performs the refresh. In general, this endpoint doesn t need to do anything but fetch the existing JWT from the header and return a new one: Listing 7: from methods=['get']) def refresh(): Refreshes an existing JWT by creating a new one that is a copy of the old except that it has a refrehsed access expiration... example:: $ curl -X GET \ -H "Authorization: Bearer <your_token>" old_token = guard.read_token_from_header() new_token = guard.refresh_jwt_token(old_token) ret = {'access_token': new_token} return flask.jsonify(ret), 200 In the api tool, the endpoint is accessed by clicking on the refresh button: 1.3. Tutorial 21

26 There are a few things to note here. First, when we say a token is refreshed, we mean that a new token is issued. This new token is a copy of the original token in that it carries the same jti claim. Also, the refresh lifespan is not renewed in the new token. The access lifespan, however, is renewed. For subsequent access to protected endpoints, the new refreshed token should be used. Once a token s refresh lifespan is expired, that token is worthless. An entirely new token must be provisioned by logging in. To demonstrate this, let s try refreshing a token when the refresh lifespan is expired: 22 Chapter 1. Table of Contents

27 Validating Users One of the performance benefits of using JWTs is that there is no need to lookup users in the datastore to verify access. Because data queries can be the slowest part of an application, avoiding this lookup can be a definite performance gain. Instead of looking the user up, the needed user information and authorization information is embedded in the JWT and can be very quickly retrieved. However, it is important to validate users regularly. This is the purpose of having to refresh tokens. Because the need to refresh tokens is much more infrequent than simply accessing the endpoints, we can safely add more expensive operations to the refresh process. Thus, at refresh time, a user is looked up in the data-store to make sure they still exist and are valid users (have not been disabled). To demonstrate this, the example provides a disable_user endpoint that can be used to disable the current user in the data-store: Listing 8: from methods=['post']) def disable_user(): Disables a user in the data store (continues on next page) 1.3. Tutorial 23

28 (continued from previous page).. example:: $ curl -X POST \ -H "Authorization: Bearer <your_token>" \ -d '{"username":"walter"}' req = flask.request.get_json(force=true) usr = User.query.filter_by(username=req.get('username', None)).one() usr.is_active = False db.session.commit() return flask.jsonify(message='disabled user {}'.format(usr.username)) In the api tool, this is activated by clicking on the disable_user button: Note that disabling a user does not have any effect until the access lifespan is expired. So, a disabled user can keep accessing protected endpoints until access expires. This is why it s important to keep the access lifespan relatively short; you want disabling a user to have a near-term effect: 24 Chapter 1. Table of Contents

29 So, even though the user was disabled, access is still granted because the access lifespan hasn t expired. However, see what happens when we try to refresh a token when the user is disabled: 1.3. Tutorial 25

30 Similarly, a user who has been disabled cannot be logged in by the normal mechanism. Note that once a user has been disabled in this tutorial, you will need to restart the refresh app to re-gain access. In Conclusion JWTs are governed by their access and refresh lifespans A JWT must be refreshed when the access lifespan expires A JWT can be refreshed when the access is expired and the refresh is not Users are validated at refresh time only Blacklist Tutorial This section of the tutorial covers concepts demonstrated by example/blacklist.py. These concepts include: Working with long-lived JWT tokens Blacklisting jti claims 26 Chapter 1. Table of Contents

31 Long-lived JWT Often, RESTful APIs are consumed by other apps. These apps might make thousands of requests per second and are pre-registered ahead of time as trusted apps. In these cases, you do not want to have to make the app have to constantly refresh its token or to log in repeatedly. So, long-lived JWT are often provisioned for this. The problem is that a long-lived token might fall into the wrong hands, and your app needs a mechanism to revoke access from a stolen JWT. This is what the blacklist is used for The Blacklist A JWT token is uniquely identified by its jti claim. For flask-praetorian, this is provisioned as uuid4. When a token is refreshed, the new token is given the same jti claim. This serves to identify the two tokens as being really the same. A blacklist is a collection of jti claims for tokens that have had access revoked. The blacklist should be very performant and persistent. It is best to use a container that minimizes lookup time. One common pattern is to have a database table that persists the blacklist data. However, this table should not be accessed to check the blacklist on every request to a protected endpoint. Instead, when an app loads, the blacklist should be loaded into some container that lives in local memory and has very rapid lookup. You should use the refresh operation as a mechanism to flush the blacklist back out to the data-store for persistence so that if your app dies, most of the blacklist is preserved. For the purposes of our demo, the blacklist is simply a python set that is stored in local memory: blacklist = set() Listing 9: from example/blacklist.py def is_blacklisted(jti): return jti in blacklist The is_blacklisted function is then registered when initializing the flask-praetorian instance with the app: Listing 10: from example/blacklist.py # Initialize the flask-praetorian instance for the app with is_blacklisted guard.init_app(app, User, is_blacklisted=is_blacklisted) Now, any time a protected endpoint it accessed, the jti claim from the JWT will first be checked against the blacklist. To make demonstration of the blacklist more obvious, the lifespans provisioned for this demo app are obscenely long Blacklisting a Token The example app has an added blacklist_token endpoint that will blacklist the current token: Listing 11: from methods=['post']) (continues on next page) 1.3. Tutorial 27

32 def blacklist_token(): Blacklists an existing JWT by registering its jti claim in the blacklist. (continued from previous page).. example:: $ curl -X POST \ -d '{"token":"<your_token>"}' req = flask.request.get_json(force=true) data = guard.extract_jwt_token(req['token']) blacklist.add(data['jti']) return flask.jsonify(message='token blacklisted ({})'.format(req['token'])) Let s try blacklisting a token for our admin user, Walter : Now, the token for Walter is blacklisted. No access to any protected endpoint will be granted because the jti claim from that token will be found in the blacklist: 28 Chapter 1. Table of Contents

33 In Conclusion Apps often get long-lived JWTs Access for these long-lived tokens can be controlled with the blacklist The blacklist must have very fast lookup 1.4 flask-praetorian Developer Guide This developer guide will help you get started on working on flask-praetorian in a development environment so that you can add features and run tests Dependencies python3 virtualenv 1.4. flask-praetorian Developer Guide 29

34 1.4.2 Setup Create a virtualenv You should set up your virtualenv using python3: $ virtualenv --python=python3 env $ source env/bin/activate Install the package for development In order to install the package for development and to include all its dependencies (via pip), execute this command: $ pip install -e.[dev] The full list of dependencies can be found in setup.py Running tests This project uses pytest for its unit testing. Tests are executed by invoking pytest directly from the root of the project: $ py.test -ra tests The -ra option is recommended as it will report skipped tests Documentation readthedocs.org Documentation for the flask-praetorian package is available on readthedocs.org. It is configured so that new documentation is generated from the flask-praetorian docs directory automatically whenever a new commit is pushed to the master branch. So, developers need not do anything to build documentation. Adding further documentation The majority of the automatically generated developer s guide is produced from python docstrings This project uses the sphinx extension sphinx-apidoc to generate help pages from the docstrings at the module, class, and function level. There are several special keywords that can be added to docstrings that have special significance for sphinx. The most useful of these are the :param: and :return: keywords. Items can be added to the project-wide todo list and notes that is shown in the /help endpoint Here is an example method with marked up docstring: def some_method(param1, param2): This is a method that does stuff (continues on next page) 30 Chapter 1. Table of Contents

35 :param: param1: This is the first param :param: param2: This is the second param :return: A string that says 'yo'.. todo:: Make this method more awesomer.. note:: This is just a lame example return 'yo' (continued from previous page) Code Style This project uses the style constraints described in pep8 Please follow the style guide as stated. Also, please enforce the style guide during code reviews Useful tools sphinx-view restructuredtext documents and sphinx documentation can be previewed as they are edited on your workstation using a tool called sphinx-view. It is indispensable when updating this README.rst document or one of the templates for the autognerated sphinx documentation. flake8 The flake8 tool is very useful for checking for compliant code style. It can be easily installed through pip: $ pip install flake8 The flake8 tool is invoked by targeting a specific source directory: $ flake8 flask_praetorian Particular directories and source files may also be targeted directly vim Editor plugin The vim-flake8 plugin for vim is very useful for identifying style issues inside the vim editor. the vim-flake8 plugin is most easily added by using pathogen. The following vim binding is useful to execute the flake8 check on write for all python source files: # autocmd BufWritePost *.py call Flake8() It is most useful to include that in your.vimrc file Other notes flask-praetorian uses the pendulum.utcnow() to timestamp its JWT tokens 1.4. flask-praetorian Developer Guide 31

36 1.5 flask_praetorian package Submodules flask_praetorian.base module class flask_praetorian.base.praetorian(app=none, user_class=none, is_blacklisted=none) Bases: object Comprises the implementation for the flask-praetorian flask extension. Provides a tool that allows password authentication and token provision for applications and designated endpoints authenticate(username, password) Verifies that a password matches the stored password for that username. If verification passes, the matching user instance is returned encode_eternal_jwt_token(user) This utility function encodes a jwt token that never expires Note: This should be used sparingly since the token could become a security concern if it is ever lost. If you use this method, you should be sure that your application also implements a blacklist so that a given token can be blocked should it be lost or become a security concern encode_jwt_token(user, override_access_lifespan=none, override_refresh_lifespan=none) Encodes user data into a jwt token that can be used for authorization at protected endpoints Param override_access_lifespan: Override s the instance s access lifespan to set a custom duration after which the new token s accessability will expire. May not exceed the refresh_lifespan Param override_refresh_lifespan: Override s the instance s refresh lifespan to set a custom duration after which the new token s refreshability will expire. encrypt_password(raw_password) Encrypts a plaintext password using the stored passlib password context error_handler(error) Provides a flask error handler that is used for PraetorianErrors (and derived exceptions). extract_jwt_token(token) Extracts a data dictionary from a jwt token init_app(app, user_class, is_blacklisted=none) Initializes the Praetorian extension Param app: The flask app to bind this extension to Param user_class: The class used to interact with user data Param is_blacklisted: A method that may optionally be used to check the token against a blacklist when access or refresh is requested Should take the jti for the token to check as a single argument. Returns True if the jti is blacklisted, False otherwise. By default, always returns False. pack_header_for_user(user, override_access_lifespan=none, override_refresh_lifespan=none) Encodes a jwt token and packages it into a header dict for a given user Param user: The user to package the header for 32 Chapter 1. Table of Contents

37 Param override_access_lifespan: Override s the instance s access lifespan to set a custom duration after which the new token s accessability will expire. May not exceed the refresh_lifespan Param override_refresh_lifespan: Override s the instance s refresh lifespan to set a custom duration after which the new token s refreshability will expire. read_token_from_header() Unpacks a jwt token from the current flask request refresh_jwt_token(token, override_access_lifespan=none) Creates a new token for a user if and only if the old token s access permission is expired but its refresh permission is not yet expired. The new token s refresh expiration moment is the same as the old token s, but the new token s access expiration is refreshed Param token: The existing jwt token that needs to be replaced with a new, refreshed token Param override_access_lifespan: Override s the instance s access lifespan to set a custom duration after which the new token s accessability will expire. May not exceed the refresh lifespan flask_praetorian.decorators module flask_praetorian.decorators.auth_required(method) This decorator is used to ensure that a user is authenticated before being able to access a flask route. It also adds the current user to the current flask context. flask_praetorian.decorators.roles_accepted(*accepted_rolenames) This decorator ensures that any uses accessing the decorated route have one of the needed roles to access it. If decorator is not supplied already, this decorator will implicitly first flask_praetorian.decorators.roles_required(*required_rolenames) This decorator ensures that any uses accessing the decorated route have all the needed roles to access it. If decorator is not supplied already, this decorator will implicitly first flask_praetorian.exceptions module exception flask_praetorian.exceptions.authenticationerror(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The entered user s password did not match the stored password exception flask_praetorian.exceptions.blacklistederror(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The jwt token has been blacklisted and may not be used any more status_code = 403 exception flask_praetorian.exceptions.earlyrefresherror(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The jwt token has not yet expired for access and may not be refreshed exception flask_praetorian.exceptions.expiredaccesserror(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror 1.5. flask_praetorian package 33

38 The jwt token has expired for access and must be refreshed exception flask_praetorian.exceptions.expiredrefresherror(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The jwt token has expired for refresh. An entirely new token must be issued exception flask_praetorian.exceptions.invalidtokenheader(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The token contained in the header is invalid exception flask_praetorian.exceptions.invalidusererror(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The user is no longer valid and is now not authorized status_code = 403 exception flask_praetorian.exceptions.missingclaimerror(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The jwt token is missing a required claim exception flask_praetorian.exceptions.missingroleerror(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The token is missing a required role status_code = 403 exception flask_praetorian.exceptions.missingtokenheader(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The header is missing the required jwt token exception flask_praetorian.exceptions.missingusererror(message, *format_args, **format_kwds) Bases: flask_praetorian.exceptions.praetorianerror The user could not be identified exception flask_praetorian.exceptions.praetorianerror(message, *format_args, **format_kwds) Bases: flask_buzz.flaskbuzz Provides a custom exception class for flask-praetorian based on flask-buzz. flask-buzz on gitub status_code = Chapter 1. Table of Contents

39 Python Module Index f flask_praetorian, 32 flask_praetorian.base, 32 flask_praetorian.decorators, 33 flask_praetorian.exceptions, 33 35

40 36 Python Module Index

41 Index A auth_required() (in module flask_praetorian.decorators), 33 authenticate() (flask_praetorian.base.praetorian method), 32 AuthenticationError, 33 B BlacklistedError, 33 E EarlyRefreshError, 33 encode_eternal_jwt_token() (flask_praetorian.base.praetorian method), 32 encode_jwt_token() (flask_praetorian.base.praetorian method), 32 encrypt_password() (flask_praetorian.base.praetorian method), 32 error_handler() (flask_praetorian.base.praetorian method), 32 ExpiredAccessError, 33 ExpiredRefreshError, 34 extract_jwt_token() (flask_praetorian.base.praetorian method), 32 F flask_praetorian (module), 32 flask_praetorian.base (module), 32 flask_praetorian.decorators (module), 33 flask_praetorian.exceptions (module), 33 I init_app() (flask_praetorian.base.praetorian method), 32 InvalidTokenHeader, 34 InvalidUserError, 34 M MissingClaimError, 34 MissingRoleError, 34 MissingTokenHeader, 34 MissingUserError, 34 P pack_header_for_user() (flask_praetorian.base.praetorian method), 32 Praetorian (class in flask_praetorian.base), 32 PraetorianError, 34 R read_token_from_header() (flask_praetorian.base.praetorian 33 method), refresh_jwt_token() (flask_praetorian.base.praetorian method), 33 roles_accepted() (in module flask_praetorian.decorators), 33 roles_required() (in module flask_praetorian.decorators), 33 S status_code (flask_praetorian.exceptions.blacklistederror attribute), 33 status_code (flask_praetorian.exceptions.invalidusererror attribute), 34 status_code (flask_praetorian.exceptions.missingroleerror attribute), 34 status_code (flask_praetorian.exceptions.praetorianerror attribute), 34 37