Freigeben über

Konfigurationsreferenz für das IIS CORS-Modul

  • Artikel

vom IIS-Team

Dieser Artikel bietet eine Übersicht über das IIS CORS-Modul und erläutert die Konfiguration des Moduls.

Übersicht über die Funktionalität

Das Microsoft IIS CORS-Modul ist eine Erweiterung, mit der Websites das CORS-Protokoll (Cross-Origin Resource Sharing) unterstützen können.

Das IIS CORS-Modul bietet Webserveradministratoren und Websiteautoren die Möglichkeit, ihre Anwendungen dazu zu bringen, das CORS-Protokoll zu unterstützen. Mit diesem Modul können Entwickler CORS-Logik aus ihren Anwendungen verschieben und sich auf den Webserver verlassen. Die Behandlung von CORS-Anforderungen im Modul wird durch regeln bestimmt, die in der Konfiguration definiert sind. Diese CORS-Regeln können einfach definiert oder konfiguriert werden, sodass die gesamte CORS-Protokollverarbeitung einfach an das Modul delegiert werden kann.

DAS IIS CORS-Modul ist eine serverseitige CORS-Komponente

Das CORS-Protokoll steuert die Kommunikation zwischen Client und Server. In der Regel fungieren Webbrowser als clientseitige CORS-Komponente, während der IIS-Server mit Hilfe des IIS CORS-Moduls als serverseitige CORS-Komponente fungiert.

Eine CORS-Anforderung tritt auf, wenn ein protokollfähiger Client, z. B. ein Webbrowser, eine Anforderung an eine Domäne (Ursprung) sendet, die sich von der aktuellen Domäne unterscheidet. Dieses Szenario wird als ursprungsübergreifende Anforderung bezeichnet. Wenn CORS nicht verwendet wird, werden ursprungsübergreifende Anforderungen vom Client blockiert. Wenn das CORS-Modul verwendet wird, informiert IIS Clients darüber, ob eine ursprungsübergreifende Anforderung basierend auf der IIS-Konfiguration ausgeführt werden kann.

CORS Preflight-Anforderung

Eine CORS-Preflight-Anforderung wird verwendet, um zu bestimmen, ob die angeforderte Ressource so festgelegt ist, dass sie vom Server über die Ursprünge hinweg freigegeben wird. Das CORS-Preflight verwendet die HTTP OPTIONS-Methode mit der ACCESS-CONTROL-REQUEST-METHOD und den ORIGIN-Anforderungsheadern. Das IIS CORS-Modul ist für die Verarbeitung der CORS-Preflight-Anforderungen konzipiert, bevor andere IIS-Module dieselbe Anforderung verarbeiten. Die OPTIONS-Anforderungen sind immer anonym, sodass das CORS-Modul IIS-Servern eine Möglichkeit bietet, ordnungsgemäß auf die Preflight-Anforderung zu reagieren, auch wenn die anonyme Authentifizierung serverseitig deaktiviert werden muss.

CORS-Konfiguration

Der IIS CORS wird über einen Standort oder eine Anwendung web.config Datei konfiguriert und verfügt über einen eigenen cors Konfigurationsabschnitt in system.webServer.

Im Folgenden finden Sie die Konfigurationsbeispiele zum Aktivieren von CORS für eine Website mit dem Namen contentSite. Der * -Ursprung lässt alle Hostherkunft zu; diejenigen, die mit http://* beginnen, werden jedoch später ausgeschlossen. Für den https://*.microsoft.com Hostursprung wird die CORS-Antwort mit verschiedenen CORS-Konfigurationen als Beispiel angepasst.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <cors enabled="true" failUnlistedOrigins="true">
            <add origin="*" />
            <add origin="https://*.microsoft.com"
                 allowCredentials="true"
                 maxAge="120"> 
                <allowHeaders allowAllRequestedHeaders="true">
                    <add header="header1" />
                    <add header="header2" />
                </allowHeaders>
                <allowMethods>
                     <add method="DELETE" />
                </allowMethods>
                <exposeHeaders>
                    <add header="header1" />
                    <add header="header2" />
                </exposeHeaders>
            </add>
            <add origin="http://*" allowed="false" />
        </cors>
    </system.webServer>
</configuration>

Mit dem IIS CORS-Modul haben Sie folgende Möglichkeiten:

  1. Aktivieren und deaktivieren Sie CORS für einen gesamten IIS-Server oder für einen bestimmten IIS-Standort, eine Anwendung, ein virtuelles Verzeichnis, ein physisches Verzeichnis oder eine Datei (system.webServer/cors).
  2. Konfigurieren Sie alle Ursprungshostdomänen, die mit der *-Ursprungshostregel akzeptiert werden sollen.
  3. Konfigurieren Sie die Liste der bestimmten Ursprungshostdomänen, und lassen Sie nur die CORS-Anforderung zu, die denselben Wert des Ursprungsanforderungsheaders wie eine der aufgeführten Ursprungshostdomänen aufweist.
  4. Konfigurieren Sie wild Karte Ursprungshostdomänen beim Konfigurieren der Liste der Ursprungsdomänen wie http://* oder https://*.mydomain.com.
  5. Konfigurieren Sie eine Liste der Ursprungsdomänen, die als CORS-Anforderung nicht zulässig sein sollten.
  6. Passen Sie die CORS-Antwortheaderwerte mit den konfigurierten Werten an.

Attribute des Cors-Elements

Attribut Beschreibung
enabled Optionales boolesches Attribut.
Gibt an, ob CORS aktiviert ist.
Standardwert: false.
failUnlistedOrigins Optionales boolesches Attribut.
Gibt an, ob die CORS-Antwort Code status, der auf 403 festgelegt werden soll, wenn der angeforderte Ursprung nicht mit der konfigurierten Ursprungsliste übereinstimmt oder ob der Ursprungshost so konfiguriert ist, dass er nicht zugelassen wird.
Standardwert: false.

Hinzufügen von Ursprungsregel <hinzufügen>

Ursprungsregeln

Das <add> Element der <cors> Auflistung gibt einen einzelnen Ursprung an, der der Liste der Ursprungsregeln hinzugefügt werden soll.

Attribute der Ursprungsregel

Attribut Beschreibung
origin Erforderliches Zeichenfolgenattribut.
Gibt den Ursprungshost an, für den eine Ursprungsregel auferlegt werden soll. Sie können ein Sternchen (*) verwenden, um diese Regel auf alle Ursprungsanforderungsheaderwerte anzuwenden. Sie können auch ein Sternchen (*) als Platzhalter für den untergeordneten Unterdomänennamen verwenden. Wenn mehrere Ursprungsregeln vorhanden sind, wird sie unabhängig vom zulässigen Attributwert auf die spezifischste Ursprungshostnamenregel angewendet.
allowed Optionales boolesches Attribut.
Gibt an, ob die CORS-Anforderung für den Ursprungshost akzeptiert werden soll.
Standardwert: true.
allowCredentials Optionales boolesches Attribut.
Gibt an, ob der Access-Control-Allow-Credentials: true CORS-Antwortheader festgelegt werden soll. Dieses Attribut sollte nur für einen bestimmten Ursprungshostnamen und nicht für * Ursprungshost für die CORS-Protokollkonformität verwendet werden.
Standardwert: false.
maxAge Optionales Ganzzahlattribut. Dauer in Sekunden.
Gibt den Wert des Access-Control-Max-Age Antwortheaders für die Preflight-CORS-Anforderung an. Der Access-Control-Max-Age-Antwortheader sollte nur für die CORS-Preflight-Anforderungen festgelegt werden. Wenn Sie den Access-Control-Max-Age-Header in der CORS-Antwort nicht festlegen möchten, legen Sie -1 für dieses Attribut fest.
Standardwert: -1.

Nur * Ursprungshostregel verwenden

Wenn nur die Ursprungshostregel * vorhanden ist, weist das IIS CORS-Modul ein anderes Verhalten auf als bei einer bestimmten Ursprungshostnamenregel. Wenn nur die *-Ursprungshostregel vorhanden ist, führt das IIS CORS-Modul folgendes aus:

  1. Der Wert des Access-Control-Allow-Origin-Antwortheaders wird unabhängig vom Wert des Anforderungsheaders, der origin von der clientseitigen CORS-Komponente gesendet wird, auf * festgelegt.
  2. Vary: origin Der Antwortheader wird nicht hinzugefügt, da IIS CORS keine anderen Zugriffssteuerungs-Allow-Origin-Antwortheaderwerte als * generiert und es nicht erforderlich ist, den Wert vary: origin response header zu verwenden.

Untergeordnete Elemente der Ursprungshostregel

