nextjs auth0 Télécharger - nextjs auth0 Téléchargement du code source

nextjs auth0

Autre code source

v3.5.0

Télécharger

Le SDK Auth0 Next.js est une bibliothèque permettant d'implémenter l'authentification des utilisateurs dans les applications Next.js.

Documentation - Mise en route - Référence API - Commentaires

Documentation

QuickStart - notre guide pour ajouter Auth0 à votre application Next.js.
FAQ - Questions fréquemment posées sur nextjs-auth0.
Exemples - de nombreux exemples pour vos différents cas d'utilisation.
Sécurité - Quelques avis de sécurité importants que vous devriez vérifier.
Architecture - Présentation architecturale du SDK.
Tests - Une aide pour tester votre application nextjs-auth0.
Déploiement - Comment nous déployons notre exemple d'application sur Vercel.
Site Docs - explorez notre site de documentation et apprenez-en plus sur Auth0.

Commencer

Installation

Utilisation de npm :

 npm installer @auth0/nextjs-auth0

Cette bibliothèque nécessite Node.js 16 LTS et les versions LTS plus récentes.

Configuration d'authentification0

Créez une application Web standard dans le tableau de bord Auth0.

Si vous utilisez une application existante , vérifiez que vous avez configuré les paramètres suivants dans votre application Web standard :
Cliquez sur l'onglet "Paramètres" de la page de votre application.
Faites défiler vers le bas et cliquez sur le lien "Afficher les paramètres avancés".
Sous « Paramètres avancés », cliquez sur l'onglet « OAuth ».
Assurez-vous que « JsonWebToken Signature Algorithm » est défini sur RS256 et que « OIDC Conformant » est activé.

Ensuite, configurez les URL suivantes pour votre application dans la section « URI d'application » de la page « Paramètres » :

URL de rappel autorisées : http://localhost:3000/api/auth/callback
URL de déconnexion autorisées : http://localhost:3000/

Prenez note des valeurs Client ID , Client Secret et Domain dans la section « Informations de base ». Vous aurez besoin de ces valeurs à l'étape suivante.

Configuration de base

Configurer l'application

Vous devez autoriser votre application Next.js à communiquer correctement avec Auth0. Vous pouvez le faire en créant un fichier .env.local sous le répertoire racine de votre projet qui définit les valeurs de configuration Auth0 nécessaires comme suit :

 # Une valeur longue et secrète utilisée pour chiffrer le cookie de sessionAUTH0_SECRET='LONG_RANDOM_VALUE'# L'url de base de votre applicationAUTH0_BASE_URL='http://localhost:3000'# L'url de votre domaine locataire Auth0AUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0 .com'# Client de votre application Auth0 IDAUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'# Le secret client de votre application Auth0AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'

Vous pouvez exécuter la commande suivante pour générer une chaîne appropriée pour la valeur AUTH0_SECRET :

 node -e "console.log(crypto.randomBytes(32).toString('hex'))"

Vous pouvez voir une liste complète des options de configuration Auth0 dans la section « Propriétés de configuration » du document « Configuration du module ».

Pour plus de détails sur le chargement des variables d'environnement dans Next.js, visitez le document « Variables d'environnement ».

Ajoutez handleAuth() à votre application, ce qui crée les gestionnaires de route suivants sous le capot qui effectuent différentes parties du flux d'authentification :

/api/auth/login : Votre application Next.js redirige les utilisateurs vers votre fournisseur d'identité pour qu'ils se connectent (vous pouvez éventuellement transmettre un paramètre returnTo pour revenir à une URL relative personnalisée après la connexion, par exemple /api/auth/login?returnTo=/profile ).
/api/auth/callback : votre fournisseur d'identité redirige les utilisateurs vers cette route une fois qu'ils se sont connectés avec succès.
/api/auth/logout : Votre application Next.js déconnecte l'utilisateur.
/api/auth/me : Vous pouvez récupérer les informations de profil utilisateur au format JSON.

Continuez la configuration en fonction de votre routeur :

Routeur de pages
Routeur d'application

Routeur de pages

Ajouter la route API dynamique

Créez un gestionnaire de routage API dynamique dans le répertoire /pages/api :

Créez un répertoire auth sous le répertoire /pages/api/ .
Créez un fichier [auth0].js sous le répertoire auth nouvellement créé.

Le chemin d'accès à votre fichier de route API dynamique serait /pages/api/auth/[auth0].js . Remplissez ce fichier comme suit :

 importer { handleAuth } depuis '@auth0/nextjs-auth0';exporter handleAuth par défaut();

Ajouter le UserProvider à l'application personnalisée

Enveloppez votre composant pages/_app.js avec le composant UserProvider :

 // pages/_app.jsimport React depuis 'react'; importer { UserProvider } depuis '@auth0/nextjs-auth0/client'; exporter la fonction par défaut App({ Component, pageProps }) {
  return (<UserProvider> <Component {...pageProps} /></UserProvider>
  );}

Consommer l'authentification

Vous pouvez maintenant déterminer si un utilisateur est authentifié en vérifiant que l'objet user renvoyé par le hook useUser() est défini. Vous pouvez également connecter ou déconnecter vos utilisateurs de la couche frontend de votre application Next.js en les redirigeant vers l'itinéraire généré automatiquement approprié :

 // pages/index.jsimport { useUser } de '@auth0/nextjs-auth0/client';exporter la fonction par défaut Index() {
  const {utilisateur, erreur, isLoading } = useUser();

  if (isLoading) return <div>Chargement...</div> ;
  si (erreur) renvoie <div>{error.message}</div> ;

  if (user) {return ( <div>Bienvenue {user.name} ! <a href="/api/auth/logout">Déconnexion</a> </div>);
  }

  return <a href="/api/auth/login">Connexion</a>;}

Les règles de peluchage suivantes pourraient suggérer d'utiliser le composant Link au lieu d'une balise d'ancrage. Le composant Link est destiné à effectuer des transitions côté client entre les pages. Comme les liens pointent vers une route API et non vers une page, vous devez les conserver comme balises d'ancrage.

Routeur d'application

Consultez Utilisation de ce SDK avec les composants React Server avant de continuer.

Ajouter la route API dynamique

Créez un gestionnaire de routes API dynamique et fourre-tout dans le répertoire /app/api (à proprement parler, vous n'avez pas besoin de placer les routes API sous /api mais nous maintenons la convention pour plus de simplicité) :

Créez un répertoire api sous le répertoire /app/ .
Créez un répertoire auth sous le répertoire /app/api/ nouvellement créé.
Créez un répertoire [auth0] sous le répertoire auth nouvellement créé.
Créez un fichier route.js sous le répertoire [auth0] nouvellement créé.

Le chemin d'accès à votre fichier de route API dynamique sera /app/api/auth/[auth0]/route.js . Remplissez ce fichier comme suit :

 importer { handleAuth } depuis '@auth0/nextjs-auth0';export const GET = handleAuth();

Ajoutez le `UserProvider` à votre mise en page

Enveloppez votre composant app/layout.js avec le composant UserProvider :

 // app/layout.jsimport React depuis 'react'; importer { UserProvider } depuis '@auth0/nextjs-auth0/client'; exporter la fonction par défaut App({ children }) {
  return (<UserProvider> <body>{children}</body></UserProvider>
  );}

Consommer l'authentification

Vous pouvez maintenant déterminer si un utilisateur est authentifié en vérifiant que l'objet user renvoyé par le hook useUser() est défini. Vous pouvez également connecter ou déconnecter vos utilisateurs de la couche frontend de votre application Next.js en les redirigeant vers l'itinéraire généré automatiquement approprié :

 // pages/index.js'utiliser le client'; importer { useUser } depuis '@auth0/nextjs-auth0/client'; exporter la fonction par défaut Index() {
  const {utilisateur, erreur, isLoading } = useUser();

  if (isLoading) return <div>Chargement...</div> ;
  si (erreur) renvoie <div>{error.message}</div> ;

  if (user) {return ( <div>Bienvenue {user.name} ! <a href="/api/auth/logout">Déconnexion</a> </div>);
  }

  return <a href="/api/auth/login">Connexion</a>;}

Les règles de peluchage suivantes pourraient suggérer d'utiliser le composant Link au lieu d'une balise d'ancrage. Le composant Link est destiné à effectuer des transitions côté client entre les pages. Comme les liens pointent vers une route API et non vers une page, vous devez les conserver sous forme de balises d'ancrage.

Utilisation de ce SDK avec les composants React Server

Les composants serveur du répertoire d'applications (y compris les pages et les mises en page) ne peuvent pas écrire dans un cookie.

Si vous comptez uniquement sur les composants serveur pour lire et mettre à jour votre session, vous devez être conscient des points suivants :

Si vous disposez d'une session continue (valeur par défaut pour ce SDK), l'expiration ne sera pas mise à jour lorsque l'utilisateur visitera votre site. La session peut donc expirer plus tôt que prévu (vous pouvez utiliser withMiddlewareAuthRequired pour atténuer cela).
Si vous actualisez le jeton d'accès, le nouveau jeton d'accès ne sera pas conservé dans la session. Ainsi, les tentatives ultérieures pour obtenir un jeton d’accès entraîneront toujours l’actualisation du jeton d’accès expiré dans la session.
Si vous effectuez d'autres mises à jour de la session, elles ne seront pas conservées entre les requêtes.

Le cookie peut être écrit à partir d'un middleware, de gestionnaires de routes et d'actions du serveur.

Pour d’autres exemples complets, consultez le document EXAMPLES.md.

Référence API

Serveur

Pour le nœud

import * from @auth0/nextjs-auth0

Pour l'exécution Edge

import * from @auth0/nextjs-auth0/edge

Options de configuration et variables d'environnement
initAuth0
handleAuth
handleConnexion
handleCallback
handleLogout
poignéeProfil
avecApiAuthRequired
avecPageAuthRequired
obtenirSession
mise à jourSession
getAccessToken
withMiddlewareAuthRequired (Edge uniquement)

Client (pour le navigateur)

import * from @auth0/nextjs-auth0/client

Fournisseur d'utilisateurs
utiliserUtilisateur
avecPageAuthRequired

Aides aux tests

import * from @auth0/nextjs-auth0/testing

générerSessionCookie

Consultez la documentation API générée automatiquement pour plus de détails.

Cookies et sécurité

Tous les cookies seront définis sur HttpOnly, SameSite=Lax et seront définis sur Secure si l' AUTH0_BASE_URL de l'application est https .

Le paramètre HttpOnly garantira que JavaScript côté client ne pourra pas accéder au cookie afin de réduire la surface d'attaque des attaques XSS.

Le paramètre SameSite=Lax aidera à atténuer les attaques CSRF. Apprenez-en davantage sur SameSite en lisant le billet de blog « Modifications de comportement du navigateur à venir : ce que les développeurs doivent savoir ».

Mise en cache et sécurité

De nombreux fournisseurs d'hébergement proposeront de mettre en cache votre contenu en périphérie afin de fournir des données à vos utilisateurs le plus rapidement possible. Par exemple, Vercel mettra en cache votre contenu sur le réseau Vercel Edge pour tout le contenu statique et les fonctions sans serveur si vous fournissez les en-têtes de mise en cache nécessaires dans votre réponse.

C'est généralement une mauvaise idée de mettre en cache toute réponse nécessitant une authentification, même si le contenu de la réponse semble sûr à mettre en cache, il peut y avoir d'autres données dans la réponse qui ne le sont pas.

Ce SDK propose une session continue par défaut, ce qui signifie que toute réponse qui lit la session aura un en-tête Set-Cookie pour mettre à jour l'expiration du cookie. Vercel et potentiellement d'autres fournisseurs d'hébergement incluent l'en-tête Set-Cookie dans la réponse mise en cache, donc même si vous pensez que le contenu de la réponse peut être mis en cache publiquement, l'en-tête Set-Cookie des réponses ne le peut pas.

Vérifiez les règles de mise en cache de votre fournisseur d'hébergement, mais en général, vous ne devez jamais mettre en cache les réponses qui nécessitent une authentification ou même toucher la session pour vérifier l'authentification (par exemple lorsque vous utilisez withApiAuthRequired , withPageAuthRequired ou même simplement getSession ou getAccessToken ).

Gestion des erreurs et sécurité

Les erreurs provenant d'Auth0 dans le rappel redirect_uri peuvent contenir une entrée utilisateur reflétée via l' error OpenID Connect et le paramètre de requête error_description . Pour cette raison, nous effectuons quelques échappements de base sur les propriétés message , error et error_description de IdentityProviderError .

Mais, si vous écrivez votre propre gestionnaire d'erreurs, vous ne devez pas restituer le message d'erreur ou les propriétés error et error_description sans utiliser d'abord un moteur de création de modèles qui les échappera correctement pour d'autres contextes HTML.

Chemin de base et routage internationalisé

Avec Next.js, vous pouvez déployer une application Next.js sous un sous-chemin d'un domaine à l'aide du chemin de base et servir des routes internationalisées (i18n) à l'aide du routage internationalisé.

Si vous utilisez ces fonctionnalités, les URL de votre application changeront et donc les URL des routes nextjs-auth0 changeront. Pour cela, il existe différents endroits dans le SDK où vous pouvez personnaliser l'URL.

Par exemple, si basePath: '/foo' vous devez ajouter ceci aux loginUrl et profileUrl spécifiés dans votre Auth0Provider :

 // _app.jsxfunction App({ Composant, pageProps }) {
  return (<UserProvider loginUrl="/foo/api/auth/login" profileUrl="/foo/api/auth/me"> <Component {...pageProps} /></UserProvider>
  );}

De plus, tous les liens de connexion ou de déconnexion doivent inclure le basePath :

 <a href="/foo/api/auth/login">Connexion</a><br /><a href="/foo/api/auth/logout">Déconnexion</a>

Vous devez configurer la baseUrl (ou la variable d'environnement AUTH0_BASE_URL ). Par exemple:

 # .env.localAUTH0_BASE_URL=http://localhost:3000/foo

Pour toutes les pages protégées côté serveur avec PageAuthRequired, vous devez mettre à jour le paramètre returnTo en fonction du basePath et locale si nécessaire.

 // ./pages/my-ssr-page.jsxexport par défaut MySsrPage = () => <></>;const getFullReturnTo = (ctx) => {
  // TODO : implémentez getFullReturnTo en fonction de ctx.resolvedUrl, ctx.locale
  // et les paramètres basePath et i18n de votre next.config.js.
  return '/foo/en-US/my-ssr-page';};export const getServerSideProps = (ctx) => {
  const returnTo = getFullReturnTo(ctx.req);
  return withPageAuthRequired({ returnTo })(ctx);};

Comparaison avec le SDK Auth0 React

Nous fournissons également un SDK Auth0 React, auth0-react, qui peut convenir à votre application Next.js.

Le modèle de sécurité SPA utilisé par auth0-react est différent du modèle de sécurité d'application Web utilisé par ce SDK. En bref, ce SDK protège les pages et les routes API avec une session cookie (voir « Cookies et sécurité »). Une bibliothèque SPA comme auth0-react stockera le jeton d'identification et le jeton d'accès de l'utilisateur directement dans le navigateur et les utilisera pour accéder directement aux API externes.

Vous devez être conscient des implications en matière de sécurité des deux modèles. Cependant, auth0-react peut être plus adapté à vos besoins si vous répondez à l'un des scénarios suivants :

Vous utilisez l'exportation HTML statique avec Next.js.
Vous n'avez pas besoin d'accéder aux données utilisateur pendant le rendu côté serveur.
Vous souhaitez obtenir le jeton d'accès et appeler des API externes directement à partir de la couche frontend plutôt que d'utiliser les routes API Next.js comme proxy pour appeler des API externes.

Essai

Par défaut, le SDK crée et gère une instance singleton à exécuter pendant toute la durée de vie de l'application. Lorsque vous testez votre application, vous devrez peut-être réinitialiser cette instance afin que son état ne soit pas divulgué entre les tests.

Si vous utilisez Jest, nous vous recommandons d'utiliser jest.resetModules() après chaque test. Vous pouvez également envisager de créer votre propre instance du SDK, afin qu'elle puisse être recréée entre les tests.

Pour les tests de bout en bout, découvrez comment nous utilisons un fournisseur OIDC fictif.

Déploiement

Pour le déploiement, jetez un œil à la façon dont nous déployons notre exemple d'application sur Vercel.

Contribuer

Nous apprécions les commentaires et les contributions à ce dépôt ! Avant de commencer, veuillez lire ce qui suit :

Directives générales de contribution d'Auth0
Lignes directrices du code de conduite d'Auth0
Le guide de contribution de ce dépôt

Rapports de vulnérabilité

Veuillez ne pas signaler les failles de sécurité sur le système de suivi des problèmes public GitHub. Le programme de divulgation responsable détaille la procédure de divulgation des problèmes de sécurité.