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

This is work in progress of version 2.0 of NextAuth, an authentication library for Next.js.

Version 2.0 is a complete re-write, designed from the ground up for serverless.

• Built for Serverless - unlike version 1.x it doesn't depend on Express or PassportJS (but is compatible with them) and is designed to support automatic code splitting at build time for optimal bundle size and performance.
• Supports the same oAuth 1.x and oAuth 2.x and email authentication flows as version 1.x (both client and server side).
• Simple configuration with out-of-the-box support for common oAuth providers and databases.

If you are familiar with version 1.x you will appreciate the much simpler and hassle free configuration, especially for provider configuration, database adapters and much improved Cross Site Request Forgery token handling (now enabled by default for next-auth routes only).

Additional options and planned features will be announced closer to release.

Note: NextAuth is not associated with Next.js or Vercel.

Getting Started

Configuration is much simpler and more powerful than in NextAuth 1.0, with both SQL and Document databases supported out of the box. There are predefined models for Users and Sessions, which you can use (or extend or replace with your own models/schemas).

Server

To add next-auth to a project, create a file to handle authentication requests at pages/api/auth/[...slug.js]:

import NextAuth from 'next-auth'
import Providers from 'next-auth/providers'
import Adapters from 'next-auth/adapters'

const options = {
  site: process.env.SITE_NAME || 'http://localhost:3000',
  providers: [
    Providers.Twitter({
      clientId: process.env.TWITTER_CLIENT_ID,
      clientSecret: process.env.TWITTER_CLIENT_SECRET,
    }),
    Providers.Google({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET
    }),
    Providers.GitHub({
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET
    }),
  ],
  adapter: Adapters.Default()
}

export default (req, res) => NextAuth(req, res, options)

All requests to pages/api/auth/* (signin, callback, signout) will now be automatically handed by NextAuth.

Client

You can use the useSession() hook to see if a user is signed in.

export default () => {
  const [session, loading] = NextAuth.useSession()

  return <>
    {loading && <p>Checking session…</p>}
    {!loading && session && <p>Signed in as {session.user.name || session.user.email}.</p>}
    {!loading && !session && <p><a href="/api/auth/signin">Sign in here</p>}
  </>
}

This is all the code you need to add support for signing in to a project!

Using useSession() like this will work perfectly fine, but keep in mind this will do a network request to fetch the session in each component you use it. If you want to only do one network request you can wrap your component tree in our Provider, which will make useSession() use React Context instead.

You can use this Provider on a specific page if you want, or for all pages by overriding your _app.js file in Next.js as documented here Example pages/_app.js:

export default ({ Component, pageProps }) => {
  return (
    <NextAuth.Provider>
      <Component {...pageProps} />
    </NextAuth.Provider>
  )
}

Server Side Rendering

Authentication in Server Side Rendering flows is also supported.

import NextAuth from 'next-auth/client'

export default ({ session }) => <>
  {session && <p>Signed in as {session.user.name || session.user.email}.</p>}
  {!session && <p><a href="/api/auth/signin">Sign in here</a></p>}
</>

export async function getServerSideProps({req}) {
  const session = await NextAuth.session({req})
  return {
    props: {
      session
    }
  }
}

You can use this method and the useSession() hook together - the hook can be pre-populated with the session object from the server side call, so that it is avalible immediately when the page is loaded, and updated client side when the page is viewed in the browser.

You can also call NextAuth.session() function in client side JavaScript, without needing to pass a req object - it is only needed when calling the function from getServerSideProps or getInitialProps.

Authentication between the client and server is handled securely, using an HTTP only cookie for the session ID.

Important! The API for 2.0 is subject to change before release.

Configuration

Configuration options are passed to NextAuth when initalizing it (in your /api/ route).

The only things you will probably need to configure are your site name (e.g. 'http://www.example.com'), which should be set explicitly for security reasons, a list of authentication services (Twitter, Facebook, Google, etc) and a database adapter.

An "Adapter" in NextAuth is the thing that connects your application to whatever system you want to use to store data for user accounts, sessions, etc.

NextAuth comes with a default adapter that uses TypeORM so that it can be be used with many different databases without any configuration, you simply add the database driver you want to use to your project and tell NextAuth to use it.

Simple Example

This is an example of how to use an SQLite in memory database, which can be useful for development and testing, and to check everything is working:

1. Install the database driver as a dependancy in the usual way - e.g. npm i sqlite3
2. Pass a TypeORM configuration object when calling NextAuth() in your API route.

e.g.

adapter: Adapters.Default({
  type: 'sqlite',
  database: ':memory:'
}),

You can pass database credentials securely, using environment variables for options.

See the TypeORM configuration documentation for more details about supported options.

Supported Databases

The following databases are supported by the default adapter:

• cordova
• expo
• mariadb
• mongodb
• mssql
• mysql
• oracle
• postgres
• sqlite
• sqljs
• react-native

Appropriate tables / collections for Users, Sessions (etc) will be created automatically. You can customize, extend or replace the models by passing additional options to the Adapters.Default() function.

If you are using a database that is not supported out of the box - or if you want to use NextAuth with an existing database (or have a more complex setup, with accounts and sessions spread across different systems - you can pass your own methods to be called for user and session creation / deletion (etc).

Important! The list of supported databases is subject to change before release.

Customization

NextAuth automatically crates simple, unbranded authentication pages for handling Sign in, Email Verification, callbacks, etc.

These are generated based on the configuration supplied, You can create custom authentication pages if you would like to customize the experience.

This documentation will be updated closer to release.