Intégration Auth0 React

Ajoutez l'authentification à vos applications React single-page avec @auth0/auth0-react.

Prérequis

Application React 16.11+ (Vite ou Create React App) - supporte React 16, 17, 18 et 19
Compte Auth0 et application configurée
Si vous n'avez pas encore configuré Auth0, utilisez d'abord la skill auth0-quickstart

Quand NE PAS l'utiliser

Applications Next.js - Utilisez la skill auth0-nextjs pour App Router et Pages Router
Applications React Native mobile - Utilisez la skill auth0-react-native pour iOS/Android
React rendu côté serveur - Utilisez le SDK spécifique au framework (Next.js, Remix, etc.)
Connexion intégrée - Ce SDK utilise Auth0 Universal Login (basé sur la redirection)
Authentification API backend - Utilisez express-openid-connect ou la validation JWT à la place

Flux de démarrage rapide

1. Installer le SDK

npm install @auth0/auth0-react

2. Configurer l'environnement

Pour une configuration automatisée avec Auth0 CLI, consultez le Guide de configuration pour les scripts complets.

Pour une configuration manuelle :

Créez un fichier .env :

Vite :

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

Create React App :

REACT_APP_AUTH0_DOMAIN=your-tenant.auth0.com
REACT_APP_AUTH0_CLIENT_ID=your-client-id

3. Envelopper l'app avec Auth0Provider

Mettez à jour src/main.tsx (Vite) ou src/index.tsx (CRA) :

import React from 'react';
import ReactDOM from 'react-dom/client';
import { Auth0Provider } from '@auth0/auth0-react';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Auth0Provider
      domain={import.meta.env.VITE_AUTH0_DOMAIN} // ou process.env.REACT_APP_AUTH0_DOMAIN
      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
      authorizationParams={{
        redirect_uri: window.location.origin
      }}
    >
      <App />
    </Auth0Provider>
  </React.StrictMode>
);

4. Ajouter l'interface d'authentification

import { useAuth0 } from '@auth0/auth0-react';

export function LoginButton() {
  const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuth0();

  if (isLoading) return <div>Loading...</div>;

  if (isAuthenticated) {
    return (
      <div>
        <span>Welcome, {user?.name}</span>
        <button onClick={() => logout({ logoutParams: { returnTo: window.location.origin } })}>
          Logout
        </button>
      </div>
    );
  }

  return <button onClick={() => loginWithRedirect()}>Login</button>;
}

5. Tester l'authentification

Démarrez votre serveur de développement et testez le flux de connexion :

npm run dev  # Vite
# ou
npm start    # CRA

Documentation détaillée

Guide de configuration - Scripts de configuration automatisée (Bash/PowerShell), commandes CLI, configuration manuelle
Guide d'intégration - Routes protégées, appels API, gestion des erreurs, modèles avancés
Référence API - API SDK complète, options de configuration, référence des hooks, stratégies de test

Erreurs courantes

Erreur	Solution
Oublié d'ajouter l'URI de redirection dans le tableau de bord Auth0	Ajoutez l'URL de votre application (par ex. `http://localhost:3000`, `https://app.example.com`) à Allowed Callback URLs dans le tableau de bord Auth0
Utilisation du mauvais préfixe de variable d'environnement	Vite utilise le préfixe `VITE_`, Create React App utilise `REACT_APP_`
Pas de gestion de l'état de chargement	Vérifiez toujours `isLoading` avant de rendre l'interface dépendante de l'authentification
Stockage des tokens dans localStorage	Ne stockez jamais les tokens manuellement - le SDK gère le stockage sécurisé automatiquement
Wrapper Auth0Provider manquant	L'application entière doit être enveloppée dans `<Auth0Provider>`
Provider non au niveau racine	Auth0Provider doit envelopper tous les composants qui utilisent les hooks d'authentification
Chemin d'importation incorrect pour les variables d'environnement	Vite utilise `import.meta.env.VITE_`, CRA utilise `process.env.REACT_APP_`
Utilisation de `acr_values` pour la MFA dans l'application	Utilisez l'API `useAuth0().mfa` pour les flux d'inscription/défi/vérification dans l'application
Non-capture de `MfaRequiredError`	Enveloppez `getAccessTokenSilently` dans un try/catch et vérifiez `instanceof MfaRequiredError`
Appels HTTP directs aux endpoints MFA	Utilisez la propriété `mfa` de `useAuth0()` — elle gère automatiquement la gestion des tokens
Oubli d'activer les refresh tokens pour la MFA progressive	Définissez `useRefreshTokens={true}` sur Auth0Provider lors de l'utilisation de `interactiveErrorHandler="popup"`

Skills connexes

auth0-quickstart - Configuration basique d'Auth0
auth0-migration - Migration depuis un autre fournisseur d'authentification
auth0-mfa - Ajouter l'authentification multi-facteurs

Référence rapide

Hooks principaux :

useAuth0() - Hook d'authentification principal
isAuthenticated - Vérifier si l'utilisateur est connecté
user - Informations de profil utilisateur
loginWithRedirect() - Initier la connexion
logout() - Déconnecter l'utilisateur
getAccessTokenSilently() - Obtenir un token d'accès pour les appels API
mfa - Client API MFA pour l'inscription, le défi et la vérification
- mfa.getAuthenticators(mfaToken) - Lister les authentificateurs inscrits
- mfa.getEnrollmentFactors(mfaToken) - Obtenir les facteurs d'inscription disponibles
- mfa.enroll(params) - Inscrire un nouvel authentificateur (OTP, SMS, Email, Voice, Push)
- mfa.challenge(params) - Initier un défi MFA
- mfa.verify(params) - Vérifier le défi MFA et terminer l'authentification

Types d'erreurs MFA (à importer de @auth0/auth0-react) :

MfaRequiredError - Levée par getAccessTokenSilently quand la MFA est nécessaire (contient mfa_token et mfa_requirements)
MfaEnrollmentError, MfaChallengeError, MfaVerifyError - Levées par les méthodes mfa.* respectives

Cas d'usage courants :

Boutons de connexion/déconnexion → Voir l'étape 4 ci-dessus
Routes protégées → Guide d'intégration
Appels API avec tokens → Guide d'intégration
Gestion des erreurs → Guide d'intégration
Gestion de la MFA → Guide d'intégration