Skip to content

8. Autenticação e autorização

Duas perguntas distintas se colocam a cada requisição:

  • Quem é o usuário? Isso é a autenticação: o usuário se identificou com um nome de usuário e uma senha, e cada requisição subsequente deve provar que vem dele;
  • Ele tem permissão para acessar esta página? Isso é a autorização: no estudo de caso, somente um usuário com o papel ADMIN gerencia os médicos e os clientes.

Como o servidor é stateless (veja o capítulo sobre escopos), a prova de identidade deve ser incluída em cada requisição. Usa-se um token chamado JWT (*JSON Web Token*): após o login, o servidor gera um token contendo a identidade do usuário e o assina com uma chave secreta. O token é armazenado em um cookie; o navegador o devolve a cada requisição; o servidor verifica a assinatura. O usuário pode ler seu token, mas não pode modificá-lo: qualquer modificação invalida a assinatura. É o mesmo princípio da sessão do [Flask] (Exemplo 20), mas com um formato padronizado (RFC 7519), compreendido por todas as linguagens de programação, e uma data de expiração embutida no token.

O [Flask] não tem um mecanismo de segurança embutido, ao contrário do [Spring] ([Spring Security]) ou do [ASP.NET Core]. Existem extensões ([Flask-Login], [Flask-JWT-Extended]...), mas o mecanismo é simples o bastante para ser escrito à mão com as ferramentas dos capítulos anteriores, o que tem a vantagem de torná-lo transparente:

  • a autenticação é tratada por uma função [before_request] (capítulo anterior), que recupera o token do cookie, o verifica e armazena o usuário autenticado em [g], o objeto da requisição;
  • a autorização é tratada por decoradores aplicados às ações ([@login_required], [@role_required("ADMIN")]), construídos como o decorador [@with_language] do Exemplo 12.

Duas bibliotecas são usadas, instaladas pelo arquivo [requirements.txt] dos exemplos: [PyJWT], que gera e verifica tokens, e [bcrypt], que calcula o hash das senhas.

8.1. Exemplo 25: Login, token, página protegida

25-jwt/
├── app.py
├── auth/
│   ├── security.py
│   ├── service.py
│   └── users.py
├── config.py
├── controllers/
│   ├── auth.py
│   └── profile.py
└── templates/
    ├── auth/
    │   └── login.html
    ├── layout.html
    └── profile/
        └── profile.html

8.1.1. Configuração: config.py e app.py

O token é assinado com uma chave secreta, que não deve ser escrita diretamente no código. Chegou a hora de separar a configuração do código:

1
2
3
4
5
6
# config.py: a configuração da aplicação, lida por app.config.from_pyfile.
# Somente as variáveis em MAIÚSCULAS são mantidas.

# a chave que assina os tokens JWT (pelo menos 32 caracteres), e seu tempo de vida
JWT_SECRET = "a-secret-key-of-at-least-32-characters-for-example-25"
JWT_DURATION_MINUTES = 60

Um arquivo de configuração do [Flask] é simplesmente um módulo [Python]: suas variáveis em maiúsculas tornam-se chaves de [app.config]. [JWT_SECRET] é a chave de assinatura do token; o padrão exige, para o algoritmo usado (HMAC-SHA256), uma chave de pelo menos 256 bits, ou 32 bytes. [JWT_DURATION_MINUTES] é a duração de um token.

# app.py: a aplicação do exemplo 25
from pathlib import Path

from flask import Blueprint, Flask

from auth import security
from auth.service import AuthService
from auth.users import UsersService
from controllers.auth import auth
from controllers.profile import profile

BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    # a configuração: o arquivo config.py, depois as variáveis de ambiente
    # que começam com FLASK_ (FLASK_JWT_SECRET substitui JWT_SECRET)
    app.config.from_pyfile("config.py")
    app.config.from_prefixed_env()
    # os serviços de autenticação
    users = UsersService()
    app.extensions["auth"] = AuthService(users, app.config["JWT_SECRET"],
                                         app.config["JWT_DURATION_MINUTES"])
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(auth)
    app.register_blueprint(profile)
    # o usuário de cada requisição, lido do token do cookie
    security.register(app)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • linha 21: leitura do arquivo de configuração, indicado por um caminho relativo à pasta da aplicação;
  • linha 22: leitura das variáveis de ambiente cujos nomes começam por [FLASK_]: [FLASK_JWT_SECRET] substitui a chave [JWT_SECRET] do arquivo. O valor de uma variável é interpretado como JSON sempre que possível ([FLASK_JWT_DURATION_MINUTES=30] resulta no inteiro 30). Em produção, a chave secreta é fornecida pelo ambiente, e o arquivo contém apenas um valor de desenvolvimento;
  • linhas 24–26: os dois serviços de autenticação, o segundo dos quais recebe a chave e a duração do token;
  • linha 32: o registro da função [before_request], que lê o token.

No [Linux] ou no [macOS], a aplicação seria iniciada com uma chave diferente da seguinte maneira:

FLASK_JWT_SECRET="another-key-of-at-least-thirty-two-characters" python app.py

e no [Windows] (PowerShell):

$env:FLASK_JWT_SECRET="another-key-of-at-least-thirty-two-characters"
python app.py

8.1.2. Usuários: auth/users.py

