3/ NextAuth v4: introduction

NextAuth is an open source authentication solution for fullstack (Next) applications. It offers support for different login methods like OAuth providers (f.e. Google, GitHub, ...), credentials (classic email + password) and email ("magic links" via email that the user can click on to sign in). It also offers different database adapters that will directly put login details in a specific database like MongoDB or tap into an ORM like Prisma.

In this series we will only focus on using NextAuth with one OAuth provider (Google) and the credentials provider (email + password).

Now in English

That's the official explanation of NextAuth. But, what does it specifically do?

1. Functions and handlers

When using NextAuth, you aim to build authentication: a login system. A login page that lets you click a button login with your google account or a form where you enter your email and password and then submit. The buttons and the form, that's just plain Next. NextAuth offers you functions to call, for example signIn and signOut. These start up the authentication flow. So NextAuth provides functions that let you interact with the authentication process.

2. Providers

NextAuth has a whole range of build-in providers. These let you sign in with for example Google, Github or using an email + password. NextAuth provides these for you. You don't have to figure out how they work internally. The provider needs some configuration and is ready to go. NextAuth does the heavy lifting for you.

3. Cookies

On a successful login, NextAuth will set a bunch of cookies in your browser. This is a third functionality of NextAuth. You don't have to worry about these cookies, NextAuth handles this.

4. Creating Tokens

One of these cookies holds a JWT token. These are encoded (not encrypted) strings that look like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The structure is this: somecode.somecode.somecode or to be more specific header.payload.signature. The payload part holds encoded data like a userName or userId or whatever you need it to hold.

NextAuth will put some data into this token (payload) by default and allows you to customize this payload with whatever you need. This is a fourth NextAuth feature: creating tokens.

5. Reading Tokens

On top of that, NextAuth gives you the tools to check if there is a token and retrieve the data from it. In other words to check if the user is signed in by reading the token.

6. Backend

What is missing here is a database. In this series we integrate with Strapi. So at some point during the login process we want to put users into the DB or check the DB if this user is registered. NextAuth provides you with the functionality to do this.

NextAuth overview

And that is the main functionality of NextAuth (in this series):

1. Functions that trigger login and logout processes.
2. Built-in providers and adapters that can be customized.
3. Setting cookies.
4. Creating and populating JWT tokens.
5. Reading these token using helper functions.
6. Integration with a database.

This is more or less what NextAuth does. It should also give some idea where Next ends and where NextAuth starts.

Route handlers

The main configuration or customization of NextAuth happens in a route handler. Let's do a quick recap what route handlers are.

route handlers in Next

To create an API route in Next 13+ (app router) you use route handlers. They are similar to page routes but instead of using page.tsx you use route.ts inside your route folder.

So, f.e. app/testing/route.ts creates an api route http://localhost:3000/testing that you can call. Obviously you will need to write the necessary code in the route.ts file but you can read all about that in the next docs.

NextAuth route handler

Under the hood, NextAuth calls a NextAuth route handler that we will set up. We won't have to call it directly, NextAuth does it for us. But, we do have to write this route handler ourself to do most of the NextAuth configuration.

Why is this important? To avoid confusion. The main configuration and setup file for NextAuth is a route handler. Why? Because that is how NextAuth works internally.

Default components

We spoke about how we have to build components like login forms or buttons ourselves but that is not strictly true. NextAuth has some default login components like buttons and forms. But they can't be customized so they are of very limited use.

As we begin to build our little project, we will use these default components as a starting point. This will keep things simpler. We will then gradually replace these default components with custom components.

Summary

I took some extra time to write this chapter because NextAuth confused me quite a bit when I first started digging into it. So I tried to clarify what NextAuth does and how it does that.

The functionality of NextAuth can summarized like this:

1. Functions that trigger login and logout processes.
2. Built-in providers and adapters that can be customized.
3. Setting cookies.
4. Creating and populating JWT tokens.
5. Reading these token using helper functions.
6. Integration with a database.

Under the hood, NextAuth relies a lot on a custom route handler and that is where will write a lot of configuration and customization code.

In the next chapter we are going to start coding.

If you want to support my writing, you can donate with paypal.