This article is a guest post by Osmar Pérez. He wrote this blog post through the Write for the Community program. If you are passionate about everything Jamstack, open-source, or javascript and want to share, join the writer's guild!

In this tutorial, we will learn how to implement a local authentication system with Strapi and integrate it into the Frontend using the Next.js Framework and NextAuth.js.

Requirements:

• Node.js >= 12.x or <= 14.x installed on your machine [Node installation docs]
• NPM >= 6.x or YARN installed on your machine [YARN installation docs]
• PostgreSQL >= 10 installed on your machine or you can follow this tutorial

This tutorial was made with Ubuntu 20.04 and YARN

What you will learn:

• How to install Strapi with custom database Postgresql
• How to install Next.js and NextAuth
• Different ways to save a JWT token
• Recognizing the security implications of saving this type of token
• Building a credential-based authentication system with Strapi and NextAuth

What is Strapi?

Strapi is an attractive open-source Headless CMS that gives us the possibility to create an API in seconds. Its most important features are:

• It provides a fairly simple administration panel to create your data models and consume them directly as an API.
• It offers a plugin architecture to be able to be extended.
• APIs can be consumed via REST or GraphQL!
• Provides an authentication and authorization service with JWT.

And many other features that will grab you at the first instant...

1. Setup work directory

This architecture will consist of two main components:

• The backend called "api" with an API made with Strapi.
• And the frontend called "app" is managed by Next.js.

To get started, we will create the main folder containing our project.

1
2
mkdir next-strapi-auth
cd next-strapi-auth

Now, we will proceed to create a database with PostgreSQL:

1
sudo -i -u postgres

Once inside our Postgres user we run the command:

1
psql

In order to enter the PostgreSQL bash and create our database as follows:

1
2
3
CREATE DATABASE strapi;
CREATE ROLE strapiu WITH LOGIN PASSWORD 'strongpassword';
GRANT ALL PRIVILEGES ON DATABASE strapi TO strapiu;

Now, we close the postgresql bash and the user's session by typing twice exit.

1
2
postgres=# exit
postgres@user:~$ exit

Now we are ready to do our Strapi installation. To install Strapi we can use your preferred package manager:

1
2
yarn create strapi-app api //using yarn where api is the name of the project
npx create-strapi-app api //using npx where api is the name of the project

In this tutorial we will use postgresql, so we will use the custom installation, to use the database created before.

1
2
3
? Choose your installation type (Use arrow keys)
   Quickstart (recommended) 
❯  Custom (manual settings) 

Select postgres as our database:

1
2
3
4
5
6
? Choose your installation type Custom (manual settings)
? Choose your default database client 
  sqlite 
❯ postgres 
  mysql 
  mongo 

Then we enter the name of our database, in this case, Strapi.

1
2
3
? Choose your installation type Custom (manual settings)
? Choose your default database client postgres
? Database name: strapi

Then we select the host of our database, as we are working locally the host is the one that is indicated by default, so we simply press enter.

1
2
3
4
? Choose your installation type Custom (manual settings)
? Choose your default database client postgres
? Database name: strapi
? Host: (127.0.0.1) 

Strapi also needs to know the port of PostgreSQL, the standard port that is used by postgres is 5432 and will most certainly be that in your case as well. Otherwise, specify your own custom port number.

1
2
3
4
5
? Choose your installation type Custom (manual settings)
? Choose your default database client postgres
? Database name: strapi
? Host: 127.0.0.1
? Port: (5432) 

Now we enter the name of the user with rights in the database, in this case "strapiu".

1
2
3
4
5
6
? Choose your installation type Custom (manual settings)
? Choose your default database client postgres
? Database name: strapi
? Host: 127.0.0.1
? Port: 5432
? Username: strapiu

Now enter the chosen password for the database user:

1
2
3
4
5
6
7
? Choose your installation type Custom (manual settings)
? Choose your default database client postgres
? Database name: strapi
? Host: 127.0.0.1
? Port: 5432
? Username: strapiu
? Password: ***********

And finally, we will use the default configuration of SSL, so we just hit enter.

1
2
3
4
5
6
7
8
? Choose your installation type Custom (manual settings)
? Choose your default database client postgres
? Database name: strapi
? Host: 127.0.0.1
? Port: 5432
? Username: strapiu
? Password: ***********
? Enable SSL connection: No

The next step is to create our frontend with next.js for this we will use the following command:

1
2
3
npx create-next-app app
# or
yarn create next-app app

Up to this point we will have a file structure as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
.
├── api
│   ├── api
│   ├── build
│   ├── config
│   ├── extensions
│   ├── favicon.ico
│   ├── node_modules
│   ├── package.json
│   ├── public
│   ├── README.md
│   └── yarn.lock
└── app
    ├── node_modules
    ├── package.json
    ├── pages
    ├── public
    ├── README.md
    ├── styles
    └── yarn.lock

To start our development servers we must enter the following commands in the terminal:

1
2
    /app yarn dev
    /api yarn strapi dev

2. Introduction to JWT storage

What is a JWT?

JSON Web Token (JWT) is a JSON-based RFC 7519 open standard proposed by the IETF for the creation of access tokens that enable identity and privilege propagation between 2 peers.

Due to its size, a JWT can be sent through a URL, through a POST parameter, or within an HTTP header.

This token contains all the necessary information about an entity to avoid unnecessary queries to the database.

Advantages of JWT

• It is compact
• Can use X.509 certificate to sign token with public/private key pair
• Can be signed symmetrically with HMAC algorithm
• Easy to use, these tokens are decoded in JSON format, so it has support for multiple programming languages.

A JWT token is composed of 3 parts:

1.- JavaScript Object Signing and Encryption (JOSE) Header: Contains metadata about the type of token and the cryptographic algorithm used to secure its content.

2.- Payload: Contains all the information about the entity (usually the user) and its different attributes.

3.- Signature: It is used to verify the validity of the user sending the token and ensures that the message has not been changed along the way.

In the end, these 3 parts are concatenated in base64 in the following way: [header][payload][signature].

About token storage

In Strapi our JWT is generated by making a POST request, containing our user ID and password as follows:

1
2
3
4
{
  "identifier": "reader@strapi.io",
  "password": "strapi"
}

to the route http://localhost:1337/auth/local, this route will return us the JWT:

1
2
3
4
5
6
7
8
{
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiaWF0IjoxNTc2OTM4MTUwLCJleHAiOjE1Nzk1MzAxNTB9.UgsjjXkAZ-anD257BF7y1hbjuY3ogNceKfTAQtzDEsU",
    "user": {
        "id": 1,
        "username": "reader",
        ...
    }
}

Yeah, the request is made once every time the user wants to make a request to our API. So if the requirement is to store this token in the browser's memory, it's a pretty safe and easy solution. But what if I want my user to be able to refresh his screen or sync different tabs without having to log in again?

Let's discuss possible solutions:

LOCAL STORAGE

Many developers tend to store their tokens in the browsers localstorage for persistence between tabs and ease of use, remembering that these are not sent on every request like cookies, so they are not susceptible to CSRF attacks, but if an attacker can execute javascript code "XSS" in one of your NODE_MODULES packages or in some third party CDN like google analytics, immediately this attacker can get access to your token by executing code like the following.

1
<script>alert(localStorage.getItem(‘jwt’))</script>

It is important to understand that all token saving methods are vulnerable to XSS and, in some cases, will only make them more difficult to access.

I recommend that you watch this video to know what an XSS attack is and its implications.

SESSION STORAGE As with local storage, session storage presents the same problem, the only change is that when the user closes the window his token will be deleted, so this is not a viable option.

IN BROWSER MEMORY This is a secure solution, but if the user reloads the page, they will have to log in again. So it is only recommended if the use case is that the user has to log in again when reloading the page or the token is one-time use.

COOKIES My opinion, and that of many others, is that the best way to store these tokens is with cookies. But why?

Cookies are sent automatically on every browser request and have different security methods that allow you to give more reliability to your system, among them:

Secure: This flag ensures that the server will only send requests if the request is encrypted over the HTTPS protocol, this flag will help us to avoid man-in-the-middle attacks by not allowing the use of our cookies with the HTTP protocol.

SameSite: It is a cookie attribute defined in RFC6265, it allows us to add some security against CSRF type attacks, it has 3 different options.

• SameSite = Strict "Cookies are sent only in the domain where they are created".
• SameSite = None "Cookies work as before this RFC: cross-site"
• SameSite = Lax "Lax allows access to top-level HTTP requests such as GET in cross-site but blocks others such as POST"

HttpOnly: Let's suppose that our application has an XSS vulnerability. Then the attacker can take advantage of this vulnerability to steal our authentication cookie. To prevent this, we use the HttpOnly flag, which prevents our cookie from being accessed through JavaScript.

With the above, we mitigate the possibility of using XSS to obtain our token, but still not, however, there is a type of attack called XST that allows bypassing the HttpOnly flag in order to obtain our cookie.

This type of attack is independent of the security settings of our cookie and uses the HTTP Trace method combined with XSS to read the authentication cookie, even when the HTTP Only flag is set.

To prevent this type of attack, disable in the configuration of our HTTP server (Apache, Nginx, etc...) the possibility of sending HTTP trace requests, thus making it impossible for this type of attack to be carried out.

Now we know how to protect ourselves from XSS attacks, but what about CSRF attacks?

As mentioned before, cookies send on each request all the information stored in them, so let's assume the following scenario:

Our user is authenticated in our application and his cookie has been successfully generated.

A malicious actor sends an email with an offer to his email address using social engineering.

The user clicks on the button to claim the offer, this button sends a password change request or makes use of some other API entry of your application to obtain the user's protected information. At that point, the cookies in the browser will be sent automatically and it will be a valid request as it uses the cookies of the currently authenticated user, thus obtaining all his information. At that point, the malicious actor will have successfully performed a CSRF attack.

If you want to know more about this type of attacks I recommend the following video:

How can we protect ourselves from CSRF attacks?

The most common way to avoid this type of attack is by using a CSRF token. This token is randomly generated by the backend of the application, and in each request that is made, it will be sent and validated by the application itself. In this way the attacker will never know the value of this token, and will not be able to make a successful request outside our application.

But even after all these security measures if we are susceptible to an XSS attack, couldn't the attacker send a request directly from our application? The answer is, yes.

Normally react/next saves us the work of cleaning up user input, greatly reducing XSS attacks, however, there are ways in which these types of attacks can occur using these technologies. So I recommend you review this cheatsheet with some methods to avoid them.

3. Creating an authentication system Strapi and Next with next-auth

Now you may ask, do I have to implement each of these measures? The answer is no.

In this guide, we will use NextAuth, which implements all of these measures from the ground up, with some of them, such as JWT encryption (JWE), to secure your JWT token.

Continuing with our tutorial we will go to our app/ directory:

1
cd app/

Then install next-auth and axios to be able to make a request to the Strapi path /auth/local:

1
yarn add next-auth axios

Following the next-auth documentation, we must create an environment file in the main path of our project, in this case, app/ and another configuration file called ...nextauth.js in the "/app/pages/api/auth/" path of our next project. First, we will create the environment file with the name ".env.development" in our root directory of next, in this case "/app":

1
touch .env.development

In this file we will declare 3 constants, the base URL of our frontend ("NEXTAUTH_URL") which uses NexAuth as canonical URL in its code, then the following is the URL of the database we have created before which will be used for both Strapi and NextAuth.

The Postgresql URL of our database is given by: postgres://dbuser:password@localhost:5432/database

Finally, the Strapi URL in this case localhost:1337 :

1
2
3
NEXTAUTH_URL=http://localhost:3000
NEXT_PUBLIC_DATABASE_URL=postgres://strapiu:strongpassword@localhost:5432/strapi?synchronize=true
NEXT_PUBLIC_API_URL=http://localhost:1337 

Then we will create the "auth" directory:

1
2
3
mkdir pages/api/auth/
cd pages/api/auth/
touch [...nextauth].js

With the content of the file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
import NextAuth from "next-auth";
import Providers from "next-auth/providers";
import axios from 'axios'

const options = {
  providers: [
    Providers.Credentials({
      name: 'Credentials',
      credentials: {
        username: { label: "Email", type: "email", placeholder: "jsmith" },
        password: { label: "Password", type: "password" }
      },
      authorize: async (credentials) => {
        try {
          const user = await axios.post(`${process.env.NEXT_PUBLIC_API_URL}/auth/local`, {
            identifier: credentials.username,
            password: credentials.password,
          });
          if (user.data) {
            return user.data
          } else {
            return null
          }
        }  catch (error) {
          const errorMessage = error.response.data.message[0].messages[0].message
          throw new Error(errorMessage)
        }
      }
    }),
  ],
  database: process.env.NEXT_PUBLIC_DATABASE_URL,
  session: {
    jwt: true,
  },
  callbacks: {
    jwt: async (token, user) => {
      if (user){
        token.jwt = user.jwt;
        token.user = user.user;
      }
      return Promise.resolve(token);
    },
    session: async (session, token) => {
      session.jwt = token.jwt;
      session.user = token.user;
      return Promise.resolve(session);
    },
  },
  pages:{
    signIn: '/login',
    error: '/login'
  }
};
const Auth = (req, res) =>
  NextAuth(req, res, options);
export default Auth;

Now I will explain the most important parts of this file:

NextAuth has different types of providers, you can see all providers, but our tutorial focuses on a username and password model, so our provider will be Credentials.

1
import Providers from "next-auth/providers";

The credentials object in line 3 serves to identify the input of our form, and basically tells NextAuth which values belong to the user and which to the password.

1
2
3
4
5
6
Providers.Credentials({
      name: 'Credentials',
      credentials: {
        username: { label: "Email", type: "email", placeholder: "jsmith" },
        password: { label: "Password", type: "password" }
      }

Now NextAuth already knows how to get the credentials of your user but, how is it going to get the JWT token from Strapi to be able to make a request to the API? With the function authorize; This function is in charge of sending a request to the Strapi API (auth/local) through axios, and receive the JWT token and the object of our user.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
      authorize: async (credentials) => {
        try {
          const user = await axios.post(`${process.env.NEXT_PUBLIC_API_URL}/auth/local`, {
            identifier: credentials.username,
            password: credentials.password,
          });
          if (user.data) {
            return user.data
          } else {
            return null
          }
        } catch (error) {
          const errorMessage = error.response.data.message
          throw new Error(errorMessage + '&email=' + credentials.email)
        }
      }

NextAuth can work without a database, but this is only recommended if you do not need persistent accounts. (e.g. for billing, to contact customers, etc).

In this tutorial, we will use the database created before to be able to keep persistent the accounts of our users, therefore in line 31 we define the connection to the database with our environment variable, NEXT_PUBLIC_DATABASE_URL.

1
  database: process.env.NEXT_PUBLIC_DATABASE_URL,

NextAuth lets us choose between saving our data as a session or as a jwt token, for this tutorial we will use jwt for the advantages it offers.

1
2
3
  session: {
    jwt: true,
  },

After that, we have the callbacks. The jwt function receives the information from the user and send it to our callback function to be able to use that data in the cookie.

1
2
3
4
5
6
7
8
9
10
11
12
    jwt: async (token, user) => {
      if (user){
        token.jwt = user.jwt;
        token.user = user.user;
      }
      return Promise.resolve(token);
    },
    session: async (session, token) => {
      session.jwt = token.jwt;
      session.user = token.user;
      return Promise.resolve(session);
    },

And finally, we have pages. NextAuth has default pages for login and signup, but in this tutorial, we will make our own so we give the default path in this case: "/login".

1
2
3
4
  pages:{
    signIn: '/login',
    error: '/login'
  }

4. Creating auth views

Now we will create a simple interface in Next.js that will be composed of 3 main pages:

• Index
• Login
• Protected

4.1 Login page

As we decided to implement a personalized login, we will have to create a directory in the /pages directory of our "app" called login and inside it, an index.js file, the structure of the pages folder would be:

1
2
3
4
5
6
7
.
├── api
│   └── auth
├── _app.js
├── index.js
├── login
    └── index.js

In this file we will do two main things:

• Show authentication errors.
• Send our credentials to NextAuth with the corresponding CSRF Token.

To show errors we need a react hook: "useState" this hook will collect the authentication errors and the credentials of the user in our app.

To send our credentials, we will use an asynchronous request with the help of a NextAuth method called signIn() this method ensures that the user ends up on the page where he started after completing a login flow. This method will contain in its body the provider (in this case credentials), the user's identifier (email), and the password. In response we will get a promise with the following content: { error: string | undefined //The error message status: number //HTTP Status code ok: boolean // True if sign was successful url: string | null //the URL the user should have been redirected to. }

Note: It is important that the name of our inputs match the ones configured in the ...nextauth.js file.

2nd Note: All styles are available on the GitHub repo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import { signIn } from 'next-auth/client'
import { useRouter } from 'next/router'
import { useState } from 'react'
//import styles from '../../styles/Login.module.css'

export default function Login() {
    const [credentials, setCredentials] = useState({ username: '', password: '' })
    const [loginError, setError] = useState('')
    const router = useRouter()
    function handleUpdate(update) {
        setCredentials({ ...credentials, ...update })
    }
    return (
        <div className={styles.login}>
            <div className={styles.wrapper}>
                <div className={styles.var}>
                    <label htmlFor="username">Email</label>
                    <input name='username' type='email' onChange={(e) => handleUpdate({ username: e.target.value })} />
                </div>
                <div className={styles.var}>
                    <label htmlFor="password">Password</label>
                    <input name='password' type='password' onChange={(e) => handleUpdate({ password: e.target.value })} />
                </div>
                <span className={styles.error}>{loginError}</span>
                <button
                    onClick={async () => {
                        const response = await signIn('credentials', {
                            redirect: false,
                            ...credentials
                        })
                        if (response.error) {
                            setError(response.error)
                        } else if (response.ok) {
                            router.push("/")
                        }
                    }}
                >
                    Sign in
                </button>
            </div>
        </div>
    )
}

The resulting view would be:

When an error occurs, it will be displayed as follows:

4.2 Index page

For the main page, we will create a basic interface that contains:

• A Login button, if the user is not logged in and a welcome message as shown in the following picture if we try to open the protected page we will be redirected to the sign in page.

• A logout button, the user's token and a link to a protected view if the user is currently logged in.

To implement this view we need to know if our user is currently authenticated or not, for this we use the NextAuth hook useSession(), which will return the value of the session and if this hook is loading and another NextAuth function called signOut that will serve us so that the user can close the session.

This is a client-side hook and works best if we configure the NextAuth Session Provider called Provider for this we need to modify our _app.js file in the root of our Next.js project "/app" as follows:

1
2
3
4
5
6
7
8
9
import { Provider } from 'next-auth/client'

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

Now we can access these values easily:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
import Head from 'next/head'
import { useSession, signOut } from 'next-auth/client'
//import styles from '../styles/Home.module.css'

export default function Home() {
  const [session, loading] = useSession()
  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <nav className={styles.navbar}>
        <div className={styles.wrapper}>
          <div className={styles.left}>
            <p>Your logo</p>
          </div>
          <div className={styles.right}>
            {session && session.user ?
              <div className={styles.navlist}>
                <a href="/protected">Protected page</a>
                <a
                  href={`/api/auth/signout`}
                  className={styles.button}
                  onClick={(e) => {
                    e.preventDefault()
                    signOut()
                  }}
                >Logout
                        </a>
              </div>
              :
              <a className={styles.button} href="/login">Login</a>
            }
          </div>
        </div>
      </nav>
      <main className={styles.main}>
        <h1 className={styles.title}>
          {session ? <span>Welcome back <p>{session.user.username}</p> to </span> : 'Welcome to'}
          <p>Next.js! + Strapi + NextAuth app</p>
        </h1>
        <p className={styles.description}>
          {session ? <span>Your JWT is {session.jwt}</span> : <span>Get started by click in <a href="/login">login</a>{' '}</span>}
        </p>
      </main>
      <footer className={styles.footer}>
        <a
          href="https://ixtlan.dev"
          target="_blank"
          rel="noopener noreferrer"
        >
          Powered by Ixtlan.dev
        </a>
      </footer>
    </div>
  )
}

As we can see, once this token is working, we will be able to access it through the "session" object and the data returned from the user specifically through "session.user" or the token with "session.jwt".

Now you may be wondering, to know if my user is authenticated Do i need to call that function every time? Yes, but we will simplify this task by adding a new function called Auth to our _app.js file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
//import '../styles/globals.css'
import { useEffect } from 'react'
import { useRouter } from 'next/router'
import { useSession } from 'next-auth/client'
import { Provider } from 'next-auth/client'

function MyApp({ Component, pageProps }) {
  return (
    <Provider session={pageProps.session}>
        {Component.auth
          ? <Auth><Component {...pageProps} /></Auth>
          : <Component {...pageProps} />
        }
    </Provider>
  )
}

function Auth({ children }) {
  const [session, loading] = useSession()
  const isUser = !!session?.user
  const router = useRouter()
  useEffect(() => {
    if (loading) return // Do nothing while loading
    if (!isUser) router.push('/login')
    // If not authenticated, force log in
  }, [isUser, loading])
  if (isUser) {
    return children
  }
  // Session is being fetched, or no user.
  // If no user, useEffect() will redirect.
  return <div>Loading...</div>
}
export default MyApp

This function will validate if the user is currently logged in and can access the protected view, to test it, we will create a new page called protected.

4.3 Protected As we did with login we will create a folder called protected inside pages and we will add an index.js file in it, the structure of pages would look like this:

1
2
3
4
5
6
7
8
9
10
.
├── api
│   └── auth
│       └── [...nextauth].js
├── _app.js
├── index.js
├── login
│   └── index.js
└── protected
    └── index.js

This page is simple, we will only return a message that is protected for example:

1
2
3
4
export default function PortectedPage(){
    return <h1>Im protected page</h1>
} 
PortectedPage.auth = true

The most important part of the previous code would be to add the "auth" attribute at the end of our component, this part will help the function created in _app.js to validate if the user can access this page or not.

5. Creating a user in Strapi

In order to obtain our token we must first create a user in Strapi, for this we navigate to the path "localhost:1337" and fill out the following form to create an administrator account.

Then go to the user's section and click on "+Add New User".

Now we put some test data, in this case. I created a Test User with email "test@gmail.com" and a password, then we click on the "Save" button.

Now we can access your jwt token by sending your username and password to the Strapi "/auth/local" path.

6. Test the app

To test our simply log in with the previously registered user, but first, we must start the two test servers (Next and Strapi) with:

1
2
    /app yarn dev
    /api yarn strapi dev

and go to localhost:3000 and start to test the app.

Conclusion

In this tutorial, we learned how to authenticate an application in Next.js with Strapi and NextAuth using the Strapi user credentials. We also learned how to use NextAuth hooks to retrieve the user's jwt.

Note: The database used in this tutorial is optional.

The code for this tutorial is available on GitHub.