Informazioni di riferimento sulla configurazione del modulo CORS iis

Articolo
07/19/2023

dal team IIS

Questo articolo fornisce 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 la gestione di tutti i protocolli CORS al modulo.

Il modulo CORS iis è un componente CORS lato server

Il protocollo CORS gestisce la comunicazione client/server. In genere, i Web browser fungono da componente CORS 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 il 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 le origini verranno bloccate dal client. Quando si usa il modulo CORS, IIS informerà i client se è possibile eseguire una richiesta tra le origini in base alla configurazione iis.

Richiesta preliminare CORS

Viene usata una richiesta preliminare CORS per determinare se la risorsa richiesta è impostata per essere condivisa tra le origini dal server. La verifica preliminare CORS usa il metodo HTTP OPTIONS con le intestazioni di richiesta ACCESS-CONTROL-REQUEST-METHOD e ORIGIN . Il modulo CORS iis è progettato per gestire le richieste cors preliminari 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 a livello di server.

Configurazione CORS

IIS CORS viene configurato tramite un sito o un file diweb.config dell'applicazione 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 in seguito. Per l'origine https://*.microsoft.com host, la risposta CORS viene personalizzata con varie configurazioni CORS come 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 CORS iis è possibile:

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).
Configurare tutti i domini host di origine da accettare con * regola host di origine.
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.
Configurare i domini host dell'origine con caratteri jolly durante la configurazione dell'elenco di domini di origine, http://* ad esempio o https://*.mydomain.com.
Configurare un elenco di domini di origine che devono essere non consentiti come richiesta CORS.
Personalizzare i valori dell'intestazione della risposta CORS con i valori configurati.

Attributi dell'elemento cors

Attributo	Descrizione
`enabled`	Attributo booleano facoltativo. Specifica se CORS è abilitato. Il valore predefinito è `false`.
`failUnlistedOrigins`	Attributo booleano facoltativo. Specifica se il codice di stato della risposta CORS da impostare con 403 se l'origine richiesta non corrisponde all'elenco di origine configurato o se l'host di origine è configurato per non essere consentito. Il valore predefinito è `false`.

Aggiunta della 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

Attributo	Descrizione
`origin`	Attributo stringa obbligatorio. Specifica l'host di origine in cui imporre una regola di origine. È possibile usare un asterisco () per applicare questa regola a tutti i valori di intestazione della richiesta di origine. È anche possibile usare un asterisco () come carattere jolly per il nome del sottodominio figlio. Se sono presenti più regole di origine, viene applicata alla regola del nome host di origine più specifica indipendentemente dal valore dell'attributo consentito.
`allowed`	Attributo booleano facoltativo. Specifica se accettare la richiesta CORS per l'host di origine. Il valore predefinito è `true`.
`allowCredentials`	Attributo booleano facoltativo. Specifica se impostare l'intestazione della risposta CORS access-Control-Allow-Credentials `true` . Questo attributo deve essere usato solo per un nome host di origine specifico anziché * host di origine per la conformità del protocollo CORS. Il valore predefinito è `false`.
`maxAge`	Attributo Integer facoltativo. Durata in secondi. Specifica il valore dell'intestazione `Access-Control-Max-Age` della risposta per la richiesta CORS preliminare. L'intestazione di risposta Access-Control-Max-Age deve essere impostata solo per le richieste preliminari CORS. Se non si vuole impostare l'intestazione Access-Control-Max-Age nella risposta CORS, impostare -1 per questo attributo. Il valore predefinito è `-1`.

Uso solo * regola host di origine

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

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.
Variare: origin l'intestazione della risposta non viene aggiunta perché IIS CORS non genera valori di intestazione della risposta Access-Control-Allow-Origin diversi da * e non è necessario usare il valore dell'intestazione Di risposta Vary: origin .

Elementi figlio della regola host di origine

elemento	Descrizione
allowHeaders	configura l'insieme allowHeaders utilizzato per il valore dell'intestazione `Access-Control-Allow-Headers` di risposta CORS per l'host di origine specificato nella regola host di origine. L'intestazione `Access-Control-Allow-Headers` della risposta verrà impostata solo per le richieste CORS effettive anziché per le richieste preliminari.
allowMethods	configura l'insieme allowMethods utilizzato per il valore dell'intestazione di risposta CORS per l'host `Access-Control-Allow-Methods` di origine specificato nella regola host di origine. L'intestazione `Access-Control-Allow-Methods` della risposta verrà impostata solo per le richieste preliminari CORS.
exposeHeaders	configura l'insieme exposeHeaders utilizzato per il valore dell'intestazione `Access-Control-Expose-Headers` di risposta CORS per l'host di origine specificato nella regola host di origine. L'intestazione `Access-Control-Expose-Headers` della risposta verrà impostata solo per le richieste CORS effettive anziché per le richieste preliminari.

Attributi dell'elemento allowHeaders

Attributo Descrizione

allowAllRequestedHeaders Attributo booleano facoltativo. Se questo è vero, il modulo IIS accetta il valore dell'intestazione della richiesta CORS Access-Control-Request-Headers specificata e imposta l'intestazione di risposta Access-Control-Allow-Headers con lo stesso valore, ovvero tutte le intestazioni indicate sono consentite. Se è false, imposta l'intestazione della risposta Access-Control-Allow-Headers con i valori di intestazione dell'insieme allowHeaders, il che significa che sono consentite solo le intestazioni elencate. Il valore predefinito è false.

Attributo	Descrizione
`allowAllRequestedHeaders`	Attributo booleano facoltativo. Se questo è vero, il modulo IIS accetta il valore dell'intestazione della richiesta CORS Access-Control-Request-Headers specificata e imposta l'intestazione di risposta Access-Control-Allow-Headers con lo stesso valore, ovvero tutte le intestazioni indicate sono consentite. Se è false, imposta l'intestazione della risposta Access-Control-Allow-Headers con i valori di intestazione dell'insieme allowHeaders, il che significa che sono consentite solo le intestazioni elencate. Il valore predefinito è `false`.

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

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

Condividi tramite