Skip to content

8. Autenticação e autorização

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

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

A prova de identidade deve acompanhar cada requisição. O [Django] tem uma aplicação de autenticação completa, [django.contrib.auth]: um modelo [User] (uma tabela do banco de dados), um middleware que guarda o usuário logado em [request.user], views de login e logout, permissões, grupos e a interface de administração que os gerencia. Ela guarda o usuário logado em sua sessão (veja o capítulo sobre escopos), que é a solução mais simples para uma aplicação web. O estudo de caso, em todas as suas versões ([ASP.NET Core MVC], [Spring MVC], [NestJS], [Flask], [Laravel], [Symfony]), usa em vez disso um token JWT (JSON Web Token), que usaremos aqui: após o login, o servidor gera um token contendo a identidade do usuário e o assina com uma chave secreta (é o princípio do cookie assinado do Exemplo 23). O token é guardado em um cookie; o navegador o reenvia 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 formato é padronizado (RFC 7519), compreendido por todas as linguagens de programação, e o token inclui sua data de expiração. Mais importante, o servidor não precisa guardar nada: qualquer servidor que conheça a chave pode verificar o token.

Os usuários do estudo de caso são os de sua própria tabela, [users], e não os de [django.contrib.auth]; os próprios tokens não têm lugar em [django.contrib.auth]. Implementaremos, portanto, a autenticação por conta própria, com as ferramentas que já conhecemos, o que tem a vantagem de deixar tudo transparente:

  • um middleware (Exemplo 03) determina, a cada requisição, quem é o usuário com base no token de seu cookie e o inclui na requisição ([request.user], Exemplo 12). O restante da aplicação vê apenas esse resultado;
  • decoradores (exemplo 08) protegem as views: [@login_required], [@role_required("ADMIN")];
  • as senhas são verificadas com as funções de hash do [Django] ([django.contrib.auth.hashers], que podem ser usadas sem o restante da aplicação [auth]);
  • as negações de acesso são exceções [PermissionDenied], convertidas em uma página de erro por uma view [handler403] (Exemplo 24);
  • as tentativas de login são limitadas usando o cache do [Django] (Exemplo 27).

A criação e a verificação dos tokens ficam a cargo da biblioteca [PyJWT], a mais usada em [Python], instalada pelo arquivo de exemplo [requirements.txt] (ela é importada com o nome [jwt]). (Existem bibliotecas de token JWT para o [Django], como [djangorestframework-simplejwt], concebidas para APIs; para uma aplicação web, bastam algumas linhas, que ilustram melhor o mecanismo.)

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

25-jwt/
├── accounts/
│   ├── __init__.py
│   └── views.py
├── config/
│   ├── settings.py
│   ├── urls.py
│   └── ...
├── security/
│   ├── __init__.py
│   ├── auth.py
│   ├── decorators.py
│   ├── middleware.py
│   └── users.py
├── templates/
│   ├── auth/
│   │   └── login.html
│   ├── profile/
│   │   └── profile.html
│   └── layout.html
└── manage.py

8.1.1. Configuração: config/settings.py

O token é assinado com uma chave secreta, que não deve ficar fixa no código de uma aplicação em produção. É hora de separar de verdade a configuração do código:

# config/settings.py: a configuração do exemplo 25

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-jr8u&rl2ff+bpg(h18&^u2dtu^qtulf9yoy!e&la+nt_z-vb*8"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "security",
    "accounts",
]

MIDDLEWARE = [
    "django.middleware.csrf.CsrfViewMiddleware",
    # AUTENTICAÇÃO: a cada requisição, o usuário é encontrado a partir do
    # token JWT de seu cookie (veja security/middleware.py)
    "security.middleware.Authentication",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
    },
]

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR.parent / "common" / "static",
]

# nossas próprias configurações: a chave que assina os tokens JWT (pelo menos 32 caracteres) e
# sua duração. os.environ.get: a variável de ambiente de mesmo nome se ela
# existir (em produção), o valor escrito aqui caso contrário (em desenvolvimento)
JWT_SECRET = os.environ.get("JWT_SECRET", "a-secret-key-of-at-least-32-characters-for-example-25")
JWT_DURATION_MINUTES = int(os.environ.get("JWT_DURATION_MINUTES", "60"))
  • linhas 21–26: dois middlewares: a proteção anti-CSRF (Exemplo 18), seguida do nosso middleware de autenticação;
  • linhas 43–44: duas configurações específicas da aplicação (Exemplo 06): a chave que assina os tokens e a duração deles, em minutos. [os.environ.get("NAME", default)] atribui o valor da variável de ambiente a [NAME] se ela existir; caso contrário, usa o valor padrão. Durante o desenvolvimento, o valor escrito no arquivo é suficiente; em produção, a chave real é fornecida por uma variável de ambiente, que tem precedência. Uma variável de ambiente é sempre uma string: [int] converte a duração em um inteiro.

O padrão exige, para o algoritmo utilizado (HMAC-SHA256), uma chave de pelo menos 256 bits, ou 32 bytes: [PyJWT] emite um aviso para uma chave mais curta. No [Linux] ou no [macOS], a aplicação seria iniciada com uma chave diferente da seguinte forma:

JWT_SECRET="another-key-of-at-least-thirty-two-characters" python manage.py runserver

e no [Windows] ([PowerShell]):

$env:JWT_SECRET="another-key-of-at-least-thirty-two-characters"
python manage.py runserver

A chave secreta do [Django] em si, [SECRET_KEY], exigiria o mesmo tratamento; o estudo de caso lê todos os seus segredos de um arquivo chamado [.env], ou do ambiente.

8.1.2. Usuários: security/users.py

# security/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, field


@dataclass(frozen=True)
class User:
    login: str
    name: str
    # o papel: USER ou ADMIN
    role: str
    # o HASH da senha (vazio para um usuário lido de um token)
    password_hash: str = ""
    # o conteúdo do token que autenticou o usuário; field(default_factory=dict):
    # um dicionário vazio NOVO para cada objeto
    claims: dict = field(default_factory=dict)


# NUNCA guardamos uma senha, apenas seu hash, calculado uma vez por todas
# pela função make_password do Django (algoritmo PBKDF2-SHA256, 1.500.000
# iterações, um salt aleatório):
# python -c "from django.conf import settings; settings.configure();
#            from django.contrib.auth.hashers import make_password; print(make_password('marie'))"
USERS = {
    "marie": ("Marie Pélissier", "USER",
              "pbkdf2_sha256$1500000$pjnFn2tL1G4bu5rVFTv6sZ$Y6v+fj3dC+Y0LZYJGxeE1OOi9beaZVuMVm6R6tljEwI="),
    "admin": ("Administrator", "ADMIN",
              "pbkdf2_sha256$1500000$UTT2hXVaLIEAuGHPFxgnv9$D9+Owt9lDG14VrvArR3n0GGQXWjY9Sg8cgFwip4+yx4="),
}


def find(login: str) -> User | None:
    if login not in USERS:
        return None
    # o "desempacotamento" de uma tupla: seus três elementos em três variáveis
    name, role, password_hash = USERS[login]
    return User(login, name, role, password_hash)
  • linhas 7–17: um usuário: o login, o nome, o papel, o hash da senha e o conteúdo do token que autenticou o usuário (vazio para um usuário lido da lista de usuários). Os dois últimos atributos têm um valor padrão. Para um dicionário, esse valor não pode ser escrito como [claims: dict = {}]: esse dicionário seria criado uma única vez e compartilhado por todos os objetos. [field(default_factory=dict)] instrui [@dataclass] a chamar [dict()] para cada novo objeto;
  • linhas 20–24: um servidor nunca guarda uma senha, nem mesmo criptografada: se o banco de dados fosse roubado, as senhas seriam roubadas junto (e muitas pessoas usam a mesma senha em todo lugar). Ele guarda o resultado de uma função de hash, uma função unidirecional: é possível calcular o hash de uma senha, mas não é possível recuperar uma senha a partir de seu hash. Para verificar uma senha digitada, calcula-se seu hash e compara-se com o que está guardado no banco de dados;
  • linhas 25–30: dois usuários de teste, fixados no programa (o Exemplo 28 e o estudo de caso os colocarão em um banco de dados): para cada login, o nome, o papel e o hash da senha. O hash foi calculado de uma vez por todas pela função [make_password] do [Django] (o comando é fornecido em um comentário), com seu algoritmo padrão, PBKDF2-SHA256. O hash guardado tem quatro partes, separadas por [$]: o algoritmo ([pbkdf2_sha256]), o número de iterações, o salt e, por fim, o resultado. Um bom algoritmo de hash de senhas tem duas características. É intencionalmente lento, com um nível de lentidão ajustável: o PBKDF2 aplica a função SHA-256 1.500.000 vezes, o que leva algumas centenas de milissegundos — imperceptível para um usuário, mas que torna muito custoso para um invasor tentar bilhões de senhas; o [Django] aumenta esse número a cada versão para acompanhar o poder de processamento (sua aplicação [auth] atualiza então os hashes guardados durante os logins); hashes mais antigos continuam verificáveis, pois incluem seu número de iterações. E usa salt: um salt gerado aleatoriamente é misturado à senha antes do hash e guardado no próprio hash; assim, dois usuários com a mesma senha terão hashes diferentes. O [Django] também pode usar [Argon2] e [bcrypt] (configurando [PASSWORD_HASHERS]); o estudo de caso, cujo banco de dados contém hashes [bcrypt], usa diretamente a biblioteca [bcrypt];
  • linhas 33–38: o usuário de um login, ou [None]. [not in] verifica a ausência de uma chave; a atribuição [name, role, password_hash = ...] desempacota uma tupla: cada variável recebe o elemento correspondente.

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

# security/auth.py: a verificação das senhas e dos tokens JWT

import time

import jwt
from django.conf import settings
from django.contrib.auth.hashers import check_password

from . import users
from .users import User

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


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


# o token JWT do usuário, assinado com a chave secreta (HMAC-SHA256)
def create_token(user: User) -> str:
    now = int(time.time())
    # 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 + settings.JWT_DURATION_MINUTES * 60,
    }
    return jwt.encode(claims, settings.JWT_SECRET, algorithm="HS256")


# o usuário descrito por um token cuja assinatura e data de expiração são
# válidas; None caso contrário (token forjado, expirado ou ilegível)
def verify(token: str) -> User | None:
    try:
        # decode verifica a assinatura E a data de expiração (claim exp)
        claims = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"])
    except jwt.InvalidTokenError:
        return None
    return User(claims["sub"], claims["name"], claims["role"], claims=claims)
  • Linha 5: a biblioteca [PyJWT];
  • linha 7: a função [check_password] do [Django];
  • linha 13: o nome do cookie que transporta o token;
  • linhas 19–25: verificação de um nome de usuário e de uma senha. [check_password] lê o algoritmo, o número de iterações e o salt do hash guardado, calcula o hash da senha digitada com eles e compara os dois resultados (em tempo constante, veja o exemplo 23). Um nome de usuário desconhecido e uma senha incorreta produzem o mesmo resultado, [None];
  • linhas 29–39: 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. As datas são expressas em segundos decorridos desde 1º de janeiro de 1970 ([time.time()] retorna esse número, incluindo as casas decimais, que [int] omite). Os demais campos são opcionais: aqui, o nome e o papel. [jwt.encode] gera o token e o assina com o algoritmo [HS256] (HMAC-SHA256, uma assinatura com chave secreta compartilhada);
  • linhas 44–50: verificação do token. [jwt.decode] verifica a assinatura e a data de expiração e depois retorna as asserções. Qualquer anomalia (token forjado, expirado ou malformado) lança uma exceção da classe [jwt.InvalidTokenError] ou de uma de suas subclasses, que o bloco [except] intercepta. O parâmetro [algorithms] especifica a lista de algoritmos aceitos: um token que declare um algoritmo diferente (ou nenhum, [none]) seria rejeitado. O token válido se torna um [User], sem hash, junto com suas claims (parâmetro chamado [claims]).

