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

About NextAuth

NextAuth is an authentication 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 universal 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 NextAuth comes with a client library, designed to work with React pages powered by Next.js to easily add universal session support to sites.

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.

Note: As of version 1.5 NextAuth is also compatible non-Next.js React projects, just pass null instead of a nextApp instance when calling nextAuth().

You will need to handle setting up routes before and after initialising NextAuth if you are not using Next.js. NextAuth lets you pass an instance of express as 'expressApp' option (and returns it in the response).

Example Client Usage

import React from 'react'
import { NextAuth } from 'next-auth/client'

export default class extends React.Component {
  static async getInitialProps({req}) {
    return {
      session: await NextAuth.init({req})
    }
  }
  render() {
    if (this.props.session.user) {
      return(
        <div>
          <p>You are logged in as {this.props.session.user.name || this.props.session.user.email}.</p>
        </div>
        )
    } else {
      return(
        <div>
          <p>You are not logged in.</p>
        </div>
      )
    }
  }
}

See Documentation for the NextAuth Client for more information on how to interact with the client.

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.

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 original 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 this route:

• 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 via an option in the module, but it is currently hard coded in the client component, so you probably don't want to change it. It will be configurable in future releases.

Getting Started

Create an index.js file in the root of your Next.js 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 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"
}

Pages

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

• index.js // Sign In (and Link/Unlink)
• error.js // Error handling
• check-email.js // Check email prompt
• callback.js // Callback page, used to update state in Single Page Apps

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

Configuration

Configuration 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

The example configuration provided is for Mongo DB. By defining the behaviour in these functions you can use NextAuth with any database, including a relational database that uses SQL.

Required

• find({id,email,emailToken,provider})
• insert(user, oAuthProfile)
• update(user, oAuthProfile)
• remove(id)
• serialize(user)
• deserialize(id)

Optional

• sendSigninEmail({email, url, req})
• signIn({form, req})

The sendSigninEmail() method is used to send an email for email token based sign in (one time use passwords). Omit it or set it to null to disable email based sign in.

The signIn() method is used to handle authenticating with custom credentials (e.g. username and password, 2FA token, etc). Omit it or leave it undefined unless you need it.

You can use any combination of authentication methods (email, credentials, oAuth providers).

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 included example site and the expanded example at nextjs-starter.now.sh.