Go API: Authorization with JWT Middleware

package config

import (
    "fmt"
    "os"
)

type AuthConfig struct {
    Domain   string
    Audience string
}

func LoadAuthConfig() (*AuthConfig, error) {
    domain := os.Getenv("AUTH0_DOMAIN")
    if domain == "" {
        return nil, fmt.Errorf("AUTH0_DOMAIN environment variable required")
    }

    audience := os.Getenv("AUTH0_AUDIENCE")
    if audience == "" {
        return nil, fmt.Errorf("AUTH0_AUDIENCE environment variable required")
    }

    return &AuthConfig{
        Domain:   domain,
        Audience: audience,
    }, nil
}

package auth

import (
    "context"
    "fmt"
    "strings"
)

// CustomClaims contains custom data we want to parse from the JWT.
type CustomClaims struct {
    Scope string `json:"scope"`
}

// Validate ensures the custom claims are properly formatted.
func (c *CustomClaims) Validate(ctx context.Context) error {
    // Scope is optional, but if present, must be properly formatted
    if c.Scope == "" {
        return nil // No scope is valid - not all endpoints require permissions
    }

    // Validate scope format (no leading/trailing spaces, no double spaces)
    if strings.TrimSpace(c.Scope) != c.Scope {
        return fmt.Errorf("scope claim has invalid whitespace")
    }

    if strings.Contains(c.Scope, "  ") {
        return fmt.Errorf("scope claim contains double spaces")
    }

    return nil
}

// HasScope checks whether our claims have a specific scope.
func (c *CustomClaims) HasScope(expectedScope string) bool {
    if c.Scope == "" {
        return false
    }

    scopes := strings.Split(c.Scope, " ")
    for _, scope := range scopes {
        if scope == expectedScope {
            return true
        }
    }
    return false
}

package auth

import (
    "fmt"
    "net/url"
    "time"

    "github.com/auth0/go-jwt-middleware/v3/jwks"
    "github.com/auth0/go-jwt-middleware/v3/validator"
)

func NewValidator(domain, audience string) (*validator.Validator, error) {
    // Construct issuer URL (must include trailing slash)
    issuerURL, err := url.Parse("https://" + domain + "/")
    if err != nil {
        return nil, fmt.Errorf("failed to parse issuer URL: %w", err)
    }

    // Initialize JWKS provider using v3 options pattern
    provider, err := jwks.NewCachingProvider(
        jwks.WithIssuerURL(issuerURL),
        jwks.WithCacheTTL(5*time.Minute),
    )
    if err != nil {
        return nil, fmt.Errorf("failed to create JWKS provider: %w", err)
    }

    // Create validator using v3 options pattern
    jwtValidator, err := validator.New(
        validator.WithKeyFunc(provider.KeyFunc),         // Provides public keys for RS256
        validator.WithAlgorithm(validator.RS256),        // Algorithm (prevents confusion attacks)
        validator.WithIssuer(issuerURL.String()),        // Validates 'iss' claim
        validator.WithAudience(audience),                // Validates 'aud' claim
        validator.WithCustomClaims(func() validator.CustomClaims {
            return &CustomClaims{}                       // Returns our custom claims from claims.go
        }),
        validator.WithAllowedClockSkew(30*time.Second),  // Allows 30s clock drift
    )
    if err != nil {
        return nil, fmt.Errorf("failed to create validator: %w", err)
    }

    return jwtValidator, nil
}

package auth

import (
    "log/slog"
    "net/http"

    jwtmiddleware "github.com/auth0/go-jwt-middleware/v3"
    "github.com/auth0/go-jwt-middleware/v3/validator"
)

func NewMiddleware(jwtValidator *validator.Validator) (*jwtmiddleware.JWTMiddleware, error) {
    return jwtmiddleware.New(
        jwtmiddleware.WithValidator(jwtValidator),
        jwtmiddleware.WithValidateOnOptions(false),
        jwtmiddleware.WithErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) {
            slog.Error("JWT validation failed", "error", err, "path", r.URL.Path)
            w.Header().Set("Content-Type", "application/json")
            w.WriteHeader(http.StatusUnauthorized)
            w.Write([]byte(`{"message":"Failed to validate JWT."}`))
        }),
    )
}

package handlers

import (
    "encoding/json"
    "net/http"

    "github.com/yourorg/myapi/internal/auth"
    jwtmiddleware "github.com/auth0/go-jwt-middleware/v3"
    "github.com/auth0/go-jwt-middleware/v3/validator"
)

// PublicHandler - no authentication required
func PublicHandler(w http.ResponseWriter, r *http.Request) {
    response := map[string]string{
        "message": "Hello from a public endpoint! You don't need to be authenticated to see this.",
    }
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(response)
}

// PrivateHandler - requires valid JWT
func PrivateHandler(w http.ResponseWriter, r *http.Request) {
    response := map[string]string{
        "message": "Hello from a private endpoint! You need to be authenticated to see this.",
    }
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(response)
}

// ScopedHandler - requires 'read:messages' permission
func ScopedHandler(w http.ResponseWriter, r *http.Request) {
    // Extract validated claims using generics (v3 feature)
    claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
    if err != nil {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusUnauthorized)
        w.Write([]byte(`{"message":"Unauthorized."}`))
        return
    }

    // Check for required scope in custom claims
    customClaims, ok := claims.CustomClaims.(*auth.CustomClaims)
    if !ok || !customClaims.HasScope("read:messages") {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusForbidden)
        w.Write([]byte(`{"message":"Insufficient scope."}`))
        return
    }

    response := map[string]string{
        "message": "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.",
    }
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(response)
}

package main

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

    "github.com/yourorg/myapi/internal/auth"
    "github.com/yourorg/myapi/internal/config"
    "github.com/yourorg/myapi/internal/handlers"
    "github.com/joho/godotenv"
)

func main() {
    // Load environment variables from .env file
    if err := godotenv.Load(); err != nil {
        log.Println("No .env file found, using environment variables")
    }

    // Load Auth0 configuration
    cfg, err := config.LoadAuthConfig()
    if err != nil {
        log.Fatalf("Failed to load config: %v", err)
    }

    // Create JWT validator
    jwtValidator, err := auth.NewValidator(cfg.Domain, cfg.Audience)
    if err != nil {
        log.Fatalf("Failed to create validator: %v", err)
    }

    // Create HTTP middleware
    middleware, err := auth.NewMiddleware(jwtValidator)
    if err != nil {
        log.Fatalf("Failed to create middleware: %v", err)
    }

    // Setup routes
    mux := http.NewServeMux()
    mux.HandleFunc("/api/public", handlers.PublicHandler)
    mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(handlers.PrivateHandler)))
    mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(handlers.ScopedHandler)))

    // Configure server with production timeouts
    srv := &http.Server{
        Addr:         ":8080",
        Handler:      mux,
        ReadTimeout:  15 * time.Second,
        WriteTimeout: 15 * time.Second,
        IdleTimeout:  60 * time.Second,
    }

    // Start server in goroutine
    go func() {
        log.Println("Server starting on :8080")
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatalf("Server failed: %v", err)
        }
    }()

    // Graceful shutdown
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, os.Interrupt)
    <-quit

    log.Println("Shutting down server...")
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil {
        log.Fatalf("Server forced to shutdown: %v", err)
    }

    log.Println("Server exited")
}