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.

Copy link to headingNextAuth/Auth.js setup on Vercel

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.

Copy link to headingRequired environment variables

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.

Copy link to headingThe NEXTAUTH_URL gotcha

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

Copy link to headingGoogle and GitHub provider setup

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

Copy link to headingOAuth2 for enterprise integrations

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

Copy link to headingCustom OAuth2 provider pattern

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

Copy link to headingMCP server authentication

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.

Copy link to headingSecuring Server Actions

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

Copy link to headingAuthentication checks

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

Copy link to headingCSRF protection

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.

Copy link to headingRate limiting

Protect sensitive Server Actions from abuse:

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

Copy link to headingServer reference security

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

Copy link to headingTroubleshooting: works locally, fails on Vercel

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

Copy link to headingv0 to Vercel deployment auth flow

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

Copy link to headingSummary

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.