Como usar o Flask-Login para autenticação de usuários no Flask

Autenticação é uma das primeiras camadas reais de complexidade em qualquer aplicação web. No ecossistema do Flask, a extensão Flask-Login resolve bem o básico — sessões, login persistente e controle de acesso — sem tentar ser um sistema completo de identidade.

Aqui vai um guia direto ao ponto, com o mínimo necessário para colocar isso funcionando e alguns pontos onde normalmente dá problema.

Instalação

pip install flask-login

Estrutura mínima

Você precisa de três coisas:

• Um modelo de usuário
• Um gerenciador de login (LoginManager)
• Funções de carregamento e autenticação

Modelo de Usuário

O Flask-Login não impõe ORM, mas espera alguns métodos no objeto de usuário. A forma mais simples é herdar de UserMixin.

from flask_login import UserMixin

class User(UserMixin):
    def __init__(self, id, username, password):
        self.id = id
        self.username = username
        self.password = password

Se estiver usando SQLAlchemy, basta herdar de UserMixin no seu model.

Setup do LoginManager

from flask import Flask
from flask_login import LoginManager

app = Flask(__name__)
app.secret_key = "super-secret-key"

login_manager = LoginManager()
login_manager.init_app(app)
login_manager.login_view = "login"

login_view define para onde o usuário vai ser redirecionado quando tentar acessar uma rota protegida.

User Loader

O Flask-Login precisa saber como carregar um usuário a partir do ID salvo na sessão.

users = {}  # simulação simples (troque por DB)

@login_manager.user_loader
def load_user(user_id):
    return users.get(user_id)

Se isso estiver errado, tudo quebra silenciosamente — especialmente sessões que não persistem.

Rota de Login

from flask import request, redirect, url_for
from flask_login import login_user

@app.route("/login", methods=["GET", "POST"])
def login():
    if request.method == "POST":
        username = request.form["username"]
        password = request.form["password"]

        user = next((u for u in users.values() if u.username == username), None)

        if user and user.password == password:
            login_user(user)
            return redirect(url_for("dashboard"))

    return "Login page"

Ponto crítico: isso aqui está inseguro (senha em texto plano). Em produção, use hash (werkzeug.security).

Protegendo rotas

from flask_login import login_required

@app.route("/dashboard")
@login_required
def dashboard():
    return "Área logada"

Sem login → redireciona automaticamente.

Logout

from flask_login import logout_user

@app.route("/logout")
def logout():
    logout_user()
    return "Logout feito"

Acessando o usuário atual

from flask_login import current_user

@app.route("/profile")
def profile():
    if current_user.is_authenticated:
        return f"Olá, {current_user.username}"
    return "Não autenticado"

Problemas comuns (onde geralmente quebra)

Sessão não persiste

• SECRET_KEY não definida ou mudando a cada restart
• Proxy (tipo Cloudflare) mal configurado com cookies

user_loader não funciona

• Retornando None por ID errado
• Tipo do ID inconsistente (string vs int)

Login parece funcionar, mas não mantém estado

• Cookies bloqueados
• Falta de SESSION_COOKIE_SECURE em HTTPS

Limitações reais (e quando abandonar)

O Flask-Login:

• não gerencia permissões complexas
• não cuida de OAuth
• não resolve multi-tenant
• não protege contra brute force sozinho

Se seu sistema começa a precisar de:

• roles dinâmicos
• login social
• SSO

→ você já está no território de algo como Auth0, Keycloak ou um provider próprio.

Extensões úteis no ecossistema

• Flask-Security → adiciona roles + registro + recuperação de senha
• Flask-Principal → controle de permissões mais granular

Mas cuidado: empilhar extensão vira dívida técnica rápido.

Estrutura recomendada (produção)

Separar responsabilidades evita acoplamento:

app/
  auth/
    routes.py
    forms.py
  models/
    user.py
  extensions.py
  __init__.py

E inicializar o LoginManager em extensions.py.