Valider JWT

Utilisez la stratégie de sécurité Valider JWT pour activer la validation d'un jeton Web JSON (JWT) dans une demande avant d'autoriser l'accès aux API.

Prise en charge des passerelles

Tableau 1. Tableau des passerelles prenant en charge cette stratégie, ainsi que la version de stratégie correspondante
Passerelle	Version de la stratégie
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0

Cette rubrique décrit comment configurer la stratégie dans l'interface utilisateur de l'assemblage. Pour plus de détails sur la configuration de la stratégie dans votre source OpenAPI , voir jwt-validate.

A propos de

Le jeton Web JSON (JWT) est un moyen compact, sûr pour les URL, de représenter les réclamations à transférer entre deux parties. La stratégie Validate JWT vous permet de sécuriser l'accès à vos API à l'aide de la validation JWT. Par exemple, lorsqu'une demande d'entrée qui contient un jeton JWT dans l'en-tête est reçue, la stratégie Valider le jeton JWT extrait le jeton, vérifie et déchiffre (le cas échéant) la signature et valide la réclamation. Si elle est valide, elle est placée dans une variable d'exécution (en vue d'une utilisation ultérieure si nécessaire) et l'accès à l'API est autorisé. Si la réclamation n'est pas valide, l'accès est refusé.

Toutes les réclamations spécifiées dans la stratégie Valider JWT sont validées, mais il ne s'agit pas nécessairement de toutes les réclamations contenues dans le JWT. Toutes les réclamations qui se trouvent dans le jeton Web JSON (JWT) ne doivent pas être validées, mais si l'une des réclamations spécifiées dans la stratégie Valider le jeton Web JSON (JWT) échoue, la validation échoue dans son intégralité. Si la validation aboutit, l'ensemble complet des réclamations contenues dans le jeton JWT est écrit dans la variable d'exécution spécifiée dans la propriété Output Claims . Toute action ultérieure peut donc utiliser cette variable d'exécution pour valider davantage l'intégralité des réclamations qui se trouvaient dans le JWT, si nécessaire.

Remarque :

Si le message d'origine a été signé avec une clé secrète partagée, l'objet cryptographique spécifié doit également être une clé secrète partagée.
Si le message d'origine a été signé avec une clé privée, l'objet cryptographique spécifié doit être un certificat cryptographique (certificat public).
Les éléments cryptographiques peuvent être fournis par l'intermédiaire d'un JWK (JSON Web Key).
Si un paramètre d'en-tête JWK est inclus dans l'en-tête du JWT, ce paramètre doit correspondre au JWK ou à l'objet cryptographique spécifié dans la stratégie, faute de quoi la validation du JWT échouera.
Si un objet cryptographique et un JWK sont tous deux spécifiés, l'objet cryptographique est utilisé pour déchiffrer ou vérifier le JWT.
L'action de validation JWT sur le DataPower API Gateway peut vérifier un JWT à l'aide d'un JWK unique ou d'un ensemble JWK.

Prérequis

Les conditions préalables suivantes s'appliquent :

IBM® DataPower V7.5 avec l'option Application Optimization (AO).
Si vous utilisez un ou plusieurs objets cryptographiques (crypto objects), ils doivent se trouver dans le domaine IBM API Connect de l' DataPower appliance. Les objets cryptographiques doivent référencer la clé secrète partagée ou le certificat public requis pour déchiffrer le contenu du JWT ou vérifier la signature.
Si une clé Web JSON (JWK) ou un ensemble JWK est utilisé, il doit être référencé par une variable d'exécution.

Propriétés

Le tableau suivant répertorie les propriétés des stratégies, indique si une propriété est nécessaire, définit les valeurs d'entrée et par défaut valides et précise le type de données des valeurs.

Tableau 2. Valider les propriétés de la stratégie JWT
Libellé de la propriété	Obligatoire	Descriptif	Type de données
Titre	Oui	Titre de la stratégie. La valeur par défaut est `jwt-validate`.	chaîne
Description	Non	Description de la stratégie.	chaîne
Jeton Web JSON (JWT)	Oui	Variable contextuelle ou d'exécution qui contient le JWT à valider. La valeur par défaut est `request.headers.authorization`. Toutefois, si cette propriété n'est pas définie, la stratégie recherche le JWT dans l'emplacement `request.headers.authorization` par défaut. Remarque: Le format de l'en-tête d'autorisation doit être le suivant: `"Authorization: Bearer jwt-token"` , `jeton-jwt` correspondant au JWT codé.	chaîne
Réclamations de sortie	Oui	Variable d'exécution à laquelle l'intégralité des réclamations contenues dans le JWT sont affectées. La valeur par défaut est `decoded.claims`.	chaîne
Réclamation de l'émetteur	Non	Perl Compatible Regular Expressions (PCRE) à utiliser pour valider la réclamation de l'émetteur (iss).	chaîne
Réclamation du public	Non	Expression PCRE à utiliser pour valider la réclamation du public (aud).	chaîne
Déchiffrer l'objet crypto	Non	Objet cryptographique (clé partagée ou certificat) à utiliser pour décoder la réclamation.^¹	chaîne
Déchiffrer le nom de variable JWK crypto	Non	Variable d'exécution qui contient le JWK à utiliser pour déchiffrer le JWT.^¹	chaîne
Vérifier l'objet crypto	Non	Objet cryptographique (clé partagée ou certificat) à utiliser pour vérifier la signature.^²	chaîne
Vérifier le nom de variable JWK crypto	Non	Variable d'exécution contenant le JWK ou l'ensemble JWK à utiliser pour vérifier la signature.^²	chaîne

Exemple

- jwt-validate:
    version: 1.0.0
    title: jwt-validate
    jwt: request.headers.authorization
    output-claims: decoded.claims
    iss-claim: "'^data.*'"
    aud-claim: "'^id.*'"
    jwe-crypto: jweCryptoObjectName
    jwe-jwk: jwe.jwk
    jws-crypto: jwsCryptoObjectName
    jws-jwk: jws.jwk

Erreurs

L'erreur suivante peut être générée lorsque la stratégie est exécutée :

RuntimeError - Erreur générique qui capture toutes les erreurs qui se produisent lors de l'exécution de la stratégie. En cas d'incident de validation, le message d'erreur détaillé reçu du module JOSE sous-jacent est consigné dans le journal système par défaut comme message d'erreur. Ce message d'erreur détaillé est également affecté à la variable d'exécution jwt-validate.error-message et peut donc être extrait via une interception.

Si une capture n'est pas configurée, en cas d'échec de la validation, la politique Validate JWT renvoie un code HTTP 500 Invalid-JWT-Validate. Le message d'erreur détaillé du module JOSE sous-jacent se trouve dans le journal système.

Attention: si vous êtes un développeur d'API qui est en train de résoudre un incident que l'un de vos clients a rencontré avec votre API, tenez compte des risques de sécurité avant d'envoyer à un client le contenu exact du message de journal. Vous pouvez éviter qu'une personne lance une attaque à partir des informations qu'elle reçoit du message de journal en n'envoyant au client que les informations générales sur le message.

Pour des exemples, voir jwt-validate.

¹ Un JWK et un objet cryptographique sont des moyens valides de fournir les données cryptographiques nécessaires pour déchiffrer le JWT. Toutefois, si les deux types de données sont spécifiés, seul l'objet cryptographique est utilisé. Si vous utilisez un ou plusieurs objets cryptographiques (objets crypto), ils doivent se trouver dans le domaine IBM API Connect de l' DataPower appliance. Les objets cryptographiques doivent référencer la clé secrète partagée ou le certificat public requis pour déchiffrer le contenu du JWT ou vérifier la signature.

² Un JWK ou un ensemble JWK et un objet cryptographique sont des moyens valides de fournir les données cryptographiques nécessaires pour vérifier le JWT. Toutefois, si les deux types de données sont spécifiés, seul l'objet cryptographique est utilisé.