Building a Secure Login System with Flask and JWT Authentication#

Flask Web Framework Basics#

• Routing: Flask uses decorators (@app.route('/path')) to map URLs to Python functions. These functions handle incoming requests and return responses.
• Request Object: Flask provides a global request object that contains incoming request data, such as form data, JSON payloads, query parameters, and headers.
• Configuration: Application settings, like secret keys or database URIs, are stored in the app.config dictionary.

JSON Web Tokens (JWT) Explained#

• Structure: Header (metadata), Payload (claims), Signature (verification).
• Claims: Standard claims (like exp for expiration, sub for subject/user ID) and custom claims (application-specific data).
• Statelessness: The server does not need to store session state for authenticated users. The token itself contains the necessary information. This is beneficial for scaling horizontally.
• Verification: The server uses the secret key (for symmetric encryption like HS256) or public key (for asymmetric encryption like RS256) to verify the token’s signature. A valid signature ensures the token hasn’t been altered since it was issued.

The Authentication Flow with JWT#

1. User Login: The user submits credentials (username, password) to the server.
2. Server Verification: The server verifies the credentials against stored user data (e.g., checking the hashed password).
3. Token Issuance: If credentials are valid, the server generates a JWT (typically an access token and often a refresh token) containing user information (like user ID) in the payload.
4. Token Transmission: The server sends the JWTs back to the client.
5. Client Storage: The client stores the tokens (e.g., in local storage, session storage, or HTTP-only cookies).
6. Accessing Protected Resources: For subsequent requests to protected endpoints, the client includes the access token, usually in the Authorization header as a Bearer token (Authorization: Bearer <token>).
7. Server Validation: The server receives the request, extracts the token, and verifies its signature and expiration time.
8. Resource Access: If the token is valid, the server processes the request and returns the requested data. If invalid, it rejects the request (e.g., returns 401 Unauthorized).
9. Token Refresh: When an access token expires, the client uses a refresh token (if issued) to request a new access token from a dedicated refresh endpoint. Refresh tokens typically have a longer lifespan than access tokens.

Security Considerations with JWT#

While statelessness is a benefit, JWTs require careful handling to ensure security.

• Secret Key Management: The secret key used to sign tokens must be kept confidential on the server. Compromising this key allows attackers to forge tokens.
• HTTPS/SSL/TLS: Tokens should always be transmitted over encrypted connections (HTTPS) to prevent interception.
• Token Storage on Client: Storing tokens in browser local storage is susceptible to Cross-Site Scripting (XSS) attacks. HTTP-only cookies offer better protection against XSS but require CSRF protection. Storing tokens securely on mobile applications also requires specific considerations.
• Expiration Times: Tokens should have appropriate expiration times. Short-lived access tokens reduce the window of opportunity if a token is compromised.
• Token Revocation (Blacklisting): Although JWTs are stateless by design, implementing a mechanism to invalidate tokens before their natural expiration (e.g., upon logout or security breach) is crucial. This is often done by maintaining a blacklist of revoked tokens on the server side.
• Payload Data: Avoid putting sensitive information directly into the token payload, as it is only encoded, not encrypted. Information suitable for the payload includes non-sensitive user identifiers or roles needed for authorization decisions.

1. Project Setup and Dependencies#

Begin by creating a project directory and installing Flask and Flask-JWT-Extended.

1
mkdir flask_jwt_auth
2
cd flask_jwt_auth
3
python -m venv venv
4
source venv/bin/activate  # On Windows use `venv\Scripts\activate`
5
pip install Flask Flask-JWT-Extended werkzeug

• Flask: The web framework.
• Flask-JWT-Extended: An extension that simplifies working with JWTs in Flask.
• werkzeug: Used here specifically for secure password hashing.

2. Basic Flask App Structure#

Create a file (e.g., app.py) and set up a minimal Flask application.

