3/ NextAuth v4: introduction
Tags: nextauth, nextjs
Published: 2024-04-01 16:15:22

`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](https://nextjs.org/docs/app/building-your-application/routing/route-handlers).

### 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](https://www.paypal.com/donate/?hosted_button_id=4D78YQU4V5NEJ).