Vérification des jetons Web JSON - Amazon Cognito
PrérequisValidez les jetons avec aws-jwt-verifyComprendre et inspecter les jetons

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Vérification des jetons Web JSON

Les jetons Web JSON (JWTs) peuvent être décodés, lus et modifiés facilement. Un jeton d'accès modifié crée un risque d'augmentation des privilèges. Un jeton d'identification modifié crée un risque d'usurpation d'identité. Votre application fait confiance à votre groupe d'utilisateurs en tant qu'émetteur de jetons, mais que se passe-t-il si un utilisateur intercepte le jeton en transit ? Vous devez vous assurer que votre application reçoit le même jeton qu'Amazon Cognito a émis.

Amazon Cognito émet des jetons qui utilisent certaines des fonctionnalités d'intégrité et de confidentialité de la spécification OpenID Connect (OIDC). Les jetons du pool d'utilisateurs indiquent la validité à l'aide d'objets tels que le délai d'expiration, l'émetteur et la signature numérique. La signature, le troisième et dernier segment du JWT . délimité, est l'élément clé de la validation des jetons. Un utilisateur malveillant peut modifier un jeton, mais si votre application récupère la clé publique et compare la signature, elle ne correspondra pas. Toute application utilisant JWTs l'authentification OIDC doit effectuer cette opération de vérification à chaque connexion.

Sur cette page, nous formulons quelques recommandations générales et spécifiques pour la vérification de JWTs. Le développement d'applications couvre une variété de langages de programmation et de plateformes. Dans la mesure où Amazon Cognito implémente l'OIDC de manière suffisamment proche des spécifications publiques, toute bibliothèque JWT réputée dans l'environnement de développement de votre choix peut répondre à vos exigences de vérification.

Ces étapes décrivent la vérification d'un jeton web JSON (JWT) de groupe d'utilisateurs.

Prérequis

Il se peut que votre bibliothèque, votre SDK ou votre infrastructure logicielle gère déjà les tâches décrites dans cette section. AWS SDKs fournissez des outils pour le traitement et la gestion des jetons du pool d'utilisateurs Amazon Cognito dans votre application. AWS Amplify inclut des fonctions permettant de récupérer et d'actualiser les jetons Amazon Cognito.

Pour plus d'informations, consultez les pages suivantes.

De nombreuses bibliothèques sont disponibles pour le décodage et la vérification d'un jeton web JSON (JWT). De telles bibliothèques peuvent être utiles si vous voulez traiter manuellement des jetons pour le traitement d'API côté serveur, ou si vous utilisez d'autres langages de programmation. Consultez la liste de bibliothèques OpenID Foundation pour la gestion des jetons JWT.

Validez les jetons avec aws-jwt-verify

Dans une application Node.js, AWS recommande à la aws-jwt-verifybibliothèque de valider les paramètres du jeton que l'utilisateur transmet à votre application. Avec aws-jwt-verify, vous pouvez renseigner un CognitoJwtVerifier avec les valeurs des champs standard que vous souhaitez vérifier pour un ou plusieurs groupes d'utilisateurs. Parmi les valeurs qu'il peut vérifier figurent les suivantes :

Pour plus d'informations et des exemples de code que vous pouvez utiliser dans une application Node.js ou un AWS Lambda autorisateur, reportez-vous aws-jwt-verifyà la section suivante. GitHub

Comprendre et inspecter les jetons

Avant d'intégrer l'inspection par jetons à votre application, réfléchissez au mode d'assemblage d'Amazon Cognito. JWTs Récupérez des exemples de jetons de votre groupe d'utilisateurs. Décodez et examinez-les en détail pour comprendre leurs caractéristiques et déterminer ce que vous souhaitez vérifier et à quel moment. Par exemple, vous pouvez examiner l'appartenance à un groupe dans un scénario et les étendues dans un autre.

Les sections suivantes décrivent un processus permettant d'inspecter manuellement Amazon Cognito lors de la préparation JWTs de votre application.

Vérification de la structure du jeton JWT.

Un jeton Web JSON (JWT) comprend trois sections séparées par un séparateur . (point).

En-tête

L'ID de clé, kid, et l'algorithme RSA, alg, utilisés par Amazon Cognito pour signer le jeton. Amazon Cognito signe les jetons avec un alg ayant pour valeur RS256. kidIl s'agit d'une référence tronquée à une clé de signature privée RSA de 2048 bits détenue par votre groupe d'utilisateurs.

Charge utile

Champs standard du jeton. Dans un jeton d'identification, les champs standard incluent des attributs de l'utilisateur et des informations sur le groupe d'utilisateurs, iss, et le client d'application, aud. Dans un jeton d'accès, la charge utile inclut les étendues, l'appartenance à un groupe, votre groupe d'utilisateurs en tant que iss, et votre client d'application en tant que client_id.

Signature

La signature n'est pas décodable en base64url comme l'en-tête et la charge utile. Il s'agit d'un RSA256 identifiant dérivé d'une clé de signature et de paramètres que vous pouvez observer sur votre URI JWKS.

L'en-tête et la charge utile sont des fichiers JSON codés en base64url. Vous pouvez les identifier grâce aux premiers caractères eyJ dont la forme déchiffrée correspond au caractère ouvrant {. Si votre utilisateur présente un JWT codé en base64url à votre application et qu'il n'est pas au format approprié[JSON Header].[JSON Payload].[Signature], il ne s'agit pas d'un jeton Amazon Cognito valide et vous pouvez le supprimer.

L'exemple d'application suivant vérifie les jetons du groupe d'utilisateurs avecaws-jwt-verify.

// cognito-verify.js
// Usage example: node cognito-verify.js eyJra789ghiEXAMPLE

const { CognitoJwtVerifier } = require('aws-jwt-verify');

// Replace with your Amazon Cognito user pool ID
const userPoolId = 'us-west-2_EXAMPLE';

async function verifyJWT(token) {
  try {
    const verifier = CognitoJwtVerifier.create({
      userPoolId,
      tokenUse: 'access', // or 'id' for ID tokens
      clientId: '1example23456789', // Optional, only if you need to verify the token audience
    });

    const payload = await verifier.verify(token);
    console.log('Decoded JWT:', payload);
  } catch (err) {
    console.error('Error verifying JWT:', err);
  }
}

// Example usage
if (process.argv.length < 3) {
  console.error('Please provide a JWT token as an argument.');
  process.exit(1);
}

const MyToken = process.argv[2];
verifyJWT(MyToken);

Validation du jeton JWT

La signature du jeton JWT est une combinaison hachée de l'en-tête et de la charge utile. Amazon Cognito génère deux paires de clés de chiffrement RSA pour chaque groupe d'utilisateurs. Une clé privée signe les jetons d'accès et l'autre signe les jetons d'identification.

Pour vérifier la signature d'un jeton JWT

  1. Décodez le jeton d'identification.

    OpenID Foundation gère également une liste de bibliothèques pour la gestion des jetons JWT.

    Vous pouvez également l'utiliser AWS Lambda pour décoder le groupe d'utilisateurs. JWTs Pour plus d'informations, consultez Décoder et vérifier les jetons Amazon Cognito JWT à l'aide de. AWS Lambda

  2. Comparez l'ID de clé local (kid) à l'identifiant kid public.

    1. Téléchargez et stockez la clé web JSON (JWK) publique correspondante pour votre groupe d'utilisateurs. Elle est disponible dans le cadre d'un ensemble de clés web JSON (JWKS). Vous pouvez le localiser en construisant l'URI jwks_uri suivant pour votre environnement :

      https://cognito-idp.<Region>.amazonaws.com/<userPoolId>/.well-known/jwks.json

      Pour plus d'informations sur les clés JWK et les ensembles de clés JWK, consultez JSON Web Key (JWK).

      Note

      Amazon Cognito peut effectuer une rotation des clés de signature dans votre groupe d’utilisateurs. Une bonne pratique consiste à mettre en cache les clés publiques de votre application, en utilisant l'identifiant kid comme clé de cache, et à actualiser régulièrement le cache. Comparez l'identifiant kid dans les jetons que votre application reçoit à votre cache.

      Si vous recevez un jeton avec l'émetteur approprié, mais un identifiant kid différent, Amazon Cognito a peut-être effectué la rotation de la clé de signature. Actualisez le cache à partir du point de terminaison jwks_uri de votre groupe d'utilisateurs.

      Ceci est un exemple de fichier jwks.json :

      {
	"keys": [{
		"kid": "1234example=",
		"alg": "RS256",
		"kty": "RSA",
		"e": "AQAB",
		"n": "1234567890",
		"use": "sig"
	}, {
		"kid": "5678example=",
		"alg": "RS256",
		"kty": "RSA",
		"e": "AQAB",
		"n": "987654321",
		"use": "sig"
	}]
}
      ID de clé (kid)

      L'identifiant kid indique quelle clé a été utilisée pour sécuriser la signature Web JSON (JWS) du jeton.

      Algorithme (alg)

      Le paramètre d'en-tête alg indique l'algorithme de chiffrement utilisé pour sécuriser le jeton d'identification. Les groupes d'utilisateurs utilisent un algorithme RS256 cryptographique, qui est une signature RSA avec SHA-256. Pour plus d'informations sur RSA, consultez Chiffrement RSA.

      Type de clé (kty)

      Le paramètre kty identifie la famille d'algorithmes de chiffrement utilisée avec la clé, comme « RSA » dans cet exemple.

      Exposant RSA (e)

      Le paramètre e contient la valeur d'exposant pour la clé publique RSA. Elle est représentée sous la forme d'une valeur codée en base64URLUInt.

      Modulo RSA (n)

      Le paramètre n contient la valeur de module pour la clé publique RSA. Elle est représentée sous la forme d'une valeur codée en base64URLUInt.

      Use (use)

      Le paramètre use décrit l'utilisation prévue de la clé publique. Dans cet exemple, la valeur use sig représente la signature.

    2. Recherchez dans la clé Web JSON publique un identifiant kid correspondant à l'identifiant kid de votre jeton JWT.

Vérification des demandes.

Pour vérifier les demandes de jeton JWT.

  1. À l'aide de l'une des méthodes suivantes, vérifiez que le jeton n'a pas expiré.

    1. Décodez le jeton et comparez le champ standard exp à l'heure actuelle.

    2. Si votre jeton d'accès inclut une aws.cognito.signin.user.admin réclamation, envoyez une demande à une API telle que GetUser. Les demandes d'API que vous autorisez avec un jeton d'accès renvoient une erreur si votre jeton a expiré.

    3. Présentez votre jeton d'accès dans une demande adressée au Point de terminaison UserInfo. Votre demande renvoie une erreur si votre jeton a expiré.

  2. La demande aud dans un jeton d'identification et la demande client_id dans un jeton d'accès doivent correspondre à l'ID de client d'application créé dans le groupe d'utilisateurs Amazon Cognito.

  3. La demande du diffuseur (iss) doit correspondre à votre groupe d'utilisateurs. Par exemple, un groupe d'utilisateurs créé dans la région us-east-1 a la valeur iss suivante :

    https://cognito-idp.us-east-1.amazonaws.com/<userpoolID>.

  4. Vérifiez la demande token_use.

    • Si vous acceptez uniquement le jeton d'accès dans vos opérations de l'API web, sa valeur doit être access.

    • Si vous utilisez uniquement le jeton d'identification, sa valeur doit indiquer id.

    • Si vous utilisez des jetons d'identification et d'accès, la demande token_use doit être id ou access.

Vous pouvez désormais approuver les demandes à l'intérieur du jeton.