Zásady omezení přístupu ke službě API Management

  • Článek
  • 19 min ke čtení

V tomto tématu najdete referenční informace pro následující zásady API Management. Informace o přidávání a konfiguraci zásad najdete v tématu zásady v API Management.

Zásady omezení přístupu

Tip

Zásady omezení přístupu můžete použít v různých oborech pro různé účely. Můžete například zabezpečit celé rozhraní API pomocí ověřování AAD, a to tak, že použijete validate-jwt zásady na úrovni rozhraní API, nebo ho můžete použít na úrovni operace rozhraní API a použít k podrobnějšímu claims řízení.

Kontrolovat hlavičku HTTP

Pomocí check-header zásady můžete vyhovět, že žádost má určenou HLAVIČKU http. Volitelně můžete kontrolovat, zda má hlavička určitou hodnotu, nebo kontrolovat Rozsah povolených hodnot. Pokud se ověření nepovede, zásada ukončí zpracování žádosti a vrátí stavový kód HTTP a chybovou zprávu určenou zásadou.

Prohlášení o zásadách

<check-header name="header name" failed-check-httpcode="code" failed-check-error-message="message" ignore-case="true">
    <value>Value1</value>
    <value>Value2</value>
</check-header>

Příklad

<check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
    <value>f6dc69a089844cf6b2019bae6d36fac8</value>
</check-header>

Elementy

Název Popis Povinné
check-Header Kořenový element. Yes
hodnota Povolená hodnota hlavičky protokolu HTTP. Je-li zadána více elementů hodnot, je tato kontrolu považována za úspěšnou, pokud je jedna z hodnot shodná. No

Atributy

Název Popis Povinné Výchozí
neúspěšné-chyba-chyba-zpráva Chybová zpráva, která se má vrátit v těle odpovědi HTTP, pokud hlavička neexistuje nebo má neplatnou hodnotu. Tato zpráva musí mít správně uvozené speciální znaky. Yes –
chyba-check-httpCode Stavový kód HTTP, který se má vrátit, pokud hlavička neexistuje nebo má neplatnou hodnotu. Yes –
záhlaví – název Název hlavičky HTTP, která se má ověřit Yes –
ignorovat – případ Lze nastavit na hodnotu true nebo false. Pokud je hodnota nastavená na true Case, ignoruje se při porovnání hodnoty hlavičky se sadou přijatelných hodnot. Yes –

Využití

Tyto zásady se dají použít v následujících oddílech a oborechzásad.

  • Oddíly zásad: příchozí, odchozí

  • Obory zásad: všechny rozsahy

Omezení četnosti volání podle předplatného

rate-limitZásady zabrání špičkám využití rozhraní API na základě předplatného, a to omezením rychlosti volání na zadaný počet za zadané časové období. Pokud je překročena rychlost volání, volající obdrží 429 Too Many Requests kód stavu odpovědi.

Důležité

Tato zásada se dá pro dokument zásad použít jenom jednou.

Výrazy zásad nelze použít v žádném z atributů zásad pro tuto zásadu.

Upozornění

Vzhledem k distribuované povaze architektury omezování není omezení rychlosti nikdy zcela přesné. Rozdíl mezi nakonfigurovaným a skutečným počtem povolených požadavků se liší v závislosti na objemu a frekvenci požadavků, latenci back-endu a dalších faktorech.

Poznámka

Pro pochopení rozdílu mezi omezeními a kvótami získáte informace v části omezení přenosové rychlosti a kvóty.

Prohlášení o zásadách

<rate-limit calls="number" renewal-period="seconds">
    <api name="API name" id="API id" calls="number" renewal-period="seconds">
        <operation name="operation name" id="operation id" calls="number" renewal-period="seconds" 
        retry-after-header-name="header name" 
        retry-after-variable-name="policy expression variable name"
        remaining-calls-header-name="header name"  
        remaining-calls-variable-name="policy expression variable name"
        total-calls-header-name="header name"/>
    </api>
</rate-limit>

Příklad

V následujícím příkladu je omezení četnosti předplatného na 20 volání za 90 sekund. Po každém spuštění zásad jsou zbývající volání povolená v daném časovém období uložená v proměnné remainingCallsPerSubscription .

<policies>
    <inbound>
        <base />
        <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementy

Název Popis Povinné
frekvence – omezení Kořenový element. Yes
api Přidejte jeden nebo více těchto prvků k omezení četnosti volání rozhraní API v rámci produktu. Omezení rychlosti volání rozhraní API a produktů se aplikují nezávisle. Na rozhraní API se dá odkazovat prostřednictvím name nebo id . Pokud jsou zadány oba atributy, budou id použity a name budou ignorovány. No
operation Přidejte jeden nebo více těchto prvků k omezení četnosti volání operací v rámci rozhraní API. Omezení frekvence volání produktů, rozhraní API a operací se aplikují nezávisle. Na operaci lze odkazovat prostřednictvím name nebo id . Pokud jsou zadány oba atributy, budou id použity a name budou ignorovány. No

Atributy

Název Popis Povinné Výchozí
name Název rozhraní API, pro které se má použít limit přenosové rychlosti Yes –
Volání Maximální povolený celkový počet volání během časového intervalu zadaného v renewal-period . Yes –
renewal-period Délka v sekundách posuvného okna, během kterého by počet povolených požadavků neměl překročit hodnotu zadanou v calls . Maximální povolená hodnota: 300 sekund. Yes –
retry-after-header-name Název hlavičky odpovědi, jejíž hodnota je doporučený interval opakování v sekundách po překročení zadané frekvence volání. No –
retry-after-variable-name Název proměnné výrazu zásad, která ukládá doporučený interval opakování v sekundách po překročení zadané frekvence volání. No –
remaining-calls-header-name Název hlavičky odpovědi, jejíž hodnota po každém spuštění zásady je počet zbývajících volání povolených pro časový interval zadaný v renewal-period . No –
remaining-calls-variable-name Název proměnné výrazu zásad, který po každém spuštění zásady ukládá počet zbývajících volání povolených pro časový interval zadaný v renewal-period . No –
total-calls-header-name Název hlavičky odpovědi, jejíž hodnota je hodnota zadaná v calls . No –

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

  • Oddíly zásad: příchozí

  • Obory zásad: produkt, rozhraní API, operace

Omezení frekvence volání podle klíče

Důležité

Tato funkce není dostupná na úrovni Consumption API Management.

Zásady brání špičkám využití rozhraní API pro každý klíč omezením call rate na zadané číslo rate-limit-by-key za zadané časové období. Klíč může mít libovolnou řetězcovou hodnotu a obvykle se poskytuje pomocí výrazu zásad. Můžete přidat volitelnou podmínku přírůstku, která určuje, které požadavky se mají do limitu započítat. Při překročení této frekvence volání obdrží volající 429 Too Many Requests stavový kód odpovědi.

Další informace a příklady těchto zásad najdete v tématu Pokročilé omezování požadavků pomocí Azure API Management.

Upozornění

Vzhledem k distribuované povaze architektury omezování není omezování rychlosti nikdy úplně přesné. Rozdíl mezi nakonfigurovaným a skutečným počtem povolených požadavků se liší v závislosti na objemu a frekvenci požadavků, latenci back-endu a dalších faktorech.

Poznámka

Informace o rozdílech mezi limity přenosové rychlosti a kvótami najdete v tématu Omezení přenosové rychlosti a kvóty.

Prohlášení o zásadách

<rate-limit-by-key calls="number"
                   renewal-period="seconds"
                   increment-condition="condition"
                   counter-key="key value" 
                   retry-after-header-name="header name" retry-after-variable-name="policy expression variable name"
                   remaining-calls-header-name="header name"  remaining-calls-variable-name="policy expression variable name"
                   total-calls-header-name="header name"/>

Příklad

V následujícím příkladu je omezení rychlosti 10 volání za 60 sekund klíčované IP adresou volajícího. Po každém spuštění zásad se zbývající volání povolená v časovém období uloží do proměnné remainingCallsPerIP .

<policies>
    <inbound>
        <base />
        <rate-limit-by-key  calls="10"
              renewal-period="60"
              increment-condition="@(context.Response.StatusCode == 200)"
              counter-key="@(context.Request.IpAddress)"
              remaining-calls-variable-name="remainingCallsPerIP"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementy

Název Popis Povinné
rate-limit-by-key Kořenový element. Yes

Atributy

