Intégration Auth0 SPA JS

Ajoutez l'authentification à n'importe quelle application monopage basée sur navigateur avec @auth0/auth0-spa-js — le SDK Auth0 bas niveau pour Vanilla JS, Svelte, SolidJS et tout SPA n'utilisant pas React, Angular ou Vue.

Instruction agent : Avant de fournir les instructions de configuration du SDK, récupérez la dernière version en lançant :

gh api repos/auth0/auth0-spa-js/releases/latest --jq '.tag_name'

Utilisez la version retournée dans toutes les lignes de dépendance au lieu de tout numéro de version codé en dur ci-dessous. Si la commande échoue, consultez https://github.com/auth0/auth0-spa-js/releases.

Prérequis

• Navigateur moderne avec support ES2017+
• npm ou yarn (ou utilisez CDN pour les apps sans bundler)
• Compte Auth0 avec une Single Page Application configurée
• Si Auth0 n'est pas encore configuré, consultez auth0-quickstart

Quand NE PAS l'utiliser

• React SPAs (hooks, Auth0Provider) : Utilisez auth0-react
• Angular SPAs (AuthModule, AuthGuard) : Utilisez auth0-angular
• Vue 3 SPAs (createAuth0, useAuth0) : Utilisez auth0-vue
• Next.js (sessions côté serveur, App Router) : Utilisez auth0-nextjs
• Nuxt (SSR côté serveur) : Utilisez auth0-nuxt
• Applications web Express côté serveur : Utilisez auth0-express
• React Native / Expo apps mobiles : Utilisez auth0-react-native

Workflow Démarrage Rapide

1. Installer le SDK

npm install @auth0/auth0-spa-js

Ou via CDN (sans bundler). Lancez ceci pour obtenir la dernière version, puis utilisez-la dans votre HTML :

VERSION=$(npm view @auth0/auth0-spa-js version)

<script src="https://cdn.auth0.com/js/auth0-spa-js/$VERSION/auth0-spa-js.production.js"></script>

2. Configurer Auth0

Pour la configuration automatisée avec Auth0 CLI, consultez Setup Guide pour les scripts complets.

Pour la configuration manuelle, créez .env (Vite) :

VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id

Dans le Auth0 Dashboard, configurez pour votre Single Page Application :

• Allowed Callback URLs : http://localhost:5173
• Allowed Logout URLs : http://localhost:5173
• Allowed Web Origins : http://localhost:5173

3. Initialiser le Client Auth0

import { createAuth0Client } from '@auth0/auth0-spa-js';

const auth0 = await createAuth0Client({
  domain: import.meta.env.VITE_AUTH0_DOMAIN,
  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
  authorizationParams: {
    redirect_uri: window.location.origin
  }
});

// Traiter le rappel de redirection après la connexion
const query = new URLSearchParams(window.location.search);
if ((query.has('code') || query.has('error')) && query.has('state')) {
  await auth0.handleRedirectCallback();
  window.history.replaceState({}, document.title, window.location.pathname);
}

4. Ajouter Connexion / Déconnexion

Instruction agent : Avant d'ajouter de nouveaux éléments d'interface, recherchez le projet pour trouver les gestionnaires de clic existants pour les boutons login, logout, sign-in ou sign-out. Si des gestionnaires existants sont trouvés, connectez le code Auth0 à ceux-ci sans modifier l'interface existante. Créez des boutons uniquement si aucun gestionnaire existant n'est trouvé.

// Connexion
document.getElementById('login-btn').addEventListener('click', async () => {
  await auth0.loginWithRedirect();
});

// Déconnexion
document.getElementById('logout-btn').addEventListener('click', () => {
  auth0.logout({
    logoutParams: { returnTo: window.location.origin }
  });
});

// Mettre à jour l'interface en fonction de l'état d'authentification
const isAuthenticated = await auth0.isAuthenticated();
if (isAuthenticated) {
  const user = await auth0.getUser();
  console.log(user.name, user.email);
}

5. Obtenir les Tokens d'Accès pour les Appels API

const accessToken = await auth0.getTokenSilently();

const response = await fetch('https://your-api.example.com/data', {
  headers: { Authorization: `Bearer ${accessToken}` }
});

6. Construire et Vérifier

Instruction agent : Après avoir terminé l'intégration, compilez le projet pour vérifier qu'il se compile correctement :

npm run build

Si la compilation échoue, analysez la sortie d'erreur et corrigez les problèmes. Les erreurs de compilation courantes lors de l'intégration incluent :

• Module not found : npm install @auth0/auth0-spa-js manquant — lancez la commande d'installation
• Cannot find name 'import.meta' : Cible TypeScript trop basse — définissez "target": "ES2020" ou plus dans tsconfig.json
• createAuth0Client is not a function : Chemin d'import incorrect ou utilisation CDN sans étape de bundling
• Env vars undefined at runtime : Vite nécessite le préfixe VITE_ ; webpack/CRA nécessite le préfixe REACT_APP_

Relancez la compilation après chaque correction. Suivez le nombre d'itérations de correction de compilation.

Failcheck : Si la compilation échoue toujours après 5–6 tentatives de correction, arrêtez et posez la question à l'utilisateur en utilisant AskUserQuestion : "La compilation échoue toujours après plusieurs tentatives de correction. Comment souhaitez-vous procéder ?"

• Laisser la skill continuer à corriger de manière itérative — continuez la boucle de correction de compilation pour 5–6 autres tentatives
• Le corriger manuellement — montrez les erreurs restantes et laissez l'utilisateur les résoudre
• Ignorer la vérification de compilation — continuez sans compilation réussie

Documentation Détaillée

• Setup Guide — Scripts de configuration automatisée (Bash/PowerShell), commandes Auth0 CLI, configuration .env, configuration des URL de rappel
• Integration Patterns — Gestion des tokens, appels API, actualisation des tokens, organisations, MFA, DPoP, gestion des erreurs, modèles avancés
• Testing & Reference — Options de configuration, référence des claims, checklist de test, problèmes courants, considérations de sécurité

Erreurs Courantes

Skills Associées

• auth0-quickstart — Configurer un compte et une application Auth0
• auth0-react — Auth0 pour React SPAs avec hooks
• auth0-angular — Auth0 pour Angular SPAs
• auth0-vue — Auth0 pour Vue 3 SPAs
• auth0-mfa — Ajouter l'Authentification Multi-Facteur

Référence Rapide

Méthodes Principales

Cas d'Usage Courants

• Connexion/Déconnexion → Voir l'étape 4 ci-dessus
• Protéger du contenu → Integration Guide
• Appels API avec tokens → Integration Guide
• Actualisation des tokens → Integration Guide
• Organisations → Integration Guide
• Gestion MFA → Integration Guide
• Gestion des erreurs → Integration Guide

Références

• Auth0 SPA JS SDK Documentation
• Auth0 Vanilla JS Quickstart
• SDK GitHub Repository
• EXAMPLES.md — Advanced patterns
• API Documentation