API 管理原則來驗證要求和回應

  • 發行項

本文提供API 管理原則的參考，以針對 API 定義或補充 JSON 或 XML 架構中所定義的架構驗證 REST 或 SOAP API 要求和回應。 驗證原則可防止插入標頭或承載或洩漏敏感性資料等弱點。 深入瞭解常見的 API 弱點。

雖然不是取代Web 應用程式防火牆，但驗證原則提供彈性，以回應依賴靜態預先定義規則的安全性產品未涵蓋的其他威脅類別。

原則的詳細資訊：

驗證原則

  • 驗證內容 - 根據一或多個 API 架構驗證要求或回應本文的大小或內容。 支援的架構格式為 JSON 和 XML。
  • 驗證參數 - 根據 API 架構驗證要求標頭、查詢或路徑參數。
  • 驗證標頭 - 根據 API 架構驗證回應標頭。
  • 驗證狀態碼 - 驗證 API 架構回應中的 HTTP 狀態碼。

注意

驗證原則可以使用的 API 架構大小上限為 4 MB。 如果架構超過此限制，驗證原則會在執行時間傳回錯誤。 若要增加，請連絡 支援人員。

動作

每個驗證原則都包含一個屬性，指定動作，API 管理驗證 API 要求中的實體或對 API 架構的回應時採取此動作。

  • 針對 API 架構中所表示的專案，以及根據原則，針對 API 架構中未表示的專案，可以指定動作。

  • 原則子項目中指定的動作會覆寫為其父元素指定的動作。

可用的動作：

動作 描述
ignore 略過驗證。
prevent 封鎖要求或回應處理、記錄詳細資訊 驗證錯誤，並傳回錯誤。 偵測到第一組錯誤時，處理會中斷。
detect 記錄 驗證錯誤，而不會中斷要求或回應處理。

記錄

原則執行期間驗證錯誤的詳細資料會記錄至原則根項目之 屬性中指定的 errors-variable-name 變數 context.Variables 。 在動作中 prevent 設定時，驗證錯誤會封鎖進一步的要求或回應處理，而且也會傳播至 context.LastError 屬性。

若要調查錯誤，請使用追蹤原則，將內容變數的錯誤記錄到應用程式Insights。

效能影響

新增驗證原則可能會影響 API 輸送量。 下列一般原則適用：

  • API 架構大小愈大，輸送量就越低。
  • 要求或回應中的承載愈大，輸送量就越低。
  • API 架構的大小對效能的影響大於承載的大小。
  • 針對大小為數 MB 的 API 架構進行驗證，可能會在某些情況下造成要求或回應逾時。 在服務的 取 用和 開發人員 層中，效果更明顯。

建議您使用預期的生產工作負載執行負載測試，以評估驗證原則對 API 輸送量的影響。

驗證內容

此原則 validate-content 會根據一或多個 支援的架構，驗證要求或回應本文的大小或內容。

提示

為了協助您設定此原則，入口網站會提供以表單為基礎的引導式編輯器。 深入瞭解如何設定或編輯API 管理原則。

下表顯示原則支援的架構格式和要求或回應內容類型。 內容類型值不區分大小寫。

格式 內容類型
JSON 範例：application/json
application/hal+json
XML 範例： application/xml
SOAP 允許的值： application/soap+xml 針對 SOAP 1.2 API
text/xml 適用于 SOAP 1.1 API

驗證的內容

此原則會驗證對架構的要求或回應中的下列內容：

  • 所有必要屬性是否存在。
  • 如果架構已 additionalProperties 將 欄位設定為 false ，則沒有其他屬性。
  • 所有屬性的類型。 例如，如果架構將屬性指定為整數，則要求 (或回應) 必須包含整數，而不是另一種類型，例如字串。
  • 屬性的格式，如果在架構中指定 ，例如，RegEx (如果 pattern 指定關鍵字) 、 minimum 整數等等。

提示

如需可用於架構的 RegEx 模式條件約束範例，請參閱 OWASP 驗證 Regex 存放庫。

原則陳述式

<validate-content unspecified-content-type-action="ignore|prevent|detect" max-size="size in bytes" size-exceeded-action="ignore|prevent|detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from|when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json|xml|soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore|prevent|detect" />
</validate-content>

範例

JSON 架構驗證

