The complete guide to authentication on Vercel

Authentication is the most common friction point when deploying applications to Vercel. This guide covers everything from basic NextAuth/Auth.js setup to enterprise OAuth2 patterns, helping you avoid the "works locally but fails on Vercel" problem.

NextAuth.js (now Auth.js) is the most popular authentication library for Next.js applications. Setting it up on Vercel requires attention to environment variables and URL configuration.

Configure these variables in your Vercel project settings:

• NEXTAUTH_SECRET - A random string used to encrypt tokens and cookies. Generate with openssl rand -base64 32
• NEXTAUTH_URL - Your production URL (e.g., https://your-app.vercel.app). On Vercel, this is automatically set for production but must be configured for preview deployments.

This is the most common source of auth failures on Vercel. In production, Vercel automatically infers the correct URL, so you don't need to set NEXTAUTH_URL. However, preview deployments get unique URLs, which causes callback URL mismatches with OAuth providers.

Solutions:

1. Use VERCEL_URL for dynamic URL detection in your auth configuration
2. Add wildcard callback URLs to your OAuth provider (e.g., https://*.vercel.app/api/auth/callback/*)
3. Use branch-specific environment variables in Vercel for preview deployments with a stable domain

For Google OAuth:

1. Create credentials in Google Cloud Console
2. Add authorized redirect URIs: https://your-domain.com/api/auth/callback/google
3. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in Vercel

For GitHub OAuth:

1. Create an OAuth App in GitHub Developer Settings
2. Set callback URL: https://your-domain.com/api/auth/callback/github
3. Set GITHUB_ID and GITHUB_SECRET in Vercel

Enterprise customers building agents and integrations often need OAuth2 patterns for proprietary systems like banking APIs or internal SaaS platforms.

When integrating with proprietary OAuth2 systems, define a custom provider in your Auth.js configuration:

1. Configure the authorization endpoint, token endpoint, and userinfo endpoint
2. Map the provider's user profile to your application's user model
3. Handle token refresh for long-lived sessions

For Model Context Protocol (MCP) servers deployed on Vercel, implement OAuth authorization using the withMcpAuth wrapper. This pattern validates bearer tokens, checks required scopes, and returns authenticated user information to your handlers.

Server Actions introduce new security considerations. Unlike API routes, Server Actions can be invoked from client components, creating potential attack vectors.

Always verify the user's session at the start of every Server Action:

1. Call getServerSession() or your auth library's equivalent
2. Return early or throw an error if unauthenticated
3. Verify user permissions for the specific action

Next.js Server Actions have built-in CSRF protection through origin checking. The framework automatically validates that requests originate from your domain. However, ensure your next.config.js doesn't disable these protections.

Protect sensitive Server Actions from abuse:

• Use Vercel's Edge Config with KV for distributed rate limiting
• Implement per-user and per-IP limits
• Consider using Vercel's Firewall rules for additional protection

Server Actions create server references that can be discovered by attackers. Never rely on obscurity:

• Treat every Server Action as a public API endpoint
• Validate all inputs server-side
• Use Zod or similar libraries for runtime type checking

Use this matrix to diagnose common authentication failures:

Symptom: OAuth callback fails with "redirect_uri_mismatch"

• Cause: NEXTAUTH_URL mismatch or callback URL not registered with OAuth provider
• Fix: Add your Vercel domain to OAuth provider's allowed redirect URIs

Symptom: Session is null after successful login

• Cause: NEXTAUTH_SECRET not set or different between environments
• Fix: Ensure NEXTAUTH_SECRET is set in Vercel environment variables for all environments

Symptom: Infinite redirect loop on sign-in

• Cause: Cookie domain mismatch or secure cookie issues
• Fix: Ensure your app is served over HTTPS and cookie settings match your domain

Symptom: "CSRF token mismatch" error

• Cause: Session cookie not persisting between requests
• Fix: Check cookie settings, particularly SameSite and Secure attributes

Symptom: Auth works on main branch but fails on preview

• Cause: Preview deployments have unique URLs not registered with OAuth provider
• Fix: Use wildcard callback URLs or configure branch-specific environment variables

When deploying a v0-generated app with authentication to Vercel:

1. Export your project - Deploy directly to Vercel from v0's interface
2. Configure environment variables - Add NEXTAUTH_SECRET and provider credentials in Vercel project settings
3. Update OAuth providers - Add your new Vercel domain to allowed callback URLs
4. Test authentication - Verify sign-in and sign-out flows work correctly
5. Configure preview environments - Set up auth for preview deployments if needed

Common v0 auth issues:

• v0 uses placeholder environment variables - replace them with real credentials
• Database connections may need updating for production
• Auth callbacks expect your production domain, not localhost

Authentication on Vercel requires attention to environment configuration, especially around NEXTAUTH_URL and callback URLs. For enterprise OAuth2 integrations, define custom providers and handle token refresh. Secure your Server Actions by validating sessions, implementing rate limiting, and treating every action as a public endpoint. When issues arise, check environment variables first - they're the root cause of most "works locally, fails on Vercel" problems.