Implementing OAuth 2.0 in Next.js: A Comprehensive Guide

1. Introduction

OAuth 2.0 is the industry-standard protocol for authorization, letting your users sign in with external identity providers (Google, GitHub, Facebook, and more) without you handling passwords directly. In this guide, we'll walk through how to add OAuth 2.0 authentication to a Next.js app using NextAuth.js, covering setup, configuration, best practices, and troubleshooting.

2. Why OAuth 2.0?

Implementing OAuth 2.0 offers several benefits:

• 🔒 Security: Delegate credential handling to trusted providers.
• ⚡ Rapid Onboarding: Let users log in with existing accounts.
• 🛠️ Scalability: Integrate multiple providers with minimal code.
• 🔄 Single Sign-On: Provide seamless cross-app experiences.

3. Choosing the Right Library

While you can roll your own OAuth flow, we recommend using NextAuth.js for:

• Built-in support for many providers (Google, GitHub, Facebook, LinkedIn, Auth0, etc.)
• Session management and secure cookies out of the box
• TypeScript support and easy callback hooks
• Zero-config defaults with plenty of customization points

4. Installation & Setup

4.1. Install NextAuth.js

npm install next-auth

4.2. Create API Route

// pages/api/auth/[...nextauth].ts
import NextAuth from 'next-auth'
import GoogleProvider from 'next-auth/providers/google'

export default NextAuth({
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
    // add other providers here
  ],
  secret: process.env.NEXTAUTH_SECRET,
})

4.3. Environment Variables

• GOOGLE_CLIENT_ID – obtained from Google Cloud Console
• GOOGLE_CLIENT_SECRET – obtained from Google Cloud Console
• NEXTAUTH_SECRET – generate with openssl rand -base64 32

5. Configuring Providers

NextAuth supports dozens of built-in providers. Here’s how to add GitHub:

// pages/api/auth/[...nextauth].ts
import GitHubProvider from 'next-auth/providers/github'

export default NextAuth({
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),
    // existing providers...
  ],
})

Tip: Always store secrets in environment variables, never in source code.

6. Client-Side Integration

Use the NextAuth React hooks to handle sign-in, sign-out, and session data:

import { useSession, signIn, signOut } from 'next-auth/react'

export default function Header() {
  const { data: session } = useSession()
  return (
    <header>
      {session ? (
        <>
          <p>Hello, {session.user?.name}!</p>
          <button onClick={() => signOut()}>Sign out</button>
        </>
      ) : (
        <button onClick={() => signIn('google')}>Sign in with Google</button>
      )}
    </header>
  )
}

7. Secure Session Handling

• Wrap your app with <SessionProvider session={session}> in _app.tsx.
• NextAuth stores tokens in HTTP-only cookies by default—immune to XSS.
• Customize session callbacks and JWT contents via the callbacks option.

8. Advanced Customization

8.1. Custom Sign-In Page

Override the built-in UI with your own page:

export default NextAuth({
  pages: {
    signIn: '/auth/signin',
  },
  // ...
})

8.2. Access Control

Restrict pages to authenticated users:

import { getSession } from 'next-auth/react'

export async function getServerSideProps(ctx) {
  const session = await getSession(ctx)
  if (!session) {
    return { redirect: { destination: '/auth/signin', permanent: false } }
  }
  return { props: { session } }
}

9. Security Considerations

• ✅ Always use HTTPS in production to protect token transport.
• ✅ Rotate NEXTAUTH_SECRET periodically.
• ✅ Limit scopes requested to only what you need (scope option).
• ✅ Monitor and revoke unused OAuth app credentials in provider consoles.

10. Troubleshooting & Debugging

• ❗ Invalid redirect URI: Ensure your OAuth app settings list the exact callback URL (e.g., https://yourdomain.com/api/auth/callback/google).
• ❗ Environment variables not loading: Restart your dev server after adding to .env.local.
• ❗ Session undefined: Wrap pages/components in <SessionProvider> and call useSession() only inside React components.

11. Final Checklist

• ✅ Installed and configured NextAuth.js
• ✅ Added at least one OAuth provider (Google, GitHub, etc.)
• ✅ Set up secure environment variables
• ✅ Integrated sign-in/sign-out buttons
• ✅ Wrapped app in SessionProvider
• ✅ Enforced HTTPS and secure cookies
• ✅ Tested callbacks and redirect URIs

With these steps in place, your Next.js app will have robust, secure OAuth 2.0 authentication ready for production!