Partager via

Informations de référence sur la configuration du module IIS CORS

  • Article

par l’équipe IIS

Cet article fournit une vue d’ensemble du module IIS CORS et explique la configuration du module.

Vue d’ensemble des fonctionnalités

Le module CORS Microsoft IIS est une extension qui permet aux sites web de prendre en charge le protocole CORS (Cross-Origin Resource Sharing).

Le module IIS CORS permet aux administrateurs de serveur web et aux auteurs de sites web de faire en sorte que leurs applications prennent en charge le protocole CORS. Avec ce module, les développeurs peuvent déplacer la logique CORS de leurs applications et s’appuyer sur le serveur web. La gestion des requêtes CORS par le module est déterminée par des règles définies dans la configuration. Ces règles CORS peuvent être facilement définies ou configurées, ce qui simplifie la délégation de toute la gestion du protocole CORS au module.

Le module CORS IIS est un composant CORS côté serveur

Le protocole CORS régit la communication client/serveur. En règle générale, les navigateurs web agissent en tant que composant CORS côté client, tandis que le serveur IIS fonctionne comme le composant CORS côté serveur à l’aide du module CORS IIS.

Une requête CORS se produit lorsqu’un client prenant en charge le protocole, tel qu’un navigateur web, effectue une demande à un domaine (origine) qui diffère du domaine actuel. Ce scénario est appelé demande d’origine croisée. Lorsque CORS n’est pas utilisé, les demandes d’origine croisée sont bloquées par le client. Lorsque le module CORS est utilisé, IIS indique aux clients si une demande d’origine croisée peut être effectuée en fonction de la configuration IIS.

Demande de contrôle préalable CORS

Une demande de contrôle préalable CORS est utilisée pour déterminer si la ressource demandée est définie pour être partagée entre les origines par le serveur. Le contrôle préalable CORS utilise la méthode HTTP OPTIONS avec les en-têtes ACCESS-CONTROL-REQUEST-METHOD et ORIGIN request. Le module CORS IIS est conçu pour gérer les demandes de contrôle préalable CORS avant que d’autres modules IIS ne gèrent la même requête. Les requêtes OPTIONS étant toujours anonymes, le module CORS fournit aux serveurs IIS un moyen de répondre correctement à la demande de contrôle préliminaire, même si l’authentification anonyme doit être désactivée au niveau du serveur.

CORS Configuration

IIS CORS est configuré via un fichier deweb.config de site ou d’application et possède sa propre cors section de configuration dans system.webServer.

Voici les exemples de configuration permettant d’activer CORS pour un site nommé contentSite. L’origine * autorise toutes les origines de l’hôte ; toutefois, ceux qui commencent http://* par sont ensuite exclus. Pour l’origine de l’hôte https://*.microsoft.com , la réponse CORS est personnalisée avec différentes configurations CORS à titre d’exemple.

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

Avec le module IIS CORS, vous pouvez :

  1. Activez et désactivez CORS pour un serveur IIS entier ou pour un site IIS spécifique, une application, un répertoire virtuel, un répertoire physique ou un fichier (system.webServer/cors).
  2. Configurez tous les domaines hôtes d’origine à accepter avec la règle d’hôte d’origine *.
  3. Configurez la liste des domaines hôtes d’origine spécifiques et autorisez uniquement la requête CORS qui a la même valeur d’en-tête de la demande d’origine que l’un des domaines hôtes d’origine répertoriés.
  4. Configurez des domaines hôtes d’origine carte génériques lors de la configuration de la liste des domaines d’origine tels que http://* ou https://*.mydomain.com.
  5. Configurez une liste de domaines d’origine qui doivent être interdits en tant que demande CORS.
  6. Personnalisez les valeurs d’en-tête de réponse CORS avec les valeurs configurées.

Attributs de l’élément cors

Attribut Description
enabled Attribut booléen facultatif.
Spécifie si CORS est activé.
La valeur par défaut est false.
failUnlistedOrigins Attribut booléen facultatif.
Spécifie si la réponse CORS status code à définir avec 403 si l’origine demandée ne correspond pas à la liste d’origine configurée ou si l’hôte d’origine est configuré pour être interdit.
La valeur par défaut est false.

Ajout d’une règle d’origine <ajouter>

Règles d’origine