# auth/users.py: os usuários, em memória (o exemplo 28 e o estudo
# de caso os colocarão em um banco de dados)
from dataclasses import dataclass

import bcrypt


@dataclass(frozen=True)
class User:
    login: str
    name: str
    role: str
    password_hash: bytes


# o hash de uma senha: bcrypt, com custo 10 (2^10 rodadas);
# gensalt sorteia um "salt" aleatório, que é guardado no próprio hash
def hash_password(password: str) -> bytes:
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt(rounds=10))


class UsersService:

    def __init__(self):
        # NUNCA guardamos uma senha, apenas seu hash
        self._users = {u.login: u for u in (
            User("marie", "Marie Pélissier", "USER", hash_password("marie")),
            User("admin", "Administrator", "ADMIN", hash_password("admin")),
        )}

    def find(self, login: str) -> User | None:
        return self._users.get(login)
  • Linhas 9–13: um usuário: seu login, nome, papel e o hash de sua senha. Um servidor nunca armazena uma senha, nem mesmo criptografada: se o banco de dados fosse roubado, as senhas também seriam (e muitas pessoas usam a mesma senha em todos os lugares). Ele armazena o resultado de uma função de hash, uma função de mão única: é possível calcular o hash de uma senha, mas não é possível recuperar a senha a partir do hash. Para verificar uma senha digitada, calcula-se seu hash e o compara com o que está registrado;
  • linhas 18–19: o hash usando o algoritmo [bcrypt], projetado para senhas. Ele tem duas características distintivas. É intencionalmente lento, com uma lentidão ajustável (o parâmetro [rounds], ou custo: 2^10 ciclos de cálculo): algumas dezenas de milissegundos, imperceptíveis para um usuário, mas que tornam muito custoso para um invasor tentar bilhões de senhas. Ele usa um salt: [gensalt] gera aleatoriamente um salt, mistura-o com a senha antes do hash e o armazena dentro do próprio hash; assim, dois usuários com a mesma senha terão hashes diferentes. [bcrypt] opera sobre bytes: [encode()] converte a string em bytes ([UTF-8]). Ele considera apenas os 72 primeiros bytes de uma senha, e a versão 5 da biblioteca rejeita senhas mais longas (o estudo de caso leva isso em conta);
  • Linhas 26–28: dois usuários de teste, armazenados em memória, organizados em um dicionário construído durante o processamento ([{key: value for ...}]). O Exemplo 28 e o estudo de caso os armazenarão em um banco de dados.

8.1.3. O serviço de autenticação: auth/service.py

# auth/service.py: a verificação das senhas e dos tokens JWT
from datetime import datetime, timedelta, timezone

import bcrypt
import jwt
from flask import current_app

from auth.users import User, UsersService

# o nome do cookie que carrega o token
COOKIE = "token"


class AuthService:

    def __init__(self, users: UsersService, secret: str, duration_minutes: int):
        self._users = users
        self._secret = secret
        self.duration = timedelta(minutes=duration_minutes)

    # o usuário, ou None se o login for desconhecido ou a senha estiver errada.
    # checkpw calcula o hash da senha digitada com o salt do hash guardado,
    # depois compara os dois resultados
    def validate(self, login: str | None, password: str | None) -> User | None:
        if not login or password is None:
            return None
        user = self._users.find(login)
        if user is None or not bcrypt.checkpw(password.encode(),
                                              user.password_hash):
            return None
        return user

    # o token JWT do usuário, assinado com a chave secreta (HMAC-SHA256)
    def create_token(self, user: User) -> str:
        now = datetime.now(timezone.utc)
        # o conteúdo do token: os "claims" (declarações sobre o usuário)
        claims = {
            "sub": user.login,
            "name": user.name,
            "role": user.role,
            "iat": now,
            "exp": now + self.duration,
        }
        return jwt.encode(claims, self._secret, algorithm="HS256")

    # os claims de um token cuja assinatura e data de expiração são
    # válidas; None caso contrário (token forjado, expirado ou ilegível)
    def check(self, token: str) -> dict | None:
        try:
            return jwt.decode(token, self._secret, algorithms=["HS256"])
        except jwt.InvalidTokenError:
            return None


def auth_service() -> AuthService:
    return current_app.extensions["auth"]
  • Linhas 24–31: verificação de um nome de usuário e uma senha. [bcrypt.checkpw] calcula o hash da senha digitada usando o salt do hash armazenado e compara os dois hashes. Um nome de usuário desconhecido e uma senha incorreta produzem o mesmo resultado, [None];
  • linhas 34–44: geração do token. Seu conteúdo é um dicionário de claims sobre o usuário. Alguns têm nomes padronizados: [sub] (*subject*), o identificador do usuário; [iat] (*issued at*), a data de criação; [exp] (*expiration*), a data de expiração. Os demais são arbitrários: neste caso, o nome e o papel. [jwt.encode] gera o token e o assina usando o algoritmo [HS256] (HMAC-SHA256, uma assinatura com chave secreta compartilhada). As datas devem ser datas com fuso horário: [datetime.now(timezone.utc)];
  • Linhas 48–30: verificação do token. [jwt.decode] verifica a assinatura e a data de expiração e, em seguida, retorna as claims. Qualquer anomalia (token forjado, expirado ou malformado) lança uma exceção da família [InvalidTokenError]. O parâmetro [algorithms] especifica os algoritmos aceitos: sem ele, um atacante poderia criar um token que declara um algoritmo diferente (ou mesmo nenhum, [none]).

