Getting Started with Auth0 and Next.js: A Step-by-Step Guide

In today's digital era, securing your web applications is paramount. Authentication is a critical component of any app, and it's essential to manage it well. For developers using Next.js, integrating an authentication service can be a bit daunting. That's where Auth0 comes in a powerful authentication and authorization platform that simplifies this process. In this article, we'll walk you through the steps to get started with Auth0 and Next.js, securing your app effectively and efficiently.

What is Auth0?

Auth0 is an authentication and authorization service that offers a lot of features out of the box, such as social login integrations, enterprise identity providers, passwordless login, and much more. It allows developers to implement complex authentication features with minimal effort.

What is Next.js?

Next.js is a React framework that enables functionality such as server-side rendering and generating static websites for React-based web applications. It's a powerful tool for creating high-performance applications with an emphasis on a great developer experience.

Prerequisites

Basic knowledge of JavaScript and React
Node.js installed on your system
A code editor (VSCode, Sublime Text, etc.)
An Auth0 account (you can sign up for free at Auth0's website)

Step 1: Set Up Your Auth0 Application

First, you need to set up an application in Auth0:

Log in to your Auth0 Dashboard.
Click on "Applications" in the sidebar and then "Create Application".
Give your application a name, choose "Single Page Web Applications", and click "Create".
In the "Settings" tab, add http://localhost:3000 to the "Allowed Callback URLs", "Allowed Logout URLs", and "Allowed Web Origins".
Scroll down and click "Save Changes".

Make note of the Domain, Client ID, and Client Secret from the settings page, as you will need these for your Next.js application.

Step 2: Bootstrap Your Next.js Application

Create a new Next.js app by running the following command in your terminal:

npx create-next-app my-auth0-app
cd my-auth0-app

This will create a new directory called my-auth0-app with a starter Next.js application.

Step 3: Install Auth0 SDK for Next.js

Auth0 provides an SDK that makes integration with Next.js a breeze. Install it using npm or yarn:

npm install @auth0/nextjs-auth0

yarn add @auth0/nextjs-auth0

Step 4: Set Up Environment Variables

Create a .env.local file in the root of your Next.js project and add the following environment variables with the values from your Auth0 application settings:

AUTH0_SECRET='a_long_unique_value_like_a_guid'
AUTH0_BASE_URL='http://localhost:3000'
AUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN'
AUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'
AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'

Replace YOUR_AUTH0_DOMAIN, YOUR_AUTH0_CLIENT_ID, and YOUR_AUTH0_CLIENT_SECRET with the actual values from your Auth0 application.

Step 5: Configure Auth0 SDK

Create a file called auth0.js inside a new folder utils in your project and initialize the Auth0 SDK like so:

import { initAuth0 } from '@auth0/nextjs-auth0';

export default initAuth0({
  secret: process.env.AUTH0_SECRET,
  issuerBaseURL: process.env.AUTH0_ISSUER_BASE_URL,
  baseURL: process.env.AUTH0_BASE_URL,
  clientID: process.env.AUTH0_CLIENT_ID,
  clientSecret: process.env.AUTH0_CLIENT_SECRET,
  routes: {
    callback: '/api/auth/callback',
    postLogoutRedirect: '/'
  },
  session: {
    // The secret used to encrypt the cookie
    cookieSecret: process.env.AUTH0_SECRET,
    cookieLifetime: 60 * 60 * 8,
    storeIdToken: false,
    storeAccessToken: false,
    storeRefreshToken: false
  }
});

This configures the SDK with your Auth0 application settings.

Step 6: Create API Routes for Authentication

In Next.js, API routes provide a solution to build your API with JavaScript and Node.js. Create the following two files in the pages/api/auth directory:

[...auth0].js: This will handle login, logout, and callback.

import auth0 from '../../../utils/auth0';

export default async function auth(req, res) {
  try {
    await auth0.handleAuth(req, res);
  } catch (error) {
    console.error(error);
    res.status(error.status || 500).end(error.message);
  }
}

me.js: This will show the user profile information.

import auth0 from '../../../utils/auth0';

export default async function me(req, res) {
  try {
    await auth0.handleProfile(req, res);
  } catch (error) {
    console.error(error);
    res.status(error.status || 500).end(error.message);
  }
}

Step 7: Add Authentication to Your Pages

Now, you can use the Auth0 SDK in your React components to add authentication. Here's an example of how to implement a login button:

import React from 'react';
import { useUser } from '@auth0/nextjs-auth0';

export default function Home() {
  const { user, error, isLoading } = useUser();

  return (
    <div>
      {isLoading && <p>Loading...</p>}
      {error && <p>{error.message}</p>}
      {user ? (
        <div>
          <h1>Welcome, {user.name}!</h1>
          <p><img src={user.picture} alt={user.name} /></p>
          <p><a href="/api/auth/logout">Logout</a></p>
        </div>
      ) : (
        <p><a href="/api/auth/login">Login</a></p>
      )}
    </div>
  );
}

This code checks if the user is authenticated and displays their name and a logout button. If the user is not authenticated, it shows a login button.

Step 8: Protecting Routes

To protect a route and make it accessible only to authenticated users, you can use the withPageAuthRequired higher-order component from the SDK:

import { withPageAuthRequired } from '@auth0/nextjs-auth0';

export const getServerSideProps = withPageAuthRequired();

export default function ProtectedPage() {
  return <div>This is a protected page</div>;
}

Step 9: Deploying Your App

When you're ready to go live, don't forget to add the actual deployment URL to the "Allowed Callback URLs", "Allowed Logout URLs", and "Allowed Web Origins" in your Auth0 application settings.

Deploy your Next.js app to Vercel, Netlify, or any other hosting provider that supports Node.js.

Conclusion

Congratulations! You've successfully integrated Auth0 with Next.js, providing robust authentication for your application. Auth0's platform makes managing users and their authentication states a breeze, allowing you to focus on developing the core features of your app.

Remember to secure your user data, use environment variables to protect your secrets, and always keep your dependencies up to date. Security is an ever-evolving field, and staying informed is key.

For more advanced topics, such as role-based access control and multi-factor authentication with Auth0 and Next.js, stay tuned to sebiweise.dev. Happy coding!