JWK Auth Middleware

The JWK Auth Middleware authenticates requests by verifying tokens using JWK (JSON Web Key). It checks for an Authorization header and other configured sources, such as cookies, if specified. Specifically, it validates tokens using the provided keys, retrieves keys from jwks_uri if specified, and supports token extraction from cookies if the cookie option is set.

INFO

The Authorization header sent from the client must have a specified scheme.

Example: Bearer my.token.value or Basic my.token.value

Import

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

Usage

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')
})

Get 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) // eg: { "sub": "1234567890", "name": "John Doe", "iat": 1516239022 }
})

Anonymous access:

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' })
})

Options

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

The values of your public keys, or a function that returns them. The function receives the Context object.

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

If this value is set, attempt to fetch JWKs from this URI, expecting a JSON response with keys, which are added to the provided keys option. You can also pass a callback function to dynamically determine the JWKS URI using the Context.

optional allow_anon: boolean

If this value is set to true, requests without a valid token will be allowed to pass through the middleware. Use c.get('jwtPayload') to check if the request is authenticated. The default is false.

optional cookie: string

If this value is set, then the value is retrieved from the cookie header using that value as a key, which is then validated as a token.