Auth0 Nuxt SDK

Overview

Server-side session authentication for Nuxt 3/4. NOT the same as @auth0/auth0-vue (client-side SPA).

Core principle: Uses server-side encrypted cookie sessions, not client-side tokens.

When to Use

Use this when:

• Building Nuxt 3/4 applications with server-side rendering (Node.js 20 LTS+)

• Need secure session management with encrypted cookies

• Protecting server routes and API endpoints

• Accessing Auth0 Management API or custom APIs

Don't use this when:

• Using Nuxt 2 (not supported - use different Auth0 SDK)

• Building pure client-side SPA without server (use @auth0/auth0-vue instead)

• Using non-Auth0 authentication provider

• Static site generation only (SSG) without server runtime

Critical Mistakes to Avoid

Mistake Solution

Installing @auth0/auth0-vue or @auth0/auth0-spa-js

Use @auth0/auth0-nuxt

Auth0 app type "Single Page Application" Use "Regular Web Application"

Env vars: VITE_AUTH0_* or VUE_APP_AUTH0_*

Use NUXT_AUTH0_* prefix

Using useUser() for security checks Use useAuth0(event).getSession() server-side

Missing callback URLs in Auth0 Dashboard Add http://localhost:3000/auth/callback

Weak/missing session secret Generate: openssl rand -hex 64

Quick Setup

1. Install

npm install @auth0/auth0-nuxt

2. Generate secret

openssl rand -hex 64

3. .env

NUXT_AUTH0_DOMAIN=your-tenant.auth0.com NUXT_AUTH0_CLIENT_ID=your-client-id NUXT_AUTH0_CLIENT_SECRET=your-client-secret NUXT_AUTH0_SESSION_SECRET=<from-openssl> NUXT_AUTH0_APP_BASE_URL=http://localhost:3000 NUXT_AUTH0_AUDIENCE=https://your-api # optional

// 4. nuxt.config.ts export default defineNuxtConfig({ modules: ['@auth0/auth0-nuxt'], runtimeConfig: { auth0: { domain: '', clientId: '', clientSecret: '', sessionSecret: '', appBaseUrl: 'http://localhost:3000', audience: '', // optional }, }, })

Built-in Routes

The SDK automatically mounts these routes:

Route Method Purpose

/auth/login

GET Initiates login flow. Supports ?returnTo=/path parameter

/auth/callback

GET Handles Auth0 callback after login

/auth/logout

GET Logs user out and redirects to Auth0 logout

/auth/backchannel-logout

POST Receives logout tokens for back-channel logout

Customize: Pass routes: { login, callback, logout, backchannelLogout } or mountRoutes: false to module config.

Composables

Composable Context Usage

useAuth0(event)

Server-side Access getUser() , getSession() , getAccessToken() , logout()

useUser()

Client-side Display user data only. Never use for security checks

// Server example const auth0 = useAuth0(event); const session = await auth0.getSession();

<script setup> const user = useUser(); </script>

<template> <div v-if="user">Welcome {{ user.name }}</div> <template>

Protecting Routes

Three layers: Route middleware (client), server middleware (SSR), API guards.

// middleware/auth.ts - Client navigation export default defineNuxtRouteMiddleware((to) => { if (!useUser().value) return navigateTo(/auth/login?returnTo=${encodeURIComponent(to.path)}); });

// server/middleware/auth.server.ts - SSR protection export default defineEventHandler(async (event) => { const url = getRequestURL(event); const auth0Client = useAuth0(event); const session = await auth0Client.getSession(); if (!session) { return sendRedirect(event, /auth/login?returnTo=${encodeURIComponent(url.pathname)}); } });

// server/api/protected.ts - API endpoint protection export default defineEventHandler(async (event) => { const auth0Client = useAuth0(event); const session = await auth0Client.getSession();

if (!session) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); }

return { data: 'protected data' }; });

For role-based, permission-based, and advanced patterns: route-protection.md

Session Management

Stateless (Default)

Uses encrypted, chunked cookies. No configuration needed.

Stateful (Redis, MongoDB, etc.)

For larger sessions or distributed systems:

// nuxt.config.ts modules: [ ['@auth0/auth0-nuxt', { sessionStoreFactoryPath: '~/server/utils/session-store-factory.ts' }] ]

For complete session store implementations, see: session-stores.md

API Integration

Configure audience for API access tokens:

// nuxt.config.ts runtimeConfig: { auth0: { audience: 'https://your-api-identifier', } }

Retrieve tokens server-side:

// server/api/call-api.ts export default defineEventHandler(async (event) => { const auth0Client = useAuth0(event); const { accessToken } = await auth0Client.getAccessToken();

return await $fetch('https://api.example.com/data', { headers: { Authorization: Bearer ${accessToken} } }); });

Security Checklist

• ✅ Server-side validation only (never trust useUser() )

• ✅ HTTPS in production

• ✅ Strong session secret (openssl rand -hex 64 )

• ✅ Never commit .env files

• ✅ Stateful sessions for PII/large data

Troubleshooting

Error Solution

"Module not found" Install @auth0/auth0-nuxt , not @auth0/auth0-vue

"Missing domain/clientId/clientSecret" Check NUXT_AUTH0_ prefix, .env location, runtimeConfig

"Redirect URI mismatch" Match Auth0 Dashboard callback to appBaseUrl + /auth/callback

"useAuth0 is not defined" Use only in server context with H3 event object

Cookies too large Use stateful sessions or reduce scopes

Additional Resources

Guides: Route Protection Patterns • Custom Session Stores • Common Examples

Links: Auth0-Nuxt GitHub • Auth0 Docs • Nuxt Modules