JWT 认证(Auth)

JWT 认证组件

jwt 是基于 golang-jwt 封装的 Token 管理组件，提供完整的 JWT 生成和解析功能。

核心功能：

• 支持 HS256/HS384/HS512 等多种签名算法
• 提供完整的 Token 生命周期管理
• 内置 Token 校验和过期检查机制

Token 生成和校验

JWT 组件提供了两种生成和验证 JWT Token 的方式。

One Token

点击查看示例代码

package main

import (
    "github.com/go-dev-frame/sponge/pkg/jwt"
    "time"
)

func main() {
    uid := "123"

    // 示例 1: 默认设置, signKey, signMethod(HS256), expiry time(24 hour)
    {
        // generate token
        jwtID, token, err := jwt.GenerateToken(uid)

        // validate token, get claims
        claims, err := jwt.ValidateToken(token)

        // refresh token
        //jwtID, newToken, err := jwt.RefreshToken(token)
    }

    // 示例 2: 自定义设置, signMethod, signKey, expiry time, fields, claims
    {
        now := time.Now()
        signMethod := jwt.HS384
        signKey := "your-secret-key"

        // generate token
        jwtID, token, err := jwt.GenerateToken(
            uid,
            jwt.WithGenerateTokenSignMethod(signMethod),
            jwt.WithGenerateTokenSignKey(signKey),
            jwt.WithGenerateTokenFields(map[string]interface{}{
                "name": "john",
                "role": "admin",
            }),
            jwt.WithGenerateTokenClaims([]jwt.RegisteredClaimsOption{
                jwt.WithExpires(time.Hour * 12),
                jwt.WithIssuedAt(now),
                // jwt.WithSubject("123"),
                // jwt.WithIssuer("https://auth.example.com"),
                // jwt.WithAudience("https://api.example.com"),
                // jwt.WithNotBefore(now),
                // jwt.WithJwtID("abc1234xxx"),
            }...),
        )

        // validate token, get claims
        claims, err := jwt.ValidateToken(token)

        // refresh token
        //jwtID, newToken, err := jwt.RefreshToken(
        //    token,
        //    jwt.WithRefreshTokenSignKey(signKey),
        //    jwt.WithRefreshTokenExpire(time.Hour*12),
        //)
    }
}

Tip: jwtID用于防止重放攻击。 如果您需要将用户踢下线，您可以将其添加到黑名单中，并在下次请求时直接拒绝。

Two Tokens

点击查看示例代码

package main

import (
    "github.com/go-dev-frame/sponge/pkg/jwt"
    "time"
)

func main() {
    uid := "123"

    // 示例 1: 默认设置, signKey, signMethod(HS256), expiry time(24 hour)
    {
        // generate token
        tokens, err := jwt.GenerateTwoTokens(uid)

        // validate token, get claims
        claims, err := jwt.ValidateToken(tokens.AccessToken)

        // refresh token, get new access token, if refresh token is expired time is less than 3 hours, will refresh token too.
        //newAccessTokens, err := jwt.RefreshTwoTokens(tokens.RefreshToken, tokens.AccessToken)
    }

    // 示例 2: 自定义设置, signMethod, signKey, expiry time, fields, claims
    {
        now := time.Now()
        signMethod := jwt.HS384
        signKey := "your-secret-key"

        // generate token
        tokens, err := jwt.GenerateTwoTokens(
            uid,
            jwt.WithGenerateTwoTokensSignMethod(signMethod),
            jwt.WithGenerateTwoTokensSignKey(signKey),
            jwt.WithGenerateTwoTokensFields(map[string]interface{}{
                "name": "john",
                "role": "admin",
            }),
            jwt.WithGenerateTwoTokensRefreshTokenClaims([]jwt.RegisteredClaimsOption{
                jwt.WithExpires(time.Hour * 24 * 15),
                jwt.WithIssuedAt(now),
                // jwt.WithSubject("123"),
                // jwt.WithIssuer("https://auth.example.com"),
                // jwt.WithAudience("https://api.example.com"),
                // jwt.WithNotBefore(now),
                // jwt.WithJwtID("abc1234xxx"),
            }...),
            jwt.WithGenerateTwoTokensAccessTokenClaims([]jwt.RegisteredClaimsOption{
                jwt.WithExpires(time.Minute * 15),
                jwt.WithIssuedAt(now),
                // jwt.WithSubject("123"),
                // jwt.WithIssuer("https://auth.example.com"),
                // jwt.WithAudience("https://api.example.com"),
                // jwt.WithNotBefore(now),
                // jwt.WithJwtID("abc1234xxx"),
            }...),
        )

        // validate token, get claims
        claims, err := jwt.ValidateToken(tokens.AccessToken)

        // refresh token
        newTokens, err := jwt.RefreshTwoTokens(
            tokens.RefreshToken,
            tokens.AccessToken,
            jwt.WithRefreshTwoTokensSignKey(signKey),
            jwt.WithRefreshTwoTokensRefreshTokenExpires(time.Hour*24*15),
            jwt.WithRefreshTwoTokensAccessTokenExpires(time.Minute*15),
        )
    }
}

框架集成

Gin

提供开箱即用的 JWT 认证中间件，支持路由级权限控制。点击查看 在 Gin 中使用 JWT 示例。

gRPC

提供 gRPC 拦截器实现，支持服务/方法级 JWT 认证。点击查看 在 gRPC 使用 JWT 示例。