Skip to content

8. Autenticación y autorización

Para cada solicitud surgen dos preguntas distintas:

  • ¿Quién es el usuario? Esto es la autenticación: el usuario se ha identificado con un nombre de usuario y una contraseña, y cada solicitud posterior debe demostrar que proviene de él;
  • ¿Tiene permiso para acceder a esta página? Esto es la autorización: en el caso de estudio, solo un usuario con el rol ADMIN administra los médicos y los clientes.

La prueba de identidad debe incluirse en cada solicitud. [Symfony] normalmente almacena al usuario conectado en su sesión (véase la sección sobre los ámbitos), que es la solución más simple para una aplicación web. En cambio, el caso de estudio, en todas sus versiones ([ASP.NET Core MVC], [Spring MVC], [NestJS], [Flask], [Laravel]), utiliza un token (JWT, JSON Web Token), que usaremos aquí: después del inicio de sesión, el servidor genera un token que contiene la identidad del usuario y lo firma con una clave secreta (este es el principio de la cookie firmada del Ejemplo 23). El token se almacena en una cookie; el navegador la reenvía con cada solicitud; el servidor verifica la firma. El usuario puede leer su token, pero no modificarlo: cualquier modificación invalida la firma. El formato está estandarizado (RFC 7519), lo entienden todos los lenguajes de programación y el token incluye su fecha de expiración. Lo más importante es que el servidor no necesita almacenar nada: cualquier servidor que conozca la clave puede verificar el token.