Název Popis Povinné Výchozí
Volání Maximální povolený celkový počet volání během časového intervalu zadaného v renewal-period . Výraz zásad je povolený. Yes –
klíč čítače Klíč, který se má použít pro zásady omezení přenosové rychlosti. Yes –
increment-condition Logický výraz určující, jestli se má požadavek započítávat do rychlosti ( true ). No –
renewal-period Délka v sekundách posuvného okna, během kterého by počet povolených požadavků neměl překročit hodnotu zadanou v calls . Výraz zásad je povolený. Maximální povolená hodnota: 300 sekund. Yes –
retry-after-header-name Název hlavičky odpovědi, jejíž hodnota je doporučený interval opakování v sekundách po překročení zadané frekvence volání. No –
retry-after-variable-name Název proměnné výrazu zásad, která ukládá doporučený interval opakování v sekundách po překročení zadané frekvence volání. No –
remaining-calls-header-name Název hlavičky odpovědi, jejíž hodnota po každém spuštění zásady je počet zbývajících volání povolených pro časový interval zadaný v renewal-period . No –
remaining-calls-variable-name Název proměnné výrazu zásad, který po každém spuštění zásady ukládá počet zbývajících volání povolených pro časový interval zadaný v renewal-period . No –
total-calls-header-name Název hlavičky odpovědi, jejíž hodnota je hodnota zadaná v calls . No –

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

  • Oddíly zásad: příchozí

  • Obory zásad: všechny rozsahy

Omezení IP adres volajícího

ip-filterFiltry zásad (povolují/zakazuje) volání z konkrétních IP adres nebo rozsahů adres.

Prohlášení o zásadách

<ip-filter action="allow | forbid">
    <address>address</address>
    <address-range from="address" to="address" />
</ip-filter>

Příklad

V následujícím příkladu zásada povoluje pouze žádosti přicházející buď z jedné IP adresy, nebo z rozsahu zadaných IP adres.

<ip-filter action="allow">
    <address>13.66.201.169</address>
    <address-range from="13.66.140.128" to="13.66.140.143" />
</ip-filter>

Elementy

Název Popis Povinné
filtr IP adres Kořenový element. Yes
adresa Určuje jednu IP adresu, na které se má filtrovat. addressJe vyžadován alespoň jeden address-range prvek nebo.
adresový rozsah z = "adresa" na = "adresa" Určuje rozsah IP adres, na kterých se má filtrovat. addressJe vyžadován alespoň jeden address-range prvek nebo.

Atributy

Název Popis Povinné Výchozí
adresový rozsah z = "adresa" na = "adresa" Rozsah IP adres, pro které chcete povolit nebo odepřít přístup. Požadováno při address-range použití elementu. –
akce filtru IP = "povolení | zakázat" Určuje, jestli se mají u zadaných IP adres a rozsahů povolit volání. Yes –

Využití

Tyto zásady se dají použít v následujících oddílech a oborechzásad.

  • Oddíly zásad: příchozí
  • Obory zásad: všechny rozsahy

Nastavení kvóty využití podle předplatného

Tato quota zásada vynutila obnovitelné nebo maximální objem volání nebo kvótu šířky pásma na jednotlivých předplatných.

Důležité

Tato zásada se dá pro dokument zásad použít jenom jednou.

Výrazy zásad nelze použít v žádném z atributů zásad pro tuto zásadu.

Poznámka

Pro pochopení rozdílu mezi omezeními a kvótami získáte informace v části omezení přenosové rychlosti a kvóty.

Prohlášení o zásadách

<quota calls="number" bandwidth="kilobytes" renewal-period="seconds">
    <api name="API name" id="API id" calls="number" renewal-period="seconds" />
        <operation name="operation name" id="operation id" calls="number" renewal-period="seconds" />
    </api>
</quota>

Příklad

<policies>
    <inbound>
        <base />
        <quota calls="10000" bandwidth="40000" renewal-period="3600" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementy

Název Popis Povinné
kvóta Kořenový element. Yes
api Přidejte jeden nebo více těchto prvků pro uložení kvóty volání rozhraní API v rámci produktu. Kvóty volání produktů a rozhraní API se aplikují nezávisle. Na rozhraní API se dá odkazovat prostřednictvím name nebo id . Pokud jsou zadány oba atributy, budou id použity a name budou ignorovány. No
operation Přidejte jeden nebo více těchto prvků pro uložení kvóty volání operací v rámci rozhraní API. Kvóty volání produktů, rozhraní API a operací se aplikují nezávisle. Na operaci lze odkazovat prostřednictvím name nebo id . Pokud jsou zadány oba atributy, budou id použity a name budou ignorovány. No

Atributy

Název Popis Povinné Výchozí
name Název rozhraní API nebo operace, pro kterou platí kvóta. Yes –
připojení Maximální celkový počet kilobajtů povolený v časovém intervalu zadaném v renewal-period . calls bandwidth Musí být zadány oba, nebo oba současně. –
volání Maximální celkový počet volání povolených v časovém intervalu zadaném v renewal-period . calls bandwidth Musí být zadány oba, nebo oba současně. –
prodloužení platnosti – období Časové období v sekundách, po kterém se kvóta resetuje. Pokud je nastavená na 0 perioda, nastaví se na nekonečné. Yes –

Využití

Tyto zásady se dají použít v následujících oddílech a oborechzásad.

  • Oddíly zásad: příchozí
  • Obory zásad: produkt

Nastavit kvótu využití podle klíče

Důležité

Tato funkce není k dispozici v API Management úrovně spotřeby .

Tato quota-by-key zásada vynutila obnovitelné nebo maximální objem volání nebo kvótu šířky pásma na jednotlivých klíčích. Klíč může obsahovat libovolnou řetězcovou hodnotu a obvykle se poskytuje pomocí výrazu zásad. Můžete přidat volitelnou podmínku přírůstku, která určuje, které požadavky se mají do kvóty počítat. Pokud by více zásad mohl zvýšit stejnou hodnotu klíče, zvyšuje se pouze jednou za požadavek. Pokud je překročena rychlost volání, volající obdrží 403 Forbidden kód stavu odpovědi.

Další informace a příklady těchto zásad najdete v tématu Pokročilé omezování požadavků pomocí Azure API Management.

Poznámka

Pro pochopení rozdílu mezi omezeními a kvótami získáte informace v části omezení přenosové rychlosti a kvóty.

Prohlášení o zásadách

<quota-by-key calls="number"
              bandwidth="kilobytes"
              renewal-period="seconds"
              increment-condition="condition"
              counter-key="key value" />

Příklad

V následujícím příkladu je kvóta nastavena podle IP adresy volajícího.

<policies>
    <inbound>
        <base />
        <quota-by-key calls="10000" bandwidth="40000" renewal-period="3600"
                      increment-condition="@(context.Response.StatusCode >= 200 && context.Response.StatusCode < 400)"
                      counter-key="@(context.Request.IpAddress)" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementy

Název Popis Povinné
kvóta Kořenový element. Yes

Atributy

Název Popis Povinné Výchozí
připojení Maximální celkový počet kilobajtů povolený v časovém intervalu zadaném v renewal-period . calls bandwidth Musí být zadány oba, nebo oba současně. –
volání Maximální celkový počet volání povolených v časovém intervalu zadaném v renewal-period . calls bandwidth Musí být zadány oba, nebo oba současně. –
Counter – klíč Klíč, který se má použít pro zásady kvót Yes –
přírůstek-podmínka Logický výraz určující, zda má být požadavek počítán k kvótě ( true ) No –
prodloužení platnosti – období Časové období v sekundách, po kterém se kvóta resetuje. Pokud je nastavená na 0 perioda, nastaví se na nekonečné. Yes –

Poznámka

counter-keyHodnota atributu musí být jedinečná napříč všemi rozhraními API ve API Management, pokud nechcete sdílet součet mezi ostatními rozhraními API.

Využití

Tyto zásady se dají použít v následujících oddílech a oborechzásad.

  • Oddíly zásad: příchozí
  • Obory zásad: všechny rozsahy

Ověřit token JWT

validate-jwtZásady vynutily existenci a platnost tokenu JWT (JSON web token) extrahované ze zadané HLAVIČKY http nebo zadaného parametru dotazu.

Důležité

Tato validate-jwt zásada vyžaduje, aby exp registrovaná deklarace identity byla obsažena v tokenu JWT, pokud require-expiration-time není zadána vlastnost a nastavena na false . Tato validate-jwt zásada podporuje algoritmy podepisování HS256 a RS256. Pro HS256 musí být klíč poskytnutý jako vložený v rámci zásady ve formě kódované v kódování Base64. Pro RS256 může být klíč poskytnutý buď prostřednictvím koncového bodu konfigurace otevřeného ID, nebo zadáním ID nahraného certifikátu, který obsahuje veřejný klíč nebo dvojici exponentu veřejného klíče. validate-jwtZásady podporují tokeny šifrované pomocí symetrických klíčů pomocí následujících šifrovacích algoritmů: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.

Prohlášení o zásadách

<validate-jwt
    header-name="name of http header containing the token (use query-parameter-name attribute if the token is passed in the URL)"
    failed-validation-httpcode="http status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    token-value="expression returning JWT token as a string"
    require-expiration-time="true|false"
    require-scheme="scheme"
    require-signed-tokens="true|false"
    clock-skew="allowed clock skew in seconds"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
  <openid-config url="full URL of the configuration endpoint, e.g. https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </decryption-keys>
  <audiences>
    <audience>audience string</audience>
    <!-- if there are multiple possible audiences, then add additional audience elements -->
  </audiences>
  <issuers>
    <issuer>issuer string</issuer>
    <!-- if there are multiple possible issuers, then add additional issuer elements -->
  </issuers>
  <required-claims>
    <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
      <value>claim value as it is expected to appear in the token</value>
      <!-- if there is more than one allowed values, then add additional value elements -->
    </claim>
    <!-- if there are multiple possible allowed values, then add additional value elements -->
  </required-claims>
</validate-jwt>

Příklady

Ověřování jednoduchých tokenů

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key>  <!-- signing key specified as a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Ověřování tokenu pomocí certifikátu RSA

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key certificate-id="my-rsa-cert" />  <!-- signing key specified as certificate ID, enclosed in double-quotes -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

ověřování tokenu Azure Active Directory

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" />
    <audiences>
        <audience>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Azure Active Directory Ověření tokenu B2C

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>d313c4e4-de5f-4197-9470-e509a2f0b806</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Autorizace přístupu k operacím na základě deklarací identity tokenů

Tento příklad ukazuje, jak použít zásadu ověření JWT k autorizaci přístupu k operacím na základě hodnoty deklarací identity tokenu.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
</validate-jwt>
<choose>
    <when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
        <return-response>
            <set-status code="403" reason="Forbidden" />
        </return-response>
    </when>
</choose>

Elementy

Element Popis Povinné
ověřit – JWT Kořenový element. Yes
publikum Obsahuje seznam přijatelných deklarací cílové skupiny, které mohou být k dispozici na tokenu. Pokud je přítomno více hodnot cílové skupiny, pak se každá hodnota vyzkouší, dokud nebudou vyčerpány všechny (v takovém případě ověření selže) nebo dokud jeden neuspěje. Je nutné zadat alespoň jednu cílovou skupinu. No
Vystavitel – podpisové klíče Seznam klíčů zabezpečení kódovaných v kódování Base64 používaných k ověřování podepsaných tokenů. Pokud je k dispozici více klíčů zabezpečení, pak se každý klíč vyzkouší, dokud nebudou vyčerpány všechny (v takovém případě selže ověřování) nebo jedna úspěšná (užitečná pro výměnu tokenu). Klíčové prvky mají volitelný id atribut, který se používá pro porovnání s kid deklarací identity.

Případně zadejte podpisový klíč vystavitele pomocí:

- certificate-id v části formát <key certificate-id="mycertificate" /> Zadejte identifikátor entity certifikátu nahrané do API Management
– n Páry a exponenty RSA e ve formátu <key n="<modulus>" e="<exponent>" /> pro určení parametrů RSA ve formátu kódovaném v base64url		 No
dešifrování – klíče Seznam klíčů zakódovaných ve formátu base64, které slouží k dešifrování tokenů. Pokud je k dispozici více klíčů zabezpečení, pak se každý klíč vyzkouší, dokud nebudou vyčerpány všechny klíče (v takovém případě ověření selže) nebo je klíč úspěšný. Klíčové prvky mají volitelný id atribut, který se používá pro porovnání s kid deklarací identity.

Případně zadejte dešifrovací klíč pomocí:

