JWT Auth 中间件

🌐 JWT Auth Middleware

JWT 认证中间件通过使用 JWT 验证令牌来提供认证。 如果未设置 cookie 选项，中间件将检查 Authorization 头。你可以使用 headerName 选项来自定义头名称。

🌐 The JWT Auth Middleware provides authentication by verifying the token with JWT. The middleware will check for an Authorization header if the cookie option is not set. You can customize the header name using the headerName option.

INFO

从客户端发送的 Authorization 标头必须具有指定的方案。

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

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

导入

🌐 Import

import { Hono } from 'hono'
import { jwt } from 'hono/jwt'
import type { JwtVariables } from 'hono/jwt'

用法

🌐 Usage

// Specify the variable types to infer the `c.get('jwtPayload')`:
type Variables = JwtVariables

const app = new Hono<{ Variables: Variables }>()

app.use(
  '/auth/*',
  jwt({
    secret: 'it-is-very-secret',
    alg: 'HS256',
  })
)

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

获取有效负载：

🌐 Get payload:

const app = new Hono()

app.use(
  '/auth/*',
  jwt({
    secret: 'it-is-very-secret',
    alg: 'HS256',
    verification: {
      iss: 'my-trusted-issuer',
      aud: 'my-api',
    },
  })
)

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

TIP

jwt() 只是一个中间件函数。如果你想使用环境变量（例如：c.env.JWT_SECRET），你可以按如下方式使用它：

app.use('/auth/*', (c, next) => {
  const jwtMiddleware = jwt({
    secret: c.env.JWT_SECRET,
    alg: 'HS256',
  })
  return jwtMiddleware(c, next)
})

选项

🌐 Options

required 秘密：string

你的密钥值。

🌐 A value of your secret key.

required 算法: string

用于验证的算法类型。

🌐 An algorithm type that is used for verifying.

可用的类型有 HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | PS256 | PS384 | PS512 | ES256 | ES384 | ES512 | EdDSA。

🌐 Available types are HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | PS256 | PS384 | PS512 | ES256 | ES384 | ES512 | EdDSA.

optional cookie: string

如果设置了此值，则使用该值作为密钥从 cookie 标头中检索该值，然后将其验证为令牌。

🌐 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.

optional headerName: string

要查找 JWT 令牌的头名称。默认值是 Authorization。

🌐 The name of the header to look for the JWT token. The default is Authorization.

app.use(
  '/auth/*',
  jwt({
    secret: 'it-is-very-secret',
    alg: 'HS256',
    headerName: 'x-custom-auth-header',
  })
)

optional 验证：VerifyOptions

控制令牌验证的选项。

🌐 Options controlling verification of the token.

optional VerifyOptions.iss: string | RegExp

用于令牌验证的预期发行者。如果未设置此项，将不会检查 iss 声明。

🌐 The expected issuer used for token verification. The iss claim will not be checked if this isn't set.

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

用于令牌验证的预期受众。如果设置了此项，令牌必须包含 aud 声明，并且至少有一个受众值必须匹配。

🌐 The expected audience used for token verification. If this is set, the token must include an aud claim and at least one audience value must match.

optional VerifyOptions.nbf: boolean

如果存在，nbf（不可早于）声明将被验证，并且设置为 true。默认值是 true。

🌐 The nbf (not before) claim will be verified if present and this is set to true. The default is true.

optional VerifyOptions.iat: boolean

iat（签发时间）声明如果存在将会被验证，并且其值设置为 true。默认值是 true。

🌐 The iat (issued at) claim will be verified if present and this is set to true. The default is true.

optional VerifyOptions.exp: boolean

exp（过期时间）声明如果存在将会被验证，并且其设置为 true。默认值是 true。

🌐 The exp (expiration time) claim will be verified if present and this is set to true. The default is true.