Element Beschreibung
allowHeaders konfiguriert die allowHeaders-Auflistung , die für den Wert des Access-Control-Allow-Headers CORS-Antwortheaders für den in der Ursprungshostregel angegebenen Ursprungshost verwendet wird.
Der Access-Control-Allow-Headers Antwortheader wird nur für die tatsächlichen CORS-Anforderungen und nicht für die Preflight-Anforderungen festgelegt.
allowMethods konfiguriert die allowMethods-Auflistung , die für den Wert des Access-Control-Allow-Methods CORS-Antwortheaders für den in der Ursprungshostregel angegebenen Ursprungshost verwendet wird.
Der Access-Control-Allow-Methods Antwortheader wird nur für die CORS-Preflight-Anforderungen festgelegt.
exposeHeaders konfiguriert die exposeHeaders-Auflistung , die für den Wert des Access-Control-Expose-Headers CORS-Antwortheaders für den in der Ursprungshostregel angegebenen Ursprungshost verwendet wird.
Der Access-Control-Expose-Headers Antwortheader wird nur für die tatsächlichen CORS-Anforderungen und nicht für die Preflight-Anforderungen festgelegt.

Attribute des allowHeaders-Elements

Attribut Beschreibung
allowAllRequestedHeaders Optionales boolesches Attribut. Wenn dies der Fall ist, übernimmt das IIS-Modul den Wert des angegebenen Access-Control-Request-Headers CORS-Anforderungsheaders und legt den Access-Control-Allow-Headers-Antwortheader mit dem gleichen Wert fest, was bedeutet, dass alle angegebenen Header zulässig sind. Wenn dies false ist, legt er den Access-Control-Allow-Headers-Antwortheader mit den Headerwerten der allowHeaders-Auflistung fest, was bedeutet, dass nur die aufgeführten Header zulässig sind. Standardwert: false.

Beispielcode

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample {

    private static void Main() {

        using(ServerManager serverManager = new ServerManager()) {
            Configuration config = serverManager.GetWebConfiguration("contentSite");

            ConfigurationSection corsSection = config.GetSection("system.webServer/cors");
            corsSection["enabled"] = true;
            corsSection["failUnlistedOrigins"] = true;

            ConfigurationElementCollection corsCollection = corsSection.GetCollection();

            ConfigurationElement addElement = corsCollection.CreateElement("add");
            addElement["origin"] = @"*";
            corsCollection.Add(addElement);

            ConfigurationElement addElement1 = corsCollection.CreateElement("add");
            addElement1["origin"] = @"https://*.microsoft.com";
            addElement1["allowCredentials"] = true;
            addElement1["maxAge"] = 120;

            ConfigurationElement allowHeadersElement = addElement1.GetChildElement("allowHeaders");
            allowHeadersElement["allowAllRequestedHeaders"] = true;

            ConfigurationElementCollection allowHeadersCollection = allowHeadersElement.GetCollection();

            ConfigurationElement addElement2 = allowHeadersCollection.CreateElement("add");
            addElement2["header"] = @"header1";
            allowHeadersCollection.Add(addElement2);

            ConfigurationElement addElement3 = allowHeadersCollection.CreateElement("add");
            addElement3["header"] = @"header2";
            allowHeadersCollection.Add(addElement3);

            ConfigurationElementCollection allowMethodsCollection = addElement1.GetCollection("allowMethods");

            ConfigurationElement addElement4 = allowMethodsCollection.CreateElement("add");
            addElement4["method"] = @"DELETE";
            allowMethodsCollection.Add(addElement4);

            ConfigurationElementCollection exposeHeadersCollection = addElement1.GetCollection("exposeHeaders");

            ConfigurationElement addElement5 = exposeHeadersCollection.CreateElement("add");
            addElement5["header"] = @"header1";
            exposeHeadersCollection.Add(addElement5);

            ConfigurationElement addElement6 = exposeHeadersCollection.CreateElement("add");
            addElement6["header"] = @"header2";
            exposeHeadersCollection.Add(addElement6);
            corsCollection.Add(addElement1);

            ConfigurationElement addElement7 = corsCollection.CreateElement("add");
            addElement7["origin"] = @"http://*";
            addElement7["allowed"] = false;
            corsCollection.Add(addElement7);

            serverManager.CommitChanges();
        }
    }
}

JavaScript


var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/contentSite";

var corsSection = adminManager.GetAdminSection("system.webServer/cors", "MACHINE/WEBROOT/APPHOST/contentSite");
corsSection.Properties.Item("enabled").Value = true;
corsSection.Properties.Item("failUnlistedOrigins").Value = true;

var corsCollection = corsSection.Collection;

var addElement = corsCollection.CreateNewElement("add");
addElement.Properties.Item("origin").Value = "*";
corsCollection.AddElement(addElement);


