OAuth2 and OpenID Connect: Production Security Patterns

package oauth2handler
 
import (
    "context"
    "crypto/rand"
    "crypto/sha256"
    "encoding/base64"
    "net/http"
    "time"
 
    "golang.org/x/oauth2"
)
 
type Handler struct {
    config *oauth2.Config
}
 
// generateCodeVerifier: 32 random bytes, base64-URL-encoded (43 chars).
func generateCodeVerifier() string {
    b := make([]byte, 32)
    rand.Read(b)
    return base64.RawURLEncoding.EncodeToString(b)
}
 
// codeChallenge: SHA256(code_verifier), base64-URL-encoded.
func codeChallenge(verifier string) string {
    h := sha256.Sum256([]byte(verifier))
    return base64.RawURLEncoding.EncodeToString(h[:])
}
 
func (h *Handler) Login(w http.ResponseWriter, r *http.Request) {
    // Generate PKCE verifier, store in httpOnly cookie.
    codeVerifier := generateCodeVerifier()
    http.SetCookie(w, &http.Cookie{
        Name:     "code_verifier",
        Value:    codeVerifier,
        MaxAge:   600, // 10 min expiry (code must be used quickly)
        HttpOnly: true,
        Secure:   true,
        SameSite: http.SameSiteStrictMode,
    })
 
    // Redirect to auth server with code_challenge.
    authURL := h.config.AuthCodeURL(
        generateState(), // CSRF token in URL
        oauth2.SetAuthURLParam("code_challenge", codeChallenge(codeVerifier)),
        oauth2.SetAuthURLParam("code_challenge_method", "S256"),
    )
    http.Redirect(w, r, authURL, http.StatusFound)
}
 
func (h *Handler) Callback(w http.ResponseWriter, r *http.Request) {
    // Extract code_verifier from httpOnly cookie.
    cookie, err := r.Cookie("code_verifier")
    if err != nil || cookie.Value == "" {
        http.Error(w, "missing PKCE verifier", http.StatusBadRequest)
        return
    }
 
    // Exchange authorization code + PKCE verifier for tokens.
    ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
    defer cancel()
 
    token, err := h.config.Exchange(ctx, r.URL.Query().Get("code"),
        oauth2.SetAuthURLParam("code_verifier", cookie.Value),
    )
    if err != nil {
        http.Error(w, "token exchange failed", http.StatusInternalServerError)
        return
    }
 
    // Store access_token + refresh_token in httpOnly cookies.
    setTokenCookies(w, token)
    http.Redirect(w, r, "/dashboard", http.StatusSeeOther)
}
 
func setTokenCookies(w http.ResponseWriter, token *oauth2.Token) {
    // Access token: short-lived (1 hour default).
    http.SetCookie(w, &http.Cookie{
        Name:     "access_token",
        Value:    token.AccessToken,
        MaxAge:   3600,
        HttpOnly: true,
        Secure:   true,
        SameSite: http.SameSiteStrictMode,
    })
 
    // Refresh token: long-lived (30 days, rotated on use).
    http.SetCookie(w, &http.Cookie{
        Name:     "refresh_token",
        Value:    token.RefreshToken,
        MaxAge:   2592000, // 30 days
        HttpOnly: true,
        Secure:   true,
        SameSite: http.SameSiteStrictMode,
    })
}

package tokenrotation
 
import (
    "crypto/sha256"
    "encoding/hex"
    "time"
)
 
type RefreshTokenRecord struct {
    TokenHash    string    // SHA256(refresh_token) — never store raw tokens
    FamilyID     string    // Links rotated tokens; theft = entire family revoked
    UserID       string
    IssuedAt     time.Time
    LastUsedAt   time.Time
    ExpiresAt    time.Time
    IsRevoked    bool
}
 
// IssueRefreshToken: create a new token + hash, store record, return token.
func IssueRefreshToken(userID string, db *DB) (token string, record *RefreshTokenRecord, err error) {
    token = generateSecureRandom(32)
    tokenHash := hashToken(token)
    familyID := generateUUID()
 
    record = &RefreshTokenRecord{
        TokenHash: tokenHash,
        FamilyID:  familyID,
        UserID:    userID,
        IssuedAt:  time.Now(),
        ExpiresAt: time.Now().Add(30 * 24 * time.Hour), // 30-day TTL
    }
 
    if err := db.InsertRefreshToken(record); err != nil {
        return "", nil, err
    }
    return token, record, nil
}
 
// UseRefreshToken: validate + rotate. Return new tokens + detect theft.
func UseRefreshToken(userID, clientToken string, db *DB) (newAccessToken, newRefreshToken string, err error) {
    tokenHash := hashToken(clientToken)
 
    // Look up token by hash.
    record, err := db.GetRefreshTokenByHash(tokenHash)
    if err != nil || record == nil {
        return "", "", ErrInvalidToken
    }
 
    // Token already used? (Reuse = theft detection)
    if !record.LastUsedAt.IsZero() {
        // Revoke entire family — attacker may be in possession.
        db.RevokeTokenFamily(record.FamilyID)
        return "", "", ErrTokenReused // Force user to re-login
    }
 
    // Expired?
    if time.Now().After(record.ExpiresAt) {
        return "", "", ErrTokenExpired
    }
 
    // Mark as used.
    record.LastUsedAt = time.Now()
    db.UpdateRefreshToken(record)
 
    // Issue new tokens (refresh token rotates).
    newRefreshToken, newRecord, err := IssueRefreshToken(userID, db)
    if err != nil {
        return "", "", err
    }
    newRecord.FamilyID = record.FamilyID // Link to the same family
 
    // Issue short-lived access token.
    newAccessToken, err = issueAccessToken(userID, time.Hour)
    if err != nil {
        return "", "", err
    }
 
    return newAccessToken, newRefreshToken, nil
}
 
func hashToken(token string) string {
    h := sha256.Sum256([]byte(token))
    return hex.EncodeToString(h[:])
}

func (h *Handler) ClientCredentials(w http.ResponseWriter, r *http.Request) {
    clientID := r.FormValue("client_id")
    clientSecret := r.FormValue("client_secret")
    scope := r.FormValue("scope") // e.g., "payments:read"
 
    // Authenticate client by secret (bcrypt hash in DB).
    client, err := h.db.GetClientByID(clientID)
    if err != nil || bcrypt.CompareHashAndPassword([]byte(client.SecretHash), []byte(clientSecret)) != nil {
        w.WriteHeader(http.StatusUnauthorized)
        json.NewEncoder(w).Encode(map[string]string{"error": "invalid_client"})
        return
    }
 
    // Verify requested scope is allowed for this client.
    if !client.AllowedScopes.Contains(scope) {
        w.WriteHeader(http.StatusForbidden)
        json.NewEncoder(w).Encode(map[string]string{"error": "invalid_scope"})
        return
    }
 
    // Issue access token (no refresh token for service-to-service).
    accessToken, err := issueAccessToken(clientID, 1*time.Hour)
    if err != nil {
        w.WriteHeader(http.StatusInternalServerError)
        return
    }
 
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]interface{}{
        "access_token": accessToken,
        "token_type":   "Bearer",
        "expires_in":   3600,
    })
}

func ValidateJWT(tokenString string) (*Claims, error) {
    token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
        return publicKey, nil // Pre-fetch JWKS once on startup
    })
    if err != nil {
        return nil, err
    }
    claims, ok := token.Claims.(*Claims)
    if !ok || !token.Valid {
        return nil, ErrInvalidToken
    }
    return claims, nil
}

func ValidateOpaqueToken(tokenString string) (*TokenMetadata, error) {
    // Database call — can be cached with TTL.
    metadata, err := db.GetTokenMetadata(tokenString)
    if err != nil || metadata.IsRevoked {
        return nil, ErrInvalidToken
    }
    return metadata, nil
}

func (h *Handler) Revoke(w http.ResponseWriter, r *http.Request) {
    token := r.FormValue("token")
    tokenTypeHint := r.FormValue("token_type_hint") // "access_token" or "refresh_token"
 
    // Look up and mark revoked in DB.
    tokenHash := hashToken(token)
    if err := h.db.RevokeToken(tokenHash); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }
 
    // For refresh tokens: revoke the entire family.
    if tokenTypeHint == "refresh_token" {
        record, _ := h.db.GetRefreshTokenByHash(tokenHash)
        if record != nil {
            h.db.RevokeTokenFamily(record.FamilyID)
        }
    }
 
    // 200 OK, even if token was already revoked (RFC 7009).
    w.WriteHeader(http.StatusOK)
}

package authn
 
import (
	"context"
	"errors"
	"fmt"
	"sync"
	"sync/atomic"
	"time"
 
	"github.com/MicahParks/keyfunc/v3"
	"github.com/golang-jwt/jwt/v5"
)
 
type JWKSVerifier struct {
	jwks       *keyfunc.JWKS
	jwksURL    string
	expectedIss string
	expectedAud string
 
	// Refresh-on-miss safety net: bound IdP load when many requests
	// arrive with a kid the cache hasn't seen yet (key rotation event).
	mu          sync.Mutex
	lastRefresh atomic.Int64 // unix-millis of last on-demand refresh
}
 
const minRefreshIntervalMs = 30_000 // never re-fetch more than 2× per minute
 
func NewJWKSVerifier(ctx context.Context, jwksURL, iss, aud string) (*JWKSVerifier, error) {
	jwks, err := keyfunc.NewDefaultCtx(ctx, []string{jwksURL})
	if err != nil {
		return nil, fmt.Errorf("jwks bootstrap: %w", err)
	}
	return &JWKSVerifier{jwks: jwks, jwksURL: jwksURL, expectedIss: iss, expectedAud: aud}, nil
}
 
func (v *JWKSVerifier) Verify(ctx context.Context, raw string) (*jwt.RegisteredClaims, error) {
	parse := func() (*jwt.Token, error) {
		// In golang-jwt v5 the per-claim VerifyXXX methods were removed; audience
		// and issuer are enforced by the built-in validator via parser options.
		return jwt.ParseWithClaims(raw, &jwt.RegisteredClaims{}, v.jwks.Keyfunc,
			jwt.WithAudience(v.expectedAud),
			jwt.WithIssuer(v.expectedIss),
		)
	}
 
	token, err := parse()
	// Opportunistic refresh on unknown-kid, rate-limited.
	if err != nil && errors.Is(err, jwt.ErrTokenSignatureInvalid) {
		now := time.Now().UnixMilli()
		if now-v.lastRefresh.Load() > minRefreshIntervalMs {
			v.mu.Lock()
			if time.Now().UnixMilli()-v.lastRefresh.Load() > minRefreshIntervalMs {
				_ = v.jwks.Refresh(ctx)
				v.lastRefresh.Store(time.Now().UnixMilli())
			}
			v.mu.Unlock()
			token, err = parse()
		}
	}
	if err != nil {
		return nil, fmt.Errorf("jwt parse: %w", err)
	}
 
	// Audience and issuer were already validated by the parser options above;
	// a returned token with token.Valid == true has passed both checks.
	claims, ok := token.Claims.(*jwt.RegisteredClaims)
	if !ok || !token.Valid {
		return nil, errors.New("invalid claims")
	}
	return claims, nil
}

func TestVerifyAfterKeyRotation(t *testing.T) {
	ctx := context.Background()
 
	// Phase 1: server publishes the old JWKS, verifier bootstraps.
	srv := newJWKSServer(t, oldKeySet)
	v, err := NewJWKSVerifier(ctx, srv.URL+"/jwks", "https://idp.example", "checkout-api")
	if err != nil { t.Fatal(err) }
	if _, err := v.Verify(ctx, signWith(oldKey, "checkout-api")); err != nil {
		t.Fatalf("old key should verify: %v", err)
	}
 
	// Phase 2: IdP rotates. Server now publishes new JWKS, old key removed.
	// First Verify call with a new-key-signed token MUST trigger refresh and pass.
	srv.SetKeys(newKeySet)
	if _, err := v.Verify(ctx, signWith(newKey, "checkout-api")); err != nil {
		t.Fatalf("new key should verify after refresh: %v", err)
	}
 
	// Phase 3: confirm rate-limited — second unknown-kid attempt within 30s
	// must NOT hit the IdP again. Fail open with a clear error.
	srv.AssertNoMoreFetchesFor(t, 30*time.Second)
}

func RequireJWT(v *JWKSVerifier) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			auth := r.Header.Get("Authorization")
			if !strings.HasPrefix(auth, "Bearer ") {
				http.Error(w, "missing bearer", http.StatusUnauthorized)
				return
			}
			claims, err := v.Verify(r.Context(), strings.TrimPrefix(auth, "Bearer "))
			if err != nil {
				http.Error(w, "invalid token", http.StatusUnauthorized)
				return
			}
			ctx := context.WithValue(r.Context(), claimsKey{}, claims)
			next.ServeHTTP(w, r.WithContext(ctx))
		})
	}
}

POST /payments HTTP/1.1
Host: api.example.com
Authorization: DPoP eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0Iiwiandr
      Ijp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYi...fQ.
      eyJodG0iOiJQT1NUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vcGF5bWVudHMiLAogICAgImlhdCI6MTcyNTQ2MTAwMCwiCiAgICAianRpIjoiOWY4Yi0xMjM0In0.
      MEUCIQDX...
Content-Type: application/json
 
{"amount": 1200, "currency": "GBP"}

func VerifyDPoP(r *http.Request, accessTokenCnf string) error {
    proof := r.Header.Get("DPoP")
    parsed, err := jwt.Parse(proof, func(t *jwt.Token) (interface{}, error) {
        // The signing key is embedded in the proof's `jwk` header — extract it.
        jwk, ok := t.Header["jwk"].(map[string]interface{})
        if !ok { return nil, errors.New("missing jwk header") }
        return jwkToPublicKey(jwk)
    })
    if err != nil || !parsed.Valid {
        return fmt.Errorf("dpop signature: %w", err)
    }
 
    claims := parsed.Claims.(jwt.MapClaims)
 
    // 1. Method + URL bind the proof to this exact request — replay against
    //    a different endpoint fails.
    if claims["htm"] != r.Method { return errors.New("htm mismatch") }
    if claims["htu"] != canonicalURL(r) { return errors.New("htu mismatch") }
 
    // 2. Freshness — proofs older than 60s are rejected (clock skew tolerance).
    iat := time.Unix(int64(claims["iat"].(float64)), 0)
    if time.Since(iat) > 60*time.Second { return errors.New("proof expired") }
 
    // 3. Replay defence — jti must be unique within the freshness window.
    if !replayCache.SeenOnce(claims["jti"].(string), 90*time.Second) {
        return errors.New("dpop replay")
    }
 
    // 4. Binding — proof's public key must hash to the access token's cnf.jkt.
    if jwkThumbprint(parsed.Header["jwk"]) != accessTokenCnf {
        return errors.New("token-key mismatch")
    }
    return nil
}