clerk-security-basics
Implement security best practices with Clerk authentication. Use when securing your application, reviewing auth implementation, or hardening Clerk configuration. Trigger with phrases like "clerk security", "secure clerk", "clerk best practices", "clerk hardening". allowed-tools: Read, Write, Edit, Grep version: 1.0.0 license: MIT author: Jeremy Longshore <jeremy@intentsolutions.io>
Allowed Tools
No tools specified
Provided by Plugin
clerk-pack
Claude Code skill pack for Clerk authentication (24 skills)
Installation
This skill is included in the clerk-pack plugin:
/plugin install clerk-pack@claude-code-plugins-plusClick to copy
Instructions
# Clerk Security Basics
## Overview
Implement security best practices for Clerk authentication in your application.
## Prerequisites
- Clerk SDK installed and configured
- Understanding of authentication security concepts
- Production deployment planned or active
## Instructions
### Step 1: Secure Environment Variables
```bash
# .env.local (development)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
# .env.production (production - use secrets manager)
# NEVER commit production keys to git
# Use Vercel/Railway/AWS Secrets Manager
# .gitignore
.env.local
.env.production
.env*.local
```
```typescript
// lib/env.ts - Validate environment at startup
const requiredEnvVars = [
'NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY',
'CLERK_SECRET_KEY'
]
export function validateEnv() {
for (const envVar of requiredEnvVars) {
if (!process.env[envVar]) {
throw new Error(`Missing required environment variable: ${envVar}`)
}
}
// Validate key format
const pk = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY!
if (!pk.startsWith('pk_test_') && !pk.startsWith('pk_live_')) {
throw new Error('Invalid publishable key format')
}
}
```
### Step 2: Secure Middleware Configuration
```typescript
// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
import { NextResponse } from 'next/server'
const isPublicRoute = createRouteMatcher([
'/',
'/sign-in(.*)',
'/sign-up(.*)',
'/api/webhooks(.*)'
])
const isAdminRoute = createRouteMatcher(['/admin(.*)'])
const isSensitiveRoute = createRouteMatcher(['/api/admin(.*)', '/api/billing(.*)'])
export default clerkMiddleware(async (auth, request) => {
const { userId, orgRole } = await auth()
// Security headers
const response = NextResponse.next()
response.headers.set('X-Frame-Options', 'DENY')
response.headers.set('X-Content-Type-Options', 'nosniff')
response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
// Protect routes
if (!isPublicRoute(request)) {
if (!userId) {
return NextResponse.redirect(new URL('/sign-in', request.url))
}
}
// Admin routes require admin role
if (isAdminRoute(request) && orgRole !== 'org:admin') {
return NextResponse.redirect(new URL('/unauthorized', request.url))
}
// Log sensitive route access
if (isSensitiveRoute(request)) {
console.log('Sensitive route accessed:', {
path: request.nextUrl.pathname,
userId,
timestamp: new Date().toISOString()
})
}
return response
})
```
### Step 3: Secure API Routes
```typescript
// app/api/protected/route.ts
import { auth } from '@clerk/nextjs/server'
import { headers } from 'next/headers'
export async function POST(request: Request) {
// 1. Verify authentication
const { userId, sessionId } = await auth()
if (!userId) {
return Response.json({ error: 'Unauthorized' }, { status: 401 })
}
// 2. Validate request origin (CSRF protection)
const headersList = await headers()
const origin = headersList.get('origin')
const allowedOrigins = [
process.env.NEXT_PUBLIC_APP_URL,
'https://yourdomain.com'
]
if (origin && !allowedOrigins.includes(origin)) {
return Response.json({ error: 'Invalid origin' }, { status: 403 })
}
// 3. Validate content type
const contentType = headersList.get('content-type')
if (!contentType?.includes('application/json')) {
return Response.json({ error: 'Invalid content type' }, { status: 400 })
}
// 4. Parse and validate body
let body
try {
body = await request.json()
} catch {
return Response.json({ error: 'Invalid JSON' }, { status: 400 })
}
// 5. Process request
return Response.json({ success: true })
}
```
### Step 4: Secure Webhook Handling
```typescript
// app/api/webhooks/clerk/route.ts
import { Webhook } from 'svix'
import { headers } from 'next/headers'
import { WebhookEvent } from '@clerk/nextjs/server'
export async function POST(req: Request) {
const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET
if (!WEBHOOK_SECRET) {
console.error('CLERK_WEBHOOK_SECRET not configured')
return Response.json({ error: 'Configuration error' }, { status: 500 })
}
// Get headers
const headerPayload = await headers()
const svix_id = headerPayload.get('svix-id')
const svix_timestamp = headerPayload.get('svix-timestamp')
const svix_signature = headerPayload.get('svix-signature')
// Validate required headers
if (!svix_id || !svix_timestamp || !svix_signature) {
return Response.json({ error: 'Missing svix headers' }, { status: 400 })
}
// Verify webhook
const body = await req.text()
const wh = new Webhook(WEBHOOK_SECRET)
let evt: WebhookEvent
try {
evt = wh.verify(body, {
'svix-id': svix_id,
'svix-timestamp': svix_timestamp,
'svix-signature': svix_signature
}) as WebhookEvent
} catch (err) {
console.error('Webhook verification failed:', err)
return Response.json({ error: 'Invalid signature' }, { status: 400 })
}
// Process verified event
const eventType = evt.type
// Idempotency check (prevent replay attacks)
const processed = await checkIfProcessed(svix_id)
if (processed) {
return Response.json({ message: 'Already processed' })
}
// Handle event
await processWebhookEvent(evt)
// Mark as processed
await markAsProcessed(svix_id)
return Response.json({ success: true })
}
```
### Step 5: Session Security
```typescript
// lib/session-security.ts
import { auth } from '@clerk/nextjs/server'
export async function validateSession() {
const { userId, sessionClaims } = await auth()
if (!userId) {
throw new Error('No session')
}
// Check session age
const issuedAt = sessionClaims?.iat
const maxAge = 60 * 60 // 1 hour in seconds
if (issuedAt && Date.now() / 1000 - issuedAt > maxAge) {
throw new Error('Session too old, please re-authenticate')
}
return { userId, sessionClaims }
}
// Force re-authentication for sensitive operations
export async function requireFreshAuth() {
const { userId, sessionClaims } = await auth()
if (!userId) {
throw new Error('Not authenticated')
}
const issuedAt = sessionClaims?.iat
const freshThreshold = 5 * 60 // 5 minutes
if (issuedAt && Date.now() / 1000 - issuedAt > freshThreshold) {
throw new Error('Please re-authenticate for this action')
}
return { userId }
}
```
## Output
- Secure environment configuration
- Hardened middleware
- Protected API routes
- Verified webhook handling
## Security Checklist
- [ ] Production keys stored in secrets manager
- [ ] Environment variables validated at startup
- [ ] Middleware protects all sensitive routes
- [ ] API routes validate authentication
- [ ] Webhooks verified with svix
- [ ] Security headers configured
- [ ] HTTPS enforced in production
- [ ] Session timeouts configured
## Resources
- [Clerk Security](https://clerk.com/docs/security/overview)
- [Webhook Security](https://clerk.com/docs/integrations/webhooks/sync-data)
- [OWASP Guidelines](https://owasp.org/www-project-web-security-testing-guide/)
## Next Steps
Proceed to `clerk-prod-checklist` for production readiness.