Overview of JSON Web Tokens

A JSON Web Token (JWT) is defined by the OpenID Foundasion under the RFC 7519 specification. It serves as a compact, URL-safe means of representing claims to be transferred between two parties. While the format is based on JSON, the token itself contains cryptographic signatures, allowing for the transmission of information securely. Although the standard supports encryption algorithms for confidentiality, the most common usage involves signed tokens, which guarantee integrity.

Core Application Scenarios

In modern distributed architectures, JWTs address several critical needs:

• Stateless Authentication: Unlike traditional session stores held on the server, JWTs carry the authentication state. This makes them ideal for microservices where scaling out requires avoiding shared session databases.
• Secure Information Transfer: Developers can embed arbitrary JSON objects within the payload (Claims), facilitating the safe passage of configuration data or user metadata alongside authorization tokens.
• Decoupled Authorization: By verifying the digital signature rather than database lookups, services can quickly determine if a user is authorized to access resources without complex backend handshakes.

Structural Anatomy

A JWT consists of three distinct strings separated by periods (.). Each segment is encoded using Base64Url encoding.

1. The Header: Contains metadata regarding the token type and the signing algorithm used. For instance, the algorithm might be HMAC SHA-256 (HS256) or RSA (RS256).
2. The Payload: This holds the claims. Claims are categorized into registered claims (standardized keys like exp, iat), public claims (customizable but standardized meanings), and private claims (application-specific data). Care must be taken not to store sensitive information like passwords here, as the payload is merely encoded, not encrypted.
3. The Signature: Used to verify the sender's identity and ensure the message hasn't been altered. This is created by signing the encoded header and payload using a secret key (for symmetric algorithms) or a private key (for asymmetric algorithms).

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Implementation in Golang

To build robust JWT systems in Go, we utilize libraries such as github.com/golang-jwt/jwt/v5. Below is a structured approach to handling token lifecycle management, including creation, verification, and middleware integration.

Dependency Setup

Ensure your module references the official jwt package:

go get github.com/golang-jwt/jwt/v5

Cryptographic Key Configuration

Security relies heavily on the strength of the secret key used for signing. This should never be hardcoded in production; environment variables or secrets managers are preferred.

package main

import (
	"crypto/rand"
	"encoding/hex"
	"log"
	"net/http"
	"time"

	jwt "github.com/golang-jwt/jwt/v5"
)

// generateSecret creates a secure random key if one does not exist.
func init() {
	key := make([]byte, 32)
	if _, err := rand.Read(key); err != nil {
		log.Fatal("Failed to generate random key")
	}
	JWT_SECRET = hex.EncodeToString(key)
}

var JWT_SECRET []byte

Defining User Claims

Rather than using generic maps, defining a custom struct for claims offers better type safety.

type CustomClaims struct {
	UserID   int    `json:"user_id"`
	Username string `json:"username"`
	jwt.RegisteredClaims
}

Token Generation Logic

The following function constructs a new token, populates the claims, sets expiration, and signs the payload using HMAC-SHA256.

// CreateToken generates a new JWT for an authenticated user.
func CreateToken(userID int, username string) (string, error) {
	expirationTime := time.Now().Add(15 * time.Minute)
	
	claims := &CustomClaims{
		UserID:   userID,
		Username: username,
		RegisteredClaims: jwt.RegisteredClaims{
			ExpiresAt: jwt.NewNumericDate(expirationTime),
			IssuedAt:  jwt.NewNumericDate(time.Now()),
		},
	}

	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	return token.SignedString(JWT_SECRET)
}

Token Validation Middleware

To protect endpoints, implement an HTTP middleware that intercepts requests, extracts the bearer token from headers, validates the signature, and checks expiration.

// AuthMiddleware handles JWT validation for protected routes.
func AuthMiddleware(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		authHeader := r.Header.Get("Authorization")
		
		if authHeader == "" || len(authHeader) < 7 || authHeader[:7] != "Bearer " {
			http.Error(w, "Missing or malformed Authorization header", http.StatusUnauthorized)
			return
		}

		tokenString := authHeader[7:]
		token, err := jwt.ParseWithClaims(tokenString, &CustomClaims{}, func(token *jwt.Token) (interface{}, error) {
			if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
				return nil, jwt.ErrSignatureInvalid
			}
			return JWT_SECRET, nil
		})

		if err != nil || !token.Valid {
			http.Error(w, "Invalid or expired token", http.StatusUnauthorized)
			return
		}

		next(w, r)
	}
}

Routing and Handler Integration

Below is a complete server setup integrating login, registration, and protected resource retrieval.

func HandleLogin(w http.ResponseWriter, r *http.Request) {
	userID := 101
	username := "developer_go"

	tokenStr, err := CreateToken(userID, username)
	if err != nil {
		http.Error(w, "Internal Server Error", http.StatusInternalServerError)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(map[string]string{"access_token": tokenStr})
}

func HandleProtectedResource(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("Access granted: You are querying protected data."))
}

func main() {
	http.HandleFunc("/auth/login", HandleLogin)
	
	protectedHandler := func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Welcome to the secure dashboard!"))
	}
	
	http.HandleFunc("/dashboard", AuthMiddleware(http.HandlerFunc(HandleProtectedResource)))

	log.Println("Server starting on :8080")
	if err := http.ListenAndServe(":8080", nil); err != nil {
		log.Fatal(err)
	}
}

Handling Expiration and Refresh

Short-lived access tokens are crucial for security. If a token expires during an API call, the verification step in parseToken will fail, returning a non-zero error. In production environments, its recommended to pair access tokens with refresh tokens, stored securely, to issue new access tokens without forcing re-authentication.