condivisione delle risorse tra origini (CORS)

Configurazione Esempi di configurazione

La condivisione di risorse multiorigine (CORS) consente alle applicazioni web lato client di accedere alle risorse di origini diverse. Cloud Storage supporta la specifica CORS, consentendoti di configurare i bucket per condividere le risorse in modo sicuro con script di altre origini. Ad esempio, puoi utilizzare CORS per consentire alla tua applicazione web https://example-app.appspot.com di accedere a una risorsa nell'origine https://example-data.storage.s3nsapis.fr.

Per saperne di più sui componenti della configurazione CORS, consulta Imposta CORS bucket.

Come funziona CORS

Utilizza CORS quando vuoi che il tuo sito web recuperi file, immagini o script direttamente da un bucket Cloud Storage utilizzando una richiesta basata su browser.

Consentire l'accesso tra domini

Per impostazione predefinita, i browser web applicano una misura di sicurezza chiamata policy della stessa origine. Il criterio della stessa origine impedisce a uno script su un sito web di interagire con le risorse di un dominio diverso. Sebbene questo protegga gli utenti dai siti dannosi, blocca anche le richieste legittime. Ad esempio, se l'applicazione web https://example-app.appspot.com tenta di accedere a una risorsa nell'origine https://example-data.storage.s3nsapis.fr, il browser bloccherà la richiesta per impostazione predefinita perché i domini non corrispondono.

La specifica CORS consente ai server di comunicare al browser: "Mi fido di questo dominio specifico, quindi procedi e consenti la richiesta".

Cloud Storage ti consente di impostare una configurazione CORS sul tuo bucket. Se configurato, Cloud Storage invia al browser intestazioni HTTP specifiche (ad esempio Access-Control-Allow-Origin) che autorizzano il browser a condividere le risorse del bucket con la tua applicazione web.

Tipi di richiesta

Le richieste CORS funzionano in due modi: semplici e preflight. Una richiesta semplice procede direttamente, mentre una richiesta preflight invia prima una richiesta preliminare per ottenere l'autorizzazione.

Richieste semplici

Quando un browser effettua una richiesta semplice a Cloud Storage, si verifica il seguente processo:

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

  2. Cloud Storage confronta il metodo HTTP della richiesta e il valore dell'intestazione Origin con le informazioni Methods e Origins nella configurazione CORS del bucket di destinazione per verificare se esistono corrispondenze. In questo caso, Cloud Storage include l'intestazione Access-Control-Allow-Origin nella 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 va a buon fine. Se non corrispondono o se l'intestazione Access-Control-Allow-Origin non è presente nella risposta, la richiesta non va a buon fine.

Richieste preflight

Una richiesta viene sottoposta a preflight 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.

Una richiesta preflight esegue prima i seguenti passaggi. Se l'esito è positivo, segue la stessa procedura di una richiesta semplice:

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

  2. Cloud Storage risponde con i valori dei metodi e delle intestazioni HTTP consentiti dalla risorsa di destinazione. Se uno dei valori del metodo o dell'intestazione nella richiesta di verifica preliminare non è presente nell'insieme di metodi e intestazioni consentiti dalla risorsa di destinazione, la richiesta non va a buon fine e la richiesta principale non viene inviata.

Per una descrizione più completa delle richieste CORS, leggi la specifica Fetch.

Supporto CORS di Cloud Storage

Cloud Storage consente di impostare le configurazioni CORS a livello di bucket. Gli endpoint API JSON e API XML gestiscono le richieste CORS e restituiscono le intestazioni della risposta in modo diverso. Comprendi questi comportamenti per configurare i bucket in modo efficace:

  • Gli endpoint API JSON consentono sempre le richieste CORS e restituiscono valori predefiniti nelle intestazioni della risposta CORS, indipendentemente dalla configurazione impostata sul bucket.

  • Gli endpoint API XML consentono solo richieste CORS basate sulla configurazione del bucket e restituiscono valori di intestazione CORS specifici in risposta a questa configurazione.

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

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

storage.s3nsapis.fr/BUCKET_NAME
 
BUCKET_NAME.storage.s3nsapis.fr

Per informazioni sugli URL delle richieste API XML, consulta Endpoint di richiesta.

Componenti di una configurazione CORS

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

La tabella seguente descrive i campi di una configurazione CORS e il comportamento di risposta delle API XML e JSON. Per scoprire come vengono utilizzati questi campi, consulta gli esempi di configurazione CORS.

Campo1 Descrizione Comportamento della risposta dell'API XML Comportamento della risposta dell'API JSON
origin Specifica le origini che vuoi consentire per 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 esiste una corrispondenza, Cloud Storage non include Access-Control-Allow-Origin nella risposta. Puoi fornire un valore con carattere 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 che vuoi consentire per 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 confronta i metodi inviati dal browser nell'intestazione Access-Control-Request-Methods con la configurazione CORS del bucket. Se non esiste una corrispondenza, 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 le intestazioni che vuoi consentire per 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 confronta le intestazioni inviate dal browser nell'intestazione Access-Control-Request-Headers con la configurazione CORS del bucket. Se non esiste una corrispondenza, Cloud Storage non restituisce le intestazioni della risposta CORS. Cloud Storage restituisce l'intestazione Access-Control-Allow-Headers impostata in modo che corrisponda ai valori specificati dall'intestazione Access-Control-Request-Headers.
maxAgeSeconds (facoltativo) Specifica il numero di secondi per cui il browser è autorizzato a effettuare richieste prima di dover ripetere la richiesta preflight. Questo è anche noto come data di scadenza della cache. Questo valore viene restituito nell'intestazione Access-Control-Max-Age nelle risposte alle richieste di 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 3600. Cloud Storage restituisce l'intestazione Access-Control-Max-Age con il valore predefinito 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 specifico per XML.

Specifica di più origini, metodi o intestazioni

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

  • 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 l'invio di richieste da qualsiasi origine, imposta l'origine sul carattere jolly *. 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 è consigliabile limitare le origini delle richieste per impedire l'utilizzo indesiderato delle risorse.

Ulteriori considerazioni

La tabella seguente descrive le 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 viene impostata su true.

Per le richieste preflight, se 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 quali intestazioni potrebbe includere una futura richiesta CORS. 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 della risposta 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 alle risorse statiche ospitate su un sito web esterno a Cloud Storage. In questo scenario, il sito web fornisce intestazioni CORS in modo che i contenuti su storage.s3nsapis.fr possano accedere.

Come best practice, devi dedicare un bucket specifico per questo accesso ai dati. Questo approccio impedisce al tuo sito di esporre inavvertitamente risorse statiche a tutto storage.s3nsapis.fr. Ad esempio, se vuoi dedicare un bucket denominato mybucket all'accesso ai dati, devi fare in modo che il sito web fornisca l'intestazione CORS Access-Control-Allow-Origin: https://mybucket.storage.s3nsapis.fr anziché Access-Control-Allow-Origin: https://storage.s3nsapis.fr.

Supporto CORS lato client

La maggior parte dei browser utilizza l'oggetto XMLHttpRequest per effettuare una richiesta tra domini. XMLHttpRequest si occupa di tutto il lavoro di inserimento delle intestazioni giuste e di gestione dell'interazione CORS con il server. Ciò significa che non devi aggiungere nuovo codice per sfruttare il supporto di CORS nei bucket Cloud Storage.

Passaggi successivi