Flask Authentication with Flask-Login
Overview
Session-based authentication for a Flask 3 app: Flask-Login keeps the signed-in user in the session cookie, Werkzeug hashes the passwords, and Flask-WTF CSRFProtect guards every form, including logout.
Building blocks:
LoginManagercreated inextensions.py, bound withlogin_manager.init_app(app), withlogin_manager.login_view = 'auth.login'for the redirect of anonymous users (all inproject-scaffold).- A
user_loadercallback in the factory that returns the user for the id in the session:db.session.get(User, int(user_id)). - A
Usermodel that inheritsUserMixinand stores only a password hash. The model itself is inproject-scaffold(minimal) and in thesqlalchemy-devplugin (model-patterns,references/flask-login-user.md). - Routes
auth.login,auth.register,auth.logoutin one blueprint:login_user(user),logout_user(),@login_required(below). SECRET_KEYset and kept stable: it signs the session.CSRFProtectinitialised:{{ csrf_token() }}is undefined in a template without it.
Install with the SQLAlchemy pin (see setup for why):
pip install Flask Flask-Login Flask-WTF Flask-SQLAlchemy "SQLAlchemy<2.1"
Routes
# routes/auth.py
from urllib.parse import urlsplit
from flask import Blueprint, flash, redirect, render_template, request, url_for
from flask_login import current_user, login_required, login_user, logout_user
from sqlalchemy.exc import IntegrityError
from werkzeug.security import check_password_hash, generate_password_hash
from extensions import db
from models import User
auth_bp = Blueprint('auth', __name__)
NAME_MAX, EMAIL_MAX = 100, 120 # String(100) and String(120) of the User columns
MIN_PASSWORD_LENGTH = 15 # NIST SP 800-63B-4: 15 when the password is the only factor, 8 with a second factor
MAX_PASSWORD_LENGTH = 128 # NIST asks for at least 64; a cap keeps one request from hashing megabytes
# Checked when the email is unknown, so "no such user" and "wrong password" cost the same time.
DUMMY_HASH = generate_password_hash('not-a-real-password', method='scrypt')
def local_target(target):
"""Return target only when it is a path on this site; None otherwise (open-redirect guard)."""
if not target or not target.startswith('/') or target.startswith('//') or '' in target:
return None
parts = urlsplit(target)
return None if parts.scheme or parts.netloc else target
def password_problem(password):
"""Length, not composition: NIST SP 800-63B-4 bans composition rules."""
if len(password) < MIN_PASSWORD_LENGTH:
return f'Password must be at least {MIN_PASSWORD_LENGTH} characters'
if len(password) > MAX_PASSWORD_LENGTH:
return f'Password must be at most {MAX_PASSWORD_LENGTH} characters'
return None
@auth_bp.route('/register', methods=['GET', 'POST'])
def register():
if current_user.is_authenticated:
return redirect(url_for('dashboard.dashboard'))
if request.method == 'POST':
name = request.form.get('name', '').strip()
email = request.form.get('email', '').strip().lower()
password = request.form.get('password', '')
if not name or not email:
problem = 'Name and email are required'
elif len(name) > NAME_MAX or len(email) > EMAIL_MAX:
problem = f'Name must be at most {NAME_MAX} characters and email at most {EMAIL_MAX}' # the column sizes: PostgreSQL raises instead of cutting
else:
problem = password_problem(password)
if problem:
flash(problem, 'error')
return render_template('register.html')
user = User(
name=name,
email=email,
password_hash=generate_password_hash(password, method='scrypt'),
)
db.session.add(user)
try:
db.session.commit()
except IntegrityError: # the unique constraint on email decides, so two requests cannot both win
db.session.rollback()
flash('Email already registered', 'error')
return render_template('register.html')
login_user(user)
flash('Registration successful!', 'success')
return redirect(url_for('dashboard.dashboard'))
return render_template('register.html')
@auth_bp.route('/login', methods=['GET', 'POST'])
def login():
if current_user.is_authenticated:
return redirect(url_for('dashboard.dashboard'))
if request.method == 'POST':
email = request.form.get('email', '').strip().lower()
password = request.form.get('password', '')
user = db.session.scalar(db.select(User).filter_by(email=email))
password_ok = check_password_hash(user.password_hash if user else DUMMY_HASH, password)
if user is not None and password_ok:
login_user(user)
return redirect(local_target(request.args.get('next')) or url_for('dashboard.dashboard'))
flash('Wrong email or password', 'error') # one message for both cases: no account enumeration
return render_template('login.html')
@auth_bp.post('/logout')
@login_required
def logout():
logout_user()
flash('Signed out', 'success')
return redirect(url_for('auth.login'))
Why it is written this way:
- One error for login. "You haven't registered yet" for an unknown email tells an attacker which addresses have accounts. Both failures give
Wrong email or password, and the dummy hash keeps the response time the same. - Hash method named.
generate_password_hash(password, method='scrypt')is the Werkzeug 3 default; naming it fixes the choice in code. The hash is about 160 characters, soString(256)is enough.check_password_hashreads the method from the stored hash, so old hashes keep working when the method changes. - Registration on the constraint. The
unique=Truecolumn is the only check that survives two simultaneous sign-ups; theIntegrityErrorbranch turns it into the same flash message. A register form still tells a visitor that an address is taken: if that matters, accept any address and confirm by e-mail. nextstays local.@login_requiredredirects anonymous users to/login?next=/path; the login form posts back to the same URL, sonextis still there.local_targetrejectshttps://evil.example,//evil.exampleand/\evil.example.- Passwords: length, not composition. NIST SP 800-63B-4 asks for at least 15 characters when the password is the only factor (8 with a second factor), at least 64 allowed, and no composition rules ("one digit and one special character" pushes people to
Password1!). Check new passwords against a list of common and breached ones as well (a local list, or the k-anonymity range API of Have I Been Pwned); that is the rule that actually stopscorrect-horse-1!-style choices, and it needs no change to the routes except one moreelifinpassword_problem. - Field sizes.
nameandemailare checked against the column sizes before the insert: SQLite stores an over-long value, PostgreSQL raisesDataErrorand the visitor sees a 500. - Logout is
POSTwith a CSRF token. AGETlogout is triggered by any other page (<img src="/logout">). The form is inbase.html(project-scaffold).
Rate limiting and "remember me"
- Throttle
/loginand/register. Nothing above limits guesses: every request costs the attacker one scrypt check at most. Flask-Limiter (pip install Flask-Limiter) adds a per-address limit, for example@limiter.limit('5 per minute', methods=['POST'])on both views, with a shared store (Redis) once you run more than one worker. Create theLimiterinextensions.pylike the other extensions. - Sessions are not persistent here.
login_user(user)withoutremember=Truesigns the user in for the browser session only. If you add a "remember me" box (login_user(user, remember=True)), Flask-Login sets a second cookie that outlives the session; harden it like the session cookie:REMEMBER_COOKIE_SECURE = True,REMEMBER_COOKIE_HTTPONLY = True,REMEMBER_COOKIE_SAMESITE = 'Lax'inProductionConfig, and a boundedREMEMBER_COOKIE_DURATION(the default is 365 days).
Templates
{# templates/login.html #}
{% extends "base.html" %}
{% block title %}Log in{% endblock %}
{% block content %}
<h1>Log in</h1>
<form method="post">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<label>Email <input type="email" name="email" required autofocus></label>
<label>Password
<span class="password-field">
<input type="password" name="password" id="password" required>
<button type="button" data-toggle-password="password">Show</button>
</span>
</label>
<button type="submit">Log in</button>
</form>
<p><a href="{{ url_for('auth.register') }}">Create an account</a></p>
{% endblock %}
{% block scripts %}<script src="{{ url_for('static', filename='js/auth.js') }}" defer></script>{% endblock %}
The form has no action, so it posts to the URL it was loaded from and keeps ?next=.
{# templates/register.html #}
{% extends "base.html" %}
{% block title %}Register{% endblock %}
{% block content %}
<h1>Create an account</h1>
<form method="post">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<label>Name <input type="text" name="name" required autofocus maxlength="100"></label>
<label>Email <input type="email" name="email" required maxlength="120"></label>
<label>Password
<span class="password-field">
<input type="password" name="password" id="password" required minlength="15" maxlength="128">
<button type="button" data-toggle-password="password">Show</button>
</span>
</label>
<p class="hint">At least 15 characters. A passphrase of several words is fine; spaces and any characters are allowed.</p>
<button type="submit">Register</button>
</form>
<p><a href="{{ url_for('auth.login') }}">I already have an account</a></p>
{% endblock %}
{% block scripts %}<script src="{{ url_for('static', filename='js/auth.js') }}" defer></script>{% endblock %}
Show / hide password:
// static/js/auth.js
document.querySelectorAll('[data-toggle-password]').forEach(function (button) {
button.addEventListener('click', function () {
var input = document.getElementById(button.dataset.togglePassword);
var show = input.type === 'password';
input.type = show ? 'text' : 'password';
button.textContent = show ? 'Hide' : 'Show';
});
});
The navigation (current_user.is_authenticated: Log in / Register, or Dashboard / Log out) is in templates/base.html of project-scaffold.
Protecting routes
from flask_login import current_user, login_required
@clients_bp.route('/clients')
@login_required
def clients():
# current_user is the signed-in User instance
...
@login_requiredgoes under@route. The login and register views stay public.- To protect a whole app at once, use the
before_requesthook inapp-patterns(Request Hooks) with a set of public endpoints. - A route that serves JSON should answer
401, not redirect to a login page: register@login_manager.unauthorized_handlerfor those blueprints. - Every query for a signed-in user's rows is scoped to
current_user.id, and a record fetched by an id from the URL is fetched together with its owner. Forgetting it exposes other users' data. The scoped helpers (owned_by,one_or_404) are in thesqlalchemy-devplugin,query-patterns,references/owner-scoped-queries.md; the CRUD routes that use them are inapp-patterns,references/crud-views.md.
Tests
With TestingConfig (WTF_CSRF_ENABLED = False, see app-patterns, Testing):
# tests/test_auth.py
import re
import pytest
from extensions import db
from models import User
PASSWORD = 'correct horse battery' # 21 characters, no digit or symbol needed
def register(client, email='ann@example.com', password=PASSWORD, name='Ann'):
return client.post('/register', data={'name': name, 'email': email, 'password': password})
def test_register_signs_in(client):
response = register(client)
assert response.status_code == 302
assert client.get('/dashboard').status_code == 200
def test_each_client_has_its_own_user(app):
ann, ben = app.test_client(), app.test_client()
register(ann, 'ann@example.com', name='Ann')
register(ben, 'ben@example.com', name='Ben')
assert b'ann@example.com' in ann.get('/dashboard').data
assert b'ben@example.com' in ben.get('/dashboard').data
assert b'ann@example.com' not in ben.get('/dashboard').data
def test_password_rule_is_length(client):
assert register(client, password='Short1!').status_code == 200 # 7 characters: refused
assert b'at least 15' in register(client, password='Short1!').data
assert register(client, password='x' * 129).status_code == 200 # over the cap: refused
assert register(client).status_code == 302 # a plain passphrase is accepted
def test_overlong_name_or_email_is_refused_before_the_insert(app, client):
assert b'at most' in register(client, name='n' * 101).data
assert b'at most' in register(client, email='e' * 110 + '@example.com').data
with app.app_context():
assert db.session.scalar(db.select(db.func.count()).select_from(User)) == 0
def test_login_error_is_the_same_for_unknown_email_and_wrong_password(client):
register(client)
client.post('/logout')
unknown = client.post('/login', data={'email': 'nobody@example.com', 'password': 'x'})
wrong = client.post('/login', data={'email': 'ann@example.com', 'password': 'x'})
assert b'Wrong email or password' in unknown.data
assert b'Wrong email or password' in wrong.data
def test_logout_needs_post(client):
register(client)
assert client.get('/logout').status_code == 405
assert client.post('/logout').status_code == 302
assert client.get('/dashboard').status_code == 302
@pytest.mark.parametrize('target', ['https://evil.example/', '//evil.example/', '/\\evil.example/'])
def test_next_must_stay_on_the_site(client, target):
register(client)
client.post('/logout')
response = client.post('/login?next=' + target,
data={'email': 'ann@example.com', 'password': PASSWORD})
assert response.headers['Location'].endswith('/dashboard')
def test_password_is_stored_hashed(app, client):
register(client)
with app.app_context():
user = db.session.scalar(db.select(User))
assert user.password_hash != PASSWORD
assert user.password_hash.startswith('scrypt:')
def test_login_form_needs_the_csrf_token(app, client):
app.config['WTF_CSRF_ENABLED'] = True # TestingConfig switches it off
page = client.get('/login').data.decode()
token = re.search(r'name="csrf_token" value="([^"]+)"', page).group(1)
form = {'email': 'nobody@example.com', 'password': 'x'}
assert client.post('/login', data=form).status_code == 400
assert b'Wrong email or password' in client.post('/login', data={**form, 'csrf_token': token}).data
test_each_client_has_its_own_user depends on the fixture of app-patterns: it yields the app without an open app context, so each client's requests get their own g and their own Flask-Login user.
See app-patterns for the extension wiring, CSRF setup and error handlers, jinja2-patterns for template inheritance, troubleshoot for redirect loops and CSRF errors, and the sqlalchemy-dev plugin for the User model and queries.