1. What is Session Management?¶
In daily life, when we open a browser to visit a website, enter our account and password to log in, and even after closing the browser and reopening it, we can still maintain the logged-in state (such as the shopping cart of an e-commerce site or membership information of a video site). This is where session management is at work. In simple terms, session management is maintaining the state information of a user during one visit (or multiple visits) so that the server can identify “this is the same user”.
2. Basics of Session Management in Flask¶
Flask provides a built-in session object to handle session management, which is based on cookies (user state is encrypted and stored in the browser’s cookies). Using session requires two key steps:
2.1 Import session and Set a Secret Key¶
First, import Flask’s session module and set a secret key (SECRET_KEY) in the Flask application. The secret key is crucial for encrypting session data and must be set and not leaked (use a secure random string in production).
from flask import Flask, session, request, redirect, url_for, render_template, flash
from datetime import timedelta # For setting session expiration time
app = Flask(__name__)
# Set the secret key (required for encrypting session data)
app.secret_key = "your_secret_key_here" # Replace with a random string in production (e.g., os.urandom(24))
2.2 Session Expiration Time¶
By default, the session expires automatically when the browser is closed. If you want the session to be “persistent” (e.g., keeping the logged-in state until the user actively logs out), you can extend its expiration time using permanent_session_lifetime.
# Set session expiration to 1 day (default is a temporary session, expired when browser is closed)
app.permanent_session_lifetime = timedelta(days=1)
3. Implementing Persistent User Login State¶
The following demonstrates how to manage a user’s login state using Flask through a complete “login-verify-logout” process.
3.1 Step 1: Create a Login Page (Frontend)¶
First, create a simple login form (login.html) for users to enter their account and password:
<!-- templates/login.html -->
<!DOCTYPE html>
<html>
<head>
<title>Login</title>
</head>
<body>
<h1>User Login</h1>
<!-- Display error messages (if any) -->
{% with messages = get_flashed_messages() %}
{% if messages %}
<div style="color: red;">{{ messages[0] }}</div>
{% endif %}
{% endwith %}
<form method="post">
<div>
<label>Username:</label>
<input type="text" name="username" required>
</div>
<div>
<label>Password:</label>
<input type="password" name="password" required>
</div>
<button type="submit">Login</button>
</form>
</body>
</html>
3.2 Step 2: Write Login Verification Logic (Backend)¶
The backend needs to handle login requests, verify user information, and set session data upon successful verification. Here, we use hardcoded users for demonstration (replace with database queries in actual projects):
# Hardcoded test user (replace with database query in actual projects)
VALID_USER = {"username": "admin", "password": "admin123"}
@app.route('/login', methods=['GET', 'POST'])
def login():
# If user is already logged in, redirect to the home page (avoid repeated login)
if "username" in session:
return redirect(url_for("index"))
if request.method == "POST":
# Get form data from frontend
username = request.form.get("username")
password = request.form.get("password")
# Verify user (hardcoded example; replace with database query in production)
if username == VALID_USER["username"] and password == VALID_USER["password"]:
# Set session data (only critical info like username)
session["username"] = username
# Mark as "permanent session" (works with app.permanent_session_lifetime)
session.permanent = True
return redirect(url_for("index")) # Redirect to home after successful login
else:
flash("Incorrect username or password") # Show error message
# Render the login page
return render_template("login.html")
3.3 Step 3: Verify User Login Status (Middleware)¶
For pages requiring user login (e.g., the home page), check if username exists in the session; if not, redirect to the login page. Use a decorator to simplify the verification logic:
from functools import wraps
# Custom decorator: Check if user is logged in
def login_required(f):
@wraps(f)
def decorated_function(*args, **kwargs):
if "username" not in session:
return redirect(url_for("login")) # Redirect to login page if not logged in
return f(*args, **kwargs)
return decorated_function
# Home page route: Accessible only to logged-in users
@app.route("/")
@login_required # Use decorator to verify login status
def index():
return f"Welcome back, {session['username']}!" # Display the logged-in username
3.4 Step 4: Implement Logout Functionality¶
To log out, clear the session data and terminate the user’s login state:
@app.route("/logout")
def logout():
session.pop("username", None) # Remove username from session (no error if key doesn't exist)
return redirect(url_for("login")) # Redirect to login page after logout
4. Session Security and Optimization¶
- Security Tips:
- Keep the secret key (SECRET_KEY) confidential; do not hardcode it in the code (use environment variables in production:
os.getenv("SECRET_KEY")). -
Store only necessary information in session data (e.g., user ID) and avoid sensitive data (e.g., passwords).
-
Persistent Session Expiration:
Set the session expiration time usingapp.permanent_session_lifetime(default: 1 hour). This requiressession.permanent = Truein the login logic:
app.permanent_session_lifetime = timedelta(days=1) # Session expires after 1 day
5. Summary¶
Flask session management is implemented via the session object. The core workflow is:
1. Set a secret key (SECRET_KEY) to encrypt session data.
2. Store user state (e.g., session["username"]) upon successful login.
3. Use a decorator to check session status and ensure only logged-in users access sensitive pages.
4. Clear session data (e.g., session.pop(...)) during logout.
By following these steps, you can implement persistent user login state management, allowing users to browse the website without repeated logins.