Azure apim jwt-validierung

Überprüfen, ob JWT

gilt für: Alle API Management-Ebenen

Die Richtlinie erzwingt das Vorhandensein und die Gültigkeit eines unterstützten JSON-Webtokens (JWT), das aus einem angegebenen HTTP-Header extrahiert wurde, aus 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 Richtlinie bereit.

Hinweis

Legen Sie die Elemente und untergeordneten Elemente der Richtlinie in der Reihenfolge fest, die in der Richtlinienanweisung angegeben ist. Um Sie bei der Konfiguration dieser Richtlinie zu unterstützen, bietet das Portal einen geführten, formularbasierten Editor. Erfahren Sie mehr über das Festlegen oder Bearbeiten von API Management-Richtlinien.

Richtlinienanweisung

Attribute

Attribut	Beschreibung	Erforderlich:
Standardheadername	: Der Name des HTTP-Headers, der das Token enthält. Richtlinienausdrücke sind zulässig.	Einer von oder muss angegeben werden.	N/A
query-parameter-name	Der Name des Abfrageparameters, der das Token enthält. Richtlinienausdrücke sind zulässig.	Einer von oder muss angegeben werden.	N/A
token-value	Ausdruck, der eine Zeichenfolge zurückgibt, die das Token enthält. Sie dürfen nicht als Teil des Tokenwerts zurückgegeben werden. Richtlinienausdrücke sind zulässig.	Einer von oder muss angegeben werden.	N/A
failed-validation-httpcode	HTTP-Statuscode, der zurückgegeben werden soll, wenn das JWT die Validierung nicht besteht. Richtlinienausdrücke sind zulässig.	Nein	401
failed-validation-error-message Fehlermeldung	, die im HTTP-Antworttext zurückgegeben werden soll, wenn das JWT die Validierung nicht besteht. Diese Nachricht muss alle Sonderzeichen enthalten, die ordnungsgemäß mit Escapezeichen versehen sind. Richtlinienausdrücke sind zulässig.	Die Fehlermeldung "Nein	Standard" hängt von einem Validierungsproblem ab, z. B. "JWT nicht vorhanden".
require-expiration-time	Boolean. Gibt an, ob ein Ablaufanspruch im Token erforderlich ist. Richtlinienausdrücke sind zulässig.	No	true
require-scheme	Der Name des Tokenschemas, z. B. "Bearer". Wenn dieses Attribut festgelegt ist, stellt die Richtlinie sicher, dass das angegebene Schema im Authorization-Headerwert vorhanden ist. Richtlinienausdrücke sind zulässig.	Nein	N/A
require-signed-tokens	Boolean. Gibt an, ob ein Token signiert werden muss. Richtlinienausdrücke sind zulässig.	Keine	echte
Zeitspanne mit Zeitverzerrung	. Verwenden Sie diese Option, um die maximale 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	Zeichenfolge. Name der Kontextvariablen, die nach erfolgreicher Tokenvalidierung einen Tokenwert als Objekt des Typs erhält. Richtlinienausdrücke sind nicht zulässig.	Keine

