Verifiera JWT

  • Artikel

GÄLLER FÖR: Alla API Management-nivåer

Principen validate-jwt framtvingar existens och giltighet för en JSON-webbtoken (JWT) som stöds som extraheras från ett angivet HTTP-huvud, extraheras från en angiven frågeparameter eller matchar ett visst värde.

Kommentar

Api Management tillhandahåller validate-azure-ad-token även principen för att verifiera en JWT som tillhandahölls av Microsoft Entra-tjänsten.

Kommentar

Ange principens element och underordnade element i den ordning som anges i principbeskrivningen. För att hjälpa dig att konfigurera den här principen tillhandahåller portalen en guidad, formulärbaserad redigerare. Läs mer om hur du anger eller redigerar API Management-principer.

Principuttryck

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

Attribut

Attribut beskrivning Obligatoriskt Standardvärde
rubriknamn Namnet på HTTP-huvudet som innehåller token. Principuttryck tillåts. En av header-name, query-parameter-name eller token-value måste anges. Ej tillämpligt
query-parameter-name Namnet på frågeparametern som innehåller token. Principuttryck tillåts. En av header-name, query-parameter-name eller token-value måste anges. Ej tillämpligt
token-value Uttryck som returnerar en sträng som innehåller token. Du får inte returnera Bearer som en del av tokenvärdet. Principuttryck tillåts. En av header-name, query-parameter-name eller token-value måste anges. Ej tillämpligt
failed-validation-httpcode HTTP-statuskod som returneras om JWT inte klarar valideringen. Principuttryck tillåts. Nej 401
failed-validation-error-message Felmeddelande om att returnera i HTTP-svarstexten om JWT inte klarar valideringen. Det här meddelandet måste ha undantagna specialtecken. Principuttryck tillåts. Nej Standardfelmeddelandet beror på valideringsproblem, till exempel "JWT finns inte".
require-expiration-time Boolesk. Anger om ett förfalloanspråk krävs i token. Principuttryck tillåts. Nej true
require-scheme Namnet på tokenschemat, till exempel "Bearer". När det här attributet har angetts ser principen till att det angivna schemat finns i värdet auktoriseringshuvud. Principuttryck tillåts. Nej Ej tillämpligt
require-signed-tokens Boolesk. Anger om en token måste signeras. Principuttryck tillåts. Nej true
klocksnedställning Gått. Använd för att ange maximal förväntad tidsskillnad mellan systemklockorna för token utfärdaren och API Management-instansen. Principuttryck tillåts. Nej 0 sekunder
output-token-variable-name Sträng. Namn på kontextvariabel som ska ta emot tokenvärde som ett objekt av typen Jwt vid lyckad tokenverifiering. Principuttryck tillåts inte. Nej Ej tillämpligt

Element

Element Description Obligatoriskt
openid-config Lägg till ett eller flera av dessa element för att ange en kompatibel OpenID-konfigurationsslutpunkts-URL från vilken signeringsnycklar och utfärdare kan hämtas.

Konfiguration inklusive JSON-webbnyckeluppsättningen (JWKS) hämtas från slutpunkten var 1 timme och cachelagras. Om token som verifieras refererar till en valideringsnyckel (med anspråk kid ) som saknas i cachelagrad konfiguration, eller om hämtningen misslyckas, hämtar API Management från slutpunkten högst en gång per 5 min. Dessa intervall kan komma att ändras utan föregående meddelande.

Svaret ska vara enligt specifikationerna som definieras i URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

För Microsoft Entra-ID använder du openID-Anslut metadataslutpunkten som konfigurerats i din appregistrering, till exempel:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
– v2 Multi-Tenant https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
– Kundklientorganisation (förhandsversion) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Ersätta ditt katalogklientnamn eller ID, till exempel contoso.onmicrosoft.com, för {tenant-name}.		 Nej
issuer-signing-keys En lista över Base64-kodade säkerhetsnycklar i key underelement som används för att verifiera signerade token. Om det finns flera säkerhetsnycklar provas varje nyckel tills alla är uttömda (i vilket fall verifieringen misslyckas) eller så lyckas en (användbar för tokenåterställning).

Du kan också ange en nyckel med hjälp id av attributet för att matcha ett kid anspråk. Om du vill verifiera en token som är signerad med en asymmetrisk nyckel kan du ange den offentliga nyckeln med ett certificate-id attribut med värdet identifieraren för ett certifikat som laddats upp till API Management, eller RSA-modulus n och exponentparet e för signeringsnyckeln i Base64url-kodat format.		 Nej
dekrypteringsnycklar En lista över Base64-kodade nycklar i key underelement som används för att dekryptera token. Om det finns flera säkerhetsnycklar provas varje nyckel tills alla nycklar är uttömda (i vilket fall verifieringen misslyckas) eller så lyckas en nyckel.

Du kan också ange en nyckel med hjälp id av attributet för att matcha ett kid anspråk. Om du vill dekryptera en token som krypterats med en asymmetrisk nyckel kan du ange den offentliga nyckeln med hjälp av ett certificate-id attribut med värdet identifieraren för ett certifikat som laddats upp till API Management, eller RSA-modulus n och exponentpar e för nyckeln i Base64url-kodat format.		 Nej
Publik En lista över godtagbara målgruppsanspråk i audience underelement som kan finnas på token. Om flera målgruppsvärden finns provas varje värde tills alla är uttömda (i vilket fall verifieringen misslyckas) eller tills ett lyckas. Minst en målgrupp måste anges. Nej
Emittenter En lista över godtagbara huvudkonton, i issuer underelement, som utfärdade token. Om det finns flera utfärdarvärden provas varje värde tills alla är uttömda (i vilket fall verifieringen misslyckas) eller tills ett lyckas. Nej
obligatoriska anspråk En lista över anspråk i claim underelement förväntas finnas på token för att den ska anses vara giltig. När flera anspråk finns måste token matcha anspråksvärden enligt värdet för attributet match . Nej

nyckelattribut

Attribut beskrivning Obligatoriskt Standardvärde
id Sträng. Identifierare som används för att matcha kid anspråk som visas i JWT. Nej Ej tillämpligt
certifikat-ID Identifierare för en certifikatentitet som laddats upp till API Management, som används för att ange den offentliga nyckeln för att verifiera en token signerad med en asymmetrisk nyckel. Nej Ej tillämpligt
n Modulus för den offentliga nyckeln som används för att verifiera utfärdaren av en token som är signerad med en asymmetrisk nyckel. Måste anges med värdet för exponenten e. Principuttryck tillåts inte. Nej Ej tillämpligt
e Exponent för den offentliga nyckeln som används för att verifiera utfärdaren av en token signerad med en asymmetrisk nyckel. Måste anges med värdet för modulus n. Principuttryck tillåts inte. Nej Ej tillämpligt

anspråksattribut

Attribut beskrivning Obligatoriskt Standardvärde
Matcha Attributet match för elementet claim anger om varje anspråksvärde i principen måste finnas i token för att verifieringen ska lyckas. Möjliga värden är:

- all – varje anspråksvärde i principen måste finnas i token för att verifieringen ska lyckas.

- any – Minst ett anspråksvärde måste finnas i token för att verifieringen ska lyckas.		 Nej alla
Avgränsare Sträng. Anger en avgränsare (till exempel ",") som ska användas för att extrahera en uppsättning värden från ett anspråk med flera värden. Nej Ej tillämpligt

Användning

Användningsanteckningar

  • Principen validate-jwt kräver att det registrerade anspråket exp ingår i JWT-token, såvida inte require-expiration-time attributet anges och anges till false.
  • Principen stöder både symmetriska och asymmetriska signeringsalgoritmer:
    • Symmetrisk – Följande krypteringsalgoritmer stöds: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • Om den används i principen måste nyckeln anges infogad i principen i det Base64-kodade formuläret.
    • Asymmetrisk – Följande krypteringsalgortitmer stöds: PS256, RS256, RS512.
      • Om den används i principen kan nyckeln anges antingen via en OpenID-konfigurationsslutpunkt eller genom att ange ID:t för ett uppladdat certifikat (i PFX-format) som innehåller den offentliga nyckeln eller modulus-exponent-paret för den offentliga nyckeln.
  • Om du vill konfigurera principen med en eller flera OpenID-konfigurationsslutpunkter för användning med en lokalt installerad gateway måste URL:erna för OpenID-konfigurationsslutpunkter också kunna nås av molngatewayen.
  • Du kan använda principer för åtkomstbegränsning i olika omfång för olika syften. Du kan till exempel skydda hela API:et med Microsoft Entra-autentisering genom att tillämpa validate-jwt principen på API-nivå, eller så kan du tillämpa den på API-åtgärdsnivå och använda claims den för mer detaljerad kontroll.
  • När du använder en anpassad rubrik (header-name) ignoreras det konfigurerade obligatoriska schemat (require-scheme). Om du vill använda ett obligatoriskt schema måste JWT-token anges i Authorization rubriken.

Exempel

Enkel tokenverifiering

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

Tokenverifiering med RSA-certifikat

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

Validering av enkel klienttoken för 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>

Validering av kundklienttoken för 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>

Validering av Azure Active Directory B2C-token

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

Auktorisera åtkomst till åtgärder baserat på tokenanspråk

Det här exemplet visar hur du använder validate-jwt principen för att auktorisera åtkomst till åtgärder baserat på tokenanspråksvärde.

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

Relaterat innehåll

Mer information om hur du arbetar med principer finns i: