API Management för att verifiera begäranden och svar

Den här artikeln innehåller en referens för följande API Management principer. Information om hur du lägger till och konfigurerar principer finns i Principer i API Management.

Använd valideringsprinciper för att verifiera API-begäranden och svar mot ett OpenAPI-schema och skydda mot sårbarheter, till exempel ktion av huvuden eller nyttolast. Valideringsprinciper ersätter inte en Web Application Firewall, men ger flexibilitet att svara på en ytterligare klass av hot som inte omfattas av säkerhetsprodukter som förlitar sig på statiska, fördefinierade regler.

Verifieringsprinciper

Anteckning

Den maximala storleken för API-schemat som kan användas av en valideringsprincip är 4 MB. Om schemat överskrider den här gränsen returnerar valideringsprinciper fel vid körning. Kontakta supporten för att öka antalet.

Åtgärder

Varje valideringsprincip innehåller ett attribut som anger en åtgärd som API Management vidtar när en entitet verifieras i en API-begäran eller ett API-svar mot API-schemat. En åtgärd kan anges för element som representeras i API-schemat och, beroende på principen, för element som inte representeras i API-schemat. En åtgärd som anges i en princips underordnade element åsidosätter en åtgärd som angetts för dess överordnade element.

Tillgängliga åtgärder:

Åtgärd Beskrivning
Ignorera Hoppa över validering.
Förhindra Blockera bearbetning av begäran eller svar, logga det utförliga valideringsfeletoch returnera ett fel. Bearbetningen avbryts när den första uppsättningen fel identifieras.
detect Loggverifieringsfel, utan att avbryta bearbetning av begäran eller svar.

Loggar

Information om valideringsfelen under principkörning loggas till variabeln i som anges context.Variables errors-variable-name i attributet i principens rotelement. När ett valideringsfel konfigureras i en åtgärd blockeras ytterligare bearbetning av förfrågningar eller prevent svar och sprids även till egenskapen context.LastError .

Om du vill undersöka fel använder du en spårningsprincip för att logga felen från kontextvariabler till Application Insights.

Prestandaöverväganden

Att lägga till valideringsprinciper kan påverka API-dataflödet. Följande allmänna principer gäller:

  • Ju större API-schemastorlek, desto lägre blir dataflödet.
  • Ju större nyttolasten i en begäran eller ett svar, desto lägre blir dataflödet.
  • STORLEKEN på API-schemat har en större inverkan på prestanda än storleken på nyttolasten.
  • Validering mot ett API-schema som är flera megabyte i storlek kan orsaka tidsgränser för begäran eller svar under vissa förhållanden. Effekten är mer uttalad i förbruknings- och utvecklarnivå för tjänsten.

Vi rekommenderar att du utför belastningstester med dina förväntade produktionsarbetsbelastningar för att utvärdera effekten av valideringsprinciper på API-dataflödet.

Verifiera innehåll

Principen validate-content validerar storleken eller JSON-schemat för en begäran eller svarstext mot API-schemat. Andra format än JSON stöds inte.

Principutdrag

<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="content type string, for example: application/json, application/hal+json" validate-as="json" action="ignore|prevent|detect" />
</validate-content>

Exempel

I följande exempel verifieras JSON-nyttolasten i begäranden och svar i identifieringsläge. Meddelanden med nyttolaster som är större än 100 KB blockeras.

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

Element

Namn Beskrivning Krävs
verifiera innehåll Rotelementet. Yes
innehåll Lägg till ett eller flera av de här elementen för att verifiera innehållstypen i begäran eller svaret och utför den angivna åtgärden. No

Attribut

