Validate JWT (JWT überprüfen)

  • Artikel

GILT FÜR: Alle API Management-Ebenen

Die validate-jwt-Richtlinie erzwingt die Existenz und die Gültigkeit eines unterstützten JSON-Webtokens (JWT), das aus einem angegebenen HTTP-Header oder einem angegebenen Abfrageparameter extrahiert wurde oder einem bestimmten Wert entspricht.

Hinweis

Um ein JWT zu überprüfen, das vom Microsoft Entra-Dienst bereitgestellt wurde, stellt API Management auch die validate-azure-ad-token-Richtlinie bereit.

Hinweis

Legen Sie die Elemente und untergeordneten Elemente einer Richtlinie in der Reihenfolge fest, die in der Richtlinienanweisung angegeben ist. Das Portal unterstützt Sie bei der Konfiguration dieser Richtlinie durch einen formularbasierten, angeleiteten Editor. Erfahren Sie mehr darüber, wie Sie API Management-Richtlinien festlegen oder bearbeiten.

Richtlinienanweisung

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

Attribute

Attribut BESCHREIBUNG Erforderlich Standard
header-name Der Name des HTTP-Headers, der das Token enthält. Richtlinienausdrücke sind zulässig. Eines von header-name, query-parameter-name oder token-value muss angegeben werden. –
query-parameter-name Der Name des Abfrageparameters, der das Token enthält. Richtlinienausdrücke sind zulässig. Eines von header-name, query-parameter-name oder token-value muss angegeben werden. –
token-value Ausdruck, der eine Zeichenfolge mit Token zurückgibt. Bearer darf nicht als Teil des Tokenwerts zurückgegeben werden. Richtlinienausdrücke sind zulässig. Eines von header-name, query-parameter-name oder token-value muss angegeben werden. –
failed-validation-httpcode Der HTTP-Statuscode, der zurückgegeben werden soll, wenn das JWT die Überprüfung nicht besteht. Richtlinienausdrücke sind zulässig. Nein 401
failed-validation-error-message Die Fehlermeldung, die im HTTP-Antworttext zurückgegeben werden soll, wenn das JWT die Überprüfung nicht besteht. In dieser Meldung müssen alle Sonderzeichen ordnungsgemäß mit Escapezeichen versehen sein. Richtlinienausdrücke sind zulässig. Nein Die Standardfehlermeldung hängt vom Überprüfungsproblem ab, z.B. „JWT nicht vorhanden“.
require-expiration-time Boolesch. Gibt an, ob ein Ablaufanspruch im Token erforderlich ist. Richtlinienausdrücke sind zulässig. Nein true
require-scheme Der Name des Tokenschemas, z. B. „Bearer“. Wenn dieses Attribut festgelegt ist, stellt die Richtlinie sicher, das das angegebene Schema im Wert für den Autorisierungsheader vorhanden ist. Richtlinienausdrücke sind zulässig. Nein N/V
require-signed-tokens Boolesch. Gibt an, ob ein Token signiert sein muss. Richtlinienausdrücke sind zulässig. Nein true
clock-skew Zeitspanne. Verwenden Sie diese Option, um die maximal erwartete Zeitdifferenz zwischen den Systemuhren des Tokenausstellers und der API Management-Instanz anzugeben. Richtlinienausdrücke sind zulässig. Nein 0 Sekunden
output-token-variable-name Eine Zeichenfolge. Der Name der Kontextvariablen, die den Tokenwert bei erfolgreicher Tokenüberprüfung als ein Objekt des Typs Jwt empfängt. Richtlinienausdrücke sind nicht zulässig. Nein –

Elemente

Element BESCHREIBUNG Erforderlich
openid-config Fügen Sie mindestens eins dieser Elemente hinzu, um die URL eines konformen OpenID-Konfigurationsendpunkt anzugeben, über die Signaturschlüssel und Aussteller abgerufen werden können.

Die Konfiguration einschließlich des JWKS (JSON Web Key-Satz) wird stündlich vom Endpunkt abgerufen und zwischengespeichert. Wenn das überprüfte Token auf einen Validierungsschlüssel (mit kid-Anspruch) verweist, der in der zwischengespeicherten Konfiguration fehlt, oder wenn der Abruf fehlschlägt, ruft API Management den Endpunkt höchstens einmal alle fünf Minuten ab. Diese Intervalle können ohne vorherige Ankündigung geändert werden.

Die Antwort sollte den Spezifikationen entsprechen, wie sie unter URL https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata definiert sind.

Verwenden Sie für Azure Active Directory den OpenID Connect-Metadatenendpunkt, der in Ihrer App-Registrierung konfiguriert ist, z. B.:
– v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
– v2 mehrere Mandanten https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
– v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
– Kundenmandant (Vorschau) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Ersetzen Sie dabei {tenant-name} durch den Namen oder die ID Ihres Verzeichnismandanten, z. B. contoso.onmicrosoft.com.		 Nein
issuer-signing-keys Eine Liste von Base64-codierten Sicherheitsschlüsseln in key-Unterelementen, die zum Überprüfen von signierten Token verwendet werden. Wenn mehrere Sicherheitsschlüssel vorhanden sind, wird jeder Schlüssel ausprobiert, bis entweder alle verbraucht sind (in diesem Fall gibt es einen Validierungsfehler) oder ein Schlüssel erfolgreich ist (hilfreich für ein Tokenrollover).

Geben Sie optional einen Schlüssel an, indem Sie das id-Attribut verwenden, um einem kid-Anspruch zu entsprechen. Um ein Token zu überprüfen, das mit einem asymmetrischen Schlüssel signiert ist, geben Sie optional den öffentlichen Schlüssel mithilfe eines certificate-id-Attributs mit dem Wert des Bezeichners eines in API Management hochgeladenen Zertifikats oder des RSA-Modulus-n- und -Exponent-e-Paars des Signaturschlüssels im Base64url-codierten Format an.		 No
decryption-keys Eine Liste der Base64-codierten Schlüssel in key-Unterelementen, die zum Entschlüsseln der Token verwendet werden. Wenn mehrere Sicherheitsschlüssel vorhanden sind, wird jeder Schlüssel ausprobiert, bis entweder alle verbraucht sind (in diesem Fall gibt es einen Validierungsfehler) oder ein Schlüssel erfolgreich ist.

Geben Sie optional einen Schlüssel an, indem Sie das id-Attribut verwenden, um einem kid-Anspruch zu entsprechen. Um ein Token zu entschlüsseln, das mit einem asymmetrischen Schlüssel verschlüsselt ist, geben Sie optional den öffentlichen Schlüssel mithilfe eines certificate-id-Attributs mit dem Wert des Bezeichners eines in API Management hochgeladenen Zertifikats oder des RSA-Modulus-n- und -Exponent-e-Paars des Schlüssels im Base64url-codierten Format an.		 No
audiences Eine Liste der zulässigen Zielgruppenansprüche in audience-Unterelementen, die im Token vorhanden sein können. Wenn mehrere audience-Werte vorhanden sind, wird jeder Wert ausprobiert, bis entweder alle verbraucht sind (in diesem Fall gibt es einen Überprüfungsfehler) oder ein Wert erfolgreich ist. Mindestens ein audience-Wert muss angegeben werden. Nein
issuers Eine Liste der zulässigen Prinzipale in issuer-Unterelementen, die das Token ausgestellt haben. Wenn mehrere issuer-Werte vorhanden sind, wird jeder Wert ausprobiert, bis entweder alle verbraucht sind (in diesem Fall gibt es einen Überprüfungsfehler) oder ein Wert erfolgreich ist. Nein
required-claims Eine Liste von Ansprüchen in claim-Unterelementen, deren Vorhandensein im Token erwartet wird, damit dieses als gültig eingestuft wird. Wenn mehrere Ansprüche vorhanden sind, muss das Token entsprechend dem Wert des match-Attributs mit Anspruchswerten übereinstimmen. Nein

Schlüsselattribute

attribute BESCHREIBUNG Erforderlich Standard
id Eine Zeichenfolge. Bezeichner, der verwendet wird, um mit dem in JWT dargestellten kid-Anspruch übereinzustimmen. Nein –
certificate-id Bezeichner einer in API Management hochgeladenen Zertifikatentität, mit der der öffentliche Schlüssel zum Überprüfen eines Tokens, das mit einem asymmetrischen Schlüssel signiert ist, angegeben wird. No –
n Modulus des öffentlichen Schlüssels, der verwendet wird, um den Aussteller eines Tokens, das mit einem asymmetrischen Schlüssel signiert ist, zu überprüfen. Muss mit dem Wert des Exponenten e angegeben werden. Richtlinienausdrücke sind nicht zulässig. Nein –
e Exponent des öffentlichen Schlüssels, der verwendet wird, um den Aussteller eines Tokens, das mit einem asymmetrischen Schlüssel signiert ist, zu überprüfen. Muss mit dem Wert des Modulus n angegeben werden. Richtlinienausdrücke sind nicht zulässig. Nein –

Anspruchsattribute

attribute BESCHREIBUNG Erforderlich Standard
match Das match-Attribut im claim-Element gibt an, ob jeder Anspruchswert in der Richtlinie im Token vorhanden sein muss, damit die Überprüfung erfolgreich ist. Mögliche Werte:

- all – jeder Anspruchswert in der Richtlinie muss im Token vorhanden sein, damit die Überprüfung erfolgreich ist.

- any – mindestens ein Anspruchswert in der Richtlinie muss im Token vorhanden sein, damit die Überprüfung erfolgreich ist.		 Nein alle
Trennzeichen Zeichenfolge. Gibt ein Trennzeichen (z. B. „,“) zum Extrahieren eines Satzes von Werten aus einem mehrwertigen Anspruch an. Nein –

Verwendung

Hinweise zur Verwendung

  • Die validate-jwt-Richtlinie erfordert, dass der über exp registrierte Anspruch in das JWT einbezogen wird, sofern nicht das require-expiration-time-Attribut angegeben und auf false festgelegt ist.
  • Die Richtlinie unterstützt symmetrische und asymmetrische Signaturalgorithmen:
    • Symmetrisch: Die folgenden Verschlüsselungsalgorithmen werden unterstützt: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • Wenn er in der Richtlinie verwendet wird, muss der Schlüssel inline innerhalb der Richtlinie in Base64-codiertem Format angegeben werden.
    • Asymmetrisch: Die folgenden Verschlüsselungsalgorithmen werden unterstützt: PS256, RS256, RS512.
      • Wenn er in der Richtlinie verwendet wird, kann der Schlüssel entweder über einen Open ID-Konfigurationsendpunkt oder durch Angabe der ID eines hochgeladenen Zertifikats (im PFX-Format) bereitgestellt werden, das den öffentlichen Schlüssel oder das Modulus-Exponent-Paar des öffentlichen Schlüssels enthält.
  • Um die Richtlinie mit mindestens einem OpenID-Konfigurationsendpunkt für die Verwendung mit einem selbstgehosteten Gateway zu konfigurieren, müssen die URLs der OpenID-Konfigurationsendpunkte auch vom Cloudgateway erreichbar sein.
  • Sie können Richtlinien für die Zugriffsbeschränkung in verschiedenen Bereichen zu unterschiedlichen Zwecken verwenden. Sie können beispielsweise die gesamte API mit der Microsoft Entra-Authentifizierung sichern, indem Sie die validate-jwt-Richtlinie auf API-Ebene anwenden, oder Sie können sie auf API-Vorgangsebene anwenden und claims für eine genauere Kontrolle verwenden.
  • Bei Verwendung eines benutzerdefinierten Headers (header-name) wird das konfigurierte erforderliche Schema (require-scheme) ignoriert. Um ein erforderliches Schema zu verwenden, müssen JWT-Token im Authorization-Header angegeben werden.

Beispiele

Einfache Tokenüberprüfung

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

Tokenvalidierung mit RSA-Zertifikat

<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: Prüfung eines Tokens mit Einzelmandant

<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: Prüfung eines Tokens mit Kundenmandant

<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-Tokenüberprüfung

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

Autorisieren des Zugriffs auf Vorgänge basierend auf Tokenansprüchen

Dieses Beispiel zeigt die Verwendung der Richtlinie validate-jwt, um den Zugriff auf Vorgänge basierend auf dem Wert für Tokenansprüche zu autorisieren.

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

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier: