Skip to content

Files

Latest commit

9dfc088 · Mar 7, 2025

History

History
242 lines (179 loc) · 9.54 KB

01-login.md

File metadata and controls

242 lines (179 loc) · 9.54 KB
title description budicon topics github contentType useCase
Login
This guide demonstrates how to integrate Auth0 with any new or existing Next.js application using the Auth0 Next.js SDK.
448
quickstarts
nextjs
next.js
login
path
Sample-01
tutorial
quickstart

<%= include('../_includes/_getting_started', { library: 'Next.js', callback: 'http://localhost:3000/api/auth/callback' }) %>

<%= include('../../../_includes/_logout_url', { returnTo: 'http://localhost:3000' }) %>

Install the Auth0 Next.js SDK

Run the following command within your project directory to install the Auth0 Next.js SDK:

npm i @auth0/nextjs-auth0

The SDK exposes methods and variables that help you integrate Auth0 with your Next.js application using Route Handlers on the backend and React Context with React Hooks on the frontend.

Configure the SDK

In the root directory of your project, add the file .env.local with the following environment variables:

AUTH0_SECRET='use [openssl rand -hex 32] to generate a 32 bytes value'
AUTH0_BASE_URL='http://localhost:3000'
AUTH0_ISSUER_BASE_URL='https://${account.namespace}'
AUTH0_CLIENT_ID='${account.clientId}'
AUTH0_CLIENT_SECRET='${account.clientSecret}'
  • AUTH0_SECRET: A long secret value used to encrypt the session cookie. You can generate a suitable string using openssl rand -hex 32 on the command line.
  • AUTH0_BASE_URL: The base URL of your application.
  • AUTH0_ISSUER_BASE_URL: The URL of your Auth0 tenant domain. If you are using a Custom Domain with Auth0, set this to the value of your Custom Domain instead of the value reflected in the "Settings" tab.
  • AUTH0_CLIENT_ID: Your Auth0 application's Client ID.
  • AUTH0_CLIENT_SECRET: Your Auth0 application's Client Secret.

The SDK will read these values from the Node.js process environment and automatically configure itself.

Create the Auth0 SDK Client

Create a file at src/lib/auth0.ts. This file provides methods for handling authentication, sessions and user data.

Then, import the Auth0Client class from the SDK to create an instance and export it as auth0. This instance is used in your app to interact with Auth0.

// src/lib/auth0.ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client();

Add the Authentication Middleware

::: note The Next.js Middleware allows you to run code before a request is completed. :::

Create a file at src/middleware.ts. This file is used to enforce authentication on specific routes.

The middleware function intercepts incoming requests and applies Auth0's authentication logic. The matcher configuration ensures that the middleware runs on all routes except for static files and metadata.

// src/middleware.ts
import type { NextRequest } from "next/server";
import { auth0 } from "./lib/auth0";

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico, sitemap.xml, robots.txt (metadata files)
     */
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

Add the Landing Page Content

The Landing page src/app/page.tsx is where users interact with your app. It displays different content based on whether the users is logged in or not.

Edit the file src/app/page.tsx to add the auth0.getSession() method to determine if the user is logged in by retrieving the user session.

If there is no user session, the method returns null and the app displays the Sign up or Log in buttons. If a user sessions exists, the app displays a welcome message with the user's name and a Log out button.

// src/app/page.tsx
import { auth0 } from "@/lib/auth0";
import './globals.css';

export default async function Home() {
  // Fetch the user session
  const session = await auth0.getSession();

  // If no session, show sign-up and login buttons
  if (!session) {
    return (
      <main>
        <a href="/auth/login?screen_hint=signup">
          <button>Sign up</button>
        </a>
        <a href="/auth/login">
          <button>Log in</button>
        </a>
      </main>
    );
  }

  // If session exists, show a welcome message and logout button
  return (
    <main>
      <h1>Welcome, {session.user.name}!</h1>
      <p>
        <a href="/auth/logout">
          <button>Log out</button>
        </a>
      </p>
    </main>
  );
}

::: note The Logout functionality is already included in the file src/app/page.tsx. When the user selects the Log out button, they are redirected to the Auth0 logout endpoint, which clears their session and redirects back to your app. :::

Run the Sample

Run this command to start your Next.js development server:

npm run dev

Visit the url http://localhost:3000 in your browser.

You will see:

A Sign up and Log in button if the user is not authenticated. A welcome message and a Log out button if the user is authenticated.

:::panel Checkpoint

Run your application.

Verify that your Next.js application redirects you to the Auth0 Universal Login page and that you can now log in or sign up using a username and password or a social provider.

Once that's complete, verify that Auth0 redirects back to your application. :::

Auth0 Universal Login

<%= include('../_includes/_auth_note_dev_keys') %>

Show User Profile Information

The Auth0 Next.js SDK helps you retrieve the profile information associated with the logged-in user, such as their name or profile picture, to personalize the user interface.

From a Client Component

The profile information is available through the user property exposed by the useUser() hook. Take this Client Component as an example of how to use it:

'use client';

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

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

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>{error.message}</div>;

  return (
    user && (
      <div>
        <img src={user.picture} alt={user.name} />
        <h2>{user.name}</h2>
        <p>{user.email}</p>
      </div>
    )
  );
}

The user property contains sensitive information and artifacts related to the user's identity. As such, its availability depends on the user's authentication status. To prevent any render errors:

  • Ensure that the SDK has completed loading before accessing the user property by checking that isLoading is false.
  • Ensure that the SDK has loaded successfully by checking that no error was produced.
  • Check the user property to ensure that Auth0 has authenticated the user before React renders any component that consumes it.

From a Server Component

The profile information is available through the user property exposed by the getSession function. Take this Server Component as an example of how to use it:

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

export default async function ProfileServer() {
  const { user } = await getSession();

  return (
      user && (
          <div>
            <img src={user.picture} alt={user.name} />
            <h2>{user.name}</h2>
            <p>{user.email}</p>
          </div>
      )
  );
}

:::panel Checkpoint Verify that you can display the user.name or any other user property within a component correctly after you have logged in. :::

What's next?

We put together a few examples of how to use nextjs-auth0 in more advanced use cases: