Security Best Practices

This guide outlines security best practices when using oauth-mcp-proxy in production.

Breaking Changes (Security Hardening v1.1.0)

The following security improvements introduce breaking changes:

1. Issuer URL Validation (CRITICAL)

What changed: OIDC providers (Okta, Google, Azure) now enforce HTTPS validation for issuer URLs in Config.Validate().

Why: Prevents man-in-the-middle attacks on OAuth communication.

Impact: Invalid issuer URLs will cause NewServer() to fail with error.

Migration:

// ✅ Valid configurations
Issuer: "https://company.okta.com"              // Production
Issuer: "http://localhost:8080"                 // Local testing only
Issuer: "http://127.0.0.1:8080"                 // Local testing only

// ❌ Invalid - will fail validation
Issuer: "http://company.okta.com"               // Must use HTTPS
Issuer: "company.okta.com"                      // Missing scheme
Issuer: "https://192.168.1.1/issuer"            // IP addresses not allowed

2. State Signing Key Initialization

What changed: NewServer() now panics if the state signing key cannot be generated via crypto/rand.

Why: Prevents weak fallback that could allow state forgery attacks.

Impact: Server startup will fail immediately if crypto/rand fails.

Migration: No code changes needed. Ensure your system has a working CSPRNG (crypto/rand). This should never fail on healthy systems.

3. Nonce Generation Failure Behavior

What changed: generateSecureNonce() now panics instead of falling back to weak timestamp-based nonces.

Why: Timestamp-based nonces are predictable and vulnerable to replay attacks.

Impact: OAuth authorization requests will fail if crypto/rand fails.

Migration: No code changes needed. Ensure your system has a working CSPRNG.

4. CreateRequestAuthHook Now Rejects Requests

What changed: CreateRequestAuthHook() now returns an error for all requests instead of silently allowing them through.

Why: The previous implementation returned nil (allow-all), which created a security bypass if integrators relied on this hook for authentication. The hook's signature cannot propagate context changes, making it fundamentally unable to perform real auth.

Impact: Any code using CreateRequestAuthHook() will now reject all requests with an error.

Migration: Switch to WithOAuth() tool-level middleware, which properly handles authentication and context propagation:

// ❌ Old (deprecated, now fails all requests)
hook := oauth.CreateRequestAuthHook(validator)

// ✅ New
oauthServer, oauthOption, _ := mark3labs.WithOAuth(mux, &oauth.Config{...})
mcpServer := server.NewMCPServer("name", "1.0.0", oauthOption)

5. Redirect URI Validation in Config

What changed: Config.Validate() now validates redirect URIs and fixed redirect URIs at startup. HTTPS is required for non-localhost URIs, fragments are rejected, and whitespace-only URI lists are caught.

Why: Prevents open redirect vulnerabilities and ensures OAuth 2.0 spec compliance.

Impact: Existing configs with HTTP redirect URIs for non-localhost hosts, or URIs containing fragments, will fail validation at startup.

Migration:

// ✅ Valid
RedirectURIs: "https://app.example.com/callback"
RedirectURIs: "http://localhost:3000/callback"

// ❌ Invalid - will fail validation
RedirectURIs: "http://app.example.com/callback"      // Must use HTTPS
RedirectURIs: "https://app.example.com/cb#fragment"   // No fragments allowed
RedirectURIs: " , , "                                  // No valid URIs

6. Error Message Simplification

What changed: Security-sensitive error paths now return generic error messages to prevent information leakage.

Why: Prevents attackers from learning internal system details through error messages.

Impact: Debugging authentication failures from client-side may be less informative.

Migration: Use server logs for detailed debugging. Client-facing errors are intentionally generic for security.

Backward-Compatible Changes

The following security improvements are fully backward-compatible:

Token cache expiry fix - Cache now respects JWT expiration times
State replay protection - Legacy states without timestamp/nonce still accepted for rolling deploys
Input validation - Only affects malformed/abusive requests
Query injection prevention - Transparent fix, no API changes
go-sdk adapter session management - Fully backwards compatible

🔒 Secrets Management

Never Commit Secrets

❌ BAD:

