Comment puis-je décoder et vérifier la signature d'un jeton Web JSON Amazon Cognito ?

Brève description

Lorsque les clients utilisent un groupe d'utilisateurs pour s'authentifier auprès de votre application, Cognito envoie un jeton Web JSON (JWT) que vous pouvez décoder, lire et modifier. Pour obtenir les informations utilisateur de Cognito à partir d'un JWT, décodez le jeton et vérifiez la signature.

Important : Avant d'accorder l'accès à vos ressources, vous devez vérifier la signature.

Résolution

Vérifiez que Cognito a émis des jetons JWT

Utilisez le code suivant au format JavaScript :

import { CognitoJwtVerifier } from "aws-jwt-verify";

// Verifier that expects valid access tokens:
const verifier = CognitoJwtVerifier.create({
  userPoolId: "user_pool_id",
  tokenUse: "access",
  clientId: "client_id",
});

try {
  const payload = await verifier.verify(
    "eyJraWQeyJhdF9oYXNoIjoidk..." // the JWT as string
  );
  console.log("Token is valid. Payload:", payload);
} catch {
  console.log("Token not valid!");
}

Remarque : Remplacez user_pool_id par l’ID de votre groupe d'utilisateurs et client_id par l’ID de votre client d’application. Pour le jeton d'identification, mettez à jour le champ tokenUse à « id ». Pour obtenir la liste des paramètres disponibles, consultez la page aws-jwt-verify sur le site web GitHub.

Si vous utilisez un autre langage de programmation, consultez les bibliothèques jwt.io sur le site Web de JWT ou les bibliothèques OpenID Connect sur le site Web d'OpenID. Pour un exemple de code, consultez la page Décoder et vérifier les jetons JWT Amazon Cognito sur le site Web GitHub.

Cognito renvoie jusqu'à trois jetons, le jeton d'identification, le jeton d'accès et le jeton d’actualisation. Si vous utilisez des API REST, AWS Amplify ou des kits SDK AWS pour authentifier un utilisateur, vous obtenez les trois jetons.

Pour l'interface utilisateur hébergée par Cognito, le jeton que vous obtenez dépend du type d'octroi d’autorisation que vous utilisez. Si vous utilisez l'octroi implicite, vous n'obtenez que le jeton d'accès et d'identification.L’octroi de code d'autorisation renvoie des jetons d'accès, d’identification et d’actualisation. L'octroi d’informations d'identification client renvoie uniquement le jeton d'accès.

Les jetons d'accès et d'identification incluent un en-tête, une charge utile et une signature. Le client ne peut pas décoder ni vérifier le jeton d'actualisation.

Voici un exemple d'en-tête de jeton d'identification. L'en-tête contient l'ID de clé (« kid ») et l'algorithme (« alg ») utilisé pour signer le jeton. L'algorithme RS256 est une signature RSA avec SHA-256 :

{
  "kid": "key_id_example=",
  "alg": "RS256"
}

Voici un exemple de charge utile contenant des informations sur l'utilisateur et des horodatages de création et d'expiration du jeton :

{
  "sub": "aaaaaaaa-bbbb-cccc-dddd-example",
  "aud": "audience_example",
  "email_verified": true,
  "token_use": "id",
  "auth_time": 1500009400,
  "iss": "https://cognito-idp.ap-southeast-2.amazonaws.com/ap-southeast-2_example",
  "cognito:username": "anaya",
  "exp": 1500013000,
  "given_name": "Anaya",
  "iat": 1500009400,
  "email": "anaya@example.com"
}

La signature est une combinaison hachée et chiffrée de l'en-tête et de la charge utile.

Cognito génère deux paires de clés RSA pour chaque groupe d'utilisateurs. La clé privée de chaque paire est utilisée pour signer par cryptographie le jeton d'identification ou le jeton d'accès. Vous pouvez trouver les clés publiques dans une adresse à l’emplacement suivant :

https://cognito-idp.region.amazonaws.com/userPoolId/.well-known/jwks.json

Remarque : Remplacez region par la région AWS dans laquelle se trouve votre groupe d'utilisateurs et userPoolId par l'ID de votre groupe d'utilisateurs.

Le fichier JSON (jwks.json) est structuré au format suivant :

{    "keys": [{
        "alg": "RS256",
        "e": "AQAB",
        "kid": "abcdefghijklmnopqrsexample=",
        "kty": "RSA",
        "n": "lsjhglskjhgslkjgh43lj5h34lkjh34lkjht3example",
        "use": "sig"
    }, {
        "alg":
        "RS256",
        "e": "AQAB",
        "kid": "fgjhlkhjlkhexample=",
        "kty": "RSA",
        "n": "sgjhlk6jp98ugp98up34hpexample",
        "use": "sig"
    }]
}

Pour vérifier la signature d'un JWT Cognito, recherchez la clé publique dont l'identifiant correspond à l'en-tête du jeton. Utilisez différentes bibliothèques pour vérifier la signature du jeton et extraire des valeurs, telles que l'expiration et le nom d'utilisateur.

Il est recommandé de vérifier que le jeton n'a pas expiré. Assurez-vous également que l'audience (« aud ») de la charge utile correspond à l'ID client de l'application que vous avez créé dans le groupe d'utilisateurs Amazon Cognito. La bibliothèque aws-jwt-verify vérifie ces valeurs pour vous. Pour plus d'informations, consultez la page aws-jwt-verify sur le site Web de GitHub.

Clés publiques de cache

Comme les clés publiques du point de terminaison JWKS font rarement l'objet d'une rotation, vous n'avez pas besoin de les télécharger depuis le point de terminaison chaque fois que vous vérifiez un jeton. Téléchargez plutôt les clés publiques et mettez-les en cache sur la machine locale sur laquelle vous utilisez la logique de vérification des jetons JWT.

L’ID « kid » est un identifiant unique pour les clés publiques. Pour vérifier un jeton JWT, vérifiez votre cache local pour déterminer si l’ID « kid » figurant dans l'en-tête du jeton se trouve dans le cache. En l’absence de cache, téléchargez les clés publiques depuis le point de terminaison JWKS et mettez à jour votre cache.

Utilisez différentes méthodes pour vérifier le statut d'expiration ou de révocation d'un jeton

Vous pouvez révoquer les jetons d'actualisation et invalider les jetons d'accès, mais vous ne pouvez pas révoquer les jetons d'identification. Les bibliothèques de vérification JWT vérifient l'expiration du jeton, mais ne vérifient pas le statut de révocation d'un jeton. Une vérification du statut de révocation requiert une vérification côté serveur.

Informations connexes

Comprendre les jetons Web JSON (JWT) du groupe d'utilisateurs

Comment puis-je révoquer les jetons JWT dans Amazon Cognito via l'AWS CLI ?