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
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:
- 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:
e no [Windows] ([PowerShell]):
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
- 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
- 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
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
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
- 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
- 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).
- 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:
Uma senha incorreta:

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:
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:
(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:

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:
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
- 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
- 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
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
- 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
- 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:

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

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:
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:
8.3.1. A imagem do CAPTCHA: security/captcha_drawing.py
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
- 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
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
- 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
- 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
- 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

Um código copiado incorretamente:

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

Com [curl], quatro tentativas usando um identificador de CAPTCHA inventado (depois de obter, como no Exemplo 25, o cookie e o token anti-CSRF):
Mesmo com a senha correta, a quarta tentativa é rejeitada sem ser processada.