condivisione delle risorse tra origini (CORS)

Configurazione Esempi di configurazione

Il criterio della stessa origine è un criterio di sicurezza applicato alle applicazioni web lato client (come i browser web) per impedire interazioni tra risorse di origini diverse. Sebbene sia utile per prevenire comportamenti dannosi, questa misura di sicurezza impedisce anche interazioni legittime tra origini note. Ad esempio, uno script su una pagina ospitata in example.appspot.com potrebbe dover utilizzare le risorse archiviate in un bucket Cloud Storage in example.storage.googleapis.com. Tuttavia, poiché si tratta di due origini diverse dal punto di vista del browser, il browser non consentirà a uno script di example.appspot.com di recuperare risorse da example.storage.googleapis.com.

La specifica della condivisione delle risorse tra origini (CORS) è stata sviluppata dal World Wide Web Consortium (W3C) per aggirare questa limitazione. Cloud Storage supporta questa specifica consentendo di configurare i bucket per il supporto di CORS. Proseguendo con l'esempio precedente, puoi configurare il bucket example.storage.googleapis.com in modo che un browser possa condividere le proprie risorse con gli script di example.appspot.com.

Per ulteriori informazioni sui componenti di configurazione di CORS, consulta Impostare CORS del bucket.

Come funziona CORS

Esistono due tipi di richieste CORS: semplici e preflight. Puoi avviare direttamente una richiesta semplice. Una richiesta preflight deve inviare al server una richiesta "preflight" preliminare per ottenere l'autorizzazione prima che la richiesta principale possa procedere. Una richiesta viene eseguita in fase preliminare se si verifica una delle seguenti circostanze:

  • Utilizza metodi diversi da GET, HEAD o POST.
  • Utilizza il metodo POST con un Content-Type diverso da text/plain, application/x-www-form-urlencoded o multipart/form-data.
  • Imposta intestazioni personalizzate. Ad esempio, X-PINGOTHER.

Il seguente processo si verifica quando un browser invia una semplice richiesta a Cloud Storage:

  1. Il browser aggiunge l'intestazione Origin alla richiesta. L'intestazione Origin contiene l'origine della risorsa che vuole condividere le risorse del bucket Cloud Storage, ad esempio Origin:https://www.example.appspot.com.

  2. Cloud Storage confronta il metodo HTTP della richiesta e il valore dell'intestazione Origin con le informazioni Metodi e Origini nella configurazione CORS del bucket di destinazione per verificare se esistono corrispondenze. Se ce ne sono, Cloud Storage include l'intestazione Access-Control-Allow-Origin nella sua risposta. L'intestazione Access-Control-Allow-Origin contiene il valore dell'intestazione Origin della richiesta iniziale.

  3. Il browser riceve la risposta e controlla se il valore Access-Control-Allow-Origin corrisponde al dominio specificato nella richiesta originale. Se corrispondono, la richiesta viene soddisfatta. Se non corrispondono o se l'intestazione Access-Control-Allow-Origin non è presente nella risposta, la richiesta ha esito negativo.

Per prima cosa, una richiesta preflight esegue i seguenti passaggi. Se l'operazione ha esito positivo, seguirà lo stesso processo di una semplice richiesta:

  1. Il browser invia una richiesta OPTIONS contenente i Requested Method e Requested Headers della richiesta principale.

  2. Cloud Storage risponde con i valori dei metodi e delle intestazioni HTTP consentiti dalla risorsa scelta come target. Se uno qualsiasi dei valori di metodo o intestazione nella richiesta preflight non è nell'insieme di metodi e intestazioni consentiti dalla risorsa scelta come target, la richiesta ha esito negativo e la richiesta principale non viene inviata.

Questa è una descrizione semplificata di CORS. Per una descrizione più completa, leggi la specifica per il recupero.

Supporto CORS per Cloud Storage

