SDK Nuxt Auth0

Vue d'ensemble

Authentification par session côté serveur pour Nuxt 3/4. N'est PAS la même chose que @auth0/auth0-vue (SPA côté client).

Principe fondamental : Utilise les sessions de cookie chiffré côté serveur, pas les tokens côté client.

Quand l'utiliser

Utilisez ceci quand :

• Construire des applications Nuxt 3/4 avec rendu côté serveur (Node.js 20 LTS+)
• Besoin de gestion sécurisée des sessions avec cookies chiffrés
• Protection des routes serveur et des endpoints API
• Accès à l'API Auth0 Management ou à des API personnalisées

Ne l'utilisez pas quand :

• Utilisation de Nuxt 2 (non supporté - utilisez un SDK Auth0 différent)
• Construction d'une SPA purement côté client sans serveur (utilisez @auth0/auth0-vue à la place)
• Utilisation d'un fournisseur d'authentification autre qu'Auth0
• Génération de site statique uniquement (SSG) sans runtime serveur

Erreurs critiques à éviter

Configuration rapide

# 1. Installer
npm install @auth0/auth0-nuxt

# 2. Générer 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
    },
  },
})

Routes intégrées

Le SDK monte automatiquement ces routes :

Personnaliser : Passez routes: { login, callback, logout, backchannelLogout } ou mountRoutes: false à la config du module.

Composables

// Exemple serveur
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>

Protection des routes

Trois niveaux : Route middleware (client), server middleware (SSR), API guards.

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

// server/middleware/auth.server.ts - Protection SSR
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 - Protection endpoint API
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' };
});

Pour les patterns basés sur les rôles, les permissions, et les patterns avancés : route-protection.md

Gestion des sessions

Stateless (Défaut)

Utilise des cookies chiffrés et fragmentés. Aucune configuration nécessaire.

Stateful (Redis, MongoDB, etc.)

Pour les sessions plus volumineuses ou les systèmes distribués :

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

Pour les implémentations complètes de session store, voir : session-stores.md

Intégration API

Configurez l'audience pour les tokens d'accès API :

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

Récupérez les tokens côté serveur :

// 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}`
    }
  });
});

Checklist de sécurité

• ✅ Validation côté serveur uniquement (ne faites jamais confiance à useUser())
• ✅ HTTPS en production
• ✅ Secret de session fort (openssl rand -hex 64)
• ✅ Ne validez jamais les fichiers .env
• ✅ Sessions stateful pour les PII/données volumineuses

Dépannage

Ressources supplémentaires

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

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