Authenticate Users with Flask-Login

You've built a Flask app that serves pages, but now you need to protect them. Without authentication, anyone can access your admin dashboard, delete records, or view private user data. This lesson teaches you how to authenticate users with Flask-Login — the most popular session-based authentication library for Flask — so you can secure your routes with just a few lines of code.

The problem this lesson solves

Raw Flask gives you requests and responses, but zero tools for user identity. If you try to roll your own login logic, you'll end up managing session cookies, password hashes, and user loaders by hand — that's hours of work and a guaranteed source of security bugs. The pain is real: you need a simple, battle-tested way to attach a logged-in user to every request, protect private routes, and redirect anonymous visitors to a login page.

Flask-Login fixes this by providing session management, user loading, and route protection out of the box. It integrates seamlessly with any user model and database — SQLAlchemy, raw SQL, or even a JSON file for prototypes.

Core concept / mental model

Think of Flask-Login as a bouncer for your web app. When a request arrives, the bouncer checks the visitor's ID card — a signed cookie stored in their browser. If the card is valid, the bouncer looks up the user from your database and attaches that user object to flask.g or current_user. If the card is missing or expired, the bouncer treats the visitor as anonymous and can redirect them to the login gate.

Here's the mental picture:

Browser request → Flask-Login checks session cookie →
  valid? → load user by ID → attach to current_user →
  invalid? → mark as anonymous → possibly redirect to login

Core definitions you'll use daily:

• UserMixin — a mixin class that adds default properties like is_authenticated and is_active to your user model.
• login_user() — logs a user in after credentials are verified, creating the session.
• logout_user() — clears the session and logs the user out.
• @login_required — a decorator that protects a route; unauthenticated users are redirected to the login page.
• current_user — a proxy that gives you the logged-in user object (or an anonymous user if not logged in).

How it works step by step

Let's trace the flow to see exactly how authentication happens:

1. User submits credentials — your login route receives the form data (usually email/username + password).
2. Verify credentials — you check the password against the stored hash (e.g., using Werkzeug's check_password_hash). If they match, proceed.
3. Call login_user(user) — Flask-Login stores the user's ID in the session cookie, signed with your app's SECRET_KEY.
4. Subsequent requests — the LoginManager.user_loader callback is triggered; it takes the user ID from the session and returns the user object from your database.
5. Route protection — decorate routes with @login_required; if the visitor isn't authenticated, Flask-Login redirects them to your login view.

Here's the sequence in code:

# Step 1: Flask-Login sends user to the login view
@app.route('/dashboard')
@login_required
def dashboard():
    # Step 2: Only authenticated users reach this code
    return f"Hello, {current_user.username}!"

Hands-on walkthrough

Let's build a minimal Flask app with Flask-Login, step by step. You'll need flask and flask-login installed:

pip install flask flask-login

1. Set up the app and login manager

Create a file app.py:

from flask import Flask, redirect, url_for, render_template, request
from flask_login import LoginManager, UserMixin, login_user, logout_user, login_required, current_user

app = Flask(__name__)
app.secret_key = 'a-super-secret-key'  # Replace with an environment variable in production

# Initialize Flask-Login
login_manager = LoginManager()
login_manager.init_app(app)
login_manager.login_view = 'login'  # where to redirect if not authenticated

# In-memory user database for this demo
users = {
    'alice': {'password': 'pbkdf2:sha256:...'},  # store hashes, not plain text
}

# User class must inherit UserMixin
class User(UserMixin):
    def __init__(self, id):
        self.id = id

# User loader callback
@login_manager.user_loader
def load_user(user_id):
    if user_id in users:
        return User(user_id)
    return None

2. Create login and logout routes

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        username = request.form['username']
        password = request.form['password']
        user = users.get(username)
        # In a real app, use werkzeug.security.check_password_hash
        if user and password == 'secret':
            user_obj = User(username)
            login_user(user_obj)
            return redirect(url_for('dashboard'))
        else:
            return render_template('login.html', error='Invalid credentials')
    return render_template('login.html')

@app.route('/logout')
@login_required
def logout():
    logout_user()
    return redirect(url_for('login'))

@app.route('/dashboard')
@login_required
def dashboard():
    return f"Welcome, {current_user.id}!"

if __name__ == '__main__':
    app.run(debug=True)

3. Create a simple login template

templates/login.html:

<form method="post">
    <input type="text" name="username" placeholder="Username" required>
    <input type="password" name="password" placeholder="Password" required>
    <button type="submit">Log in</button>
</form>
{% if error %}<p>{{ error }}</p>{% endif %}

4. Run and test

Run python app.py, visit /dashboard — you'll be redirected to /login. Enter alice and secret, and you'll land on the dashboard. Now you're authenticating users with Flask-Login!

Expected output: After login, /dashboard shows "Welcome, alice!". If you visit /logout, you're sent back to /login.

Compare options / when to choose what

Flask-Login isn't the only auth game in town. Here's a quick comparison:

When to choose Flask-Login? If you're building a classic Flask app with server-rendered templates and want the least friction, Flask-Login is your pick. For a pure REST API, JWT might be cleaner. For a SaaS with social login, consider OAuth.

Variations to explore: - Use flask-dance for OAuth social login alongside Flask-Login. - Integrate with flask-sqlalchemy for database-backed users. - Add flask-principal for role-based access control.

Troubleshooting & edge cases

Even seasoned developers trip on these. Here are the classic pitfalls:

• Missing user_loader → Flask-Login raises AttributeError when trying to load a user. Always define the callback.
• User object doesn't inherit UserMixin → current_user.is_authenticated won't work as expected. Subclass UserMixin.
• Session expires too soon → Adjust REMEMBER_COOKIE_DURATION or use remember=True in login_user().
• Forgetting SECRET_KEY → Flask will error or cookies won't be signed. Set it.
• Password stored as plain text → Use Werkzeug's generate_password_hash and check_password_hash to hash and verify.

Why is this happening? Often, the error traceback points to user_loader. Check the session cookie is present in dev tools; clear cookies if stale.

What you learned & what's next

You now can authenticate users with Flask-Login end to end: you set up the login manager, created a user model with UserMixin, protected routes with @login_required, and handled login/logout flows. You understand the mental model of session-based auth and when to pick Flask-Login over JWT or OAuth.

Next in the track: In the upcoming lesson, you'll learn how to authorize users — controlling what each authenticated user can do. You'll combine Flask-Login with role-based permissions to build multi-user apps with admin, moderator, and regular user levels. That's the natural progression from authentication to full access control.

Practice recap: Extend your demo app by adding a templates/base.html with a navigation bar that shows "Logout" when current_user.is_authenticated. Then add a /profile route that displays the user's ID. This reinforces the core concepts and gets you ready for authorization.