8.1.4. Segurança: auth/security.py

# auth/security.py: o usuário de cada requisição, e a proteção das ações
from functools import wraps

from flask import g, redirect, request, url_for

from auth.service import COOKIE, auth_service


def register(app):

    # antes de cada ação: o token do cookie -> g.user (seus claims), ou None
    @app.before_request
    def read_token():
        token = request.cookies.get(COOKIE)
        g.user = auth_service().check(token) if token else None


# um decorador: a ação é executada somente para um usuário autenticado;
# caso contrário, direto para a página de login
def login_required(action):
    @wraps(action)
    def protected_action(*args, **kwargs):
        if g.user is None:
            response = redirect(url_for("auth.form"))
            # um cookie presente, mas inválido (expirado, token forjado): nós o apagamos
            if COOKIE in request.cookies:
                response.delete_cookie(COOKIE)
            return response
        return action(*args, **kwargs)

    return protected_action
  • linhas 13–15: antes de cada ação, o token do cookie é verificado; [g.user] contém as claims de um token válido, ou [None]. Essa função não rejeita nada: ela estabelece quem é o usuário. Isso é a autenticação;
  • linhas 20–31: o decorador que exige um usuário autenticado. Para um visitante anônimo, ele não retorna a ação, mas redireciona para a página de login. Se o navegador enviou um cookie, isso significa que o token é inválido (expirado ou forjado): aproveitamos a ocasião para excluí-lo ([delete_cookie] envia um cookie vazio que já expirou).

8.1.5. Os controllers

# controllers/auth.py: login e logout
from flask import Blueprint, redirect, render_template, request, url_for

from auth.service import COOKIE, auth_service

auth = Blueprint("auth", __name__)


@auth.get("/")
def home():
    return redirect(url_for("profile.display"))


@auth.get("/login")
def form():
    return render_template("auth/login.html")


@auth.post("/login")
def login():
    login = request.form.get("login")
    user = auth_service().validate(login, request.form.get("password"))
    if user is None:
        # uma mensagem deliberadamente vaga: não dizemos se é o login ou a senha
        return render_template("auth/login.html", login=login,
                               error="Incorrect login or password.")
    response = redirect(url_for("profile.display"))
    # o token, em um cookie: o JavaScript da página não pode lê-lo
    # (httponly); ele não acompanha requisições POST vindas de outros sites
    # (samesite); ele desaparece ao mesmo tempo que o token expira (max_age)
    response.set_cookie(COOKIE, auth_service().create_token(user), httponly=True,
                        samesite="Lax", max_age=auth_service().duration)
    return response


# sair: somente POST (um simples link, colocado em outro site, não pode
# desconectar o usuário sem que ele saiba); apagamos o cookie
@auth.post("/logout")
def logout():
    response = redirect(url_for("auth.form"))
    response.delete_cookie(COOKIE)
    return response
  • linhas 20–26: o login. Se o login falha, o formulário é exibido novamente com o nome de usuário digitado e uma mensagem deliberadamente vaga: dizer “nome de usuário desconhecido” revelaria a um invasor quais nomes de usuário existem;
  • linhas 27–32: em caso de sucesso, o token é armazenado em um cookie, com um redirecionamento para a página protegida (padrão PRG). O cookie é [httponly]: o [JavaScript] da página não consegue lê-lo, o que protege o token contra a injeção de scripts (XSS); ele é [samesite="Lax"]: o navegador não o envia com uma requisição POST originada em outro site, o que protege a aplicação contra ataques CSRF (exemplo 18); sua duração ([max_age], que aceita um [timedelta]) é a do token. Em produção, com HTTPS, acrescentaríamos [secure=True]: o cookie nunca seria enviado por uma conexão não criptografada;
  • linhas 38–41: o logout exclui o cookie. É uma ação POST: um simples link para [/logout], colocado em outro site ou dentro de uma imagem, não poderia desconectar o usuário sem que ele soubesse. Observe uma limitação dos tokens: o próprio token continua válido até expirar. Quem tiver feito uma cópia dele ainda poderia usá-lo. É por isso que sua duração é limitada.
# controllers/profile.py: uma página reservada a usuários autenticados
from flask import Blueprint, g, render_template

from auth.security import login_required

profile = Blueprint("profile", __name__)


@profile.get("/profile")
@login_required
def display():
    # g.user: os claims do token, já verificados (veja auth/security.py)
    return render_template("profile/profile.html", name=g.user["name"],
                           admin=g.user["role"] == "ADMIN", claims=g.user)
  • linha 10: a página é protegida;
  • linha 13: a ação usa [g.user], tendo a garantia de que ele não é [None].

