JWT ellenőrzése

  • Cikk

A KÖVETKEZŐRE VONATKOZIK: Minden API Management-szint

A validate-jwt szabályzat kikényszeríti a megadott HTTP-fejlécből kinyert, egy adott lekérdezési paraméterből kinyert vagy egy adott értéknek megfelelő támogatott JSON-webes jogkivonat (JWT) meglétét és érvényességét.

Feljegyzés

A Microsoft Entra szolgáltatás által biztosított JWT érvényesítéséhez az API Management a szabályzatot validate-azure-ad-token is biztosítja.

Feljegyzés

Állítsa be a szabályzat elemeit és gyermekelemeit a szabályzatutasításban megadott sorrendben. A szabályzat konfigurálásához a portál egy irányított, űrlapalapú szerkesztőt biztosít. További információ az API Management-szabályzatok beállításáról és szerkesztéséről.

Szabályzatutasítás

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

Attribútumok

Attribútum Leírás Kötelező Alapértelmezett
fejléc neve A jogkivonatot tartalmazó HTTP-fejléc neve. A szabályzatkifejezések engedélyezettek. Az egyiket header-namemeg kell adni, query-parameter-name vagy token-value meg kell adni. n/a
query-parameter-name A jogkivonatot tartalmazó lekérdezési paraméter neve. A szabályzatkifejezések engedélyezettek. Az egyiket header-namemeg kell adni, query-parameter-name vagy token-value meg kell adni. n/a
token-value A jogkivonatot tartalmazó sztringet visszaadó kifejezés. A jogkivonat értékeként nem térhet vissza Bearer . A szabályzatkifejezések engedélyezettek. Az egyiket header-namemeg kell adni, query-parameter-name vagy token-value meg kell adni. n/a
failed-validation-httpcode HTTP-állapotkód visszaadása, ha a JWT nem felel meg az ellenőrzésnek. A szabályzatkifejezések engedélyezettek. Nem 401
failed-validation-error-message Hibaüzenet jelenik meg a HTTP válasz törzsében, ha a JWT nem felel meg az ellenőrzésnek. Ennek az üzenetnek megfelelően kell tartalmaznia a speciális karaktereket. A szabályzatkifejezések engedélyezettek. Nem Az alapértelmezett hibaüzenet az érvényesítési problémától függ, például a "JWT nincs jelen".
lejárati idő megkövetelése Logikai. Megadja, hogy szükség van-e lejárati jogcímre a jogkivonatban. A szabályzatkifejezések engedélyezettek. Nem true
kötelező séma A jogkivonat-séma neve, például "Tulajdonos". Ha ez az attribútum be van állítva, a szabályzat biztosítja, hogy a megadott séma szerepel-e az Engedélyezési fejléc értékében. A szabályzatkifejezések engedélyezettek. Nem N.A.
kötelező aláírt jogkivonatok Logikai. Megadja, hogy szükség van-e jogkivonat aláírására. A szabályzatkifejezések engedélyezettek. Nem true
óra-ferdeség Időbélyeg. A tokenkibocsátó és az API Management-példány rendszerórái közötti maximális várható időkülönbség megadására használható. A szabályzatkifejezések engedélyezettek. Nem 0 másodperc
output-token-variable-name Karakterlánc. Annak a környezeti változónak a neve, amely a jogkivonat értékét típusobjektumként Jwt kapja meg a sikeres jogkivonat-ellenőrzéskor. A szabályzatkifejezések nem engedélyezettek. Nem N.A.

Elemek

Elem Leírás Kötelező
openid-config Adjon hozzá egy vagy több ilyen elemet a megfelelő OpenID konfigurációs végpont URL-címének megadásához, amelyből az aláíró kulcsok és a kiállító lekérthetők.

A JSON webkulcskészletet (JWKS) is tartalmazó konfigurációt 1 óránként lekérte a rendszer a végpontról, és gyorsítótárazza. Ha az érvényesítendő jogkivonat egy olyan érvényesítési kulcsra hivatkozik (jogcím használatával kid ), amely hiányzik a gyorsítótárazott konfigurációban, vagy ha a lekérés sikertelen, az API Management legfeljebb 5 percenként egyszer lekéri a végpontot. Ezek az intervallumok értesítés nélkül változhatnak.

A válasznak a következő URL-címen megadott specifikációknak kell lennie: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

Microsoft Entra-azonosító esetén használja az alkalmazásregisztrációban konfigurált OpenID Csatlakozás metaadat-végpontot, például:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- v2 több-bérlős https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
- Ügyfélbérlelő (előzetes verzió) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

A címtár-bérlő nevének vagy azonosítójának helyettesítése például contoso.onmicrosoft.com: {tenant-name}.		 Nem
kiállítói aláírási kulcsok A Base64 kódolású biztonsági kulcsok listája alelemekben key , az aláírt jogkivonatok ellenőrzésére. Ha több biztonsági kulcs is található, a rendszer minden kulcsot megpróbál, amíg az összes ki nem merül (ebben az esetben az érvényesítés sikertelen), vagy sikeres lesz (a tokenek átállításához hasznos).

Igény szerint megadhat egy kulcsot az id attribútum használatával egy jogcímnek kid megfelelően. Az aszimmetrikus kulccsal aláírt jogkivonat érvényesítéséhez opcionálisan adja meg a nyilvános kulcsot egy certificate-id olyan attribútummal, amely az API Managementbe feltöltött tanúsítvány azonosítóját, vagy az aláírókulcs RSA modulusát n és kitevő e párját Base64url-kódolású formátumban adja meg.		 Nem
visszafejtési kulcsok A base64 kódolású kulcsok listája alelemekben key , a jogkivonatok visszafejtéséhez. Ha több biztonsági kulcs is található, akkor a rendszer mindaddig próbálkozik, amíg az összes kulcs ki nem merül (ebben az esetben az érvényesítés sikertelen), vagy egy kulcs sikeres lesz.

Igény szerint megadhat egy kulcsot az id attribútum használatával egy jogcímnek kid megfelelően. Az aszimmetrikus kulccsal titkosított jogkivonat visszafejtéséhez adja meg a nyilvános kulcsot egy certificate-id olyan attribútummal, amely az API Managementbe feltöltött tanúsítvány azonosítóját, vagy a kulcs RSA modulusát n és kitevő e párját Base64url-kódolású formátumban adja meg.		 Nem
Közönség A jogkivonaton elérhető elfogadható célközönség-jogcímek listája alelemekben audience . Ha több célközönségérték van jelen, akkor a rendszer mindaddig próbálkozik, amíg az összes ki nem merül (ebben az esetben az érvényesítés sikertelen), vagy amíg az egyik sikeres nem lesz. Legalább egy célközönséget meg kell adni. Nem
Kibocsátók A jogkivonatot kibocsátó elfogadható tagok listája alelemekben issuer . Ha több kiállítói érték van jelen, akkor a rendszer mindaddig próbálkozik, amíg az összes ki nem merül (ebben az esetben az ellenőrzés sikertelen), vagy amíg az egyik sikeres nem lesz. Nem
kötelező jogcímek Az alelemekben található claim jogcímek listája, amely várhatóan érvényesnek tekinthető a jogkivonaton. Ha több jogcím van jelen, a jogkivonatnak meg kell egyeznie a jogcímértékekkel az match attribútum értéke szerint. Nem

kulcsattribútumok

