OAuth2 and OpenID Connect: Production Security Patterns

package oauth2handler
 
import (
    "context"
    "crypto/rand"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "net/http"
    "time"
 
    "golang.org/x/oauth2"
)
 
type Handler struct {
    config *oauth2.Config
}
 
// generateCodeVerifier: 32 random bytes, base64-URL-encoded (43 chars).
// Since Go 1.24, rand.Read never returns an error (it crashes the process
// instead); the check matters on older toolchains, where a failed read
// must fail the request rather than yield a partly zero-filled verifier.
func generateCodeVerifier() (string, error) {
    b := make([]byte, 32)
    if _, err := rand.Read(b); err != nil {
        return "", fmt.Errorf("generate code verifier: %w", err)
    }
    return base64.RawURLEncoding.EncodeToString(b), nil
}
 
// 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, err := generateCodeVerifier()
    if err != nil {
        http.Error(w, "failed to start login", http.StatusInternalServerError)
        return
    }
    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"
    "fmt"
    "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 under a family, store, return.
// Pass an empty familyID to start a new family (fresh login); pass an existing
// family to rotate within it so reuse of any token revokes the whole chain.
func IssueRefreshToken(userID, familyID string, db *DB) (token string, record *RefreshTokenRecord, err error) {
    token = generateSecureRandom(32)
    tokenHash := hashToken(token)
    if familyID == "" {
        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.
// The user comes from the stored record: a refresh request carries only the
// token, so trusting a caller-supplied user ID would let any valid refresh
// token mint access tokens for someone else.
func UseRefreshToken(clientToken string, db *DB) (newAccessToken, newRefreshToken string, err error) {
    tokenHash := hashToken(clientToken)
 
    // Look up token by hash. Revoked rows are returned too (IsRevoked set),
    // so the /revoke handler below can still find a revoked token's family.
    record, err := db.GetRefreshTokenByHash(tokenHash)
    if err != nil {
        // A storage failure is not an invalid token: reporting invalid_grant
        // here would make every client discard its token and force a re-login.
        return "", "", fmt.Errorf("look up refresh token: %w", err)
    }
    if record == nil {
        return "", "", ErrInvalidToken
    }
 
    // Token already used? (Reuse = theft detection)
    if !record.LastUsedAt.IsZero() {
        return "", "", revokeOnReuse(db, record.FamilyID)
    }
 
    // Revoked (logout, or its family was revoked after theft)? Without this
    // check, the newest token of a revoked family would still rotate.
    if record.IsRevoked {
        return "", "", ErrInvalidToken
    }
 
    // Expired?
    if time.Now().After(record.ExpiresAt) {
        return "", "", ErrTokenExpired
    }
 
    // Mark as used with a conditional write, e.g.
    //   UPDATE refresh_tokens SET last_used_at = now()
    //   WHERE token_hash = $1 AND last_used_at IS NULL AND NOT is_revoked
    // A read-then-write would let two concurrent presentations of this token
    // both pass the check above and both rotate; AND NOT is_revoked closes
    // the same race against a family revocation landing between the
    // IsRevoked check above and this write. Zero rows updated means someone
    // else used it first, or the family was just revoked — either way, fail
    // like reuse. A failed write must fail the refresh, or a stolen copy
    // stays replayable without tripping detection.
    marked, err := db.MarkRefreshTokenUsed(tokenHash)
    if err != nil {
        return "", "", fmt.Errorf("persist token use: %w", err)
    }
    if !marked {
        return "", "", revokeOnReuse(db, record.FamilyID)
    }
 
    // Issue new tokens (refresh token rotates) within the SAME family, so
    // reuse of any token in the chain revokes the whole family. Passing the
    // family into IssueRefreshToken persists it on the new row — patching the
    // returned struct after the insert (as a previous version did) never
    // reached the DB and silently broke theft detection.
    newRefreshToken, _, err = IssueRefreshToken(record.UserID, record.FamilyID, db)
    if err != nil {
        return "", "", err
    }
 
    // Issue short-lived access token.
    newAccessToken, err = issueAccessToken(record.UserID, time.Hour)
    if err != nil {
        return "", "", err
    }
 
    return newAccessToken, newRefreshToken, nil
}
 
// revokeOnReuse revokes the whole family: an attacker may hold one of its
// tokens. A failed revocation is surfaced, not swallowed — continuing would
// leave the stolen chain live while the caller believed it was dead.
func revokeOnReuse(db *DB, familyID string) error {
    if err := db.RevokeTokenFamily(familyID); err != nil {
        return fmt.Errorf("revoke token family after reuse: %w", err)
    }
    return ErrTokenReused // force the user to re-login
}
 
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
}

// Client authentication runs in middleware; the lookups below must also
// confirm the token was issued to that authenticated client before
// revoking it (RFC 7009 §2.1) — omitted here for brevity.
func (h *Handler) Revoke(w http.ResponseWriter, r *http.Request) {
    // token_type_hint is only a lookup hint: the server must find the token
    // even when the hint is wrong or absent (RFC 7009 §2.1), so it is not
    // used to decide whether a refresh-token family gets revoked.
    tokenHash := hashToken(r.FormValue("token"))
 
    // Mark revoked in DB (an unknown hash is a no-op, not an error). A
    // storage failure means nothing was revoked: 503 tells the client to
    // assume the token is still live and retry (RFC 7009 §2.2.1).
    if err := h.db.RevokeToken(tokenHash); err != nil {
        w.WriteHeader(http.StatusServiceUnavailable)
        return
    }
 
    // A refresh token takes its entire family with it (the logout path;
    // password change or compromise revokes every family for the user).
    // A swallowed error here would return 200 OK while the rest of the
    // family stayed live.
    record, err := h.db.GetRefreshTokenByHash(tokenHash)
    if err != nil {
        w.WriteHeader(http.StatusServiceUnavailable)
        return
    }
    if record != nil {
        if err := h.db.RevokeTokenFamily(record.FamilyID); err != nil {
            w.WriteHeader(http.StatusServiceUnavailable)
            return
        }
    }
 
    // 200 OK, even for an unknown or already-revoked token (RFC 7009 §2.2).
    w.WriteHeader(http.StatusOK)
}

package authn
 
import (
	"context"
	"errors"
	"fmt"
	"time"
 
	"github.com/MicahParks/keyfunc/v3"
	"github.com/golang-jwt/jwt/v5"
	"golang.org/x/time/rate"
)
 
type JWKSVerifier struct {
	jwks        keyfunc.Keyfunc
	expectedIss string
	expectedAud string
}
 
func NewJWKSVerifier(ctx context.Context, jwksURL, iss, aud string) (*JWKSVerifier, error) {
	// ctx bounds keyfunc's background refresh goroutine, not a single request.
	// Unknown kid => keyfunc re-fetches the JWKS, gated by RefreshUnknownKID:
	// at most one such refresh per 30s. RateLimitWaitMax bounds both waiting
	// for that limiter AND the refresh HTTP fetch itself, so it has to cover
	// a slow IdP round trip, not just limiter contention (the defaults are
	// one refresh per 5 min and up to a minute for both).
	jwks, err := keyfunc.NewDefaultOverrideCtx(ctx, []string{jwksURL}, keyfunc.Override{
		RefreshUnknownKID: rate.NewLimiter(rate.Every(30*time.Second), 1),
		RateLimitWaitMax:  5 * time.Second,
	})
	if err != nil {
		return nil, fmt.Errorf("jwks bootstrap: %w", err)
	}
	return &JWKSVerifier{jwks: jwks, expectedIss: iss, expectedAud: aud}, nil
}
 
func (v *JWKSVerifier) Verify(ctx context.Context, raw string) (*jwt.RegisteredClaims, error) {
	// In golang-jwt v5 the per-claim VerifyXXX methods were removed; audience,
	// issuer and a mandatory exp are enforced by the built-in validator via
	// parser options. A kid still unknown after the refresh surfaces as
	// jwt.ErrTokenUnverifiable.
	token, err := jwt.ParseWithClaims(raw, &jwt.RegisteredClaims{}, v.jwks.KeyfuncCtx(ctx),
		jwt.WithAudience(v.expectedAud),
		jwt.WithIssuer(v.expectedIss),
		jwt.WithExpirationRequired(),
	)
	if err != nil {
		return nil, fmt.Errorf("jwt parse: %w", err)
	}
 
	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 — a second unknown kid within 30s must be
	// rejected (fail closed) WITHOUT hitting the IdP again.
	if _, err := v.Verify(ctx, signWith(strayKey, "checkout-api")); err == nil {
		t.Fatal("unknown kid inside the refresh window must be rejected")
	}
	srv.AssertFetchCount(t, 2) // bootstrap + the one rotation-triggered refresh
}

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.
      eyJodG0iOiJQT1NUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vcGF5bWVudHMiLCJpYXQiOjE3MjU0NjEwMDAs
      Imp0aSI6IjlmOGItMTIzNCIsImF0aCI6ImhQbmRrcFdINHI3RHlVZE1VcnJxRjNqREpBMDYzemYwSDZEcTJQdnpwWVUifQ.
      Q2Xv5n8JwT0...
Content-Type: application/json
 
{"amount": 1200, "currency": "GBP"}

func VerifyDPoP(r *http.Request, accessToken, accessTokenCnf string) error {
    proof := r.Header.Get("DPoP")
    parsed, err := jwt.Parse(proof, func(t *jwt.Token) (interface{}, error) {
        if t.Header["typ"] != "dpop+jwt" { return nil, errors.New("typ must be dpop+jwt") }
        // 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)
    }, jwt.WithValidMethods([]string{"ES256"})) // asymmetric only; never none or HS*
    if err != nil || !parsed.Valid {
        return fmt.Errorf("dpop signature: %w", err)
    }
 
    claims, ok := parsed.Claims.(jwt.MapClaims)
    if !ok {
        return errors.New("unexpected claims type")
    }
 
    // 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 — accept proofs up to 60s old and at most 30s in the future
    // (clock skew). Bound BOTH sides: a far-future iat would otherwise outlive
    // the replay cache below and make a pre-generated proof replayable.
    // claims come straight off the wire in the client-supplied DPoP header,
    // so a missing or wrong-typed iat must fail the request, not panic it.
    iatFloat, ok := claims["iat"].(float64)
    if !ok { return errors.New("missing or invalid iat claim") }
    age := time.Since(time.Unix(int64(iatFloat), 0))
    if age > 60*time.Second || age < -30*time.Second {
        return errors.New("proof outside the iat window")
    }
 
    // 3. Replay defence — jti must stay unique for as long as a proof is
    // acceptable: 60s + 30s of skew = the 90s cache TTL. Same reasoning as
    // above: a jti of the wrong type must fail cleanly, not panic the handler.
    jti, ok := claims["jti"].(string)
    if !ok || jti == "" { return errors.New("missing or invalid jti claim") }
    if !replayCache.SeenOnce(jti, 90*time.Second) {
        return errors.New("dpop replay")
    }
 
    // 4. Binding — the proof must name THIS access token (ath = base64url
    // SHA-256 of it), and its public key must hash to the token's cnf.jkt.
    // Without ath, a proof captured beside one token works with another.
    athSum := sha256.Sum256([]byte(accessToken))
    if claims["ath"] != base64.RawURLEncoding.EncodeToString(athSum[:]) {
        return errors.New("ath mismatch")
    }
    if jwkThumbprint(parsed.Header["jwk"]) != accessTokenCnf {
        return errors.New("token-key mismatch")
    }
    return nil
}