[Symfony] tiene un componente de seguridad completo, integrado por SecurityBundle, cuyos elementos usaremos tal cual:

  • las URL de la aplicación se distribuyen entre cortafuegos (firewalls), cada uno con su propio método de autenticación de usuarios;
  • la autenticación está a cargo de los autenticadores (authenticators): objetos que determinan la identidad del usuario en cada solicitud. [Symfony] proporciona varios (formulario de inicio de sesión, sesión, token de API, etc.); escribiremos el nuestro, que lee el token JWT. El resto de la aplicación solo ve el resultado: el usuario autenticado, proporcionado por [#[CurrentUser]], [$this->getUser()] y, en las vistas, [app.user];
  • los usuarios los proporciona un proveedor de usuarios, y sus contraseñas se procesan con hash mediante el componente PasswordHasher (algoritmo [bcrypt]);
  • las autorizaciones se basan en roles: la protección de las páginas se describe mediante reglas de control de acceso ([access_control]) o mediante el atributo [#[IsGranted]] de las acciones; las vistas comprueban un derecho mediante [is_granted];
  • Los intentos de inicio de sesión están limitados por el componente RateLimiter (Ejemplo 27).

Todo esto lo realizan los listeners de eventos del kernel (capítulo anterior): el cortafuegos escucha [kernel.request] (prioridad 8), [#[IsGranted]] se lee en [kernel.controller_arguments] y las denegaciones de acceso son excepciones, gestionadas en [kernel.exception].

La generación y la verificación de tokens las realiza la biblioteca [firebase/php-jwt], la más utilizada en [PHP], instalada por el archivo [composer.json] de los ejemplos. (Existe un bundle muy utilizado para tokens —JWT y [LexikJWTAuthenticationBundle]— diseñado para API; para una aplicación web bastan unas pocas líneas, que ilustran mejor el mecanismo.)

8.1. Ejemplo 25: inicio de sesión, 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. Configuración: .env, bundles.php y framework.yaml

El token se firma con una clave secreta, que no debe estar codificada en el código. Es hora de separar realmente la configuración del código. Los ajustes específicos de una instalación están en el archivo [.env] (Ejemplo 01), que ahora contiene tres líneas nuevas (un comentario, seguido de dos variables):

1
2
3
4
5
6
# .env: la configuración del ejemplo 25 (véase el ejemplo 01)
APP_ENV=dev
APP_SECRET=6144ddf9f821deebee2291ab7742d7a9
# la clave que firma los tokens JWT (al menos 32 caracteres), y su duración
JWT_SECRET=a-secret-key-of-at-least-32-characters-for-example-25
JWT_DURATION_MINUTES=60

El estándar exige que el algoritmo utilizado (HMAC-SHA256) tenga una clave de al menos 256 bits, es decir, 32 bytes; la biblioteca rechaza cualquier clave más corta. El código en sí no lee directamente el archivo [.env]: el componente [Dotenv] (ejemplo 01) lo ha convertido en variables de entorno, que el contenedor proporciona a los servicios que las solicitan (lo veremos con el servicio [AuthService]). Una variable de entorno real tiene prioridad sobre el archivo [.env]: en [Linux] o [macOS], la aplicación se iniciaría con una clave diferente de la siguiente manera:

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

y en [Windows] (PowerShell):

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

(La opción [-d variables_order=EGPCS] indica a [PHP] que llene el arreglo [$_ENV] con las variables de entorno, lo que su configuración predeterminada no siempre hace.) En producción, los secretos suelen confiarse a la bóveda de [Symfony] (secrets vault, comando [bin/console secrets:set]), que los almacena cifrados dentro del proyecto.

SecurityBundle se agrega a la lista de bundles:

1
2
3
4
5
6
7
8
<?php
// config/bundles.php: los bundles de la aplicación; el SecurityBundle integra
// el componente de seguridad (autenticación, autorización)
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
];

La sesión se utiliza aquí únicamente para el token anti-CSRF del formulario de inicio de sesión (Ejemplo 21):

1
2
3
4
5
6
7
8
# config/packages/framework.yaml: la configuración del FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # la sesión: solo se usa para el token anti-CSRF del formulario de inicio de sesión
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    csrf_protection: true

8.1.2. Configuración de seguridad: config/packages/security.yaml

# config/packages/security.yaml: la configuración del SecurityBundle
security:
    # el hash de las contraseñas de los usuarios de la clase User: bcrypt
    password_hashers:
        App\Security\User:
            algorithm: bcrypt

    # el PROVEEDOR de usuarios: el objeto que encuentra a un usuario a partir de su login
    providers:
        users:
            id: App\Security\UsersService

    # los FIREWALLS: cada uno protege las URL que coinciden con su patrón
    firewalls:
        # los archivos de Bootstrap: sin seguridad
        resources:
            pattern: ^/bootstrap/
            security: false
        # todas las demás URL
        main:
            # stateless: el usuario no se almacena en la sesión, se
            # vuelve a encontrar en cada solicitud, a partir de su token
            stateless: true
            provider: users
            # el autenticador: lee el token de la cookie, en cada solicitud
            custom_authenticators:
                - App\Security\TokenAuthenticator

    # el CONTROL DE ACCESO: las URL que comienzan con /profile requieren un
    # usuario autenticado; las demás son públicas
    access_control:
        - { path: ^/profile, roles: IS_AUTHENTICATED }
  • líneas 4–6: el algoritmo de hash de contraseñas para los usuarios de la clase [User]: [bcrypt]. (El valor [auto] seleccionaría el mejor algoritmo disponible y podría verificar hashes de otros algoritmos);
  • líneas 9–11: el proveedor de usuarios, el servicio que encuentra a un usuario a partir de su ID (aquí, nuestra clase [UsersService]). [Symfony] proporciona varios: [memory] (una lista escrita en este archivo), [entity] (una tabla de base de datos; véase el caso de estudio)...;
  • Líneas 14–27: los cortafuegos. Cada uno se aplica a las entradas de URL que coinciden con su patrón ([pattern]), y se selecciona la primera entrada que coincide. El primero, [resources], cubre los archivos de [Bootstrap] (Ejemplo 15), sin seguridad ([security: false]): no hay necesidad de buscar un usuario para servir una hoja de estilos. El segundo, [main], no tiene un motivo específico: cubre todas las demás URL;
  • línea 23: el cortafuegos es sin estado (stateless): el usuario autenticado no se almacena en la sesión; se le identifica en cada solicitud a partir de su token;
  • Líneas 26–27: el autenticador del cortafuegos, nuestra clase [TokenAuthenticator];
  • Líneas 31–32: control de acceso: una lista de reglas, examinadas en orden, de las cuales se aplica la primera que corresponde a la URL. Las URL que comienzan con [/profile] requieren un usuario autenticado ([IS_AUTHENTICATED]); las demás son públicas.

En un proyecto estándar, este archivo lo escribe [Symfony Flex] cuando se instala el bundle ([composer require security]), y el comando [bin/console make:user] de [MakerBundle] escribe la clase de usuario y su proveedor.

8.1.3. Usuarios: src/Security/User.php y UsersService.php

<?php
// src/Security/User.php: un usuario. UserInterface: la interfaz que
// Symfony espera de los usuarios autenticados; PasswordAuthenticatedUserInterface:
// un usuario que tiene una contraseña

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,
        // el rol: USER o ADMIN
        public string $role,
        // el HASH de la contraseña (vacío para un usuario leído a partir de un token)
        public string $passwordHash = '',
        // el contenido del token que autenticó al usuario
        public array $claims = [],
    ) {
    }

    // el identificador del usuario: su login
    public function getUserIdentifier(): string
    {
        return $this->login;
    }

    // los roles, en el sentido de Symfony: cadenas que comienzan con ROLE_
    public function getRoles(): array
    {
        return ['ROLE_'.$this->role];
    }

    public function getPassword(): string
    {
        return $this->passwordHash;
    }
}
  • Línea 11: un usuario. [Symfony] espera que los usuarios autenticados implementen la interfaz [UserInterface]: sus métodos le proporcionan el identificador y los roles del usuario. La interfaz [PasswordAuthenticatedUserInterface] añade la contraseña con hash. En una aplicación típica, la entidad [Doctrine] de la tabla de usuarios (próximo capítulo) implementa estos métodos;
  • Líneas 13–23: el inicio de sesión, el nombre, el rol, el hash de la contraseña y el contenido del token que autenticó al usuario (vacío para un usuario recuperado de la lista de usuarios). Un servidor nunca almacena una contraseña, ni siquiera cifrada: si la base de datos fuera robada, las contraseñas también lo serían (y muchas personas usan la misma contraseña en todas partes). Almacena el resultado de una función hash, una función unidireccional: se puede calcular el hash de una contraseña, pero no es posible recuperar la contraseña a partir de su hash. Para verificar una contraseña ingresada, se calcula su hash y se compara con el almacenado;
  • líneas 32–35: roles, tal como los define [Symfony]: cadenas que comienzan con [ROLE_]. El rol [USER] del caso de estudio se convierte en [ROLE_USER].
<?php
// src/Security/UsersService.php: los usuarios, en memoria (el ejemplo 28
// y el caso de estudio los pondrán en una base de datos). UserProviderInterface: un
// PROVEEDOR de usuarios, en el sentido de Symfony (véase 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 una contraseña, solo su hash bcrypt, calculado
    // una vez por todas con: 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);
    }

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

    // el usuario almacenado en la sesión, por recargar: nunca se invoca aquí,
    // ya que el firewall es stateless
    public function refreshUser(UserInterface $user): UserInterface
    {
        throw new UnsupportedUserException();
    }

    public function supportsClass(string $class): bool
    {
        return $class === User::class;
    }
}
  • Líneas 17–20: dos usuarios de prueba, definidos directamente en el código (el ejemplo 28 y el caso de estudio los almacenarán en una base de datos): para cada inicio de sesión, el nombre, el rol y el hash de la contraseña. El hash se genera con el algoritmo bcrypt, diseñado para contraseñas. Tiene dos características distintivas. Es deliberadamente lento, con un nivel de lentitud ajustable (el costo, aquí fijado en 10: 2^10 ciclos de cálculo, lo que da como resultado el hash [$10$]): unas pocas decenas de milisegundos, imperceptibles para un usuario, pero que hacen muy costoso para un atacante probar miles de millones de contraseñas. Es con sal: una sal generada aleatoriamente se mezcla con la contraseña antes de aplicar el hash y se almacena dentro del propio hash (los 22 caracteres que siguen a [$10$]); así, dos usuarios con la misma contraseña tendrán hashes diferentes. Los hashes se calcularon una vez por todas con la función [password_hash] de [PHP] (línea 16), o con el comando [bin/console security:hash-password] de [Symfony]: calcularlos en cada solicitud sería una pérdida de tiempo innecesaria, ya que la aplicación se reconstruye con cada solicitud. [bcrypt] solo tiene en cuenta los primeros 72 bytes de una contraseña: el caso de estudio lo tiene en cuenta;
  • líneas 22–29: el usuario de un inicio de sesión, o [null]. [isset] verifica la existencia de una clave; la asignación [[$name, $role, $hash] = ...] desestructura un arreglo: cada variable recibe el elemento correspondiente;
  • líneas 32–47: los tres métodos de la interfaz [UserProviderInterface], que convierten la clase en un proveedor de usuarios: [loadUserByIdentifier] devuelve el usuario asociado a un identificador, o lanza la excepción [UserNotFoundException]; [refreshUser] recarga el usuario almacenado en la sesión (innecesario con un firewall sin estado); [supportsClass] especifica la clase de los usuarios proporcionados. El operador [??] seguido de [throw] lanza la excepción cuando la expresión del lado izquierdo se evalúa como [null].

8.1.4. El servicio de autenticación: src/Security/AuthService.php

<?php
// src/Security/AuthService.php: la verificación de las contraseñas y de los 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
{
    // el nombre de la cookie que lleva el token
    public const COOKIE = 'token';

    public function __construct(
        private UsersService $users,
        // el servicio de hash de contraseñas (véase config/packages/security.yaml)
        private UserPasswordHasherInterface $hasher,
        // #[Autowire(env: ...)]: el valor de una variable de entorno (archivo .env);
        // el prefijo int: lo convierte en un entero
        #[Autowire(env: 'JWT_SECRET')] private string $secret,
        #[Autowire(env: 'int:JWT_DURATION_MINUTES')] public readonly int $durationMinutes,
    ) {
    }

    // el usuario, o null si el login es desconocido o la contraseña es incorrecta.
    // isPasswordValid aplica el hash a la contraseña ingresada con la sal del hash almacenado,
    // y luego compara los dos 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;
    }

    // el token JWT del usuario, firmado con la clave secreta (HMAC-SHA256)
    public function createToken(User $user): string
    {
        $now = time();
        // el contenido del token: los "claims" (afirmaciones sobre el usuario)
        $claims = [
            'sub' => $user->login,
            'name' => $user->name,
            'role' => $user->role,
            'iat' => $now,
            'exp' => $now + $this->durationMinutes * 60,
        ];
        return JWT::encode($claims, $this->secret, 'HS256');
    }

    // el usuario descrito por un token cuya firma y fecha de expiración
    // son válidas; null en caso contrario (token falsificado, expirado o ilegible)
    public function check(string $token): ?User
    {
        try {
            // decode devuelve un objeto; (array) lo convierte en un arreglo asociativo
            $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);
    }
}
  • Líneas 17–26: el servicio recibe el proveedor de usuarios, el servicio de hash de contraseñas ([UserPasswordHasherInterface], que aplica el algoritmo seleccionado en [security.yaml]) y dos valores de configuración. El atributo [#[Autowire(env: 'NAME')]] proporciona el valor de una variable de entorno; un prefijo lo convierte: [int:] a entero (hay otros: [bool:], [json:], [base64:]...). La duración de vida es una propiedad pública de solo lectura: el controlador la usará;
  • líneas 31–41: verificación de un nombre de usuario y una contraseña. [isPasswordValid] calcula el hash de la contraseña ingresada usando la sal del hash almacenado y compara los dos hashes. Un nombre de usuario desconocido y una contraseña incorrecta producen el mismo resultado, [null];
  • Líneas 44–56: generación del token. El token contiene un arreglo de afirmaciones (claims) sobre el usuario. Algunas tienen nombres estandarizados: [sub] (subject), el identificador del usuario; [iat] (issued at), la fecha de creación; [exp] (expiration), la fecha de expiración. Las fechas se expresan en segundos transcurridos desde el 1 de enero de 1970 (la función [time()] de [PHP]). Los demás campos son opcionales: aquí, el nombre y el rol. [JWT::encode] genera el token y lo firma con el algoritmo [HS256] (HMAC-SHA256, una firma con una clave secreta compartida);
  • líneas 60–69: verificación del token. [JWT::decode] verifica la firma y la fecha de expiración, y luego devuelve las afirmaciones (un objeto, convertido en arreglo mediante [(array)]). Cualquier anomalía (token falsificado, expirado o mal formado) lanza una excepción; [catch (Throwable)] las captura todas ([Throwable] es la interfaz de todas las excepciones y errores de [PHP]; el nombre de la variable es opcional cuando no se usa). El objeto [Key] asocia la clave con un algoritmo: un token que especifique un algoritmo diferente (o ninguno, [none]) sería rechazado. El token válido se convierte en un [User], sin hash, junto con sus claims (parámetro llamado [claims]).

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

<?php
// src/Security/TokenAuthenticator.php: el AUTENTICADOR del firewall (véase
// config/packages/security.yaml): en cada solicitud, establece quién es el usuario,
// a partir del token JWT de la 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)
    {
    }

    // el autenticador actúa solo si la solicitud lleva la cookie del token;
    // de lo contrario, el visitante permanece anónimo
    public function supports(Request $request): ?bool
    {
        return $request->cookies->has(AuthService::COOKIE);
    }

    // el PASAPORTE del usuario: quién es (la credencial), y cómo verificarlo.
    // El token ya fue verificado: el pasaporte se valida a sí mismo (SelfValidatingPassport)
    public function authenticate(Request $request): Passport
    {
        $user = $this->auth->check($request->cookies->get(AuthService::COOKIE));
        if ($user === null) {
            throw new CustomUserMessageAuthenticationException('invalid token');
        }
        // la credencial: el login, y una función que devuelve al usuario (aquí, el del
        // token, sin consultar la lista de usuarios)
        return new SelfValidatingPassport(new UserBadge($user->login, fn () => $user));
    }

    // un token válido: null, la solicitud continúa su camino hacia la acción
    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
    {
        return null;
    }

    // un token inválido (expirado, falsificado): se envía a /login, y eliminamos la cookie
    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
    {
        $response = new RedirectResponse('/login');
        $response->headers->clearCookie(AuthService::COOKIE);
        return $response;
    }

    // el PUNTO DE ENTRADA: la respuesta dada a un visitante anónimo que solicita una
    // página protegida; aquí, una redirección a la página de inicio de sesión
    public function start(Request $request, ?AuthenticationException $authException = null): Response
    {
        return new RedirectResponse('/login');
    }
}