L’élément <add> de la <cors> collection spécifie une origine individuelle à ajouter à la liste des règles d’origine.

Attributs de la règle d’origine

Attribut Description
origin Attribut de chaîne requis.
Spécifie l’hôte d’origine sur lequel imposer une règle d’origine. Vous pouvez utiliser un astérisque (*) pour appliquer cette règle à toutes les valeurs d’en-tête de demande d’origine. Vous pouvez également utiliser un astérisque (*) comme caractère générique pour le nom de sous-domaine enfant. S’il existe plusieurs règles d’origine, elles sont appliquées à la règle de nom d’hôte d’origine la plus spécifique, quelle que soit la valeur d’attribut autorisée.
allowed Attribut booléen facultatif.
Spécifie s’il faut accepter la demande CORS pour l’hôte d’origine.
La valeur par défaut est true.
allowCredentials Attribut booléen facultatif.
Spécifie s’il faut définir l’en-tête de réponse Access-Control-Allow-Credentials : true CORS. Cet attribut doit être utilisé uniquement pour un nom d’hôte d’origine spécifique plutôt que pour * hôte d’origine pour la conformité du protocole CORS.
La valeur par défaut est false.
maxAge Attribut entier facultatif. Durée en secondes.
Spécifie la valeur de l’en-tête Access-Control-Max-Age de réponse pour la demande CORS en amont. L’en-tête de réponse Access-Control-Max-Age est censé être défini uniquement pour les demandes de contrôle préalable CORS. Si vous ne souhaitez pas définir l’en-tête Access-Control-Max-Age dans la réponse CORS, définissez -1 pour cet attribut.
La valeur par défaut est -1.

Utilisation uniquement de la règle d’hôte d’origine *

S’il n’existe que * règle d’hôte d’origine, le module IIS CORS a des comportements différents par rapport à lorsqu’il existe une règle de nom d’hôte d’origine spécifique. S’il existe uniquement une règle d’hôte d’origine *, le module IIS CORS effectue les opérations suivantes :

  1. La valeur de l’en-tête de réponse Access-Control-Allow-Origin est définie sur * quelle que soit la valeur de l’en-tête origin de requête envoyée par le composant CORS côté client.
  2. Vary : origin l’en-tête de réponse n’est pas ajouté, car IIS CORS ne génère pas de valeurs d’en-tête de réponse Access-Control-Allow-Origin autres que * et il n’est pas nécessaire d’utiliser la valeur d’en-tête de réponse Vary: origin .

Éléments enfants de la règle d’hôte d’origine

Element Description
allowHeaders configure la collection allowHeaders utilisée pour la valeur de l’en-tête Access-Control-Allow-Headers de réponse CORS pour l’hôte d’origine spécifié dans la règle d’hôte d’origine.
L’en-tête Access-Control-Allow-Headers de réponse est défini uniquement pour les requêtes CORS réelles plutôt que pour les requêtes préliminaires.
allowMethods configure la collection allowMethods utilisée pour la valeur de l’en-tête Access-Control-Allow-Methods de réponse CORS pour l’hôte d’origine spécifié dans la règle d’hôte d’origine.
L’en-tête Access-Control-Allow-Methods de réponse est défini uniquement pour les demandes de contrôle préalable CORS.
exposeHeaders configure la collection exposeHeaders utilisée pour la valeur de l’en-tête Access-Control-Expose-Headers de réponse CORS pour l’hôte d’origine spécifié dans la règle d’hôte d’origine.
L’en-tête Access-Control-Expose-Headers de réponse est défini uniquement pour les requêtes CORS réelles plutôt que pour les requêtes préliminaires.

Attributs de l’élément allowHeaders

Attribut Description
allowAllRequestedHeaders Attribut booléen facultatif. Si cette valeur est vraie, le module IIS prend la valeur de l’en-tête de requête CORS Access-Control-Request-Headers donné et définit l’en-tête de réponse Access-Control-Allow-Headers avec la même valeur, ce qui signifie que tous les en-têtes donnés sont autorisés. Si cette valeur est false, elle définit l’en-tête de réponse Access-Control-Allow-Headers avec les valeurs d’en-tête de la collection allowHeaders, ce qui signifie que seuls les en-têtes répertoriés sont autorisés. La valeur par défaut est false.

Exemple de code

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

Ligne de commande (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'}