Cloud Storage consente di impostare una configurazione CORS solo a livello di bucket. Puoi configurare una configurazione CORS per un bucket utilizzando diversi strumenti; tuttavia, diversi endpoint Cloud Storage gestiscono le richieste CORS in modi diversi:

  • Gli endpoint API JSON consentono sempre le richieste CORS e restituiscono valori predefiniti nelle intestazioni delle risposte CORS, indipendentemente dalla configurazione impostata nel bucket.

  • Gli endpoint API XML consentono solo le richieste CORS in base alla configurazione nel bucket e restituiscono valori di intestazione CORS specifici in risposta alla configurazione.

  • L'endpoint di download del browser autenticato storage.cloud.google.com non consente le richieste CORS. Tieni presente che la console Google Cloud fornisce questo endpoint per il link dell'URL pubblico di ciascun oggetto.

Puoi utilizzare uno dei seguenti URL di richiesta dell'API XML per ottenere una risposta da Cloud Storage contenente le intestazioni CORS:

storage.googleapis.com/BUCKET_NAME
BUCKET_NAME.storage.googleapis.com

Per informazioni sugli URL delle richieste dell'API XML, consulta Endpoint delle richieste.

Componenti di una configurazione CORS

Quando utilizzi l'API XML, i valori che imposti nella configurazione CORS del bucket determinano le intestazioni CORS che Cloud Storage restituisce in una risposta HTTP. Quando utilizzi l'API JSON, Cloud Storage non valuta la configurazione del bucket e restituisce invece valori di intestazione predefiniti.

La seguente tabella descrive i campi in una configurazione CORS e il comportamento della risposta delle API XML e JSON. Per informazioni su come vengono utilizzati questi campi, consulta Esempi di configurazione di CORS.

Campo1 Descrizione Comportamento della risposta dell'API XML Comportamento della risposta dell'API JSON
origin Specifica le origini in cui vuoi consentire la condivisione delle risorse tra origini con questo bucket Cloud Storage. Ad esempio, https://origin1.example.com. Se l'origine nella richiesta di un browser corrisponde a un'origine nella configurazione CORS, Cloud Storage restituisce Access-Control-Allow-Origin al browser. Se non viene trovata una corrispondenza, Cloud Storage non include Access-Control-Allow-Origin nella risposta. Puoi fornire un valore jolly che concede l'accesso a tutte le origini: <Origin>*</Origin>. Cloud Storage restituisce l'intestazione Access-Control-Allow-Origin impostata sull'origine della richiesta.
method

Specifica i metodi HTTP da consentire la condivisione delle risorse tra origini con questo bucket Cloud Storage. Il valore viene restituito nell'intestazione Access-Control-Allow-Methods in risposta alle richieste preflight riuscite.

Poiché OPTIONS è un metodo standard utilizzato dai browser per avviare richieste preflight, non devi specificare OPTIONS nella configurazione CORS.

Cloud Storage supporta i seguenti metodi: DELETE, GET, HEAD, POST, PUT.

Cloud Storage controlla i metodi inviati dal browser nell'intestazione Access-Control-Request-Methods in base alla configurazione CORS del bucket. In assenza di corrispondenze, Cloud Storage restituisce un codice di risposta 200 senza intestazioni della risposta CORS.

 Cloud Storage restituisce l'intestazione Access-Control-Allow-Methods impostata sui seguenti metodi: DELETE, GET, HEAD, PATCH, POST, PUT.
responseHeader Specifica quali intestazioni vuoi consentire la condivisione delle risorse tra origini con questo bucket Cloud Storage. Il valore viene restituito nell'intestazione Access-Control-Allow-Headers in risposta alle richieste preflight riuscite. Per le richieste preflight, Cloud Storage controlla le intestazioni inviate dal browser nell'intestazione Access-Control-Request-Headers in base alla configurazione CORS del bucket. Se non viene trovata alcuna corrispondenza, Cloud Storage non restituisce le intestazioni delle risposte CORS. Cloud Storage restituisce l'intestazione Access-Control-Allow-Headers impostata uguale ai valori specificati dall'intestazione Access-Control-Request-Headers.
maxAgeSeconds (facoltativo) Specifica il numero di secondi in cui il browser è autorizzato a effettuare richieste prima che debba ripetere la richiesta preflight. È anche nota come data di scadenza della cache. Questo valore viene restituito nell'intestazione Access-Control-Max-Age nelle risposte alle richieste preflight. Ad esempio, 3600 imposta la data di scadenza della cache su 1 ora. Cloud Storage restituisce l'intestazione Access-Control-Max-Age con la data di scadenza della cache specificata. Se ometti questo campo, Cloud Storage restituisce il valore predefinito di 3600. Cloud Storage restituisce l'intestazione Access-Control-Max-Age con il valore predefinito di 3600.

1 I nomi documentati nella colonna Campo sono specifici dell'API JSON. Quando utilizzi l'API XML per impostare una configurazione CORS, utilizza il formato XML specifico.

Specificare più origini, metodi o intestazioni

Per scoprire come impostare più origini, metodi o intestazioni in una configurazione CORS, consulta l'elenco seguente:

  • Quando utilizzi l'API JSON, puoi specificare più origini, metodi o intestazioni utilizzando un array separato da virgole. Ad esempio, "method": ["GET", "PUT"].

  • Quando utilizzi l'API XML, puoi specificare più origini, metodi o intestazioni utilizzando elementi separati. Ad esempio:

    <Methods>
  <Method>PUT</Method>
  <Method>GET</Method>
</Methods>

  • Per consentire le richieste da qualsiasi origine, imposta l'origine su *. Ad esempio, "origin": ["*"] nell'API JSON o <Origin>*</Origin> nell'API XML. Sebbene questa origine sia utile per testare le configurazioni, nella maggior parte dei casi conviene limitare le origini delle richieste per evitare utilizzi indesiderati delle risorse.

Ulteriori considerazioni

La seguente tabella descrive alcune considerazioni da fare quando si effettuano richieste utilizzando credenziali o intestazioni di controllo dell'accesso:

Proprietà o intestazione Descrizione Comportamento della risposta dell'API XML Comportamento della risposta dell'API JSON
Credenziali Cookie, intestazioni di autorizzazione o certificati client TLS. Cloud Storage non restituisce mai l'intestazione Access-Control-Allow-Credentials. Le credenziali CORS non sono supportate dall'API XML.

Per le richieste semplici, se la richiesta CORS viene approvata, l'intestazione Access-Control-Allow-Credentials è impostata su true.

Per le richieste preflight, se il campo Access-Control-Request-Method è vuoto, Cloud Storage imposta Access-Control-Allow-Credentials su true e rifiuta la richiesta con 404 - Not Found.
Intestazioni esposte Per le richieste preflight, l'intestazione della richiesta Access-Control-Request-Headers indica le intestazioni che potrebbe includere una richiesta CORS futura. L'intestazione della risposta Access-Control-Expose-Headers è inclusa nella risposta del server e indica al client quali intestazioni possono essere esposte. Per le richieste semplici, Access-Control-Expose-Headers elenca i valori delle intestazioni delle risposte nella configurazione CORS. Per le richieste semplici, Access-Control-Expose-Headers restituisce i valori specificati in Access-Control-Request-Headers se fanno parte di un elenco di intestazioni HTTP comuni.

Consentire ai bucket di accedere alle risorse esterne

A volte potresti voler consentire agli script ospitati in Cloud Storage di accedere a risorse statiche ospitate su un sito web esterno a Cloud Storage. In questo scenario, il sito web pubblica le intestazioni CORS in modo da consentire l'accesso ai contenuti su storage.googleapis.com.

Come best practice, devi dedicare un bucket specifico a questo accesso ai dati. Questo approccio impedisce che il tuo sito mostri inavvertitamente le risorse statiche in tutto il dominio storage.googleapis.com. Ad esempio, se vuoi dedicare un bucket denominato mybucket per l'accesso ai dati, il sito web deve pubblicare l'intestazione CORS Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com anziché Access-Control-Allow-Origin: https://storage.googleapis.com.

Supporto CORS lato client

La maggior parte dei browser utilizza l'oggetto XMLHttpRequest per effettuare una richiesta tra domini. XMLHttpRequest si occupa di inserire le intestazioni corrette e di gestire l'interazione CORS con il server. Non è necessario aggiungere nuovo codice per sfruttare il supporto CORS sui bucket Cloud Storage.

Passaggi successivi