Para cada solicitud que pasa por el firewall, [Symfony] llama a los métodos del autenticador en este orden:

  • líneas 28–31: [supports]: ¿participa el autenticador en esta solicitud? Sí, si contiene la cookie del token. De lo contrario, no ocurre nada: el visitante sigue siendo anónimo;
  • líneas 35–44: [authenticate] construye un pasaporte: la identidad del usuario (una credencial, [UserBadge]) y las credenciales que se deben verificar. Un formulario de inicio de sesión estándar incluiría la contraseña ingresada en el pasaporte, que [Symfony] verificaría por sí mismo. Aquí, la prueba es el token, ya verificado por [AuthService]: el pasaporte se valida a sí mismo ([SelfValidatingPassport]). La credencial contiene el inicio de sesión y una función que identifica al usuario: en este caso, el usuario descrito por el token, sin consultar la lista de usuarios (sin esta función, [Symfony] solicitaría el usuario al proveedor). Un token no válido lanza una excepción de autenticación;
  • líneas 47–50: [onAuthenticationSuccess]: la autenticación se realizó con éxito. Devolver [null] permite que la solicitud llegue a la acción con un usuario autenticado. (Un formulario de inicio de sesión redirigiría aquí a la página de inicio);
  • líneas 53–58: [onAuthenticationFailure]: la autenticación falló (token expirado o falsificado). La respuesta redirige a la página de inicio de sesión y aprovecha para borrar la cookie: [clearCookie] agrega a la respuesta una cookie vacía y ya expirada;
  • líneas 62–65: [start] es el método de la interfaz [AuthenticationEntryPointInterface]: el punto de entrada del firewall, es decir, la respuesta enviada a un visitante anónimo que solicita una página protegida. En este caso, una redirección a la página de inicio de sesión.

El autenticador no deniega el acceso: determina quién es el usuario, o determina que el usuario es anónimo. Esto es la autenticación. Las denegaciones son responsabilidad del control de acceso.

8.1.6. Los controladores

<?php
// src/Controller/AuthController.php: inicio y cierre de sesión

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
    {
        // el token anti-CSRF del formulario (véase el ejemplo 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) {
            // un mensaje deliberadamente vago: no decimos si es el login o la contraseña
            return $this->render('auth/login.html.twig', ['login' => $login,
                'error' => 'Incorrect login or password.']);
        }
        // el token, en una cookie: el JavaScript de la página no puede leerlo
        // (httpOnly); no viaja con las solicitudes POST provenientes de otros sitios
        // (sameSite); desaparece al mismo tiempo que expira el token
        $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;
    }

    // cierre de sesión: solo POST (un simple enlace, colocado en otro sitio, no puede
    // cerrar la sesión del usuario sin que se entere); eliminamos la 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;
    }
}
  • líneas 36–38: el formulario de inicio de sesión está protegido contra solicitudes falsificadas, como todos los formularios (ejemplo 21);
  • líneas 40–45: el proceso de inicio de sesión. Si falla, el formulario se vuelve a mostrar con el nombre de usuario ingresado y un mensaje deliberadamente vago: decir «nombre de usuario desconocido» revelaría a un atacante qué nombres de usuario existen;
  • Líneas 49–54: si tiene éxito, el token se almacena en una cookie y el usuario es redirigido a la página protegida (patrón PRG). La cookie es [httpOnly]: el [JavaScript] de la página no puede leerla, lo que protege el token contra la inyección de scripts (XSS); es [SameSite=Lax]: el navegador no la envía con una solicitud POST proveniente de otro sitio, lo que protege la aplicación contra ataques CSRF; su fecha de expiración ([withExpires], aquí un número de segundos desde 1970) es la misma que la del token. En producción, con HTTPS, se agregaría [withSecure(true)]: la cookie nunca se enviaría a través de una conexión sin cifrar;
  • Líneas 59–68: cerrar sesión elimina la cookie ([clearCookie]). Es una acción POST, protegida por un token anti-CSRF: un simple enlace a [/logout], colocado en otro sitio o dentro de una imagen, no puede cerrar la sesión del usuario sin que este lo sepa. Cabe señalar una limitación de los tokens: el token en sí sigue siendo válido hasta que expira. Alguien que haya hecho una copia podría seguir usándolo. Por eso su duración de vida es limitada.

