Bagikan melalui

Referensi Konfigurasi modul IIS CORS

oleh Tim IIS

Artikel ini memberikan gambaran umum tentang modul IIS CORS dan menjelaskan konfigurasi modul.

Gambaran Umum Fungsionalitas

Modul CORS Microsoft IIS adalah ekstensi yang memungkinkan situs web mendukung protokol CORS (Berbagi Sumber Daya Lintas Asal).

Modul CORS IIS menyediakan cara bagi administrator server web dan penulis situs web untuk membuat aplikasi mereka mendukung protokol CORS. Dengan modul ini, pengembang dapat memindahkan logika CORS keluar dari aplikasi mereka dan mengandalkan server web. Penanganan permintaan CORS modul ditentukan oleh aturan yang ditentukan dalam konfigurasi. Aturan CORS ini dapat dengan mudah didefinisikan atau dikonfigurasi sehingga mudah untuk mendelegasikan semua penanganan protokol CORS ke modul.

Modul CORS IIS adalah komponen CORS sisi server

Protokol CORS mengatur komunikasi klien/server. Biasanya, browser web bertindak sebagai komponen CORS sisi klien, sementara server IIS berfungsi sebagai komponen CORS sisi server dengan bantuan modul IIS CORS.

Permintaan CORS terjadi ketika klien sadar protokol, seperti browser web, membuat permintaan ke domain (asal) yang berbeda dari domain saat ini. Skenario ini dikenal sebagai permintaan lintas asal. Ketika CORS tidak digunakan, permintaan lintas asal akan diblokir oleh klien. Ketika modul CORS digunakan, IIS akan memberi tahu klien apakah permintaan lintas asal dapat dilakukan berdasarkan konfigurasi IIS.

Permintaan preflight CORS

Permintaan preflight CORS digunakan untuk menentukan apakah sumber daya yang diminta diatur untuk dibagikan di seluruh asal oleh server. Preflight CORS menggunakan metode HTTP OPTIONS dengan ACCESS-CONTROL-REQUEST-METHOD dan header permintaan ORIGIN . Modul CORS IIS dirancang untuk menangani permintaan preflight CORS sebelum modul IIS lainnya menangani permintaan yang sama. Permintaan OPTIONS selalu anonim, sehingga modul CORS menyediakan server IIS cara untuk merespons permintaan preflight dengan benar bahkan jika autentikasi anonim perlu dinonaktifkan server-bijaksana.

Konfigurasi CORS

IIS CORS dikonfigurasi melalui situs atau aplikasi web.config file dan memiliki bagian konfigurasinya sendiri cors dalam system.webServer.

Di bawah ini adalah contoh konfigurasi untuk mengaktifkan CORS untuk situs bernama contentSite. Asal * memungkinkan semua asal host; namun, yang dimulai dengan http://* kemudian dikecualikan. https://*.microsoft.com Untuk asal host, respons CORS disesuaikan dengan berbagai konfigurasi CORS sebagai contoh.

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

Dengan modul IIS CORS, Anda dapat:

  1. Aktifkan, nonaktifkan CORS untuk seluruh server IIS atau untuk situs IIS tertentu, aplikasi, direktori virtual, direktori fisik, atau file (system.webServer/cors).
  2. Konfigurasikan semua domain host asal untuk diterima dengan * aturan host asal.
  3. Konfigurasikan daftar domain host asal tertentu dan hanya izinkan permintaan CORS yang memiliki nilai header permintaan asal yang sama dengan salah satu domain host asal yang tercantum.
  4. Konfigurasikan domain host asal wild card saat mengonfigurasi daftar domain asal seperti http://* atau https://*.mydomain.com.
  5. Mengonfigurasi daftar domain asal yang harus dilarang sebagai permintaan CORS.
  6. Sesuaikan nilai header respons CORS dengan nilai yang dikonfigurasi.

Atribut elemen cors

Attribut Deskripsi
enabled Atribut Boolean opsional.
Menentukan apakah CORS diaktifkan.
Nilai defaultnya adalah false.
failUnlistedOrigins Atribut Boolean opsional.
Menentukan apakah kode status respons CORS akan diatur dengan 403 jika asal yang diminta tidak cocok dengan daftar asal yang dikonfigurasi atau jika host asal dikonfigurasi untuk tidak diizinkan.
Nilai defaultnya adalah false.

