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 or | Use |
| Auth0 app type "Single Page Application" | Use "Regular Web Application" |
| Env vars: or | Use prefix |
| Using for security checks | Use useAuth0(event).getSession()
|
| Missing callback URLs in Auth0 Dashboard | Add http://localhost:3000/auth/callback
|
| Weak/missing session secret | Generate: |
Quick Setup
bash
# 1. Install
npm install @auth0/auth0-nuxt
# 2. Generate secret
openssl rand -hex 64
bash
# 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
typescript
// 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 |
|---|
| GET | Initiates login flow. Supports parameter |
| GET | Handles Auth0 callback after login |
| GET | Logs user out and redirects to Auth0 logout |
| POST | Receives logout tokens for back-channel logout |
Customize: Pass
routes: { login, callback, logout, backchannelLogout }
or
to module config.
Composables
| Composable | Context | Usage |
|---|
| Server-side | Access , , , |
| Client-side | Display user data only. Never use for security checks |
typescript
// Server example
const auth0 = useAuth0(event);
const session = await auth0.getSession();
vue
<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.
typescript
// middleware/auth.ts - Client navigation
export default defineNuxtRouteMiddleware((to) => {
if (!useUser().value) return navigateTo(`/auth/login?returnTo=${to.path}`);
});
typescript
// 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=${url.pathname}`);
}
});
typescript
// 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:
typescript
// 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:
typescript
// nuxt.config.ts
runtimeConfig: {
auth0: {
audience: 'https://your-api-identifier',
}
}
Retrieve tokens server-side:
typescript
// 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 )
- ✅ HTTPS in production
- ✅ Strong session secret ()
- ✅ Never commit files
- ✅ Stateful sessions for PII/large data
Troubleshooting
| Error | Solution |
|---|
| "Module not found" | Install , not |
| "Missing domain/clientId/clientSecret" | Check prefix, location, |
| "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