[Symfony] también puede gestionar por sí solo el inicio de sesión mediante formulario (el autenticador [form_login]) y el cierre de sesión (la opción de firewall [logout] ); pero almacenan al usuario en la sesión, mientras que nosotros queremos un token.

<?php
// src/Controller/ProfileController.php: una página reservada para usuarios autenticados
// (véase access_control en 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]: el usuario autenticado de la solicitud, el que encontró
    // el autenticador
    #[Route('/profile', methods: ['GET'])]
    public function display(#[CurrentUser] User $user): Response
    {
        return $this->render('profile/profile.html.twig', ['user' => $user]);
    }
}
  • línea 18: el atributo [#[CurrentUser]] proporciona el usuario autenticado, el establecido por el autenticador. La acción está protegida por la regla [access_control] de [security.yaml]: se garantiza que recibirá un usuario. También lo obtendríamos mediante [$this->getUser()].

8.1.7. Las vistas

{% 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 %}
  • línea 6: el token anti-CSRF del formulario (ejemplo 21);
  • línea 9: el inicio de sesión ingresado se vuelve a mostrar después de un fallo ([??]: una cadena vacía cuando la variable [login] no 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>
  {# cierre de sesión: un formulario POST reducido a su botón #}
  <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 %}
  • líneas 8–10: el contenido del token, mostrado con fines ilustrativos. Un bucle [for] de [Twig] puede recorrer las claves y los valores de un arreglo asociativo ([for key, value in ...]);
  • líneas 13–16: cierre de sesión, mediante un formulario reducido a un solo botón.

El usuario autenticado también está disponible en todas las vistas con el nombre [app.user].

8.1.8. Ejecución

Solicitemos la página protegida [/profile] sin haber iniciado sesión:

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

Una contraseña incorrecta:

Image

Inicio de sesión exitoso. Con [curl], primero se debe solicitar el formulario para obtener el token anti-CSRF y la cookie de sesión (ejemplo 21), y luego enviar el formulario conservando la cookie recibida:

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

El token consta de tres partes, separadas por puntos, cada una codificada en Base64: el encabezado, el contenido y la firma. Las dos primeras partes se pueden decodificar sin ninguna clave:

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

(La [é] se escribe en su forma escapada en JSON, [\u00e9].) El tiempo de expiración es de una hora (3600 segundos) después de la creación. En el navegador, la página de perfil muestra este mismo contenido:

Image

Un usuario malintencionado modifica su token: reemplaza el rol ***[USER]*** por ***[ADMIN]*** en el contenido, vuelve a codificar esta parte en Base64 y conserva la firma original. El servidor recalcula la firma del contenido modificado, que ya no coincide:

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

El token falsificado es rechazado y eliminado (el valor [deleted] y la fecha expirada le indican al navegador que elimine la cookie). Para generar una firma válida, habría que conocer la clave secreta; de ahí la importancia de mantenerla en secreto y de elegir una clave larga y aleatoria.

8.2. Ejemplo 26: roles

El ejemplo 26 agrega una página de administración, restringida al rol ADMIN. Solo se muestran los archivos nuevos o modificados.

8.2.1. La configuración: config/packages/security.yaml

# config/packages/security.yaml: la configuración del SecurityBundle (véase el ejemplo 25)
security:
    password_hashers:
        App\Security\User:
            algorithm: bcrypt

    providers:
        users:
            id: App\Security\UsersService

    # la JERARQUÍA de los roles: un administrador tiene también los derechos de un usuario
    role_hierarchy:
        ROLE_ADMIN: ROLE_USER

    firewalls:
        resources:
            pattern: ^/bootstrap/
            security: false
        main:
            stateless: true
            provider: users
            custom_authenticators:
                - App\Security\TokenAuthenticator
            # un usuario autenticado, pero que no tiene el derecho solicitado: nuestra página 403
            access_denied_handler: App\Security\AccessDenied

    # /profile: cualquier usuario autenticado; /admin está protegido por el #[IsGranted]
    # atributo de su controlador; podríamos haber escrito aquí:
    # - { path: ^/admin, roles: ROLE_ADMIN }
    access_control:
        - { path: ^/profile, roles: IS_AUTHENTICATED }
  • Líneas 12–13: la jerarquía de roles: el rol [ROLE_ADMIN] incluye el rol [ROLE_USER]. Un administrador tiene así todos los derechos de un usuario sin necesidad de que se le asignen ambos roles;
  • Línea 25: el controlador de acceso denegado del firewall ([access_denied_handler]): la clase que genera la respuesta enviada a un usuario autenticado que solicita una página que no está autorizado a ver;
  • Líneas 27–31: la página [/admin] podría protegerse aquí con una regla adicional; en cambio, la protegemos en su controlador para demostrar un enfoque alternativo.

La diferencia entre las dos respuestas de denegación es importante: un visitante anónimo que solicita una página protegida es redirigido al punto de entrada del firewall (la página de inicio de sesión, ejemplo 25); un usuario autenticado que no tiene el rol requerido recibe un error 403 (Forbidden): iniciar sesión sería inútil, ya que ya está autenticado.

8.2.2. Acceso denegado: src/Security/AccessDenied.php

<?php
// src/Security/AccessDenied.php: la respuesta dada a un usuario AUTENTICADO que
// solicita una página que le está prohibida (véase access_denied_handler en 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);
    }
}
  • línea 13: la clase implementa la interfaz [AccessDeniedHandlerInterface], cuyo único método, [handle], devuelve la respuesta de denegación;
  • línea 21: la página de error 403, generada por [Twig] (como el listener [ErrorPage] del ejemplo 24), con el código 403 ([Response::HTTP_FORBIDDEN], una constante de la clase [Response]).

Sin este controlador, la denegación daría lugar a una excepción [AccessDeniedHttpException], y el usuario vería la página de error 403 de [Symfony] (detallada en modo de depuración). La página [templates/errors/403.html.twig] es una página de error estándar, con un enlace de regreso al perfil.

8.2.3. El controlador: src/Controller/AdminController.php

<?php
// src/Controller/AdminController.php: una página reservada para el rol 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]: la acción se ejecuta solo si el usuario tiene el rol 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]);
    }
}
  • Línea 17: el atributo [#[IsGranted]] permite que la acción solo la ejecute un usuario que tenga el permiso requerido, en este caso el rol [ROLE_ADMIN]. Un visitante anónimo es redirigido al punto de entrada; a un usuario autenticado sin este rol se le deniega el acceso. Si se aplica a la clase, el atributo protegería todas sus acciones.

El controlador no realiza ninguna verificación por sí mismo. En el código, un permiso se verificaría mediante [$this->isGranted('ROLE_ADMIN')] (que devuelve un booleano) o [$this->denyAccessUnlessGranted('ROLE_ADMIN')] (que lanza una excepción de denegación). Para reglas más granulares que un rol («un usuario solo puede editar sus propias citas»), [Symfony] permite definir «voters» (voters): clases que determinan un permiso, que [#[IsGranted]] y [is_granted] consultan como si fueran roles.

8.2.4. La vista del 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: ¿el usuario tiene este rol? El bloque se muestra solo en ese 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>
  {# cierre de sesión: un formulario POST reducido a su botón #}
  <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 %}
  • Líneas 7–11: la función [is_granted] de [Twig] verifica el permiso de un usuario. Esto evita mostrar un enlace que conduciría a un error; sin embargo, es solo una comodidad: la protección real proviene de la propia acción.

8.2.5. Ejecución

Marie, con el rol USER, sigue el enlace a la página de administración:

Image

El administrador, en cambio, tiene acceso a ella:

Image

Con [curl]: un usuario con el rol USER (que inició sesión como en el ejemplo 25, con las cookies almacenadas en el archivo [token.txt]), seguido de un 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 las rutas una por una tiene un defecto: si se olvida una, la página queda accesible para todos. El caso de estudio invertirá esta lógica: todas las páginas URL están protegidas por defecto mediante una regla [access_control] general, y solo unas pocas páginas URL (la página de inicio de sesión, la página de registro) están exentas.

8.3. Ejemplo 27: CAPTCHA y límites de intentos

Un formulario de inicio de sesión es un objetivo: un programa puede probar miles de contraseñas por minuto (ataque de fuerza bruta). Dos protecciones se complementan:

  • un CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart): una imagen que contiene un código distorsionado, fácil de leer para un ser humano pero difícil para un programa;
  • un límite de intentos: después de tres intentos fallidos, la dirección IP del cliente se bloquea durante un minuto.

El ejemplo 27 se basa en el ejemplo 25 y agrega estas dos medidas de seguridad.

8.3.1. La imagen CAPTCHA: src/Security/CaptchaDrawing.php

<?php
// src/Security/CaptchaDrawing.php: el dibujo de un CAPTCHA, una imagen SVG (texto XML)
// construida a mano

namespace App\Security;

class CaptchaDrawing
{
    public const WIDTH = 150;

    public const HEIGHT = 50;

    // La "fuente": cada carácter es una lista de trazos, cada trazo una
    // secuencia de puntos x, y en una cuadrícula de 4 x 6 (y hacia abajo).
    // Caracteres demasiado fáciles de confundir entre sí: excluidos (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]],
    ];

    // algunos colores oscuros, fáciles de leer sobre el fondo claro
    private const COLORS = ['#1f4e79', '#7b2d26', '#2e6b30', '#5b2c83', '#8a5a00', '#23395d', '#9c2a5b'];

    // un texto aleatorio. random_int es un generador "criptográfico",
    // impredecible (a diferencia de rand o mt_rand, cuya secuencia podría adivinarse)
    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;
    }

    // un número de punto flotante, al azar, entre $minimum y $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"/>'];

        // los caracteres: cada uno agrandado, inclinado, desplazado, y cada punto
        // ligeramente movido al azar
        $step = ($l - 20) / strlen($text);
        foreach (str_split($text) as $i => $character) {
            $scale = self::random(4.6, 5.6);    // tamaño de una unidad de la cuadrícula, en píxeles
            $angle = self::random(-0.35, 0.35);   // rotación, en radianes (aproximadamente ±20°)
            $cx = 10 + $step * ($i + 0.5) + self::random(-3, 3);    // centro del carácter
            $cy = $h / 2 + self::random(-4, 4);
            foreach (self::FONT[$character] as $stroke) {
                $d = [];
                for ($k = 0; $k < count($stroke); $k += 2) {
                    // punto de la cuadrícula, centrado en (2, 3), distorsionado, rotado, colocado
                    $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 líneas de interferencia: curvas que cruzan la imagen
        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);
    }
}

La imagen está en formato SVG (Scalable Vector Graphics): un dibujo vectorial descrito en XML (es decir, texto), que el servidor genera sin una biblioteca gráfica y que el navegador muestra directamente en la página. Esta clase es [PHP] puro, sin nada específico de un framework: es la misma que en la versión [Laravel] de este curso.

  • Líneas 16–49: una «fuente» minimalista: cada carácter es una lista de trazos, y cada trazo es una lista de coordenadas [x, y] en una cuadrícula de 4 × 6. Se excluyen los caracteres que se confunden fácilmente ([0] y [O], [1], [I] y [L]);
  • Líneas 56–64: una cadena aleatoria seleccionada entre los caracteres de la fuente ([array_keys], las claves del arreglo). Las funciones [rand] y [mt_rand] de [PHP] producen secuencias de números predecibles (cualquiera que conozca unos cuantos valores puede adivinar los siguientes): son adecuadas para simulaciones, no para seguridad. [random_int] es un generador criptográfico; es impredecible;
  • líneas 67–70: un número de punto flotante aleatorio, generado a partir de un entero aleatorio ([PHP_INT_MAX] es el entero más grande en [PHP]);
  • líneas 77–118: el dibujo. Cada carácter se escala, se rota y se desplaza de forma aleatoria, y cada uno de sus puntos se desvía ligeramente; cada línea se convierte en un elemento [<path>] del SVG ([M]: desplazamiento, [L]: línea). Tres curvas ([C]: curva de Bézier) cruzan la imagen para interferir con los programas de reconocimiento. La función [sprintf] formatea una cadena: [%s] inserta una cadena en ella, y [%.1f] inserta un número con un decimal. [str_split] divide una cadena en caracteres.

La clase [Captcha] combina el identificador de un CAPTCHA con su imagen:

<?php
// src/Security/Captcha.php: un CAPTCHA: su identificador y su imagen (SVG)

namespace App\Security;

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

8.3.2. El servicio CAPTCHA: src/Security/CaptchaService.php

<?php
// src/Security/CaptchaService.php: los CAPTCHA pendientes, conservados por el servidor,
// en el caché (véase el ejemplo 20)

namespace App\Security;

use Psr\Cache\CacheItemPoolInterface;

class CaptchaService
{
    // la duración de un CAPTCHA, en segundos
    private const LIFETIME = 600;

    public function __construct(private CacheItemPoolInterface $cache)
    {
    }

    public function generate(): Captcha
    {
        $text = CaptchaDrawing::randomText(5);
        // un identificador aleatorio, imposible de adivinar: 12 bytes generados por un
        // generador criptográfico (random_bytes), escritos en hexadecimal (bin2hex)
        $id = bin2hex(random_bytes(12));
        // la respuesta esperada, en el caché, durante 10 minutos (expiresAfter): el
        // caché la olvidará por sí mismo después
        $item = $this->cache->getItem("captcha.$id");
        $this->cache->save($item->set($text)->expiresAfter(self::LIFETIME));
        return new Captcha($id, CaptchaDrawing::svg($text));
    }

    // el CAPTCHA se CONSUME en todos los casos: una imagen se usa una sola vez
    public function check(?string $id, ?string $answer): bool
    {
        // un identificador mal formado no puede ser una clave del caché
        if ($id === null || ! ctype_xdigit($id) || $answer === null) {
            return false;
        }
        $item = $this->cache->getItem("captcha.$id");
        // deleteItem: la respuesta se elimina del caché, sea correcta o no
        $this->cache->deleteItem("captcha.$id");
        if (! $item->isHit()) {
            return false;    // identificador desconocido, o CAPTCHA expirado
        }
        // strcasecmp devuelve 0 para dos cadenas iguales, sin distinguir mayúsculas de minúsculas
        return strcasecmp($item->get(), trim($answer)) === 0;
    }
}
  • Líneas 18–29: un nuevo CAPTCHA: un texto aleatorio, un identificador aleatorio e imposible de adivinar, y la imagen. Para cada identificador, el servidor almacena la respuesta esperada en la caché (ejemplo 20) durante diez minutos: el método [expiresAfter] del elemento de caché establece su duración de vida en segundos. Transcurrido este tiempo, la caché lo descarta automáticamente. La página recibe solo el identificador y la imagen: la respuesta nunca sale del servidor;
  • líneas 32–46: la validación. El identificador proviene del cliente: primero verificamos que conste de dígitos hexadecimales ([ctype_xdigit]), ya que ciertos caracteres ([{}()/\@:]) están prohibidos en las claves de la caché, lo que lanzaría una excepción. El elemento se lee y luego se elimina de la caché ([deleteItem]): el CAPTCHA se consume en todos los casos, tenga éxito o no. Sin esto, un programa podría probar todas las respuestas posibles sobre la misma imagen. La comparación ignora las mayúsculas y minúsculas ([strcasecmp] devuelve 0 para dos cadenas iguales, sin importar si las letras son mayúsculas o minúsculas) y los espacios alrededor de la entrada ([trim]).

8.3.3. Límite de intentos: config/packages/framework.yaml

# config/packages/framework.yaml: la configuración del FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # la sesión: solo se usa para el token anti-CSRF del formulario de inicio de sesión
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    csrf_protection: true
    # los bloqueos (véase el ejemplo 20): el limitador los usa para contar sin errores
    # los intentos simultáneos
    lock: 'flock://%kernel.project_dir%/var/lock'
    # los LIMITADORES de tasa (componente RateLimiter); este, llamado [login],
    # acepta 3 "tokens" por ventana de 60 segundos
    rate_limiter:
        login:
            policy: fixed_window
            limit: 3
            interval: '60 seconds'
  • línea 11: bloqueos (ejemplo 20): el limitador los utiliza para garantizar que dos solicitudes simultáneas no alteren su recuento;
  • líneas 14–18: un limitador de frecuencia, llamado [login]. Un limitador de frecuencia distribuye «tokens» (sin relación con el token JWT): cada acción restringida consume uno, y cuando ya no quedan, la acción se deniega. La política [fixed_window] (ventana fija) otorga 3 tokens por período de 60 segundos, contados a partir del primer token consumido. Existen otras políticas: [sliding_window] (una ventana deslizante, más regular), [token_bucket] (un cubo que se llena a una tasa determinada). Los contadores se almacenan en la caché de la aplicación.

Para cada limitador declarado, [Symfony] crea un servicio de fábrica de limitadores ([RateLimiterFactoryInterface]), que se obtiene mediante inyección con un nombre de parámetro formado por el nombre del limitador seguido de [Limiter]: [$loginLimiter].

8.3.4. El controlador: src/Controller/AuthController.php

<?php
// src/Controller/AuthController.php: inicio de sesión (con CAPTCHA y limitación de los
// intentos) y cierre de sesión

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: la fábrica del limitador [login] (véase config/packages/framework.yaml);
    // el nombre del parámetro lo designa
    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');
        // el limitador de ESTE cliente: la clave de su contador de fallos es su dirección IP
        $limiter = $this->loginLimiter->create($request->getClientIp());

        // 1. una dirección bloqueada ni siquiera se escucha; consume(0) consulta el
        // contador sin 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. primero el CAPTCHA (barato), después la contraseña (bcrypt, costoso);
        // consume(): un fallo más
        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.');
        }
        // un inicio de sesión exitoso borra los fallos
        $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 visualización del formulario construye un CAPTCHA NUEVO
    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()]);
    }
}
  • líneas 21–26: el controlador recibe la fábrica del limitador [login];
  • línea 49: el limitador de este cliente, [create(key)], devuelve un limitador que tiene su propio contador bajo esta clave; en este caso, la dirección IP del cliente ([getClientIp()]);
  • líneas 53–57: a una dirección bloqueada ni siquiera se le presta atención. [consume(0)] consulta el limitador sin consumir nada; el objeto [RateLimit] que devuelve proporciona el número de tokens restantes ([getRemainingTokens()]) y la fecha en que la acción volverá a estar permitida ([getRetryAfter()]), de la cual se puede deducir el número de segundos que hay que esperar;
  • Líneas 60–68: el CAPTCHA se verifica antes que la contraseña; verificarlo casi no cuesta nada, mientras que [bcrypt] es deliberadamente lento. Por lo tanto, un programa que ingrese un CAPTCHA incorrecto no activaría [bcrypt]. Cada fallo, ya sea del CAPTCHA o de la contraseña, consume un token ([consume()], que consume uno por defecto). Después del tercer fallo, no quedan tokens: la dirección queda bloqueada hasta el final de la ventana de 60 segundos, contada a partir del primer fallo;
  • línea 70: un inicio de sesión exitoso borra los intentos fallidos ([reset()]);
  • líneas 91–95: cada vez que se muestra el formulario, se genera un nuevo CAPTCHA, incluso después de un intento fallido.

SecurityBundle también ofrece un límite de conexiones integrado (la opción de firewall [login_throttling] ), que se aplica a sus propios autenticadores de inicio de sesión ([form_login]...), no a nuestra acción. Para limitar el número de solicitudes de una ruta, usaríamos un limitador de la misma manera, ya sea dentro de la acción o en un listener de [kernel.request]. Elegimos contar únicamente los intentos fallidos, para no incomodar a un usuario que inicia sesión con normalidad.

8.3.5. La vista: 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>
      {# la imagen SVG, construida por el servidor: insertada sin escapar (filtro raw) #}
      <div class="mb-1">{{ captcha.svg|raw }}</div>
      {# el identificador del CAPTCHA viaja en un campo oculto; la respuesta se queda en el 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 %}
  • Línea 18: la imagen SVG se inserta en la página tal cual, sin escape (filtro [raw], ejemplo 14). Esto es legítimo: este HTML lo generó el servidor; no contiene ninguna entrada del usuario;
  • línea 20: el identificador del CAPTCHA, en un campo oculto;
  • línea 21: el navegador no sugiere entradas anteriores para este campo.

8.3.6. Ejecución

Image

Un código copiado incorrectamente:

Image

Después de tres intentos fallidos, la dirección queda bloqueada:

Image

Con [curl], cuatro intentos usando un identificador de CAPTCHA inventado (después de obtener, como en el ejemplo 25, la cookie de sesión y el 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>

Incluso con la contraseña correcta, el cuarto intento se rechaza sin ser procesado.