8.1.4. O middleware de autenticação: security/middleware.py

# security/middleware.py: AUTENTICAÇÃO: a cada requisição, quem é o usuário?

from django.shortcuts import redirect

from . import auth


class Authentication:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # por padrão, o visitante é anônimo
        request.user = None
        token = request.COOKIES.get(auth.COOKIE)
        if token is not None:
            user = auth.verify(token)
            if user is None:
                # um token inválido (expirado, forjado): direto para /login, e nós
                # excluímos o cookie
                response = redirect("login")
                response.delete_cookie(auth.COOKIE)
                return response
            request.user = user
        return self.get_response(request)

A cada requisição, antes da view:

  • linha 14: por padrão, o visitante é anônimo: [request.user] é igual a [None];
  • linhas 15–17: se a requisição contém o cookie do token, o token é verificado;
  • linhas 18–23: um token inválido (expirado ou forjado): o middleware responde por conta própria, sem invocar o restante do processamento, redirecionando para a página de login, e aproveita para apagar o cookie: [delete_cookie] adiciona à resposta um cookie vazio e já expirado;
  • linha 24: um token válido: o usuário que ele identifica é incluído na requisição. O usuário não é procurado na lista de usuários: o token basta, pois é assinado.

O middleware não nega o acesso: ele determina quem é o usuário, ou determina que o usuário é anônimo. Isso é autenticação. As negações ficam a cargo do controle de acesso.

8.1.5. Controle de acesso: security/decorators.py

# security/decorators.py: o controle de acesso das views

from functools import wraps

from django.shortcuts import redirect


# @login_required: a view só é executada para um usuário autenticado; um
# visitante anônimo é redirecionado à página de login
def login_required(view):
    @wraps(view)
    def wrapper(request, *args, **kwargs):
        if request.user is None:
            return redirect("login")
        return view(request, *args, **kwargs)
    return wrapper

O decorador [@login_required] envolve uma view (Exemplo 08): se o usuário é anônimo, ele responde redirecionando para a página de login sem chamar a view; caso contrário, chama a view. [django.contrib.auth] fornece um decorador com o mesmo nome e a mesma função, [@login_required], que se baseia em seu próprio [request.user].

8.1.6. Views: accounts/views.py

# accounts/views.py: login, logout e uma página reservada a usuários
# autenticados

from django.conf import settings
from django.shortcuts import redirect, render
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from security import auth
from security.decorators import login_required


@require_GET
def home(request):
    return redirect("profile")


# GET: o formulário; POST: o login (o token anti-CSRF foi verificado por
# CsrfViewMiddleware)
@require_http_methods(["GET", "POST"])
def login(request):
    if request.method == "GET":
        return render(request, "auth/login.html")
    login = request.POST.get("login", "")
    user = auth.validate(login, request.POST.get("password", ""))
    if user is None:
        # uma mensagem deliberadamente vaga: não dizemos se é o login ou a senha
        return render(request, "auth/login.html",
                      {"login": login, "error": "Incorrect login or password."})
    # o token, em um cookie: o JavaScript da página não consegue lê-lo
    # (httponly); ele não acompanha as requisições POST vindas de outros sites
    # (samesite); ele desaparece ao mesmo tempo que o token expira (max_age)
    response = redirect("profile")
    response.set_cookie(auth.COOKIE, auth.create_token(user),
                        max_age=settings.JWT_DURATION_MINUTES * 60, httponly=True, samesite="Lax")
    return response


# logout: somente por POST (um simples link, colocado em outro site, não pode
# desconectar o usuário sem que ele saiba); excluímos o cookie
@require_POST
def logout(request):
    response = redirect("login")
    response.delete_cookie(auth.COOKIE)
    return response


# request.user: o usuário autenticado, encontrado pelo middleware
@require_GET
@login_required
def profile(request):
    return render(request, "profile/profile.html", {"user": request.user})
  • linhas 19–22: o formulário de login, escrito à mão no template, é protegido contra requisições forjadas pelo middleware [CsrfViewMiddleware], como todos os formulários POST (Exemplo 18);
  • linhas 23–28: o processo de 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 32–35: em caso de sucesso, o token é guardado em um cookie e o usuário é redirecionado para a página protegida (esquema PRG). O cookie é [httponly]: o [JavaScript] da página não consegue lê-lo, o que protege o token contra injeção de script (XSS); ele é [SameSite=Lax]: o navegador não o envia com uma requisição POST originada de outro site, o que protege a aplicação contra ataques CSRF; sua duração ([max_age], em segundos) é a mesma do token. Em produção, com HTTPS, acrescentaríamos [secure=True]: o cookie nunca seria enviado por uma conexão não criptografada;
  • linhas 40–44: o logout apaga o cookie ([delete_cookie]). É uma view de POST, protegida pelo token anti-CSRF: um simples link para [/logout], colocado em outro site ou dentro de uma imagem, não consegue desconectar o usuário sem que ele saiba. 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;
  • linhas 48–51: a página protegida. O decorador [@login_required] garante que [request.user] não seja [None].

8.1.7. Templates

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Login</h1>
  <form method="post" action="{% url 'login' %}">
    {% csrf_token %}
    <div class="mb-2">
      <label class="form-label" for="login">Login</label>
      <input class="form-control" id="login" name="login" value="{{ login }}" 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 6: o token anti-CSRF do formulário;
  • linha 9: o login digitado é exibido novamente após uma falha (uma variável ausente é exibida como uma string vazia).
{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Hello {{ user.name }}</h1>
  <p>Your role: <b>{% if user.role == "ADMIN" %}administrator{% else %}user{% endif %}</b>.</p>
  <p>The content of your token:</p>
  <table class="table table-sm w-auto">
    {% for key, value in user.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="{% url 'logout' %}">
    {% csrf_token %}
    <button class="btn btn-outline-secondary" type="submit">Log out</button>
  </form>
{% endblock %}
  • linhas 8–10: o conteúdo do token, exibido para fins ilustrativos. [items] percorre os pares (chave, valor) do dicionário (Exemplo 18);
  • linhas 13–16: o logout, por meio de um formulário reduzido a um único botão.

8.1.8. Execução

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

curl -i http://localhost:8000/profile
1
2
3
HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: /login

Uma senha incorreta:

Image

Login bem-sucedido. Com [curl], é preciso primeiro solicitar o formulário para obter o token anti-CSRF e seu cookie (exemplo 18) e depois enviar o formulário mantendo o cookie recebido:

curl -c token.txt -b token.txt http://localhost:8000/login
curl -i -c token.txt -b token.txt -d "csrfmiddlewaretoken=...&login=marie&password=marie" http://localhost:8000/login
1
2
3
4
HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: /profile
Set-Cookie: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtYXJpZSIsIm5hbWUiOiJNYXJpZSBQXHUwMGU5bGlzc2llciIsInJvbGUiOiJVU0VSIiwiaWF0IjoxNzkwNTMwOTM5LCJleHAiOjE3OTA1MzQ1Mzl9.eJQdDTFEYVlAzHENW7esgY82dUbjsj5dN6jW-Dy6Lfo; expires=Sun, 27 Sep 2026 18:42:19 GMT; HttpOnly; Max-Age=3600; 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":1790530939,"exp":1790534539}

(O [é] é escrito em sua forma escapada, JSON, [\u00e9].) O tempo de expiração é de uma hora (3.600 segundos) após a criação. No navegador, a página de perfil exibe esse mesmo conteúdo:

Image

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

curl -i -b "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<modified content>.eJQdDTFEYVlAzHENW7esgY82dUbjsj5dN6jW-Dy6Lfo" http://localhost:8000/profile
1
2
3
4
HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: /login
Set-Cookie: token=""; expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=0; Path=/

O token forjado é rejeitado e apagado (o valor vazio e a data expirada instruem o navegador a apagar o cookie). 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. Papéis: security/users.py

# security/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, field


@dataclass(frozen=True)
class User:
    login: str
    name: str
    # o papel: USER ou ADMIN
    role: str
    # o HASH da senha (vazio para um usuário lido de um token)
    password_hash: str = ""
    # o conteúdo do token que autenticou o usuário; field(default_factory=dict):
    # um dicionário vazio NOVO para cada objeto
    claims: dict = field(default_factory=dict)

    # a HIERARQUIA dos papéis: um administrador também tem os direitos de um usuário
    def has_role(self, role: str) -> bool:
        return role in HIERARCHY.get(self.role, set())

    # para os templates, que não podem chamar um método com parâmetro
    @property
    def is_admin(self) -> bool:
        return self.has_role("ADMIN")


# cada papel e o conjunto de papéis que ele possui ({...}: um conjunto)
HIERARCHY = {
    "ADMIN": {"ADMIN", "USER"},
    "USER": {"USER"},
}


# NUNCA guardamos uma senha, apenas seu hash, calculado uma vez por todas
# pela função make_password do Django (algoritmo PBKDF2-SHA256, 1.500.000
# iterações, um salt aleatório):
# python -c "from django.conf import settings; settings.configure();
#            from django.contrib.auth.hashers import make_password; print(make_password('marie'))"
USERS = {
    "marie": ("Marie Pélissier", "USER",
              "pbkdf2_sha256$1500000$pjnFn2tL1G4bu5rVFTv6sZ$Y6v+fj3dC+Y0LZYJGxeE1OOi9beaZVuMVm6R6tljEwI="),
    "admin": ("Administrator", "ADMIN",
              "pbkdf2_sha256$1500000$UTT2hXVaLIEAuGHPFxgnv9$D9+Owt9lDG14VrvArR3n0GGQXWjY9Sg8cgFwip4+yx4="),
}


def find(login: str) -> User | None:
    if login not in USERS:
        return None
    # o "desempacotamento" de uma tupla: seus três elementos em três variáveis
    name, role, password_hash = USERS[login]
    return User(login, name, role, password_hash)
  • linhas 20–21: o método [has_role] determina se o usuário tem um papel, com base na hierarquia de papéis;
  • linhas 24–26: uma propriedade (exemplo 14), para os templates: o DTL não consegue chamar um método com parâmetro ([has_role("ADMIN")]), mas consegue ler uma propriedade ([user.is_admin]);
  • linhas 30–33: a hierarquia de papéis: para cada papel, o conjunto ([set], delimitado por chaves) dos papéis que ele possui. O papel [ADMIN] inclui o papel [USER]: um administrador tem, portanto, todos os direitos de um usuário sem precisar receber os dois papéis. O método [has_role] pode usar [HIERARCHY], embora ele seja definido mais adiante no arquivo: o nome só é procurado no momento da chamada, quando o módulo inteiro já foi carregado.

8.2.2. Controle de acesso: security/decorators.py

# security/decorators.py: o controle de acesso das views

from functools import wraps

from django.core.exceptions import PermissionDenied
from django.shortcuts import redirect


# @login_required: a view só é executada para um usuário autenticado; um
# visitante anônimo é redirecionado à página de login
def login_required(view):
    @wraps(view)
    def wrapper(request, *args, **kwargs):
        if request.user is None:
            return redirect("login")
        return view(request, *args, **kwargs)
    return wrapper


# @role_required("ADMIN"): um decorador PARAMETRIZADO (veja o exemplo 08). A view é
# executada somente se o usuário autenticado tiver o papel solicitado; caso contrário, a
# exceção PermissionDenied produz uma resposta 403 (veja security/errors.py)
def role_required(role):
    def decorator(view):
        @wraps(view)
        @login_required
        def wrapper(request, *args, **kwargs):
            if not request.user.has_role(role):
                raise PermissionDenied(f"role {role} required")
            return view(request, *args, **kwargs)
        return wrapper
    return decorator
  • linhas 23–32: um decorador parametrizado (exemplo 08), [@role_required("ADMIN")]. O wrapper é, por sua vez, envolvido por [@login_required]: um visitante anônimo é primeiro enviado à página de login; um usuário autenticado que não tem o papel exigido dispara a exceção [PermissionDenied] (exemplo 24), que resultará em um erro 403 (Forbidden).

A diferença entre os dois cenários de negação é significativa: um visitante anônimo que solicita uma página protegida é redirecionado para a página de login; um usuário autenticado que não tem o papel exigido recebe um erro 403 — fazer login não adiantaria nada, pois ele já está autenticado.

8.2.3. Negação de acesso: security/errors.py e config/urls.py

1
2
3
4
5
6
7
8
# security/errors.py: a resposta dada a um usuário AUTENTICADO que solicita uma
# página que lhe é proibida (veja handler403 em config/urls.py)

from django.shortcuts import render


def access_denied(request, exception):
    return render(request, "errors/403.html", status=403)
# config/urls.py: a tabela de roteamento principal

from django.urls import path

from accounts import views
from security.errors import access_denied

urlpatterns = [
    path("", views.home),
    path("login", views.login, name="login"),
    path("logout", views.logout, name="logout"),
    path("profile", views.profile, name="profile"),
    path("admin", views.admin, name="admin"),
]

# a view dos erros 403 (exceção PermissionDenied)
handler403 = access_denied

A view [access_denied] é a view de erro 403 da aplicação (variável [handler403], exemplo 24): [Django] a chama para qualquer exceção [PermissionDenied], tanto no modo de depuração quanto em produção. A página [templates/errors/403.html] é uma página de erro padrão com um link de volta para o perfil. Sem essa view, o usuário veria a página 403 simples do [Django] (“403 Forbidden”).

8.2.4. Views: accounts/views.py

# accounts/views.py: login, logout e páginas reservadas a usuários autenticados
# autenticados

from django.conf import settings
from django.shortcuts import redirect, render
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from security import auth
from security.decorators import login_required, role_required


@require_GET
def home(request):
    return redirect("profile")


# GET: o formulário; POST: o login (o token anti-CSRF foi verificado por
# CsrfViewMiddleware)
@require_http_methods(["GET", "POST"])
def login(request):
    if request.method == "GET":
        return render(request, "auth/login.html")
    login = request.POST.get("login", "")
    user = auth.validate(login, request.POST.get("password", ""))
    if user is None:
        # uma mensagem deliberadamente vaga: não dizemos se é o login ou a senha
        return render(request, "auth/login.html",
                      {"login": login, "error": "Incorrect login or password."})
    # o token, em um cookie: o JavaScript da página não consegue lê-lo
    # (httponly); ele não acompanha as requisições POST vindas de outros sites
    # (samesite); ele desaparece ao mesmo tempo que o token expira (max_age)
    response = redirect("profile")
    response.set_cookie(auth.COOKIE, auth.create_token(user),
                        max_age=settings.JWT_DURATION_MINUTES * 60, httponly=True, samesite="Lax")
    return response


# logout: somente por POST (um simples link, colocado em outro site, não pode
# desconectar o usuário sem que ele saiba); excluímos o cookie
@require_POST
def logout(request):
    response = redirect("login")
    response.delete_cookie(auth.COOKIE)
    return response


# request.user: o usuário autenticado, encontrado pelo middleware
@require_GET
@login_required
def profile(request):
    return render(request, "profile/profile.html", {"user": request.user})


# uma página reservada ao papel ADMIN
@require_GET
@role_required("ADMIN")
def admin(request):
    return render(request, "admin/admin.html", {"name": request.user.name})
  • linhas 55–58: a página de administração, protegida pelo decorador [@role_required("ADMIN")]. A própria view não faz nenhuma verificação.

Para regras mais granulares que um papel (“um usuário só pode editar as suas próprias consultas”), a própria view faz a validação e lança [PermissionDenied] quando necessário. O estudo de caso traz exemplos disso.

8.2.5. A view de perfil

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Hello {{ user.name }}</h1>
  <p>Your role: <b>{% if user.role == "ADMIN" %}administrator{% else %}user{% endif %}</b>.</p>
  {# is_admin: o usuário tem o papel ADMIN? #}
  {% if user.is_admin %}
    <p><a href="{% url 'admin' %}">The administration area</a></p>
  {% else %}
    <p><a href="{% url 'admin' %}">The administration area</a> (which is forbidden to you)</p>
  {% endif %}
  <p>The content of your token:</p>
  <table class="table table-sm w-auto">
    {% for key, value in user.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="{% url 'logout' %}">
    {% csrf_token %}
    <button class="btn btn-outline-secondary" type="submit">Log out</button>
  </form>
{% endblock %}
  • linhas 7–11: a propriedade [is_admin] permite adaptar a página ao papel. Isso evita exibir um link que levaria a um erro em uma aplicação real (aqui, o link é mantido para Marie, a título de experimento); porém, isso é apenas uma comodidade: a proteção de fato é feita pela view.

8.2.6. 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 [curl]: um usuário com o papel USER (logado como no Exemplo 25, com os cookies guardados no arquivo [token.txt]), seguido de um visitante anônimo:

curl -i -b token.txt http://localhost:8000/admin
curl -i http://localhost:8000/admin
HTTP/1.1 403 Forbidden
Content-Type: text/html; charset=utf-8
...
  <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
Location: /login

Proteger as views uma a uma tem uma falha: se uma for esquecida, a página se torna acessível a todos. O estudo de caso inverterá essa lógica: todas as páginas de URL são protegidas por padrão por um middleware de controle de acesso, e apenas algumas páginas de URL (a página de login, a página de cadastro) são isentas.

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 medidas de proteção 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 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 e acrescenta essas duas medidas de segurança:

27-captcha/
├── accounts/
│   └── views.py
├── config/
│   └── settings.py
├── security/
│   ├── auth.py
│   ├── captcha_drawing.py
│   ├── captchas.py
│   ├── decorators.py
│   ├── limiter.py
│   ├── middleware.py
│   └── users.py
├── templates/
│   └── auth/
│       └── login.html
└── ...

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

# security/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

# A "fonte": cada caractere é uma lista de traços, cada traço uma sequência de
# pontos x, y em uma grade de 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]],
}

# algumas cores escuras, fáceis de ler sobre o fundo claro
COLORS = ["#1f4e79", "#7b2d26", "#2e6b30", "#5b2c83", "#8a5a00", "#23395d", "#9c2a5b"]

# um gerador "criptográfico", imprevisível (diferente do módulo random,
# cuja sequência poderia ser adivinhada)
_random = secrets.SystemRandom()


def random_text(length: int) -> str:
    alphabet = list(FONT)
    return "".join(secrets.choice(alphabet) for _ in range(length))


# um número de ponto flutuante, aleatório, entre mínimo e máximo
def random(minimum: float, maximum: float) -> float:
    return _random.uniform(minimum, maximum)


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


def svg(text: str) -> str:
    w, h = WIDTH, HEIGHT
    parts = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{w}" height="{h}" viewBox="0 0 {w} {h}">',
             '<rect width="100%" height="100%" fill="#f5f7fa"/>']
    # os caracteres: cada um ampliado, inclinado, deslocado, e cada ponto levemente
    # movido ao acaso
    step = (w - 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 = h / 2 + random(-4, 4)
        for stroke in FONT[character]:
            d = []
            # range(0, n, 2): 0, 2, 4... um ponto = dois números
            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} '
                     f'{random(0, 50):.1f} {random(130, 150):.1f} {random(5, 45):.1f}" '
                     f'fill="none" stroke="{color()}" 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, em texto — que o servidor gera sem biblioteca gráfica e que o navegador exibe diretamente na página. Este módulo é [Python] puro, sem nada específico do [Django]: é a implementação em [Python] das classes das versões [Laravel] e [Symfony] deste curso.

  • linhas 13–46: uma “fonte” minimalista: cada caractere é uma lista de traços, e cada traço é uma lista de coordenadas x e y em uma grade de 4 × 6. Os caracteres facilmente confundidos ([0] e [O], [1], [I] e [L]) são excluídos;
  • linhas 53–58: texto aleatório, sorteado entre os caracteres da fonte ([list(FONT)]: a lista das chaves do dicionário). O módulo [random] do [Python] produz sequências de números previsíveis (quem conhece alguns valores pode adivinhar os seguintes): serve para simulações, não para segurança. O módulo [secrets] é um gerador criptográfico imprevisível: [secrets.choice] sorteia um elemento de uma lista, e [secrets.SystemRandom] fornece as funções de [random] ([uniform]: um número de ponto flutuante entre dois limites) usando esse gerador. [for _ in range(length)] repete [length] vezes; o nome [_] indica uma variável que não é usada;
  • linhas 70–102: o desenho. Cada caractere é ampliado, girado e deslocado aleatoriamente, e cada um de seus pontos é ligeiramente deslocado; cada traço se torna um elemento [<path>] do SVG ([M]: deslocamento, [L]: linha). Três curvas ([C]: curva de Bézier) atravessam a imagem para atrapalhar os programas de reconhecimento. Em uma f-string, [{px:.1f}] escreve um número com uma casa decimal; é possível incluir uma expressão condicional ([{'M' if k == 0 else 'L'}]). O módulo [math] fornece [cos] e [sin]. As partes do SVG são montadas por [join].

8.3.2. O serviço de CAPTCHA: security/captchas.py

# security/captchas.py: os captchas pendentes, mantidos pelo servidor, no cache

import secrets
from dataclasses import dataclass

from django.core.cache import cache

from . import captcha_drawing

# a duração de vida de um captcha, em segundos
LIFETIME = 600


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


def generate() -> Captcha:
    text = captcha_drawing.random_text(5)
    # um identificador aleatório, impossível de adivinhar: 12 bytes sorteados por um
    # gerador criptográfico, escritos em hexadecimal
    id = secrets.token_hex(12)
    # a resposta esperada, no cache, por 10 minutos: o cache a esquecerá
    # sozinho depois
    cache.set(f"captcha.{id}", text, LIFETIME)
    return Captcha(id, captcha_drawing.svg(text))


# o captcha é CONSUMIDO em todos os casos: uma imagem só é usada uma vez
def verify(id: str, entered: str) -> bool:
    if not id or not entered:
        return False
    # get retorna o valor, ou None; delete remove a resposta do cache, seja ela
    # certa ou não
    expected = cache.get(f"captcha.{id}")
    cache.delete(f"captcha.{id}")
    if expected is None:
        return False    # identificador desconhecido, ou captcha expirado
    # casefold: a string em minúsculas, para uma comparação que ignora maiúsculas e minúsculas
    return expected.casefold() == entered.strip().casefold()
  • linha 6: o cache do [Django]: um repositório de pares chave→valor compartilhado por todos os módulos. Onde ele guarda esses valores depende da configuração [CACHES] (veja abaixo);
  • linhas 21–29: um novo CAPTCHA: uma string de texto aleatória, um identificador aleatório impossível de adivinhar ([secrets.token_hex(12)]: 12 bytes aleatórios, escritos em hexadecimal, ou seja, 24 caracteres) e a imagem. Para cada identificador, o servidor guarda a resposta esperada no cache por dez minutos: o terceiro parâmetro de [cache.set] é a duração, em segundos. Passado esse tempo, o cache a descarta automaticamente. A página recebe apenas o identificador e a imagem: a resposta nunca sai do servidor;
  • linhas 33–43: a verificação. A resposta esperada é lida ([cache.get] retorna [None] para uma chave ausente) e depois removida do cache ([cache.delete]): 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 ([casefold] converte uma string para minúsculas, tratando corretamente todos os alfabetos) e os espaços ao redor da entrada ([strip]).

8.3.3. Limite de tentativas: security/limiter.py

# security/limiter.py: a limitação das tentativas de login, por endereço IP

import time

from django.conf import settings
from django.core.cache import cache


# as falhas de um cliente são contadas em uma JANELA de tempo fixa: no máximo
# LOGIN_MAX_FAILURES falhas por janela de LOGIN_WINDOW_SECONDS segundos
class Limiter:
    def __init__(self, ip: str):
        self.key = f"login.{ip}"

    # os segundos a esperar se o cliente estiver bloqueado, 0 caso contrário
    def wait(self) -> int:
        state = cache.get(self.key)
        if state is None or state["failures"] < settings.LOGIN_MAX_FAILURES:
            return 0
        return max(1, int(state["end"] - time.time()))

    # uma falha a mais
    def failure(self) -> None:
        state = cache.get(self.key)
        if state is None:
            # uma nova janela começa
            state = {"failures": 0, "end": time.time() + settings.LOGIN_WINDOW_SECONDS}
        state["failures"] += 1
        # a chave desaparece do cache no final da janela (timeout, em segundos)
        cache.set(self.key, state, timeout=max(1, int(state["end"] - time.time())))

    # um login bem-sucedido zera as falhas
    def clear(self) -> None:
        cache.delete(self.key)

O limitador conta as tentativas malsucedidas de um cliente dentro de uma janela de tempo fixa: no máximo três tentativas malsucedidas por janela de 60 segundos, contados a partir da primeira tentativa malsucedida. Cada cliente é identificado por seu endereço IP.

  • linha 13: a chave de cache, específica do cliente: [login.127.0.0.1];
  • linhas 16–20: o número de segundos a esperar se o cliente está bloqueado (o número de falhas atingiu o máximo), 0 caso contrário. O estado guardado no cache é um dicionário: o número de falhas e o instante de término da janela;
  • linhas 23–30: mais uma falha. Se não há estado no cache, uma nova janela começa. O estado é reescrito com uma duração que expira no fim da janela: o cache o esquecerá então automaticamente, e o cliente recomeçará do zero;
  • linhas 33–34: uma conexão bem-sucedida apaga as falhas.

Este limitador, escrito para fins ilustrativos, tem uma fraqueza: duas falhas simultâneas poderiam ler o mesmo estado e contá-lo como apenas uma. O cache do [Django] oferece operações atômicas ([cache.add], que só grava se a chave não existe, e [cache.incr], que incrementa um número), que são usadas na versão do estudo de caso. Também há bibliotecas prontas ([django-ratelimit], [django-axes]).

8.3.4. Configuração: config/settings.py

# config/settings.py: a configuração do exemplo 27

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-y=#3-i_9nrm%&a&_%_v^ajq460=!u*ry3uit-nj9_thr&v3ev)"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "security",
    "accounts",
]

MIDDLEWARE = [
    "django.middleware.csrf.CsrfViewMiddleware",
    # AUTENTICAÇÃO: a cada requisição, o usuário é encontrado a partir do
    # token JWT de seu cookie (veja security/middleware.py)
    "security.middleware.Authentication",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
    },
]

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR.parent / "common" / "static",
]

