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
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:
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.
- 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:
e no [Windows] (PowerShell):
8.1.2. Usuários: auth/users.py
- 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
- 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
- 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
- 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.
- 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
- 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).
- 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:
Uma senha incorreta:

Login bem-sucedido. Com o [curl], salvamos o cookie recebido em um arquivo:
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:
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:

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:
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
- 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
- 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
- Linhas 37–39: um tratador de erro registrado para um código específico — o erro 403 — exibe nossa página.
8.2.4. 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 o [curl]: um usuário com o papel USER, seguido de um visitante anônimo:
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 | |
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
- 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
- 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
- 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
- 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

Um código copiado incorretamente:

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

Com o [curl], quatro tentativas com um ID de CAPTCHA inventado:
Mesmo com a senha correta, a quarta tentativa é rejeitada sem verificação.