Menambahkan penambahan aturan <Asal>

Aturan asal

Elemen <add><cors> koleksi menentukan asal individu yang akan ditambahkan ke daftar aturan asal.

Atribut aturan asal

Attribut Deskripsi
origin Atribut string yang diperlukan.
Menentukan host asal untuk memberlakukan aturan asal. Anda dapat menggunakan tanda bintang (*) untuk menerapkan aturan ini ke semua nilai header permintaan asal. Anda juga dapat menggunakan tanda bintang (*) sebagai kartubebas untuk nama subdomain anak. Jika ada beberapa aturan asal, aturan tersebut diterapkan ke aturan nama host asal yang paling spesifik terlepas dari nilai atribut yang diizinkan.
allowed Atribut Boolean opsional.
Menentukan apakah akan menerima permintaan CORS untuk host asal.
Nilai defaultnya adalah true.
allowCredentials Atribut Boolean opsional.
Menentukan apakah akan mengatur header respons Access-Control-Allow-Credentials: true CORS. Atribut ini harus digunakan hanya untuk nama host asal tertentu daripada * host asal untuk kepatuhan protokol CORS.
Nilai defaultnya adalah false.
maxAge Atribut bilangan bulat opsional. Durasi dalam detik.
Menentukan nilai Access-Control-Max-Age header respons untuk permintaan CORS preflight. Header respons Access-Control-Max-Age seharusnya diatur hanya untuk permintaan preflight CORS. Jika Anda tidak ingin mengatur header Access-Control-Max-Age di respons CORS, atur -1 untuk atribut ini.
Nilai defaultnya adalah -1.

Hanya menggunakan * aturan host asal

Jika hanya ada * aturan host asal, modul IIS CORS memiliki beberapa perilaku yang berbeda dibandingkan dengan ketika ada aturan nama host asal tertentu. Jika hanya ada * aturan host asal, modul IIS CORS melakukan hal berikut:

  1. Nilai header respons Access-Control-Allow-Origin diatur ke * terlepas dari nilai header permintaan yang origin dikirim oleh komponen CORS sisi klien.
  2. Bervariasi: origin header respons tidak ditambahkan karena IIS CORS tidak menghasilkan nilai header respons Access-Control-Allow-Origin selain * dan tidak perlu menggunakan nilai header respons Vary: origin .

Elemen Anak dari aturan host asal

Elemen Deskripsi
allowHeaders mengonfigurasi koleksi allowHeaders yang digunakan untuk nilai Access-Control-Allow-Headers header respons CORS untuk host asal yang ditentukan dalam aturan host asal.
Header Access-Control-Allow-Headers respons hanya akan diatur untuk permintaan CORS aktual daripada permintaan preflight.
allowMethods mengonfigurasi koleksi allowMethods yang digunakan untuk nilai Access-Control-Allow-Methods header respons CORS untuk host asal yang ditentukan dalam aturan host asal.
Header Access-Control-Allow-Methods respons hanya akan diatur untuk permintaan preflight CORS.
exposeHeaders mengonfigurasi koleksi exposeHeaders yang digunakan untuk nilai Access-Control-Expose-Headers header respons CORS untuk host asal yang ditentukan dalam aturan host asal.
Header Access-Control-Expose-Headers respons hanya akan diatur untuk permintaan CORS aktual daripada permintaan preflight.

Atribut elemen allowHeaders

Attribut Deskripsi
allowAllRequestedHeaders Atribut Boolean opsional. Jika ini benar, modul IIS akan mengambil nilai header permintaan CORS Access-Control-Request-Headers yang diberikan dan mengatur header respons Access-Control-Allow-Headers dengan nilai yang sama, yang berarti semua header yang diberikan diizinkan. Jika ini salah, ini mengatur header respons Access-Control-Allow-Headers dengan nilai header koleksi allowHeaders, yang berarti bahwa hanya header yang tercantum yang diizinkan. Nilai defaultnya adalah false.

Kode Sampel

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

Baris Perintah (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'}