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

par l’équipe IIS

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

Vue d’ensemble des fonctionnalités

Le module MICROSOFT IIS CORS 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 prendre en charge le protocole CORS. Avec ce module, les développeurs peuvent déplacer la logique CORS hors de leurs applications et s’appuyer sur le serveur web. La gestion des requêtes CORS par le module est déterminée par les règles définies dans la configuration. Ces règles CORS peuvent être facilement définies ou configurées, ce qui permet de déléguer facilement la gestion de tous les protocoles CORS au module.

Le module IIS CORS 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 comme composant CORS côté client, tandis que le serveur IIS fonctionne comme composant CORS côté serveur avec 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 requête à 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 requêtes cross-origin sont bloquées par le client. Lorsque le module CORS est utilisé, IIS informe les clients si une demande d’origine croisée peut être effectuée en fonction de la configuration IIS.

Demande CORS de vérification préliminaire

Une demande préliminaire 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. La requête préliminaire CORS utilise la méthode OPTIONS avec les en-têtes de requête ACCESS-CONTROL-REQUEST-METHOD et ORIGIN. Le module IIS CORS est conçu pour gérer les demandes préliminaires CORS avant que d’autres modules IIS gèrent la même requête. Les requêtes OPTIONS sont toujours anonymes. Par conséquent, le module CORS fournit aux serveurs IIS un moyen de répondre correctement à la demande préliminaire, même si l’authentification anonyme doit être désactivée sur le serveur.

CORS Configuration

IIS CORS est configuré via un fichier de site ou d’application web.config 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 par http://* sont exclus ultérieurement. Pour l’origine de l’hôte https://*.microsoft.com , la réponse CORS est personnalisée avec différentes configurations CORS comme 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 :

Activez, 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).
Configurez tous les domaines hôtes d'origine pour être acceptés avec la règle d'hôte source '*'.
Configurez la liste des domaines hôtes d’origine spécifiques et autorisez uniquement la requête CORS qui a la même valeur que l’un des domaines hôtes d’origine répertoriés.
Configurez des domaines hôtes d’origine générique lors de la configuration de la liste des domaines d’origine tels que http://* ou https://*.mydomain.com.
Configurez une liste de domaines d’origine qui doivent être interdits en tant que requête CORS.
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 le code d'état de réponse CORS doit être réglé sur 403 si l'origine demandée ne correspond pas à la liste des origines configurées ou si l'hôte d'origine est configuré comme non autorisé. La valeur par défaut est `false`.

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

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 du sous-domaine enfant. S’il existe plusieurs règles d’origine, elle est appliquée à 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 ajouter l’en-tête de réponse CORS intitulé Access-Control-Allow-Credentials. `true` 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 requête CORS préliminaire. L’en-tête de réponse Access-Control-Max-Age doit être défini uniquement pour les requêtes CORS préliminaires. 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 de l’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 n’existe que * règle d’hôte d’origine, le module IIS CORS effectue les opérations suivantes :

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é par le composant CORS côté client.
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 source

Élément	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 demandes 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 de réponse `Access-Control-Allow-Methods` sera définie uniquement pour les demandes préliminaires 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 demandes préliminaires.

Attributs de l’élément allowHeaders

Attribut Description

allowAllRequestedHeaders Attribut booléen facultatif. Si cela est vrai, le module IIS prend la valeur de l’en-tête de requête Access-Control-Request-Headers CORS 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. S’il s’agit de false, il 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.

Attribut	Description
`allowAllRequestedHeaders`	Attribut booléen facultatif. Si cela est vrai, le module IIS prend la valeur de l’en-tête de requête Access-Control-Request-Headers CORS 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. S’il s’agit de false, il 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'}

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-03-27