Vai al contenuto

Symfony come API per una SPA React: sessioni, CSRF, errori e permessi

Una single page application in React con un backend Symfony è ormai una combinazione standard: il frontend gestisce l’interfaccia, il backend espone un’API JSON con la logica di business, la sicurezza e i dati. La separazione è utile, ma sposta il problema: le decisioni che in un’applicazione tradizionale prendeva il framework (come si autentica l’utente, come si mostrano gli errori di un form, cosa succede quando la sessione scade) diventano un contratto tra due programmi diversi, spesso scritti da persone diverse.

In questo articolo costruiamo quel contratto in modo esplicito, con codice provato: Symfony 7.4 come API, un client React 19 e una serie di prove automatiche che, tra l’altro, hanno trovato due problemi che un primo collaudo manuale non avrebbe visto.

Prima scelta: dove vive la SPA

La decisione che semplifica di più tutto il resto è servire SPA e API dalla stessa origine: stesso schema, dominio e porta, per esempio https://app.esempio.it/ per i file statici di React e https://app.esempio.it/api/ per Symfony. Il server web (nginx, Caddy, un load balancer) smista per percorso. Con una sola origine non esiste CORS da configurare, il cookie di sessione viaggia da solo e la superficie di attacco si riduce.

Schema: browser con SPA React e cookie di sessione, server web che serve i file statici e inoltra /api a Symfony; Symfony controlla in sequenza origine (403), autenticazione (401), validità dei dati (422), proprietà della risorsa (404) e poi esegue

Se SPA e API devono stare su domini diversi, servono intestazioni CORS (in Symfony di solito con NelmioCorsBundle), con un elenco esplicito delle origini ammesse e mai un carattere jolly quando si inviano credenziali. Durante lo sviluppo, invece del CORS conviene configurare il proxy del server di sviluppo del frontend, così l’applicazione locale riproduce la stessa origine della produzione.

Seconda scelta: sessione o token

Cookie di sessione HttpOnly JWT in JavaScript
Dove sta la credenziale in un cookie che JavaScript non può leggere in memoria o in localStorage, leggibile dagli script
Furto con XSS lo script può usare la sessione finché la pagina è aperta, ma non può portarsela via il token può essere sottratto e usato altrove fino alla scadenza
CSRF da gestire: il cookie parte da solo assente, se il token viaggia in un’intestazione
Logout e revoca immediati: si distrugge la sessione difficili: il token resta valido fino alla scadenza
Quando preferirlo SPA servita dalla stessa origine client diversi dal browser (app mobili, altri servizi)

Per una SPA nella stessa origine la sessione con cookie è la scelta più semplice e più solida, e Symfony la gestisce già. Il prezzo è la protezione da CSRF, che vediamo tra poco. I token restano la soluzione giusta per le app mobili e per le integrazioni tra servizi, magari sulla stessa API ma con un firewall dedicato.

La configurazione di sessione e sicurezza

Gli esempi usano la configurazione in PHP; in YAML le chiavi sono le stesse.

// config/framework.php
$container->extension('framework', [
    'secret' => '%env(APP_SECRET)%',
    'session' => [
        'cookie_httponly' => true,
        'cookie_secure' => 'auto',   // Secure quando la richiesta è HTTPS
        'cookie_samesite' => 'lax',  // il cookie non parte con le richieste POST da altri siti
    ],
]);

// config/security.php
$container->extension('security', [
    'password_hashers' => [PasswordAuthenticatedUserInterface::class => 'auto'],
    'providers' => ['utenti' => ['entity' => ['class' => Utente::class, 'property' => 'email']]],
    'firewalls' => [
        'api' => [
            'pattern' => '^/api',
            'provider' => 'utenti',
            'json_login' => ['check_path' => 'api_login', 'username_path' => 'utente', 'password_path' => 'password'],
            'login_throttling' => ['max_attempts' => 5, 'interval' => '1 minute'],
            'entry_point' => RispostaNonAutenticato::class,
            'logout' => ['path' => 'api_logout'],
        ],
    ],
    'access_control' => [
        ['path' => '^/api/login$', 'roles' => 'PUBLIC_ACCESS'],
        ['path' => '^/api', 'roles' => 'ROLE_USER'],
    ],
]);