oauth.WithOAuth(mux, &oauth.Config{
    JWTSecret: []byte("my-secret-key"),  // Committed to git!
    ClientSecret: "hardcoded-secret",     // Committed to git!
})

✅ GOOD:

oauth.WithOAuth(mux, &oauth.Config{
    JWTSecret:    []byte(os.Getenv("JWT_SECRET")),
    ClientSecret: os.Getenv("OAUTH_CLIENT_SECRET"),
})

Environment Variables

# .env (add to .gitignore!)
JWT_SECRET=your-random-32-byte-secret-key-here
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_ISSUER=https://yourcompany.okta.com

Load with library like godotenv:

import "github.com/joho/godotenv"

func main() {
    godotenv.Load() // Load .env file

    oauth.WithOAuth(mux, &oauth.Config{
        Provider:     os.Getenv("OAUTH_PROVIDER"),
        Issuer:       os.Getenv("OAUTH_ISSUER"),
        JWTSecret:    []byte(os.Getenv("JWT_SECRET")),
        ClientSecret: os.Getenv("OAUTH_CLIENT_SECRET"),
    })
}

.gitignore

# Secrets
.env
.env.local
.env.production

# Certificates
*.pem
*.key
*.crt

# OAuth tokens (testing)
*.token

🔐 JWT Secret Strength (HMAC Provider)

Minimum Requirements

// Generate cryptographically secure secret
secret := make([]byte, 32)  // 32 bytes = 256 bits
if _, err := rand.Read(secret); err != nil {
    log.Fatal(err)
}

// Store as base64 or hex
secretB64 := base64.StdEncoding.EncodeToString(secret)
fmt.Println("JWT_SECRET=" + secretB64)

Validation

secret := []byte(os.Getenv("JWT_SECRET"))
if len(secret) < 32 {
    log.Fatal("JWT_SECRET must be at least 32 bytes for security")
}

Rotation

Rotate every: 90 days recommended
Process: Generate new secret → Update config → Deploy → Update token generators
Zero downtime: Temporarily accept both old and new secrets during rotation

🌐 HTTPS in Production

Always Use TLS

❌ NEVER in production:

http.ListenAndServe(":80", mux)  // Unencrypted!

✅ Production:

http.ListenAndServeTLS(":443", "server.crt", "server.key", mux)

Get Certificates

Development:

Use mkcert for local testing

Production:

Use Let's Encrypt with certbot
Or your cloud provider's certificate service (AWS ACM, GCP Certificate Manager)

Certificate Management

// Auto-reload certificates
certManager := &autocert.Manager{
    Prompt: autocert.AcceptTOS,
    HostPolicy: autocert.HostWhitelist("your-server.com"),
    Cache: autocert.DirCache("certs"),
}

server := &http.Server{
    Addr:      ":443",
    Handler:   mux,
    TLSConfig: certManager.TLSConfig(),
}

server.ListenAndServeTLS("", "")

🎯 Audience Validation

Why Audience Matters

Prevents token reuse across services:

Service A: Audience = "api://service-a"
Service B: Audience = "api://service-b"

Token for Service A cannot be used on Service B (even with same issuer).

Configuration

HMAC Provider:

oauth.WithOAuth(mux, &oauth.Config{
    Provider: "hmac",
    Audience: "api://my-specific-mcp-server",  // Unique per service
})

OIDC Providers:

Okta: Configure custom audience in auth server claims
Google: Use Client ID as audience
Azure: Use Application ID or custom App ID URI

Validation

// Token must have matching audience
{
  "aud": "api://my-specific-mcp-server",  // Must match Config.Audience
  "iss": "https://issuer.com",
  "sub": "user-123"
}

🔄 Token Caching & Expiration

Cache Behavior

Cache TTL: 5 minutes (hardcoded in v0.1.0)
Cache scope: Per Server instance
Cache key: SHA-256 hash of token

Token Expiration Recommendations

User tokens:

Short-lived: 1 hour
Refresh tokens: 7-30 days
Reason: Limits damage if compromised

Service tokens:

Medium-lived: 6-24 hours
Reason: Balance between security and token refresh overhead