Attribútum Leírás Kötelező Alapértelmezett
id Karakterlánc. A JWT-ben bemutatott jogcímek egyeztetéséhez kid használt azonosító. Nem N.A.
tanúsítványazonosító Az API Managementbe feltöltött tanúsítványentitás azonosítója, amely a nyilvános kulcs megadására szolgál az aszimmetrikus kulccsal aláírt jogkivonat ellenőrzéséhez. Nem N.A.
n Az aszimmetrikus kulccsal aláírt jogkivonat kiállítójának ellenőrzéséhez használt nyilvános kulcs modulusa. A kitevő eértékével kell megadni. A szabályzatkifejezések nem engedélyezettek. Nem N.A.
e Az aszimmetrikus kulccsal aláírt jogkivonat kiállítójának ellenőrzéséhez használt nyilvános kulcs kitevője. A modulus nértékével kell megadni. A szabályzatkifejezések nem engedélyezettek. Nem N.A.

jogcímattribútumok

Attribútum Leírás Kötelező Alapértelmezett
Mérkőzés Az match elem attribútuma claim azt határozza meg, hogy a szabályzat minden jogcímértékének szerepelnie kell-e a jogkivonatban az ellenőrzés sikerességéhez. A lehetséges értékek a következők:

- all - a szabályzat minden jogcímértékének szerepelnie kell a jogkivonatban az ellenőrzés sikerességéhez.

- any - legalább egy jogcímértéknek szerepelnie kell a jogkivonatban az ellenőrzés sikerességéhez.		 Nem mind
Elválasztó Karakterlánc. Egy elválasztót (például ",") ad meg, amely egy többértékű jogcímből származó értékkészlet kinyeréséhez használható. Nem N.A.

Használat

Használati megjegyzések

  • A validate-jwt szabályzat megköveteli, hogy a exp regisztrált jogcím szerepeljen a JWT-jogkivonatban, kivéve, ha require-expiration-time az attribútum meg van adva, és a beállítás értéke false.
  • A szabályzat szimmetrikus és aszimmetrikus aláíró algoritmusokat is támogat:
    • Szimmetrikus – A következő titkosítási algoritmusok támogatottak: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • Ha a szabályzatban használják, a kulcsot a base64 kódolású űrlapon kell megadni a szabályzaton belül.
    • Aszimmetrikus – A következő titkosítási algoritmusok támogatottak: PS256, RS256, RS512.
      • Ha a szabályzatban használják, a kulcs egy OpenID konfigurációs végponton keresztül, vagy a nyilvános kulcsot tartalmazó feltöltött tanúsítvány azonosítójának (PFX formátumban) vagy a nyilvános kulcs modulus-kitevő párjának megadásával adható meg.
  • Ha a szabályzatot egy vagy több OpenID-konfigurációs végponttal szeretné konfigurálni saját üzemeltetésű átjáróval való használatra, az OpenID konfigurációs végpontok URL-címeinek a felhőátjárónak is elérhetőnek kell lenniük.
  • A hozzáférés-korlátozási szabályzatokat különböző hatókörökben, különböző célokra használhatja. Például a teljes API-t biztonságossá teheti a Microsoft Entra-hitelesítéssel a szabályzat API-szinten történő alkalmazásával validate-jwt , vagy alkalmazhatja az API-művelet szintjén, és részletesebb vezérlésre használhatja claims .
  • Egyéni fejléc (header-name) használatakor a rendszer figyelmen kívül hagyja a konfigurált szükséges sémát (require-scheme). A szükséges séma használatához JWT-jogkivonatokat kell megadni a Authorization fejlécben.

Példák

Egyszerű jogkivonat érvényesítése

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

Jogkivonat érvényesítése RSA-tanúsítvánnyal

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

Microsoft Entra ID egyetlen bérlői jogkivonat érvényesítése

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

Microsoft Entra ID ügyfél-bérlői jogkivonat érvényesítése

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

Azure Active Directory B2C-jogkivonat érvényesítése

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

Műveletekhez való hozzáférés engedélyezése jogkivonat-jogcímek alapján

Ez a példa bemutatja, hogyan engedélyezheti a jogkivonat jogcímértékén alapuló műveletekhez való hozzáférést a validate-jwt szabályzat használatával.

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

Kapcsolódó tartalom

A szabályzatok használatával kapcsolatos további információkért lásd: