Next.js Authentication Tutorial: Complete Guide 2026

Introduction

Authentication is essential for any application with user accounts. Next.js combined with NextAuth.js provides a robust, secure, and flexible authentication solution that works with the App Router, Server Components, and API routes.

This tutorial covers implementing authentication from scratch, including OAuth providers, credentials-based login, and protecting routes.

Prerequisites

• Next.js 14+ application
• Basic React and Next.js knowledge
• Node.js 18+

Installation

Install NextAuth.js (now called Auth.js) using npm or yarn. You will also need any database adapters if using database sessions.

Create the necessary environment variables for your secret key and OAuth provider credentials.

Basic Setup

Create Auth Configuration

Create an auth configuration file that defines your providers and callbacks. This is where you configure how authentication works in your application.

Set Up API Route

Create the NextAuth API route handler. This handles all authentication endpoints like sign in, sign out, and callbacks.

Add Session Provider

Wrap your application with the SessionProvider to make authentication state available throughout your app.

OAuth Providers

Google Sign-In

Google OAuth is one of the most popular authentication methods. Configure it by:

1. Create a project in Google Cloud Console
2. Enable the OAuth 2.0 API
3. Create OAuth credentials
4. Add authorized redirect URIs
5. Add client ID and secret to environment variables

GitHub Sign-In

GitHub OAuth is popular for developer-focused applications:

1. Create an OAuth App in GitHub Developer Settings
2. Set the authorization callback URL
3. Add client ID and secret to environment variables

Credentials Provider

For email/password authentication, use the Credentials provider. This requires:

1. A user database
2. Password hashing (use bcrypt)
3. Custom authorize function

Important: Handle errors securely without revealing whether the email exists.

Protecting Routes

Client-Side Protection

Use the useSession hook to check authentication status and redirect unauthorized users.

Server-Side Protection

For Server Components, use getServerSession to check authentication. This is more secure as it runs on the server.

Middleware Protection

Create a middleware.ts file to protect entire route groups. This runs before requests reach your pages.

Configure which routes require authentication using the matcher pattern.

Customizing Pages

Custom Sign-In Page

Create a custom sign-in page for better UX. Configure NextAuth to use your custom page instead of the default.

Your custom page should include forms for each provider and handle errors appropriately.

Custom Error Page

Handle authentication errors gracefully with a custom error page that explains what went wrong.

Session Management

Accessing Session Data

On the client, use the useSession hook. It returns session data, loading status, and update function.

On the server, use getServerSession. This is secure and can be used in Server Components and API routes.

Extending Session Data

Add custom fields to the session by extending the callbacks. For example, add user role or ID.

Database Adapters

For persistent sessions and user storage, use a database adapter.

The adapter handles user creation, session storage, and account linking.

Security Best Practices

Environment Variables

CSRF Protection

NextAuth includes CSRF protection by default. Do not disable it.

Secure Cookies

In production, cookies are automatically set to secure and httpOnly. Verify your deployment uses HTTPS.

Rate Limiting

Add rate limiting to authentication endpoints to prevent brute force attacks.

Testing

Development Testing

Use test accounts for OAuth providers during development. Most providers have sandbox modes.

E2E Testing

For end-to-end tests, mock the session provider or use test credentials. Playwright and Cypress both support this.

Deployment

Conclusion

NextAuth.js provides a comprehensive authentication solution for Next.js applications. Start with OAuth providers for quick implementation, add credentials if needed, and protect your routes appropriately.

Focus on security from the start—use environment variables, enable CSRF protection, and implement rate limiting. The library handles most security concerns, but understanding the underlying mechanisms helps you make better decisions.