Auth0 Nextjs

Use when adding authentication to Next.js applications (login, logout, protected pages, middleware, server components) - supports App Router and Pages Router...

Security Scan

The skill's requirements and instructions are coherent with its stated purpose (adding Auth0 auth to Next.js apps); it is instruction-only and asks the user to create/manage Auth0 secrets in their project, with sensible safeguards, but includes an optional install snippet (curl | sh) and file-write steps you should review before running.

Purpose & Capability

The name/description (Auth0 + Next.js) matches the content: the SKILL.md and references show step-by-step setup, middleware, API examples and SDK usage. All env variables and files mentioned (AUTH0_* and .env.local, lib/auth0.ts, middleware) are expected for this purpose.

Instruction Scope

The instructions will read project layout, create files (lib/auth0.ts, middleware/proxy), and append or create .env.local containing sensitive secrets. The SKILL.md explicitly warns not to read existing env files and requires explicit user confirmation before writing — a good safeguard. Still, the agent instructions include file I/O and interactive CLI use, so the user should confirm before allowing automated execution.

Install Mechanism

This is an instruction-only skill (no code files). The provided automated setup script may install the Auth0 CLI; on non-macOS it suggests piping an install script from raw.githubusercontent.com to sh. Using curl | sh is common for CLIs but is higher risk than package-manager installs — review the install script before executing it.

Credentials

Environment variables referenced (AUTH0_SECRET, AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, APP_BASE_URL, AUTH0_AUDIENCE) are appropriate and necessary for Auth0 integration. The skill does not itself request credentials in metadata; it instructs the user to create/append them to project env files, and warns about not exposing secrets.

Persistence & Privilege

The skill is not always-enabled and does not request system-wide privileges or modify other skills. It is agent-invokable by default, which is normal for skills. It does write to project files when the user consents, which is expected for a setup helper.

Assessment

This appears to be a legitimate Auth0 Next.js setup guide. Before you run any automated steps: (1) review the provided install script (the curl | sh installer) instead of executing it blindly; (2) back up existing .env/.env.local and confirm any append operations (the guide itself says to ask the user); (3) ensure .env.local is in .gitignore so secrets aren't committed; (4) prefer running CLI steps yourself interactively rather than giving the agent permission to run them autonomously; and (5) never paste secrets into chat — the skill already warns agents not to read env files without explicit user permission.

Auth0 Next.js Integration

Add authentication to Next.js applications using @auth0/nextjs-auth0. Supports both App Router and Pages Router.

---

Prerequisites

• Next.js 13+ application (App Router or Pages Router)
• Auth0 account and application configured
• If you don't have Auth0 set up yet, use the auth0-quickstart skill first

When NOT to Use

• Client-side only React apps - Use auth0-react for Vite/CRA SPAs
• React Native mobile apps - Use auth0-react-native for iOS/Android
• Non-Next.js frameworks - Use framework-specific SDKs (Express, Vue, Angular, etc.)
• Stateless APIs only - Use JWT validation middleware if you don't need session management

---

Quick Start Workflow

1. Install SDK

npm install @auth0/nextjs-auth0

2. Configure Environment

For automated setup with Auth0 CLI, see Setup Guide for complete scripts.

For manual setup:

Create .env.local:

AUTH0_SECRET=<generate-a-32-character-secret>
APP_BASE_URL=http://localhost:3000
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

Generate secret: openssl rand -hex 32

Important: Add .env.local to .gitignore

3. Create Auth0 Client and Middleware

Detect project structure first: Check whether the project uses a src/ directory (i.e. src/app/ or src/pages/ exists). This determines where to place files:

• With src/: src/lib/auth0.ts, src/middleware.ts (or src/proxy.ts for Next.js 16)
• Without src/: lib/auth0.ts, middleware.ts (or proxy.ts for Next.js 16)

Create lib/auth0.ts (or src/lib/auth0.ts if using the src/ convention):

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  secret: process.env.AUTH0_SECRET!,
  appBaseUrl: process.env.APP_BASE_URL!,
});

Middleware Configuration (Next.js 15 vs 16):

Next.js 15 - Create middleware.ts (at project root, or src/middleware.ts if using src/):

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

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

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Next.js 16 - You have two options:

