Ověření JWT

  • Článek

PLATÍ PRO: Všechny úrovně služby API Management

Zásada validate-jwt vynucuje existenci a platnost podporovaného webového tokenu JSON (JWT) extrahovaného ze zadané hlavičky HTTP, extrahovaného ze zadaného parametru dotazu nebo odpovídající konkrétní hodnoty.

Poznámka:

K ověření JWT poskytované službou Microsoft Entra poskytuje validate-azure-ad-token služba API Management také zásady.

Poznámka:

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Portál poskytuje průvodce editorem založeným na formulářích, který vám pomůže s konfigurací této zásady. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady služby API Management.

Prohlášení o zásadách

<validate-jwt
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    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, for example, https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent"</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent" </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 value, then add additional value elements -->
    </claim>
    <!-- if there are multiple possible allowed claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

Atributy

Atribut Popis Požaduje se Výchozí
header-name Název hlavičky HTTP, která token drží. Výrazy zásad jsou povolené. Jedna z hodnot header-namenebo token-valuequery-parameter-name musí být zadána. –
název parametru dotazu Název parametru dotazu, který obsahuje token. Výrazy zásad jsou povolené. Jedna z hodnot header-namenebo token-valuequery-parameter-name musí být zadána. –
hodnota tokenu Výraz vracející řetězec obsahující token V rámci hodnoty tokenu nesmíte vracet Bearer . Výrazy zásad jsou povolené. Jedna z hodnot header-namenebo token-valuequery-parameter-name musí být zadána. –
failed-validation-httpcode Stavový kód HTTP, který se má vrátit, pokud JWT neprojde ověřením. Výrazy zásad jsou povolené. No 401
failed-validation-error-message Chybová zpráva, která se vrátí 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ě uchycené. Výrazy zásad jsou povolené. No Výchozí chybová zpráva závisí na problému s ověřením, například "JWT není k dispozici".
require-expiration-time Logický. Určuje, jestli se v tokenu vyžaduje deklarace identity vypršení platnosti. Výrazy zásad jsou povolené. No true
vyžadovat schéma Název schématu tokenů, například "Bearer". Pokud je tento atribut nastaven, zásada zajistí, že zadané schéma je k dispozici v hodnotě autorizační hlavičky. Výrazy zásad jsou povolené. No –
require-signed-tokens Logický. Určuje, jestli se vyžaduje podepsání tokenu. Výrazy zásad jsou povolené. No true
nerovnoměrná distribuce hodin Timespan. Slouží k určení maximálního očekávaného časového rozdílu mezi systémovými hodinami vystavitele tokenu a instancí služby API Management. Výrazy zásad jsou povolené. No 0 sekund
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 typu Jwt . Výrazy zásad nejsou povolené. No –

Elementy

Element (Prvek) Popis Povinní účastníci
openid-config Přidejte jeden nebo více těchto prvků, abyste zadali adresu URL koncového bodu konfigurace OpenID, ze které se dají získat podpisové klíče a vystavitele.

Konfigurace včetně sady webových klíčů JSON (JWKS) se načte z koncového bodu každých 1 hodinu a ukládá se do mezipaměti. Pokud ověřovaný token odkazuje na ověřovací klíč (pomocí kid deklarace identity), který chybí v konfiguraci v mezipaměti nebo pokud se načtení nezdaří, služba API Management načítá z koncového bodu maximálně jednou za 5 minut. Tyto intervaly se můžou bez předchozího upozornění změnit.

Odpověď by měla být v souladu se specifikacemi definovanými na adrese URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

V případě ID Microsoft Entra použijte koncový bod metadat OpenID Připojení nakonfigurovaný v registraci vaší aplikace, například:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
– v2 s více tenanty https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
– Tenant zákazníka (Preview) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Nahraďte název nebo ID vašeho tenanta adresáře, například contoso.onmicrosoft.com.{tenant-name}		 No
issuer-signing-keys Seznam klíčů zabezpečení s kódováním Base64 v key dílčích počtech, které slouží k ověření podepsaných tokenů. Pokud existuje více klíčů zabezpečení, pak se každý klíč pokusí, dokud se nevyčerpají všechny klíče (v takovém případě se ověření nezdaří) nebo jeden úspěšný (užitečný pro vrácení tokenu).

Volitelně můžete zadat klíč pomocí atributu id , který odpovídá kid deklaraci identity. Pokud chcete ověřit token podepsaný asymetrickým klíčem, volitelně zadejte veřejný klíč pomocí certificate-id atributu s hodnotou identifikátoru certifikátu nahraného do služby API Management nebo modulu RSA n a exponent e páru podpisového klíče ve formátu kódování Base64url.		 No
dešifrovací klíče Seznam klíčů s kódováním Base64 v key dílčích poplatcích, který se používá k dešifrování tokenů. Pokud existuje více klíčů zabezpečení, pak se každý klíč pokusí, dokud se nevyčerpají všechny klíče (v takovém případě ověření selže) nebo se klíč úspěšně nezdaří.

Volitelně můžete zadat klíč pomocí atributu id , který odpovídá kid deklaraci identity. Pokud chcete dešifrovat token šifrovaný asymetrickým klíčem, volitelně zadejte veřejný klíč pomocí certificate-id atributu s hodnotou identifikátoru certifikátu nahraného do služby API Management nebo modulu RSA n a exponent e pár klíče ve formátu kódování Base64url.		 No
Publikum Seznampřijatelnýchch audience Pokud existuje více hodnot cílové skupiny, pak se každá hodnota pokusí, dokud se nevyčerpají všechny hodnoty (v takovém případě se ověření nezdaří) nebo dokud se jedna nezdaří. Musí být zadána alespoň jedna cílová skupina. No
Emitentů Seznampřijatelných objektů v issuer dílčích posadcích, které token vystavily. Pokud existuje více hodnot vystavitele, je každá hodnota vyzkoušena, dokud se nevyčerpají všechny hodnoty (v takovém případě ověření selže) nebo dokud se jedna nezdaří. No
required-claims Očekává se, že seznam deklarací identity v claim dílčích posadcích bude v tokenu považován za platný. Pokud existuje více deklarací identity, musí token odpovídat hodnotám deklarace identity podle hodnoty atributu match . No

klíčové atributy

Atribut Popis Požaduje se Výchozí
ID Řetězec. Identifikátor použitý ke shodě kid deklarace identity prezentované v JWT. No –
id certifikátu Identifikátor entity certifikátu nahrané do služby API Management, který slouží k zadání veřejného klíče k ověření tokenu podepsaného asymetrickým klíčem. No –
n Moduly veřejného klíče použitého k ověření vystavitele tokenu podepsaného asymetrickým klíčem Musí být zadán s hodnotou exponentu e. Výrazy zásad nejsou povolené. No –
e Exponent veřejného klíče použitého k ověření vystavitele tokenu podepsaného asymetrickým klíčem. Musí být zadán s hodnotou modulus n. Výrazy zásad nejsou povolené. No –

atributy deklarace identity

Atribut Popis Požaduje se Výchozí
match Atribut match elementu claim určuje, zda každá hodnota deklarace identity v zásadě musí být přítomna v tokenu, aby bylo ověření úspěšné. Možné hodnoty jsou:

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

- any – v tokenu musí existovat alespoň jedna hodnota deklarace identity, aby bylo ověření úspěšné.		 No vše
Oddělovač Řetězec. Určuje oddělovač (například ","), který se má použít k extrahování sady hodnot z deklarace identity s více hodnotami. No –

Využití

Poznámky k využití

  • Zásada validate-jwt vyžaduje, aby exp zaregistrovaná deklarace identity byla zahrnuta v tokenu JWT, pokud require-expiration-time není atribut zadán a nastaven na falsehodnotu .
  • Tato zásada podporuje symetrické i asymetrické podpisové algoritmy:
    • Symetrické – Podporují se následující šifrovací algoritmy: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • Pokud se tento klíč používá v zásadě, musí být vložený v rámci zásady ve formuláři kódovaném v base64.
    • Asymetrické – Podporují se následující algortithmy šifrování: PS256, RS256, RS512.
      • Pokud se tento klíč používá v zásadách, může se zadat buď prostřednictvím koncového bodu konfigurace OpenID, nebo zadáním ID nahraného certifikátu (ve formátu PFX), který obsahuje veřejný klíč, nebo dvojice exponentů modulus-exponent veřejného klíče.
  • Pokud chcete zásadu nakonfigurovat s jedním nebo několika koncovými body konfigurace OpenID pro použití s bránou v místním prostředí, musí být adresy URL koncových bodů konfigurace OpenID dostupné také pro cloudovou bránu.
  • 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í Microsoft Entra použitím validate-jwt zásad na úrovni rozhraní API nebo ho můžete použít na úrovni operace rozhraní API a použít claims ho k podrobnějšímu řízení.
  • Při použití vlastní hlavičky (header-name) bude nakonfigurované požadované schéma (require-scheme) ignorováno. Pokud chcete použít požadované schéma, musí být v hlavičce zadané Authorization tokeny JWT.

Příklady

Ověření jednoduchého tokenu

<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ěření 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ěření tokenu jednoho tenanta Microsoft Entra ID

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

Ověření tokenu tenanta zákazníka Microsoft Entra ID

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
	<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
	<required-claims>
		<claim name="azp" match="all">
			<value>insert claim here</value>
		</claim>
	</required-claims>
</validate-jwt>

Ověřování tokenu B2C v 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/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 pomocí validate-jwt zásad autorizovat přístup 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>

Související obsah

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