JWT Authentication with Flask

Understanding the JWT Structure

A JWT is composed of three parts separated by dots: a header, a payload, and a signature. The header typically identifies the algorithm used, the payload contains the user claims (like their unique identifier and expiration time), and the signature ensures the token has not been tampered with. Because the server holds the secret key used to sign the token, it can verify the integrity of the data just by re-hashing the header and payload and comparing it against the provided signature. This stateless nature means your Flask application does not need to maintain a stateful session store, such as a database table or Redis cache, to identify which user is making a request. By embedding the user's identity directly into the token, you offload the burden of state management to the client, which is essential for performance and horizontal scaling in distributed systems.

import jwt
import datetime

# The secret key is used to sign the token; never hardcode this in production.
SECRET_KEY = 'super-secret-key-that-should-be-in-environment-variables'

def generate_token(user_id):
    # The payload contains claims about the user and token expiration.
    payload = {
        'exp': datetime.datetime.utcnow() + datetime.timedelta(hours=1),
        'iat': datetime.datetime.utcnow(),
        'sub': user_id
    }
    # Sign the token using the HMAC SHA256 algorithm.
    return jwt.encode(payload, SECRET_KEY, algorithm='HS256')

Implementing Protected Routes

To secure a route in Flask, you must intercept the incoming request and inspect the Authorization header for a valid token. The standard convention is to use the Bearer schema, where the client sends 'Authorization: Bearer <token>'. Once your application receives this request, it must extract the token string and attempt to decode it using the same secret key used for signing. If the token is expired, the signature is invalid, or the header is missing, the authentication check fails. Using a decorator is the most idiomatic way to implement this in Flask, as it keeps your route logic clean by separating the authentication mechanism from the business logic. By wrapping route functions with a custom decorator, you can ensure that only requests with a valid token have access to your sensitive endpoint data, effectively creating a perimeter of security around your API endpoints.

from functools import wraps
from flask import request, jsonify

def token_required(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        token = request.headers.get('Authorization', '').replace('Bearer ', '')
        if not token:
            return jsonify({'message': 'Token is missing'}), 401
        try:
            data = jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
        except jwt.ExpiredSignatureError:
            return jsonify({'message': 'Token has expired'}), 401
        except:
            return jsonify({'message': 'Invalid token'}), 401
        return f(*args, **kwargs)
    return decorated

User Login and Token Issuance

The token issuance process is where you establish identity. After a user provides valid credentials, such as a username and password, you verify them against your database. Upon successful validation, your Flask server generates a signed JWT that contains the user's unique identifier. This token acts as a temporary digital credential. The client is responsible for storing this token, usually in a local storage or secure cookie, and sending it back in the header of subsequent requests. Since the server does not 'remember' the user in a session object, it trusts the token implicitly once it verifies the cryptographic signature. This effectively hands the user a 'key' that proves who they are, provided they keep the key safe. By keeping the token lifespan short, you reduce the risk associated with stolen tokens, as they will naturally expire within a defined window, forcing the user to re-authenticate periodically.

from flask import Flask, request

app = Flask(__name__)

@app.route('/login', methods=['POST'])
def login():
    auth = request.json
    # In a real app, verify credentials against a database hash.
    if auth.get('username') == 'admin' and auth.get('password') == 'secret':
        token = generate_token(user_id=1)
        return jsonify({'token': token})
    return jsonify({'message': 'Login failed'}), 401

Handling Expiration and Token Security

Security in a stateless environment relies heavily on the expiration claim within the JWT. If a token were never to expire, a compromised token would grant indefinite access to your application. By setting the 'exp' (expiration) field to a short duration, such as fifteen minutes or one hour, you limit the window of opportunity for an attacker to use a intercepted token. You must always handle the ExpiredSignatureError exception in your Flask application to explicitly inform the client that they need to re-authenticate. Never store sensitive information inside the JWT payload, as the token is merely base64 encoded and can be read by anyone who intercepts it. The security of the token comes from the signature, not from hiding the contents. By treating tokens as short-lived permissions rather than long-term credentials, you maintain a robust security posture while ensuring that users are periodically re-validated.

from jwt import decode

# Example of specific error handling during decoding
def verify_token(token):
    try:
        # Decode will raise ExpiredSignatureError if the exp claim is in the past
        return decode(token, SECRET_KEY, algorithms=['HS256'])
    except jwt.ExpiredSignatureError:
        return None # Prompt client to re-login
    except jwt.InvalidTokenError:
        return None # Token is malformed or signature mismatch

Applying Security Best Practices

To ensure your Flask API remains secure, always use the 'HS256' algorithm with a strong, complex secret key. If your infrastructure allows, consider asymmetric signing (using 'RS256') where you sign tokens with a private key and verify them with a public key; this is even more secure as the server verifying the token does not need the secret used to create it. Furthermore, you must always serve your API over HTTPS, as this prevents tokens from being intercepted via man-in-the-middle attacks. If a user logs out, you cannot technically revoke the token in a truly stateless system because the server does not track them. In high-security scenarios, you might implement a blacklist of revoked tokens in a fast memory store like Redis to handle logout scenarios effectively. Combining short-lived tokens with secure transmission protocols provides the strongest foundation for your Flask authentication system, protecting both the server's integrity and the user's data.

from flask import jsonify

@app.route('/dashboard')
@token_required
def dashboard():
    # Access the user data decoded from the token if needed
    return jsonify({'data': 'Welcome to the protected dashboard!'})

if __name__ == '__main__':
    # Always run behind a secure proxy with HTTPS in production
    app.run(ssl_context='adhoc')

Interview questions

All Flask interview questions →

Check yourself

Take the full Flask quiz →