Flask-Login — Session-based Authentication

Setting Up the User Model

To integrate Flask-Login, your User model must satisfy specific requirements so the session manager knows how to handle it. Flask-Login provides a UserMixin class which implements the four core properties required for authentication: is_authenticated, is_active, is_anonymous, and get_id(). By inheriting from this mixin, you avoid manually defining these properties, ensuring compatibility with the library's internal checks. The get_id method is particularly crucial, as it provides a unique string representation of your user, which the extension stores inside the browser's session cookie. When a request arrives, Flask-Login uses this ID to reload the user object from your database. If you do not provide this, the library cannot distinguish between different authenticated sessions or persist the user state between individual page loads, effectively breaking the authentication flow entirely.

from flask_login import UserMixin
from . import db

# UserMixin provides default implementations for session-related properties
class User(UserMixin, db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    password_hash = db.Column(db.String(128))

    def get_id(self): 
        return str(self.id) # Must return a string for the session cookie

The LoginManager Configuration

The LoginManager acts as the central hub for the authentication process, holding the configuration for your application's session management. You must initialize it by binding it to your Flask application instance. The most critical component here is the user_loader callback, which you register using the @login_manager.user_loader decorator. This function is called by Flask-Login on every request to turn the stored session ID back into a full User object from your database. Without this callback, the extension wouldn't know how to query your specific backend to verify if a user still exists. You must also define a login_view, which tells the manager where to redirect unauthenticated users when they attempt to access protected routes. This decoupling ensures your security logic remains centralized, making the application significantly easier to audit and maintain as it grows.

from flask_login import LoginManager

login_manager = LoginManager()

# Define the callback to reload user from database
@login_manager.user_loader
def load_user(user_id):
    # Re-fetch the user object based on the ID in the session
    return User.query.get(int(user_id))

# Point to your login route for unauthorized access
login_manager.login_view = 'auth.login'

Handling Authentication States

Once the manager is configured, you interact with the authentication state using the login_user and logout_user functions. When a user provides valid credentials, login_user creates a secure session, effectively signing the user into the application. Under the hood, this function sets a cookie on the client's browser containing the user's ID, which is cryptographically signed to prevent tampering. When you call logout_user, the session is cleared, and the cookie is invalidated, effectively removing the user's identity from the server's context. This mechanism is stateless from the perspective of the server's memory, as the identification data resides on the client side. By leveraging this, your application remains lightweight and scalable, as you do not need to keep massive session tables in server memory, relying instead on the signed cookie to prove identity.

from flask_login import login_user, logout_user
from flask import request

@app.route('/login', methods=['POST'])
def login():
    user = User.query.filter_by(username=request.form['username']).first()
    if user and verify_password(user, request.form['password']):
        login_user(user) # Creates the session cookie
        return 'Logged in!'
    return 'Invalid credentials'

Protecting Routes with Decorators

The @login_required decorator is the primary mechanism for enforcing access control across your application. When you place this decorator above a route function, Flask-Login intercepts the request before it executes your code. It checks the session cookie for a valid, recognized user ID. If no user is found, the extension automatically redirects the visitor to the URL defined in your login_view configuration. This is much cleaner than writing repetitive 'if current_user.is_authenticated' logic inside every single route. By using the decorator, you shift the responsibility of access control to a declarative, centralized system, which drastically reduces the risk of human error. It enforces a standard security posture for all your protected endpoints, ensuring that sensitive logic is never executed unless a valid, active session is confirmed by the application's authentication manager.

from flask_login import login_required, current_user

@app.route('/dashboard')
@login_required # Only allows access to signed-in users
def dashboard():
    # current_user is available once the decorator passes
    return f'Welcome back, {current_user.username}'

Accessing User Identity Globally

After a successful login, Flask-Login makes the currently authenticated user available via the 'current_user' proxy object throughout your request context. This object is highly convenient because it provides access to your user's model attributes, such as their username or email, directly in your templates and backend code without needing to query the database repeatedly. If a user is not logged in, current_user will be an AnonymousUser object, which safely allows you to call properties without raising errors, as long as you account for its anonymous state. This proxy is extremely efficient because it caches the database query for the duration of the request. By using current_user, you maintain a consistent way to reference user-specific data across your entire application, simplifying code and making it much more readable compared to manual session lookups.

from flask_login import current_user
from flask import render_template

@app.route('/profile')
@login_required
def profile():
    # Accessing database-backed attributes via current_user
    return render_template('profile.html', user=current_user)
    # In HTML, you can use: {{ current_user.username }}

Interview questions

All Flask interview questions →

Check yourself

Take the full Flask quiz →