goJwt

README

[!Note] This content is translated by LLM. Original text can be found here

JWT Authentication

A Golang JWT authentication library providing access and refresh tokens with fingerprint recognition, Redis storage, and automatic refresh functionality.

Key Features

Dual Token System

Access Token paired with Refresh ID, featuring an automatic refresh mechanism.

Device Fingerprint Recognition

Generates a unique fingerprint based on User-Agent, Device ID, operating system, and browser to prevent token misuse across devices.

Security Measures

Token revocation, version control, intelligent refresh, and concurrency protection using Redis locking.

Flowchart

Click to view

flowchart TD
  Start([Request Start]) --> Auth{Has Access Token?}
  Auth -->|Yes| CheckRevoke[Check if token is revoked]
  Auth -->|No| HasRefresh{Has Refresh ID?}
  HasRefresh -->|No| Unauthorized[Return 401 Unauthorized]
  HasRefresh -->|Yes| ValidateRefresh[Validate Refresh ID]
  CheckRevoke --> IsRevoked{Token revoked?}
  IsRevoked -->|Yes| Unauthorized
  IsRevoked -->|No| ParseToken[Parse access token]
  ParseToken --> TokenValid{Token valid?}
  TokenValid -->|Yes| ValidateClaims[Validate claims]
  TokenValid -->|No| IsExpired{Token expired?}
  IsExpired -->|Yes| ParseExpiredToken[Parse expired token]
  IsExpired -->|No| InvalidToken[Return 400 Invalid Token]
  ParseExpiredToken --> ValidateExpiredClaims[Validate expired token claims]
  ValidateExpiredClaims --> ExpiredClaimsValid{Refresh ID and fingerprint match?}
  ExpiredClaimsValid -->|No| InvalidClaims[Return 400 Invalid Claims]
  ExpiredClaimsValid -->|Yes| RefreshFlow[Enter refresh flow]
  ValidateClaims --> ClaimsValid{Claims match?}
  ClaimsValid -->|No| InvalidClaims
  ClaimsValid -->|Yes| CheckJTI[Check JTI]
  CheckJTI --> JTIValid{JTI valid?}
  JTIValid -->|No| Unauthorized
  JTIValid -->|Yes| Success[Return 200 Success]
  ValidateRefresh --> RefreshValid{Refresh ID valid?}
  RefreshValid -->|No| Unauthorized
  RefreshValid -->|Yes| RefreshFlow
  RefreshFlow --> AcquireLock[Acquire refresh lock]
  AcquireLock --> LockSuccess{Lock acquired?}
  LockSuccess -->|No| TooManyRequests[Return 429 Too Many Requests]
  LockSuccess -->|Yes| GetRefreshData[Get refresh data]
  GetRefreshData --> CheckTTL[Check TTL]
  CheckTTL --> NeedNewRefresh{Need new Refresh ID?}
  NeedNewRefresh -->|Yes| CreateNewRefresh[Create new Refresh ID]
  NeedNewRefresh -->|No| UpdateVersion[Update version number]
  CreateNewRefresh --> SetOldRefreshExpire[Set old Refresh ID to expire in 5 seconds]
  SetOldRefreshExpire --> SetNewRefreshData[Set new refresh data]
  UpdateVersion --> SetNewRefreshData
  SetNewRefreshData --> CheckUserExists{Check if user exists}
  CheckUserExists -->|No| Unauthorized
  CheckUserExists -->|Yes| GenerateNewToken[Generate new access token]
  GenerateNewToken --> StoreJTI[Store new JTI]
  StoreJTI --> SetCookies[Set Cookies]
  SetCookies --> ReleaseLock[Release lock]
  ReleaseLock --> RefreshSuccess[Return refresh success]

Dependencies

• github.com/gin-gonic/gin
• github.com/golang-jwt/jwt/v5
• github.com/redis/go-redis/v9
• github.com/pardnchiu/go-logger (< v0.3.1)
  Starting from v0.3.1, non-standard libraries are deprecated for performance and stability. Replaced with log/slog.

Usage

Installation

go get github.com/pardnchiu/go-jwt

Initialization

package main

import (
  "log"
  "net/http"
  
  "github.com/gin-gonic/gin"
  goJwt "github.com/pardnchiu/go-jwt"
)

func main() {
  config := goJwt.Config{
    Redis: goJwt.Redis{
      Host:     "localhost",
      Port:     6379,
      Password: "password",
      DB:       0,
    },
    CheckAuth: func(userData goJwt.Auth) (bool, error) {
      // Custom user validation logic
      return userData.ID != "", nil
    },
  }

  auth, err := goJwt.New(config)
  if err != nil {
    log.Fatal("Initialization failed:", err)
  }
  defer auth.Close()

  r := gin.Default()

  // Login endpoint
  r.POST("/login", func(c *gin.Context) {
    // After validating login credentials...
    user := &goJwt.Auth{
      ID:    "user123",
      Name:  "John Doe",
      Email: "john@example.com",
      Scope: []string{"read", "write"},
    }

    result := auth.Create(c.Writer, c.Request, user)
    if !result.Success {
      c.JSON(result.StatusCode, gin.H{"error": result.Error})
      return
    }

    c.JSON(http.StatusOK, gin.H{
      "success": true,
      "token":   result.Token.Token,
      "user":    result.Data,
    })
  })

  // Protected routes
  protected := r.Group("/api")
  protected.Use(auth.GinMiddleware())
  {
    protected.GET("/profile", func(c *gin.Context) {
      user, _ := goJwt.GetAuthDataFromGinContext(c)
      c.JSON(http.StatusOK, gin.H{"user": user})
    })
  }

  // Logout
  r.POST("/logout", func(c *gin.Context) {
    result := auth.Revoke(c.Writer, c.Request)
    if !result.Success {
      c.JSON(result.StatusCode, gin.H{"error": result.Error})
      return
    }
    c.JSON(http.StatusOK, gin.H{"message": "Logged out successfully"})
  })

  r.Run(":8080")
}

Configuration

type Config struct {
  Redis     Redis                    // Redis configuration (required)
  File      *File                    // File configuration for key management (optional)
  Option    *Option                  // System parameters and token settings (optional)
  Cookie    *Cookie                  // Cookie security settings (optional)
  CheckAuth func(Auth) (bool, error) // User authentication function (optional)
}

type Redis struct {
  Host     string // Redis server host address (required)
  Port     int    // Redis server port number (required)
  Password string // Redis authentication password (optional, empty string means no auth)
  DB       int    // Redis database index (required, usually 0-15)
}

type File struct {
  PrivateKeyPath string // ECDSA private key file path for JWT signing
  PublicKeyPath  string // ECDSA public key file path for JWT verification
}

type Option struct {
  PrivateKey           string        // ECDSA private key content (auto-generates P-256 if not provided)
  PublicKey            string        // ECDSA public key content (auto-generates P-256 if not provided)
  AccessTokenExpires   time.Duration // Access token expiration time (default: 15 minutes)
  RefreshIdExpires     time.Duration // Refresh ID expiration time (default: 7 days)
  AccessTokenCookieKey string        // Access token cookie name (default: "access_token")
  RefreshIdCookieKey   string        // Refresh ID cookie name (default: "refresh_id")
  MaxVersion           int           // Maximum version count for refresh tokens (default: 5)
  RefreshTTL           float64       // Refresh threshold as proportion of TTL (default: 0.5)
}

type Cookie struct {
  Domain   *string        // Cookie domain scope (nil means current domain)
  Path     *string        // Cookie path scope (default: "/")
  SameSite *http.SameSite // Cookie SameSite policy (default: Lax for CSRF prevention)
  Secure   *bool          // Cookie secure flag, HTTPS only (default: false)
  HttpOnly *bool          // Cookie HttpOnly flag for XSS prevention (default: true)
}

Available Functions

Instance Management

• New() - Create a new instance

  auth, err := goJwt.New(config)
  

  • Initializes Redis connection
  • Auto-generates ECDSA keys if not provided
  • Validates configuration

• Close() - Close the instance

  err := auth.Close()
  

  • Closes Redis connection
  • Releases system resources

JWT Management

• Create() - Generate a new JWT

  result := auth.Create(w, r, userData)
  

  • Generates access token and refresh ID
  • Sets secure cookies
  • Stores session data in Redis

• Verify() - Verify JWT

  result := auth.Verify(w, r)
  

  • Parses and validates JWT token
  • Checks device fingerprint
  • Automatically refreshes if needed
  • Returns user data

• Revoke() - Terminate JWT

  result := auth.Revoke(w, r)
  

  • Clears cookies
  • Adds token to blacklist
  • Updates Redis records

Middleware

// Gin framework middleware
protected.Use(auth.GinMiddleware())

// Standard HTTP middleware
server := &http.Server{
  Handler: auth.HTTPMiddleware(handler),
}

// Get user data from context
user, exists := goJwt.GetAuthDataFromGinContext(c)
user, exists := goJwt.GetAuthDataFromHTTPRequest(r)

Supports Multiple Authentication Methods

Custom Headers

r.Header.Set("X-Device-FP", fingerprint)
r.Header.Set("X-Refresh-ID", refreshID)
r.Header.Set("Authorization", "Bearer "+token)

Automatic Cookie Management

access_token, refresh_id cookies

Error Handling

All methods return a JWTAuthResult structure

type JWTAuthResult struct {
  StatusCode int          // HTTP status code
  Success    bool         // Whether operation succeeded
  Data       *Auth        // User data
  Token      *TokenResult // Token information
  Error      string       // Error message
  ErrorTag   string       // Error category tag
}

Error Tags

• data_missing - Missing required data
• data_invalid - Invalid data format
• unauthorized - Authentication failed
• revoked - Token revoked
• failed_to_update - Update operation failed
• failed_to_create - Creation operation failed
• failed_to_sign - Token signing failed
• failed_to_store - Storage operation failed
• failed_to_get - Retrieval operation failed

License

This project is licensed under the MIT license.

Author

邱敬幃 Pardn Chiu

---

©️ 2025 邱敬幃 Pardn Chiu

Documentation

Index

• type Auth
  • func GetAuthDataFromGinContext(c *gin.Context) (*Auth, bool)
  • func GetAuthDataFromHTTPRequest(r *http.Request) (*Auth, bool)
• type Config
• type Cookie
• type File
• type JWTAuth
  • func New(c Config) (*JWTAuth, error)
  • func (j *JWTAuth) Close() error
  • func (j *JWTAuth) Create(w http.ResponseWriter, r *http.Request, auth *Auth) JWTAuthResult
  • func (j *JWTAuth) GinMiddleware() gin.HandlerFunc
  • func (j *JWTAuth) HTTPMiddleware(next http.Handler) http.Handler
  • func (j *JWTAuth) Revoke(w http.ResponseWriter, r *http.Request) JWTAuthResult
  • func (j *JWTAuth) Verify(w http.ResponseWriter, r *http.Request) JWTAuthResult
• type JWTAuthResult
• type Option
• type Pem
• type Redis
• type RefreshData
• type RefreshId
• type TokenResult

Types

type Auth

type Auth struct {
	ID        string   `json:"id"`
	Name      string   `json:"name"`
	Email     string   `json:"email"`
	Thumbnail string   `json:"thumbnail,omitempty"`
	Scope     []string `json:"scope,omitempty"`
	Role      string   `json:"role,omitempty"`
	Level     int      `json:"level,omitempty"`
}

func GetAuthDataFromGinContext

func GetAuthDataFromGinContext(c *gin.Context) (*Auth, bool)

func GetAuthDataFromHTTPRequest

func GetAuthDataFromHTTPRequest(r *http.Request) (*Auth, bool)

type Config

type Config struct {
	Redis Redis `json:"redis"`          // Redis 設定
	File  *File `json:"file,omitempty"` // 檔案設定
	// Log       *Log                     `json:"log,omitempty"`       // 日誌設定
	Option    *Option                  `json:"parameter,omitempty"` // 可調參數
	Cookie    *Cookie                  `json:"cookie,omitempty"`    // Cookie 設定
	CheckAuth func(Auth) (bool, error) `json:"-"`                   // 檢查使用者是否存在的函數
}

type Cookie

type Cookie struct {
	Domain   *string        `json:"domain,omitempty"`    // Cookie 的網域
	Path     *string        `json:"path,omitempty"`      // Cookie 的路徑，預設 /
	SameSite *http.SameSite `json:"same_site,omitempty"` // Cookie 的 SameSite 屬性，預設 lax
	Secure   *bool          `json:"secure,omitempty"`    // Cookie 是否安全，預設 false
	HttpOnly *bool          `json:"http_only,omitempty"` // Cookie 是否 HttpOnly，預設 true
}

type File

type File struct {
	PrivateKeyPath string `json:"private_key_path,omitempty"`
	PublicKeyPath  string `json:"public_key_path,omitempty"`
}

type JWTAuth

type JWTAuth struct {
	// contains filtered or unexported fields
}

func New

func New(c Config) (*JWTAuth, error)

func (*JWTAuth) Close

func (j *JWTAuth) Close() error

func (*JWTAuth) Create

func (j *JWTAuth) Create(w http.ResponseWriter, r *http.Request, auth *Auth) JWTAuthResult

func (*JWTAuth) GinMiddleware

func (j *JWTAuth) GinMiddleware() gin.HandlerFunc

func (*JWTAuth) HTTPMiddleware

func (j *JWTAuth) HTTPMiddleware(next http.Handler) http.Handler

func (*JWTAuth) Revoke

func (j *JWTAuth) Revoke(w http.ResponseWriter, r *http.Request) JWTAuthResult

func (*JWTAuth) Verify

func (j *JWTAuth) Verify(w http.ResponseWriter, r *http.Request) JWTAuthResult

type JWTAuthResult

type JWTAuthResult struct {
	StatusCode int          `json:"status_code"`
	Success    bool         `json:"success"`
	Data       *Auth        `json:"data,omitempty"`
	Token      *TokenResult `json:"token,omitempty"`
	Error      string       `json:"error,omitempty"`
	ErrorTag   string       `json:"error_tag,omitempty"`
}

type Option

type Option struct {
	PrivateKey           string        `json:"private_key,omitempty"`             // 私鑰內容
	PublicKey            string        `json:"public_key,omitempty"`              // 公鑰內容
	AccessTokenExpires   time.Duration `json:"access_token_expires,omitempty"`    // Access Token 有效期限，預設 15 分鐘
	RefreshIdExpires     time.Duration `json:"refresh_id_expires,omitempty"`      // Refresh ID 有效期限，預設 7 天
	AccessTokenCookieKey string        `json:"access_token_cookie_key,omitempty"` // Access Token Cookie 鍵名，預設 access_token
	RefreshIdCookieKey   string        `json:"refresh_id_cookie_key,omitempty"`   // Refresh ID Cookie 鍵名，預設 refresh_id
	MaxVersion           int           `json:"max_version,omitempty"`             // 重刷 Refresh ID 次數，預設 5（更換 5 次 Access Token 後，Refresh ID 會被重刷）
	RefreshTTL           float64       `json:"refresh_ttl,omitempty"`             // 刷新 Refresh ID 的 TTL 閾值，預設 0.5（低於一半時間）
}

type Pem

type Pem struct {
	// contains filtered or unexported fields
}

type Redis

type Redis struct {
	Host     string `json:"host"`               // Redis 主機位址
	Port     int    `json:"port"`               // Redis 連接埠
	Password string `json:"password,omitempty"` // Redis 密碼
	DB       int    `json:"db"`                 // Redis 資料庫編號
}

type RefreshData

type RefreshData struct {
	Data        *Auth  `json:"data,omitempty"`
	Version     int    `json:"version"`
	Fingerprint string `json:"fp"`
	Exp         int64  `json:"exp"`
	Iat         int64  `json:"iat"`
	Jti         string `json:"jti"`
}

type RefreshId

type RefreshId struct {
	ID          string `json:"id"`    // 使用者 ID
	Name        string `json:"name"`  // 使用者名稱
	Email       string `json:"email"` // 電子郵件
	Fingerprint string `json:"fp"`    // 設備指紋
	Iat         int64  `json:"iat"`   // 發行時間
	Jti         string `json:"jti"`   // JWT ID
}

Refresh Data ID 結構

type TokenResult

type TokenResult struct {
	Token     string `json:"token"`
	RefreshId string `json:"refresh_id"`
}