JWK Auth 中间件

JWK Auth 中间件会使用 JWK（JSON Web Key）验证令牌来为请求进行身份认证。它会检查 Authorization 请求头及其他配置来源（如设置了 cookie 选项时的 Cookie）。中间件会使用提供的 keys 验证令牌，或在指定 jwks_uri 时从该地址拉取公钥；如果设置了 cookie 选项，还会从 Cookie 中提取令牌。

INFO

客户端发送的 Authorization 头必须携带身份验证方案。

例如：Bearer my.token.value 或 Basic my.token.value

导入

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

用法

const app = new Hono()

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

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

获取 payload：

const app = new Hono()

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

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

允许匿名访问：

const app = new Hono()

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

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

在中间件外使用 verifyWithJwks

verifyWithJwks 工具函数可以在 Hono 中间件之外校验 JWT，例如在 SvelteKit 的 SSR 页面或其他服务端环境中：

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

选项

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

公钥数组，或返回公钥数组的函数。若传入函数，将收到 Context 作为参数。

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

若设置该值，将会从对应 URI 拉取 JWK 列表（JSON 中的 keys 字段），并与 keys 选项中提供的公钥合并。也可以传入回调函数，根据 Context 动态生成 URI。

optional allow_anon：boolean

设为 true 时，即使请求未携带有效令牌也允许通过。可通过 c.get('jwtPayload') 判断请求是否已认证。默认值为 false。

optional cookie：string

若设置该值，将使用该键名从 Cookie 头中提取令牌并进行验证。

optional headerName：string

要读取 JWT 的请求头名称，默认为 Authorization。