Name Beskrivning Krävs Standardvärde
unspecified-content-type-action Åtgärd som ska utföras för begäranden eller svar med en innehållstyp som inte har angetts i API-schemat. Yes Ej tillämpligt
maximal storlek Maximal längd för brödtexten i begäran eller svaret i byte, markerat mot Content-Length rubriken. Om begärandetexten eller svarstexten komprimeras är det här värdet den dekomprimerade längden. Högsta tillåtna värde: 102 400 byte (100 kB). (Kontakta supporten om du behöver öka den här gränsen.) Yes Ej tillämpligt
size-exceeded-action Åtgärd som ska utföras för begäranden eller svar vars brödtext överskrider den storlek som anges i max-size . Yes Ej tillämpligt
errors-variable-name Namnet på variabeln i context.Variables för att logga verifieringsfel till. No Ej tillämpligt
typ Innehållstyp som brödtextvalidering ska köras för, markerat mot Content-Type rubriken. Det här värdet är okänsligt. Om det är tomt gäller det för varje innehållstyp som anges i API-schemat. No Ej tillämpligt
validate-as Valideringsmotor som ska användas för validering av brödtexten i en begäran eller ett svar med en matchande innehållstyp. För närvarande är det enda värdet som stöds "json". Yes Ej tillämpligt
åtgärd Åtgärd som ska utföras för begäranden eller svar vars brödtext inte matchar den angivna innehållstypen. Yes Ej tillämpligt

Användning

Den här principen kan användas i följande principavsnitt och omfång.

  • Principavsnitt: inkommande, utgående, vid fel

  • Principomfång: alla omfång

Validera parametrar

Principen validate-parameters validerar parametrarna rubrik, fråga eller sökväg i begäranden mot API-schemat.

Viktigt

Om du importerade ett API med en hanterings-API-version 2021-01-01-preview före kanske principen inte validate-parameters fungerar. Du kan behöva importera api:et igen med hjälp av hanterings-API-versionen 2021-01-01-preview eller senare.

Principutdrag

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

Exempel

I det här exemplet verifieras alla fråge- och sökvägsparametrar i skyddsläge och rubriker i identifieringsläget. Valideringen åsidosätts för flera huvudparametrar:

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

Element

Namn Beskrivning Krävs
validate-parameters Rotelementet. Anger standardvalideringsåtgärder för alla parametrar i begäranden. Yes
Headers Lägg till det här elementet för att åsidosätta standardvalideringsåtgärder för rubrikparametrar i begäranden. No
DocumentDB Lägg till det här elementet för att åsidosätta standardvalideringsåtgärder för frågeparametrar i begäranden. No
path Lägg till det här elementet för att åsidosätta standardvalideringsåtgärder för URL-sökvägsparametrar i begäranden. No
parameter Lägg till ett eller flera element för namngivna parametrar för att åsidosätta konfigurationen på högre nivå av valideringsåtgärderna. No

Attribut

Name Beskrivning Krävs Standardvärde
specified-parameter-action Åtgärd som ska utföras för begärandeparametrar som anges i API-schemat.

När värdet anges headers i query ett path -, - eller -element åsidosätter det värdet specified-parameter-action för i elementet validate-parameters .
Yes Ej tillämpligt
unspecified-parameter-action Åtgärd som ska utföras för begärandeparametrar som inte anges i API-schemat.

När värdet anges headers i ett - eller query -element åsidosätter det värdet unspecified-parameter-action för i elementet validate-parameters .
Yes Ej tillämpligt
errors-variable-name Namnet på variabeln i context.Variables för att logga verifieringsfel till. No Ej tillämpligt
name Namnet på parametern som valideringsåtgärden ska åsidosätta för. Det här värdet är okänsligt. Yes Ej tillämpligt
åtgärd Åtgärd som ska utföras för parametern med matchande namn. Om parametern anges i API-schemat åsidosätter det här värdet konfigurationen på högre specified-parameter-action nivå. Om parametern inte anges i API-schemat åsidosätter det här värdet konfigurationen på högre unspecified-parameter-action nivå. Yes Ej tillämpligt

Användning

Den här principen kan användas i följande principavsnitt och omfång.

  • Principavsnitt: inkommande

  • Principomfång: alla omfång

Verifiera huvuden

Principen validate-headers validerar svarshuvudena mot API-schemat.

Viktigt

Om du importerade ett API med en hanterings-API-version 2021-01-01-preview före kanske principen inte validate-headers fungerar. Du kan behöva importera api:et igen med hjälp av hanterings-API-versionen 2021-01-01-preview eller senare.

Principutdrag

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

Exempel

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

Element

Namn Beskrivning Krävs
validate-headers Rotelementet. Anger standardvalideringsåtgärder för alla huvuden i svar. Yes
sidhuvud Lägg till ett eller flera element för namngivna huvuden för att åsidosätta standardvalideringsåtgärderna för huvuden i svar. No

Attribut

Name Beskrivning Krävs Standardvärde
specified-header-action Åtgärd som ska utföras för svarshuvuden som anges i API-schemat. Yes Ej tillämpligt
unspecified-header-action Åtgärd som ska utföras för svarshuvuden som inte har angetts i API-schemat. Yes Ej tillämpligt
errors-variable-name Namnet på variabeln i context.Variables för att logga verifieringsfel till. No Ej tillämpligt
name Namnet på rubriken som valideringsåtgärden ska åsidosätta. Det här värdet är okänsligt. Yes Ej tillämpligt
åtgärd Åtgärd som ska utföras för rubriken med matchande namn. Om -huvudet anges i API-schemat åsidosätter det här värdet värdet specified-header-action för i validate-headers elementet . Annars åsidosätter den värdet för unspecified-header-action i elementet validate-headers. Yes Ej tillämpligt

Användning

Den här principen kan användas i följande principavsnitt och omfång.

  • Principavsnitt: utgående, vid fel

  • Principomfång: alla omfång

Verifiera statuskod

Principen validate-status-code validerar HTTP-statuskoderna i svar mot API-schemat. Den här principen kan användas för att förhindra läckage av backend-fel, som kan innehålla stackspårningar.

Principutdrag

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

Exempel

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

Element

Namn Beskrivning Krävs
validate-status-code Rotelementet. Yes
statuskod Lägg till ett eller flera element för HTTP-statuskoder för att åsidosätta standardvalideringsåtgärden för statuskoder i svar. No

Attribut

Name Beskrivning Krävs Standardvärde
unspecified-status-code-action Åtgärd som ska utföras för HTTP-statuskoder i svar som inte har angetts i API-schemat. Yes Ej tillämpligt
errors-variable-name Namnet på variabeln i context.Variables för att logga verifieringsfel till. No Ej tillämpligt
kod HTTP-statuskod som verifieringsåtgärden ska åsidosätta för. Yes Ej tillämpligt
åtgärd Åtgärd som ska utföras för matchande statuskod, som inte anges i API-schemat. Om statuskoden anges i API-schemat gäller inte den här åsidosättningen. Yes Ej tillämpligt

Användning

Den här principen kan användas i följande principavsnitt och omfång.

  • Principavsnitt: utgående, vid fel

  • Principomfång: alla omfång

Valideringsfel

I följande tabell visas alla möjliga fel i valideringsprinciperna.

  • Information – kan användas för att undersöka fel. Inte avsedd att delas offentligt.
  • Offentligt svar – Fel returnerades till klienten. Läcker inte implementeringsinformation.

När en valideringsprincip anger åtgärden och genererar ett fel innehåller svaret från API Management en HTTP-statuskod: 400 när principen tillämpas i avsnittet inkommande och 502 när principen tillämpas i avsnittet prevent utgående.

