8. Autenticação e autorização
Duas perguntas distintas surgem a cada requisição:
- Quem é o usuário? Isto é 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? Isto é a autorização: no estudo de caso, apenas um usuário com o papel ADMIN gerencia médicos e clientes.
A prova de identidade deve acompanhar cada requisição. O [Laravel] normalmente armazena o ID do 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]), 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 token é armazenado 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 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. O mais importante: o servidor não precisa armazenar nada, pois qualquer servidor que conheça a chave pode verificar o token.
O [Laravel] tem um sistema de autenticação completo, cujos componentes usaremos como estão:
- a autenticação é tratada por um *guard*: um objeto que, a cada requisição, identifica o usuário autenticado. O [Laravel] fornece um guard que lê a sessão; escreveremos o nosso, que lê o token, em poucas linhas. O restante da aplicação enxerga apenas o guard: [auth()->user()], [#[CurrentUser]] e [@auth] nas views;
- a proteção de páginas é tratada pelo middleware de rota (capítulo anterior): [auth] exige um usuário autenticado, [can:admin] exige uma autorização;
- as autorizações são descritas por Gates (por exemplo, 26);
- As senhas passam por hash pela facade [Hash] (com o algoritmo *bcrypt*), e os limites de tentativas são aplicados pela facade [RateLimiter] (exemplo 27).
A geração e a verificação de tokens ficam a cargo da biblioteca [firebase/php-jwt], a mais utilizada em [PHP], instalada pelo arquivo [composer.json] dos exemplos.
8.1. Exemplo 25: Login, token e página protegida
8.1.1. Configuração: .env, config/jwt.php e config/auth.php
O token é assinado com uma chave secreta, que não deve ser escrita diretamente no código. É hora de separar de verdade a configuração do código. As definições específicas de uma instalação ficam no arquivo [.env] (exemplo 01), que agora inclui duas novas linhas:
O padrão exige, para o algoritmo utilizado (HMAC-SHA256), uma chave de pelo menos 256 bits, ou 32 bytes; a biblioteca rejeita uma chave mais curta. O código, no entanto, não lê o arquivo [.env]: ele lê a configuração da aplicação — um conjunto de arquivos [PHP] armazenados na pasta [config], cada um dos quais retorna um array. Criamos o arquivo [config/jwt.php]:
- Linha 6: a função [env] lê uma variável do ambiente do processo ou, na falta dela, do arquivo [.env]; seu segundo parâmetro é um valor padrão. Uma variável de ambiente tem precedência sobre o arquivo: em produção, a chave secreta é fornecida pelo ambiente, e o arquivo [.env] não contém uma;
- linha 8: as variáveis de ambiente são strings: [(int)] converte a duração em um inteiro.
O código lê esses valores por meio da função [config]: [config('jwt.secret')] refere-se à chave [secret] do arquivo [jwt.php]. [env] só é chamada nos arquivos de configuração: em produção, o comando [php artisan config:cache] reúne toda a configuração em um único arquivo para acelerar o processo, e o [.env] deixa de ser lido. O arquivo [config/auth.php] configura a autenticação:
O [Laravel] tem sua própria configuração de autenticação (o arquivo [vendor/laravel/framework/config/auth.php]; veja o exemplo 01); a configuração da aplicação a complementa: as chaves que ela fornece substituem as do framework, enquanto as demais mantêm seus valores. Declaramos um guard chamado [jwt], com o driver [jwt] (linha 12), e o definimos como guard padrão (linha 7). O driver [jwt] não existe no [Laravel]: nós o definimos em [bootstrap/app.php].
No [Linux] ou no [macOS], iniciaríamos a aplicação com uma chave diferente da seguinte forma:
e no [Windows] (PowerShell):
8.1.2. Usuários: app/Auth/User.php e UsersService.php
- Linha 9: um usuário. O [Laravel] espera que os usuários autenticados implementem a interface [Authenticatable]: seus métodos fornecem a ele o ID do usuário, sua senha com hash e o token de sessão “lembrar-me”, desnecessário aqui. Em uma aplicação típica, o modelo [Eloquent] da tabela de usuários (próximo capítulo) implementa isso;
- linhas 12–18: 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 obtido da lista de usuários). Um servidor nunca armazena uma senha, mesmo criptografada: se o banco de dados fosse roubado, as senhas também seriam (e muitas pessoas usam a mesma senha em todo lugar). 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 uma senha a partir de seu hash. Para verificar uma senha digitada, calcula-se seu hash e compara-se com o que está registrado.
- Linhas 11–14: dois usuários de teste, escritos diretamente no programa (o exemplo 28 e o estudo de caso popularão um banco de dados com eles): para cada login, o nome, o papel e o hash da senha. O hash é gerado com o algoritmo bcrypt, projetado para senhas. Ele tem duas características distintivas. É intencionalmente lento, com um nível de lentidão ajustável (o custo, aqui definido como 10: 2^10 ciclos de cálculo, resultando no hash [$10$]): algumas dezenas de milissegundos, imperceptíveis para um usuário, mas que tornam muito custoso para um hacker tentar bilhões de senhas. Ele usa salt: um salt gerado aleatoriamente é misturado à senha antes do hash e armazenado dentro do próprio hash (os 22 caracteres que seguem [$10$]); assim, dois usuários com a mesma senha terão hashes diferentes. Os hashes foram calculados de uma vez por todas pela função [password_hash] do [PHP] (linha 10): calculá-los a cada requisição seria um desperdício desnecessário de tempo, já que a aplicação é reconstruída a cada requisição. O [bcrypt] considera apenas os primeiros 72 bytes de uma senha: o estudo de caso leva isso em conta;
- Linhas 16–23: o usuário de um login, ou [null]. [isset] verifica a existência de uma chave; a atribuição [[$name, $role, $hash] = ...] desestrutura um array: cada variável recebe o elemento correspondente.
8.1.3. O serviço de autenticação: app/Auth/AuthService.php
- linhas 20–30: verificação de um nome de usuário e uma senha. [Hash::check] 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, [null];
- linhas 33–45: geração do token. Seu conteúdo é um array 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 (a função [time()] do [PHP]). Os demais campos são opcionais: aqui, o nome e o papel. [JWT::encode] gera o token e o assina usando o algoritmo [HS256] (HMAC-SHA256, uma assinatura que usa uma chave secreta compartilhada);
- Linhas 49–58: verificação do token. [JWT::decode] verifica a assinatura e a data de expiração e, em seguida, retorna as claims (um objeto, convertido em array por [(array)]). Qualquer anomalia (token forjado, expirado ou malformado) lança uma exceção; [catch (Throwable)] captura todas elas ([Throwable] é a interface de todas as exceções e erros do [PHP]; o nome da variável é opcional quando ela não é usada). O objeto [Key] associa a chave a um algoritmo: um token que especifique outro algoritmo (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 guard: bootstrap/app.php
- linha 20: o token já está assinado; o cookie que o transporta não é criptografado (exemplo 22), o que permite examiná-lo;
- linha 22: o middleware [auth] redirecionará os visitantes anônimos para a página de login;
- linhas 28–39: [Auth::viaRequest] define um driver de guard por meio de uma função simples: ela recebe a requisição e retorna o usuário autenticado, ou [null] para um visitante anônimo. Ela só é chamada se a aplicação precisar do usuário e, depois que encontra um, o [Laravel] o retém durante toda a requisição (para um visitante anônimo, ela é chamada a cada requisição) (o middleware [auth], [auth()->user()]...). Ela não rejeita nada: ela determina quem é o usuário. Isso é a autenticação. [app(AuthService::class)] solicita um objeto ao contêiner (veja o exemplo 06): a função [app] dá acesso ao contêiner em qualquer lugar;
- Linhas 34–39: se o navegador enviou um cookie, mas seu token é inválido (expirado ou adulterado), aproveitamos para excluí-lo. [Cookie::forget] cria um cookie vazio que já expirou; [Cookie::queue] o enfileira: o middleware [AddQueuedCookiesToResponse] do grupo [web] o adicionará à resposta, seja qual for essa resposta.
8.1.5. Os controllers
- linhas 30–34: o login. Se o login falhar, 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 hacker quais nomes de usuário existem;
- linhas 39–41: em caso de sucesso, o token é armazenado em um cookie e o usuário é redirecionado 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 injeção de scripts (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 (exemplo 18); sua duração (em minutos) é a mesma do token. Em produção, para HTTPS, adicionaríamos [secure: true]: o cookie nunca seria enviado por uma conexão não criptografada;
- Linhas 46–49: o logout exclui o cookie ([withoutCookie]). Esta é uma action POST: um simples link para [/logout], colocado em outro site ou dentro de uma imagem, não pode 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.
- Linha 14: o atributo [#[CurrentUser]] solicita ao contêiner o usuário autenticado — aquele encontrado pelo guard (veja o exemplo 12 para os atributos de parâmetro). A action é protegida pelo middleware [auth] (veja a tabela de rotas): ela tem a garantia de receber um usuário. Ele também poderia ser obtido por meio de [auth()->user()] ou [$request->user()].
A tabela de rotas:
- Linha 14: o middleware [auth] protege a página de perfil. Para um visitante anônimo, ele lança uma exceção [AuthenticationException], que o [Laravel] converte em um redirecionamento para a página de login ([redirectGuestsTo]). [auth] é um alias — um nome curto que o [Laravel] associa ao middleware [Illuminate\Auth\Middleware\Authenticate]. Um grupo de rotas pode ser protegido de uma só vez: [Route::middleware('auth')->group(...)].
8.1.6. As views
- Linha 6: o formulário de login é protegido contra requisições forjadas, como todos os formulários (exemplo 18);
- linha 9: o login digitado é exibido novamente após uma tentativa malsucedida.
- Linhas 8–10: o conteúdo do token, exibido para fins ilustrativos;
- linhas 13–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], é preciso primeiro solicitar o formulário para obter o token anti-CSRF e o cookie de sessão (exemplo 18) e, em seguida, 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 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]*** 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 confere:
O token forjado é rejeitado e excluído (o valor [deleted] e a data expirada instruem o navegador a excluir 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 adiciona uma página de administração, restrita ao papel ADMIN. Apenas os arquivos novos ou modificados são exibidos.
8.2.1. Uma autorização: bootstrap/app.php
- Linha 44: a facade [Gate] (um “portão”) define uma autorização chamada [admin]. A função recebe o usuário autenticado (e, opcionalmente, outros parâmetros: o objeto a ser acessado, por exemplo) e retorna [true] se o usuário tiver a permissão solicitada. Uma permissão pode ser verificada de várias maneiras: [Gate::allows('admin')] ou [Gate::authorize('admin')] (que lança uma exceção, 403) no código, [@can('admin')] nas views e o middleware [can:admin] nas rotas. Para um número maior de regras, o [Laravel] sugere agrupá-las por classe de modelo em policies (*policies*).
8.2.2. A tabela de rotas e o controller
- linha 19: dois middlewares, executados em ordem: [auth] verifica se há um usuário autenticado (caso contrário, redireciona para a página de login) e, em seguida, [can:admin] verifica se o usuário tem a permissão [admin] (caso contrário, um erro 403, *Forbidden*). O texto que segue [:] é o parâmetro do middleware, que o [Laravel] passa a ele após [$next]. A diferença entre as duas respostas de negação é significativa: para um usuário que está autenticado, mas não tem o papel solicitado, fazer login novamente não serviria para nada, já que ele já está autenticado.
O controller não realiza nenhuma verificação: isso é responsabilidade do middleware. O [Laravel] também permite especificar middlewares diretamente na própria action, por meio de atributos: [#[Middleware('auth')]], [#[Authorize('admin')]].
8.2.3. Views
A página de erro 403: o [Laravel] procura uma view [errors/<code>.blade.php] quando ocorre um erro HTTP e a exibe no lugar de sua página padrão (veja o capítulo anterior). Não há nada a declarar. A página de perfil fornece um link para a página de administração:
- Linhas 7–11: a diretiva [@can] exibe seu bloco apenas se o usuário tiver a permissão; [@else] trata o caso oposto. Isso evita que seja exibido um link que levaria a um erro; no entanto, isso é apenas uma medida de conveniência: a proteção real vem do roteamento.
8.2.4. Execução
Marie, com o papel USER, segue o link para a página de administração:

O administrador, por outro lado, tem acesso a ela:

Com o [curl]: um usuário com o papel USER (o arquivo [token.txt], obtido fazendo login como no exemplo 25, mas no exemplo 26: os dois exemplos assinam seus tokens com chaves diferentes), seguido de um visitante anônimo:
Proteger as rotas 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 rotas são protegidas por padrão por um grupo, e apenas algumas rotas (a página de login, a página de cadastro) são excluídas.
8.3. Exemplo 27: CAPTCHA e limites 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 e adiciona essas duas medidas de segurança.
8.3.1. A imagem do CAPTCHA: app/Auth/CaptchaDrawing.php
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 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 | |
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.
- Linhas 16–49: 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;
- Linhas 56–64: uma string de texto aleatória, selecionada entre os caracteres da fonte ([array_keys], as chaves da tabela). As funções [rand] e [mt_rand] do [PHP] produzem sequências de números previsíveis (quem conhece alguns valores pode adivinhar os seguintes): são adequadas para simulações, não para segurança. [random_int] é um gerador criptográfico; ele é imprevisível;
- linhas 67–70: um número de ponto flutuante aleatório, gerado a partir de um inteiro aleatório ([PHP_INT_MAX] é o maior inteiro do [PHP]);
- linhas 77–118: o desenho. Cada caractere é redimensionado, girado e movido 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. A função [sprintf] formata uma string: [%s] insere nela uma string e [%.1f] insere um número com uma casa decimal. [str_split] divide uma string em caracteres.
8.3.2. O serviço de CAPTCHA: app/Auth/CaptchaService.php
- Linhas 15–24: um novo CAPTCHA: texto aleatório, um identificador aleatório impossível de adivinhar ([Str::random] também usa um gerador criptográfico) e a imagem. Para cada identificador, o servidor armazena a resposta esperada no cache (exemplo 20) por dez minutos: [Cache::put(key, value, seconds)]. Depois desse prazo, o cache a descarta automaticamente. A página recebe apenas o identificador e a imagem: a resposta nunca sai do servidor. A classe [Captcha] combina o identificador e a imagem;
- linhas 27–35: a verificação. [Cache::pull] lê o valor e o remove do cache: o CAPTCHA é consumido em todos os casos, com sucesso ou não. Sem isso, um programa poderia tentar todas as respostas possíveis na mesma imagem. A comparação ignora maiúsculas e minúsculas ([strcasecmp] retorna 0 para duas strings iguais, independentemente de letras maiúsculas ou minúsculas) e os espaços ao redor da entrada ([trim]).
8.3.3. O controller: app/Http/Controllers/AuthController.php
- linha 38: o limite é tratado pela facade [RateLimiter] do [Laravel], que conta as “tentativas” sob uma chave no cache. A chave aqui é o endereço IP do cliente;
- linhas 41–44: um endereço bloqueado nem sequer é ouvido. [tooManyAttempts(key, 3)] é verdadeiro se a chave atingiu 3 tentativas; [availableIn] retorna o número de segundos restantes antes do fim do bloqueio;
- linhas 46–54: o CAPTCHA é verificado antes da senha; verificá-lo quase não custa nada, ao passo que o [bcrypt] é intencionalmente lento. Um programa que digitasse o CAPTCHA errado, portanto, não acionaria o [bcrypt]. Cada falha — seja do CAPTCHA ou da senha — é contada: [RateLimiter::hit(key, 60)] adiciona uma tentativa e define a duração do contador em 60 segundos. Na terceira falha, o endereço fica, portanto, bloqueado até o fim desses 60 segundos, contados a partir da primeira falha;
- linha 55: um login bem-sucedido zera as tentativas malsucedidas;
- linhas 67–71: a cada vez que o formulário é exibido, um novo CAPTCHA é gerado, mesmo após uma tentativa malsucedida.
O [Laravel] também fornece um middleware, [throttle], que limita o número de requisições para uma rota ([->middleware('throttle:5,1')]: 5 requisições por minuto); optamos por contar apenas as tentativas malsucedidas, para não incomodar um usuário que faz login normalmente.
8.3.4. A view: resources/views/auth/login.blade.php
- Linha 18: a imagem SVG é inserida na página como está, sem escape (exemplo 14). Isso é legítimo: esse HTML foi gerado pelo servidor e não contém nenhuma entrada do usuário;
- Linha 20: o ID do captcha, em um campo oculto;
- linha 21: o navegador não sugere nenhuma entrada anterior para esse campo.
8.3.5. Execução

Um código copiado incorretamente:

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

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