Passwordless Authentication with Next.js, Prisma, and next-auth

In this post, you'll learn how to add passwordless authentication to your Next.js app using Prisma and next-auth. By the end of this tutorial, your users will be able to log in to your app with either their GitHub account or a Slack-styled magic link sent right to their Email inbox.

If you want to follow along, clone this repo and switch to the start-here branch! 😃

If you want to see the live coding version of this tutorial, check out the recording below! 👇

Step 0: Dependencies and database setup

Before we start, let's install Prisma and next-auth into the Next.js project.

npm i next-auth

npm i -D @prisma/cli @types/next-auth

I'm using TypeScript in this tutorial, so I'll also install the type definitions for next-auth

You will also need a PostgreSQL database to store all the user data and active tokens.

If you don't have access to a database yet, Heroku allows us to host PostgreSQL databases for free, super handy! You can check out this post by Nikolas Burk to see how to set it up.

If you are a Docker fan and would rather keep everything during development local, you can also check out this video I did on how to do this with Docker Compose.

Before moving on to the next step, make sure you have a PostgreSQL URI in this format:

postgresql://<USER>:<PASSWORD>@<HOST_NAME>:<PORT>/<DB_NAME>

Step 1: Initialize Prisma

Awesome! Let's generate a starter Prisma schema and a @prisma/client module into the project.

npx prisma init

Notice that a new directory prisma is created under your project. This is where all the database magic happens. 🧙‍♂️

Now, replace the dummy database URI in /prisma/.env with your own.

Step 2: Define database schema for authentication

next-auth requires us to have specific tables in our database for it to work seamlessly. In our project, the schema file is located at /prisma/schema.prisma.

Let's use the default schema for now, but know that you can always extend or customize the data models yourself.

Note: If you have an existing database, after replacing the dummy database URI, you can run npx prisma introspect to generate the schema.prisma for your database and work from there. Then, you should add the following data models to the generated schema.prisma file.

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model Account {
  id                 Int       @default(autoincrement()) @id
  compoundId         String    @unique @map(name: "compound_id")
  userId             Int       @map(name: "user_id")
  providerType       String    @map(name: "provider_type")
  providerId         String    @map(name: "provider_id")
  providerAccountId  String    @map(name: "provider_account_id")
  refreshToken       String?   @map(name: "refresh_token")
  accessToken        String?   @map(name: "access_token")
  accessTokenExpires DateTime? @map(name: "access_token_expires")
  createdAt          DateTime  @default(now()) @map(name: "created_at")
  updatedAt          DateTime  @default(now()) @map(name: "updated_at")

  @@index([providerAccountId], name: "providerAccountId")
  @@index([providerId], name: "providerId")
  @@index([userId], name: "userId")

  @@map(name: "accounts")
}

model Session {
  id           Int      @default(autoincrement()) @id
  userId       Int      @map(name: "user_id")
  expires      DateTime
  sessionToken String   @unique @map(name: "session_token")
  accessToken  String   @unique @map(name: "access_token")
  createdAt    DateTime @default(now()) @map(name: "created_at")
  updatedAt    DateTime @default(now()) @map(name: "updated_at")

  @@map(name: "sessions")
}

model User {
  id            Int       @default(autoincrement()) @id
  name          String?
  email         String?   @unique
  emailVerified DateTime? @map(name: "email_verified")
  image         String?
  createdAt     DateTime  @default(now()) @map(name: "created_at")
  updatedAt     DateTime  @default(now()) @map(name: "updated_at")

  @@map(name: "users")
}

model VerificationRequest {
  id         Int      @default(autoincrement()) @id
  identifier String
  token      String   @unique
  expires    DateTime
  createdAt  DateTime  @default(now()) @map(name: "created_at")
  updatedAt  DateTime  @default(now()) @map(name: "updated_at")

  @@map(name: "verification_requests")
}

Let's break it down a bit:

In the schema file, we defined 4 data models - Account, Session, User and VerificationRequest. The User and Account models are for storing user information, the Session model is for managing active sessions of the user, and VerificationRequest is for storing valid tokens that are generated for magic link Email sign in.

The @map attribute is for mapping the Prisma field name to a database column name, such as compoundId to compound_id, which is what next-auth needs to have it working.

snake_case is often used as a naming convention in database environments, but camelCase is how we usually name things in JavaScript and TypeScript. It's perfectly fine to name Prisma fields in snake_case, but it wouldn't look so nice. :)

Next, let's run these commands to populate the database with the tables we need.

npx prisma migrate save --experimental
npx prisma migrate up --experimental

Then, run this command to generate a Prisma client tailored to the database schema.

npx prisma generate

Now, if you open up Prisma Studio with the following command, you will be able to inspect all the tables that we just created in the database.

npx prisma studio

Step 3: Configure next-auth

Before we start configuring next-auth, let's create another .env file in the project root to store secrets that will be used by next-auth (or rename the .env.example file from the template, if you cloned the tutorial repo).

SECRET=RAMDOM_STRING
SMTP_HOST=YOUR_SMTP_HOST
SMTP_PORT=YOUR_SMTP_PORT
SMTP_USER=YOUR_SMTP_USERNAME
SMTP_PASSWORD=YOUR_SMTP_PASSWORD
SMTP_FROM=YOUR_REPLY_TO_EMAIL_ADDRESS
GITHUB_SECRET=YOUR_GITHUB_API_CLIENT_SECRET
GITHUB_ID=YOUR_GITHUB_API_CLIENT_ID
DATABASE_URL=postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public

Now, let's create a new file at /pages/api/auth/[...nextauth].ts as a "catch-all" Next.js API route for all the requests sent to your-app-url-root/api/auth (like localhost:3000/api/auth).

Inside the file, first import the essential modules from next-auth, and define an API handler which passes the request to the NextAuth function, which sends back a response that can either be an entirely generated login form page or a callback redirect. To connect next-auth to the database with Prisma, you will also need to import PrismaClient and initialize a Prisma Client instance.

import { NextApiHandler } from "next";
import NextAuth from "next-auth";
import Providers from "next-auth/providers";
import Adapters from "next-auth/adapters";

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

// we will define `options` up next
const authHandler: NextApiHandler = (req, res) => NextAuth(req, res, options);
export default authHandler;

Now let's create the options object. Here, you can choose from a wide variety of builtin authentication providers. In this tutorial, we will use GitHub OAuth and "magic links" Email to authenticate the visitors.

Step 3.1: Set up GitHub OAuth

For the builtin OAuth providers like GitHub, you will need a clientId and a clientSecret, both of which can be obtained by registering a new OAuth app at Github.

First, log into your GitHub account, go to Settings, then navigate to Developer Settings, then switch to OAuth Apps.

Clicking on the Register a new application button will redirect you to a registration form to fill out some information for your app. The Authorization callback URL should be the Next.js /api/auth route that we defined earlier (http://localhost:3000/api/auth).

An important thing to note here is that the Authorization callback URL field only supports 1 URL, unlike Auth0, which allows you to add additional callback URLs separated with a comma. This means if you want to deploy your app later with a production URL, you will need to set up a new GitHub OAuth app.

Click on the Register Application button, and then you will be able to find your newly generated Client ID and Client Secret. Copy this info into your .env file in the root directory.

Now, let's go back to /api/auth/[...nextauth].ts and create a new object called options, and source the GitHub OAuth credentials like below.

const options = {
  providers: [
    Providers.GitHub({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET,
    }),
  ],
};

OAuth providers typically work the same way, so if your choice is supported by next-auth, you can configure it the same way as we did with GitHub here. If there is no builtin support, you can still define a custom provider.

Step 3.2: Set up passwordless Email authentication

To allow users to authenticate with magic link Emails, you will need to have access to an SMTP server. These kinds of Emails are considered transactional Emails. If you don't have your own SMTP server or your mail provider has strict restrictions regarding outgoing Emails, I would recommend using SendGrid, or alternatively Amazon SES, Mailgun and others.

When you have your SMTP credentials ready, you can put that information into the .env file, add a Providers.Email({}) to the list of providers, and source the environment variables like below.

const options = {
  providers: [
    // Providers.GitHub ...
    Providers.Email({
      server: {
        host: process.env.SMTP_HOST,
        port: Number(process.env.SMTP_PORT),
        auth: {
          user: process.env.SMTP_USER,
          pass: process.env.SMTP_PASSWORD,
        },
      },
      from: process.env.SMTP_FROM, // The "from" address that you want to use
    }),
  ],
};

Step 3.3: Link up Prisma

The final step for setting up next-auth is to tell it to use Prisma to talk to the database. For this, we will use the Prisma adapter and add it to the options object. We will also need a secret key to sign and encrypt tokens and cookies for next-auth to work securely - this secret should also be sourced from environment variables.

const options = {
  providers: [
    // ...
  ],
  adapter: Adapters.Prisma.Adapter({ prisma }),
  secret: process.env.SECRET,
};

To summarize, your pages/api/auth/[...nextauth].ts should look like the following:

import { NextApiHandler } from "next";
import NextAuth from "next-auth";
import Providers from "next-auth/providers";
import Adapters from "next-auth/adapters";

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

const authHandler: NextApiHandler = (req, res) => NextAuth(req, res, options);
export default authHandler;

const options = {
  providers: [
    Providers.GitHub({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET,
    }),
    Providers.Email({
      server: {
        host: process.env.SMTP_HOST,
        port: Number(process.env.SMTP_PORT),
        auth: {
          user: process.env.SMTP_USER,
          pass: process.env.SMTP_PASSWORD,
        },
      },
      from: process.env.SMTP_FROM,
    }),
  ],
  adapter: Adapters.Prisma.Adapter({
    prisma,
  }),

  secret: process.env.SECRET,
};

Step 4: Implement authentication on the frontend

In the application, you can use next-auth to check if a visitor has cookies/tokens corresponding to a valid session. If no session can be found, then it means the user is not logged in.

With next-auth, you have 2 options for checking the sessions - it can be done inside a React component using the useSession() hook, or on the backend (getServerSideProps or in API routes) with the helper function getSession().

Let's have a look at how it works.

Step 4.1: Checking user sessions with the useSession() hook

In order to use the hook, you'll need to wrap the component inside a next-auth provider. For the authentication flow to work anywhere in your entire Next.js app, create a new file called /pages/_app.tsx.

import { Provider } from "next-auth/client";
import { AppProps } from "next/app";

const App = ({ Component, pageProps }: AppProps) => {
  return (
    <Provider session={pageProps.session}>
      <Component {...pageProps} />
    </Provider>
  );
};

export default App;

Now, you can go to /pages/index.tsx, and import the useSession hook from the next-auth/client module. You will also need the signIn and signOutfunctions to implement the authentication interaction. ThesignIn function will redirect users to a login form, which is automatically generated by next-auth.

import { signIn, signOut, useSession } from "next-auth/client";

The useSession() hook returns an array with the first element being the user session, and the second one a boolean indicating the loading status.

// ...
const IndexPage = () => {
  const [session, loading] = useSession();

  if (loading) {
    return <div>Loading...</div>;
  }
};

If the session object is null, it means the user is not logged in. Additionally, we can obtain the user information from session.user.

// ...
if (session) {
  return (
    <div>
      Hello, {session.user.email ?? session.user.name} <br />
      <button onClick={() => signOut()}>Sign out</button>
    </div>
  );
} else {
  return (
    <div>
      You are not logged in! <br />
      <button onClick={() => signIn()}>Sign in</button>
    </div>
  );
}

The finished /pages/index.tsx file should look like the following.

import { signIn, signOut, useSession } from "next-auth/client";

const IndexPage = () => {
  const [session, loading] = useSession();

  if (loading) {
    return <div>Loading...</div>;
  }

  if (session) {
    return (
      <div>
        Hello, {session.user.email ?? session.user.name} <br />
        <button onClick={() => signOut()}>Sign out</button>
      </div>
    );
  } else {
    return (
      <div>
        You are not logged in! <br />
        <button onClick={() => signIn()}>Sign in</button>
      </div>
    );
  }
};

export default IndexPage;

Now, you can spin up the Next.js dev server with npm run dev, and play with the authentication flow!

Step 4.2: Checking user sessions with getSession() on the backend

To get user sessions from the backend code, inside either getServerSideProps() or an API request handler, you will need to use the getSession() async function.

Let's create a new /pages/api/secret.ts file for now like below. The same principles from the frontend apply here - if the user doesn't have a valid session, then it means they are not logged in, in which case we will return a message with a 403 status code.

import { NextApiHandler } from "next";
import { getSession } from "next-auth/client";

const secretHandler: NextApiHandler = async (req, res) => {
  const session = await getSession({ req });
  if (session) {
    res.end(
      `Welcome to the VIP club, ${session.user.name || session.user.email}!`
    );
  } else {
    res.statusCode = 403;
    res.end("Hold on, you're not allowed in here!");
  }
};

export default secretHandler;

Go visit localhost:3000/api/secret without logging in, and you will see something like in the following image.

Conclusion

And that's it, authentication is so much easier with next-auth!

I hope you have enjoyed this tutorial and have learned something useful! You can always find the starter code and the completed project in this GitHub repo.

Also, check out the Awesome Prisma list for more tutorials and starter projects in the Prisma ecosystem!