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
npm install @auth0/auth0-nuxt
openssl rand -hex 64
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
export default defineNuxtConfig({
modules: ['@auth0/auth0-nuxt'],
runtimeConfig: {
auth0: {
domain: '',
clientId: '',
clientSecret: '',
sessionSecret: '',
appBaseUrl: 'http://localhost:3000',
audience: '',
},
},
})
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 |
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.
export default defineNuxtRouteMiddleware((to) => {
if (!useUser().value) return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
});
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)}`);
}
});
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:
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:
runtimeConfig: {
auth0: {
audience: 'https://your-api-identifier',
}
}
Retrieve tokens server-side:
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
