Informazioni di riferimento sulla configurazione del modulo CORS di IIS

dal team IIS

Questo articolo offre una panoramica del modulo CORS IIS e illustra la configurazione del modulo.

Panoramica delle funzionalità

Il modulo CORS di Microsoft IIS è un'estensione che consente ai siti Web di supportare il protocollo CORS(Cross-Origin Resource Sharing).

Il modulo CORS IIS consente agli amministratori del server Web e agli autori di siti Web di supportare il protocollo CORS delle applicazioni. Con questo modulo, gli sviluppatori possono spostare la logica CORS dalle applicazioni e basarsi sul server Web. La gestione delle richieste CORS del modulo è determinata dalle regole definite nella configurazione. Queste regole CORS possono essere definite o configurate in modo semplice per delegare tutta la gestione del protocollo CORS al modulo.

Il modulo CORS di IIS è un componente CORS lato server

Il protocollo CORS regola la comunicazione client/server. In genere, i Web browser fungono da componente CORS sul lato client, mentre il server IIS funziona come componente CORS lato server con l'aiuto del modulo CORS IIS.

Una richiesta CORS si verifica quando un client compatibile con protocollo, ad esempio un Web browser, effettua una richiesta a un dominio (origine) diverso dal dominio corrente. Questo scenario è noto come richiesta tra origini. Quando CORS non viene usato, le richieste tra origini verranno bloccate dal client. Quando viene utilizzato il modulo CORS, IIS informerà i client se è possibile eseguire una richiesta cross-origin in base alla configurazione di IIS.

Richiesta preliminare CORS

Una richiesta preliminare CORS viene usata per determinare se la risorsa richiesta è impostata per essere condivisa tra le origini dal server. La verifica preliminare CORS utilizza il metodo HTTP OPTIONS con le intestazioni HTTP di richiesta ACCESS-CONTROL-REQUEST-METHOD e ORIGIN. Il modulo CORS IIS è progettato per gestire le richieste preliminari CORS prima che altri moduli IIS gestisca la stessa richiesta. Le richieste OPTIONS sono sempre anonime, pertanto il modulo CORS fornisce ai server IIS un modo per rispondere correttamente alla richiesta preliminare anche se è necessario disabilitare l'autenticazione anonima per server.

Configurazione CORS

IIS CORS viene configurato tramite un sito o un'applicazione web.config file e ha una propria cors sezione di configurazione all'interno di system.webServer.

Di seguito sono riportati gli esempi di configurazione per abilitare CORS per un sito denominato contentSite. L'origine * consente tutte le origini host; tuttavia, quelli che iniziano con http://* vengono esclusi successivamente. Per l'origine host https://*.microsoft.com, la risposta CORS è personalizzata con diverse configurazioni CORS a titolo di esempio.

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

Con il modulo IIS CORS è possibile:

1. Abilitare, disabilitare CORS per un intero server IIS o per un sito IIS specifico, un'applicazione, una directory virtuale, una directory fisica o un file (system.webServer/cors).
2. Configurare tutti i domini host di origine da accettare con la regola host di origine *.
3. Configurare l'elenco di domini host di origine specifici e consentire solo la richiesta CORS con lo stesso valore dell'intestazione della richiesta di origine di uno dei domini host di origine elencati.
4. Configurare i domini host dell'origine jolly quando si configura l'elenco di domini di origine, http://* ad esempio o https://*.mydomain.com.
5. Configurare un elenco di domini di origine che devono essere non consentiti come richiesta CORS.
6. Personalizza i valori dell'intestazione della risposta CORS con i valori configurati.

Attributi dell'elemento cors

Aggiunta regola di origine <>

Regole di origine

L'elemento <add><cors> della raccolta specifica una singola origine da aggiungere all'elenco di regole di origine.

Attributi della regola di origine

Utilizzando solo la regola dell'host di origine

Se è presente solo * regola host di origine, il modulo IIS CORS presenta alcuni comportamenti diversi rispetto a quando è presente una regola specifica del nome host di origine. Se è presente solo * regola host di origine, il modulo IIS CORS esegue le operazioni seguenti:

1. Il valore dell'intestazione di risposta Access-Control-Allow-Origin è impostato su * indipendentemente dal valore dell'intestazione origin della richiesta inviata dal componente CORS sul lato client.
2. Vary: origin l'intestazione della risposta non viene aggiunta perché IIS CORS non genera valori per l'intestazione di risposta Access-Control-Allow-Origin diversi da * e non è necessario usare il valore dell'intestazione di risposta Vary: origin.

Elementi figli della regola dell'host origine

Attributi dell'elemento allowHeaders

Codice di esempio

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();

Linea di comando (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'}