Middleware Protection

Comprehensive route protection and authorization patterns for Clerk middleware in Next.js applications. Provides middleware configuration, route matchers, role-based access control, and authentication boundaries.

Core Concepts

Middleware Architecture

• Edge Runtime: Clerk middleware runs on Cloudflare Workers/Vercel Edge
• Request Interception: Middleware executes before route handlers
• Auth State: Access to authentication state via auth() helper
• Matcher Patterns: Configure which routes middleware applies to

Route Protection Levels

1. Public Routes: Accessible without authentication (sign-in, sign-up, landing pages)
2. Protected Routes: Require authentication (dashboards, user profiles)
3. Organization Routes: Require organization membership
4. Role-Based Routes: Require specific roles or permissions

Security Principles

• Deny by Default: All routes protected unless explicitly made public
• Defense in Depth: Middleware + server component checks + API route guards
• Session Validation: Automatic token validation on every request
• CSRF Protection: Built-in protection against cross-site request forgery

Instructions

Basic Middleware Setup

1. Create middleware.ts in project root

- Import clerkMiddleware from @clerk/nextjs/server - Export default middleware function - Configure matcher for routes to protect

1. Configure Public Routes

- Define routes accessible without authentication - Use glob patterns for route matching - Include sign-in/sign-up pages as public

1. Set Protected Routes

- Specify which routes require authentication - Use route groups for organization - Apply different protection levels

Advanced Patterns

1. Role-Based Access Control

- Check user roles in middleware - Redirect based on permissions - Implement organization-level permissions

1. Conditional Route Protection

- Apply different rules based on route patterns - Check custom metadata - Implement feature flags

1. API Route Protection

- Secure API endpoints with middleware - Validate session tokens - Check permissions before processing

1. Multi-Tenant Protection

- Organization-scoped routes - Tenant isolation - Cross-organization access prevention

Testing Protection

1. Test Authentication Boundaries

- Verify unauthenticated redirects - Check protected route access - Validate role requirements

1. Test Edge Cases

- Token expiration handling - Invalid session handling - Missing organization membership

Templates

Use these templates for middleware implementation:

Core Templates

• templates/middleware.ts - Basic middleware configuration
• templates/route-matchers.ts - Route matching patterns
• templates/role-based-middleware.ts - Role-based access control

Configuration Templates

• templates/public-routes-config.ts - Public route definitions
• templates/protected-routes-config.ts - Protected route setup
• templates/api-middleware-config.ts - API route protection

Advanced Templates

• templates/organization-middleware.ts - Organization-scoped protection
• templates/conditional-middleware.ts - Conditional route logic
• templates/custom-redirects.ts - Custom redirect handling

Scripts

Use these scripts for middleware setup and testing:

• scripts/generate-middleware.sh - Generate middleware.ts with configuration
• scripts/configure-routes.sh - Setup route protection patterns
• scripts/test-protection.sh - Test authentication guards and boundaries
• scripts/validate-middleware.sh - Validate middleware configuration

Examples

See complete examples in the examples/ directory:

Basic Examples

• examples/basic-middleware.ts - Simple middleware setup
• examples/public-private-routes.ts - Public vs protected routes
• examples/api-middleware.ts - API route protection

Advanced Examples

• examples/role-based-protection.ts - Role-based access control
• examples/organization-routes.ts - Organization-scoped routes
• examples/conditional-routing.ts - Conditional protection logic
• examples/custom-auth-flow.ts - Custom authentication flows

Testing Examples

• examples/middleware-tests.ts - Middleware unit tests
• examples/integration-tests.ts - Full protection integration tests

Security Best Practices

API Key Handling

CRITICAL: When generating middleware configuration:

• ❌ NEVER hardcode CLERKSECRETKEY or NEXTPUBLICCLERKPUBLISHABLEKEY
• ❌ NEVER include real API keys in examples
• ✅ ALWAYS use placeholders: yourclerksecretkeyhere
• ✅ ALWAYS read from environment variables: process.env.CLERKSECRETKEY
• ✅ ALWAYS add .env* to .gitignore (except .env.example)
• ✅ ALWAYS document where to obtain keys from Clerk Dashboard

Middleware Security

1. Validate All Requests: Don't skip middleware on any protected routes
2. Check Session Validity: Always validate session tokens
3. Implement Rate Limiting: Protect against brute force attacks
4. Log Security Events: Track authentication failures and suspicious activity
5. Use HTTPS Only: Never run authentication over HTTP in production

Requirements

Next.js Version:

• Next.js 13.4+ (App Router support)
• Next.js 12+ (Pages Router support)

Clerk SDK:

• @clerk/nextjs 4.0+ (latest stable)
• Node.js 16+

Configuration Files:

• .env.local with Clerk environment variables
• middleware.ts in project root
• .gitignore protecting secrets

Common Patterns

Pattern 1: Public Landing + Protected Dashboard

// Public: /, /about, /pricing
// Protected: /dashboard/*, /profile/*
// Matcher: Protect everything except public routes

Pattern 2: API Route Protection

// Protect all /api/* except /api/webhooks/clerk
// Validate session tokens on protected endpoints
// Return 401 for unauthenticated requests

Pattern 3: Organization-Scoped Routes

// Require organization membership for /org/*
// Check active organization in middleware
// Redirect to organization selection if needed

Pattern 4: Role-Based Access

// Check user roles in middleware
// Redirect based on permissions (admin vs user)
// Implement feature-specific access control

Troubleshooting

Common Issues

1. Middleware Not Running

- Check matcher configuration - Verify middleware.ts location (project root) - Ensure Next.js version supports middleware

1. Infinite Redirect Loops

- Sign-in page must be public - Check redirect logic in middleware - Verify afterSignInUrl configuration

1. Protected Routes Accessible

- Verify matcher includes routes - Check auth state validation - Ensure middleware executes before route

1. Session Not Found

- Check environment variables loaded - Verify Clerk keys are correct - Ensure cookies not blocked

Purpose: Provide comprehensive middleware protection patterns for Clerk authentication Load when: Implementing route guards, protecting routes, setting up middleware, configuring auth boundaries