- certificate-id v části formát <key certificate-id="mycertificate" /> Zadejte identifikátor entity certifikátu nahrané do API Management		 No
vystavitelů Seznam přijatelných objektů zabezpečení, které token vystavily. Pokud je přítomno více hodnot vystavitelů, pak se každá hodnota vyzkouší, dokud nejsou vyčerpány všechny (v takovém případě ověření selže) nebo dokud jeden neuspěje. No
OpenID-config Prvek použitý k zadání koncového bodu konfigurace kompatibilního otevřeného ID, ze kterého lze získat podpisové klíče a vystavitele. No
požadováno – deklarace identity Obsahuje seznam deklarací identity, které mají být přítomny na tokenu, aby se dalo považovat za platný. Pokud match je atribut nastavený na all hodnotu každá hodnota deklarace v zásadě, musí být v tokenu přítomná, aby bylo ověření úspěšné. Pokud match je atribut nastaven na any alespoň jednu deklaraci identity, musí být v tokenu přítomen, aby bylo ověření úspěšné. No

Atributy

Název Popis Povinné Výchozí
hodiny – zkosit TimeSpan. Slouží k určení maximálního očekávaného časového rozdílu mezi systémovými hodinami vystavitele tokenu a API Management instancí. No 0 sekund
failed-validation-error-message Chybová zpráva, která se má vrátit v textu odpovědi HTTP, pokud JWT neprojde ověřením. Tato zpráva musí obsahovat všechny speciální znaky, které jsou správně uvozeny. No Výchozí chybová zpráva závisí na problému s ověřením, například na tom, že není k dispozici JWT.
failed-validation-httpcode Stavový kód HTTP, který se má vrátit, pokud JWT neprojde ověřením. No 401
header-name (název hlavičky) Název hlavičky HTTP, ve které je token. Je nutné header-name query-parameter-name token-value zadat jednu z hodnot nebo . –
query-parameter-name Název parametru dotazu, který token obsahuje. Je nutné header-name query-parameter-name token-value zadat jednu z hodnot nebo . –
hodnota tokenu Výraz vracející řetězec obsahující token JWT. Jako součást hodnoty tokenu se nesmí Bearer vracet. Je nutné header-name query-parameter-name token-value zadat jednu z hodnot nebo . –
id Atribut v elementu umožňuje zadat řetězec, který se bude shodovat s deklarací identity v tokenu (pokud je k dispozici), abyste zjistili vhodný klíč, který se má použít pro id key ověření kid podpisu. No –
match Atribut elementu určuje, jestli musí být každá hodnota deklarace identity v zásadách přítomná v tokenu, aby match claim ověření bylo úspěšné. Možné hodnoty:

- all – Každá hodnota deklarace identity v zásadách musí být v tokenu, aby ověření bylo úspěšné.

- any – Token musí obsahovat alespoň jednu hodnotu deklarace identity, aby ověření bylo úspěšné.		 No Vše
vyžadovat čas vypršení platnosti Boolean. Určuje, jestli token vyžaduje deklaraci identity vypršení platnosti. No true
require-scheme (schéma vyžadování) Název schématu tokenu, například "Bearer". Když je tento atribut nastavený, zásada zajistí, že se zadané schéma nachází v hodnotě autorizační hlavičky. No –
vyžadování podepsaných tokenů Boolean. Určuje, jestli musí být token podepsaný. No true
Oddělovač Řetězec. Určuje oddělovač (např. ","), který se použije k extrahování sady hodnot z deklarace identity s více hodnotami. No –
url Open ID configuration endpoint URL from where Open ID configuration metadata can be obtained. Odpověď by měla být podle specifikací definovaných na adrese URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata . Například Azure Active Directory následující adresu URL: https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration nahraďte názvem tenanta adresáře, například contoso.onmicrosoft.com . Yes –
output-token-variable-name Řetězec. Název kontextové proměnné, která při úspěšném ověření tokenu obdrží hodnotu tokenu jako objekt Jwt typu No –

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

  • Oddíly zásad: příchozí
  • Obory zásad: všechny obory

Ověření klientského certifikátu

Pomocí zásad vynucovat, aby certifikát prezentované klientem instanci API Management odpovídal zadaným ověřovacím pravidlům a deklaraci identity, jako je předmět nebo vystavitel pro jednu nebo více validate-client-certificate identit certifikátů.

Aby byl klientský certifikát považován za platný, musí odpovídat všem ověřovacím pravidlům definovaným atributy v elementu nejvyšší úrovně a musí odpovídat všem definovaným deklaracem identity alespoň pro jednu z definovaných identit.

Pomocí této zásady můžete kontrolovat vlastnosti příchozího certifikátu oproti požadovaným vlastnostem. Tuto zásadu použijte také k přepsání výchozího ověřování klientských certifikátů v těchto případech:

  • Pokud jste nahráli vlastní certifikáty certifikační autority pro ověření požadavků klientů na spravovanou bránu
  • Pokud jste nakonfigurovali vlastní certifikační autority pro ověřování požadavků klientů na bránu spravovanou své držitelem

Další informace o vlastních certifikátech certifikační autority a certifikačních autoritách najdete v tématu Postup přidání vlastního certifikátu certifikační autority v Azure API Management.

Prohlášení o zásadách

<validate-client-certificate 
    validate-revocation="true|false"
    validate-trust="true|false" 
    validate-not-before="true|false" 
    validate-not-after="true|false" 
    ignore-error="true|false">
    <identities>
        <identity 
            thumbprint="certificate thumbprint"
            serial-number="certificate serial number"
            common-name="certificate common name"
            subject="certificate subject string"
            dns-name="certificate DNS name"
            issuer-subject="certificate issuer"
            issuer-thumbprint="certificate issuer thumbprint"
            issuer-certificate-id="certificate identifier" />
    </identities>
</validate-client-certificate>

Příklad

Následující příklad ověří klientský certifikát tak, aby odpovídal výchozím ověřovacím pravidlům zásad, a zkontroluje, jestli předmět a název vystavitele odpovídají zadaným hodnotám.

<validate-client-certificate 
    validate-revocation="true" 
    validate-trust="true" 
    validate-not-before="true" 
    validate-not-after="true" 
    ignore-error="false">
    <identities>
        <identity
            subject="C=US, ST=Illinois, L=Chicago, O=Contoso Corp., CN=*.contoso.com"
            issuer-subject="C=BE, O=FabrikamSign nv-sa, OU=Root CA, CN=FabrikamSign Root CA" />
    </identities>
</validate-client-certificate>

Elementy

Element Popis Povinné
validate-client-certificate Kořenový element. Yes
Identit Obsahuje seznam identit s definovanými deklaracemi identity v klientském certifikátu. No

Atributy

Název Popis Povinné Výchozí
ověření odvolání  Boolean. Určuje, jestli se má certifikát ověřit proti seznamu odvolaných certifikátů online.  ne  Ano
ověření důvěryhodnosti  Boolean. Určuje, jestli má ověření selhat v řetězu případů, které nelze úspěšně vytvořit pro důvěryhodnou certifikační autoritu. ne Ano
validate-not-before Boolean. Ověří hodnotu proti aktuálnímu času. ne  Ano
ověření ne po  Boolean. Ověří hodnotu proti aktuálnímu času. ne  Ano
ignore-error  Boolean. Určuje, jestli má zásada pokračovat na další obslužnou rutinu nebo přejít na chybu při neúspěšných ověřeních. ne Ne
identity Řetězec. Kombinace hodnot deklarací identity certifikátu, které dělají certifikát platným. ano –
Miniatura Kryptografický otisk certifikátu. ne –
sériové číslo Sériové číslo certifikátu. ne –
běžný název Běžný název certifikátu (část řetězce předmětu). ne –
subject Řetězec předmětu. Musí dodržovat formát Rozlišující název. ne –
název dns Hodnota položky dnsName uvnitř deklarace identity Alternativní název subjektu. ne –
vystavitel předmětu Předmět vystavitele. Musí dodržovat formát Rozlišující název. ne –
kryptografický otisk vystavitele Kryptografický otisk vystavitele. ne –
issuer-certificate-id Identifikátor existující entity certifikátu představující veřejný klíč vystavitele Vzájemně se vylučují s jinými atributy vystavitele. ne –

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

  • Oddíly zásad: příchozí
  • Obory zásad: všechny obory

Další kroky

Další informace o práci se zásadami najdete v těchto tématu: