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 |
|
|
tutorial |
quickstart |
<%= include('../_includes/_getting_started', { library: 'Next.js', callback: 'http://localhost:3000/api/auth/callback' }) %>
<%= include('../../../_includes/_logout_url', { returnTo: 'http://localhost:3000' }) %>
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.
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 usingopenssl 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 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();
::: 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).*)",
],
};
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 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. :::
<%= include('../_includes/_auth_note_dev_keys') %>
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.
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 thatisLoading
isfalse
. - 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.
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.
:::
We put together a few examples of how to use nextjs-auth0 in more advanced use cases: