Errore CORS: perché succede e come risolverlo (Guida pratica)

Parliamo di un argomento che fa venire il mal di testa a molti sviluppatori, specialmente all’inizio: l’errore CORS. Scommetto che almeno una volta, lavorando su un progetto web, ti sei trovato davanti a un messaggio rosso fuoco nella console del browser che urlava qualcosa tipo “Cross-Origin Resource Sharing error”. Fastidioso, vero? Sembra un blocco insensato, ma in realtà c’è una ragione molto importante dietro.

Immagina il web come una grande città piena di case (i siti web). La Same-Origin Policy (SOP) è come una regola di buon vicinato fondamentale: ogni casa può gestire liberamente le proprie cose al suo interno, ma non può ficcare il naso o prendere cose dalle case altrui senza permesso. È una questione di sicurezza importantissima! Impedisce a script maligni su un sito malvagio.com di leggere, ad esempio, i dati della tua sessione su lamiabanca.com aperta in un’altra scheda.

Ma allora, cos’è questa “Origin” (origine)? È semplicemente la combinazione di tre elementi:

1. Protocollo: http o https
2. Dominio: www.miosito.com o localhost
3. Porta: :80, :443, :3000, :8080, ecc. (le porte standard 80 per HTTP e 443 per HTTPS sono spesso omesse nell’URL, ma fanno comunque parte dell’origine).

Se anche solo uno di questi tre elementi è diverso tra la pagina web che fa la richiesta (il tuo frontend, ad esempio) e la risorsa che sta cercando di raggiungere (tipo un’API backend), allora siamo di fronte a una richiesta cross-origin.

Ecco CORS: Il “Permesso Speciale”

La SOP è rigida, ma il web moderno ha bisogno di flessibilità. Pensa alle API, ai microservizi, ai font caricati da Google Fonts, agli script da CDN… sono tutte risorse che spesso non si trovano sulla stessa origine della tua applicazione web!

Qui entra in gioco CORS (Cross-Origin Resource Sharing). Non è un errore, ma un meccanismo di sicurezza basato su header HTTP che permette a un server di indicare al browser quali origini diverse dalla propria sono autorizzate a caricare risorse. In pratica, è il server che dice al browser: “Ehi browser, lo so che questo script viene da miosito-frontend.com, ma fidati, gli do io il permesso di accedere alle mie risorse su api.miosito.com”.

Perché Scatta l’Errore CORS, Allora?

L’errore che vedi nella console non è generato dal server, ma dal browser! Il browser, rispettando la Same-Origin Policy, vede che stai cercando di fare una richiesta cross-origin (ad esempio, il tuo frontend su http://localhost:3000 chiama un’API su http://localhost:5000 oppure su https://api.tuoserver.com).

Prima di far partire la richiesta “vera” (tipo una POST con dati JSON), per alcune richieste considerate “non semplici” (vedremo dopo), il browser fa una cosa chiamata richiesta di preflight: invia una richiesta HTTP con metodo OPTIONS allo stesso URL dell’API. Questa richiesta OPTIONS chiede al server: “Senti, sto per mandarti una richiesta POST da http://localhost:3000 con questi header custom. Posso?”.

Il server deve rispondere a questa richiesta OPTIONS includendo degli header HTTP specifici che dicano “Sì, puoi” oppure “No, non puoi”. I più importanti sono:

• Access-Control-Allow-Origin: Specifica quali origini sono autorizzate. Può essere * (qualunque origine, usalo con cautela!) o un’origine specifica (es: https://miofrontend.com). Attenzione: non puoi mettere una lista di domini qui, solo * o uno specifico.
• Access-Control-Allow-Methods: Specifica quali metodi HTTP sono permessi (es: GET, POST, PUT, DELETE, OPTIONS).
• Access-Control-Allow-Headers: Specifica quali header HTTP custom sono permessi nella richiesta vera e propria.
• Access-Control-Allow-Credentials: Se impostato a true, permette l’invio di cookie o altri dati di autenticazione con la richiesta. Importante: se usi true qui, non puoi usare * in Access-Control-Allow-Origin, devi specificare l’origine esatta.

Se il server non risponde correttamente alla richiesta OPTIONS (o non risponde affatto), oppure se la richiesta “vera” viene fatta da un’origine non specificata in Access-Control-Allow-Origin, il browser blocca la richiesta e… voilà, l’errore CORS nella tua console!

Richieste “Semplici” vs “Non Semplici”

Non tutte le richieste scatenano un preflight OPTIONS. Le cosiddette “richieste semplici” (definite dallo standard CORS) vanno dirette. Queste sono:

• Metodi: GET, HEAD, POST
• Header: Solo alcuni header standard (come Accept, Accept-Language, Content-Language, Content-Type con valori limitati come application/x-www-form-urlencoded, multipart/form-data, text/plain).

Qualsiasi altra cosa (metodi come PUT, DELETE, PATCH, header custom come Authorization per i token JWT, Content-Type impostato a application/json) è considerata “non semplice” e richiede il preflight OPTIONS. Nella pratica, quasi tutte le chiamate API moderne che usano JSON richiedono il preflight.

Ok, Ho Capito (Forse)… Ma Come Risolvo?!

Niente panico! Ci sono diversi modi per risolvere gli errori CORS, ma il metodo giusto dipende dalla situazione. La soluzione fondamentale e corretta è quasi sempre configurare il server per inviare gli header CORS appropriati.

Soluzione 1: Configurare il Server (La Via Maestra)

Questo è il modo migliore e più sicuro. Devi modificare il codice del tuo backend (la tua API) per includere gli header CORS nelle risposte, specialmente nella risposta alla richiesta OPTIONS.

• Esempio con Node.js ed Express:
  Puoi usare un middleware come cors.
  

  npm install cors

  E poi nel tuo file principale (es. server.js o app.js):
  

  const express = require('express'); const cors = require('cors'); // Importa il middleware const app = express(); // Opzioni CORS di base (permette tutte le origini - OK per sviluppo, ATTENZIONE in produzione) // app.use(cors()); // Opzioni CORS più specifiche e sicure per produzione const corsOptions = {   origin: 'https://tuo-frontend.com', // Specifica l'origine del tuo frontend   methods: 'GET,HEAD,PUT,PATCH,POST,DELETE', // Metodi permessi   allowedHeaders: ['Content-Type', 'Authorization'], // Header permessi   credentials: true // Permette l'invio di cookie/auth header }; app.use(cors(corsOptions)); // Applica il middleware CORS con le opzioni // Definisci le tue route API qui... app.get('/api/data', (req, res) => {   res.json({ message: 'Dati segreti accessibili via CORS!' }); }); const PORT = process.env.PORT || 5000; app.listen(PORT, () => console.log(`Server in ascolto sulla porta ${PORT}`));

• Esempio con Python e Flask:
  Puoi usare l’estensione Flask-CORS.
  

  pip install Flask-CORS

  E nel tuo file app.py:
  

  from flask import Flask, jsonify from flask_cors import CORS # Importa l'estensione app = Flask(__name__) # Opzioni CORS di base (permette tutte le origini) # CORS(app) # Opzioni CORS più specifiche # Permette richieste solo da 'https://tuo-frontend.com' per tutte le route # CORS(app, origins="https://tuo-frontend.com", methods=["GET", "POST"], supports_credentials=True) # Oppure configura per specifiche route cors_config = { "origins": ["https://tuo-frontend.com", "http://localhost:3000"], # Lista di origini permesse "methods": ["GET", "POST", "PUT", "DELETE"], "allow_headers": ["Authorization", "Content-Type"], "supports_credentials": True } # Applica CORS a tutte le route che iniziano con /api/ CORS(app, resources={r"/api/*": cors_config}) @app.route('/api/data') def get_data(): return jsonify({"message": "Dati segreti da Flask!"}) if __name__ == '__main__': app.run(port=5000, debug=True)

• Altri Linguaggi/Framework: Quasi tutti i framework backend moderni (Spring Boot in Java, ASP.NET Core, Laravel/Symfony in PHP, Ruby on Rails) hanno meccanismi integrati o librerie/plugin molto diffusi per gestire CORS in modo simile. La logica è sempre la stessa: intercettare le richieste (specialmente OPTIONS) e aggiungere gli header Access-Control-* necessari.

Soluzione 2: Usare un Proxy (Utile in Sviluppo, Ma Non Solo)

A volte non hai accesso diretto al codice del backend (magari stai usando un’API di terze parti che non ha CORS configurato correttamente per te), oppure sei in fase di sviluppo e vuoi una soluzione rapida. Puoi usare un proxy!

L’idea è:

1. Il tuo frontend (es. su localhost:3000) non chiama direttamente l’API cross-origin (es. api.esterna.com).
2. Invece, chiama un endpoint sul tuo stesso server di sviluppo (es. localhost:3000/api-proxy). Questa è una richiesta same-origin, quindi niente errore CORS!
3. Il server di sviluppo (il proxy) riceve la richiesta e la inoltra all’API esterna vera e propria (api.esterna.com).
4. L’API esterna risponde al proxy.
5. Il proxy inoltra la risposta al tuo frontend.

Il browser vede solo la comunicazione tra frontend e proxy (stessa origine), quindi è contento. La comunicazione cross-origin avviene tra server (proxy e API esterna), e le regole CORS del browser non si applicano alle comunicazioni server-to-server.

• In Sviluppo: Molti tool di sviluppo frontend hanno proxy integrati facili da configurare:

• Create React App: Puoi aggiungere una chiave proxy al tuo package.json: “proxy”: “http://localhost:5000” (se la tua API gira su quella porta).
• Vue CLI: Puoi configurare devServer.proxy nel file vue.config.js.
• Angular CLI: Puoi creare un file proxy.conf.json e specificarlo nel comando ng serve.

• In Produzione: Potresti usare un reverse proxy come Nginx o Apache davanti alla tua applicazione frontend. Puoi configurare Nginx per fare da proxy per le chiamate API, aggiungendo anche gli header necessari se serve, o semplicemente mascherando la chiamata cross-origin.

Soluzioni da Evitare (o Usare con Estrema Cautela)

• Disabilitare la Sicurezza del Browser: Ci sono estensioni per browser che disabilitano i controlli CORS. NON FARLO MAI per la navigazione normale e NON CHIEDERE MAI AI TUOI UTENTI DI FARLO. È come togliere la serratura alla porta di casa perché non trovi le chiavi. Va bene solo per test molto specifici e temporanei sul tuo ambiente di sviluppo locale, sapendo esattamente cosa stai facendo.
• Usare Access-Control-Allow-Origin: * Ovunque: Permettere qualsiasi sito web di fare richieste alla tua API è spesso un rischio per la sicurezza, specialmente se l’API gestisce dati sensibili o richiede autenticazione (cookie, token). Usalo solo per API pubbliche che devono essere accessibili da chiunque, o in fase di sviluppo iniziale, ma sii consapevole delle implicazioni.
• JSONP (JSON with Padding): È una tecnica vecchia che aggirava la SOP usando i tag <script> (che non erano soggetti alle stesse restrizioni). È considerata obsoleta, insicura (vulnerabilità XSS) e limitata (supporta solo richieste GET). Evitala se puoi, CORS è lo standard moderno.

Come Fare Debugging

Quando incontri un errore CORS, la Console Sviluppatore del tuo browser (tasto F12) è la tua migliore amica.

1. Guarda il messaggio di errore preciso nella Console. Spesso ti dice quale header manca o quale origine non è permessa.
2. Vai nella scheda Network (o Rete).
3. Trova la richiesta fallita (spesso sarà segnata in rosso).
4. Se c’è stata una richiesta di preflight, vedrai una richiesta con metodo OPTIONS prima della tua richiesta vera e propria. Selezionala.
5. Controlla gli Header della Risposta (Response Headers) della richiesta OPTIONS. Ci sono gli header Access-Control-Allow-*? Hanno i valori corretti (l’origine giusta, il metodo giusto, gli header giusti)?
6. Se la OPTIONS sembra a posto, controlla gli header della richiesta vera e propria (es. la POST o GET fallita) e gli header della sua risposta. L’Access-Control-Allow-Origin della risposta corrisponde all’origine del tuo frontend?

In Conclusione: CORS Non è il Nemico!

All’inizio, CORS può sembrare solo un ostacolo frustrante messo lì per complicarci la vita. Ma ricordati: è una guardia del corpo fondamentale per la sicurezza del web. Capire perché esiste (proteggere gli utenti) e come funziona (tramite header HTTP negoziati tra server e browser) è il primo passo per smettere di combatterlo e iniziare a configurarlo correttamente.

La prossima volta che vedrai quell’errore rosso, respira, apri la console, controlla gli header e ricorda che la soluzione più pulita è quasi sempre lato server. Armati di pazienza (e magari di un middleware CORS per il tuo backend) e vedrai che riuscirai a far comunicare le tue applicazioni senza problemi e in sicurezza!

Spero che questa chiacchierata ti sia stata utile. È un argomento un po’ tecnico, ma una volta capito il meccanismo, tutto diventa più logico. Buona fortuna con il tuo codice!