Cross-Origin Resource Sharing (CORS)

Einrichtung Konfigurationsbeispiele

Die Richtlinie für denselben Ursprung ist eine Sicherheitsrichtlinie, die auf clientseitigen Webanwendungen (z. B. Webbrowsern) erzwungen wird, um Interaktionen zwischen Ressourcen unterschiedlicher Herkunft zu verhindern. Durch diese Sicherheitsmaßnahme wird böswilliges Verhalten unterbunden, sie kann aber auch legitime Interaktionen zwischen Ressourcen bekannter Herkunft stören. Beispiel: Ein Script auf einer Seite, die unter example.appspot.com gehostet wird, muss möglicherweise Ressourcen verwenden, die in einem Cloud Storage-Bucket unter example.storage.googleapis.com gespeichert sind. Aus Browsersicht handelt es sich hierbei um zwei unterschiedliche Herkunftsorte. Das Script auf example.appspot.com möchte Ressourcen von example.storage.googleapis.com abrufen, der Browser lässt dies aber nicht zu.

Die Spezifikation Cross-Origin Resource Sharing (CORS) wurde vom World Wide Web Consortium (W3C) entwickelt, um diese Einschränkung zu umgehen. Cloud Storage unterstützt diese Spezifikation und Buckets können so konfiguriert werden, dass sie CORS unterstützen. Wenn Sie das obige Beispiel fortsetzen, können Sie den Bucket example.storage.googleapis.com so konfigurieren, dass ein Browser seine Ressourcen mit Skripts von example.appspot.com teilen kann.

Weitere Informationen zu CORS-Konfigurationskomponenten finden Sie unter Bucket-CORS festlegen.

Funktionsweise von CORS

Es gibt zwei Arten von CORS-Anfragen: einfache Anfragen und Preflight-Anfragen. Eine einfache Anfrage kann direkt gestellt werden. Eine Preflight-Anfrage muss eine vorläufige Preflight-Anfrage an den Server senden, um eine Berechtigung zu erhalten. Erst dann kann die primäre Anfrage fortgesetzt werden. Eine Anfrage gilt als Preflight-Anfrage, wenn einer der folgenden Umstände zutrifft:

Sie verwendet andere Methoden als GET, HEAD oder POST.
Sie verwendet die Methode POST mit einem anderen Content-Type als text/plain, application/x-www-form-urlencoded oder multipart/form-data.
Sie legt benutzerdefinierte Header fest. Beispiel: X-PINGOTHER.

Der folgende Prozess tritt auf, wenn ein Browser eine einfache Anfrage an Cloud Storage sendet:

Der Browser fügt der Anfrage den Header Origin hinzu. Der Header Origin enthält den Ursprung der Ressource, die die Ressourcen des Cloud Storage-Buckets freigeben möchte, z. B. Origin:https://www.example.appspot.com.
Cloud Storage vergleicht die HTTP-Methode der Anfrage und den Wert des Headers Origin mit den Informationen zu Methoden und Ursprüngen in der CORS-Konfiguration des Ziel-Buckets, um festzustellen, ob Übereinstimmungen vorhanden sind. Ist dies der Fall, schließt Cloud Storage den Header Access-Control-Allow-Origin in die Antwort ein. Der Header Access-Control-Allow-Origin enthält den Wert des Headers Origin aus der ersten Anfrage.
Der Browser empfängt die Antwort und überprüft, ob der Wert Access-Control-Allow-Origin mit der in der ursprünglichen Anfrage angegebenen Domain übereinstimmt. Wenn sie übereinstimmen, ist die Anfrage erfolgreich. Wenn sie nicht übereinstimmen oder der Header Access-Control-Allow-Origin nicht in der Antwort vorhanden ist, schlägt die Anfrage fehl.

Eine Preflight-Anfrage führt zuerst die folgenden Schritte aus. Wenn dieses Vorgehen erfolgreich ist, erfolgt der gleiche Prozess wie bei einer einfachen Anfrage:

