Implementing Golang Authentication with JWT (JSON Web Tokens)

Modern web applications need secure and efficient user authentication. One of the best ways for stateless authentication is JSON Web Tokens (JWT) which makes communication between clients and servers secure. JWT gets rid of the need for server-side session management by packing user claims in a compact, self-contained token. This boosts performance and scalability of applications.

Golang (Go) is a great choice for implementing JWT-based authentication due to its speed and simplicity. Its simple syntax, strong standard library, and efficient concurrency model help developers build safe and fast authentication systems. The built-in support for cryptographic functions makes Golang easier to encode, decode, and validate JWTs.

This blog shows how to implement JWT authentication in Golang safely and effectively step by step!

>> You may consider:

• An Ultimate Guide To Web Application Security for Businesses
• Mastering 6 Golang Concurrency Patterns to Level Up Your Apps

What is JWT (JSON Web Tokens)?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and URL-safe format for securely transmitting information as a JSON object. JWTs can be digitally signed or encrypted to ensure the integrity and authenticity of the data they carry, making them a reliable solution for secure communication.

How JWTs Work for Stateless Authentication?

JWTs simplify stateless authentication because the server does not need to store session data.

• Token Creation: When a user logs in, the server generates a token with user claims (e.g., user ID, roles, permissions) and signs it with a secret key or public/private key pair.
• Client Storage: The token is stored on the client side, often in localStorage or as an HTTP-only cookie, and sent with each request (e.g., in the Authorization header).
• Server Verification: The server validates the token’s signature to confirm the user’s identity and permissions without storing session data or querying a database.

JWTs are commonly used in:

• API Authentication: Secure access to protected endpoints.
• Session Management: Embed session data in the token itself, eliminating server-side session storage.
• Authorization: Carry roles and permissions for resource access control.

>> Read more:

• Gin-Gonic Tutorial: API Development in Go Using Gin Framework
• What is An API? An Ultimate Guide for API Development

Understanding JWT Structure

A JSON Web Token (JWT) is composed of three parts: Header, Payload, and Signature. These components are encoded separately using Base64URL and and then joined together with periods (.) to form the complete token. Here's a breakdown of each component:

Header

The header contains metadata about the token, including its type and the algorithm used for signing. Typically, the header looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}

• alg: Specifies the signing algorithm, e.g., HMAC SHA-256 (HS256).
• typ: Indicates the type of token, which is always JWT.

Payload

The payload contains the claims, which are statements about the user or additional data. Claims fall into three types:

• Registered claims: Predefined claims like iss (issuer), exp (expiration time), and sub (subject).
• Public claims: Custom claims agreed upon by parties.
• Private claims: Claims shared privately between parties.

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022
}

• sub: Subject identifier (user ID).
• name: Custom claim with the user's name.
• admin: Custom claim indicating admin privileges.
• iat: Issued at timestamp.

Signature

The signature ensures the token's integrity and authenticity. It is generated by taking the encoded header and payload, concatenating them with a period, and signing the result using the specified algorithm and a secret key.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

A Base64URL-encoded string represents the signed header and payload, ensuring that the token hasn't been tampered with.

Understanding these components is crucial for implementing and troubleshooting JWTs in your applications.

Setting Up the Golang Project

Before diving into JWT implementation in Golang, let’s first set up the project environment and install the necessary dependencies.

Prerequisites

To follow along, ensure you have the following:

• Golang installed: Download and install the latest version of Golang from golang.org.
• Basic knowledge of Go modules: Familiarity with go mod for dependency management.

Step 1: Create a New Go Project

• Initialize the project directory: Open your terminal and run the following commands to create and navigate to your project folder:

mkdir go-jwt-auth
cd go-jwt-auth

• Initialize the Go module: Use the go mod init command to create a go.mod file for dependency management:

go mod init github.com/yourusername/go-jwt-auth

This command will create a go.mod file with the module path github.com/yourusername/go-jwt-auth.

Step 2: Add Dependencies

For JWT implementation, we will use the popular github.com/golang-jwt/jwt package. This package provides essential utilities for creating, signing, and verifying JWTs.

• Install the golang-jwt package: Run the following command to add the JWT package as a dependency:

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

This will download the package and update your go.mod and go.sum files.

• Verify the go.mod file: After adding the dependency, your go.mod file should look something like this:

module github.com/yourusername/go-jwt-auth

go 1.20

require github.com/golang-jwt/jwt/v5 v5.0.0

Step 3: Project Structure

Here’s a basic structure for the project:

go-jwt-auth/
├── go.mod
├── go.sum
├── main.go       // Entry point of the application
└── auth/
    └── jwt.go    // JWT-related functions

With the setup complete, you’re now ready to implement JWT-based authentication in your Go project.

Generating a JWT in Golang

Generating a JWT in Golang involves three key steps: defining claims, creating a signing key, and signing the token. Let's walk through each step.

Step 1: Define JWT Claims

JWT claims are statements about an entity (typically user information) and additional metadata. Common claims include:

• sub (subject): Identifies the user.
• exp (expiration time): Sets the token's expiry.
• iat (issued at): Records the token's creation time.

Step 2: Create a Signing Key

To ensure the token's integrity and authenticity, you'll need a signing key. Two common options are:

• HMAC (shared secret key): Efficient and straightforward for most applications.
• RSA (public/private key pair): Ideal when asymmetric signing is required.

Step 3: Sign the Token

Finally, use your chosen signing key to generate the signed JWT.

Code Walkthrough

Here’s an example of generating a JWT in Go using the HMAC SHA-256 algorithm:

package main

import (
	"fmt"
	"time"

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

// CustomClaims defines the structure of the JWT payload
type CustomClaims struct {
	UserID string `json:"user_id"`
	jwt.RegisteredClaims
}

func main() {
	// Define the signing key (HMAC secret)
	signingKey := []byte("your_secret_key")

	// Define the claims
	claims := CustomClaims{
		UserID: "123456", // Custom claim
		RegisteredClaims: jwt.RegisteredClaims{
			Issuer:    "go-jwt-auth",                      // Who issued the token
			ExpiresAt: jwt.NewNumericDate(time.Now().Add(1 * time.Hour)), // Token expiry
			IssuedAt:  jwt.NewNumericDate(time.Now()),     // Token issued time
			Subject:   "auth_token",                       // Subject claim
		},
	}

	// Create a new token with the claims
	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)

	// Sign the token using the signing key
	tokenString, err := token.SignedString(signingKey)
	if err != nil {
		fmt.Println("Error signing token:", err)
		return
	}

	// Print the generated token
	fmt.Println("Generated JWT:", tokenString)
}

Validating and Parsing a Golang JWT

Validation ensures that a JWT is authentic, unaltered, and still valid before granting access. Failing to validate a token could expose your system to unauthorized access or malicious activity. Here's how to validate and parse a JWT in a Golang application:

Extract the Token from an HTTP Request

JWTs are often sent in the Authorization header of HTTP requests in the following format:

Authorization: Bearer <token>

Here’s how to extract the token:

package main

import (
	"fmt"
	"net/http"
	"strings"

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

func extractTokenFromHeader(r *http.Request) (string, error) {
	authHeader := r.Header.Get("Authorization")
	if authHeader == "" {
		return "", fmt.Errorf("missing Authorization header")
	}

	parts := strings.Split(authHeader, " ")
	if len(parts) != 2 || parts[0] != "Bearer" {
		return "", fmt.Errorf("invalid Authorization header format")
	}

	return parts[1], nil
}

Parse and Verify the JWT

Once the token is extracted, it must be parsed and verified using the same signing key that was used to create it.

func validateToken(tokenString string, signingKey []byte) (*jwt.Token, error) {
	// Parse and validate the token
	token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
		// Ensure the token is signed with the expected method
		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
		}
		return signingKey, nil
	})

	if err != nil {
		return nil, fmt.Errorf("invalid token: %v", err)
	}

	// Optionally, check token claims
	if claims, ok := token.Claims.(jwt.MapClaims); ok && token.Valid {
		fmt.Println("Token is valid!")
		fmt.Printf("User ID: %s\n", claims["user_id"])
		return token, nil
	}

	return nil, fmt.Errorf("invalid token claims")
}

Handle Token Expiration and Invalid Tokens

The Parse function automatically checks the exp claim if it's present, and will return an error if the token has expired.

Here’s how you might combine the functions:

func handler(w http.ResponseWriter, r *http.Request) {
	signingKey := []byte("your_secret_key")

	// Extract token from the request
	tokenString, err := extractTokenFromHeader(r)
	if err != nil {
		http.Error(w, err.Error(), http.StatusUnauthorized)
		return
	}

	// Validate and parse the token
	_, err = validateToken(tokenString, signingKey)
	if err != nil {
		http.Error(w, err.Error(), http.StatusUnauthorized)
		return
	}

	// If valid, proceed with the request
	fmt.Fprintf(w, "Welcome! Token is valid.")
}

Protecting Routes with JWT Middleware

In Golang, middleware lets you intercept and process HTTP requests before they get to the end handler. It’s commonly used for tasks like logging, rate-limiting, and, in this case, authentication.

With the net/http package, middleware is implemented as a function that wraps around an http.Handler. Here’s how you can create JWT middleware to protect routes.

Middleware Concept in Go

A middleware function takes an http.Handler as input, processes the request, and either:

• Passes control to the next handler.
• Returns an error response if a condition (like invalid authentication) isn't met.

JWT Middleware Function

The following middleware function validates the JWT in the Authorization header:

package main

import (
	"fmt"
	"net/http"
	"strings"

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

// JWTMiddleware is a middleware function that validates JWTs
func JWTMiddleware(next http.Handler, signingKey []byte) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Extract token from Authorization header
		tokenString, err := extractTokenFromHeader(r)
		if err != nil {
			http.Error(w, "Unauthorized: "+err.Error(), http.StatusUnauthorized)
			return
		}

		// Validate the token
		_, err = validateToken(tokenString, signingKey)
		if err != nil {
			http.Error(w, "Unauthorized: "+err.Error(), http.StatusUnauthorized)
			return
		}

		// Call the next handler if the token is valid
		next.ServeHTTP(w, r)
	})
}

// Extracts JWT from the Authorization header
func extractTokenFromHeader(r *http.Request) (string, error) {
	authHeader := r.Header.Get("Authorization")
	if authHeader == "" {
		return "", fmt.Errorf("missing Authorization header")
	}

	parts := strings.Split(authHeader, " ")
	if len(parts) != 2 || parts[0] != "Bearer" {
		return "", fmt.Errorf("invalid Authorization header format")
	}

	return parts[1], nil
}

// Validates the JWT using the signing key
func validateToken(tokenString string, signingKey []byte) (*jwt.Token, error) {
	token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
		}
		return signingKey, nil
	})

	if err != nil || !token.Valid {
		return nil, fmt.Errorf("invalid token: %v", err)
	}

	return token, nil
}

Protecting API Endpoints

You can use the JWTMiddleware function to protect specific routes:

func main() {
	signingKey := []byte("your_secret_key")

	mux := http.NewServeMux()

	// Public endpoint
	mux.HandleFunc("/public", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "This is a public endpoint.")
	})

	// Protected endpoint
	protectedHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "Welcome! This is a protected endpoint.")
	})

	mux.Handle("/protected", JWTMiddleware(protectedHandler, signingKey))

	// Start the server
	fmt.Println("Server running on http://localhost:8080")
	http.ListenAndServe(":8080", mux)
}

• Public Route: The /public route is accessible without a token.
• Protected Route: The /protected route requires a valid JWT. The JWTMiddleware checks for the token and validates it. If the token is valid, the request proceeds to the handler.
• Middleware Flow:
  • Extract the token from the Authorization header.
  • Validate the token using the secret key.
  • If valid, call the next handler.
  • If invalid, return a 401 Unauthorized response.

Security Best Practices with Golang JWT

Implementing JWT securely is essential to protect your application against vulnerabilities like token tampering or misuse. Here are the key best practices to follow for robust JWT authentication in Golang.

Use Strong Signing Algorithms

JWT supports multiple signing algorithms, but their security varies:

• HS256 (HMAC + SHA-256): Symmetric key algorithm where both parties share the same secret key.
• RS256 (RSA + SHA-256): Asymmetric key algorithm that uses a private key for signing and a public key for verification.

Recommendation: Use RS256 for improved security, especially in distributed systems where only the signing server needs access to the private key.

token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)

Keep Your Secret Keys Safe

The security of JWT relies heavily on the confidentiality of the signing keys. If the secret key (for HS256) or private key (for RS256) is compromised, attackers can fake tokens.

Recommendations:

• Store keys securely using environment variables or secret management tools (e.g., AWS Secrets Manager, HashiCorp Vault).
• Never hard-code keys in your source code.

export JWT_SECRET_KEY="your_secret_key"

signingKey := []byte(os.Getenv("JWT_SECRET_KEY"))

Limit JWT Lifetime

Tokens should have a short lifespan to minimize the risk of misuse if a token is leaked.

Recommendation:

Set the exp (expiration) claim to a reasonable time, such as 15 minutes. Pair this with a refresh token mechanism for extended sessions.

claims := jwt.RegisteredClaims{
    ExpiresAt: jwt.NewNumericDate(time.Now().Add(15 * time.Minute)),
}

Use Secure Storage for JWTs

Where you store JWTs on the client side impacts their security:

• LocalStorage/SessionStorage: Vulnerable to XSS attacks.
• HTTP-only Cookies: Safer as they are not accessible via JavaScript.

Recommendation: Store JWTs in HTTP-only, Secure cookies to prevent XSS attacks and ensure secure transmission.

Handle and Refresh Expired Tokens

Expired tokens must be gracefully handled to avoid user frustration.

Implementation:

• Detect token expiration using the exp claim.
• Use a refresh token (with a longer lifespan) to issue new access tokens without requiring the user to log in again.

if claims, ok := token.Claims.(jwt.MapClaims); ok && !token.Valid {
    if err == jwt.ErrTokenExpired {
        // Handle token refresh
    }
}

Debug Invalid Signature Errors

Invalid signature errors usually occur due to:

• Mismatched signing keys.
• Tampered tokens.

Troubleshooting Steps:

• Ensure the same signing key is used for both signing and validation.
• Verify that token integrity is maintained during transmission.

_, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
    return []byte(signingKey), nil
})
if err != nil {
    fmt.Println("Token validation error:", err)
}

Secure Key Management

Implement key management strategies to prevent unauthorized access:

• Regularly rotate signing keys to limit exposure in case of a breach.
• Load keys from environment variables rather than embedding them in your codebase.
• For RS256, securely distribute the public key to verifying services while keeping the private key confidential.

Example for loading keys securely:

privateKey, err := jwt.ParseRSAPrivateKeyFromPEM([]byte(os.Getenv("PRIVATE_KEY")))
publicKey, err := jwt.ParseRSAPublicKeyFromPEM([]byte(os.Getenv("PUBLIC_KEY")))

If you follow these best practices, you can make the JWT implementation in your Golang app a lot safer. These measures help prevent unauthorized access, token misuse, and key exposure, ensuring a robust and secure authentication system.

>> Read more: Go 1.22: Secure Your Apps with Random Number Generation

Conclusion

To implement Golang JWT authentication, you need to create and validate tokens, secure routes with middleware, and follow key security practices. Additionally, you can make your system more reliable and secure by using strong algorithms, protecting keys, and refreshing token expiration. I hope this guide helps you successfully implement JWT authentication in Golang!

>>> Follow and Contact Relia Software for more information!