1
from flask import Flask, request, jsonify
2
from flask_jwt_extended import create_access_token, jwt_required, JWTManager, get_jwt_identity, create_refresh_token, jwt_refresh_token_required, get_raw_jwt
3
from werkzeug.security import generate_password_hash, check_password_hash
4

5
app = Flask(__name__)
6

7
# --- Configuration ---
8
# Change this in a real app!
9
app.config["JWT_SECRET_KEY"] = "your-super-secret-key-change-me"
10
# Configure JWT expiration times
11
app.config["JWT_ACCESS_TOKEN_EXPIRES"] = 3600  # 1 hour
12
app.config["JWT_REFRESH_TOKEN_EXPIRES"] = 2592000 # 30 days
13

14
jwt = JWTManager(app)
15

16
# --- User Data (In-Memory for Demonstration) ---
17
# In a real app, this would be a database
18
users = {}
19
# A simple blacklist set for token revocation
20
blacklist = set()
21

22
@jwt.token_in_blacklist_loader
23
def check_if_token_in_blacklist(decrypted_token):
24
    jti = decrypted_token['jti']
25
    return jti in blacklist
26

27
# --- Routes ---
28

29
if __name__ == "__main__":
30
    app.run(debug=True)

• Initializes the Flask app.
• Configures the JWT_SECRET_KEY. This must be a strong, randomly generated key in a production environment.
• Sets expiration times for access and refresh tokens.
• Initializes JWTManager.
• Includes a basic in-memory structure for user data and a set for token blacklisting.
• The @jwt.token_in_blacklist_loader function is registered with Flask-JWT-Extended to check if a token’s unique identifier (jti) is in the blacklist.

3. User Model/Data and Password Hashing#

For a secure system, passwords must never be stored in plain text. Use a strong hashing algorithm. werkzeug.security provides functions for this.

Modify the users structure and add functions for hashing and checking passwords.

1
# ... (previous code)
2

3
# In-memory user storage: username -> { 'password': hashed_password, 'id': user_id }
4
users = {} # Example: {'testuser': {'password': 'hashed_password_string', 'id': 1}}
5
user_id_counter = 1 # Simple ID generator for demonstration
6

7
def add_user(username, password):
8
    global user_id_counter
9
    if username in users:
10
        return False # User already exists
11
    hashed_password = generate_password_hash(password)
12
    users[username] = {'password': hashed_password, 'id': user_id_counter}
13
    user_id_counter += 1
14
    return True
15

16
def authenticate_user(username, password):
17
    user_data = users.get(username)
18
    if user_data and check_password_hash(user_data['password'], password):
19
        return user_data # Return user data including ID
20
    return None # Authentication failed
21

22
# --- Blacklist for token revocation ---
23
# (Already included in step 2)
24
blacklist = set()
25

26
@jwt.token_in_blacklist_loader
27
def check_if_token_in_blacklist(decrypted_token):
28
    jti = decrypted_token['jti']
29
    return jti in blacklist
30

31
# --- Routes ---
32
# ... (add routes below)

• generate_password_hash(): Creates a salted hash of the password.
• check_password_hash(): Verifies a password against a hash.

4. Registration Endpoint (/register)#

This endpoint handles creating new users.

1
# ... (previous code)
2

3
@app.route('/register', methods=['POST'])
4
def register():
5
    data = request.get_json()
6
    username = data.get('username')
7
    password = data.get('password')
8

9
    if not username or not password:
10
        return jsonify({"msg": "Missing username or password"}), 400
11

12
    if add_user(username, password):
13
        return jsonify({"msg": "User registered successfully"}), 201
14
    else:
15
        return jsonify({"msg": "Username already exists"}), 409

• Accepts POST requests with JSON data containing username and password.
• Checks for missing data.
• Uses the add_user function to create the user with a hashed password.
• Returns appropriate success or error responses.

5. Login Endpoint (/login)#

This endpoint authenticates the user and issues JWTs.

1
# ... (previous code)
2

