Referência de configuração do módulo CORS do IIS

Artigo
07/19/2023

pela equipe do IIS

Este artigo fornece uma visão geral do módulo CORS do IIS e explica a configuração do módulo.

Visão geral da funcionalidade

O Módulo CORS do Microsoft IIS é uma extensão que permite aos sites dar suporte ao protocolo CORS (Compartilhamento de Recursos entre Origens).

O módulo CORS do IIS fornece uma maneira de administradores de servidor Web e autores de sites fazerem com que seus aplicativos dêem suporte ao protocolo CORS. Com este módulo, os desenvolvedores podem mover a lógica cors para fora de seus aplicativos e contar com o servidor Web. O tratamento do módulo de solicitações CORS é determinado por regras definidas na configuração. Essas regras cors podem ser facilmente definidas ou configuradas, tornando simples delegar toda a manipulação de protocolo CORS para o módulo.

O módulo CORS do IIS é um componente CORS do lado do servidor

O protocolo CORS rege a comunicação cliente/servidor. Normalmente, os navegadores da Web atuam como o componente CORS do lado do cliente, enquanto o servidor IIS funciona como o componente CORS do lado do servidor com a ajuda do módulo CORS do IIS.

Uma solicitação CORS ocorre quando um cliente com reconhecimento de protocolo, como um navegador da Web, faz uma solicitação para um domínio (origem) que difere do domínio atual. Esse cenário é conhecido como uma solicitação entre origens. Quando o CORS não for usado, as solicitações entre origens serão bloqueadas pelo cliente. Quando o módulo CORS for usado, o IIS informará aos clientes se uma solicitação entre origens pode ser executada com base na configuração do IIS.

Solicitação de pré-voo do CORS

Uma solicitação de pré-vôo CORS é usada para determinar se o recurso que está sendo solicitado está definido para ser compartilhado entre origens pelo servidor. O pré-vôo CORS usa o método HTTP OPTIONS com os cabeçalhos de solicitação ACCESS-CONTROL-REQUEST-METHOD e ORIGIN . O módulo CORS do IIS foi projetado para lidar com as solicitações de pré-voo do CORS antes que outros módulos do IIS lidem com a mesma solicitação. As solicitações OPTIONS são sempre anônimas, portanto, o módulo CORS fornece aos servidores IIS uma maneira de responder corretamente à solicitação de pré-voo, mesmo que a autenticação anônima precise ser desabilitada em termos de servidor.

Configuração do CORS

O CORS do IIS é configurado por meio de um site ou aplicativo web.config arquivo e tem sua própria cors seção de configuração dentro de system.webServer.

Abaixo estão os exemplos de configuração para habilitar o CORS para um site chamado contentSite. A origem * permite todas as origens do host; no entanto, aqueles que começam com http://* são excluídos posteriormente. Para a origem do https://*.microsoft.com host, a resposta CORS é personalizada com várias configurações de CORS como exemplo.

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

Com o módulo CORS do IIS, você pode:

Habilite, desabilite o CORS para um servidor IIS inteiro ou para um site específico do IIS, um aplicativo, um diretório virtual, um diretório físico ou um arquivo (system.webServer/cors).
Configure todos os domínios de host de origem a serem aceitos com * regra de host de origem.
Configure a lista de domínios de host de origem específicos e permita apenas a solicitação CORS que tem o mesmo valor do cabeçalho de solicitação de origem que um dos domínios de host de origem listados.
Configure domínios de host de origem cartão selvagem ao configurar a lista de domínio de origem, como http://* ou https://*.mydomain.com.
Configure uma lista de domínios de origem que devem ser desautorizados como solicitação CORS.
Personalize os valores de cabeçalho de resposta CORS com os valores configurados.

Atributos do elemento cors

Atributo	Descrição
`enabled`	Atributo booliano opcional. Especifica se o CORS está habilitado. O valor padrão é `false`.
`failUnlistedOrigins`	Atributo booliano opcional. Especifica se a resposta CORS status código a ser definido com 403 se a origem solicitada não corresponder à lista de origem configurada ou se o host de origem estiver configurado para não ser permitido. O valor padrão é `false`.

Adicionar a regra <De origem adicionar>

Regras de origem

O <add> elemento da <cors> coleção especifica uma origem individual a ser adicionada à lista de regras de origem.

Atributos da regra de origem

Atributo	Descrição
`origin`	Atributo de cadeia de caracteres obrigatório. Especifica o host de origem no qual impor uma regra de origem. Você pode usar um asterisco () para aplicar essa regra a todos os valores de cabeçalho de solicitação de origem. Você também pode usar um asterisco () como curinga para o nome do subdomínio filho. Se houver várias regras de origem, ela será aplicada à regra de nome de host de origem mais específica, independentemente do valor de atributo permitido.
`allowed`	Atributo booliano opcional. Especifica se deseja aceitar a solicitação CORS para o host de origem. O valor padrão é `true`.
`allowCredentials`	Atributo booliano opcional. Especifica se o cabeçalho de resposta ACCESS-Control-Allow-Credentials: `true` CORS deve ser definido. Esse atributo deve ser usado apenas para um nome de host de origem específico em vez de * host de origem para conformidade do protocolo CORS. O valor padrão é `false`.
`maxAge`	Atributo inteiro opcional. Duração em segundos. Especifica o valor do cabeçalho de `Access-Control-Max-Age` resposta para a solicitação CORS de pré-vôo. O cabeçalho de resposta Access-Control-Max-Age deve ser definido apenas para as solicitações de pré-vôo cors. Se você não quiser definir o cabeçalho Access-Control-Max-Age na resposta CORS, defina -1 para esse atributo. O valor padrão é `-1`.

Usando apenas * regra de host de origem

Se houver apenas * regra de host de origem, o módulo CORS do IIS terá alguns comportamentos diferentes em comparação com quando há uma regra de nome de host de origem específica. Se houver apenas * regra de host de origem, o módulo do IIS CORS fará o seguinte:

O valor do cabeçalho de resposta Access-Control-Allow-Origin é definido como * independentemente do valor do cabeçalho de origin solicitação enviado pelo componente CORS do lado do cliente.
Variar: origin o cabeçalho de resposta não é adicionado porque o IIS CORS não gera valores de cabeçalho de resposta Access-Control-Allow-Origin diferentes de * e não há necessidade de usar o valor do cabeçalho Vary: origin response.

Elementos filho da regra de host de origem

Element	Descrição
allowHeaders	configura a coleção allowHeaders usada para o valor do cabeçalho de `Access-Control-Allow-Headers` resposta CORS para o host de origem especificado na regra de host de origem. O `Access-Control-Allow-Headers` cabeçalho de resposta será definido apenas para as solicitações cors reais em vez das solicitações de pré-vôo.
allowMethods	configura a coleção allowMethods usada para o valor do cabeçalho de `Access-Control-Allow-Methods` resposta CORS para o host de origem especificado na regra de host de origem. O `Access-Control-Allow-Methods` cabeçalho de resposta será definido apenas para as solicitações de pré-voo do CORS.
exposeHeaders	configura a coleção exposeHeaders usada para o valor do cabeçalho de `Access-Control-Expose-Headers` resposta CORS para o host de origem especificado na regra de host de origem. O `Access-Control-Expose-Headers` cabeçalho de resposta será definido apenas para as solicitações cors reais em vez das solicitações de pré-vôo.

Atributos do elemento allowHeaders

Atributo Descrição

allowAllRequestedHeaders Atributo booliano opcional. Se isso for verdadeiro, o módulo IIS pegará o valor do cabeçalho de solicitação CORS access-control-request-headers e definirá o cabeçalho de resposta Access-Control-Allow-Headers com o mesmo valor, o que significa que todos os cabeçalhos fornecidos são permitidos. Se isso for falso, ele definirá o cabeçalho de resposta Access-Control-Allow-Headers com os valores de cabeçalho da coleção allowHeaders, o que significa que somente os cabeçalhos listados são permitidos. O valor padrão é false.

Atributo	Descrição
`allowAllRequestedHeaders`	Atributo booliano opcional. Se isso for verdadeiro, o módulo IIS pegará o valor do cabeçalho de solicitação CORS access-control-request-headers e definirá o cabeçalho de resposta Access-Control-Allow-Headers com o mesmo valor, o que significa que todos os cabeçalhos fornecidos são permitidos. Se isso for falso, ele definirá o cabeçalho de resposta Access-Control-Allow-Headers com os valores de cabeçalho da coleção allowHeaders, o que significa que somente os cabeçalhos listados são permitidos. O valor padrão é `false`.

Exemplo de código

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

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

Partilhar via