Cross-Origin Resource Sharing (CORS)

Einrichtung Konfigurationsbeispiele

Cross-Origin Resource Sharing (CORS) ermöglicht clientseitigen Webanwendungen den Zugriff auf Ressourcen aus verschiedenen Quellen. Cloud Storage unterstützt die CORS-Spezifikation (Cross-Origin Resource Sharing). Sie können Ihre Buckets so konfigurieren, dass Ressourcen sicher mit Skripts aus anderen Quellen geteilt werden. Mit CORS können Sie beispielsweise Ihrer Webanwendung https://example-app.appspot.com den Zugriff auf eine Ressource am Ursprung https://example-data.storage.googleapis.com ermöglichen.

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

Funktionsweise von CORS

Verwenden Sie CORS, wenn Ihre Website Dateien, Bilder oder Skripts direkt aus einem Cloud Storage-Bucket mit einer browserbasierten Anfrage abrufen soll.

Domainübergreifenden Zugriff zulassen

Standardmäßig erzwingen Webbrowser eine Sicherheitsmaßnahme namens Same-Origin-Richtlinie. Die Richtlinie für denselben Ursprung verhindert, dass ein Skript auf einer Website mit Ressourcen in einer anderen Domain interagiert. Das schützt Nutzer zwar vor schädlichen Websites, blockiert aber auch legitime Anfragen. Wenn Ihre Webanwendung https://example-app.appspot.com beispielsweise versucht, auf eine Ressource am Ursprung https://example-data.storage.googleapis.com zuzugreifen, blockiert der Browser die Anfrage standardmäßig, da die Domains nicht übereinstimmen.

Die CORS-Spezifikation bietet Servern die Möglichkeit, dem Browser mitzuteilen: „Ich vertraue dieser bestimmten Domain, also erlaube die Anfrage.“

Mit Cloud Storage können Sie eine CORS-Konfiguration für Ihren Bucket festlegen. Wenn Cloud Storage entsprechend konfiguriert ist, sendet es bestimmte HTTP-Header (z. B. Access-Control-Allow-Origin) an den Browser zurück, die den Browser autorisieren, die Ressourcen des Buckets für Ihre Webanwendung freizugeben.

Anfragetypen

CORS-Anfragen funktionieren auf zwei Arten: einfach und Preflight. Eine einfache Anfrage wird direkt ausgeführt, während bei einer Preflight-Anfrage zuerst eine vorläufige Anfrage gesendet wird, um eine Berechtigung zu erhalten.

Einfache Anfragen

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

  1. 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-app.appspot.com.

  2. 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.

  3. 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.

Preflight-Anfragen

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.

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

  1. Der Browser sendet eine OPTIONS-Anfrage, die die Requested Method und die Requested Headers der primären Anfrage enthält.

  2. 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.

Eine ausführlichere Beschreibung von CORS-Anfragen finden Sie in der Fetch-Spezifikation.

CORS-Unterstützung in Cloud Storage

In Cloud Storage können Sie CORS-Konfigurationen auf Bucket-Ebene festlegen. Die Endpunkte der JSON API und der XML API verarbeiten CORS-Anfragen und geben Antwortheader unterschiedlich zurück. Wenn Sie diese Verhaltensweisen kennen, können Sie Ihre Buckets effektiv konfigurieren:

  • 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. Wenn Sie die JSON API verwenden, wird die Konfiguration Ihres Buckets von Cloud Storage nicht ausgewertet. Stattdessen werden Standardheaderwerte zurückgegeben.

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.

Feld1 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.

1 In der Spalte „Feld“ dokumentierte Namen gelten nur für die JSON API. Wenn Sie die XML API verwenden, um eine CORS-Konfiguration festzulegen, verwenden Sie das XML-spezifische Format.

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"].

  • 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>

  • Wenn Anfragen von einem beliebigen Ursprung aus gestellt werden sollen, legen Sie den Ursprung auf das Platzhalterzeichen * fest. Beispiele: "origin": ["*"] in der JSON API oder <Origin>*</Origin> in der XML API. Dieser Ursprung ist zwar hilfreich zum Testen von Konfigurationen, in den meisten Fällen sollten Sie jedoch die Ursprünge von Anfragen einschränken, um eine unerwünschte Nutzung Ihrer Ressourcen zu verhindern.

Weitere Überlegungen

In der folgenden Tabelle werden die Aspekte beschrieben, die bei Anfragen mit Anmeldedaten oder Headern für die Zugriffssteuerung zu berücksichtigen sind:

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.

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