{"id":14725,"library":"next-auth","title":"NextAuth.js","description":"NextAuth.js (version 4.24.14) provides comprehensive authentication solutions for Next.js applications, supporting a wide range of authentication providers including OAuth, email, and credentials. This package is currently in maintenance mode, with active feature development now taking place in Auth.js (v5) under the `@auth/nextjs` package. It receives critical bug fixes and security updates for its v4 branch.","status":"maintenance","version":"4.24.14","language":"javascript","source_language":"en","source_url":"https://github.com/nextauthjs/next-auth","tags":["javascript","react","nodejs","oauth","jwt","oauth2","authentication","nextjs","csrf","typescript"],"install":[{"cmd":"npm install next-auth","lang":"bash","label":"npm"},{"cmd":"yarn add next-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add next-auth","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"TypeScript type for configuration object. next-auth is ESM-only since v3; CommonJS `require` is not supported for any import.","wrong":"const { AuthOptions } = require('next-auth')","symbol":"AuthOptions","correct":"import { AuthOptions } from 'next-auth'"}],"quickstart":{"code":"import NextAuth, { type AuthOptions } from 'next-auth';\nimport GitHubProvider from 'next-auth/providers/github';\n\n// For production, ensure these are robustly set via environment variables.\n// Example using a database adapter (uncomment and install if needed):\n// import { MongoDBAdapter } from '@next-auth/mongodb-adapter';\n// import clientPromise from '../../../lib/mongodb'; // Your MongoDB connection logic\n\nexport const authOptions: AuthOptions = {\n  // Configure one or more authentication providers\n  providers: [\n    GitHubProvider({\n      clientId: process.env.GITHUB_ID ?? '',\n      clientSecret: process.env.GITHUB_SECRET ?? ''\n    })\n    // ...add more providers here\n  ],\n  // Optional: Add a database adapter if you want to persist user sessions\n  // adapter: MongoDBAdapter(clientPromise),\n  \n  // REQUIRED: A secret to sign and encrypt session tokens. \n  // Use `openssl rand -base64 32` to generate a strong one.\n  secret: process.env.NEXTAUTH_SECRET ?? '',\n\n  // Callbacks are essential for custom session data, redirects, etc.\n  // https://next-auth.js.org/configuration/callbacks\n  callbacks: {\n    async session({ session, token, user }) {\n      // Example: add user ID to session (useful for database-backed sessions)\n      if (token?.sub) {\n        session.user.id = token.sub; \n      }\n      return session;\n    }\n  },\n  // Enable debug messages in the console during development\n  debug: process.env.NODE_ENV === 'development'\n};\n\nexport default NextAuth(authOptions);","lang":"typescript","description":"This code sets up a basic NextAuth.js API route (`pages/api/auth/[...nextauth].ts`) using GitHub as an OAuth provider. It demonstrates provider configuration, the mandatory `secret` environment variable, and a simple session callback."},"warnings":[{"fix":"For new projects or App Router, use `@auth/nextjs`. For existing v4 projects, refer to the Auth.js migration guide if planning to upgrade to v5, as it involves breaking changes.","message":"NextAuth.js v4 (next-auth) is in maintenance. The project has evolved into Auth.js (v5) under `@auth/nextjs` with significant architectural changes, especially for Next.js App Router support.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to `next-auth@4.24.14` or later to automatically handle the GitHub `issuer`. Alternatively, for custom GitHub provider configurations, manually add `issuer: 'https://github.com/login/oauth'`.","message":"Older versions of the GitHub provider (pre-4.24.14) may fail due to GitHub's RFC 9207 compliance, which introduced an `iss` (issuer) parameter that `openid-client` validates unconditionally.","severity":"gotcha","affected_versions":"<4.24.14"},{"fix":"Generate a strong, random 32-character string (e.g., `openssl rand -base64 32`) and set it as `NEXTAUTH_SECRET` in your environment variables. Consider providing multiple secrets for rotation separated by commas.","message":"A strong `NEXTAUTH_SECRET` environment variable is crucial for security. Without it, session tokens are not properly signed, making your application vulnerable.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"For full and idiomatic App Router support, consider migrating to `@auth/nextjs` (Auth.js v5). If staying with v4, ensure all client-side functionalities are correctly marked with `'use client'` and server actions/components are handled appropriately.","message":"Using `next-auth` v4 with Next.js App Router requires careful implementation (e.g., `'use client'` directives for client components like `SessionProvider`, `signIn`, `signOut`). It is primarily designed for the Pages Router.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Set a strong `NEXTAUTH_SECRET` environment variable (e.g., `NEXTAUTH_SECRET=your_super_secret_string`). This is critical for security.","cause":"The `NEXTAUTH_SECRET` environment variable is not set or is empty.","error":"[next-auth][error][NO_SECRET]"},{"fix":"Ensure that the page initiating the authentication flow is properly rendered with the CSRF token. If a custom sign-in page is used, ensure it correctly renders the CSRF token from `getCsrfToken()`. Clear browser cookies and try again.","cause":"The CSRF token submitted with the request does not match the expected token, often due to expired sessions, incorrect form submission, or network issues.","error":"[next-auth][error][CSRF_TOKEN_INVALID]"},{"fix":"Double-check your provider configuration in `[...nextauth].ts` (e.g., `GitHubProvider({ clientId: process.env.GITHUB_ID, ... })`) against the values registered with your OAuth provider (GitHub, Google, etc.). Ensure your callback URL (`AUTH_URL/api/auth/callback/github`) is correctly configured in the OAuth provider settings.","cause":"An error occurred during the OAuth sign-in process, often related to incorrect provider configuration (e.g., wrong `clientId`, `clientSecret`, or `callbackUrl`).","error":"[next-auth][error][SIGNIN_OAUTH_ERROR]"},{"fix":"Verify that the provider you are trying to use (e.g., `GoogleProvider`) is correctly imported and included in the `providers` array within `authOptions` in your `[...nextauth].ts` file.","cause":"The specified provider ID (e.g., 'google') is not found in the `providers` array in your `authOptions` configuration.","error":"Could not find a NextAuth.js provider with id \"google\" (or similar provider ID)"}],"ecosystem":"npm"}