CORS

  • 發行項

適用於：所有 API 管理 層

cors 原則會將跨原始來源資源分享 (CORS) 支援加入至操作或 API，以允許來自瀏覽器型用戶端的跨網域呼叫。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。 為了協助您設定此原則，入口網站會提供引導式表單型編輯器。 深入了解如何設定或編輯 APIM 原則。

原則陳述式

<cors allow-credentials="false | true" terminate-unmatched-request="true | false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>HTTP verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

屬性

名字 描述 是必要欄位 預設
allow-credentials 事前回應中的 Access-Control-Allow-Credentials 標頭會設定為這個屬性的值，並影響用戶端是否能夠在跨網域要求中提交認證。 允許使用原則運算式。 No false
terminate-unmatched-request 控制不符合原則設定的跨原始來源要求處理。 允許使用原則運算式。

當 OPTIONS 要求處理為預檢要求，且 Origin 標頭不符合原則設定時：
- 如果屬性設定為 true，請立即以空白 200 OK 回應終止要求
- 如果屬性設定為 false，請檢查輸入中是否有屬於輸入元素直接子系的其他範圍內 cors 原則，並加以套用。 如果找不到 cors 原則，請使用空的 200 OK 回應終止要求。

當 GET 或 HEAD 要求包含 Origin 標頭時 (因此會以簡單的跨原點來源要求處理)，且不符合原則設定：
- 如果屬性設定為 true，請立即以空白 200 OK 回應終止要求。
- 如果屬性設定為 false，則允許要求正常繼續，且不會將 CORS 標頭新增至回應。		 No true

元素

名稱 描述 是必要欄位 預設
allowed-origins 包含可說明跨網域要求之允許來源的 origin 元素。 allowed-origins 可包含指定了 * 以允許任何來源的單一 origin 元素，或一或多個包含 URI 的 origin 元素。 Yes N/A
allowed-methods 如果允許 GET 或 POST 以外的方法，則需要此元素。 包含指定了所支援 HTTP 動詞命令的 method 元素。 值 * 表示所有方法。 No 如果此區段不存在，則可支援 GET 和 POST。
allowed-headers 此元素包含指定了可包含在要求中之標頭名稱的 header 元素。 Yes N/A
expose-headers 此元素包含指定了可供用戶端存取之標頭名稱的 header 元素。 No N/A

警告

在原則 * 設定中小心使用萬用字元。 此設定可能過於寬鬆，而且可能會讓 API 更容易遭受特定的 API 安全性威脅。

allowed-origins 元素

名稱 描述 是必要欄位 預設
origin 值可以是 * 以允許所有來源，或是 URI 以指定單一來源。 URI 必須包含配置、主機和連接埠。 不要包含引號。 Yes 如果 URI 中省略了連接埠，則會將連接埠 80 用於 HTTP，將連接埠 443 用於 HTTPS。

allowed-methods 屬性

名稱 描述 是必要欄位 預設
preflight-result-max-age 預檢回應中的 Access-Control-Max-Age 標頭會設為這個屬性的值，並會影響使用者代理程式是否能夠快取預檢回應。 允許使用原則運算式。 No 0

allowed-methods 元素

名稱 描述 是必要欄位 預設
method 指定 HTTP 動詞命令。 允許使用原則運算式。 如果 allowed-methods 區段存在，則需要至少一個 method 元素。 N/A

allowed-headers 元素

名稱 描述 是必要欄位 預設
標頭 指定標頭名稱。 如果該區段存在，則在 allowed-headers 中至少需要一個 header 元素。 N/A

expose-headers 元素

名稱 描述 是必要欄位 預設
標頭 指定標頭名稱。 如果該區段存在，則在 expose-headers 中至少需要一個 header 元素。 N/A

使用方式

使用注意事項

  • 例如，您可以在多個範圍 (例如，在產品範圍和全域範圍) 設定 cors 原則。 請確定元素 base 是在作業、API 和產品範圍上設定，以繼承父範圍所需的原則。
  • 在預檢期間，只會對 OPTIONS 要求評估 cors 原則。 剩餘設定的原則會根據核准的要求來進行評估。
  • 此原則只能在原則區段中使用一次。

關於 CORS

CORS 是 HTTP 標頭型標準，可讓瀏覽器和伺服器互動，以決定是否允許特定的跨原始來源要求 (從網頁上的 JavaScript 對其他網域發出的 XMLHttpRequest 呼叫)。 這比只允許相同原始來源的要求更有彈性，也比允許所有跨原始來源的要求更安全。

CORS 指定兩種類型的跨原始來源要求：

  • 預檢要求 - 瀏覽器會先使用 OPTIONS 方法將 HTTP 要求傳送至伺服器，以判斷是否允許傳送實際要求。 如果伺服器回應包含允許存取的 Access-Control-Allow-Origin 標頭，瀏覽器會遵循實際的要求。

  • 簡單要求 - 這些要求包含一個或多個額外的 Origin 標頭，但不會觸發 CORS 預檢。 只允許使用 GET 和 HEAD 方法和一組有限要求標頭的要求。

cors 原則案例

針對下列案例，在 API 管理中設定 cors 原則：

  • 在開發人員入口網站中啟用互動式測試主控台。 如需詳細資訊，請參閱開發人員入口網站文件。

    注意

    您啟用互動式主控台的 CORS 時，API 管理預設會在全域範圍設定 cors 原則。

  • 啟用 PI 管理回覆預檢要求，或在後端未提供其本身的 CORS 支援時傳遞簡單的 CORS 要求。

    注意

    如果要求與 API 中定義之 OPTIONS 方法的作業相符，將不會執行與 cors 原則相關聯的預先執行要求處理邏輯。 因此，這類作業可用來實作自訂預檢處理邏輯，例如，只在特定情況下套用 cors 原則。

常見的設定問題

  • 標頭中的訂閱金鑰 - 如果您在「產品」範圍內設定 cors 原則，且您的 API 使用訂閱金鑰來驗證，則當訂閱金鑰在標頭中傳遞時，原則將無法運作。 因應措施是修改要求，以包含訂閱金鑰作為查詢參數。
  • 具有標頭版本設定的 API - 如果您在 API 範圍內設定 cors 原則，且您的 API 使用標頭版本設定配置，則原則會因為版本是在標頭中傳遞而無法運作。 您可能需要設定替代版本設定方法，例如路徑或查詢參數。
  • 原則順序 - 如果原則 cors 不是輸入區段中的第一個原則，您可能會遭遇非預期的行為。 在原則編輯器中選取 [計算有效原則]，以檢查每個範圍的原則評估順序。 一般而言，只會套用第一個 cors 原則。
  • 空白 200 OK 回應 - 在某些原則設定中，某些跨原始來源要求會以空白的 200 OK 回應來完成。 當 terminate-unmatched-request 設為預設值 true，且傳入要求具有與 cors 原則中設定的允許原始來源不相符的 Origin 標頭時，預期會出現此回應。

範例

此範例示範如何支援預檢要求，例如具有自訂標頭或 GET 和 POST 以外方法的要求。 若要支援自訂標頭和其他 HTTP 指令動詞，請使用 allowed-methods 和 allowed-headers 區段，如下列範例所示。

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

相關內容

如需使用原則的詳細資訊，請參閱：