JWT-Authentifizierungshelfer

Dieser Helfer stellt Funktionen zum Kodieren, Dekodieren, Signieren und Überprüfen von JSON Web Tokens (JWTs) bereit. JWTs werden in Webanwendungen häufig zur Authentifizierung und Autorisierung verwendet. Der Helfer bietet robuste JWT-Funktionen mit Unterstützung verschiedener kryptografischer Algorithmen.

Import

Du kannst diesen Helfer wie folgt importieren:

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

Info

Auch die JWT-Middleware importiert die Funktion jwt aus hono/jwt.

sign()

Diese Funktion erzeugt ein JWT, indem sie eine Nutzlast kodiert und mit dem angegebenen Algorithmus und Geheimnis signiert.

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

): Promise<string>;

Beispiel

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)

Optionen

required payload: unknown

Die zu signierende JWT-Nutzlast. Du kannst weitere Claims hinzufügen, wie unter Prüfung der Nutzlast beschrieben.

required secret: string

Der geheime Schlüssel zur Prüfung oder Signierung des JWT.

optional alg: AlgorithmTypes

Der Algorithmus zur Signierung oder Prüfung des JWT. Der Standard ist HS256.

verify()

Diese Funktion prüft, ob ein JWT echt und noch gültig ist. Sie stellt sicher, dass das Token nicht verändert wurde, und prüft die Gültigkeit nur, wenn du die entsprechenden Angaben zur Prüfung der Nutzlast hinzugefügt hast.

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

Beispiel

import { verify } from 'hono/jwt'

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

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

Optionen

required token: string

Das zu prüfende JWT.

required secret: string

Der geheime Schlüssel zur Prüfung oder Signierung des JWT.

required alg: AlgorithmTypes

Der Algorithmus zur Signierung oder Prüfung des JWT.

optional issuer: string | RegExp

Der erwartete Aussteller für die JWT-Prüfung.

optional aud: string | string[] | RegExp

Die erwartete Zielgruppe für die JWT-Prüfung. Wenn diese Option gesetzt ist, muss das Token einen Claim aud enthalten und mindestens einer der Zielgruppenwerte muss übereinstimmen.

decode()

Diese Funktion dekodiert ein JWT, ohne die Signatur zu überprüfen. Sie extrahiert den Header und die Nutzlast aus dem Token und gibt beide zurück.

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

Beispiel

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)

Optionen

required token: string

Das zu dekodierende JWT.

Mit der Funktion decode kannst du den Header und die Nutzlast eines JWT untersuchen, ohne es zu überprüfen. Das ist beim Debuggen oder beim Extrahieren von Informationen aus JWTs hilfreich.

Prüfung der Nutzlast

Bei der Überprüfung eines JWT werden folgende Prüfungen der Nutzlast durchgeführt:

• exp: Es wird geprüft, ob das Token noch nicht abgelaufen ist.
• nbf: Es wird geprüft, ob das Token nicht vor einem angegebenen Zeitpunkt verwendet wird.
• iat: Es wird geprüft, ob der Ausstellungszeitpunkt des Tokens nicht in der Zukunft liegt.
• iss: Es wird geprüft, ob das Token von einem vertrauenswürdigen Aussteller stammt.
• aud: Wenn der Prüfparameter aud gesetzt ist, wird geprüft, ob das Token für eine akzeptierte Zielgruppe bestimmt ist.

Wenn du diese Prüfungen durchführen möchtest, stelle sicher, dass die JWT-Nutzlast ein Objekt ist und diese Felder enthält.

Benutzerdefinierte Fehlertypen

Das Modul definiert außerdem benutzerdefinierte Fehlertypen zur Behandlung JWT-bezogener Fehler.

• JwtAlgorithmNotImplemented: Der angeforderte JWT-Algorithmus ist nicht implementiert.
• JwtTokenInvalid: Das JWT ist ungültig.
• JwtTokenNotBefore: Das Token wird vor seinem Gültigkeitsbeginn verwendet.
• JwtTokenExpired: Das Token ist abgelaufen.
• JwtTokenIssuedAt: Der Claim „iat“ im Token ist fehlerhaft.
• JwtTokenIssuer: Der Claim „iss“ im Token ist fehlerhaft.
• JwtPayloadRequiresAud: Bei konfigurierter aud-Prüfung ist ein Claim aud erforderlich.
• JwtTokenAudience: Der Claim aud des Tokens entspricht nicht der erwarteten Zielgruppe.
• JwtTokenSignatureMismatched: Die Signatur des Tokens stimmt nicht überein.

Unterstützte AlgorithmTypes

Das Modul unterstützt die folgenden kryptografischen JWT-Algorithmen:

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