# nossas próprias configurações: a chave que assina os tokens JWT (pelo menos 32 caracteres) e
# sua duração. os.environ.get: a variável de ambiente de mesmo nome se ela
# existir (em produção), o valor escrito aqui caso contrário (em desenvolvimento)
JWT_SECRET = os.environ.get("JWT_SECRET", "a-secret-key-of-at-least-32-characters-for-example-27")
JWT_DURATION_MINUTES = int(os.environ.get("JWT_DURATION_MINUTES", "60"))

# o CACHE da aplicação: aqui, a memória do processo do servidor (é o
# cache padrão do Django). Os captchas pendentes e os contadores de falhas são
# armazenados nele
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
    },
}

# a limitação das tentativas de login: 3 falhas por janela de 60 segundos
LOGIN_MAX_FAILURES = 3
LOGIN_WINDOW_SECONDS = 60
  • linhas 49–53: o cache da aplicação. [LocMemCache] guarda os valores na memória do processo: é o cache padrão do [Django], que escrevemos para torná-lo visível. Ele se limita ao escopo da aplicação (veja o capítulo sobre escopos): é específico do processo e se perde quando o servidor é desligado. O estudo de caso usa um cache guardado em arquivos ([FileBasedCache]), que sobrevive às reinicializações; em produção, preferiríamos o [Redis] ([django.core.cache.backends.redis.RedisCache]), compartilhado por todos os processos;
  • linhas 56–57: os parâmetros do limitador.

8.3.5. A view: accounts/views.py

# accounts/views.py: login (com captcha e limitação das tentativas),
# logout e uma página reservada a usuários autenticados

from django.conf import settings
from django.shortcuts import redirect, render
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from security import auth, captchas
from security.decorators import login_required
from security.limiter import Limiter


@require_GET
def home(request):
    return redirect("profile")


# GET: o formulário; POST: o login, com captcha e limitação das tentativas
@require_http_methods(["GET", "POST"])
def login(request):
    if request.method == "GET":
        return login_page(request)
    login = request.POST.get("login", "")
    # o limitador DESTE cliente: suas falhas são contadas sob seu endereço IP
    limiter = Limiter(request.META["REMOTE_ADDR"])
    # 1. um endereço bloqueado nem sequer é ouvido
    seconds = limiter.wait()
    if seconds > 0:
        return login_page(request, login, f"Too many attempts: try again in {seconds} s.")
    # 2. primeiro o captcha (barato), depois a senha (PBKDF2, caro)
    if not captchas.verify(request.POST.get("captcha_id", ""), request.POST.get("captcha", "")):
        limiter.failure()
        return login_page(request, login, "The code of the image is incorrect.")
    user = auth.validate(login, request.POST.get("password", ""))
    if user is None:
        limiter.failure()
        return login_page(request, login, "Incorrect login or password.")
    limiter.clear()
    response = redirect("profile")
    response.set_cookie(auth.COOKIE, auth.create_token(user),
                        max_age=settings.JWT_DURATION_MINUTES * 60, httponly=True, samesite="Lax")
    return response


# cada exibição do formulário constrói um NOVO captcha
def login_page(request, login="", error=None):
    return render(request, "auth/login.html",
                  {"login": login, "error": error, "captcha": captchas.generate()})


# logout: somente por POST (um simples link, colocado em outro site, não pode
# desconectar o usuário sem que ele saiba); excluímos o cookie
@require_POST
def logout(request):
    response = redirect("login")
    response.delete_cookie(auth.COOKIE)
    return response


# request.user: o usuário autenticado, encontrado pelo middleware
@require_GET
@login_required
def profile(request):
    return render(request, "profile/profile.html", {"user": request.user})
  • linha 25: o limitador deste cliente, baseado em seu endereço IP ([REMOTE_ADDR], exemplo 05);
  • linhas 27–29: um endereço bloqueado nem sequer é ouvido;
  • linhas 31–37: o CAPTCHA é verificado antes da senha; verificá-lo não custa quase nada, ao passo que o hash PBKDF2 é intencionalmente lento. Um programa que erre o CAPTCHA não imporia, portanto, nenhuma carga ao servidor. Toda falha — seja do CAPTCHA ou da senha — é contada. Na terceira falha, o endereço é bloqueado até o fim da janela de 60 segundos, contados a partir da primeira falha;
  • linha 38: um login bem-sucedido apaga a contagem de falhas;
  • linhas 46–48: cada vez que o formulário é exibido, um novo CAPTCHA é gerado, mesmo após uma falha.

8.3.6. O template: templates/auth/login.html

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Login</h1>
  <form method="post" action="{% url 'login' %}">
    {% csrf_token %}
    <div class="mb-2">
      <label class="form-label" for="login">Login</label>
      <input class="form-control" id="login" name="login" value="{{ login }}" 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 (filtro safe) #}
      <div class="mb-1">{{ captcha.svg|safe }}</div>
      {# o identificador do captcha viaja em um campo oculto; a resposta em si permanece no servidor #}
      <input type="hidden" name="captcha_id" 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 18: a imagem SVG é inserida na página como está, sem escape (filtro [safe], Exemplo 14). Isso é legítimo: esse HTML foi gerado pelo servidor; não contém nenhuma entrada do usuário;
  • linha 20: o identificador do CAPTCHA, em um campo oculto;
  • linha 21: o navegador não sugere entradas anteriores para esse campo ([autocomplete="off"]).

8.3.7. Execução

Image

Um código copiado incorretamente:

Image

Após três tentativas malsucedidas, o endereço é bloqueado:

Image

Com [curl], quatro tentativas usando um identificador de CAPTCHA inventado (depois de obter, como no Exemplo 25, o cookie e o token anti-CSRF):

curl -b cookies.txt -d "csrfmiddlewaretoken=...&login=marie&password=marie&captcha_id=abc&captcha=ABCDE" http://localhost:8000/login
1
2
3
4
    <div class="alert alert-danger mt-3">The code of the image is incorrect.</div>
    <div class="alert alert-danger mt-3">The code of the image is incorrect.</div>
    <div class="alert alert-danger mt-3">The code of the image is incorrect.</div>
    <div class="alert alert-danger mt-3">Too many attempts: try again in 59 s.</div>

Mesmo com a senha correta, a quarta tentativa é rejeitada sem ser processada.