3
@app.route('/login', methods=['POST'])
4
def login():
5
    data = request.get_json()
6
    username = data.get('username')
7
    password = data.get('password')
8

9
    if not username or not password:
10
        return jsonify({"msg": "Missing username or password"}), 400
11

12
    user_data = authenticate_user(username, password)
13

14
    if user_data:
15
        # Create the tokens. We pass the user's ID as the subject.
16
        # The identity is later retrieved by get_jwt_identity()
17
        access_token = create_access_token(identity=user_data['id'])
18
        refresh_token = create_refresh_token(identity=user_data['id'])
19
        return jsonify(access_token=access_token, refresh_token=refresh_token)
20
    else:
21
        return jsonify({"msg": "Bad username or password"}), 401

• Accepts POST requests with JSON credentials.
• Uses authenticate_user to verify credentials.
• If successful, create_access_token() and create_refresh_token() are used to generate tokens. The identity parameter is used to store information (here, the user ID) that can be retrieved later from the token.
• Returns the access and refresh tokens in the response body.

6. Protected Endpoint (/profile)#

This endpoint requires a valid access token to access.

1
# ... (previous code)
2

3
@app.route('/profile')
4
@jwt_required() # Decorator to protect the route
5
def profile():
6
    # Access the identity of the current user with get_jwt_identity
7
    current_user_id = get_jwt_identity()
8
    # In a real app, you would fetch user details from the database using this ID
9
    # For this example, we just return the ID
10
    return jsonify({"message": f"Welcome user with ID: {current_user_id}"})

• The @jwt_required() decorator ensures that a valid access token must be present in the request’s Authorization: Bearer <token> header.
• get_jwt_identity() retrieves the identity (user ID in this case) that was stored in the token payload during creation.

7. Token Refresh Endpoint (/refresh)#

This endpoint allows exchanging a valid refresh token for a new access token.

1
# ... (previous code)
2

3
@app.route('/refresh', methods=['POST'])
4
@jwt_refresh_token_required() # Requires a valid refresh token
5
def refresh():
6
    current_user_id = get_jwt_identity()
7
    new_access_token = create_access_token(identity=current_user_id)
8
    return jsonify(access_token=new_access_token)

• The @jwt_refresh_token_required() decorator ensures a valid refresh token is provided.
• get_jwt_identity() retrieves the user ID from the refresh token.
• A new access token is created with the same identity.

8. Logout/Token Revocation (/logout)#

This endpoint demonstrates how to invalidate a token. Flask-JWT-Extended supports blacklisting based on the token’s unique identifier (jti).

1
# ... (previous code)
2

3
@app.route('/logout', methods=['POST'])
4
@jwt_required() # Requires a valid access token to initiate logout
5
def logout():
6
    jti = get_raw_jwt()['jti'] # Get the unique identifier of the current token
7
    blacklist.add(jti) # Add the jti to the blacklist
8
    return jsonify({"msg": "Successfully logged out"}), 200
9

10
@app.route('/logout2', methods=['POST'])
11
@jwt_refresh_token_required() # Also allow revoking the refresh token separately
12
def logout2():
13
    jti = get_raw_jwt()['jti']
14
    blacklist.add(jti)
15
    return jsonify({"msg": "Refresh token revoked"}), 200

• get_raw_jwt() retrieves the full decoded token payload.
• The jti (JWT ID) claim is extracted. This is a unique identifier automatically added by Flask-JWT-Extended when JWT_BLACKLIST_ENABLED is set to True (which is the default when using token_in_blacklist_loader).
• The jti is added to the blacklist set.
• The @jwt.token_in_blacklist_loader function (defined earlier) is automatically called by Flask-JWT-Extended whenever a token is received. If the token’s jti is found in the blacklist, the request is rejected.
• Note: In a production environment, the blacklist should persist (e.g., using a database or cache like Redis) rather than being an in-memory set that resets when the server restarts.