Azure apim jwt validation

s’applique à : Tous les niveaux de gestion des API

La stratégie impose l’existence et la validité d’un jeton Web JSON pris en charge (JWT) extrait d’un en-tête HTTP spécifié, extrait d’un paramètre de requête spécifié ou correspondant à une valeur spécifique.

Instruction de politique

Attributs

par défaut nom

Attribut	Description	Obligatoire	Nom
d’en-tête	Nom de l’en-tête HTTP contenant le jeton. Les expressions de stratégie sont autorisées.	L’un des ou doit être spécifié.	N/A
_de-paramètre-de-requête	Nom du paramètre de requête contenant le jeton. Les expressions de stratégie sont autorisées.	L’un des ou doit être spécifié.	N/A
token-value	Expression renvoyant une chaîne contenant le jeton. Vous ne devez pas retourner dans le cadre de la valeur du jeton. Les expressions de stratégie sont autorisées.	L’un des ou doit être spécifié.	N/A
failed-validation-httpcode	Code d’état HTTP à renvoyer si le JWT ne réussit pas la validation. Les expressions de stratégie sont autorisées.	Non	401
failed-validation-error-message	Message d’erreur à renvoyer dans le corps de la réponse HTTP si le JWT ne réussit pas la validation. Ce message doit comporter des caractères spéciaux correctement échappés. Les expressions de stratégie sont autorisées.	Non	Le message d’erreur par défaut dépend du problème de validation, par exemple « JWT non présent ».
booléen require-expiration-time	. Spécifie si une revendication d’expiration est requise dans le jeton. Les expressions de stratégie sont autorisées.	Nom
	du schéma de jetons, par exemple, « Bearer ». Lorsque cet attribut est défini, la stratégie s’assure que le schéma spécifié est présent dans la valeur de l’en-tête Authorization. Les expressions de stratégie sont autorisées.	Non	S.O.
require-signed-tokens	booléen. Spécifie si un jeton doit être signé. Les expressions de stratégie sont autorisées.	Pas	de véritable
décalage	temporel. Permet de spécifier la différence de temps maximale attendue entre les horloges système de l’émetteur du jeton et de l’instance de gestion des API. Les expressions de stratégie sont autorisées.	Pas de	0 seconde
de sortie token-variable-name	String. Nom de la variable de contexte qui recevra la valeur du jeton en tant qu’objet de type lors de la validation réussie du jeton. Les expressions de stratégie ne sont pas autorisées.	Aucun	élément n/a

de

Description de l’élément		requis
openid-config	Ajoutez un ou plusieurs de ces éléments pour spécifier une URL de point de terminaison de configuration OpenID conforme à partir de laquelle les clés de signature et l’émetteur peuvent être obtenus. La configuration, y compris le jeu de clés Web JSON (JWKS), est extraite du point de terminaison toutes les 1 heure et mise en cache. Si le jeton en cours de validation fait référence à une clé de validation (à l’aide de claim) qui est manquante dans la configuration mise en cache, ou si la récupération échoue, API Management extrait du point de terminaison au maximum une fois toutes les 5 minutes. Ces intervalles peuvent être modifiés sans préavis. La réponse doit être conforme aux spécifications définies à l’URL : . Pour Microsoft Entra ID, utilisez le point de terminaison de métadonnées OpenID Connect configuré dans l’inscription de votre application, par exemple : - v2 - v2 Multi-locataire - v1 - Locataire client (préversion) Remplacement du nom ou de l’ID de votre locataire d’annuaire, par exemple , par .	Liste
	des clés de sécurité encodées en Base64, en sous-éléments, utilisées pour valider les jetons signés. Si plusieurs clés de sécurité sont présentes, chaque clé est essayée jusqu’à ce qu’elles soient toutes épuisées (auquel cas la validation échoue) ou que l’une d’entre elles réussisse (utile pour le remplacement des jetons). Si vous le souhaitez, spécifiez une clé à l’aide de l’attribut pour correspondre à la revendication du jeton. Pour valider un jeton signé avec une clé asymétrique, spécifiez éventuellement la clé publique à l’aide d’un attribut dont la valeur est définie sur l’identificateur d’un certificat téléchargé dans Gestion des API, ou la paire module et exposant RSA de la clé de signature au format encodé en Base64url.	Pas
clés de déchiffrement	Liste des clés encodées en Base64, en sous-éléments, utilisées pour déchiffrer les jetons. Si plusieurs clés de sécurité sont présentes, chaque clé est essayée jusqu’à ce que toutes les clés soient épuisées (auquel cas la validation échoue) ou une clé réussit. Pour déchiffrer un jeton chiffré à l’aide d’une clé asymétrique, spécifiez éventuellement la clé publique à l’aide d’un attribut dont la valeur est définie sur l’identificateur d’un certificat téléchargé dans Gestion des API.	Aucune
audience	Liste des revendications d’audience acceptables, en sous-éléments, qui peuvent être présentes sur le jeton. Si plusieurs valeurs d’audience sont présentes, chaque valeur est testée jusqu’à ce qu’elles soient toutes épuisées (auquel cas la validation échoue) ou jusqu’à ce qu’une réussisse. Au moins une audience doit être spécifiée.	Aucune
émettrice.	Liste des principaux acceptables, en sous-éléments, qui ont émis le jeton. Si plusieurs valeurs d’émetteur sont présentes, chaque valeur est testée jusqu’à ce qu’elles soient toutes épuisées (auquel cas la validation échoue) ou jusqu’à ce que l’une d’entre elles réussisse.	Non
required-claims	Une liste de revendications, en sous-éléments, qui devraient être présentes sur le jeton pour qu’il soit considéré comme valide. Lorsque plusieurs revendications sont présentes, le jeton doit correspondre aux valeurs de revendication en fonction de la valeur de l’attribut.	Aucun

attribut de clé

, .

Attribut	Description	Obligatoire	Id par défaut
	(clé de signature de l’émetteur uniquement) Chaîne. Identificateur utilisé pour correspondre à la revendication présentée dans JWT. Si aucune clé ne correspond à la revendication, Gestion des API tentera chaque clé spécifiée. En savoir plus sur l’affirmation dans la RFC.
	Identificateur d’une entité de certificat téléchargée dans Gestion des API, utilisé pour spécifier le Clé publique pour vérifier un jeton signé avec une clé asymétrique.	Non	N/A
n	(clé de signature de l’émetteur uniquement) Module de la clé publique utilisé pour vérifier l’émetteur d’un jeton signé avec une clé asymétrique. Doit être spécifié avec la valeur de l’exposant . Les expressions de stratégie ne sont pas autorisées.	Non,	N/A
e	(clé de signature de l’émetteur uniquement) : Exposant de la clé publique utilisée pour vérifier l’émetteur d’un jeton signé avec une clé asymétrique. Doit être spécifié avec la valeur du module . Les expressions de stratégie ne sont pas autorisées.	Aucun	S.O

Attributs de revendication

chaîne

Attribut	Description	Obligatoire	Par défaut
match	L’attribut de l’élément spécifie si chaque valeur de revendication de la stratégie doit être présente dans le jeton pour que la validation réussisse. Les valeurs possibles sont les suivantes : - - chaque valeur de revendication dans la politique doit être présente dans le jeton pour que la validation réussisse. - - Au moins une valeur de revendication doit être présente dans le jeton pour que la validation réussisse.	Pas de
de séparation	de tous. Spécifie un séparateur (par exemple, « , ») à utiliser pour extraire un ensemble de valeurs d’une revendication à valeurs multiples.	Non	, N/A

Utilisation

Remarques d’utilisation

• La stratégie exige que la revendication enregistrée soit incluse dans le jeton JWT, sauf si l’attribut est spécifié et défini sur .
• La politique prend en charge à la fois les stratégies symétriques et Algorithmes de signature asymétrique :
  • symétrique : les algorithmes de chiffrement suivants sont pris en charge : A128CBC-HS256, A192CBC-HS384 A256CBC-HS512.
    • Si elle est utilisée dans la stratégie, la clé doit être fournie en ligne dans la stratégie sous la forme codée en Base64.
  • Asymétrique : les algorithmes de chiffrement suivants sont pris en charge : PS256, RS256, RS512, ES256.
    • Si elle est utilisée dans la stratégie, la clé peut être fournie soit via un point de terminaison de configuration OpenID, soit en fournissant l’ID d’un certificat téléchargé (au format PFX) qui contient la clé publique, ou la paire module-exposant de la clé publique.
• Pour configurer la stratégie avec un ou plusieurs points de terminaison de configuration OpenID à utiliser avec une passerelle auto-hébergée, les URL des points de terminaison de configuration OpenID doivent également être accessibles par la passerelle cloud.
• Vous pouvez utiliser des stratégies de restriction d’accès dans différentes étendues à des fins différentes. Par exemple, vous pouvez sécuriser l’ensemble de l’API avec l’authentification Microsoft Entra en appliquant la stratégie au niveau de l’API, ou vous pouvez l’appliquer au niveau de l’opération de l’API et l’utiliser pour un contrôle plus granulaire.
• Lors de l’utilisation d’un en-tête personnalisé (), le schéma requis configuré () sera ignoré. Pour utiliser un schéma obligatoire, les jetons JWT doivent être fournis dans l’en-tête.

Exemples

Validation simple

du

jeton Validation du jeton avec certificat RSA

Microsoft

Entra ID Validation du jeton locataire unique

Microsoft Entra ID Validation du jeton locataire du client

Azure Active Directory Validation du jeton B2C

Autoriser l’accès aux opérations en fonction des revendications de jeton

Cet exemple montre comment utiliser la stratégie pour autoriser l’accès à opérations basées sur la valeur des réclamations de jeton.

Pour

plus d’informations sur l’utilisation des stratégies, consultez :