Skip to content

8. Autenticação e autorização

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

  • Quem é o usuário? Isso é a autenticação: o usuário se identificou com um nome de usuário e uma senha, e cada requisição seguinte 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 médicos e clientes.

A prova de identidade deve acompanhar cada requisição. O [Symfony] normalmente armazena o usuário logado em sua sessão (veja a seção 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]), 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 é 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 pode modificá-lo: qualquer modificação invalida a assinatura. O formato é padronizado (RFC 7519), entendido por todas as linguagens de programação, e o token inclui sua data de expiração. Acima de tudo, o servidor não precisa armazenar nada: qualquer servidor que conheça a chave pode verificar o token.

O [Symfony] tem um componente de segurança completo, integrado pelo SecurityBundle, cujos elementos usaremos como são:

  • as URLs da aplicação são distribuídas entre firewalls (firewalls), cada um com seu próprio método de autenticação dos usuários;
  • a autenticação é feita por authenticators (authenticators): objetos que determinam a identidade do usuário a cada requisição. O [Symfony] fornece vários deles (formulário de login, sessão, token de API etc.); escreveremos o nosso, que lê o token JWT. O restante da aplicação vê apenas o resultado: o usuário autenticado, fornecido por [#[CurrentUser]], [$this->getUser()] e, nas views, [app.user];
  • os usuários são fornecidos por um user provider, e suas senhas recebem hash do PasswordHasher (algoritmo [bcrypt]);
  • as autorizações são baseadas em papéis: a proteção de páginas é descrita por regras de controle de acesso ([access_control]) ou pelo atributo [#[IsGranted]] das ações; as views verificam um direito com [is_granted];
  • As tentativas de login são limitadas pelo componente RateLimiter (Exemplo 27).

Tudo isso é feito por listeners de eventos do kernel (capítulo anterior): o firewall escuta [kernel.request] (prioridade 8), [#[IsGranted]] é lido em [kernel.controller_arguments], e as negações de acesso são exceções, tratadas em [kernel.exception].

A geração e a verificação de tokens ficam a cargo da biblioteca [firebase/php-jwt], a mais usada em [PHP], instalada pelo arquivo [composer.json] dos exemplos. (Existe um bundle muito usado para tokens, o JWT e [LexikJWTAuthenticationBundle], projetado 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/
├── .env
├── config/
│   ├── bundles.php
│   └── packages/
│       ├── framework.yaml
│       └── security.yaml
├── src/
│   ├── Controller/
│   │   ├── AuthController.php
│   │   └── ProfileController.php
│   └── Security/
│       ├── AuthService.php
│       ├── TokenAuthenticator.php
│       ├── User.php
│       └── UsersService.php
├── templates/
│   ├── auth/
│   │   └── login.html.twig
│   ├── layout.html.twig
│   └── profile/
│       └── profile.html.twig
└── ...

8.1.1. Configuração: .env, bundles.php e framework.yaml

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 configurações específicas de uma instalação ficam no arquivo [.env] (Exemplo 01), que agora contém três novas linhas (um comentário, seguido de duas variáveis):

1
2
3
4
5
6
# .env: a configuração do exemplo 25 (veja o exemplo 01)
APP_ENV=dev
APP_SECRET=6144ddf9f821deebee2291ab7742d7a9
# a chave que assina os tokens JWT (pelo menos 32 caracteres) e seu tempo de vida
JWT_SECRET=a-secret-key-of-at-least-32-characters-for-example-25
JWT_DURATION_MINUTES=60

O padrão exige que o algoritmo usado (HMAC-SHA256) tenha uma chave de pelo menos 256 bits, ou 32 bytes; a biblioteca rejeita qualquer chave mais curta. O código em si não lê diretamente o arquivo [.env]: o componente [Dotenv] (exemplo 01) o converteu em variáveis de ambiente, que o contêiner fornece aos serviços que as solicitam (veremos isso com o serviço [AuthService]). Uma variável de ambiente real tem precedência sobre o arquivo [.env]: 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" php -d variables_order=EGPCS -S localhost:8000 -t public

e no [Windows] (PowerShell):

$env:JWT_SECRET="another-key-of-at-least-thirty-two-characters"
php -d variables_order=EGPCS -S localhost:8000 -t public

(A opção [-d variables_order=EGPCS] instrui o [PHP] a preencher o array [$_ENV] com as variáveis de ambiente, o que sua configuração padrão nem sempre faz.) Em produção, os segredos costumam ser confiados ao [Symfony] vault (secrets vault, comando [bin/console secrets:set]), que os armazena criptografados dentro do projeto.

O SecurityBundle é adicionado à lista de bundles:

1
2
3
4
5
6
7
8
<?php
// config/bundles.php: os bundles da aplicação; o SecurityBundle integra
// o componente de segurança (autenticação, autorização)
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
];

A sessão é usada aqui apenas para o token anti-CSRF do formulário de login (Exemplo 21):

1
2
3
4
5
6
7
8
# config/packages/framework.yaml: a configuração do FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # a sessão: ela é usada apenas para o token anti-CSRF do formulário de login
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    csrf_protection: true

8.1.2. Configuração de segurança: config/packages/security.yaml

# config/packages/security.yaml: a configuração do SecurityBundle
security:
    # o hash das senhas dos usuários da classe User: bcrypt
    password_hashers:
        App\Security\User:
            algorithm: bcrypt

    # o PROVIDER de usuários: o objeto que encontra um usuário a partir de seu login
    providers:
        users:
            id: App\Security\UsersService

    # os FIREWALLS: cada um protege as URLs que correspondem ao seu pattern
    firewalls:
        # os arquivos do Bootstrap: sem segurança
        resources:
            pattern: ^/bootstrap/
            security: false
        # todas as outras URLs
        main:
            # stateless: o usuário não é armazenado na sessão, ele é
            # reencontrado a cada requisição, a partir de seu token
            stateless: true
            provider: users
            # o authenticator: ele lê o token do cookie, a cada requisição
            custom_authenticators:
                - App\Security\TokenAuthenticator

    # o CONTROLE DE ACESSO: as URLs que começam com /profile exigem um usuário
    # autenticado; as outras são públicas
    access_control:
        - { path: ^/profile, roles: IS_AUTHENTICATED }
  • linhas 4–6: o algoritmo de hash de senhas para os usuários da classe [User]: [bcrypt]. (O valor [auto] selecionaria o melhor algoritmo disponível e seria capaz de verificar hashes de outros algoritmos);
  • linhas 9–11: o user provider, o serviço que encontra um usuário a partir de seu ID (aqui, nossa classe [UsersService]). O [Symfony] fornece vários: [memory] (uma lista escrita neste arquivo), [entity] (uma tabela do banco de dados; veja o estudo de caso)...;
  • Linhas 14–27: os firewalls. Cada um se aplica às URLs que correspondem ao seu padrão ([pattern]), sendo selecionado o primeiro que corresponder. O primeiro, [resources], cobre os arquivos do [Bootstrap] (Exemplo 15), sem segurança ([security: false]): não há necessidade de procurar um usuário para servir uma folha de estilo. O segundo, [main], não tem uma razão específica: cobre todas as demais URLs;
  • linha 23: o firewall é stateless (stateless): o usuário autenticado não é armazenado na sessão; ele é identificado a cada requisição com base em seu token;
  • Linhas 26–27: o authenticator do firewall, nossa classe [TokenAuthenticator];
  • Linhas 31–32: o controle de acesso: uma lista de regras, examinadas em ordem, das quais se aplica a primeira que corresponder à URL. As URLs que começam por [/profile] exigem um usuário autenticado ([IS_AUTHENTICATED]); as demais são públicas.

Em um projeto padrão, este arquivo é escrito pelo [Symfony Flex] quando o bundle ([composer require security]) é instalado, e o comando [bin/console make:user] do [MakerBundle] escreve a classe do usuário e seu provider.

8.1.3. Usuários: src/Security/User.php e UsersService.php

<?php
// src/Security/User.php: um usuário. UserInterface: a interface que
// o Symfony espera dos usuários autenticados; PasswordAuthenticatedUserInterface:
// um usuário que possui uma senha

namespace App\Security;

use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Component\Security\Core\User\UserInterface;

readonly class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    public function __construct(
        public string $login,
        public string $name,
        // o papel: USER ou ADMIN
        public string $role,
        // o HASH da senha (vazio para um usuário lido de um token)
        public string $passwordHash = '',
        // o conteúdo do token que autenticou o usuário
        public array $claims = [],
    ) {
    }

    // o identificador do usuário: seu login
    public function getUserIdentifier(): string
    {
        return $this->login;
    }

    // os papéis, no sentido do Symfony: strings que começam com ROLE_
    public function getRoles(): array
    {
        return ['ROLE_'.$this->role];
    }

    public function getPassword(): string
    {
        return $this->passwordHash;
    }
}
  • Linha 11: um usuário. O [Symfony] espera que os usuários autenticados implementem a interface [UserInterface]: seus métodos fornecem o identificador e os papéis do usuário. A interface [PasswordAuthenticatedUserInterface] acrescenta a senha com hash. Em uma aplicação típica, a entidade [Doctrine] da tabela de usuários (próximo capítulo) implementa esses métodos;
  • Linhas 13–23: 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, 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 o hash dela e compara-se com o que está armazenado;
  • linhas 32–35: os papéis, conforme definidos pelo [Symfony]: strings que começam com [ROLE_]. O papel [USER] do estudo de caso se torna [ROLE_USER].
<?php
// src/Security/UsersService.php: os usuários, em memória (o exemplo 28
// e o estudo de caso os colocarão em um banco de dados). UserProviderInterface: um
// PROVIDER de usuários, no sentido do Symfony (veja config/packages/security.yaml)

namespace App\Security;

use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
use Symfony\Component\Security\Core\Exception\UserNotFoundException;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\UserProviderInterface;

class UsersService implements UserProviderInterface
{
    // NUNCA guardamos uma senha, apenas seu hash bcrypt, calculado
    // de uma vez por todas por: php -r "echo password_hash('marie', PASSWORD_BCRYPT);"
    private const USERS = [
        'marie' => ['Marie Pélissier', 'USER', '$2y$10$2DnOgGBiVcyc07su9rj2E.EvOoyPFzHN/h9PLKDuoW5P7UGtclW6W'],
        'admin' => ['Administrator', 'ADMIN', '$2y$10$m5o9euCi0EdgoZkLVw.UsO58RxJcqhMBfVrlLMCIOh2LyGSjuN29K'],
    ];

    public function find(string $login): ?User
    {
        if (! isset(self::USERS[$login])) {
            return null;
        }
        [$name, $role, $hash] = self::USERS[$login];
        return new User($login, $name, $role, $hash);
    }

    // os três métodos de UserProviderInterface
    public function loadUserByIdentifier(string $identifier): UserInterface
    {
        return $this->find($identifier) ?? throw new UserNotFoundException();
    }

    // o usuário armazenado na sessão, a recarregar: nunca chamado aqui,
    // já que o firewall é stateless
    public function refreshUser(UserInterface $user): UserInterface
    {
        throw new UnsupportedUserException();
    }

    public function supportsClass(string $class): bool
    {
        return $class === User::class;
    }
}
  • Linhas 17–20: dois usuários de teste, fixados no código (o exemplo 28 e o estudo de caso os armazenarão em um banco de dados): 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 marcantes. É intencionalmente lento, com um nível de lentidão ajustável (o custo, aqui definido como 10: 2^10 ciclos de computação, o que resulta no hash [$10$]): 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 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 uma única vez pela função [password_hash] do [PHP] (linha 16), ou pelo comando [bin/console security:hash-password] do [Symfony]: calculá-los a cada requisição seria uma perda de tempo desnecessária, 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 22–29: 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;
  • linhas 32–47: os três métodos da interface [UserProviderInterface], que fazem da classe um provider de usuários: [loadUserByIdentifier] retorna o usuário associado a um identificador, ou lança a exceção [UserNotFoundException]; [refreshUser] recarrega o usuário armazenado na sessão (desnecessário com um firewall stateless); [supportsClass] especifica a classe dos usuários fornecidos. O operador [??] seguido de [throw] lança a exceção quando a expressão à esquerda é avaliada como [null].

8.1.4. O serviço de autenticação: src/Security/AuthService.php

<?php
// src/Security/AuthService.php: a verificação das senhas e dos tokens JWT

namespace App\Security;

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
use Throwable;

class AuthService
{
    // o nome do cookie que carrega o token
    public const COOKIE = 'token';

    public function __construct(
        private UsersService $users,
        // o serviço de hash de senhas (veja config/packages/security.yaml)
        private UserPasswordHasherInterface $hasher,
        // #[Autowire(env: ...)]: o valor de uma variável de ambiente (arquivo .env);
        // o prefixo int: o converte em inteiro
        #[Autowire(env: 'JWT_SECRET')] private string $secret,
        #[Autowire(env: 'int:JWT_DURATION_MINUTES')] public readonly int $durationMinutes,
    ) {
    }

    // o usuário, ou null se o login for desconhecido ou a senha estiver errada.
    // isPasswordValid calcula o hash da senha digitada com o salt do hash armazenado e
    // depois compara os dois resultados
    public function validate(?string $login, ?string $password): ?User
    {
        if (! $login || $password === null) {
            return null;
        }
        $user = $this->users->find($login);
        if ($user === null || ! $this->hasher->isPasswordValid($user, $password)) {
            return null;
        }
        return $user;
    }

    // o token JWT do usuário, assinado com a chave secreta (HMAC-SHA256)
    public function createToken(User $user): string
    {
        $now = time();
        // o conteúdo do token: as "claims" (declarações sobre o usuário)
        $claims = [
            'sub' => $user->login,
            'name' => $user->name,
            'role' => $user->role,
            'iat' => $now,
            'exp' => $now + $this->durationMinutes * 60,
        ];
        return JWT::encode($claims, $this->secret, 'HS256');
    }

    // o usuário descrito por um token cuja assinatura e data de expiração
    // são válidas; null caso contrário (token forjado, expirado ou ilegível)
    public function check(string $token): ?User
    {
        try {
            // decode retorna um objeto; (array) o converte em array associativo
            $claims = (array) JWT::decode($token, new Key($this->secret, 'HS256'));
        } catch (Throwable) {
            return null;
        }
        return new User($claims['sub'], $claims['name'], $claims['role'], claims: $claims);
    }
}
  • Linhas 17–26: o serviço recebe o provider de usuários, o serviço de hash de senhas ([UserPasswordHasherInterface], que aplica o algoritmo selecionado em [security.yaml]) e dois valores de configuração. O atributo [#[Autowire(env: 'NAME')]] fornece o valor de uma variável de ambiente; um prefixo a converte: [int:] para um inteiro (há outros: [bool:], [json:], [base64:]...). O tempo de vida é uma propriedade pública somente leitura: o controller a utilizará;
  • linhas 31–41: verificação de um nome de usuário e de uma senha. [isPasswordValid] 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 44–56: geração do token. O token contém um array de declarações (claims) sobre o usuário. Algumas 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 com chave secreta compartilhada);
  • linhas 60–69: verificação do token. [JWT::decode] verifica a assinatura e a data de expiração e, em seguida, retorna as declarações (um objeto, convertido em array por [(array)]). Qualquer anomalia (token forjado, expirado ou malformado) lança uma exceção; [catch (Throwable)] captura todas ([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 um algoritmo diferente (ou nenhum, [none]) seria rejeitado. O token válido se torna um [User], sem hash, junto com suas declarações (parâmetro chamado [claims]).

8.1.5. O autenticador: src/Security/TokenAuthenticator.php

<?php
// src/Security/TokenAuthenticator.php: o AUTHENTICATOR do firewall (veja
// config/packages/security.yaml): a cada requisição, ele estabelece quem é o usuário,
// a partir do token JWT do cookie [token]

namespace App\Security;

use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;

class TokenAuthenticator extends AbstractAuthenticator implements AuthenticationEntryPointInterface
{
    public function __construct(private AuthService $auth)
    {
    }

    // o authenticator age apenas se a requisição carregar o cookie do token;
    // caso contrário, o visitante permanece anônimo
    public function supports(Request $request): ?bool
    {
        return $request->cookies->has(AuthService::COOKIE);
    }

    // o PASSPORT do usuário: quem ele é (o badge) e como verificá-lo.
    // O token já foi verificado: o passport se valida sozinho (SelfValidatingPassport)
    public function authenticate(Request $request): Passport
    {
        $user = $this->auth->check($request->cookies->get(AuthService::COOKIE));
        if ($user === null) {
            throw new CustomUserMessageAuthenticationException('invalid token');
        }
        // o badge: o login e uma função que retorna o usuário (aqui, o do
        // token, sem consultar a lista de usuários)
        return new SelfValidatingPassport(new UserBadge($user->login, fn () => $user));
    }

    // um token válido: null, a requisição segue seu caminho até a action
    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
    {
        return null;
    }

    // um token inválido (expirado, forjado): vá para /login, e apagamos o cookie
    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
    {
        $response = new RedirectResponse('/login');
        $response->headers->clearCookie(AuthService::COOKIE);
        return $response;
    }

    // o ENTRY POINT: a resposta dada a um visitante anônimo que solicita uma
    // página protegida; aqui, um redirecionamento para a página de login
    public function start(Request $request, ?AuthenticationException $authException = null): Response
    {
        return new RedirectResponse('/login');
    }
}

Para cada requisição que passa pelo firewall, o [Symfony] chama os métodos do autenticador nesta ordem:

  • linhas 28–31: [supports]: o autenticador está envolvido nesta requisição? Sim, se ela contiver o cookie do token. Caso contrário, nada acontece: o visitante permanece anônimo;
  • linhas 35–44: [authenticate] constrói um passaporte: a identidade do usuário (um badge, [UserBadge]) e as credenciais a verificar. Um formulário de login padrão incluiria a senha digitada no passaporte, que o [Symfony] verificaria por conta própria. Aqui, a prova é o token, já verificado pelo [AuthService]: o passaporte se valida sozinho ([SelfValidatingPassport]). O badge contém o login e uma função que identifica o usuário: neste caso, o usuário descrito pelo token, sem consultar a lista de usuários (sem essa função, o [Symfony] solicitaria o usuário ao provider). Um token inválido lança uma exceção de autenticação;
  • linhas 47–50: [onAuthenticationSuccess]: a autenticação foi bem-sucedida. Retornar [null] permite que a requisição prossiga até a ação com um usuário autenticado. (Um formulário de login redirecionaria aqui para a página inicial);
  • linhas 53–58: [onAuthenticationFailure]: a autenticação falhou (token expirado ou forjado). A resposta redireciona para a página de login e aproveita para limpar o cookie: [clearCookie] adiciona à resposta um cookie vazio e já expirado;
  • linhas 62–65: [start] é o método da interface [AuthenticationEntryPointInterface]: o ponto de entrada do firewall, ou seja, a resposta enviada a um visitante anônimo que solicita uma página protegida. Neste caso, um redirecionamento para a página de login.

O autenticador 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 são responsabilidade do controle de acesso.

8.1.6. Os controllers

<?php
// src/Controller/AuthController.php: login e logout

namespace App\Controller;

use App\Security\AuthService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\Routing\Attribute\Route;

class AuthController extends AbstractController
{
    public function __construct(private AuthService $auth)
    {
    }

    #[Route('/', methods: ['GET'])]
    public function home(): Response
    {
        return $this->redirect('/profile');
    }

    #[Route('/login', methods: ['GET'])]
    public function form(): Response
    {
        return $this->render('auth/login.html.twig');
    }

    #[Route('/login', methods: ['POST'])]
    public function login(Request $request): Response
    {
        // o token anti-CSRF do formulário (veja o exemplo 21)
        if (! $this->isCsrfTokenValid('login', $request->getPayload()->getString('_csrf_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        $login = $request->getPayload()->getString('login');
        $user = $this->auth->validate($login, $request->getPayload()->getString('password'));
        if ($user === null) {
            // uma mensagem deliberadamente vaga: não dizemos se é o login ou a senha
            return $this->render('auth/login.html.twig', ['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 em que o token expira
        $response = $this->redirect('/profile');
        $response->headers->setCookie(Cookie::create(AuthService::COOKIE, $this->auth->createToken($user))
            ->withExpires(time() + $this->auth->durationMinutes * 60)
            ->withHttpOnly(true)
            ->withSameSite(Cookie::SAMESITE_LAX));
        return $response;
    }

    // logout: apenas POST (um simples link, colocado em outro site, não pode
    // desconectar o usuário sem que ele saiba); apagamos o cookie
    #[Route('/logout', methods: ['POST'])]
    public function logout(Request $request): Response
    {
        if (! $this->isCsrfTokenValid('logout', $request->getPayload()->getString('_csrf_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        $response = $this->redirect('/login');
        $response->headers->clearCookie(AuthService::COOKIE);
        return $response;
    }
}
  • linhas 36–38: o formulário de login é protegido contra requisições forjadas, como todos os formulários (exemplo 21);
  • linhas 40–45: o processo de login. Se ele 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 invasor quais nomes de usuário existem;
  • Linhas 49–54: se houver sucesso, o token é armazenado 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 pode 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; sua data de expiração ([withExpires], aqui um número de segundos desde 1970) é a mesma do token. Em produção, com HTTPS, acrescentaríamos [withSecure(true)]: o cookie nunca seria enviado por uma conexão não criptografada;
  • Linhas 59–68: o logout exclui o cookie ([clearCookie]). Essa é uma ação POST, protegida por um token anti-CSRF: 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 seu tempo de vida é limitado.

O [Symfony] também pode cuidar sozinho do login por formulário (o autenticador [form_login]) e do logout (a opção de firewall [logout] ); mas eles armazenam o usuário na sessão, ao passo que queremos um token.

<?php
// src/Controller/ProfileController.php: uma página reservada aos usuários autenticados
// (veja access_control em config/packages/security.yaml)

namespace App\Controller;

use App\Security\User;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\CurrentUser;

class ProfileController extends AbstractController
{
    // #[CurrentUser]: o usuário autenticado da requisição, aquele encontrado pelo
    // authenticator
    #[Route('/profile', methods: ['GET'])]
    public function display(#[CurrentUser] User $user): Response
    {
        return $this->render('profile/profile.html.twig', ['user' => $user]);
    }
}
  • linha 18: o atributo [#[CurrentUser]] fornece o usuário autenticado, aquele estabelecido pelo autenticador. A ação é protegida pela regra [access_control] de [security.yaml]: ela com certeza receberá um usuário. Também o obteríamos por meio de [$this->getUser()].

8.1.7. As views

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Login</h1>
  <form method="post" action="/login">
    <input type="hidden" name="_csrf_token" value="{{ csrf_token('login') }}">
    <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 is defined %}
    <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 (exemplo 21);
  • linha 9: o login digitado é exibido novamente após uma falha ([??]: uma string vazia quando a variável [login] não existe).
{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Hello {{ user.name }}</h1>
  <p>Your role: <b>{{ user.role == 'ADMIN' ? 'administrator' : 'user' }}</b>.</p>
  <p>The content of your token:</p>
  <table class="table table-sm w-auto">
    {% for key, value in user.claims %}
      <tr><td><code>{{ key }}</code></td><td>{{ value }}</td></tr>
    {% endfor %}
  </table>
  {# logout: um formulário POST reduzido ao seu botão #}
  <form method="post" action="/logout">
    <input type="hidden" name="_csrf_token" value="{{ csrf_token('logout') }}">
    <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. Um laço [for] do [Twig] pode percorrer as chaves e os valores de um array associativo ([for key, value in ...]);
  • linhas 13–16: o logout, por meio de um formulário reduzido a um único botão.

O usuário autenticado também está disponível em todas as views com o nome [app.user].

8.1.8. Execução

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

curl -i http://localhost:8000/profile
1
2
3
4
HTTP/1.1 302 Found
...
Location: /login
...

Uma senha incorreta:

Image

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 21) e, em seguida, 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 "_csrf_token=...&login=marie&password=marie" http://localhost:8000/login
1
2
3
4
HTTP/1.1 302 Found
Location: /profile
Set-Cookie: token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJtYXJpZSIsIm5hbWUiOiJNYXJpZSBQXHUwMGU5bGlzc2llciIsInJvbGUiOiJVU0VSIiwiaWF0IjoxNzkwNTAyNzM3LCJleHAiOjE3OTA1MDYzMzd9.ijkEBdAyfFX9yFEyHOLAi-WhkFvShYW4mxoPIG2LqOI; expires=Sun, 27 Sep 2026 10:52:17 GMT; Max-Age=3600; path=/; httponly; 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:

{"typ":"JWT","alg":"HS256"}
{"sub":"marie","name":"Marie P\u00e9lissier","role":"USER","iat":1790502737,"exp":1790506337}

(O [é] é escrito em sua forma escapada em 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=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.<modified content>.ijkEBdAyfFX9yFEyHOLAi-WhkFvShYW4mxoPIG2LqOI" http://localhost:8000/profile
1
2
3
4
HTTP/1.1 302 Found
Location: /login
Set-Cookie: token=deleted; expires=Sat, 27 Sep 2025 09:52:20 GMT; Max-Age=0; path=/; httponly
...

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 acrescenta uma página de administração, restrita ao papel ADMIN. Somente os arquivos novos ou modificados são exibidos.

8.2.1. A configuração: config/packages/security.yaml

# config/packages/security.yaml: a configuração do SecurityBundle (veja o exemplo 25)
security:
    password_hashers:
        App\Security\User:
            algorithm: bcrypt

    providers:
        users:
            id: App\Security\UsersService

    # a HIERARQUIA dos papéis: um administrador também tem os direitos de um usuário
    role_hierarchy:
        ROLE_ADMIN: ROLE_USER

    firewalls:
        resources:
            pattern: ^/bootstrap/
            security: false
        main:
            stateless: true
            provider: users
            custom_authenticators:
                - App\Security\TokenAuthenticator
            # um usuário autenticado, mas que não possui o direito solicitado: nossa página 403
            access_denied_handler: App\Security\AccessDenied

    # /profile: qualquer usuário autenticado; /admin é protegido pelo atributo #[IsGranted]
    # de seu controller; poderíamos ter escrito aqui:
    # - { path: ^/admin, roles: ROLE_ADMIN }
    access_control:
        - { path: ^/profile, roles: IS_AUTHENTICATED }
  • Linhas 12–13: a hierarquia de papéis: o papel [ROLE_ADMIN] inclui o papel [ROLE_USER]. Um administrador tem, assim, todos os direitos de um usuário, sem precisar receber os dois papéis;
  • Linha 25: o manipulador de acesso negado do firewall ([access_denied_handler]): a classe que gera a resposta enviada a um usuário autenticado que solicita uma página que ele não tem autorização para ver;
  • Linhas 27–31: a página [/admin] poderia ser protegida aqui com uma regra adicional; em vez disso, nós a protegemos em seu controller, para demonstrar uma abordagem alternativa.

A diferença entre as duas respostas de negação é importante: um visitante anônimo que solicita uma página protegida é redirecionado para o ponto de entrada do firewall (a página de login, exemplo 25); um usuário autenticado que não tem o papel exigido recebe um erro 403 (Forbidden): fazer login seria inútil, pois ele já está autenticado.

8.2.2. Acesso negado: src/Security/AccessDenied.php

<?php
// src/Security/AccessDenied.php: a resposta dada a um usuário AUTENTICADO que
// solicita uma página que lhe é proibida (veja access_denied_handler em security.yaml)

namespace App\Security;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Exception\AccessDeniedException;
use Symfony\Component\Security\Http\Authorization\AccessDeniedHandlerInterface;
use Twig\Environment;

class AccessDenied implements AccessDeniedHandlerInterface
{
    public function __construct(private Environment $twig)
    {
    }

    public function handle(Request $request, AccessDeniedException $accessDeniedException): ?Response
    {
        return new Response($this->twig->render('errors/403.html.twig'), Response::HTTP_FORBIDDEN);
    }
}
  • linha 13: a classe implementa a interface [AccessDeniedHandlerInterface], cujo único método, [handle], retorna a resposta de negação;
  • linha 21: a página de erro 403, gerada pelo [Twig] (como o listener [ErrorPage] do exemplo 24), com o código 403 ([Response::HTTP_FORBIDDEN], uma constante da classe [Response]).

Sem esse manipulador, a negação resultaria em uma exceção [AccessDeniedHttpException], e o usuário veria a página de erro 403 do [Symfony] (detalhada no modo de depuração). A página [templates/errors/403.html.twig] é uma página de erro padrão, com um link de volta ao perfil.

8.2.3. O controller: src/Controller/AdminController.php

<?php
// src/Controller/AdminController.php: uma página reservada ao papel ADMIN

namespace App\Controller;

use App\Security\User;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\CurrentUser;
use Symfony\Component\Security\Http\Attribute\IsGranted;

class AdminController extends AbstractController
{
    // #[IsGranted]: a action é executada apenas se o usuário tiver o papel ADMIN
    #[Route('/admin', methods: ['GET'])]
    #[IsGranted('ROLE_ADMIN')]
    public function display(#[CurrentUser] User $user): Response
    {
        return $this->render('admin/admin.html.twig', ['name' => $user->name]);
    }
}
  • Linha 17: o atributo [#[IsGranted]] permite que a ação seja executada somente por um usuário que tenha a permissão exigida, neste caso o papel [ROLE_ADMIN]. Um visitante anônimo é redirecionado para o ponto de entrada; um usuário autenticado sem esse papel tem o acesso negado. Quando aplicado à classe, o atributo protegeria todas as suas ações.

O controller não faz nenhuma verificação por conta própria. No código, uma permissão seria verificada com [$this->isGranted('ROLE_ADMIN')] (que retorna um booleano) ou com [$this->denyAccessUnlessGranted('ROLE_ADMIN')] (que lança uma exceção de negação). Para regras mais granulares do que um papel (“um usuário só pode editar as próprias consultas”), o [Symfony] permite definir “voters” (voters): classes que determinam uma permissão, que [#[IsGranted]] e [is_granted] consultam como se fossem papéis.

8.2.4. A view do perfil

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Hello {{ user.name }}</h1>
  <p>Your role: <b>{{ user.role == 'ADMIN' ? 'administrator' : 'user' }}</b>.</p>
  {# is_granted: o usuário tem este papel? O bloco é exibido somente nesse caso #}
  {% if is_granted('ROLE_ADMIN') %}
    <p><a href="/admin">The administration area</a></p>
  {% else %}
    <p><a href="/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 %}
      <tr><td><code>{{ key }}</code></td><td>{{ value }}</td></tr>
    {% endfor %}
  </table>
  {# logout: um formulário POST reduzido ao seu botão #}
  <form method="post" action="/logout">
    <input type="hidden" name="_csrf_token" value="{{ csrf_token('logout') }}">
    <button class="btn btn-outline-secondary" type="submit">Log out</button>
  </form>
{% endblock %}
  • Linhas 7–11: a função [is_granted] do [Twig] verifica a permissão de um usuário. Isso evita exibir um link que levaria a um erro; no entanto, é apenas um recurso de conveniência: a proteção real vem da própria ação.

8.2.5. Execução

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

Image

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

Image

Com o [curl]: um usuário com o papel USER (conectado como no exemplo 25, com os cookies armazenados 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
...
        <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
...
Location: /login
...

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 páginas de URL são protegidas por padrão por meio de uma regra [access_control] geral, e apenas algumas páginas de URL (a página de login e a página de cadastro) ficam 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 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 acrescenta essas duas medidas de segurança.

8.3.1. A imagem do CAPTCHA: src/Security/CaptchaDrawing.php

<?php
// src/Security/CaptchaDrawing.php: o desenho de um CAPTCHA, uma imagem SVG (texto XML)
// construída à mão

namespace App\Security;

class CaptchaDrawing
{
    public const WIDTH = 150;

    public const 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).
    private const 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
    private const COLORS = ['#1f4e79', '#7b2d26', '#2e6b30', '#5b2c83', '#8a5a00', '#23395d', '#9c2a5b'];

    // um texto aleatório. random_int é um gerador "criptográfico",
    // imprevisível (ao contrário de rand ou mt_rand, cuja sequência poderia ser adivinhada)
    public static function randomText(int $length): string
    {
        $alphabet = array_keys(self::FONT);
        $text = '';
        for ($i = 0; $i < $length; $i++) {
            $text .= $alphabet[random_int(0, count($alphabet) - 1)];
        }
        return $text;
    }

    // um número de ponto flutuante, aleatório, entre $minimum e $maximum
    private static function random(float $minimum, float $maximum): float
    {
        return $minimum + ($maximum - $minimum) * random_int(0, PHP_INT_MAX) / PHP_INT_MAX;
    }

    private static function color(): string
    {
        return self::COLORS[random_int(0, count(self::COLORS) - 1)];
    }

    public static function svg(string $text): string
    {
        $l = self::WIDTH;
        $h = self::HEIGHT;
        $pieces = ["<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"$l\" height=\"$h\" viewBox=\"0 0 $l $h\">",
            '<rect width="100%" height="100%" fill="#f5f7fa"/>'];

        // os caracteres: cada um ampliado, inclinado, deslocado, e cada ponto
        // levemente movido ao acaso
        $step = ($l - 20) / strlen($text);
        foreach (str_split($text) as $i => $character) {
            $scale = self::random(4.6, 5.6);    // tamanho de uma unidade da grade, em pixels
            $angle = self::random(-0.35, 0.35);   // rotação, em radianos (cerca de ±20°)
            $cx = 10 + $step * ($i + 0.5) + self::random(-3, 3);    // centro do caractere
            $cy = $h / 2 + self::random(-4, 4);
            foreach (self::FONT[$character] as $stroke) {
                $d = [];
                for ($k = 0; $k < count($stroke); $k += 2) {
                    // ponto da grade, centralizado em (2, 3), distorcido, girado, posicionado
                    $x = ($stroke[$k] - 2 + self::random(-0.2, 0.2)) * $scale;
                    $y = ($stroke[$k + 1] - 3 + self::random(-0.2, 0.2)) * $scale;
                    $px = $cx + $x * cos($angle) - $y * sin($angle);
                    $py = $cy + $x * sin($angle) + $y * cos($angle);
                    $d[] = sprintf('%s%.1f %.1f', $k === 0 ? 'M' : 'L', $px, $py);
                }
                $pieces[] = sprintf('<path d="%s" fill="none" stroke="%s" stroke-width="%.1f" '
                    .'stroke-linecap="round" stroke-linejoin="round"/>',
                    implode(' ', $d), self::color(), self::random(2.2, 3));
            }
        }

        // 3 linhas de embaralhamento: curvas que cruzam a imagem
        for ($n = 0; $n < 3; $n++) {
            $pieces[] = sprintf('<path d="M%.1f %.1f C%.1f %.1f %.1f %.1f %.1f %.1f" fill="none" '
                .'stroke="%s" stroke-width="1.3"/>',
                self::random(0, 20), self::random(5, 45), self::random(30, 60), self::random(0, 50),
                self::random(90, 120), self::random(0, 50), self::random(130, 150), self::random(5, 45),
                self::color());
        }
        $pieces[] = '</svg>';
        return implode('', $pieces);
    }
}

A imagem está no formato SVG (Scalable Vector Graphics): um desenho vetorial descrito em XML — ou seja, em texto — que o servidor gera sem uma biblioteca gráfica e que o navegador exibe diretamente na página. Esta classe é puro [PHP], sem nada específico de um framework: é a mesma da versão [Laravel] deste curso.

  • 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 aleatória escolhida 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 consegue 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 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) cruzam 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.

A classe [Captcha] combina o identificador de um CAPTCHA com sua imagem:

<?php
// src/Security/Captcha.php: um CAPTCHA: seu identificador e sua imagem (SVG)

namespace App\Security;

readonly class Captcha
{
    public function __construct(
        public string $id,
        public string $svg,
    ) {
    }
}

8.3.2. O serviço de CAPTCHA: src/Security/CaptchaService.php

<?php
// src/Security/CaptchaService.php: os CAPTCHAs pendentes, mantidos pelo servidor,
// no cache (veja o exemplo 20)

namespace App\Security;

use Psr\Cache\CacheItemPoolInterface;

class CaptchaService
{
    // o tempo de vida de um CAPTCHA, em segundos
    private const LIFETIME = 600;

    public function __construct(private CacheItemPoolInterface $cache)
    {
    }

    public function generate(): Captcha
    {
        $text = CaptchaDrawing::randomText(5);
        // um identificador aleatório, impossível de adivinhar: 12 bytes sorteados por um
        // gerador criptográfico (random_bytes), escritos em hexadecimal (bin2hex)
        $id = bin2hex(random_bytes(12));
        // a resposta esperada, no cache, por 10 minutos (expiresAfter): o
        // cache a esquecerá sozinho depois
        $item = $this->cache->getItem("captcha.$id");
        $this->cache->save($item->set($text)->expiresAfter(self::LIFETIME));
        return new Captcha($id, CaptchaDrawing::svg($text));
    }

    // o CAPTCHA é CONSUMIDO em todos os casos: uma imagem é usada uma única vez
    public function check(?string $id, ?string $answer): bool
    {
        // um identificador malformado não pode ser uma chave do cache
        if ($id === null || ! ctype_xdigit($id) || $answer === null) {
            return false;
        }
        $item = $this->cache->getItem("captcha.$id");
        // deleteItem: a resposta é removida do cache, esteja certa ou não
        $this->cache->deleteItem("captcha.$id");
        if (! $item->isHit()) {
            return false;    // identificador desconhecido, ou CAPTCHA expirado
        }
        // strcasecmp retorna 0 para duas strings iguais, sem diferenciar maiúsculas de minúsculas
        return strcasecmp($item->get(), trim($answer)) === 0;
    }
}
  • Linhas 18–29: um novo CAPTCHA: um texto aleatório, um identificador aleatório e impossível de adivinhar, e a imagem. Para cada identificador, o servidor armazena a resposta esperada no cache (exemplo 20) por dez minutos: o método [expiresAfter] do item de cache define seu tempo de vida em segundos. Passado esse tempo, o cache o descarta automaticamente. A página recebe apenas o identificador e a imagem: a resposta nunca sai do servidor;
  • linhas 32–46: a validação. O identificador vem do cliente: primeiro verificamos que ele é composto por dígitos hexadecimais ([ctype_xdigit]), já que certos caracteres ([{}()/\@:]) são proibidos em chaves de cache, o que lançaria uma exceção. O item é lido e depois removido do cache ([deleteItem]): 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. Limite de tentativas: config/packages/framework.yaml

# config/packages/framework.yaml: a configuração do FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # a sessão: ela é usada apenas para o token anti-CSRF do formulário de login
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    csrf_protection: true
    # os locks (veja o exemplo 20): o limiter os usa para contar sem erro
    # as tentativas simultâneas
    lock: 'flock://%kernel.project_dir%/var/lock'
    # os limiters de TAXA (componente RateLimiter); este, chamado [login],
    # aceita 3 "tokens" por janela de 60 segundos
    rate_limiter:
        login:
            policy: fixed_window
            limit: 3
            interval: '60 seconds'
  • linha 11: locks (exemplo 20): o limitador os utiliza para garantir que duas requisições simultâneas não distorçam sua contagem;
  • linhas 14–18: um limitador de taxa, chamado [login]. Um limitador de taxa distribui “tokens” (sem relação com o token JWT): cada ação restrita consome um e, quando não restam mais, a ação é negada. A política [fixed_window] (janela fixa) concede 3 tokens por período de 60 segundos, contados a partir do primeiro token consumido. Existem outras políticas: [sliding_window] (uma janela deslizante, mais regular) e [token_bucket] (um balde que se enche a uma taxa determinada). Os contadores são armazenados no cache da aplicação.

Para cada limitador declarado, o [Symfony] cria um serviço de fábrica de limitadores ([RateLimiterFactoryInterface]), que é obtido por injeção sob um nome de parâmetro formado pelo nome do limitador seguido de [Limiter]: [$loginLimiter].

8.3.4. O controller: src/Controller/AuthController.php

<?php
// src/Controller/AuthController.php: login (com CAPTCHA e limitação das
// tentativas) e logout

namespace App\Controller;

use App\Security\AuthService;
use App\Security\CaptchaService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;
use Symfony\Component\Routing\Attribute\Route;

class AuthController extends AbstractController
{
    // $loginLimiter: a factory do limiter [login] (veja config/packages/framework.yaml);
    // o nome do parâmetro designa o limiter
    public function __construct(
        private AuthService $auth,
        private CaptchaService $captchas,
        private RateLimiterFactoryInterface $loginLimiter,
    ) {
    }

    #[Route('/', methods: ['GET'])]
    public function home(): Response
    {
        return $this->redirect('/profile');
    }

    #[Route('/login', methods: ['GET'])]
    public function form(): Response
    {
        return $this->loginPage();
    }

    #[Route('/login', methods: ['POST'])]
    public function login(Request $request): Response
    {
        $inputs = $request->getPayload();
        if (! $this->isCsrfTokenValid('login', $inputs->getString('_csrf_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        $login = $inputs->getString('login');
        // o limiter DESTE cliente: a chave de seu contador de falhas é seu endereço IP
        $limiter = $this->loginLimiter->create($request->getClientIp());

        // 1. um endereço bloqueado nem chega a ser atendido; consume(0) consulta o
        // contador sem consumir nada
        $state = $limiter->consume(0);
        if ($state->getRemainingTokens() === 0) {
            $seconds = $state->getRetryAfter()->getTimestamp() - time();
            return $this->loginPage($login, "Too many attempts: try again in $seconds s.");
        }
        // 2. primeiro o CAPTCHA (barato), depois a senha (bcrypt, caro);
        // consume(): mais uma falha
        if (! $this->captchas->check($inputs->getString('captchaId'), $inputs->getString('captcha'))) {
            $limiter->consume();
            return $this->loginPage($login, 'The image code is incorrect.');
        }
        $user = $this->auth->validate($login, $inputs->getString('password'));
        if ($user === null) {
            $limiter->consume();
            return $this->loginPage($login, 'Incorrect login or password.');
        }
        // um login bem-sucedido apaga as falhas
        $limiter->reset();
        $response = $this->redirect('/profile');
        $response->headers->setCookie(Cookie::create(AuthService::COOKIE, $this->auth->createToken($user))
            ->withExpires(time() + $this->auth->durationMinutes * 60)
            ->withHttpOnly(true)
            ->withSameSite(Cookie::SAMESITE_LAX));
        return $response;
    }

    #[Route('/logout', methods: ['POST'])]
    public function logout(Request $request): Response
    {
        if (! $this->isCsrfTokenValid('logout', $request->getPayload()->getString('_csrf_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        $response = $this->redirect('/login');
        $response->headers->clearCookie(AuthService::COOKIE);
        return $response;
    }

    // cada exibição do formulário constrói um NOVO CAPTCHA
    private function loginPage(?string $login = null, ?string $error = null): Response
    {
        return $this->render('auth/login.html.twig', ['login' => $login, 'error' => $error,
            'captcha' => $this->captchas->generate()]);
    }
}
  • linhas 21–26: o controller recebe a fábrica do limitador [login];
  • linha 49: o limitador deste cliente, [create(key)], retorna um limitador que tem seu próprio contador sob essa chave — neste caso, o endereço IP do cliente ([getClientIp()]);
  • linhas 53–57: um endereço bloqueado nem sequer é ouvido. [consume(0)] consulta o limitador sem consumir nada; o objeto [RateLimit] que ele retorna fornece o número de tokens restantes ([getRemainingTokens()]) e a data em que a ação voltará a ser permitida ([getRetryAfter()]), da qual podemos deduzir o número de segundos de espera;
  • Linhas 60–68: o CAPTCHA é verificado antes da senha; verificá-lo custa quase nada, ao passo que o [bcrypt] é intencionalmente lento. Um programa que digite o CAPTCHA errado, portanto, não acionaria o [bcrypt]. Cada falha — seja do CAPTCHA ou da senha — consome um token ([consume()], que consome um por padrão). Após a terceira falha, não restam tokens: o endereço fica bloqueado até o fim da janela de 60 segundos, contada a partir da primeira falha;
  • linha 70: um login bem-sucedido zera as tentativas malsucedidas ([reset()]);
  • linhas 91–95: a cada exibição do formulário, um novo CAPTCHA é gerado, mesmo após uma tentativa malsucedida.

O SecurityBundle também oferece um limite de conexão integrado (a opção de firewall [login_throttling] ), que se aplica aos seus próprios autenticadores de login ([form_login]...), e não à nossa ação. Para limitar o número de requisições a uma rota, usaríamos um limitador da mesma maneira, seja dentro da ação, seja em um listener de [kernel.request]. Optamos por contar apenas as tentativas malsucedidas, para não incomodar um usuário que faz login normalmente.

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

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Login</h1>
  <form method="post" action="/login">
    <input type="hidden" name="_csrf_token" value="{{ csrf_token('login') }}">
    <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 raw) #}
      <div class="mb-1">{{ captcha.svg|raw }}</div>
      {# o identificador do captcha viaja em um campo oculto; a resposta fica no servidor #}
      <input type="hidden" name="captchaId" value="{{ captcha.id }}">
      <input class="form-control" id="captcha" name="captcha" autocomplete="off" required>
    </div>
    <button class="btn btn-primary" type="submit">Log in</button>
  </form>
  {% if error %}
    <div class="alert alert-danger mt-3">{{ error }}</div>
  {% endif %}
  <p class="text-muted small mt-3">Test accounts (password = login): marie (USER), admin (ADMIN).</p>
{% endblock %}
  • Linha 18: a imagem SVG é inserida na página como está, sem escape (filtro [raw], exemplo 14). Isso é legítimo: esse HTML foi gerado pelo servidor e 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 nenhuma entrada anterior para este campo.

8.3.6. Execução

Image

Um código copiado incorretamente:

Image

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

Image

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

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

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