Der Browser sendet eine OPTIONS-Anfrage, die die Requested Method und die Requested Headers der primären Anfrage enthält.
Cloud Storage antwortet mit den Werten der HTTP-Methoden und -Header, die von der Zielressource zugelassen werden. Wenn einer der Methoden- oder Headerwerte in der Preflight-Anfrage nicht in dem von der Zielressource zulässigen Satz von Methoden und Headern enthalten ist, schlägt die Anfrage fehl und die primäre Anfrage wird nicht gesendet.

Dies ist eine vereinfachte Beschreibung von CORS. Eine ausführlichere Beschreibung finden Sie in der Fetch-Spezifikation.

CORS-Unterstützung in Cloud Storage

Mit Cloud Storage können Sie eine CORS-Konfiguration nur auf Bucket-Ebene festlegen. Sie können eine CORS-Konfiguration für einen Bucket mithilfe verschiedener Tools einrichten. Die verschiedenen Cloud Storage-Endpunkte behandeln jedoch CORS-Anfragen unterschiedlich:

Endpunkte der JSON API erlauben CORS-Anfragen immer und geben Standardwerte in den CORS-Antwortheadern zurück, unabhängig von der im Bucket festgelegten Konfiguration.
Endpunkte der XML API erlauben CORS-Anfragen nur anhand der Konfiguration im Bucket zu und geben als Antwort auf diese Konfiguration bestimmte CORS-Headerwerte zurück.
Der authentifizierte Endpunkt des Browserdownloads storage.cloud.google.com lässt keine CORS-Anfragen zu. Beachten Sie, dass die Google Cloud Console diesen Endpunkt für den öffentlichen URL-Link der verschiedenen Objekte bereitstellt.

Sie können eine der folgenden XML API-Anfrage-URLs verwenden, um eine Antwort von Cloud Storage abzurufen, welche die CORS-Header enthält:

storage.googleapis.com/BUCKET_NAME

BUCKET_NAME.storage.googleapis.com

Weitere Informationen zu XML API-Anfrage-URLs finden Sie unter Anfrageendpunkte.

Komponenten einer CORS-Konfiguration

Wenn Sie die XML API verwenden, bestimmen die Werte, die Sie in der CORS-Konfiguration Ihres Buckets festlegen, welche CORS-Header Cloud Storage in einer HTTP-Antwort zurückgibt. Bei Verwendung der JSON API wertet Cloud Storage die Konfiguration Ihres Buckets nicht aus und gibt stattdessen Standardheaderwerte zurück.

In der folgenden Tabelle werden die Felder in einer CORS-Konfiguration und das Antwortverhalten der XML API und der JSON API beschrieben. Informationen zur Verwendung dieser Felder finden Sie unter CORS-Konfigurationsbeispiele.

Feld¹	Beschreibung	Antwortverhalten bei Verwendung der XML API	Antwortverhalten bei Verwendung der JSON API
`origin`	Geben Sie den Ursprung an, den Sie für Cross-Origin Resource Sharing mit diesem Cloud Storage-Bucket zulassen möchten. Beispiel: `https://origin1.example.com`.	Wenn der Ursprung in der Anfrage eines Browsers mit dem Ursprung in Ihrer CORS-Konfiguration übereinstimmt, gibt Cloud Storage `Access-Control-Allow-Origin` an den Browser zurück. Wenn es keine Übereinstimmung gibt, fügt Cloud Storage `Access-Control-Allow-Origin` nicht in die Antwort ein. Sie können den Platzhalterwert `<Origin>*</Origin>` angeben. Dieser Wert gewährt Zugriff auf alle Ursprünge.	Cloud Storage gibt den Header `Access-Control-Allow-Origin` zurück, der auf den Ursprung der Anfrage festgelegt ist.
`method`	Geben Sie HTTP-Methoden an, die für Cross-Origin Resource Sharing mit diesem Cloud Storage-Bucket zugelassen werden sollen. Der Wert wird als Antwort auf erfolgreiche Preflight-Anfragen im Header `Access-Control-Allow-Methods` zurückgegeben. Da `OPTIONS` eine Standardmethode ist, mit der Browser Preflight-Anfragen initiieren, sollten Sie `OPTIONS` nicht in Ihrer CORS-Konfiguration angeben.	Cloud Storage unterstützt die folgenden Methoden: `DELETE`, `GET`, `HEAD`, `POST` und `PUT`. Cloud Storage prüft die vom Browser im Header `Access-Control-Request-Methods` gesendeten Methoden anhand der CORS-Konfiguration des Buckets. Wenn keine Übereinstimmung vorliegt, gibt Cloud Storage einen `200`-Antwortcode ohne CORS-Antwortheader zurück.	Cloud Storage gibt den Header `Access-Control-Allow-Methods` zurück, in dem die folgenden Methoden festgelegt sind: `DELETE`, `GET`, `HEAD`, `PATCH`, `POST` und `PUT`.
`responseHeader`	Geben Sie an, welche Header für Cross-Origin Resource Sharing mit diesem Cloud Storage-Bucket zugelassen werden sollen. Der Wert wird als Antwort auf erfolgreiche Preflight-Anfragen im Header `Access-Control-Allow-Headers` zurückgegeben.	Bei Preflight-Anfragen prüft Cloud Storage die vom Browser gesendeten Header im Header `Access-Control-Request-Headers` anhand der CORS-Konfiguration des Buckets. Wenn keine Übereinstimmung gefunden wird, gibt Cloud Storage keine CORS-Antwortheader zurück.	Cloud Storage gibt den Header `Access-Control-Allow-Headers` zurück, der den im Header `Access-Control-Request-Headers` angegebenen Werten entspricht.
`maxAgeSeconds` (optional)	Geben Sie an, wie viele Sekunden lang der Browser Anfragen senden darf, bevor die Preflight-Anfrage wiederholt werden muss. Dies wird auch als Cache-Ablaufzeit bezeichnet. Der Wert wird im Header `Access-Control-Max-Age` in Antworten auf Preflight-Anfragen zurückgegeben. Beispielsweise wird mit `3600` die Cache-Ablaufzeit auf eine Stunde festgelegt.	Cloud Storage gibt den Header `Access-Control-Max-Age` mit der angegebenen Cache-Ablaufzeit zurück. Wenn Sie dieses Feld weglassen, gibt Cloud Storage den Standardwert `3600` zurück.	Cloud Storage gibt den Header `Access-Control-Max-Age` mit dem Standardwert `3600` zurück.

¹ In der Spalte „Feld“ dokumentierte Namen gelten nur für die JSON API. Verwenden Sie das XML-spezifische Format, wenn Sie die XML API zum Festlegen einer CORS-Konfiguration verwenden.

Mehrere Ursprünge, Methoden oder Header angeben

Informationen zum Festlegen mehrerer Ursprünge, Methoden oder Header in einer CORS-Konfiguration finden Sie in der folgenden Liste:

Bei Verwendung der JSON API können Sie mehrere Ursprünge, Methoden oder Header mithilfe eines durch Kommas getrennten Arrays angeben. Beispiel: "method": ["GET", "PUT"].

Achtung: Wenn Sie eine CORS-Konfiguration mit der JSON API festlegen, werden Anfragen von allen Ursprüngen unabhängig vom Feldwert origin in der CORS-Konfiguration akzeptiert.
Bei Verwendung der XML API können Sie mehrere Ursprünge, Methoden oder Header mithilfe separater Elemente angeben. Beispiel:
```
<Methods>
  <Method>PUT</Method>
  <Method>GET</Method>
</Methods>
```
Damit Anfragen von jedem Ursprung gesendet werden können, legen Sie den Ursprung auf * fest. Beispiel: "origin": ["*"] in der JSON API oder <Origin>*</Origin> in der XML API. Dieser Ursprung ist zwar zum Testen von Konfigurationen hilfreich, aber in den meisten Fällen ist es sinnvoll, Anfrageursprünge einzuschränken, um eine unerwünschte Nutzung Ihrer Ressourcen zu verhindern.

Weitere Überlegungen

In der folgenden Tabelle werden Überlegungen zu Anfragen mit Anmeldedaten oder Zugriffssteuerungsheadern beschrieben:

Attribut oder Titel Beschreibung Antwortverhalten bei Verwendung der XML API Antwortverhalten bei Verwendung der JSON API

Anmeldedaten

Cookies, Autorisierungsheader oder TLS-Clientzertifikate

