Gin JWT 中间件

English | 繁體中文 | 简体中文

一个强大且灵活的 Gin Web 框架的 JWT 认证中间件，基于 golang-jwt/jwt 实现。 轻松为你的 Gin 应用添加登录、Token 刷新与授权功能。

目录

• Gin JWT 中间件
• 目录
• 功能特色
• 安全性注意事项
  • 🔒 关键安全要求
  • 🛡️ 生产环境安全检查清单
  • 🔄 OAuth 2.0 安全标准
  • 💡 安全配置示例
• 安装
• 快速开始示例
• 使用示例
  • 🔑 基础认证
  • 🌐 OAuth SSO 集成
  • 🔐 Token 生成器
  • 🗄️ Redis 存储
  • 🛡️ 授权控制
• 配置
• JWT 解析选项
  • 时钟偏差容错（Leeway）
  • 何时使用 Leeway
  • 配置示例
  • Leeway 工作原理
  • 其他解析选项
  • JSON 数值处理
  • 必需声明验证
  • 组合多个选项
• 支持多个 JWT 提供者
  • 使用场景
  • 解决方案：动态密钥函数
  • 为什么这个方法有效
  • 实现策略
  • 步骤 1：创建统一的中间件
  • 步骤 2：辅助函数
  • 步骤 3：路由设置
  • 完整的 Azure AD 集成示例
  • 替代方法：自定义包装中间件
  • 关键考虑事项
  • 测试多提供者设置
  • 常见问题与解决方案
  • 其他资源
• Token 生成器（直接创建 Token）
  • 基本用法
  • Token 结构
  • 刷新 Token 管理
• Redis 存储配置
  • Redis 功能特色
  • Redis 使用方法
  • 使用函数选项模式（推荐）
  • 可用选项
  • 配置选项
  • RedisConfig
  • 回退行为
  • Redis 示例
• Demo
  • 登录
  • 刷新 Token
  • Hello World
  • 授权示例
• 理解 Authorizer
  • Authorizer 工作原理
  • Authorizer 函数签名
  • 基本用法示例
  • 示例 1：基于角色的授权
  • 示例 2：基于路径的授权
  • 示例 3：基于方法和路径的授权
  • 为不同路由设置不同授权
  • 方法 1：多个中间件实例
  • 方法 2：带路径逻辑的单一 Authorizer
  • 高级授权模式
  • 使用 Claims 进行细粒度控制
  • 常见模式和最佳实践
  • 授权完整示例
  • 登出
• Cookie Token
  • 刷新 Token Cookie 支持
  • 登录流程（LoginHandler）
  • 需要 JWT Token 的端点（MiddlewareFunc）
  • 登出流程（LogoutHandler）
  • 刷新流程（RefreshHandler）
  • 登录失败、Token 错误或权限不足

功能特色

• 🔒 为 Gin 提供简单的 JWT 认证
• 🔁 内置登录、刷新、登出处理器
• 🛡️ 可自定义认证、授权与 Claims
• 🍪 支持 Cookie 与 Header Token
• 📝 易于集成，API 清晰
• 🔐 符合 RFC 6749 规范的刷新令牌（OAuth 2.0 标准）
• 🗄️ 可插拔的刷新令牌存储（内存、Redis 客户端缓存）
• 🏭 直接生成 Token，无需 HTTP 中间件
• 📦 结构化 Token 类型与元数据

安全性注意事项

🔒 关键安全要求

⚠️ JWT 密钥安全

• 最低要求： 使用至少 256 位（32 字节） 长度的密钥
• 禁止使用： 简单密码、字典词汇或可预测的模式
• 建议： 生成加密安全的随机密钥或使用 RS256 算法
• 存储： 将密钥存储在环境变量中，绝不硬编码在源码中
• 漏洞： 弱密钥易受暴力破解攻击（jwt-cracker）

🛡️ 生产环境安全检查清单

• ✅ 仅限 HTTPS： 生产环境中务必使用 HTTPS
• ✅ 强密钥： 最少 256 位随机生成的密钥
• ✅ Token 过期： 设置适当的过期时间（建议：访问 Token 15-60 分钟）
• ✅ 安全 Cookie： 启用 SecureCookie、CookieHTTPOnly 和适当的 SameSite 设置
• ✅ 环境变量： 将敏感配置存储在环境变量中
• ✅ 输入验证： 彻底验证所有认证输入

🔄 OAuth 2.0 安全标准

此库遵循 RFC 6749 OAuth 2.0 安全标准：

• 分离令牌： 使用不同的不透明刷新令牌（非 JWT）以增强安全性
• 服务器端存储： 刷新令牌在服务器端存储和验证
• 令牌轮替： 每次使用时自动轮替刷新令牌
• 增强安全性： 防止 JWT 刷新令牌漏洞和重放攻击

💡 安全配置示例

// ❌ 不良：弱密钥、不安全设置
authMiddleware := &jwt.GinJWTMiddleware{
    Key:         []byte("weak"),           // 太短！
    Timeout:     time.Hour * 24,          // 太长！
    SecureCookie: false,                  // 生产环境不安全！
}

// ✅ 良好：强安全配置
authMiddleware := &jwt.GinJWTMiddleware{
    Key:            []byte(os.Getenv("JWT_SECRET")), // 来自环境变量
    Timeout:        time.Minute * 15,                // 短期访问令牌
    MaxRefresh:     time.Hour * 24 * 7,             // 1 周刷新有效期
    SecureCookie:   true,                           // 仅限 HTTPS
    CookieHTTPOnly: true,                           // 防止 XSS
    CookieSameSite: http.SameSiteStrictMode,        // CSRF 保护
    SendCookie:     true,                           // 启用安全 Cookie
}

更多安全指导，请参见我们的 安全最佳实践指南

安装

需要 Go 1.24+

go get -u github.com/appleboy/gin-jwt/v3

import "github.com/appleboy/gin-jwt/v3"

快速开始示例

请参考 _example/basic/server.go 示例文件，并可使用 ExtractClaims 获取 JWT 内的用户数据。

package main

import (
  "log"
  "net/http"
  "os"
  "time"

  jwt "github.com/appleboy/gin-jwt/v3"
  "github.com/gin-gonic/gin"
  "github.com/golang-jwt/jwt/v5"
)

type login struct {
  Username string `form:"username" json:"username" binding:"required"`
  Password string `form:"password" json:"password" binding:"required"`
}

var (
  identityKey = "id"
  port        string
)

// User demo
type User struct {
  UserName  string
  FirstName string
  LastName  string
}

func init() {
  port = os.Getenv("PORT")
  if port == "" {
    port = "8000"
  }
}

func main() {
  engine := gin.Default()
  // the jwt middleware
  authMiddleware, err := jwt.New(initParams())
  if err != nil {
    log.Fatal("JWT Error:" + err.Error())
  }

  // initialize middleware
  errInit := authMiddleware.MiddlewareInit()
  if errInit != nil {
    log.Fatal("authMiddleware.MiddlewareInit() Error:" + errInit.Error())
  }

  // register route
  registerRoute(engine, authMiddleware)

  // start http server
  if err = http.ListenAndServe(":"+port, engine); err != nil {
    log.Fatal(err)
  }
}

func registerRoute(r *gin.Engine, handle *jwt.GinJWTMiddleware) {
  // Public routes
  r.POST("/login", handle.LoginHandler)
  r.POST("/refresh", handle.RefreshHandler) // RFC 6749 compliant refresh endpoint

  r.NoRoute(handle.MiddlewareFunc(), handleNoRoute())

  // Protected routes
  auth := r.Group("/auth", handle.MiddlewareFunc())
  auth.GET("/hello", helloHandler)
  auth.POST("/logout", handle.LogoutHandler) // Logout with refresh token revocation
}

func initParams() *jwt.GinJWTMiddleware {
  return &jwt.GinJWTMiddleware{
    Realm:       "test zone",
    Key:         []byte("secret key"),
    Timeout:     time.Hour,
    MaxRefresh:  time.Hour,
    IdentityKey: identityKey,
    PayloadFunc: payloadFunc(),

    IdentityHandler: identityHandler(),
    Authenticator:   authenticator(),
    Authorizer:      authorizer(),
    Unauthorized:    unauthorized(),
    LogoutResponse:  logoutResponse(),
    TokenLookup:     "header: Authorization, query: token, cookie: jwt",
    // TokenLookup: "query:token",
    // TokenLookup: "cookie:token",
    TokenHeadName: "Bearer",
    TimeFunc:      time.Now,
  }
}

func payloadFunc() func(data any) jwt.MapClaims {
  return func(data any) jwt.MapClaims {
    if v, ok := data.(*User); ok {
      return jwt.MapClaims{
        identityKey: v.UserName,
      }
    }
    return jwt.MapClaims{}
  }
}

func identityHandler() func(c *gin.Context) any {
  return func(c *gin.Context) any {
    claims := jwt.ExtractClaims(c)
    return &User{
      UserName: claims[identityKey].(string),
    }
  }
}

func authenticator() func(c *gin.Context) (any, error) {
  return func(c *gin.Context) (any, error) {
    var loginVals login
    if err := c.ShouldBind(&loginVals); err != nil {
      return "", jwt.ErrMissingLoginValues
    }
    userID := loginVals.Username
    password := loginVals.Password

    if (userID == "admin" && password == "admin") || (userID == "test" && password == "test") {
      return &User{
        UserName:  userID,
        LastName:  "Bo-Yi",
        FirstName: "Wu",
      }, nil
    }
    return nil, jwt.ErrFailedAuthentication
  }
}

func authorizer() func(c *gin.Context, data any) bool {
  return func(c *gin.Context, data any) bool {
    if v, ok := data.(*User); ok && v.UserName == "admin" {
      return true
    }
    return false
  }
}

func unauthorized() func(c *gin.Context, code int, message string) {
  return func(c *gin.Context, code int, message string) {
    c.JSON(code, gin.H{
      "code":    code,
      "message": message,
    })
  }
}

func logoutResponse() func(c *gin.Context) {
  return func(c *gin.Context) {
    // This demonstrates that claims are now accessible during logout
    claims := jwt.ExtractClaims(c)
    user, exists := c.Get(identityKey)

    response := gin.H{
      "code":    http.StatusOK,
      "message": "Successfully logged out",
    }

    // Show that we can access user information during logout
    if len(claims) > 0 {
      response["logged_out_user"] = claims[identityKey]
    }
    if exists {
      response["user_info"] = user.(*User).UserName
    }

    c.JSON(http.StatusOK, response)
  }
}

func handleNoRoute() func(c *gin.Context) {
  return func(c *gin.Context) {
    c.JSON(404, gin.H{"code": "PAGE_NOT_FOUND", "message": "Page not found"})
  }
}

func helloHandler(c *gin.Context) {
  claims := jwt.ExtractClaims(c)
  user, _ := c.Get(identityKey)
  c.JSON(200, gin.H{
    "userID":   claims[identityKey],
    "userName": user.(*User).UserName,
    "text":     "Hello World.",
  })
}

使用示例

本项目提供多个完整的示例实现，展示不同的使用场景：

🔑 基础认证

展示基本的 JWT 认证功能，包含登录、受保护路由和 token 验证。

🌐 OAuth SSO 集成

OAuth 2.0 单点登录示例，支持多个身份提供者（Google、GitHub）：

• OAuth 2.0 授权码流程
• 使用 state token 的 CSRF 保护
• 双重认证支持：httpOnly cookies + Authorization headers
• 为浏览器和移动应用程序提供安全的 token 传递
• 包含交互式 demo 页面

🔐 Token 生成器

直接生成 JWT token，无需 HTTP middleware，适用于：

• 程序化认证
• 服务间通信
• 测试需要认证的端点
• 自定义认证流程

🗄️ Redis 存储

展示 Redis 集成用于 refresh token 存储，包含：

• 客户端缓存以提升性能
• 自动降级至内存存储
• 生产环境就绪的配置示例

🛡️ 授权控制

高级授权模式，包含：

• 基于角色的访问控制
• 基于路径的授权
• 多个 middleware 实例
• 精细的权限控制

配置

GinJWTMiddleware 结构体提供以下配置选项：