Téléchargement du nœud jsonwebtoken - Téléchargement du code source du nœud jsonwebtoken

nœud jsonwebtoken

Autre code source

1.0.0

Télécharger

jsonwebtoken

Construire	Dépendance

Une implémentation de jetons Web JSON.

Ceci a été développé avec draft-ietf-oauth-json-web-token-08 . Il utilise node-jws

Installer

 $ npm installer jsonwebtoken

Notes de migration

De la v8 à la v9
De la v7 à la v8

Usage

jwt.sign(charge utile, secretOrPrivateKey, [options, rappel])

(Asynchrone) Si un rappel est fourni, le rappel est appelé avec l' err ou le JWT.

(Synchrone) Renvoie le JsonWebToken sous forme de chaîne

payload peut être un objet littéral, un tampon ou une chaîne représentant un JSON valide.

Veuillez noter que exp ou toute autre revendication n'est définie que si la charge utile est un objet littéral. Les charges utiles de tampon ou de chaîne ne sont pas vérifiées pour la validité JSON.

Si payload n'est pas un tampon ou une chaîne, elle sera convertie en chaîne à l'aide de JSON.stringify .

secretOrPrivateKey est une chaîne (codée en utf-8), un tampon, un objet ou un KeyObject contenant soit le secret des algorithmes HMAC, soit la clé privée codée PEM pour RSA et ECDSA. Dans le cas d'une clé privée avec une phrase secrète, un objet { key, passphrase } peut être utilisé (basé sur la documentation cryptographique), dans ce cas, assurez-vous de transmettre l'option algorithm . Lors de la signature avec les algorithmes RSA, la longueur minimale du module est de 2 048, sauf lorsque l'option allowInsecureKeySizes est définie sur true. Les clés privées inférieures à cette taille seront rejetées avec une erreur.

options :

algorithm (par défaut : HS256 )
expiresIn : exprimé en secondes ou une chaîne décrivant un intervalle de temps vercel/ms.
Ex : 60 , "2 days" , "10h" , "7d" . Une valeur numérique est interprétée comme un nombre de secondes. Si vous utilisez une chaîne, assurez-vous de fournir les unités de temps (jours, heures, etc.), sinon l'unité en millisecondes est utilisée par défaut ( "120" est égal à "120ms" ).
notBefore : exprimé en secondes ou une chaîne décrivant un intervalle de temps vercel/ms.
Ex : 60 , "2 days" , "10h" , "7d" . Une valeur numérique est interprétée comme un nombre de secondes. Si vous utilisez une chaîne, assurez-vous de fournir les unités de temps (jours, heures, etc.), sinon l'unité en millisecondes est utilisée par défaut ( "120" est égal à "120ms" ).
audience
issuer
jwtid
subject
noTimestamp
header
keyid
mutatePayload : si vrai, la fonction sign modifiera directement l'objet payload. Ceci est utile si vous avez besoin d'une référence brute à la charge utile après que les revendications lui ont été appliquées, mais avant qu'elle ne soit codée dans un jeton.
allowInsecureKeySizes : si vrai, autorise l'utilisation de clés privées avec un module inférieur à 2048 pour RSA
allowInvalidAsymmetricKeyTypes : si vrai, autorise les clés asymétriques qui ne correspondent pas à l'algorithme spécifié. Cette option est uniquement destinée à la compatibilité ascendante et doit être évitée.

Il n'y a pas de valeurs par défaut pour expiresIn , notBefore , audience , subject , issuer . Ces revendications peuvent également être fournies directement dans la charge utile avec exp , nbf , aud , sub et iss respectivement, mais vous ne pouvez pas les inclure aux deux endroits.

N'oubliez pas que exp , nbf et iat sont NumericDate , voir l'expiration du jeton associée (réclamation d'exp)

L'en-tête peut être personnalisé via l'objet options.header .

Les jwts générés incluront par défaut une réclamation iat (émise à), sauf si noTimestamp n'est spécifié. Si iat est inséré dans la charge utile, il sera utilisé à la place de l'horodatage réel pour calculer d'autres choses comme exp en fonction d'un intervalle de temps dans options.expiresIn .

Signe synchrone avec valeur par défaut (HMAC SHA256)

 var jwt = require('jsonwebtoken');var token = jwt.sign({ foo: 'bar' }, 'shhhhh');

Signe synchrone avec RSA SHA256

 // signez avec RSA SHA256var privateKey = fs.readFileSync('private.key');var token = jwt.sign({ foo: 'bar' }, privateKey, { algorithm: 'RS256' });

Signer de manière asynchrone

 jwt.sign({ foo : 'bar' }, privateKey, { algorithm : 'RS256' }, function(err, token) {
  console.log(jeton);});

Antidater de jwt 30 secondes

 var old_token = jwt.sign({ foo : 'bar', iat : Math.floor(Date.now() / 1000) - 30 }, 'shhhhh');

Expiration du jeton (réclamation d'exp)

La norme pour JWT définit une réclamation exp pour l'expiration. L'expiration est représentée par un NumericDate :

Une valeur numérique JSON représentant le nombre de secondes entre 1970-01-01T00:00:00Z UTC jusqu'à la date/heure UTC spécifiée, en ignorant les secondes intercalaires. Cela équivaut à la définition IEEE Std 1003.1, édition 2013 [POSIX.1] « Secondes depuis l'époque », dans laquelle chaque jour représente exactement 86 400 secondes, à part le fait que des valeurs non entières peuvent être représentées. Voir la RFC 3339 [RFC3339] pour plus de détails concernant la date/heure en général et UTC en particulier.

Cela signifie que le champ exp doit contenir le nombre de secondes écoulées depuis l'époque.

Signature d'un token avec 1 heure d'expiration :

 jwt.sign({
  exp : Math.floor(Date.now() / 1000) + (60 * 60),
  données : 'foobar'}, 'secret');

Une autre façon de générer un jeton comme celui-ci avec cette bibliothèque est :

 jwt.sign({
  data : 'foobar'}, 'secret', { expiresIn: 60 * 60 });//ou encore mieux :jwt.sign({
  data : 'foobar'}, 'secret', { expiresIn : '1h' });

jwt.verify(jeton, secretOuPublicKey, [options, rappel])

(Asynchrone) Si un rappel est fourni, la fonction agit de manière asynchrone. Le rappel est appelé avec la charge utile décodée si la signature est valide et si l'expiration facultative, l'audience ou l'émetteur sont valides. Sinon, il sera appelé avec l'erreur.

(Synchrone) Si aucun rappel n’est fourni, la fonction agit de manière synchrone. Renvoie la charge utile décodée si la signature est valide et si l'expiration facultative, l'audience ou l'émetteur sont valides. Sinon, l'erreur sera générée.

Avertissement : lorsque le jeton provient d'une source non fiable (par exemple, une entrée utilisateur ou des requêtes externes), la charge utile décodée renvoyée doit être traitée comme n'importe quelle autre entrée utilisateur ; veuillez vous assurer de désinfecter et de travailler uniquement avec les propriétés attendues

token est la chaîne JsonWebToken

secretOrPublicKey est une chaîne (codée en utf-8), un tampon ou un KeyObject contenant soit le secret des algorithmes HMAC, soit la clé publique codée PEM pour RSA et ECDSA. Si jwt.verify est appelé asynchrone, secretOrPublicKey peut être une fonction qui doit récupérer la clé secrète ou publique. Voir ci-dessous pour un exemple détaillé

Comme mentionné dans ce commentaire, il existe d'autres bibliothèques qui attendent des secrets codés en base64 (octets aléatoires codés en base64), si tel est votre cas, vous pouvez transmettre Buffer.from(secret, 'base64') , en faisant cela, le secret sera décodé en utilisant base64 et la vérification du jeton utilisera les octets aléatoires d'origine.

options

algorithms : Liste de chaînes avec les noms des algorithmes autorisés. Par exemple, ["HS256", "HS384"] .
S'il n'est pas spécifié, une valeur par défaut sera utilisée en fonction du type de clé fournie.

secret - ['HS256', 'HS384', 'HS512']
rsa - ['RS256', 'RS384', 'RS512']
ce - ['ES256', 'ES384', 'ES512']
par défaut - ['RS256', 'RS384', 'RS512']

audience : si vous souhaitez vérifier l'audience ( aud ), fournissez une valeur ici. L'audience peut être vérifiée par rapport à une chaîne, une expression régulière ou une liste de chaînes et/ou d'expressions régulières.
Par exemple : "urn:foo" , /urn:f[o]{2}/ , [/urn:f[o]{2}/, "urn:bar"]
complete : renvoie un objet avec le { payload, header, signature } décodé au lieu du seul contenu habituel du payload.
issuer (facultatif) : chaîne ou tableau de chaînes de valeurs valides pour le champ iss .
jwtid (facultatif) : si vous souhaitez vérifier l'ID JWT ( jti ), fournissez une valeur de chaîne ici.
ignoreExpiration : si true ne valide pas l'expiration du token.
ignoreNotBefore ...
subject : si vous souhaitez vérifier subject ( sub ), fournissez une valeur ici
clockTolerance : nombre de secondes à tolérer lors de la vérification des revendications nbf et exp , pour gérer les petites différences d'horloge entre les différents serveurs
maxAge : l'âge maximum autorisé pour que les jetons soient toujours valides. Il est exprimé en secondes ou en chaîne décrivant un intervalle de temps vercel/ms.
Ex : 1000 , "2 days" , "10h" , "7d" . Une valeur numérique est interprétée comme un nombre de secondes. Si vous utilisez une chaîne, assurez-vous de fournir les unités de temps (jours, heures, etc.), sinon l'unité en millisecondes est utilisée par défaut ( "120" est égal à "120ms" ).
clockTimestamp : l'heure en secondes qui doit être utilisée comme heure actuelle pour toutes les comparaisons nécessaires.
nonce : si vous souhaitez vérifier la réclamation nonce , fournissez une valeur de chaîne ici. Il est utilisé sur Open ID pour les jetons d'identification. (Notes de mise en œuvre d’Open ID)
allowInvalidAsymmetricKeyTypes : si vrai, autorise les clés asymétriques qui ne correspondent pas à l'algorithme spécifié. Cette option est uniquement destinée à la compatibilité ascendante et doit être évitée.

 // vérifie un jeton symétrique - synchronousvar decoded = jwt.verify(token, 'shhhhh');console.log(decoded.foo) // bar// vérifie un jeton symétriquejwt.verify(token, 'shhhhh', function(err , décodé) {
  console.log(decoded.foo) // bar});// jeton invalide - synchronoustry {
  var décodé = jwt.verify(token, 'wrong-secret');} catch(err) {
  // erreur}// tokenjwt.verify invalide (jeton, 'mauvais secret', fonction (erreur, décodé) {
  // euh
  // décodé undéfini});// vérifie un jeton assymétriquevar cert = fs.readFileSync('public.pem');  // récupère la clé publiquejwt.verify(token, cert, function(err, décodé) {
  console.log(decoded.foo) // bar});//vérifie audiencevar cert = fs.readFileSync('public.pem');  // récupère la clé publiquejwt.verify(token, cert, { audience: 'urn:foo' }, function(err, decoded) {
  // si l'audience ne correspond pas, err == audience non valide});// vérifiez issuervar cert = fs.readFileSync('public.pem');  // récupère la clé publiquejwt.verify(token, cert, { audience : 'urn:foo', issuer : 'urn:issuer' }, function(err, decoded) {
  // si l'émetteur ne correspond pas, err == émetteur non valide});// vérifie jwt idvar cert = fs.readFileSync('public.pem');  // récupère la clé publiquejwt.verify(token, cert, { audience : 'urn:foo', issuer : 'urn:issuer', jwtid : 'jwtid' }, function(err, décodé) {
  // si l'identifiant jwt ne correspond pas, err == identifiant jwt invalide});// vérifiez subjectvar cert = fs.readFileSync('public.pem');  // récupère la clé publiquejwt.verify(token, cert, { audience : 'urn:foo', issuer : 'urn:issuer', jwtid : 'jwtid', subject : 'subject' }, function(err, decoded) {
  // si le sujet ne correspond pas, err == sujet invalide});// alg mismatchvar cert = fs.readFileSync('public.pem'); // récupère la clé publiquejwt.verify(token, cert, { algorithms : ['RS256'] }, function (err, payload) {
  // si jeton alg != RS256, err == signature invalide});// Vérifiez à l'aide du rappel getKey// L'exemple utilise https://github.com/auth0/node-jwks-rsa comme moyen de récupérer les clés. var jwksClient = require('jwks-rsa');var client = jwksClient({
  jwksUri : 'https://sandrino.auth0.com/.well-known/jwks.json'});fonction getKey(en-tête, rappel){
  client.getSigningKey(header.kid, function(err, key) {var signatureKey = key.publicKey || key.rsaPublicKey;callback(null, signatureKey);
  });}jwt.verify(token, getKey, options, function(err, décodé) {
  console.log(decoded.foo) // bar});

Besoin de jeter un œil à un JWT sans le vérifier ? (Cliquez pour agrandir)

jwt.decode(jeton [, options])

(Synchrone) Renvoie la charge utile décodée sans vérifier si la signature est valide.

Attention : Cela ne vérifiera pas si la signature est valide. Vous ne devez pas l'utiliser pour des messages non fiables. Vous souhaiterez probablement utiliser jwt.verify à la place.

Avertissement : lorsque le jeton provient d'une source non fiable (par exemple, entrée utilisateur ou demande externe), la charge utile décodée renvoyée doit être traitée comme n'importe quelle autre entrée utilisateur ; veuillez vous assurer de désinfecter et de travailler uniquement avec les propriétés attendues

token est la chaîne JsonWebToken

options :

json : force JSON.parse sur la charge utile même si l'en-tête ne contient pas "typ":"JWT" .
complete : renvoie un objet avec la charge utile et l'en-tête décodés.

Exemple

 // récupère la charge utile décodée en ignorant la signature, aucun secretOrPrivateKey n'est nécessairevar decoded = jwt.decode(token);// récupère la charge utile décodée et l'en-tête décodé = jwt.decode(token, {complete: true});console.log(decoded. en-tête);console.log(decoded.payload)

Erreurs et codes

Erreurs possibles générées lors de la vérification. L'erreur est le premier argument du rappel de vérification.

TokenExpiredError

Erreur générée si le jeton est expiré.

Objet d'erreur :

nom : 'TokenExpiredError'
message : « jwt a expiré »
expiré à : [ExpDate]

 jwt.verify(token, 'shhhhh', function(err, décodé) {
  if (err) {/* err = { nom : 'TokenExpiredError', message : 'jwt expiré', expiredAt : 1408621000 } */
  }});

JsonWebTokenErreur

Objet d'erreur :

nom : 'JsonWebTokenError'
message:

'jeton invalide' - l'en-tête ou la charge utile n'ont pas pu être analysés
'jwt mal formé' - le jeton n'a pas trois composants (délimités par un . )
'la signature jwt est requise'
'signature invalide'
'JWT audience invalide. attendu : [OPTIONS PUBLIC]'
'émetteur jwt invalide. attendu : [ÉMETTEUR D'OPTIONS]'
'jwt identifiant invalide. attendu : [OPTIONS ID JWT]'
'jwt sujet invalide. attendu : [OPTIONS SUJET]'

 jwt.verify(token, 'shhhhh', function(err, décodé) {
  if (err) {/* err = { nom : 'JsonWebTokenError', message : 'jwt mal formé' } */
  }});

Pas avant erreur

Lancée si l'heure actuelle est antérieure à la réclamation nbf.

Objet d'erreur :

nom : 'NotBeforeError'
message : "jwt n'est pas actif"
date : 2018-10-04T16:10:44.000Z

 jwt.verify(token, 'shhhhh', function(err, décodé) {
  if (err) {/* err = { nom : 'NotBeforeError', message : 'jwt not actif', date : 2018-10-04T16:10:44.000Z } */
  }});

Algorithmes pris en charge

Tableau d'algorithmes pris en charge. Les algorithmes suivants sont actuellement pris en charge.

alg Valeur du paramètre	Signature numérique ou algorithme MAC
HS256	HMAC utilisant l'algorithme de hachage SHA-256
HS384	HMAC utilisant l'algorithme de hachage SHA-384
HS512	HMAC utilisant l'algorithme de hachage SHA-512
RS256	RSASSA-PKCS1-v1_5 utilisant l'algorithme de hachage SHA-256
RS384	RSASSA-PKCS1-v1_5 utilisant l'algorithme de hachage SHA-384
RS512	RSASSA-PKCS1-v1_5 utilisant l'algorithme de hachage SHA-512
PS256	RSASSA-PSS utilisant l'algorithme de hachage SHA-256 (uniquement nœud ^6.12.0 OU >=8.0.0)
PS384	RSASSA-PSS utilisant l'algorithme de hachage SHA-384 (uniquement nœud ^6.12.0 OU >=8.0.0)
PS512	RSASSA-PSS utilisant l'algorithme de hachage SHA-512 (uniquement nœud ^6.12.0 OU >=8.0.0)
ES256	ECDSA utilisant la courbe P-256 et l'algorithme de hachage SHA-256
ES384	ECDSA utilisant la courbe P-384 et l'algorithme de hachage SHA-384
ES512	ECDSA utilisant la courbe P-521 et l'algorithme de hachage SHA-512
aucun	Aucune signature numérique ou valeur MAC incluse

Actualiser les JWT

Tout d’abord, nous vous recommandons de bien réfléchir si l’actualisation automatique d’un JWT n’introduira aucune vulnérabilité dans votre système.

Nous ne sommes pas à l'aise de l'inclure dans la bibliothèque, cependant, vous pouvez jeter un œil à cet exemple pour montrer comment cela pourrait être accompli. En dehors de cet exemple, il existe un problème et une pull request pour obtenir plus de connaissances sur ce sujet.

FAIRE

La chaîne de certificats X.509 n'est pas vérifiée

Signalement de problèmes

Si vous avez trouvé un bug ou si vous avez une demande de fonctionnalité, veuillez les signaler dans cette section des problèmes du référentiel. Veuillez ne pas signaler les failles de sécurité sur le système de suivi des problèmes public GitHub. Le programme de divulgation responsable détaille la procédure de divulgation des problèmes de sécurité.