Namn Typ Verifieringsuttryck Information Offentligt svar Åtgärd
verifiera innehåll
RequestBody SizeLimit Begärandetexten är {size} byte lång och överskrider den konfigurerade gränsen på {maxSize} byte. Begärandetexten är {size} byte lång och överskrider gränsen på {maxSize} byte. identifiera/förhindra
ResponseBody SizeLimit Svarets brödtext är {size} byte lång och överskrider den konfigurerade gränsen på {maxSize} byte. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{messageContentType} RequestBody Ospecificerat Ospecificerad innehållstyp {messageContentType} tillåts inte. Ospecificerad innehållstyp {messageContentType} tillåts inte. identifiera/förhindra
{messageContentType} ResponseBody Ospecificerat Ospecificerad innehållstyp {messageContentType} tillåts inte. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ApiSchema API-schemat finns inte eller så gick det inte att matcha det. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ApiSchema API-schemat anger inte definitioner. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{messageContentType} RequestBody/ResponseBody MissingDefinition API-schemat innehåller inte definitionen {definitionName}, som är associerad med innehållstypen {messageContentType}. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{messageContentType} RequestBody IncorrectMessage Brödtexten i begäran överensstämmer inte med definitionen {definitionName}, som är associerad med innehållstypen {messageContentType}.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}
Brödtexten i begäran överensstämmer inte med definitionen {definitionName}, som är associerad med innehållstypen {messageContentType}.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}
identifiera/förhindra
{messageContentType} ResponseBody IncorrectMessage Brödtexten i svaret överensstämmer inte med definitionen {definitionName}, som är associerad med innehållstypen {messageContentType}.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}
Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
RequestBody ValidationException Begärandetexten kan inte verifieras för innehållstypen {messageContentType}.

{undantagsinformation}
Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ResponseBody ValidationException Brödtexten i svaret kan inte verifieras för innehållstypen {messageContentType}.

{undantagsinformation}
Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
validate-parameters/validate-headers
{paramName} / {headerName} QueryParameter/PathParameter/RequestHeader Ospecificerat Ospecificerad {sökvägsparameter/frågeparameter/rubrik} {paramName} tillåts inte. Ospecificerad {sökvägsparameter/frågeparameter/rubrik} {paramName} tillåts inte. identifiera/förhindra
{headerName} ResponseHeader Ospecificerat Ospecificerad rubrik {headerName} tillåts inte. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ApiSchema API:et har inget schema eller så gick det inte att lösa det. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
ApiSchema API-schemat anger inte definitioner. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader/ResponseHeader MissingDefinition API-schemat innehåller inte definitionen {definitionName}, som är associerad med {query parameter/path parameter/header} {paramName}. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Begäran får inte innehålla flera värden för parametern {query/path parameter/header} {paramName}. Begäran får inte innehålla flera värden för parametern {query/path parameter/header} {paramName}. identifiera/förhindra
{headerName} ResponseHeader IncorrectMessage Svaret får inte innehålla flera värden för rubriken {headerName}. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Värdet för {query parameter/path parameter/header} {paramName} överensstämmer inte med definitionen.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}
Värdet för {query parameter/path parameter/header} {paramName} överensstämmer inte med definitionen.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}
identifiera/förhindra
{headerName} ResponseHeader IncorrectMessage Värdet för rubriken {headerName} överensstämmer inte med definitionen.

{valError.Message} Rad: {valError.LineNumber}, Position: {valError.LinePosition}
Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Värdet för {query parameter/path parameter/header} {paramName} kan inte parsas enligt definitionen.

{ex. Meddelande}
Värdet för {query parameter/path parameter/header} {paramName} kunde inte parsas enligt definitionen.

{ex. Meddelande}
identifiera/förhindra
{headerName} ResponseHeader IncorrectMessage Det gick inte att parsa värdet för rubriken {headerName} enligt definitionen. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{paramName} QueryParameter/PathParameter/RequestHeader ValidationError {Frågeparameter/sökvägsparameter/rubrik} {paramName} kan inte verifieras.

{undantagsinformation}
Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
{headerName} ResponseHeader ValidationError Det går inte att verifiera rubriken {headerName}.

{undantagsinformation}
Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra
validate-status-code
{status-code} StatusCode Ospecificerat Svarsstatuskoden {status-code} tillåts inte. Det gick inte att bearbeta begäran på grund av ett internt fel. Kontakta API-ägaren. identifiera/förhindra

I följande tabell visas alla möjliga orsaksvärden för ett valideringsfel tillsammans med möjliga meddelandevärden:

Anledning Meddelande
Felaktig begäran {Details} för sammanhangsvariabeln {Offentligt svar} för klienten
Svaret tillåts inte {Details} för sammanhangsvariabeln {Offentligt svar} för klienten

Nästa steg

Mer information om hur du arbetar med principer finns i: