JWT valideren

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, geëxtraheerd uit een opgegeven queryparameter of overeenkomt met een specifieke waarde.

Notitie

Als u een JWT wilt valideren die is geleverd door de Azure Active Directory-service, biedt API Management ook het validate-azure-ad-token beleid.

Notitie

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

Beleidsverklaring

<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 Standaard
header-name De naam van de HTTP-header die het token bevat. 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. One of header-name, query-parameter-name or token-value must be specified. N.v.t.
tokenwaarde Expressie die een tekenreeks met het token retourneert. U mag niet retourneren Bearer als onderdeel van de tokenwaarde. One of header-name, query-parameter-name or token-value must be specified. N.v.t.
failed-validation-httpcode HTTP-statuscode die moet worden geretourneerd als de JWT niet door de validatie komt. No 401
failed-validation-error-message Foutbericht dat moet worden geretourneerd in de hoofdtekst van het HTTP-antwoord als de JWT niet door de validatie komt. Dit bericht moet eventuele speciale tekens bevatten die op de juiste manier zijn escape-tekens. No Het standaardfoutbericht is afhankelijk van het validatieprobleem, bijvoorbeeld 'JWT niet aanwezig'.
vervaltijd vereisen Booleaanse. Hiermee geeft u op of een verloopclaim is vereist in het token. No 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. Nee N.v.t.
require-signed-tokens Boolean. Hiermee geeft u op of een token moet worden ondertekend. No true
klok-scheeftrekken Tijdspanne. Gebruik om het maximale verwachte tijdsverschil op te geven tussen de systeemklokken van de tokenverlener en het API Management-exemplaar. No 0 seconden
output-token-variable-name Tekenreeks. Naam van de contextvariabele die de tokenwaarde als object van het type Jwt ontvangt wanneer de tokenvalidatie is geslaagd Nee N.v.t.

Elementen

Element Beschrijving Vereist
openid-config Voeg een of meer van deze elementen toe om een compatibele OpenID-configuratie-eindpunt-URL op te geven waaruit ondertekeningssleutels en verlener 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, wordt API Management maximaal één keer per 5 minuten opgehaald van het eindpunt. Deze intervallen kunnen zonder voorafgaande kennisgeving worden gewijzigd.

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

Gebruik voor Azure Active Directory het OpenID Connect-eindpunt voor metagegevens 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

door de naam of id van uw directorytenant, bijvoorbeeld contoso.onmicrosoft.com, {tenant-name}te vervangen door .
No
issuer-signing-keys 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 sleutels zijn uitgeput (in welk geval de validatie mislukt) of één slaagt (handig voor tokenrollover).

Geef eventueel een sleutel op met behulp van het id kenmerk dat overeenkomt met een kid claim. Als u een door RS256 ondertekend token wilt valideren, geeft u desgewenst de openbare sleutel op met behulp van een certificate-id kenmerk met de waarde de id van een certificaat dat is geüpload naar API Management, of het RSA-modulusn- en exponentpaar e van de RS256-ondertekeningssleutel-in Base64url-gecodeerde indeling.
No
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 welk geval de validatie mislukt) of een sleutel slaagt.

Optionally specify a key by using the id attribute to match a kid claim. Als u een rs256-ondertekend token wilt ontsleutelen, geeft u desgewenst de openbare sleutel op met behulp van een certificate-id kenmerk met de waarde de id van een certificaat dat is geüpload naar API Management.
No
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 welk geval de validatie mislukt) of totdat een slaagt. Er moet ten minste één doelgroep worden opgegeven. No
Emittenten Een lijst met acceptabele principals, in issuer subelementen, die het token hebben uitgegeven. Als er meerdere waarden voor verleners aanwezig zijn, wordt elke waarde geprobeerd totdat alle waarden zijn uitgeput (in welk geval de validatie mislukt) of totdat er een slaagt. No
required-claims Een lijst met claims, in claim subelementen, die naar verwachting aanwezig zijn op het token om als geldig te worden beschouwd. Wanneer er meerdere claims aanwezig zijn, moet het token overeenkomen met claimwaarden op basis van de waarde van het match kenmerk. No

belangrijkste kenmerken

Kenmerk Beschrijving Vereist Standaard
id Tekenreeks. Id die wordt gebruikt om de claim te vinden 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 RS256-ondertekend token te verifiëren. Nee N.v.t.
n Modulus van de openbare sleutel die wordt gebruikt om de verlener van een RS256-ondertekend token te verifiëren. Moet worden opgegeven met de waarde van de exponent e. Nee N.v.t.
e Exponent van de openbare sleutel die wordt gebruikt om de verlener een RS256-ondertekend token te verifiëren. Moet worden opgegeven met de waarde van de modulus n. Nee N.v.t.

claimkenmerken

Kenmerk Beschrijving Vereist Standaard
Overeenkomen met Het match kenmerk op het claim element geeft aan of elke claimwaarde in het beleid aanwezig moet zijn in het token om de validatie te laten slagen. 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 laten slagen.
No all
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

Gebruiksopmerkingen

  • 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 ingesteld op false.
  • Het beleid ondersteunt HS256- en RS256-ondertekeningsalgoritmen:
    • HS256 : de sleutel moet inline worden opgegeven binnen het beleid in het met Base64 gecodeerde formulier.
    • RS256 : de sleutel kan 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.
  • Het beleid ondersteunt tokens die zijn versleuteld met symmetrische sleutels met behulp van de volgende versleutelingsalgoritmen: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
  • 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 gebruiken voor verschillende doeleinden. U kunt bijvoorbeeld de hele API beveiligen met Azure AD verificatie door het validate-jwt beleid toe te passen op API-niveau, of u kunt het toepassen op het api-bewerkingsniveau en gebruiken claims voor gedetailleerdere controle.

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>

Azure Active Directory-tokenvalidatie

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

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

Volgende stappen

Zie voor meer informatie over het werken met beleid: