Middleware JWK Auth

Le middleware JWK Auth authentifie les requêtes en vérifiant les jetons à l’aide de JWK (JSON Web Key). Il examine l’en-tête Authorization ainsi que les autres sources configurées, comme les cookies, si elles sont spécifiées. Il valide les jetons avec les keys fournies, récupère les clés depuis jwks_uri si cette option est spécifiée, et prend en charge l’extraction des jetons depuis les cookies si l’option cookie est définie.

Ce que valide ce middleware

Pour chaque jeton, jwk() :

• Analyse et valide le format de l’en-tête JWT.
• Exige un en-tête kid et recherche une clé correspondante d’après kid.
• Rejette les algorithmes symétriques (HS256, HS384, HS512).
• Exige que l’en-tête alg figure dans la liste d’algorithmes autorisés configurée par alg.
• Si une JWK correspondante possède un champ alg, exige que celui-ci corresponde à l’en-tête JWT alg.
• Vérifie la signature du jeton avec la clé correspondante.
• Valide par défaut les claims temporels : nbf, exp et iat.

La validation facultative des claims peut être configurée avec l’option verification :

• iss : Valide l’émetteur lorsque cette option est fournie.
• aud : Valide l’audience lorsque cette option est fournie.

Si vous avez besoin de contrôles supplémentaires, par exemple des règles d’autorisation propres à votre application, ajoutez-les dans votre propre middleware après jwk().

Information

L’en-tête Authorization envoyé par le client doit contenir un schéma spécifié.

Exemple : Bearer my.token.value ou Basic my.token.value

Importation

import { Hono } from 'hono'
import { jwk } from 'hono/jwk'
import { verifyWithJwks } from 'hono/jwt'

Utilisation

const app = new Hono()

app.use(
  '/auth/*',
  jwk({
    jwks_uri: `https://${backendServer}/.well-known/jwks.json`,
    alg: ['RS256'],
  })
)

app.get('/auth/page', (c) => {
  return c.text('You are authorized')
})

Récupérer la charge utile :

const app = new Hono()

app.use(
  '/auth/*',
  jwk({
    jwks_uri: `https://${backendServer}/.well-known/jwks.json`,
    alg: ['RS256'],
  })
)

app.get('/auth/page', (c) => {
  const payload = c.get('jwtPayload')
  return c.json(payload) // eg: { "sub": "1234567890", "name": "John Doe", "iat": 1516239022 }
})

Accès anonyme :

const app = new Hono()

app.use(
  '/auth/*',
  jwk({
    jwks_uri: (c) =>
      `https://${c.env.authServer}/.well-known/jwks.json`,
    alg: ['RS256'],
    allow_anon: true,
  })
)

app.get('/auth/page', (c) => {
  const payload = c.get('jwtPayload')
  return c.json(payload ?? { message: 'hello anon' })
})

Utiliser verifyWithJwks en dehors d’un middleware

La fonction utilitaire verifyWithJwks permet de vérifier les jetons JWT en dehors du contexte middleware de Hono, par exemple dans des pages SSR SvelteKit ou d’autres environnements côté serveur :

const id_payload = await verifyWithJwks(
  id_token,
  {
    jwks_uri: 'https://your-auth-server/.well-known/jwks.json',
    allowedAlgorithms: ['RS256'],
  },
  {
    cf: { cacheEverything: true, cacheTtl: 3600 },
  }
)

Configurer les options de requête pour récupérer les JWKS

Pour configurer la récupération des JWKS depuis jwks_uri, passez les options de requête fetch comme deuxième argument de jwk().

Cet argument est de type RequestInit et sert uniquement à la requête de récupération des JWKS.

const app = new Hono()

app.use(
  '/auth/*',
  jwk(
    {
      jwks_uri: `https://${backendServer}/.well-known/jwks.json`,
      alg: ['RS256'],
    },
    {
      headers: {
        Authorization: 'Bearer TOKEN',
      },
    }
  )
)

Options

obligatoire alg: AsymmetricAlgorithm[]

Un tableau des algorithmes asymétriques autorisés pour la vérification des jetons.

Les types disponibles sont RS256 | RS384 | RS512 | PS256 | PS384 | PS512 | ES256 | ES384 | ES512 | EdDSA.

facultatif keys: HonoJsonWebKey[] | (c: Context) => Promise<HonoJsonWebKey[]>

Les valeurs de vos clés publiques, ou une fonction qui les renvoie. Cette fonction reçoit l’objet Context.

facultatif jwks_uri: string | (c: Context) => Promise<string>

Si cette valeur est définie, le middleware tente de récupérer les JWK depuis cette URI et attend une réponse JSON contenant keys, qui sont ajoutées à l’option keys fournie. Vous pouvez aussi passer une fonction de rappel pour déterminer dynamiquement l’URI des JWKS à partir du Context.

facultatif allow_anon: boolean

Si cette valeur vaut true, les requêtes sans jeton valide sont autorisées à traverser le middleware. Utilisez c.get('jwtPayload') pour vérifier si la requête est authentifiée. La valeur par défaut est false.

facultatif cookie: string

Si cette option est définie, sa valeur sert de clé pour récupérer une valeur dans l’en-tête cookie, puis cette valeur est validée comme jeton.

facultatif headerName: string

Le nom de l’en-tête dans lequel rechercher le jeton JWT. La valeur par défaut est Authorization.

facultatif realm: string

L’espace de protection décrit par le paramètre realm de l’en-tête de défi WWW-Authenticate renvoyé dans les réponses 401. La valeur par défaut est l’URL de la requête.

facultatif verification: VerifyOptions

Configure le comportement de validation des claims en plus de la vérification de la signature :

facultatif VerifyOptions.iss: string | RegExp

L’émetteur attendu pour la vérification du jeton. Le claim iss n’est pas vérifié si cette option n’est pas définie.

facultatif VerifyOptions.aud: string | string[] | RegExp

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

facultatif VerifyOptions.nbf: boolean

Le claim nbf (not before) est vérifié s’il est présent et que cette option vaut true. La valeur par défaut est true.

facultatif VerifyOptions.iat: boolean

Le claim iat (issued at) est vérifié s’il est présent et que cette option vaut true. La valeur par défaut est true.

facultatif VerifyOptions.exp: boolean

Le claim exp (expiration time) est vérifié s’il est présent et que cette option vaut true. La valeur par défaut est true.