var addElement1 = corsCollection.CreateNewElement("add");
addElement1.Properties.Item("origin").Value = "https://*.microsoft.com";
addElement1.Properties.Item("allowCredentials").Value = true;
addElement1.Properties.Item("maxAge").Value = 120;
var allowHeadersElement = addElement1.ChildElements.Item("allowHeaders");
allowHeadersElement.Properties.Item("allowAllRequestedHeaders").Value = true;

var allowHeadersCollection = allowHeadersElement.Collection;

var addElement2 = allowHeadersCollection.CreateNewElement("add");
addElement2.Properties.Item("header").Value = "header1";
allowHeadersCollection.AddElement(addElement2);


var addElement3 = allowHeadersCollection.CreateNewElement("add");
addElement3.Properties.Item("header").Value = "header2";
allowHeadersCollection.AddElement(addElement3);


var allowMethodsCollection = addElement1.ChildElements.Item("allowMethods").Collection;

var addElement4 = allowMethodsCollection.CreateNewElement("add");
addElement4.Properties.Item("method").Value = "DELETE";
allowMethodsCollection.AddElement(addElement4);


var exposeHeadersCollection = addElement1.ChildElements.Item("exposeHeaders").Collection;

var addElement5 = exposeHeadersCollection.CreateNewElement("add");
addElement5.Properties.Item("header").Value = "header1";
exposeHeadersCollection.AddElement(addElement5);


var addElement6 = exposeHeadersCollection.CreateNewElement("add");
addElement6.Properties.Item("header").Value = "header2";
exposeHeadersCollection.AddElement(addElement6);

corsCollection.AddElement(addElement1);


var addElement7 = corsCollection.CreateNewElement("add");
addElement7.Properties.Item("origin").Value = "http://*";
addElement7.Properties.Item("allowed").Value = false;
corsCollection.AddElement(addElement7);


adminManager.CommitChanges();

Befehlszeile (AppCmd)

appcmd.exe set config "contentSite" -section:system.webServer/cors /enabled:"True" /failUnlistedOrigins:"True"

appcmd.exe set config "contentSite" -section:system.webServer/cors /+"[origin='*']"

appcmd.exe set config "contentSite" -section:system.webServer/cors /+"[origin='https://*.microsoft.com',allowCredentials='True',maxAge='120']"
appcmd.exe set config "contentSite" -section:system.webServer/cors /[origin='https://*.microsoft.com',allowCredentials='True',maxAge='120'].allowHeaders.allowAllRequestedHeaders:"True"

appcmd.exe set config "contentSite" -section:system.webServer/cors /+"[origin='https://*.microsoft.com',allowCredentials='True',maxAge='120'].allowHeaders.[header='header1']"

appcmd.exe set config "contentSite" -section:system.webServer/cors /+"[origin='https://*.microsoft.com',allowCredentials='True',maxAge='120'].allowHeaders.[header='header2']"

appcmd.exe set config "contentSite" -section:system.webServer/cors /+"[origin='https://*.microsoft.com',allowCredentials='True',maxAge='120'].allowMethods.[method='DELETE']"

appcmd.exe set config "contentSite" -section:system.webServer/cors /+"[origin='https://*.microsoft.com',allowCredentials='True',maxAge='120'].exposeHeaders.[header='header1']"

appcmd.exe set config "contentSite" -section:system.webServer/cors /+"[origin='https://*.microsoft.com',allowCredentials='True',maxAge='120'].exposeHeaders.[header='header2']"

appcmd.exe set config "contentSite" -section:system.webServer/cors /+"[origin='http://*',allowed='False']"

PowerShell

Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors" -name "enabled" -value "True"
Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors" -name "failUnlistedOrigins" -value "True"

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors" -name "." -value @{origin='*'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors" -name "." -value @{origin='https://*.microsoft.com';allowCredentials='True';maxAge=120}
Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors/add[@origin='https://*.microsoft.com']/allowHeaders" -name "allowAllRequestedHeaders" -value "True"

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors/add[@origin='https://*.microsoft.com']/allowHeaders" -name "." -value @{header='header1'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors/add[@origin='https://*.microsoft.com']/allowHeaders" -name "." -value @{header='header2'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors/add[@origin='https://*.microsoft.com']/allowMethods" -name "." -value @{method='DELETE'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors/add[@origin='https://*.microsoft.com']/exposeHeaders" -name "." -value @{header='header1'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors/add[@origin='https://*.microsoft.com']/exposeHeaders" -name "." -value @{header='header2'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/contentSite'  -filter "system.webServer/cors" -name "." -value @{origin='http://*';allowed='False'}