loading...
Cover image for πŸ”‘ Passwordless Authentication with Next.js, Prisma, and next-auth
Prisma

πŸ”‘ Passwordless Authentication with Next.js, Prisma, and next-auth

hexrcs profile image Xiaoru Li πŸ‡¨πŸ‡³πŸ‡©πŸ‡ͺ ・Updated on ・10 min read

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! πŸ˜ƒ

`next-auth` OAuth demo
Check out the slick auth flow!


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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Step 1: Initialize Prisma

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

npx prisma init
Enter fullscreen mode Exit fullscreen mode

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.

Project structure after running `npx prisma init`
Project structure after running npx prisma init

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")
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

npx prisma generate
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Prisma studio screenshot
Prisma Studio model selection

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
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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.

GitHub OAuth apps
GitHub 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.

Registering an OAuth app
Registering an 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.

Obtaining OAuth Client ID and Client Secret
Obtaining OAuth Client ID and Client Secret

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,
    }),
  ],
};
Enter fullscreen mode Exit fullscreen mode

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
    }),
  ],
};
Enter fullscreen mode Exit fullscreen mode

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,
};
Enter fullscreen mode Exit fullscreen mode

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,
};
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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";
Enter fullscreen mode Exit fullscreen mode

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>;
  }
};
Enter fullscreen mode Exit fullscreen mode

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>
  );
}
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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

403 error if the user is not logged in
403 error if the user is not logged in

Conclusion

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

High five gif

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!

Discussion

pic
Editor guide
Collapse
epavanello profile image
Emanuele Pavanello

I started to use prisma and seems good, thanks for this post! πŸ’ͺ🏻

Collapse
hexrcs profile image
Xiaoru Li πŸ‡¨πŸ‡³πŸ‡©πŸ‡ͺ Author

You are welcome, hope you found this tutorial useful! πŸ‘

Have you joined the Prisma Slack channel? If you encountered any problem with Prisma, feel free to post it there!

Collapse
epavanello profile image
Emanuele Pavanello

I didn’t know this channel, thank you very much πŸ‘πŸ»

Collapse
spsaucierbakkt profile image
Stevo

So, uh.. doesn't this allow anyone with an email address to log into the app? Where is the user/email whitelist?

Collapse
garytube profile image
Gary

how would I add new columns to the user model? the offical documentation is not very helpfule.

i want to extend the users schema with user roles for authz

Collapse
thebiglabasky profile image
HervΓ© Labas

Hi Gary,
While it's still experimental, and will be updated in the coming weeks, you can use Prisma migrate to do that.
Update your schema with the columns you need, run migrate (or db push if you don't need to keep and share the history of your schema migrations)
The docs about that are here: prisma.io/docs/reference/tools-and...
Hope it helps!