Option 1: Use middleware.ts (same as Next.js 15, same src/ placement rules):

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

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

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Option 2: Use proxy.ts (at project root, or src/proxy.ts if using src/):

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

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

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

This automatically creates endpoints:

• /auth/login - Login
• /auth/logout - Logout
• /auth/callback - OAuth callback
• /auth/profile - User profile

4. Add User Context (Optional)

Note: In v4, wrapping with <Auth0Provider> is optional. Only needed if you want to pass an initial user during server rendering to useUser().

App Router - Optionally wrap app in app/layout.tsx:

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

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const session = await auth0.getSession();

  return (
    <html>
      <body>
        <Auth0Provider user={session?.user}>{children}</Auth0Provider>
      </body>
    </html>
  );
}

Pages Router - Optionally wrap app in pages/_app.tsx:

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Auth0Provider user={pageProps.user}>
      <Component {...pageProps} />
    </Auth0Provider>
  );
}

5. Add Authentication UI

Client Component (works in both routers):

'use client'; // Only needed for App Router

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

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

  if (isLoading) return <div>Loading...</div>;

  if (user) {
    return (
      <div>
        <img src={user.picture} alt={user.name} />
        <h2>Welcome, {user.name}!</h2>
        <a href="/auth/logout">Logout</a>
      </div>
    );
  }

  return <a href="/auth/login">Login</a>;
}

6. Test Authentication

Start your dev server:

npm run dev

Visit http://localhost:3000 and test the login flow.

---

Detailed Documentation

• Setup Guide - Automated setup scripts, environment configuration, Auth0 CLI usage
• Integration Guide - Server-side auth, protected routes, API routes, middleware
• API Reference - Complete SDK API, hooks, helpers, session management

---

Common Mistakes

Mistake	Fix
Using v3 environment variables	v4 uses APP_BASE_URL and AUTH0_DOMAIN (not AUTH0_BASE_URL or AUTH0_ISSUER_BASE_URL)
Forgot to add callback URL in Auth0 Dashboard	Add /auth/callback to Allowed Callback URLs (e.g., http://localhost:3000/auth/callback)
Missing middleware configuration	v4 requires middleware to mount auth routes - create middleware.ts (Next.js 15+16) or proxy.ts (Next.js 16 only) with auth0.middleware()
Wrong route paths	v4 uses /auth/login not /api/auth/login - routes drop the /api prefix
Missing or weak AUTH0_SECRET	Generate secure secret with openssl rand -hex 32 and store in .env.local
Using .env instead of .env.local	Next.js requires .env.local for local secrets, and .env.local should be in .gitignore
App created as SPA type in Auth0	Must be Regular Web Application type for Next.js
Using removed v3 helpers	v4 removed withPageAuthRequired and withApiAuthRequired - use getSession() instead
Using useUser in Server Component	useUser is client-only, use auth0.getSession() for Server Components
AUTH0_DOMAIN includes https://	v4 AUTH0_DOMAIN should be just the domain (e.g., example.auth0.com), no scheme

---

Related Skills

• auth0-quickstart - Basic Auth0 setup
• auth0-migration - Migrate from another auth provider
• auth0-mfa - Add Multi-Factor Authentication

---

Quick Reference

V4 Setup:

• Detect src/ convention: check if src/app/ or src/pages/ exists — place all files inside src/ if so
• Create lib/auth0.ts (or src/lib/auth0.ts) with Auth0Client instance
• Create middleware configuration (required):
  • Next.js 15: middleware.ts (or src/middleware.ts) with middleware() function
  • Next.js 16: middleware.ts with middleware() OR proxy.ts with proxy() function (same src/ rules)
• Optional: Wrap with <Auth0Provider> for SSR user

Client-Side Hooks:

• useUser() - Get user in client components
• user - User profile object
• isLoading - Loading state

Server-Side Methods:

• auth0.getSession() - Get session in Server Components/API routes/middleware
• auth0.getAccessToken() - Get access token for calling APIs

Common Use Cases:

• Login/Logout links → Use /auth/login and /auth/logout paths (see Step 5)
• Protected pages (App Router) → Integration Guide
• Protected pages (Pages Router) → Integration Guide
• API routes with auth → Integration Guide
• Middleware protection → Integration Guide

---

References

• Auth0 Next.js SDK Documentation
• Auth0 Next.js Quickstart
• SDK GitHub Repository