JWT valideren

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

Het validate-jwt beleid dwingt het bestaan en de geldigheid af van een ondersteund JSON-webtoken (JWT) dat is geëxtraheerd uit een opgegeven HTTP-header, uit een opgegeven queryparameter is geëxtraheerd of overeenkomt met een specifieke waarde.

Notitie

Api Management biedt ook het validate-azure-ad-token beleid om een JWT te valideren die is geleverd door de Microsoft Entra-service.

Notitie

Stel de elementen en onderliggende elementen van het beleid in de volgorde in die in de beleidsverklaring is opgegeven. Om u te helpen dit beleid te configureren, biedt de portal een begeleide editor op basis van formulieren. Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Kenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
header-name De naam van de HTTP-header met het token. Beleidsexpressies zijn toegestaan. Een van header-name, query-parameter-name of token-value moet worden opgegeven. N.v.t.
query-parameter-name De naam van de queryparameter die het token bevat. Beleidsexpressies zijn toegestaan. Een van header-name, query-parameter-name of token-value moet worden opgegeven. N.v.t.
tokenwaarde Expressie die een tekenreeks retourneert die het token bevat. U mag niet retourneren Bearer als onderdeel van de tokenwaarde. Beleidsexpressies zijn toegestaan. Een van header-name, query-parameter-name of token-value moet worden opgegeven. N.v.t.
failed-validation-httpcode HTTP-statuscode die moet worden geretourneerd als de JWT geen validatie doorstaan. Beleidsexpressies zijn toegestaan. Nee 401
failed-validation-error-message Foutbericht dat moet worden geretourneerd in de hoofdtekst van het HTTP-antwoord als de JWT de validatie niet doorstaan. Dit bericht moet speciale tekens bevatten die correct zijn ontsnapt. Beleidsexpressies zijn toegestaan. Nee Het standaardfoutbericht is afhankelijk van het validatieprobleem, bijvoorbeeld 'JWT niet aanwezig'.
verlooptijd vereisen Booleaans. Hiermee geeft u op of een vervaldatumclaim vereist is in het token. Beleidsexpressies zijn toegestaan. Nee true
require-scheme De naam van het tokenschema, bijvoorbeeld Bearer. Wanneer dit kenmerk is ingesteld, zorgt het beleid ervoor dat het opgegeven schema aanwezig is in de waarde van de autorisatieheader. Beleidsexpressies zijn toegestaan. Nee N.v.t.
ondertekende tokens vereisen Booleaans. Hiermee geeft u op of een token moet worden ondertekend. Beleidsexpressies zijn toegestaan. Nee true
klok-scheeftrekken Tijdspanne. Gebruik dit diagram om het maximale verwachte tijdsverschil op te geven tussen de systeemklokken van de tokenverlener en het API Management-exemplaar. Beleidsexpressies zijn toegestaan. Nee 0 seconden
output-token-variable-name Tekenreeks. Naam van contextvariabele die tokenwaarde als object van het type Jwt ontvangt bij geslaagde tokenvalidatie. Beleidsexpressies zijn niet toegestaan. Nee N.v.t.

Elementen

Element Beschrijving Vereist
openid-config Voeg een of meer van deze elementen toe om een compatibele URL voor het OpenID-configuratie-eindpunt op te geven waaruit ondertekeningssleutels en verleners kunnen worden verkregen.

Configuratie met inbegrip van de JSON Web Key Set (JWKS) wordt elke 1 uur opgehaald uit het eindpunt en in de cache opgeslagen. Als het token dat wordt gevalideerd verwijst naar een validatiesleutel (met behulp van kid claim) die ontbreekt in de configuratie in de cache of als het ophalen mislukt, haalt API Management maximaal één keer per 5 minuten het eindpunt op. Deze intervallen kunnen zonder kennisgeving worden gewijzigd.

Het antwoord moet zijn gebaseerd op specificaties zoals gedefinieerd op URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

Gebruik voor Microsoft Entra ID het OpenID-Verbinding maken metagegevenseindpunt dat is geconfigureerd in uw app-registratie, zoals:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- v2 Multitenant https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
- Tenant van klant (preview) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Vervang de naam of id van uw maptenant, bijvoorbeeld contoso.onmicrosoft.com.{tenant-name}		 Nee
verlener-ondertekeningssleutels Een lijst met met Base64 gecodeerde beveiligingssleutels, in key subelementen, die worden gebruikt om ondertekende tokens te valideren. Als er meerdere beveiligingssleutels aanwezig zijn, wordt elke sleutel geprobeerd totdat alle zijn uitgeput (in dat geval mislukt de validatie) of één geslaagd (handig voor het rollover van tokens).

Geef desgewenst een sleutel op met behulp van het id kenmerk dat overeenkomt met een kid claim. Als u een token wilt valideren dat is ondertekend met een asymmetrische sleutel, geeft u desgewenst de openbare sleutel op met een certificate-id kenmerk met de waarde van een certificaat dat is geüpload naar API Management, of het RSA-modulus n - en exponentpaar e van de ondertekeningssleutel in base64url-gecodeerde indeling.		 Nee
ontsleutelingssleutels Een lijst met met Base64 gecodeerde sleutels, in key subelementen, die worden gebruikt om de tokens te ontsleutelen. Als er meerdere beveiligingssleutels aanwezig zijn, wordt elke sleutel geprobeerd totdat alle sleutels zijn uitgeput (in dat geval mislukt de validatie) of een sleutel slaagt.