在下列範例中，API 管理解譯具有空白內容類型標頭的要求，或具有內容類型標頭 application/hal+json 的要求做為內容類型 application/json 的要求。 然後，API 管理針對 API 定義中內容類型定義的 application/json 架構，在偵測模式中執行驗證。 承載大於 100 KB 的訊息會遭到封鎖。

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" />
</validate-content>

SOAP 架構驗證

在下列範例中，不論傳入內容類型為何，API 管理將任何要求解譯為內容類型 application/soap+xml 的要求， (SOAP 1.2) API 所使用的內容類型。 要求可能會以空的內容類型標頭、SOAP 1.1 API) 或其他內容類型標頭所使用的 (內容類型標頭 text/xml 送達。 然後，API 管理從 SOAP 信封擷取 XML 承載，並針對名為 「myschema」 的架構，以預防模式執行驗證。 承載大於 100 KB 的訊息會遭到封鎖。

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

項目

名稱 描述 必要
validate-content 根元素。 是
content-type-map 新增這個專案，將傳入要求的內容類型或回應對應至另一個用來觸發驗證的內容類型。 否
content 新增一或多個元素，以驗證要求或回應中的內容類型，或對應的內容類型，然後執行指定的動作。 否

屬性

名稱 描述 必要 預設
unspecified-content-type-action 針對 在 API 架構中未指定內容類型的要求或回應執行動作。 是 N/A
max-size 針對標頭檢查 Content-Length 的要求或回應主體長度上限，以位元組為單位。 如果壓縮要求本文或回應本文，這個值就是解壓縮的長度。 允許的最大值：102，400 個位元組 (100 KB) 。 如果您需要增加此限制，請 (連絡 支援人員 。) 是 N/A
size-exceeded-action 針對主體超過 中指定的 max-size 大小的要求或回應執行的動作。 是 N/A
errors-variable-name 中 context.Variables 要記錄驗證錯誤的變數名稱。 否 N/A
any-content-type-value 不論傳入內容類型為何，用於驗證要求或回應主體的內容類型。 否 N/A
missing-content-type-value 當傳入內容類型遺失或空白時，用於驗證要求或回應主體的內容類型。 否 N/A
content-type-map \ type 新增一或多個元素，將傳入內容類型對應至用來驗證要求或回應主體的內容類型。 使用 from 來指定已知的傳入內容類型，或 when 搭配原則運算式使用 來指定符合條件的任何傳入內容類型。 如果指定，則會覆寫 和 missing-content-type-value 中的 any-content-type-value 對應。 否 N/A
content \ type 要執行本文驗證的內容類型，如果指定，則會根據內容類型標頭或對應的值 content-type-mapping 進行檢查。 如果空白，則會套用至 API 架構中指定的每個內容類型。

若要驗證 SOAP 要求和回應 (validate-as 屬性設為 「soap」) ，請將 設為 typeapplication/soap+xml SOAP 1.2 API 或 text/xml SOAP 1.1 API。		 否 N/A
validate-as 驗證引擎，用來驗證具有相符 type 的要求或回應主體。 支援的值：「json」、「xml」、「soap」。

指定 「soap」 時，會從 SOAP 信封擷取來自要求或回應的 XML，並針對 XML 架構進行驗證。		 是 N/A
schema-id 新增至內容驗證之API 管理實例的現有架構名稱。 如果未指定，則會使用 API 定義的預設架構。 否 N/A
schema-ref 針對 中指定的 schema-id JSON 架構，針對 JSON 檔中有效本機參考路徑的選擇性參考。 範例： #/components/schemas/address. 屬性應該會傳回 JSON 物件，API 管理處理為有效的 JSON 架構。

對於 XML 架構， schema-ref 不支援，而且任何最上層架構專案都可以做為 XML 要求或回應承載的根目錄。 驗證會檢查從 XML 要求或回應承載根目錄開始的所有專案都遵守提供的 XML 架構。		 否 N/A
動作 針對 主體不符合指定內容類型的要求或回應執行動作。 是 N/A

內容驗證的架構

根據預設，要求或回應內容的驗證會使用 API 定義的 JSON 或 XML 架構。 將 API 從 OpenAPI 或 WSDL 規格匯入API 管理時，可以手動或自動指定這些架構。

使用原則 validate-content 時，您可以選擇性地針對已新增至 API 管理 實例且不屬於 API 定義的一或多個 JSON 或 XML 架構進行驗證。 您新增至API 管理的架構可以跨許多 API 重複使用。

若要使用 Azure 入口網站，將架構新增至您的API 管理實例：

  1. 在入口網站中，流覽至您的 API 管理 實例。

  2. 在左側功能表的 [API]區段中，選取 [架構>+ 新增]。

  3. 在 [ 建立架構 ] 視窗中，執行下列動作：

    1. 輸入架構的 [名稱 ]。
    2. 在 [架構類型] 中，選取 [JSON ] 或 [ XML]。
    3. 輸入說明。
    4. 在 Create 方法中，執行下列其中一項：
      • 選取 [新建 ]，然後輸入或貼上架構。
      • 選取 [從檔案匯 入] 或 [ 從 URL 匯 入]，然後輸入架構位置。

        注意

        若要從 URL 匯入架構，您必須從瀏覽器透過網際網路存取架構。

    5. 選取 [儲存]。

    Create schema

建立架構之後，它會出現在 [ 架構 ] 頁面上的清單中。 選取架構以檢視其屬性，或在架構編輯器中編輯。

注意

  • 架構可能會交叉參考另一個新增至 API 管理 實例的架構。
  • 開放原始碼工具可解析 WSDL 和 XSD 架構參考，以及將產生的架構批次匯入至API 管理，可在GitHub上使用。

使用方式

此原則可用於下列原則區段和範圍。

  • 原則區段︰輸入、輸出、錯誤

  • 原則範圍：所有範圍

驗證參數

此 validate-parameters 原則會根據 API 架構，在要求中驗證標頭、查詢或路徑參數。

重要

如果您在 之前 2021-01-01-preview 使用管理 API 版本匯入 API，則原則 validate-parameters 可能無法運作。 您可能需要使用管理 API 版本或更新版本 2021-01-01-preview來重新匯入您的 API。

提示

為了協助您設定此原則，入口網站會提供以表單為基礎的引導式編輯器。 深入瞭解如何設定或編輯API 管理原則。

原則陳述式

<validate-parameters specified-parameter-action="ignore|prevent|detect" unspecified-parameter-action="ignore|prevent|detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore|prevent|detect" unspecified-parameter-action="ignore|prevent|detect">
        <parameter name="parameter name" action="ignore|prevent|detect" />
    </headers>
    <query specified-parameter-action="ignore|prevent|detect" unspecified-parameter-action="ignore|prevent|detect">
        <parameter name="parameter name" action="ignore|prevent|detect" />
    </query>
    <path specified-parameter-action="ignore|prevent|detect">
        <parameter name="parameter name" action="ignore|prevent|detect" />
    </path>
</validate-parameters>

範例

在此範例中，所有查詢和路徑參數都會在偵測模式的預防模式和標頭中驗證。 已覆寫數個標頭參數的驗證：

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

項目

名稱 描述 必要
validate-parameters 根元素。 指定要求中所有參數的預設驗證動作。 是
headers 新增此元素以覆寫要求中標頭參數的預設驗證動作。 否
query 新增此元素以覆寫要求中查詢參數的預設驗證動作。 否
path 新增此元素以覆寫要求中 URL 路徑參數的預設驗證動作。 否
parameter 為具名參數新增一或多個元素，以覆寫驗證動作的較高層級組態。 否

屬性

名稱 描述 必要 預設
specified-parameter-action 針對 API 架構中指定的要求參數執行動作。

在 、 或 專案中提供 headers 時，值會覆寫 專案中的值 specified-parameter-actionvalidate-parameters 。 pathquery		 是 N/A
unspecified-parameter-action 針對 API 架構中未指定之要求參數執行的動作。

在 或 專案中提供 headers 時，值會覆寫 專案中的值 unspecified-parameter-actionvalidate-parameters 。 query		 是 N/A
errors-variable-name 中 context.Variables 要記錄驗證錯誤的變數名稱。 否 N/A
name 要覆寫驗證動作的參數名稱。 這個值不區分大小寫。 是 N/A
action 要針對具有相符名稱的參數執行動作。 如果在 API 架構中指定 參數，這個值會覆寫較高層級 specified-parameter-action 的組態。 如果未在 API 架構中指定 參數，這個值會覆寫較高層級 unspecified-parameter-action 的組態。 是 N/A

使用方式

此原則可用於下列原則區段和範圍。

  • 原則區段︰inbound

  • 原則範圍：所有範圍

驗證標頭

原則 validate-headers 會根據 API 架構驗證回應標頭。

重要

如果您使用之前的 2021-01-01-preview 管理 API 版本匯入 API，原則 validate-headers 可能無法運作。 您可能需要使用管理 API 版本或更新版本 2021-01-01-preview 重新匯入 API。

提示

為了協助您設定此原則，入口網站會提供引導式表單式編輯器。 深入瞭解如何設定或編輯API 管理原則。

原則陳述式

<validate-headers specified-header-action="ignore|prevent|detect" unspecified-header-action="ignore|prevent|detect" errors-variable-name="variable name">
    <header name="header name" action="ignore|prevent|detect" />
</validate-headers>

範例

<validate-headers specified-header-action="ignore" unspecified-header-action="prevent" errors-variable-name="responseHeadersValidation" />

項目

名稱 描述 必要
validate-headers 根元素。 指定回應中所有標頭的預設驗證動作。 是
header 為具名標頭新增一或多個元素，以覆寫回應中標頭的預設驗證動作。 否

屬性

名稱 描述 必要 預設
specified-header-action 針對 API 架構中指定的回應標頭執行動作。 是 N/A
unspecified-header-action 針對 API 架構中未指定的回應標頭執行動作。 是 N/A
errors-variable-name 中 context.Variables 要記錄驗證錯誤的變數名稱。 否 N/A
name 要覆寫驗證動作的標頭名稱。 這個值不區分大小寫。 是 N/A
action 要針對具有相符名稱的標頭執行動作。 如果在 API 架構中指定標頭，這個值會覆寫 元素中的 validate-headers 值 specified-header-action 。 否則，它會覆寫 validate-headers 元素中的 值 unspecified-header-action 。 是 N/A

使用方式

此原則可用於下列原則區段和範圍。

  • 原則區段： 輸出、發生錯誤

  • 原則範圍：所有範圍

驗證狀態碼

原則 validate-status-code 會驗證 HTTP 狀態碼，以回應 API 架構。 此原則可用來防止後端錯誤外泄，其中包含堆疊追蹤。

提示

為了協助您設定此原則，入口網站會提供引導式表單式編輯器。 深入瞭解如何設定或編輯API 管理原則。

原則陳述式

<validate-status-code unspecified-status-code-action="ignore|prevent|detect" errors-variable-name="variable name">
    <status-code code="HTTP status code number" action="ignore|prevent|detect" />
</validate-status-code>

範例

<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />

項目

名稱 描述 必要
validate-status-code 根元素。 是
status-code 為 HTTP 狀態碼新增一或多個元素，以覆寫回應中狀態碼的預設驗證動作。 否

屬性

名稱 描述 必要 預設
unspecified-status-code-action 在 API 架構中未指定之回應中執行 HTTP 狀態碼的動作。 是 N/A
errors-variable-name 中 context.Variables 要記錄驗證錯誤的變數名稱。 否 N/A
code 要覆寫驗證動作的 HTTP 狀態碼。 是 N/A
action 要針對 API 架構中未指定之相符狀態碼執行的動作。 如果在 API 架構中指定狀態碼，則此覆寫不會生效。 是 N/A

使用方式

此原則可用於下列原則區段和範圍。

  • 原則區段： 輸出、錯誤

  • 原則範圍：所有範圍

驗證錯誤

API 管理會產生下列格式的驗證錯誤：

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

下表列出驗證原則的所有可能錯誤。

  • 詳細資料：可用來調查錯誤。 不打算公開共用。
  • 公用回應：傳回給用戶端的錯誤。 不會洩漏實作詳細資料。

當驗證原則指定 prevent 動作並產生錯誤時，來自 API 管理的回應會包含 HTTP 狀態碼：在輸入區段中套用原則時為 400，並在輸出區段中套用原則時為 502。

名稱 型別 驗證規則 詳細資料 公用回應 動作
validate-content
RequestBody SizeLimit 要求的主體長度為 {size} 個位元組，超過 {maxSize} 個位元組的設定限制。 要求的本文長度為 {size} 個位元組，超過 {maxSize} 個位元組的限制。 detect / prevent
ResponseBody SizeLimit 回應的本文長度為 {size} 位元組，超過 {maxSize} 位元組的設定限制。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
{messageContentType} RequestBody [未指定] 不允許未指定的內容類型 {messageContentType} 。 不允許未指定的內容類型 {messageContentType} 。 detect / prevent
{messageContentType} ResponseBody [未指定] 不允許未指定的內容類型 {messageContentType} 。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
ApiSchema API 的架構不存在或無法解析。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
ApiSchema API 的架構未指定定義。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
{messageContentType} RequestBody / ResponseBody MissingDefinition API 的架構不包含定義 {definitionName}，與內容類型 {messageContentType} 相關聯。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
{messageContentType} RequestBody IncorrectMessage 要求的本文不符合與內容類型 {messageContentType} 相關聯的定義 {definitionName}。

{valError.Message} 行： {valError.LineNumber}， Position： {valError.LinePosition}		 要求的本文不符合與內容類型 {messageContentType} 相關聯的定義 {definitionName}。

{valError.Message} 行： {valError.LineNumber}， Position： {valError.LinePosition}		 detect / prevent
{messageContentType} ResponseBody IncorrectMessage 回應本文不符合定義 {definitionName}，與內容類型 {messageContentType} 相關聯。

{valError.Message} 行： {valError.LineNumber}， Position： {valError.LinePosition}		 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
RequestBody ValidationException 無法驗證內容類型 {messageContentType} 的要求本文。

{例外狀況詳細資料}		 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
ResponseBody ValidationException 無法驗證內容類型 {messageContentType} 的回應本文。

{例外狀況詳細資料}		 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
validate-parameters / validate-headers
{paramName} / {headerName} QueryParameter / PathParameter / RequestHeader [未指定] 不允許未指定的 {path 參數/ 查詢參數 / 標頭} {paramName} 。 不允許未指定的 {path 參數/ 查詢參數 / 標頭} {paramName} 。 detect / prevent
{headerName} ResponseHeader [未指定] 不允許未指定的標頭 {headerName}。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
ApiSchema API 的架構不存在或無法解析。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
ApiSchema API 架構未指定定義。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader / ResponseHeader MissingDefinition API 的架構不包含定義 {definitionName}，與 {query 參數 / path 參數 / header} {paramName} 相關聯。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage 要求不能包含 {query 參數 / path 參數 / header} {paramName} 的多個值。 要求不能包含 {query 參數 / path 參數 / header} {paramName} 的多個值。 detect / prevent
{headerName} ResponseHeader IncorrectMessage 回應不能包含標頭 {headerName} 的多個值。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage {query 參數 / path 參數 / header} {paramName} 的值不符合定義。

{valError.Message} 行： {valError.LineNumber}， Position： {valError.LinePosition}		 {query 參數 / path 參數 / header} {paramName} 的值不符合定義。

{valError.Message} 行： {valError.LineNumber}， Position： {valError.LinePosition}		 detect / prevent
{headerName} ResponseHeader IncorrectMessage 標頭 {headerName} 的值不符合定義。

{valError.Message} 行： {valError.LineNumber}， Position： {valError.LinePosition}		 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage 無法根據定義剖析 {query 參數 / path 參數 / header} {paramName} 的值。

{ex.Message}		 無法根據定義剖析 {query 參數 / path 參數 / header} {paramName} 的值。

{ex.Message}		 detect / prevent
{headerName} ResponseHeader IncorrectMessage 無法根據定義剖析標頭 {headerName} 的值。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader ValidationError {Query parameter / Path parameter / Header}無法驗證 {paramName}。

{例外狀況詳細資料}		 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
{headerName} ResponseHeader ValidationError 無法驗證標頭 {headerName}。

{例外狀況詳細資料}		 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent
validate-status-code
{status-code} StatusCode [未指定] 不允許回應狀態碼 {status-code}。 因為發生內部錯誤，所以無法處理要求。 請連絡 API 擁有者。 detect / prevent

下表列出驗證錯誤的所有可能 Reason 值，以及可能的訊息值：

原因 訊息
不正確的要求 內容變數的 {Details} ，用戶端的 {Public response}
不允許回應 內容變數的 {Details} ，用戶端的 {Public response}

後續步驟

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