8.1.6. As views

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Login</h1>
  <form method="post" action="/login">
    <div class="mb-2">
      <label class="form-label" for="login">Login</label>
      <input class="form-control" id="login" name="login" value="{{ login or '' }}" required>
    </div>
    <div class="mb-3">
      <label class="form-label" for="password">Password</label>
      <input class="form-control" type="password" id="password" name="password" required>
    </div>
    <button class="btn btn-primary" type="submit">Log in</button>
  </form>
  {% if error %}
  <div class="alert alert-danger mt-3">{{ error }}</div>
  {% endif %}
  <p class="text-muted small mt-3">Test accounts (password = login): marie (USER), admin (ADMIN).</p>
{% endblock %}
  • linha 8: o login digitado é exibido novamente após uma falha; a expressão [login or ''] resulta em uma string vazia se [login] for [None] (ou estiver ausente).
{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Hello {{ name }}</h1>
  <p>Your role: <b>{{ "administrator" if admin else "user" }}</b>.</p>
  <p>The content of your token:</p>
  <table class="table table-sm w-auto">
    {# um laço sobre um dicionário: items() fornece os pares (chave, valor) #}
    {% for key, value in claims.items() %}
    <tr><td><code>{{ key }}</code></td><td>{{ value }}</td></tr>
    {% endfor %}
  </table>
  {# logout: um formulário POST reduzido ao seu botão #}
  <form method="post" action="/logout">
    <button class="btn btn-outline-secondary" type="submit">Log out</button>
  </form>
{% endblock %}
  • Linhas 9–11: o conteúdo do token, exibido para fins ilustrativos;
  • linhas 14–16: o logout, por meio de um formulário reduzido a um único botão.

8.1.7. Execução

Vamos solicitar a página protegida [/profile] sem estar logado:

curl -i http://localhost:5000/profile
1
2
3
4
5
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 199
Location: /login
...

Uma senha incorreta:

Image

Login bem-sucedido. Com o [curl], salvamos o cookie recebido em um arquivo:

curl -i -c token.txt -d "login=marie&password=marie" http://localhost:5000/login
1
2
3
4
5
6
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 203
Location: /profile
Set-Cookie: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtYXJpZSIsIm5hbWUiOiJNYXJpZSBQXHUwMGU5bGlzc2llciIsInJvbGUiOiJVU0VSIiwiaWF0IjoxNzkwNDMwMDE4LCJleHAiOjE3OTA0MzM2MTh9.5jkKhOHitXj6dsXqgVx85QQIovkt2YB_oygSS-68jiE; Expires=Sat, 26 Sep 2026 14:40:18 GMT; Max-Age=3600; HttpOnly; Path=/; SameSite=Lax
...

O token é composto de três partes, separadas por pontos, cada uma codificada em Base64: o cabeçalho, o conteúdo e a assinatura. As duas primeiras partes podem ser decodificadas sem nenhuma chave:

{"alg":"HS256","typ":"JWT"}
{"sub":"marie","name":"Marie Pélissier","role":"USER","iat":1790430018,"exp":1790433618}

As datas são expressas em segundos decorridos desde 1º de janeiro de 1970; o prazo de expiração é de uma hora após a criação. No navegador, a página de perfil exibe esse mesmo conteúdo:

Image

Um usuário mal-intencionado modifica seu token: ele substitui o papel ***[USER]*** no conteúdo por ***[ADMIN]***, recodifica essa parte em Base64 e mantém a assinatura original. O servidor recalcula a assinatura do conteúdo modificado, que já não corresponde:

curl -i -b "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<modified content>.5jkKhOHitXj6dsXqgVx85QQIovkt2YB_oygSS-68jiE" http://localhost:5000/profile
1
2
3
4
5
6
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 199
Location: /login
Set-Cookie: token=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=0; Path=/
...

O token forjado é rejeitado e excluído. Para gerar uma assinatura válida, seria preciso conhecer a chave secreta — daí a importância de mantê-la em segredo e de escolher uma chave longa e aleatória.

8.2. Exemplo 26: Papéis

O Exemplo 26 acrescenta uma página de administração, restrita ao papel ADMIN. Apenas os arquivos novos ou modificados são exibidos.

8.2.1. Um decorador com parâmetro: auth/security.py

# auth/security.py: o usuário de cada requisição, e a proteção das ações
from functools import wraps

from flask import abort, g, redirect, request, url_for

from auth.service import COOKIE, auth_service


def register(app):

    # antes de cada ação: o token do cookie -> g.user (seus claims), ou None
    @app.before_request
    def read_token():
        token = request.cookies.get(COOKIE)
        g.user = auth_service().check(token) if token else None


# um decorador: a ação é executada somente para um usuário autenticado;
# caso contrário, direto para a página de login
def login_required(action):
    @wraps(action)
    def protected_action(*args, **kwargs):
        if g.user is None:
            response = redirect(url_for("auth.form"))
            # um cookie presente, mas inválido (expirado, token forjado): nós o apagamos
            if COOKIE in request.cookies:
                response.delete_cookie(COOKIE)
            return response
        return action(*args, **kwargs)

    return protected_action


# um decorador COM PARÂMETRO: @role_required("ADMIN"). role_required("ADMIN") retorna
# o decorador propriamente dito, que recebe a ação. Ele é usado DEPOIS (abaixo de)
# @login_required: o usuário está então necessariamente autenticado
def role_required(role: str):
    def decorator(action):
        @wraps(action)
        def protected_action(*args, **kwargs):
            if g.user["role"] != role:
                abort(403)  # acesso negado
            return action(*args, **kwargs)

        return protected_action

    return decorator
  • Linhas 37–47: [@role_required("ADMIN")] tem um parâmetro. A expressão que segue [@] é avaliada primeiro: [role_required("ADMIN")] retorna uma função, [decorator], que é o decorador propriamente dito, aplicado à ação. Temos, portanto, três funções aninhadas: [role_required] recebe o papel, [decorator] recebe a ação e [protected_action] recebe os parâmetros da requisição e executa o trabalho. Cada uma tem acesso às variáveis das funções que a contêm ([role], [action]);
  • Linha 42: um usuário autenticado que não tem o papel exigido recebe um erro 403 (*Forbidden*). Isso é bastante diferente de um usuário anônimo, que é redirecionado para a página de login: fazer login de nada serviria, pois o usuário já está autenticado.

8.2.2. O controller: controllers/admin.py

# controllers/admin.py: uma página reservada ao papel ADMIN
from flask import Blueprint, g, render_template

from auth.security import login_required, role_required

admin = Blueprint("admin", __name__)


# os decoradores se aplicam de baixo para cima: role_required envolve a ação,
# depois login_required envolve o conjunto. Na hora da execução, é portanto
# login_required que verifica PRIMEIRO se o usuário está autenticado
@admin.get("/admin")
@login_required
@role_required("ADMIN")
def display():
    return render_template("admin/admin.html", name=g.user["name"])
  • Linhas 12–14: os decoradores são aplicados de baixo para cima: [role_required] envolve a ação e, em seguida, [login_required] envolve toda a estrutura. Em tempo de execução, a ordem se inverte: o invólucro externo, [login_required], é executado primeiro. Assim, quando [role_required] é executado, o usuário está necessariamente autenticado, e [g.user] não é [None].

8.2.3. A página de erro: app.py

# app.py: a aplicação do exemplo 26
from pathlib import Path

from flask import Blueprint, Flask, render_template

from auth import security
from auth.service import AuthService
from auth.users import UsersService
from controllers.admin import admin
from controllers.auth import auth
from controllers.profile import profile

BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    # a configuração: o arquivo config.py, depois as variáveis de ambiente
    # que começam com FLASK_ (FLASK_JWT_SECRET substitui JWT_SECRET)
    app.config.from_pyfile("config.py")
    app.config.from_prefixed_env()
    # os serviços de autenticação
    users = UsersService()
    app.extensions["auth"] = AuthService(users, app.config["JWT_SECRET"],
                                         app.config["JWT_DURATION_MINUTES"])
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(auth)
    app.register_blueprint(profile)
    app.register_blueprint(admin)
    # o usuário de cada requisição, lido do token do cookie
    security.register(app)

    # papel insuficiente: abort(403) (veja auth/security.py) -> nossa página de erro
    @app.errorhandler(403)
    def access_denied(e):
        return render_template("error.html", code=403), 403

    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Linhas 37–39: um tratador de erro registrado para um código específico — o erro 403 — exibe nossa página.
1
2
3
4
5
6
7
8
9
{% extends "layout.html" %}

{% block content %}
  <div class="alert alert-danger">
    <h1 class="h4">Error {{ code }}</h1>
    <p class="mb-0">{{ "Access denied: this page is reserved for administrators." if code == 403 else "An error occurred." }}</p>
  </div>
  <p><a href="/profile">Back to the profile</a></p>
{% endblock %}

8.2.4. Execução

Marie, com o papel USER, segue o link para a página de administração:

Image

O administrador, por sua vez, tem acesso a ela:

Image

Com o [curl]: um usuário com o papel USER, seguido de um visitante anônimo:

curl -i -b token.txt http://localhost:5000/admin
curl -i http://localhost:5000/admin
HTTP/1.1 403 FORBIDDEN
Content-Type: text/html; charset=utf-8
Content-Length: 492
...
  <div class="alert alert-danger">
    <h1 class="h4">Error 403</h1>
    <p class="mb-0">Access denied: this page is reserved for administrators.</p>
  </div>
...
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 199
Location: /login

Proteger as ações uma a uma tem uma falha: um único esquecimento abre uma página para todos. O estudo de caso inverterá essa lógica: todas as ações são protegidas por padrão, e um decorador [@public] designa as raras exceções (a página de login, o cadastro).

8.3. Exemplo 27: CAPTCHA e limite de tentativas

Um formulário de login é um alvo: um programa pode tentar milhares de senhas por minuto (ataque de força bruta). Duas proteções se complementam:

  • um CAPTCHA (*Completely Automated Public Turing test to tell Computers and Humans Apart*): uma imagem contendo um código distorcido, fácil de ler para um ser humano, mas difícil para um programa;
  • um limite de tentativas: após três tentativas malsucedidas, o endereço IP do cliente é bloqueado por um minuto.

O Exemplo 27 se baseia no Exemplo 25 (sem a página de administração) e acrescenta essas duas medidas de segurança.

8.3.1. A imagem do CAPTCHA: auth/captcha_drawing.py

# auth/captcha_drawing.py: o desenho de um captcha, uma imagem SVG (texto XML)
# construída à mão
import math
import secrets

WIDTH = 150
HEIGHT = 50

# secrets: um gerador de números aleatórios "criptográfico", imprevisível
# (ao contrário do módulo random, cuja sequência poderia ser adivinhada)
_random = secrets.SystemRandom()

# A "fonte": cada caractere é uma lista de traços, cada traço uma
# sequência de pontos (x, y) em uma grade 4 x 6 (y para baixo).
# Caracteres fáceis demais de confundir entre si: excluídos (0 O, 1 I L).
FONT = {
    "A": [[0, 6, 2, 0, 4, 6], [0.8, 3.8, 3.2, 3.8]],
    "B": [[0, 0, 0, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3], [0, 0, 3, 0, 4, 1, 4, 2, 3, 3]],
    "C": [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5]],
    "D": [[0, 0, 0, 6, 2.5, 6, 4, 4.5, 4, 1.5, 2.5, 0, 0, 0]],
    "E": [[4, 0, 0, 0, 0, 6, 4, 6], [0, 3, 3, 3]],
    "F": [[4, 0, 0, 0, 0, 6], [0, 3, 3, 3]],
    "G": [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 3.5, 2.5, 3.5]],
    "H": [[0, 0, 0, 6], [4, 0, 4, 6], [0, 3, 4, 3]],
    "J": [[4, 0, 4, 5, 3, 6, 1, 6, 0, 5]],
    "K": [[0, 0, 0, 6], [4, 0, 0, 3.5], [1.3, 2.6, 4, 6]],
    "M": [[0, 6, 0, 0, 2, 3.5, 4, 0, 4, 6]],
    "N": [[0, 6, 0, 0, 4, 6, 4, 0]],
    "P": [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3]],
    "Q": [[1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5, 0, 1, 1, 0], [2.5, 4.5, 4, 6.3]],
    "R": [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3], [2, 3, 4, 6]],
    "S": [[4, 1, 3, 0, 1, 0, 0, 1, 0, 2, 1, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
    "T": [[0, 0, 4, 0], [2, 0, 2, 6]],
    "U": [[0, 0, 0, 5, 1, 6, 3, 6, 4, 5, 4, 0]],
    "V": [[0, 0, 2, 6, 4, 0]],
    "W": [[0, 0, 1, 6, 2, 2.5, 3, 6, 4, 0]],
    "X": [[0, 0, 4, 6], [4, 0, 0, 6]],
    "Y": [[0, 0, 2, 3, 4, 0], [2, 3, 2, 6]],
    "Z": [[0, 0, 4, 0, 0, 6, 4, 6]],
    "2": [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 0, 6, 4, 6]],
    "3": [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1.5, 3], [3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
    "4": [[3, 6, 3, 0, 0, 4, 4, 4]],
    "5": [[4, 0, 0, 0, 0, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
    "6": [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3]],
    "7": [[0, 0, 4, 0, 1.5, 6]],
    "8": [[1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1, 3, 0, 4, 0, 5, 1, 6, 3, 6, 4, 5,
           4, 4, 3, 3]],
    "9": [[4, 3, 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5]],
}

ALPHABET = "".join(FONT)

# algumas cores escuras, facilmente legíveis sobre o fundo claro
COLORS = ["#1f4e79", "#7b2d26", "#2e6b30", "#5b2c83", "#8a5a00", "#23395d", "#9c2a5b"]


def random_text(length: int) -> str:
    return "".join(_random.choice(ALPHABET) for _ in range(length))


def random(minimum: float, maximum: float) -> float:
    return _random.uniform(minimum, maximum)


def color() -> str:
    return _random.choice(COLORS)


def svg(text: str) -> str:
    parts = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{WIDTH}" height="{HEIGHT}" '
             f'viewBox="0 0 {WIDTH} {HEIGHT}">',
             '<rect width="100%" height="100%" fill="#f5f7fa"/>']

    # os caracteres: cada um ampliado, inclinado, deslocado, e cada ponto
    # levemente movido ao acaso
    step = (WIDTH - 20) / len(text)
    for i, character in enumerate(text):
        scale = random(4.6, 5.6)  # tamanho de uma unidade da grade, em pixels
        angle = random(-0.35, 0.35)  # rotação, em radianos (cerca de ±20°)
        cx = 10 + step * (i + 0.5) + random(-3, 3)  # centro do caractere
        cy = HEIGHT / 2 + random(-4, 4)
        d = []
        for stroke in FONT[character]:
            for k in range(0, len(stroke), 2):
                # ponto da grade, centralizado em (2, 3), distorcido, girado, posicionado
                x = (stroke[k] - 2 + random(-0.2, 0.2)) * scale
                y = (stroke[k + 1] - 3 + random(-0.2, 0.2)) * scale
                px = cx + x * math.cos(angle) - y * math.sin(angle)
                py = cy + x * math.sin(angle) + y * math.cos(angle)
                d.append(f"{'M' if k == 0 else 'L'}{px:.1f} {py:.1f}")
        parts.append(f'<path d="{" ".join(d)}" fill="none" stroke="{color()}" '
                     f'stroke-width="{random(2.2, 3):.1f}" stroke-linecap="round" '
                     f'stroke-linejoin="round"/>')

    # 3 traços de embaralhamento: curvas que cruzam a imagem
    for _ in range(3):
        parts.append(
            f'<path d="M{random(0, 20):.1f} {random(5, 45):.1f} '
            f'C{random(30, 60):.1f} {random(0, 50):.1f} {random(90, 120):.1f} {random(0, 50):.1f} '
            f'{random(130, 150):.1f} {random(5, 45):.1f}" fill="none" stroke="{color()}" '
            f'stroke-width="1.3"/>')
    parts.append("</svg>")
    return "".join(parts)

A imagem está no formato SVG (*Scalable Vector Graphics*): um gráfico vetorial descrito em XML — ou seja, texto — que o servidor gera sem uma biblioteca gráfica e que o navegador exibe diretamente na página.

  • Linha 11: o módulo [random] do [Python] produz sequências de números previsíveis (quem conhece alguns valores pode adivinhar os seguintes): ele é adequado para simulações, não para segurança. O módulo [secrets] fornece um gerador criptográfico imprevisível;
  • Linhas 16–48: uma “fonte” minimalista: cada caractere é uma lista de traços, e cada traço é uma lista de coordenadas [x, y] em uma grade de 4 × 6. Os caracteres facilmente confundidos ([0] e [O], [1], [I] e [L]) são excluídos;
  • linha 51: ["".join(FONT)] combina as chaves do dicionário: os caracteres disponíveis;
  • linhas 57–58: texto aleatório. [_] é o nome convencional de uma variável não utilizada;
  • linhas 69–103: o desenho. Cada caractere é ampliado, girado e deslocado aleatoriamente, e cada um de seus pontos é ligeiramente deslocado; cada linha se torna um elemento [<path>] do SVG ([M]: deslocamento, [L]: linha). Três curvas ([C]: curva de Bézier) atravessam a imagem para confundir os programas de reconhecimento. Os formatos [:.1f] escrevem os números com uma casa decimal.

8.3.2. O serviço de CAPTCHA: auth/captcha.py

# auth/captcha.py: os captchas pendentes, mantidos em memória pelo servidor
import secrets
from dataclasses import dataclass
from datetime import datetime, timedelta
from threading import Lock

from flask import current_app

from auth import captcha_drawing

LIFETIME = timedelta(minutes=10)


# um captcha: seu identificador, e sua imagem (SVG)
@dataclass(frozen=True)
class Captcha:
    id: str
    svg: str


class CaptchaService:

    def __init__(self):
        # identificador -> (resposta esperada, data de expiração)
        self._pending: dict[str, tuple[str, datetime]] = {}
        self._lock = Lock()

    def generate(self) -> Captcha:
        text = captcha_drawing.random_text(5)
        id = secrets.token_urlsafe(16)  # um identificador aleatório, impossível de adivinhar
        with self._lock:
            self._pending[id] = (text, datetime.now() + LIFETIME)
        return Captcha(id, captcha_drawing.svg(text))

    # o captcha é CONSUMIDO em todos os casos: uma imagem é usada uma única vez
    def check(self, id: str | None, answer: str | None) -> bool:
        with self._lock:
            expected = self._pending.pop(id, None) if id else None
        if expected is None or answer is None:
            return False
        text, expires = expected
        return expires > datetime.now() and text.lower() == answer.strip().lower()


def captcha_service() -> CaptchaService:
    return current_app.extensions["captchas"]
  • linhas 28–33: um novo CAPTCHA: texto aleatório, um identificador aleatório e impossível de adivinhar ([secrets.token_urlsafe]) e a imagem. Para cada identificador, o servidor armazena a resposta esperada e uma data de expiração. A página recebe apenas o identificador e a imagem: a resposta nunca sai do servidor;
  • linhas 36–42: verificação. [pop] remove a entrada do dicionário e a retorna: o CAPTCHA é consumido em todos os casos, com sucesso ou não. Sem isso, um programa poderia tentar todas as respostas possíveis sobre a mesma imagem. A comparação ignora maiúsculas e minúsculas e os espaços ao redor da entrada.

Este serviço mantém dados na memória do servidor: isso é um desvio do princípio de servidor sem estado (veja o capítulo sobre escopos), aceitável para dados de curta duração. Com vários servidores, os dados precisariam ser armazenados em um sistema de armazenamento compartilhado (um banco de dados, [Redis]...). Observe também que os captchas que nunca foram usados não são excluídos: o estudo de caso limpa regularmente os captchas expirados.

8.3.3. Limite de tentativas: auth/limiter.py

# auth/limiter.py: conta as falhas de login de cada endereço IP
import math
from datetime import datetime, timedelta
from threading import Lock

from flask import current_app

MAX_FAILURES = 3
BLOCK_DURATION = timedelta(minutes=1)


class Counter:
    def __init__(self):
        self.failures = 0
        self.blocked_until = datetime.min


class LimiterService:

    def __init__(self):
        self._counters: dict[str, Counter] = {}
        # várias requisições simultâneas, um único acesso por vez
        self._lock = Lock()

    # o número de segundos restantes de bloqueio (0: não bloqueado)
    def blocked_seconds(self, ip: str) -> int:
        with self._lock:
            counter = self._counters.get(ip)
            if counter is None:
                return 0
            remaining = (counter.blocked_until - datetime.now()).total_seconds()
            return max(0, math.ceil(remaining))

    def failure(self, ip: str):
        with self._lock:
            counter = self._counters.setdefault(ip, Counter())
            counter.failures += 1
            if counter.failures >= MAX_FAILURES:
                counter.blocked_until = datetime.now() + BLOCK_DURATION
                counter.failures = 0  # após o bloqueio, recomeça-se do zero

    def success(self, ip: str):
        with self._lock:
            self._counters.pop(ip, None)


def limiter_service() -> LimiterService:
    return current_app.extensions["limiter"]
  • linhas 12–15: para cada endereço IP, um número de tentativas fracassadas e uma data de fim de bloqueio ([datetime.min], a data mais antiga possível, significa “não bloqueado”);
  • linhas 26–32: o número de segundos restantes do bloqueio, arredondado para o inteiro superior ([math.ceil]);
  • linhas 34–40: mais uma falha. [setdefault] redefine o contador do endereço, criando-o se não existir. Na terceira falha, o endereço é bloqueado por um minuto e o contador volta a zero;
  • linhas 42–44: uma conexão bem-sucedida zera o contador.

8.3.4. O controller: controllers/auth.py

# controllers/auth.py: login (com captcha e limitação de tentativas) e logout
from flask import Blueprint, redirect, render_template, request, url_for

from auth.captcha import captcha_service
from auth.limiter import limiter_service
from auth.service import COOKIE, auth_service

auth = Blueprint("auth", __name__)


@auth.get("/")
def home():
    return redirect(url_for("profile.display"))


@auth.get("/login")
def form():
    return login_page()


@auth.post("/login")
def login():
    login = request.form.get("login")
    # o endereço IP do cliente
    ip = request.remote_addr

    # 1. um endereço bloqueado nem sequer é ouvido
    seconds = limiter_service().blocked_seconds(ip)
    if seconds > 0:
        return login_page(login, f"Too many attempts: try again in {seconds} s.")
    # 2. primeiro o captcha (barato), depois a senha (bcrypt, caro)
    if not captcha_service().check(request.form.get("captchaId"), request.form.get("captcha")):
        limiter_service().failure(ip)
        return login_page(login, "The image code is incorrect.")
    user = auth_service().validate(login, request.form.get("password"))
    if user is None:
        limiter_service().failure(ip)
        return login_page(login, "Incorrect login or password.")
    limiter_service().success(ip)
    response = redirect(url_for("profile.display"))
    response.set_cookie(COOKIE, auth_service().create_token(user), httponly=True,
                        samesite="Lax", max_age=auth_service().duration)
    return response


@auth.post("/logout")
def logout():
    response = redirect(url_for("auth.form"))
    response.delete_cookie(COOKIE)
    return response


# cada exibição do formulário constrói um NOVO captcha
def login_page(login: str | None = None, error: str | None = None):
    return render_template("auth/login.html", login=login, error=error,
                           captcha=captcha_service().generate())
  • linha 25: o endereço do cliente, IP;
  • linhas 28–30: um endereço bloqueado nem sequer é atendido;
  • linhas 32–34: o CAPTCHA é verificado antes da senha: verificá-lo quase não custa nada, ao passo que o [bcrypt] é intencionalmente lento. Um programa que digite um CAPTCHA errado não acionaria, portanto, o [bcrypt]. Toda falha, seja do CAPTCHA ou da senha, é contabilizada;
  • linha 39: um login bem-sucedido zera a contagem de falhas;
  • linhas 54–56: cada vez que o formulário é exibido, um novo CAPTCHA é gerado, mesmo após uma falha.

8.3.5. A view: templates/auth/login.html

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Login</h1>
  <form method="post" action="/login">
    <div class="mb-2">
      <label class="form-label" for="login">Login</label>
      <input class="form-control" id="login" name="login" value="{{ login or '' }}" required>
    </div>
    <div class="mb-2">
      <label class="form-label" for="password">Password</label>
      <input class="form-control" type="password" id="password" name="password" required>
    </div>
    <div class="mb-3">
      <label class="form-label" for="captcha">Copy the code of the image</label>
      {# a imagem SVG, construída pelo servidor: inserida sem escape (safe) #}
      <div class="mb-1">{{ captcha.svg | safe }}</div>
      {# o identificador do captcha viaja em um campo oculto; a resposta fica no servidor #}
      <input type="hidden" name="captchaId" value="{{ captcha.id }}">
      <input class="form-control" id="captcha" name="captcha" autocomplete="off" required>
    </div>
    <button class="btn btn-primary" type="submit">Log in</button>
  </form>
  {% if error %}
  <div class="alert alert-danger mt-3">{{ error }}</div>
  {% endif %}
  <p class="text-muted small mt-3">Test accounts (password = login): marie (USER), admin (ADMIN).</p>
{% endblock %}
  • linha 17: a imagem SVG é inserida como está na página, com o filtro [safe] (exemplo 14). Isso é legítimo: esse HTML foi gerado pelo servidor e não contém nenhuma entrada do usuário;
  • linha 19: o ID do captcha, em um campo oculto;
  • linha 20: o navegador não sugere entradas anteriores para esse campo.

8.3.6. Execução

Image

Um código copiado incorretamente:

Image

Na terceira tentativa fracassada, o endereço é bloqueado:

Image

Com o [curl], quatro tentativas com um ID de CAPTCHA inventado:

curl -d "login=marie&password=marie&captchaId=abc&captcha=XXXXX" http://localhost:5000/login
1
2
3
4
  <div class="alert alert-danger mt-3">The image code is incorrect.</div>
  <div class="alert alert-danger mt-3">The image code is incorrect.</div>
  <div class="alert alert-danger mt-3">The image code is incorrect.</div>
  <div class="alert alert-danger mt-3">Too many attempts: try again in 60 s.</div>

Mesmo com a senha correta, a quarta tentativa é rejeitada sem verificação.