// When generating tokens
token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
    "sub": "user-123",
    "aud": "api://my-server",
    "exp": time.Now().Add(1 * time.Hour).Unix(),  // Expire in 1 hour
    "iat": time.Now().Unix(),
})

🛡️ PKCE (Proof Key for Code Exchange)

Automatic Protection

oauth-mcp-proxy automatically supports PKCE (RFC 7636):

Prevents authorization code interception attacks
Required for public clients (mobile, desktop, browser)
Automatically validated when code_challenge provided

No Configuration Needed

PKCE is automatically enabled when client provides:

code_challenge parameter in /oauth/authorize
code_verifier parameter in /oauth/token

🚪 Redirect URI Security

Native Mode (Client OAuth)

Localhost only for security:

✅ http://localhost:8080/callback
✅ http://127.0.0.1:3000/callback
✅ http://[::1]:9000/callback
❌ http://evil.com/callback         (rejected)
❌ https://localhost.evil.com/...   (rejected - subdomain attack)

Proxy Mode (Server OAuth)

Allowlist configuration:

oauth.WithOAuth(mux, &oauth.Config{
    RedirectURIs: "https://app.example.com/callback",  // Single URI (fixed)
    // Or multiple:
    // RedirectURIs: "https://app1.com/cb,https://app2.com/cb",  // Allowlist
})

Security checks:

HTTPS required for non-localhost
No fragment allowed (per OAuth 2.0 spec)
Exact match validation (no wildcards)

🎫 Token Security

Token Storage (Client Side)

Browser:

Use httpOnly cookies or sessionStorage (NOT localStorage)
Clear on logout

Mobile/Desktop:

Use OS keychain (macOS Keychain, Windows Credential Manager)
Never store in plain text files

CLI Tools:

Store in encrypted config files
Use OS-specific secure storage when possible

Token Transmission

Always use Authorization header:

curl -H "Authorization: Bearer <token>" https://server.com/mcp

Never:

In URL query parameters (logged in web servers)
In cookies without httpOnly flag
In localStorage (XSS vulnerable)

🔍 Logging & Monitoring

What Gets Logged

oauth-mcp-proxy logs (with custom logger or default):

Info Level:

Authorization requests
Successful authentications
Token cache hits

Warn Level:

Security violations (invalid redirects)
Configuration issues

Error Level:

Token validation failures
OAuth provider errors

What NOT to Log

✅ Safe: Token hash (SHA-256)

INFO: Validating token (hash: a7bc40a987f35871...)

❌ NEVER log: Full tokens

ERROR: Token xyz123... invalid  // SECURITY VIOLATION!

Custom Logger for Production

type ProductionLogger struct {
    logger *zap.Logger
}

func (l *ProductionLogger) Error(msg string, args ...interface{}) {
    // Sanitize before logging
    l.logger.Sugar().Errorf(msg, args...)
    // Send to error tracking (Sentry, etc.)
}

oauth.WithOAuth(mux, &oauth.Config{
    Logger: &ProductionLogger{logger: zapLogger},
})

🚨 Rate Limiting

Built-in Rate Limiter

oauth-mcp-proxy includes a built-in rate limiter:

import "github.com/tuannvm/oauth-mcp-proxy"

limiter := oauth.NewRateLimiter(time.Minute, 100) // 100 req/min
if !limiter.Allow("client-key") {
    http.Error(w, "Rate limit exceeded", http.StatusTooManyRequests)
    return
}

Features:

Fixed-window rate limiting
Automatic cleanup of expired entries
Thread-safe (uses sync.RWMutex)
Background cleanup goroutine support

// Start background cleanup (prevents memory leaks)
stopCleanup := limiter.StartCleanup(5 * time.Minute)
defer stopCleanup()

Additional Protection

For OAuth endpoints, consider additional rate limiting:

import "golang.org/x/time/rate"

globalLimiter := rate.NewLimiter(10, 20)  // 10 req/s, burst 20

func rateLimitMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if !globalLimiter.Allow() {
            http.Error(w, "Rate limit exceeded", http.StatusTooManyRequests)
            return
        }
        next.ServeHTTP(w, r)
    })
}

// Apply to OAuth endpoints
mux.Handle("/oauth/", rateLimitMiddleware(oauthHandler))

🔁 Security Headers

OAuth handler automatically adds security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Cache-Control: no-store, no-cache, max-age=0
Pragma: no-cache
Content-Security-Policy: default-src 'none'; script-src 'none'; style-src 'none'; img-src 'none'; font-src 'none'; connect-src 'none'; object-src 'none'; frame-ancestors 'none'; form-action 'self';

🛡️ Built-in Security Features

oauth-mcp-proxy includes multiple security defenses:

State Replay Protection

OAuth state parameters are protected against replay attacks:

Timestamp validation - States expire after 10 minutes
Nonce uniqueness - Each state uses a cryptographically random nonce
Replay detection - Nonce tracked and rejected if reused
Automatic cleanup - Expired nonces removed to prevent memory leaks
Rolling deploy compatible - Accepts states from older versions during upgrades

Token Cache Security

Token caching respects JWT expiration times:

// Cache uses min(token.expiry, now + 5 minutes)
// This prevents cached tokens from being used past actual expiration

Input Validation

Request parameters are validated to prevent abuse:

code parameter - Max 512 characters
state parameter - Max 256 characters
code_challenge parameter - Max 256 characters
Request body size - Limited to prevent DoS (1MB for /oauth/token, 256KB for /oauth/register)

Issuer URL Validation

OIDC provider issuer URLs are validated:

HTTPS required for non-localhost URLs (prevents MITM attacks)
Valid URL format - Must parse correctly
Not empty - Issuer must be specified
No raw IP addresses - Hostnames only (prevents misconfiguration)

Constant-Time Cryptography

HMAC signatures verified using constant-time comparison:

// Prevents timing attacks on signature validation
hmac.Equal([]byte(receivedSig), []byte(expectedSig))

Secure Random Number Generation

Nonces generated using crypto/rand:

Panics on failure - No fallback to weak timestamp-based nonces
Cryptographically secure - Uses system CSPRNG

Session Management (Official SDK)

The official SDK adapter populates the go-sdk auth context:

auth.TokenInfo populated - User ID and expiration set for session binding
Session hijacking prevention - Requests from different users rejected
CORS support - OPTIONS requests pass through for browser clients

Add application-level headers:

func securityHeaders(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Strict-Transport-Security", "max-age=63072000; includeSubDomains")
        w.Header().Set("Content-Security-Policy", "default-src 'self'")
        next.ServeHTTP(w, r)
    })
}

http.ListenAndServeTLS(":443", "cert.pem", "key.pem", securityHeaders(mux))

📋 Security Checklist

Pre-Production

Configuration:

All secrets in environment variables (not code)
HTTPS enabled with valid certificates
Audience configured and validated
JWT secret 32+ bytes (HMAC) or provider-issued (OIDC)
Issuer URL validated (OIDC providers)
Redirect URIs properly configured

Built-in Security (already enabled):

State replay protection (timestamp + nonce)
Nonce cleanup (memory leak prevention)
Token cache with JWT expiry awareness
Input validation (parameter length limits)
Request body size limits (DoS prevention)
Constant-time HMAC comparison
Secure nonce generation (crypto/rand)
Security headers (CSP, X-Frame-Options, etc.)
CORS support (OPTIONS pass-through)

Optional:

Custom logger configured (no sensitive data logged)
Additional rate limiting on OAuth endpoints

Regular Maintenance

Rotate secrets every 90 days
Review OAuth provider audit logs
Monitor for unusual authentication patterns
Update dependencies (go get -u)
Review token expiration policies
Test disaster recovery (secret compromise)

🚩 Security Incidents

Token Compromise

If JWT secret (HMAC) leaked:

Generate new secret immediately
Update config and redeploy
All existing tokens invalidated (users must re-auth)
Review logs for suspicious activity

If client secret (OIDC) leaked:

Revoke in OAuth provider (Okta/Google/Azure)
Generate new secret
Update config and redeploy
Existing user tokens still valid (not affected)

Suspicious Activity

Multiple failed auth attempts → Consider IP blocking
Unusual token usage patterns → Review logs
Invalid redirect URI attempts → Security violation logged

📚 Additional Resources

🤝 Reporting Security Issues

Found a security vulnerability? Email security@[your-domain] or open a confidential GitHub Security Advisory.

Do NOT open public GitHub issues for security vulnerabilities.

PreviousConfiguration Guide NextTroubleshooting Guide

Last updated 1 month ago

Was this helpful?

Good afternoon

hashtagBreaking Changes (Security Hardening v1.1.0)

hashtag1. Issuer URL Validation (CRITICAL)

hashtag2. State Signing Key Initialization

hashtag3. Nonce Generation Failure Behavior

hashtag4. CreateRequestAuthHook Now Rejects Requests

hashtag5. Redirect URI Validation in Config

hashtag6. Error Message Simplification

hashtagBackward-Compatible Changes

hashtag🔒 Secrets Management

hashtagNever Commit Secrets

hashtagEnvironment Variables

hashtag.gitignore

hashtag🔐 JWT Secret Strength (HMAC Provider)

hashtagMinimum Requirements

hashtagValidation

hashtagRotation

hashtag🌐 HTTPS in Production

hashtagAlways Use TLS

hashtagGet Certificates

hashtagCertificate Management

hashtag🎯 Audience Validation

hashtagWhy Audience Matters

hashtagConfiguration

hashtagValidation

hashtag🔄 Token Caching & Expiration

hashtagCache Behavior

hashtagToken Expiration Recommendations

hashtag🛡️ PKCE (Proof Key for Code Exchange)

hashtagAutomatic Protection

hashtagNo Configuration Needed

hashtag🚪 Redirect URI Security

hashtagNative Mode (Client OAuth)

hashtagProxy Mode (Server OAuth)

hashtag🎫 Token Security

hashtagToken Storage (Client Side)

hashtagToken Transmission

hashtag🔍 Logging & Monitoring

hashtagWhat Gets Logged

hashtagWhat NOT to Log

hashtagCustom Logger for Production

hashtag🚨 Rate Limiting

hashtagBuilt-in Rate Limiter

hashtagAdditional Protection

hashtag🔁 Security Headers

hashtag🛡️ Built-in Security Features

hashtagState Replay Protection

hashtagToken Cache Security

hashtagInput Validation

hashtagIssuer URL Validation

hashtagConstant-Time Cryptography

hashtagSecure Random Number Generation

hashtagSession Management (Official SDK)

hashtag📋 Security Checklist

hashtagPre-Production

hashtagRegular Maintenance

hashtag🚩 Security Incidents

hashtagToken Compromise

hashtagSuspicious Activity

hashtag📚 Additional Resources

hashtag🤝 Reporting Security Issues

Breaking Changes (Security Hardening v1.1.0)

1. Issuer URL Validation (CRITICAL)

2. State Signing Key Initialization

3. Nonce Generation Failure Behavior

4. CreateRequestAuthHook Now Rejects Requests

5. Redirect URI Validation in Config

6. Error Message Simplification

Backward-Compatible Changes

🔒 Secrets Management

Never Commit Secrets

Environment Variables

.gitignore

🔐 JWT Secret Strength (HMAC Provider)

Minimum Requirements

Validation

Rotation

🌐 HTTPS in Production

Always Use TLS

Get Certificates

Certificate Management

🎯 Audience Validation

Why Audience Matters

Configuration

Validation

🔄 Token Caching & Expiration

Cache Behavior

Token Expiration Recommendations

🛡️ PKCE (Proof Key for Code Exchange)

Automatic Protection

No Configuration Needed

🚪 Redirect URI Security

Native Mode (Client OAuth)

Proxy Mode (Server OAuth)

🎫 Token Security

Token Storage (Client Side)

Token Transmission

🔍 Logging & Monitoring

What Gets Logged

What NOT to Log

Custom Logger for Production

🚨 Rate Limiting

Built-in Rate Limiter

Additional Protection

🔁 Security Headers

🛡️ Built-in Security Features

State Replay Protection

Token Cache Security

Input Validation

Issuer URL Validation

Constant-Time Cryptography

Secure Random Number Generation

Session Management (Official SDK)

📋 Security Checklist

Pre-Production

Regular Maintenance

🚩 Security Incidents

Token Compromise

Suspicious Activity

📚 Additional Resources

🤝 Reporting Security Issues