Geef desgewenst een sleutel op met behulp van het id kenmerk dat overeenkomt met een kid claim. Als u een token wilt ontsleutelen dat is versleuteld met een asymmetrische sleutel, geeft u desgewenst de openbare sleutel op met een certificate-id kenmerk met de waarde van een certificaat dat is geüpload naar API Management, of het RSA-modulus n - en exponentpaar e van de sleutel in base64url-gecodeerde indeling.		 Nee
Publiek Een lijst met acceptabele doelgroepclaims, in audience subelementen, die aanwezig kunnen zijn op het token. Als er meerdere doelgroepwaarden aanwezig zijn, wordt elke waarde geprobeerd totdat alle waarden zijn uitgeput (in dat geval mislukt de validatie) of totdat één is geslaagd. Er moet ten minste één doelgroep worden opgegeven. Nee
Emittenten Een lijst met acceptabele principals, in issuer subelementen, die het token hebben uitgegeven. Als er meerdere verlenerwaarden aanwezig zijn, wordt elke waarde geprobeerd totdat alle waarden zijn uitgeput (in dat geval mislukt de validatie) of totdat een waarde slaagt. Nee
vereiste claims Een lijst met claims, in claim subelementen, verwachtte aanwezig te zijn op het token, zodat deze als geldig kan worden beschouwd. Wanneer er meerdere claims aanwezig zijn, moet het token overeenkomen met claimwaarden op basis van de waarde van het match kenmerk. Nee

sleutelkenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
id Tekenreeks. Id die wordt gebruikt om de claim te vergelijken kid die wordt weergegeven in JWT. Nee N.v.t.
certificaat-id Id van een certificaatentiteit die is geüpload naar API Management, die wordt gebruikt om de openbare sleutel op te geven om een token te verifiëren dat is ondertekend met een asymmetrische sleutel. Nee N.v.t.
n Modulus van de openbare sleutel die wordt gebruikt om de uitgever van een token te verifiëren dat is ondertekend met een asymmetrische sleutel. Moet worden opgegeven met de waarde van de exponent e. Beleidsexpressies zijn niet toegestaan. Nee N.v.t.
e Exponent van de openbare sleutel die wordt gebruikt om de verlener van een token te verifiëren dat is ondertekend met een asymmetrische sleutel. Moet worden opgegeven met de waarde van de modulus n. Beleidsexpressies zijn niet toegestaan. Nee N.v.t.

claimkenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
Overeenkomen met Het match kenmerk op het claim element geeft aan of elke claimwaarde in het beleid aanwezig moet zijn in het token om te kunnen worden gevalideerd. Mogelijke waarden zijn:

- all - elke claimwaarde in het beleid moet aanwezig zijn in het token om te kunnen worden gevalideerd.

- any - ten minste één claimwaarde moet aanwezig zijn in het token om de validatie te voltooien.		 Nee Alles
scheidingsteken Tekenreeks. Hiermee geeft u een scheidingsteken (bijvoorbeeld ',') op dat moet worden gebruikt voor het extraheren van een set waarden uit een claim met meerdere waarden. Nee N.v.t.

Gebruik

Gebruiksnotities

  • Het validate-jwt beleid vereist dat de exp geregistreerde claim is opgenomen in het JWT-token, tenzij het require-expiration-time kenmerk is opgegeven en is ingesteld op false.
  • Het beleid ondersteunt zowel symmetrische als asymmetrische ondertekeningsalgoritmen:
    • Symmetrisch : de volgende versleutelingsalgoritmen worden ondersteund: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • Als deze wordt gebruikt in het beleid, moet de sleutel inline worden opgegeven in het beleid in het met Base64 gecodeerde formulier.
    • Asymmetrisch : de volgende versleutelingsalgortithms worden ondersteund: PS256, RS256, RS512.
      • Als deze wordt gebruikt in het beleid, kan de sleutel worden opgegeven via een OpenID-configuratie-eindpunt of door de id op te geven van een geüpload certificaat (in PFX-indeling) dat de openbare sleutel bevat, of het modulus-exponent-paar van de openbare sleutel.
  • Als u het beleid wilt configureren met een of meer OpenID-configuratie-eindpunten voor gebruik met een zelf-hostende gateway, moeten de URL's voor OpenID-configuratie-eindpunten ook bereikbaar zijn voor de cloudgateway.
  • U kunt toegangsbeperkingsbeleid in verschillende bereiken voor verschillende doeleinden gebruiken. U kunt bijvoorbeeld de hele API beveiligen met Microsoft Entra-verificatie door het validate-jwt beleid toe te passen op API-niveau, of u kunt deze toepassen op het niveau van de API-bewerking en deze gebruiken claims voor gedetailleerdere controle.
  • Wanneer u een aangepaste header (header-name) gebruikt, wordt het geconfigureerde vereiste schema (require-scheme) genegeerd. Als u een vereist schema wilt gebruiken, moeten JWT-tokens worden opgegeven in de Authorization header.

Voorbeelden

Eenvoudige tokenvalidatie

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

Tokenvalidatie met RSA-certificaat

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

Validatie van één tenanttoken voor 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>

Validatie van tenanttoken voor Microsoft Entra ID-klant

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

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

Toegang tot bewerkingen autoriseren op basis van tokenclaims

In dit voorbeeld ziet u hoe u het validate-jwt beleid gebruikt om toegang tot bewerkingen te autoriseren op basis van de waarde van tokenclaims.

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

Gerelateerde inhoud

Zie voor meer informatie over het werken met beleid: