Simple JWT Authentication with Flask-JWT

Often in Flask applications we want to add login/logout functionality. Depending on the type of application you're creating, you could use sessions or tokens.

• Sessions are best suited to applications where you're serving web pages with Flask—i.e. making extensive use of render_template.
• Tokens are best suited to APIs, where your Flask application accepts and returns data to another application (such as mobile apps or web apps).

In this post we'll learn how to add token-based authentication to your Flask apps. But first...

What is a JWT?

JWT stands for JSON Web Token, and it is a piece of text with some information encoded into it.

The information stored when doing authentication in a Flask app is usually something that we can use to identify the user for whom we generated the JWT.

The flow goes like this:

1. User provides their username and password
2. We verify they are correct inside our Flask app
3. We generate a JWT which contains the user's ID.
4. We send that to the user.
5. Whenever the user makes a request to our application, they must send us the JWT we generated earlier. By doing this, we can verify the JWT is valid—and then we'll know the user who sent us the JWT is the user for whom we generated it.

That last point is important. When we receive a JWT we know to be valid, we know we generated it for a specific user. We can check this using the information stored inside the JWT.

Since we know the user sent us the JWT that we generated when they logged in, we can treat this used as a "logged in user".

Any user that does not send us a valid JWT, we will treat as a "logged out" user.

Authentication with Flask-JWT

There are two main libraries for authentication with Flask: Flask-JWT and Flask-JWT-Extended.

Flask-JWT is slightly simpler, while Flask-JWT-Extended is a bit more powerful. Learning one will make learning the other very straightforward.

In this post we'll use Flask-JWT.

Installing and linking with our app

To install Flask-JWT, activate your virtual environment and then do:

pip install flask-jwt

Then, in the file where your app is defined, you'll need to import Flask-JWT and create the JWT object. You also need to define app.secret_key as that is used to sign the JWT so you know it is your app that created it, and not anyone else:

from flask import Flask
from flask_jwt import JWT
from security import authenticate, identity

app = Flask(__name__)
app.secret_key = "jose"  # Make this long, random, and secret in a real app!
jwt = JWT(app, authenticate, identity)

if __name__ == "__main__":
	app.run()

We also have an import for authenticate and identity. These two functions are required for Flask-JWT to know how to handle an incoming JWT, and also what data we want to store in an outgoing JWT.

As soon as we create the JWT object, Flask-JWT registers an endpoint with our application, /auth.

That means that the simple app in that code already has an endpoint that users can access. By default, users should be able to send POST requests to the /auth endpoint with some JSON payload:

{
  "username": "their_username",
  "password": "their_plaintext_password"
}

What is authenticate?

The authenticate function is used to authenticate a user. That means, when a user gives us their username and password, what data we want to put into the JWT. Remember, the data we put into the JWT will come back to us when the user sends it with each request.

The flow goes like this:

1. User makes a POST request to the new /auth endpoint with their username and password as the JSON payload.
2. The authenticate function is called with that username and password. Flask-JWT set this up when we created the JWT object.

Usually in the authenticate function I check the validity of a user's username and password, and then tell Flask-JWT to store the user's id inside the JWT.

Something like this:

from werkzeug.security import safe_str_cmp
from models.user import UserModel


def authenticate(username, password):
    user = UserModel.find_by_username(username)
    if user and safe_str_cmp(user.password, password):
        return user

My authenticate function accepts a username and password. It then goes into the database and finds a user matching that username, and checks the password is correct.

If it is, it returns the user.

Does that mean the user is stored in the JWT?

No. Flask-JWT will take the id property of the user object and store that in the JWT.

If your user object does not have an id property, you'll get an error.

You can change which property gets stored in the JWT by setting an app configuration property. Learn more in our Flask-JWT Configuration blog post.

What is identity?

The identity function is used when we receive a JWT.

In any of our endpoints (except the /auth endpoint) the user can send us a JWT alongside their data. They will do this by adding a header to their request:

Authorization: JWT <JWT_VALUE_HERE>

When that happens, Flask-JWT will take the JWT and get the data out of it. Data stored inside a JWT is called a "payload", so our identity function accepts that payload as a parameter:

def identity(payload):
    user_id = payload['identity']
    return UserModel.find_by_id(user_id)

The payload['identity'] contains the user's id property that we saved into the JWT when we created it. The payload also contains other things, such as when the token was created, when it expires, and more. For more information, read the "Payload" section of this post.

Since payload['identity'] is the user's id—we use that to find the user in the database and return it.

Important: the identity function is not called unless we decorate our endpoints with the @jwt_required() decorator, like so:

from flask_jwt import jwt_required, current_identity

@app.route('/protected')
@jwt_required()
def protected():
    return '%s' % current_identity

Inside any endpoint that is decorated with @jwt_required(), we can access the current_identity proxy—it will give us whatever the identity function returns for the JWT we received in this specific request.

Testing and error messages

Here's a simple app, taken from the official documentation, that you can use to test your Flask-JWT requests.

I would recommend testing different scenarios with Flask-JWT to check what it can return you. For example, what happens if:

• You send an invalid username or password;
• You send an invalid or incomplete JWT;
• Your user isn't found in the database with the id in the payload;

Flask-JWT-Extended

Flask-JWT-Extended is very similar to Flask-JWT, but has more configuration options and some more functionality. For example, it allows for token refreshing.

After you're comfortable with Flask-JWT—and if you need those advanced features—read our blog post on Flask-JWT-Extended for more!

---

I hope you've found this post useful, and you've learned something!

If you want an even better and more digestible set of video tutorials guiding you through creating Flask applications and REST APIs, check out our REST APIs with Flask and Python course. It contains everything you need to develop simple, professional REST APIs easily.

If you sign up to our mailing list below, that's the best way to get access to a discount code—we share them every month with our subscribers!