Utilitaire d’authentification JWT

Cet utilitaire fournit des fonctions pour encoder, décoder, signer et vérifier les JSON Web Tokens (JWT). Les JWT sont couramment utilisés pour l’authentification et l’autorisation dans les applications web. Cet utilitaire offre des fonctionnalités JWT robustes avec la prise en charge de plusieurs algorithmes cryptographiques.

Importation

Pour utiliser cet utilitaire, importez-le comme suit :

import { decode, sign, verify } from 'hono/jwt'

Information

Le middleware JWT importe également la fonction jwt depuis hono/jwt.

sign()

Cette fonction génère un jeton JWT en encodant une charge utile puis en la signant avec l’algorithme et la clé secrète spécifiés.

sign(
  payload: unknown,
  secret: string,
  alg?: 'HS256';

): Promise<string>;

Exemple

import { sign } from 'hono/jwt'

const payload = {
  sub: 'user123',
  role: 'admin',
  exp: Math.floor(Date.now() / 1000) + 60 * 5, // Token expires in 5 minutes
}
const secret = 'mySecretKey'
const token = await sign(payload, secret)

Options

obligatoire payload: unknown

La charge utile JWT à signer. Vous pouvez inclure d’autres claims, comme indiqué dans Validation de la charge utile.

obligatoire secret: string

La clé secrète utilisée pour vérifier ou signer le JWT.

facultatif alg: AlgorithmTypes

L’algorithme utilisé pour signer ou vérifier le JWT. La valeur par défaut est HS256.

verify()

Cette fonction vérifie qu’un jeton JWT est authentique et toujours valide. Elle garantit que le jeton n’a pas été modifié et ne vérifie sa validité temporelle que si vous avez ajouté les champs de validation de la charge utile.

verify(
  token: string,
  secret: string,
  alg: 'HS256';
  issuer?: string | RegExp;
  aud?: string | string[] | RegExp;
): Promise<any>;

Exemple

import { verify } from 'hono/jwt'

const tokenToVerify = 'token'
const secretKey = 'mySecretKey'

const decodedPayload = await verify(tokenToVerify, secretKey, 'HS256')
console.log(decodedPayload)

Options

obligatoire token: string

Le jeton JWT à vérifier.

obligatoire secret: string

La clé secrète utilisée pour vérifier ou signer le JWT.

obligatoire alg: AlgorithmTypes

L’algorithme utilisé pour signer ou vérifier le JWT.

facultatif issuer: string | RegExp

L’émetteur attendu lors de la vérification du JWT.

facultatif aud: string | string[] | RegExp

L’audience attendue lors de la vérification du JWT. Si cette option est définie, le jeton doit inclure un claim aud et au moins une valeur d’audience doit correspondre.

decode()

Cette fonction décode un jeton JWT sans vérifier sa signature. Elle extrait et renvoie l’en-tête et la charge utile du jeton.

decode(token: string): { header: any; payload: any };

Exemple

import { decode } from 'hono/jwt'

// Decode the JWT token
const tokenToDecode =
  'eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAidXNlcjEyMyIsICJyb2xlIjogImFkbWluIn0.JxUwx6Ua1B0D1B0FtCrj72ok5cm1Pkmr_hL82sd7ELA'

const { header, payload } = decode(tokenToDecode)

console.log('Decoded Header:', header)
console.log('Decoded Payload:', payload)

Options

obligatoire token: string

Le jeton JWT à décoder.

La fonction decode permet d’inspecter l’en-tête et la charge utile d’un jeton JWT sans effectuer de vérification. Cela peut être utile pour le débogage ou l’extraction d’informations à partir de jetons JWT.

Validation de la charge utile

Lors de la vérification d’un jeton JWT, les contrôles suivants sont effectués sur la charge utile :

• exp : Vérifie que le jeton n’a pas expiré.
• nbf : Vérifie que le jeton n’est pas utilisé avant la date spécifiée.
• iat : Vérifie que le jeton n’a pas été émis à une date future.
• iss : Vérifie que le jeton a été émis par un émetteur de confiance.
• aud : Vérifie que le jeton est destiné à une audience acceptée lorsque le paramètre de vérification aud est défini.

Assurez-vous que la charge utile de votre JWT contient ces champs sous forme d’objet si vous souhaitez effectuer ces contrôles lors de la vérification.

Types d’erreurs personnalisés

Le module définit également des types d’erreurs personnalisés pour gérer les erreurs liées aux JWT.

• JwtAlgorithmNotImplemented : Indique que l’algorithme JWT demandé n’est pas implémenté.
• JwtTokenInvalid : Indique que le jeton JWT est invalide.
• JwtTokenNotBefore : Indique que le jeton est utilisé avant sa date de validité.
• JwtTokenExpired : Indique que le jeton a expiré.
• JwtTokenIssuedAt : Indique que le claim « iat » du jeton est incorrect.
• JwtTokenIssuer : Indique que le claim « iss » du jeton est incorrect.
• JwtPayloadRequiresAud : Indique qu’un claim aud est requis lorsque la vérification aud est configurée.
• JwtTokenAudience : Indique que le claim aud du jeton ne correspond pas à l’audience attendue.
• JwtTokenSignatureMismatched : Indique une discordance de signature dans le jeton.

AlgorithmTypes pris en charge

Le module prend en charge les algorithmes cryptographiques JWT suivants :

• HS256 : HMAC avec SHA-256
• HS384 : HMAC avec SHA-384
• HS512 : HMAC avec SHA-512
• RS256 : RSASSA-PKCS1-v1_5 avec SHA-256
• RS384 : RSASSA-PKCS1-v1_5 avec SHA-384
• RS512 : RSASSA-PKCS1-v1_5 avec SHA-512
• PS256 : RSASSA-PSS avec SHA-256 et MGF1 avec SHA-256
• PS384 : RSASSA-PSS avec SHA-386 et MGF1 avec SHA-386
• PS512 : RSASSA-PSS avec SHA-512 et MGF1 avec SHA-512
• ES256 : ECDSA avec P-256 et SHA-256
• ES384 : ECDSA avec P-384 et SHA-384
• ES512 : ECDSA avec P-521 et SHA-512
• EdDSA : EdDSA avec Ed25519