next-auth

What is next-auth?

NextAuth.js is a complete open-source authentication solution for Next.js applications. It provides a simple and secure way to add authentication to your Next.js app, supporting various authentication providers, including OAuth, email/password, and custom credentials.

What are next-auth's main functionalities?

OAuth Authentication

NextAuth.js supports OAuth authentication with various providers like Google, Facebook, GitHub, etc. The code sample demonstrates how to configure Google and Facebook OAuth providers.

```javascript
import NextAuth from 'next-auth';
import Providers from 'next-auth/providers';

export default NextAuth({
  providers: [
    Providers.Google({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET
    }),
    Providers.Facebook({
      clientId: process.env.FACEBOOK_CLIENT_ID,
      clientSecret: process.env.FACEBOOK_CLIENT_SECRET
    })
  ]
});
```

Email/Password Authentication

NextAuth.js allows email/password authentication by sending magic links to users' email addresses. The code sample shows how to configure the email provider.

```javascript
import NextAuth from 'next-auth';
import Providers from 'next-auth/providers';

export default NextAuth({
  providers: [
    Providers.Email({
      server: process.env.EMAIL_SERVER,
      from: process.env.EMAIL_FROM
    })
  ]
});
```

Custom Credentials Authentication

NextAuth.js supports custom credentials authentication, allowing you to define your own logic for authenticating users. The code sample demonstrates a simple username/password authentication.

```javascript
import NextAuth from 'next-auth';
import Providers from 'next-auth/providers';

export default NextAuth({
  providers: [
    Providers.Credentials({
      name: 'Credentials',
      credentials: {
        username: { label: 'Username', type: 'text' },
        password: { label: 'Password', type: 'password' }
      },
      authorize: async (credentials) => {
        const user = { id: 1, name: 'User' };
        if (credentials.username === 'user' && credentials.password === 'password') {
          return Promise.resolve(user);
        } else {
          return Promise.resolve(null);
        }
      }
    })
  ]
});
```

Session Management

NextAuth.js provides session management, allowing you to access the user's session data on both the client and server sides. The code sample shows how to retrieve the session in a Next.js page using getServerSideProps.

```javascript
import { getSession } from 'next-auth/client';

export async function getServerSideProps(context) {
  const session = await getSession(context);
  return {
    props: { session }
  };
}
```

Other packages similar to next-auth

passport

Passport is a popular authentication middleware for Node.js. It is highly flexible and supports a wide range of authentication strategies. Compared to NextAuth.js, Passport requires more manual setup and configuration, but it offers greater flexibility and can be used with any Node.js framework.

auth0

Auth0 is a cloud-based authentication service that provides a comprehensive solution for authentication and authorization. It supports various authentication methods and integrates well with many platforms. Compared to NextAuth.js, Auth0 is a third-party service that requires a subscription for advanced features, but it offers a more extensive set of features and easier integration with multiple platforms.

firebase-auth

Firebase Authentication is a part of Google's Firebase platform, providing backend services to authenticate users in your app. It supports email/password, phone number, and various social providers. Compared to NextAuth.js, Firebase Authentication is a managed service that integrates seamlessly with other Firebase services, but it may not offer the same level of customization as NextAuth.js.

README

NextAuth

NextAuth is an authenticaton library for Next.js projects.

The NextAuth library uses Express and Passport, the most commonly used authentication library for Node.js, to provide support for signing in with email and with services like Facebook, Google and Twitter.

NextAuth adds Cross Site Request Forgery (CSRF) tokens and HTTP Only cookies, supports univeral rendering and does not require client side JavaScript.

It adds session support without using client side accessible session tokens, providing protection against Cross Site Scripting (XSS) and session hijacking, while leveraging localStorage where available to cache non-critical session state for optimal performance in Single Page Apps.

The NextAuthClient library for NextAuth is designed to work with React pages powered by Next.js.

It contains an example site that shows how to use it in a simple project.

It's also used in the nextjs-starter.now.sh project, which provides a more complete example with a live demo.

Routes

NextAuth adds a number of routes under `/auth':

• POST /auth/email/signin - Request Sign In Token
• GET /auth/email/signin/:token - Validate Sign In Token
• POST /auth/signout - Sign Out
• GET /auth/csrf - CSRF endpoint for Single Page Apps
• GET /auth/session - Session endpoint for Single Page Apps
• GET /auth/linked - View linked accounts for Single Page Apps

All POST routes request must include a CSRF token (this is handled automatically by the NextAuthClient).

CSRF, Session and Linked Account endpoints are provided for Single Page Apps.

Note: Session Tokens are stored in HTTP Only cookies to prevent session hijacking and protect against Cross Site Scripting (XSS) attacks. Only HTTP requests that originate from the origional domain are able to read from them.

In addition, it will add the following routes for each oAuth provider currently configured:

• GET /auth/oauth/${provider}
• GET /auth/oauth/${provider}/callback
• POST /auth/oauth/${provider}/unlink

You can see which routes are configured and the callback URLs defined for them via /auth/providers:

• GET /auth/providers

It will return a JSON object with the current oAuth provider configuration:

{
  "Facebook": {
    "signin": "/auth/oauth/facebook",
    "callback": "/auth/oauth/facebook/callback"
  },
  "Google": {
    "signin": "/auth/oauth/google",
    "callback": "/auth/oauth/google/callback"
  },
  "Twitter": {
    "signin": "/auth/oauth/twitter",
    "callback": "/auth/oauth/twitter/callback"
  }
}

Note: The /auth prefix is configurable on the server, but it is hard coded in the NextAuthClient so should not be changed. If you have other routes in in /auth the will not be

Pages

You will need to create following pages in ./pages/auth/:

• index.js - Sign In Page
• error.js - Error Handling
• check-email.js - Check Email Message
• callback.js - Callback Page

You can find examples of these included you can you can copy and paste into your project.

Getting Started

If you have an existing site, create an index.js file in the root of your project containing the following:

// Include Next.js, Next Auth and a Next Auth config
const next = require('next')
const nextAuth = require('next-auth')
const nextAuthConfig = require('./next-auth.config')

// Load environment variables from .env
require('dotenv').load()

// Initialize Next.js
const nextApp = next({
  dir: '.',
  dev: (process.env.NODE_ENV === 'development')
})

// Add next-auth to next app
nextApp
.prepare()
.then(() => {
  // Load configuration and return config object
  return nextAuthConfig()
})
.then(nextAuthOptions => {
  // Pass Next.js App instance and NextAuth options to NextAuth
  return nextAuth(nextApp, nextAuthOptions)  
})
.then((response) => {
  console.log(`Ready on http://localhost:${process.env.PORT || 3000}`)
})
.catch(err => {
  console.log('An error occurred, unable to start the server')
  console.log(err)
})

You can also copy over the 'auth' pages from the example project into your own pages directory and customise them:

• example pages

You can add the following to your package.json file to start the project:

"scripts": {
  "dev": "NODE_ENV=development node index.js",
  "build": "next build",
  "start": "node index.js"
},

Configuration

Configuration of NextAuth in can be split across three files to make it easier to understand and manage.

You can copy over the following configuration files into the root of your project to get started:

• next-auth.config.js
• next-auth.functions.js
• next-auth.providers.js

You can also add a .env file to the root of the project as a place to specify configuration options. The provided example files for NextAuth will use one if there is is one.

SERVER_URL=http://localhost:3000
MONGO_URI=mongodb://localhost:27017/my-database
FACEBOOK_ID=
FACEBOOK_SECRET=
GOOGLE_ID=
GOOGLE_SECRET=
TWITTER_KEY=
TWITTER_SECRET=
EMAIL_FROM=[e-mail]
EMAIL_SERVER=smtp.gmail.com
EMAIL_PORT=465
EMAIL_USERNAME=[e-mail]
EMAIL_PASSWORD=

next-auth.config.js

Basic configuration of NextAuth is handled in next-auth.config.js.

It is where the next-auth.functions.js and next-auth.providers.js files are loaded.

next-auth.functions.js

Methods for user management and sending email are defined in next-auth.functions.js

• find({id,email,emailToken,provider})
• insert(user)
• update(user)
• remove(id)
• serialize(user)
• deserialize(id)
• sendSigninEmail({email, url}) // Send email

The example configuration is designed to work with document stortage databaes like Mongo DB. By defining the behaviour in these functions you can use NextAuth with any database, including a relational database that uses SQL.

next-auth.providers.js

Configuration for oAuth providers are defined in next-auth.functions.js

It includes configuration examples for Facebook, Google and Twitter oAuth, which can easily be copied and replicated to add support for signing in other oAuth providers. For tips on configuring oAuth see AUTHENTICATION.md.

---

See the example site and the expended example at nextjs-starter.now.sh for a working examples of how to use NextAuth.