Nelle prove il provider era un elenco di utenti in memoria; qui è mostrato il provider Doctrine che si userebbe in un’applicazione reale. login_throttling richiede il componente symfony/rate-limiter e blocca i tentativi ripetuti sulla stessa coppia utente/indirizzo IP.

Tre piccole classi adattano il comportamento di Symfony a un’API. La prima risponde 401 in JSON invece di reindirizzare a una pagina di login che la SPA non saprebbe gestire:

namespace App\Sicurezza;

use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;

/** Un'API non reindirizza a una pagina di login: risponde 401 e lascia decidere alla SPA. */
final class RispostaNonAutenticato implements AuthenticationEntryPointInterface
{
    public function start(Request $request, ?AuthenticationException $authException = null): Response
    {
        return new JsonResponse(['errore' => 'non_autenticato'], 401);
    }
}

La seconda fa lo stesso per il logout, che di default reindirizzerebbe:

#[AsEventListener]
final class UscitaSenzaRedirect
{
    public function __invoke(LogoutEvent $event): void
    {
        $event->setResponse(new Response(null, 204));
    }
}

La terza è la protezione da CSRF. SameSite=Lax impedisce già ai browser moderni di inviare il cookie con una POST partita da un altro sito; come seconda difesa, ogni richiesta che modifica dati deve dichiarare un’origine ammessa. I browser inviano l’intestazione Origin con le richieste POST, PUT, PATCH e DELETE, e una pagina ostile non può falsificarla:

namespace App\Sicurezza;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

/**
 * Difesa CSRF per un'API autenticata con cookie: le richieste che modificano dati
 * devono provenire da un'origine nota. I browser inviano Origin su POST, PUT, PATCH e DELETE.
 */
#[AsEventListener(event: KernelEvents::REQUEST, priority: 100)]
final readonly class ControlloOrigine
{
    /** @param list<string> $originiAmmesse */
    public function __construct(private array $originiAmmesse)
    {
    }

    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        if (!$event->isMainRequest() || $request->isMethodSafe() || !str_starts_with($request->getPathInfo(), '/api/')) {
            return;
        }

        $origine = $request->headers->get('Origin');
        if ($origine === null || !in_array($origine, $this->originiAmmesse, true)) {
            $event->setResponse(new JsonResponse(['errore' => 'origine_non_ammessa'], 403));
        }
    }
}

Il listener rifiuta anche le richieste senza Origin. È la scelta prudente per un’API pensata per il browser; client diversi (script, app) vanno autenticati in un altro modo, su un firewall separato. Le richieste GET sono escluse dal controllo, e proprio per questo non devono mai modificare dati.

Login e utente corrente

Con json_login il firewall verifica le credenziali prima che la richiesta arrivi al controller; se il login riesce, la richiesta prosegue. Lo stesso metodo serve anche a /api/me, che la SPA chiama all’avvio per sapere se c’è una sessione attiva:

final class SessioneController extends AbstractController
{
    // json_login autentica la richiesta prima di arrivare qui: il controller restituisce solo chi è entrato
    #[Route('/api/login', name: 'api_login', methods: ['POST'], format: 'json')]
    #[Route('/api/me', name: 'api_me', methods: ['GET'], format: 'json')]
    public function utente(#[CurrentUser] ?UserInterface $utente): JsonResponse
    {
        if ($utente === null) {
            return $this->json(['errore' => 'non_autenticato'], 401);
        }

        return $this->json(['utente' => $utente->getUserIdentifier(), 'ruoli' => $utente->getRoles()]);
    }

    #[Route('/api/logout', name: 'api_logout', methods: ['POST'])]
    public function esci(): never
    {
        throw new \LogicException('Gestito dal firewall.');
    }
}

Il contratto degli errori

Una SPA deve poter distinguere con certezza cosa è andato storto: sessione scaduta, richiesta rifiutata, dati non validi, risorsa inesistente. I codici HTTP esistono per questo, a patto di usarli in modo coerente e di restituire sempre JSON.

I dati in ingresso passano da un DTO con i vincoli di validazione; l’attributo #[MapRequestPayload] lo popola dal corpo JSON e lo valida prima di chiamare il controller:

namespace App\Progetti;

use Symfony\Component\Validator\Constraints as Assert;

/** Ciò che il client può inviare: niente id, niente proprietario. */
final readonly class NuovoProgetto
{
    public function __construct(
        #[Assert\NotBlank(message: 'Il titolo è obbligatorio.', normalizer: 'trim')]
        #[Assert\Length(max: 120, maxMessage: 'Il titolo può contenere al massimo {{ limit }} caratteri.')]
        public string $titolo = '',

        #[Assert\Length(max: 2000, maxMessage: 'La descrizione può contenere al massimo {{ limit }} caratteri.')]
        public string $descrizione = '',
    ) {
    }
}

Il DTO è anche una difesa: contiene solo i campi che il client può impostare. Il proprietario del progetto viene dalla sessione, mai dal corpo della richiesta. Se i dati non sono validi, Symfony risponde 422 con un documento nel formato problem details e un elenco di violazioni, una per campo. Questo è un estratto della risposta reale, con un titolo fatto di soli spazi e una descrizione troppo lunga:

{
    "type": "https://symfony.com/errors/validation",
    "title": "Validation Failed",
    "status": 422,
    "detail": "titolo: Il titolo è obbligatorio.\ndescrizione: La descrizione può contenere al massimo 2000 caratteri.",
    "violations": [
        {
            "propertyPath": "titolo",
            "title": "Il titolo è obbligatorio.",
            "template": "Il titolo è obbligatorio.",
            "parameters": { "{{ value }}": "\"  \"" },
            "type": "urn:uuid:c1051bb4-d103-4f74-8988-acbcafc7fdc3"
        },
        {
            "propertyPath": "descrizione",
            "title": "La descrizione può contenere al massimo 2000 caratteri.",
            "template": "La descrizione può contenere al massimo {{ limit }} caratteri.",
            "parameters": { "{{ value }}": "\"xxxx…\"", "{{ limit }}": "2000", "{{ max }}": "2000", "{{ value_length }}": "2001" },
            "type": "urn:uuid:d94b19cc-114f-4f44-9cc4-4138e80a87b9"
        }
    ]
}

Le prove hanno trovato due trappole proprio qui:

  • Gli errori uscivano in HTML. Symfony sceglie il formato della pagina d’errore in base alla richiesta. Senza un’indicazione esplicita, le risposte 400, 404 e 422 arrivavano come pagine HTML, inutilizzabili per la SPA. La soluzione è dichiarare il formato sulle rotte dell’API, con l’opzione format: 'json' dell’attributo #[Route]; il client, per parte sua, invia comunque Accept: application/json.
  • Un titolo di soli spazi superava la validazione. NotBlank considera non vuota una stringa di spazi. Con normalizer: 'trim' il vincolo controlla il valore ripulito, e i testi vengono comunque salvati senza spazi iniziali e finali.

In produzione, con il debug disattivato, la risposta non contiene lo stack trace: la verifica fatta con il kernel in modalità non debug ha restituito solo tipo, titolo, stato, dettaglio e violazioni.

I permessi sui singoli oggetti

Essere autenticati non basta: un utente deve vedere e modificare solo i propri progetti. In Symfony questa regola si esprime con un voter:

/** @extends Voter<string, Progetto> */
final class ProgettoVoter extends Voter
{
    public const GESTIRE = 'PROGETTO_GESTIRE';

    protected function supports(string $attribute, mixed $subject): bool
    {
        return $attribute === self::GESTIRE && $subject instanceof Progetto;
    }

    protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token, ?Vote $vote = null): bool
    {
        return $subject->proprietario === $token->getUserIdentifier();
    }
}

Nel controller, un progetto altrui risponde 404 esattamente come uno inesistente. Rispondere 403 rivelerebbe che quell’identificativo esiste, un’informazione che in molti contesti non va data. Anche il formato della risposta è deciso in un punto solo, in modo esplicito: è il contratto con il frontend, e non deve cambiare perché qualcuno ha aggiunto una proprietà all’entità.

#[Route('/api/progetti', format: 'json')]
final class ProgettiController extends AbstractController
{
    public function __construct(private readonly ArchivioProgetti $progetti)
    {
    }

    #[Route('', methods: ['GET'])]
    public function elenco(): JsonResponse
    {
        return $this->json(array_map($this->comeJson(...), $this->progetti->diProprietario($this->getUser()->getUserIdentifier())));
    }