Attribut oder Titel	Beschreibung	Antwortverhalten bei Verwendung der XML API	Antwortverhalten bei Verwendung der JSON API
Anmeldedaten	Cookies, Autorisierungsheader oder TLS-Clientzertifikate	Cloud Storage gibt den Header `Access-Control-Allow-Credentials` nie zurück. CORS-Anmeldedaten werden von der XML API nicht unterstützt.	Bei einfachen Anfragen wird für den Header `Access-Control-Allow-Credentials` der Wert "true" festgelegt, wenn die CORS-Anfrage genehmigt ist. Wenn für Preflight-Anfragen `Access-Control-Request-Method` leer ist, setzt Cloud Storage `Access-Control-Allow-Credentials` auf "true" und lehnt die Anfrage mit `404 - Not Found` ab.
Angezeigte Header	Bei Preflight-Anfragen gibt der Anfrageheader `Access-Control-Request-Headers` an, welche Header eine zukünftige CORS-Anfrage enthalten können. Der Antwortheader `Access-Control-Expose-Headers` ist in der Antwort des Servers enthalten und gibt dem Client an, welche Header angezeigt werden können.	Bei einfachen Anfragen gibt `Access-Control-Expose-Headers` die Werte der Antwortheader in der CORS-Konfiguration an.	Bei einfachen Anfragen gibt `Access-Control-Expose-Headers` die in `Access-Control-Request-Headers` angegebenen Werte zurück, wenn sie Teil einer Liste gängiger HTTP-Header sind.

Cloud Storage gibt den Header Access-Control-Allow-Credentials nie zurück. CORS-Anmeldedaten werden von der XML API nicht unterstützt.

Bei einfachen Anfragen wird für den Header Access-Control-Allow-Credentials der Wert "true" festgelegt, wenn die CORS-Anfrage genehmigt ist.

Wenn für Preflight-Anfragen Access-Control-Request-Method leer ist, setzt Cloud Storage Access-Control-Allow-Credentials auf "true" und lehnt die Anfrage mit 404 - Not Found ab.

Angezeigte Header Bei Preflight-Anfragen gibt der Anfrageheader Access-Control-Request-Headers an, welche Header eine zukünftige CORS-Anfrage enthalten können. Der Antwortheader Access-Control-Expose-Headers ist in der Antwort des Servers enthalten und gibt dem Client an, welche Header angezeigt werden können. Bei einfachen Anfragen gibt Access-Control-Expose-Headers die Werte der Antwortheader in der CORS-Konfiguration an. Bei einfachen Anfragen gibt Access-Control-Expose-Headers die in Access-Control-Request-Headers angegebenen Werte zurück, wenn sie Teil einer Liste gängiger HTTP-Header sind.

Buckets den Zugriff auf externe Ressourcen gewähren

Manchmal müssen Sie in Cloud Storage gehosteten Skripts Zugriff auf statische Ressourcen gewähren, die auf einer Website außerhalb von Cloud Storage gehostet sind. In diesem Szenario stellt die Website CORS-Header bereit, sodass den Inhalten von storage.googleapis.com Zugriff gewährt wird.

Als Best Practice sollten Sie für diesen Datenzugriff einen bestimmten Bucket zuweisen. Dadurch wird verhindert, dass die Website statische Ressourcen versehentlich für alle Inhalte von storage.googleapis.com freigibt. Wenn Sie beispielsweise einen Bucket namens mybucket für den Datenzugriff zuweisen möchten, sollte die Website den CORS-Header Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com statt Access-Control-Allow-Origin: https://storage.googleapis.com bereitstellen.

Clientseitiger CORS-Support

In den meisten Browsern wird für domainübergreifende Anfragen das Objekt XMLHttpRequestverwendet. XMLHttpRequest übernimmt das Einfügen der richtigen Header und steuert die Verarbeitung der CORS-Interaktion auf dem Server. Sie müssen keinen neuen Code hinzufügen, um die CORS-Unterstützung für Cloud Storage-Buckets zu nutzen.

Nächste Schritte

CORS für Buckets aktivieren
CORS-Konfigurationsbeispiele ansehen, einschließlich eines Beispiels, bei dem die CORS-Konfiguration für einen Bucket entfernt wird.