IIS CORS-Modulkonfigurationsreferenz

vom IIS-Team

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

Übersicht über die Funktionalität

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

Das IIS CORS-Modul bietet eine Möglichkeit für Webserveradministratoren und Websiteautoren, ihre Anwendungen zur Unterstützung des CORS-Protokolls zu machen. Mit diesem Modul können Entwickler CORS-Logik aus ihren Anwendungen heraus verschieben und sich auf den Webserver verlassen. Die Behandlung von CORS-Anforderungen durch das Modul wird durch regeln bestimmt, die in der Konfiguration definiert sind. Diese CORS-Regeln können einfach definiert oder konfiguriert werden, wodurch es einfach ist, alle CORS-Protokollbehandlungen an das Modul zu delegieren.

DAS IIS CORS-Modul ist eine serverseitige CORS-Komponente

Das CORS-Protokoll steuert die Client-/Serverkommunikation. In der Regel fungieren Webbrowser als clientseitige CORS-Komponente, während der IIS-Server als serverseitige CORS-Komponente mit Hilfe des IIS CORS-Moduls funktioniert.

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 angesprochene Ressource vom Server herkunftsübergreifend freigegeben werden kann. Das CORS-Preflight verwendet die HTTP OPTIONS-Methode mit den Anforderungsheadern ACCESS-CONTROL-REQUEST-METHOD und ORIGIN. Das IIS CORS-Modul wurde entwickelt, um die CORS-Preflight-Anforderungen zu verarbeiten, bevor andere IIS-Module dieselbe Anforderung verarbeiten. Die OPTIONS-Anfragen sind immer anonym, sodass das CORS-Modul es den IIS-Servern ermöglicht, ordnungsgemäß auf die Preflight-Anfrage zu antworten, selbst wenn die anonyme Authentifizierung für den gesamten Server deaktiviert werden muss.

CORS-Konfiguration

Das IIS CORS wird über eine Website oder Anwendung web.config Datei konfiguriert und verfügt über einen eigenen cors Konfigurationsabschnitt innerhalb system.webServerder Datei.

Im Folgenden finden Sie die Konfigurationsbeispiele zum Aktivieren von CORS für eine Website mit dem Namen "contentSite". Der * Ursprung erlaubt alle Host-Ursprünge; allerdings werden diejenigen, die mit http://* beginnen, später ausgeschlossen. Für die Herkunft des https://*.microsoft.com Hosts wird die CORS-Antwort exemplarisch mit verschiedenen CORS-Konfigurationen 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, deaktivieren Sie CORS für einen ganzen IIS-Server oder für eine bestimmte IIS-Website, eine Anwendung, ein virtuelles Verzeichnis, ein physisches Verzeichnis oder eine Datei (system.webServer/cors).
2. Konfigurieren Sie alle Ursprungshostdomänen, die mit *origin host rule akzeptiert werden sollen.
3. Konfigurieren Sie die Liste bestimmter Ursprungshostdomänen, und lassen Sie nur die CORS-Anforderung zu, die denselben Wert des Ursprungsanforderungsheaders wie eine der aufgelisteten Ursprungshostdomänen aufweist.
4. Konfigurieren Sie Wildcard-Host-Domänen beim Festlegen der Liste der Ursprungsdomänen, wie http://* oder https://*.mydomain.com.
5. Konfigurieren Sie eine Liste der Ursprungsdomänen, die als CORS-Anforderung unzulässig sein sollten.
6. Passen Sie die Werte des CORS-Antwort-Headers mit den konfigurierten Werten an.

Attribute des CORS-Elements

Hinzufügen einer Origin-Regel <>

Ursprungsregeln

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

Attribute der Ursprungsregel

Verwenden Sie nur die * Ursprungshostregel

Wenn nur * Ursprungshostregel vorhanden ist, weist das IIS-CORS-Modul im Vergleich zu einer bestimmten Herkunftshostnamenregel ein anderes Verhalten auf. Wenn lediglich eine * Ursprungs-Hostregel vorhanden ist, führt das IIS CORS-Modul die folgenden Aktionen aus:

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

Untergeordnete Elemente der Ursprungshostregel

Attribute des allowHeaders-Elements

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'}