Beschreibung		des N/A-Elements erforderlich
openid-config	Fügen Sie eines oder mehrere dieser Elemente hinzu, um eine konforme OpenID-Konfigurationsendpunkt-URL anzugeben, von der Signaturschlüssel und Aussteller abgerufen werden können. Die Konfiguration, einschließlich des JSON Web Key Set (JWKS), wird alle 1 Stunde vom Endpunkt abgerufen und zwischengespeichert. Wenn das Token, das überprüft wird, auf einen Validierungsschlüssel (mit Anspruch) verweist, der in der zwischengespeicherten Konfiguration fehlt, oder wenn beim Abrufen ein Fehler auftritt, ruft API Management höchstens einmal alle 5 Minuten einen Abruf vom Endpunkt aus. Diese Intervalle können ohne vorherige Ankündigung geändert werden. Die Antwort sollte gemäß den Spezifikationen erfolgen, die unter URL definiert sind: . Verwenden Sie für Microsoft Entra ID den OpenID Connect-Metadatenendpunkt, der in Ihrer App-Registrierung konfiguriert wurde, z. B.: - v2 - v2 Multi-Tenant - v1 - Kundenmandant (Vorschau) Ersetzen Sie den Namen oder die ID Ihres Verzeichnismandanten, z. B. für .	No
issuer-signing-keys	Eine Liste von Base64-codierten Sicherheitsschlüsseln in Unterelementen, die zum Überprüfen signierter Token verwendet werden. Wenn mehrere Sicherheitsschlüssel vorhanden sind, wird jeder Schlüssel versucht, bis entweder alle erschöpft sind (in diesem Fall schlägt die Überprüfung fehl) oder einer erfolgreich ist (nützlich für den Tokenrollover). Geben Sie optional einen Schlüssel an, indem Sie das Attribut verwenden, um dem Anspruch des Tokens zu entsprechen. Um ein Token zu validieren, das mit einem asymmetrischen Schlüssel signiert wurde, geben Sie optional den öffentlichen Schlüssel mit einem Attribut an, dessen Wert auf die Kennung eines in API Management hochgeladenen Zertifikats festgelegt ist, oder auf das RSA-Modul- und Exponentenpaar des Signaturschlüssels im Base64url-codierten Format.	Keine
Entschlüsselungsschlüssel	Eine Liste von Base64-codierten Schlüsseln in Unterelementen, die zum Entschlüsseln der Token verwendet werden. Wenn mehrere Sicherheitsschlüssel vorhanden sind, wird jeder Schlüssel versucht, bis entweder alle Schlüssel erschöpft sind (in diesem Fall schlägt die Überprüfung fehl) oder ein Schlüssel ist erfolgreich. Um ein Token zu entschlüsseln, das mit einem asymmetrischen Schlüssel verschlüsselt wurde, geben Sie optional den öffentlichen Schlüssel mit einem Attribut an, dessen Wert auf den Bezeichner eines in API Management hochgeladenen Zertifikats festgelegt ist.	Keine
Zielgruppen	Eine Liste akzeptabler Zielgruppenansprüche in Unterelementen, die auf dem Token vorhanden sein können. Wenn mehrere Zielgruppenwerte vorhanden sind, wird jeder Wert versucht, bis entweder alle erschöpft sind (in diesem Fall schlägt die Überprüfung fehl) oder bis einer erfolgreich ist. Mindestens eine Zielgruppe muss angegeben werden.	Keine
Aussteller	Eine Liste akzeptabler Prinzipale in Unterelementen, die das Token ausgestellt haben. Wenn mehrere Ausstellerwerte vorhanden sind, wird jeder Wert versucht, bis entweder alle erschöpft sind (in diesem Fall schlägt die Überprüfung fehl) oder bis einer erfolgreich ist.	Nein
required-claims	Eine Liste von Ansprüchen in Unterelementen, von denen erwartet wird, dass sie auf dem Token vorhanden sind, damit es als gültig angesehen wird. Wenn mehrere Ansprüche vorhanden sind, muss das Token die Anspruchswerte entsprechend dem Wert des Attributs abgleichen.	Keine

Schlüsselattribute

A-Anspruchsattribute

Attribut	Beschreibung	Erforderlich
Standard-ID	(nur Aussteller-Signaturschlüssel) Zeichenfolge. Kennung, die verwendet wird, um den in JWT dargestellten Anspruch abzugleichen. Wenn keine Schlüssel mit dem Anspruch übereinstimmen, versucht API Management jeden angegebenen Schlüssel. Erfahren Sie mehr über den Claim im RFC.	Kein	N/
A-Zertifikats-ID-Bezeichner	einer Zertifikatsentität, die in API Management hochgeladen wurde und zum Angeben der Öffentlicher Schlüssel, um ein Token zu überprüfen, das mit einem asymmetrischen Schlüssel signiert ist.	Kein	N/A
n	(nur Aussteller-Signaturschlüssel) Modul des öffentlichen Schlüssels, der verwendet wird, um den Aussteller eines Tokens zu überprüfen, das mit einem asymmetrischen Schlüssel signiert ist. Muss mit dem Wert des Exponenten angegeben werden. Richtlinienausdrücke sind nicht zulässig.	Nein	N/A
e	(nur Aussteller-Signaturschlüssel) Exponent des öffentlichen Schlüssels, der verwendet wird, um den Aussteller eines Tokens zu überprüfen, das mit einem asymmetrischen Schlüssel signiert wurde. Muss mit dem Wert des Moduls angegeben werden. Richtlinienausdrücke sind nicht zulässig.	Keine	N/

Attribut	Beschreibung	Erforderlich	Standard
match	Das Attribut für das Element gibt an, ob jeder Anspruchswert in der Richtlinie im Token vorhanden sein muss, damit die Validierung erfolgreich ist. Mögliche Werte sind: - - Jeder Anspruchswert in der Richtlinie muss im Token vorhanden sein, damit die Validierung erfolgreich ist. - - Mindestens ein Anspruchswert muss im Token vorhanden sein, damit die Validierung erfolgreich ist.	Kein
All-Separator	String. Gibt ein Trennzeichen (z. B. ",") an, das zum Extrahieren eines Satzes von Werten aus einem mehrwertigen Anspruch verwendet werden soll.	Keine	N/A-Nutzung

Verwendungshinweise

Die Richtlinie erfordert, dass der registrierte Anspruch im JWT-Token enthalten ist, es sei denn, das Attribut wird angegeben und auf festgelegt.
Die Richtlinie unterstützt sowohl symmetrische als auch asymmetrische Signaturalgorithmen:
- Symmetrisch - Die folgenden Verschlüsselungsalgorithmen werden unterstützt: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
  - Wenn der Schlüssel in der Richtlinie verwendet wird, muss er inline innerhalb der Richtlinie in der Base64-codierten Form bereitgestellt werden.
- Asymmetrisch - Die folgenden Verschlüsselungsalgorithmen werden unterstützt: PS256, RS256, RS512, ES256.
  - Wenn der Schlüssel in der Richtlinie verwendet wird, kann er entweder über einen OpenID-Konfigurationsendpunkt oder durch Bereitstellen der ID eines hochgeladenen Zertifikats (im PFX-Format) bereitgestellt werden, das den öffentlichen Schlüssel oder das Modul-Exponenten-Paar des öffentlichen Schlüssels enthält.
Um die Richtlinie mit einem oder mehreren OpenID-Konfigurationsendpunkten für die Verwendung mit einem selbstgehosteten Gateway zu konfigurieren, müssen die URLs der OpenID-Konfigurationsendpunkte auch für das Cloud-Gateway erreichbar sein.
Sie können Zugriffseinschränkungsrichtlinien in verschiedenen Bereichen für unterschiedliche Zwecke verwenden. Sie können z. B. die gesamte API mit Microsoft Entra Authentifizierung sichern, indem Sie die Richtlinie auf API-Ebene anwenden, oder Sie können sie auf der API-Vorgangsebene anwenden und für eine genauere Kontrolle verwenden.
Bei Verwendung eines benutzerdefinierten Headers () wird das konfigurierte erforderliche Schema () ignoriert. Um ein erforderliches Schema verwenden zu können, müssen JWT-Token im Header bereitgestellt werden.

Beispiele

Einfache Tokenvalidierung

Tokenvalidierung mit RSA-Zertifikat

Microsoft Entra ID Tokenvalidierung eines einzelnen Mandanten

Microsoft Entra ID Kundenmandantentokenvalidierung Azure

Active Directory B2C-Tokenvalidierung

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

Dieses Beispiel zeigt, wie Sie die Richtlinie verwenden, um den Zugriff auf zu autorisieren Operationen, die auf dem Wert von Tokenansprüchen basieren.