    #[Route('', methods: ['POST'])]
    public function crea(#[MapRequestPayload] NuovoProgetto $dati): JsonResponse
    {
        $progetto = $this->progetti->aggiungi($dati, $this->getUser()->getUserIdentifier());

        return $this->json($this->comeJson($progetto), 201);
    }

    #[Route('/{id<\d+>}', methods: ['GET'])]
    public function mostra(int $id): JsonResponse
    {
        return $this->json($this->comeJson($this->progettoDelloUtente($id)));
    }

    #[Route('/{id<\d+>}', methods: ['DELETE'])]
    public function elimina(int $id): Response
    {
        $this->progetti->elimina($this->progettoDelloUtente($id)->id);

        return new Response(null, 204);
    }

    /** Un progetto altrui risponde 404 come uno inesistente: non si rivela che esiste. */
    private function progettoDelloUtente(int $id): Progetto
    {
        $progetto = $this->progetti->trova($id);
        if ($progetto === null || !$this->isGranted(ProgettoVoter::GESTIRE, $progetto)) {
            throw new NotFoundHttpException();
        }

        return $progetto;
    }

    /** Il formato della risposta è deciso qui, in modo esplicito: è il contratto con il frontend. */
    private function comeJson(Progetto $p): array
    {
        return ['id' => $p->id, 'titolo' => $p->titolo, 'descrizione' => $p->descrizione, 'creatoIl' => $p->creatoIl->format(DATE_ATOM)];
    }
}

Le prove dell’API

Le prove funzionali usano il KernelBrowser di Symfony, che esegue le richieste direttamente nel kernel e mantiene i cookie tra una richiesta e l’altra. Gli scenari principali e le risposte ottenute:

Scenario Risposta
Elenco progetti senza login 401 {"errore":"non_autenticato"}
Login da un’origine non ammessa, o senza Origin 403 {"errore":"origine_non_ammessa"}
Password sbagliata 401 {"error":"Invalid credentials."}
Login corretto 200 con utente e ruoli; cookie httponly; samesite=lax
Progetto con titolo vuoto e descrizione troppo lunga 422 con due violazioni
JSON malformato 400 in formato problem details
Progetto valido 201 con il progetto creato
Logout, poi /api/me 204, poi 401
Un altro utente legge o cancella il progetto 404, come per un progetto inesistente
Sesto tentativo di login errato in un minuto 401 con messaggio di troppi tentativi; bloccato anche con la password giusta

Il client React

Sul frontend vale lo stesso principio: un solo modulo parla con l’API, e i componenti non sanno nulla di intestazioni, cookie e formati d’errore. Il modulo trasforma ogni risposta non riuscita in un’eccezione con lo stato HTTP e, per il 422, una mappa “campo → messaggio”:

// Un solo punto per parlare con l'API: formato, cookie ed errori sono gestiti qui, non nei componenti.
export class ErroreApi extends Error {
  constructor(stato, dettaglio, campi = {}) {
    super(dettaglio || `Errore ${stato}`);
    this.stato = stato;
    this.campi = campi; // { titolo: 'Il titolo è obbligatorio.', ... }
  }
}

export async function api(percorso, {metodo = 'GET', dati, segnale} = {}) {
  const risposta = await fetch(`/api${percorso}`, {
    method: metodo,
    credentials: 'same-origin', // il cookie di sessione parte da solo; nessun token in JavaScript
    headers: {Accept: 'application/json', ...(dati !== undefined && {'Content-Type': 'application/json'})},
    body: dati !== undefined ? JSON.stringify(dati) : undefined,
    signal: segnale,
  });

  if (risposta.status === 204) return null;
  const corpo = risposta.headers.get('Content-Type')?.includes('json') ? await risposta.json() : null;
  if (risposta.ok) return corpo;

  if (risposta.status === 401) {
    window.dispatchEvent(new CustomEvent('sessione-scaduta')); // l'app mostrerà il login
  }

  // 422 di Symfony: un elenco di violazioni, una per campo
  const campi = {};
  for (const v of corpo?.violations ?? []) campi[v.propertyPath] ??= v.title;

  throw new ErroreApi(risposta.status, corpo?.detail ?? corpo?.errore, campi);
}

L’intestazione Origin non va impostata a mano: la aggiunge il browser. Il 401 non viene gestito dal componente che ha fatto la richiesta ma diventa un evento globale, perché la sessione scaduta riguarda tutta l’applicazione. Il form, a quel punto, deve occuparsi solo di ciò che lo riguarda:

import {useState} from 'react';
import {api, ErroreApi} from './api.js';

export function FormProgetto({suCreato}) {
  const [valori, setValori] = useState({titolo: '', descrizione: ''});
  const [errori, setErrori] = useState({});
  const [inInvio, setInInvio] = useState(false);
  const [erroreGenerale, setErroreGenerale] = useState(null);

  const aggiorna = (campo) => (e) => setValori({...valori, [campo]: e.target.value});

  async function invia(e) {
    e.preventDefault();
    setInInvio(true);
    setErrori({});
    setErroreGenerale(null);
    try {
      suCreato(await api('/progetti', {metodo: 'POST', dati: valori}));
      setValori({titolo: '', descrizione: ''});
    } catch (err) {
      if (err instanceof ErroreApi && err.stato === 422) setErrori(err.campi);
      else setErroreGenerale('Salvataggio non riuscito. Riprova tra poco.');
    } finally {
      setInInvio(false);
    }
  }

  return (
    <form onSubmit={invia} noValidate>
      <label htmlFor="titolo">Titolo</label>
      <input id="titolo" value={valori.titolo} onChange={aggiorna('titolo')} aria-invalid={!!errori.titolo} />
      {errori.titolo && <p role="alert" data-campo="titolo">{errori.titolo}</p>}

      <label htmlFor="descrizione">Descrizione</label>
      <textarea id="descrizione" value={valori.descrizione} onChange={aggiorna('descrizione')} aria-invalid={!!errori.descrizione} />
      {errori.descrizione && <p role="alert" data-campo="descrizione">{errori.descrizione}</p>}

      {erroreGenerale && <p role="alert">{erroreGenerale}</p>}
      <button type="submit" disabled={inInvio}>{inInvio ? 'Salvataggio…' : 'Crea progetto'}</button>
    </form>
  );
}

I messaggi d’errore sono quelli del backend: la validazione resta in un posto solo e il frontend non ne duplica le regole. Una validazione anche lato client migliora l’esperienza d’uso, ma non sostituisce mai quella del server. Il componente è stato provato in jsdom con React 19, usando come dato di prova la risposta 422 reale dell’API: i due messaggi compaiono sotto i campi giusti con aria-invalid impostato; con un 201 il progetto viene passato al genitore e il form si svuota; un 401 emette l’evento sessione-scaduta; un errore di rete mostra il messaggio generico e riattiva il pulsante.

Prima di andare in produzione

  • HTTPS ovunque. Con cookie_secure: auto il cookie diventa Secure solo se Symfony vede la richiesta come HTTPS: dietro un proxy che termina TLS vanno configurati i trusted proxies, altrimenti il cookie parte senza quell’attributo.
  • Limiti anche altrove. Oltre al login, il componente RateLimiter va applicato agli endpoint costosi o sensibili: registrazione, recupero password, esportazioni.
  • Intestazioni di sicurezza. Una Content Security Policy riduce l’impatto di un eventuale XSS, che resta il rischio principale per qualunque SPA.
  • Contenuto HTML. React protegge dall’XSS quando si mostra testo. Se occorre mostrare HTML inserito dagli utenti, va ripulito: con DOMPurify sul client o HTML Purifier sul server.
  • Log degli eventi di sicurezza. Login riusciti e falliti, blocchi per troppi tentativi, accessi negati: con Monolog e, per le eccezioni, uno strumento come Sentry.
  • Documentazione dell’API. Una specifica OpenAPI, scritta a mano o generata, rende il contratto verificabile da entrambe le parti.

Conclusione

Symfony e React lavorano bene insieme quando il confine tra i due è un contratto preciso, non un insieme di abitudini. Una sola origine elimina CORS e permette di usare la sessione con cookie; il controllo dell’origine chiude la porta al CSRF; DTO, validazione e voter rendono esplicite le regole; codici HTTP e risposte JSON coerenti permettono al frontend di reagire nel modo giusto a ogni errore. E le prove automatiche, su entrambi i lati, sono l’unico modo per sapere che il contratto regge davvero: nel nostro caso hanno trovato errori in HTML e titoli di soli spazi prima di qualunque utente.