nextjs auth0
v3.5.0
Das Auth0 Next.js SDK ist eine Bibliothek zur Implementierung der Benutzerauthentifizierung in Next.js-Anwendungen.
Dokumentation – Erste Schritte – API-Referenz – Feedback
QuickStart – unser Leitfaden zum Hinzufügen von Auth0 zu Ihrer Next.js-App.
FAQs – Häufig gestellte Fragen zu nextjs-auth0.
Beispiele – viele Beispiele für Ihre verschiedenen Anwendungsfälle.
Sicherheit – Einige wichtige Sicherheitshinweise, die Sie überprüfen sollten.
Architektur – Architekturüberblick über das SDK.
Testen – Hilfe beim Testen Ihrer nextjs-auth0-Anwendung.
Bereitstellen – So stellen wir unsere Beispiel-App auf Vercel bereit.
Docs-Site – Erkunden Sie unsere Docs-Site und erfahren Sie mehr über Auth0.
Mit npm:
npm install @auth0/nextjs-auth0
Diese Bibliothek erfordert Node.js 16 LTS und neuere LTS-Versionen.
Erstellen Sie eine reguläre Webanwendung im Auth0-Dashboard.
Wenn Sie eine vorhandene Anwendung verwenden , stellen Sie sicher, dass Sie die folgenden Einstellungen in Ihrer regulären Webanwendung konfiguriert haben:
Klicken Sie auf der Seite Ihrer Anwendung auf die Registerkarte „Einstellungen“.
Scrollen Sie nach unten und klicken Sie auf den Link „Erweiterte Einstellungen anzeigen“.
Klicken Sie unter „Erweiterte Einstellungen“ auf die Registerkarte „OAuth“.
Stellen Sie sicher, dass „JsonWebToken Signature Algorithm“ auf
RS256eingestellt und „OIDC Conformant“ aktiviert ist.
Konfigurieren Sie als Nächstes die folgenden URLs für Ihre Anwendung im Abschnitt „Anwendungs-URIs“ der Seite „Einstellungen“:
Zulässige Rückruf-URLs : http://localhost:3000/api/auth/callback
Zulässige Abmelde-URLs : http://localhost:3000/
Notieren Sie sich die Werte für Client-ID , Client-Geheimnis und Domäne im Abschnitt „Grundlegende Informationen“. Diese Werte benötigen Sie im nächsten Schritt.
Sie müssen zulassen, dass Ihre Next.js-Anwendung ordnungsgemäß mit Auth0 kommuniziert. Sie können dies tun, indem Sie eine .env.local Datei unter Ihrem Stammprojektverzeichnis erstellen, die die erforderlichen Auth0-Konfigurationswerte wie folgt definiert:
# Ein langer, geheimer Wert, der zum Verschlüsseln des Sitzungscookies verwendet wird. AUTH0_SECRET='LONG_RANDOM_VALUE'# Die Basis-URL Ihrer AnwendungAUTH0_BASE_URL='http://localhost:3000'# Die URL Ihrer Auth0-MandantendomäneAUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0 .com'# Der Client Ihrer Auth0-Anwendung IDAUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'# Das Client-Geheimnis Ihrer Auth0-AnwendungAUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'
Sie können den folgenden Befehl ausführen, um eine geeignete Zeichenfolge für den AUTH0_SECRET -Wert zu generieren:
node -e "console.log(crypto.randomBytes(32).toString('hex'))"Eine vollständige Liste der Auth0-Konfigurationsoptionen finden Sie im Abschnitt „Konfigurationseigenschaften“ des Dokuments „Modulkonfiguration“.
Weitere Informationen zum Laden von Umgebungsvariablen in Next.js finden Sie im Dokument „Umgebungsvariablen“.
Fügen Sie handleAuth() zu Ihrer App hinzu, wodurch unter der Haube die folgenden Routenhandler erstellt werden, die verschiedene Teile des Authentifizierungsflusses ausführen:
/api/auth/login : Ihre Next.js-Anwendung leitet Benutzer an Ihren Identitätsanbieter weiter, damit sie sich anmelden können (optional können Sie einen returnTo Parameter übergeben, um nach der Anmeldung zu einer benutzerdefinierten relativen URL zurückzukehren, z. B. /api/auth/login?returnTo=/profile ).
/api/auth/callback : Ihr Identitätsanbieter leitet Benutzer nach erfolgreicher Anmeldung auf diese Route um.
/api/auth/logout : Ihre Next.js-Anwendung meldet den Benutzer ab.
/api/auth/me : Sie können Benutzerprofilinformationen im JSON-Format abrufen.
Setzen Sie die Einrichtung abhängig von Ihrem Router fort:
Seitenrouter
App-Router
Erstellen Sie einen dynamischen API-Routenhandler im Verzeichnis /pages/api :
Erstellen Sie ein auth unter dem Verzeichnis /pages/api/ .
Erstellen Sie eine [auth0].js Datei im neu erstellten auth -Verzeichnis.
Der Pfad zu Ihrer dynamischen API-Routendatei wäre /pages/api/auth/[auth0].js . Füllen Sie diese Datei wie folgt:
import { handleAuth } from '@auth0/nextjs-auth0';export default handleAuth(); Umschließen Sie Ihre pages/_app.js -Komponente mit der UserProvider -Komponente:
// page/_app.jsimport React from 'react';import { UserProvider } from '@auth0/nextjs-auth0/client';export default function App({ Component, pageProps }) {
return (<UserProvider> <Component {...pageProps} /></UserProvider>
);} Sie können jetzt feststellen, ob ein Benutzer authentifiziert ist, indem Sie überprüfen, ob das vom useUser() Hook zurückgegebene user definiert ist. Sie können Ihre Benutzer auch auf der Frontend-Ebene Ihrer Next.js-Anwendung an- oder abmelden, indem Sie sie auf die entsprechende automatisch generierte Route umleiten:
// page/index.jsimport { useUser } from '@auth0/nextjs-auth0/client';export default function Index() {
const { user, error, isLoading } = useUser();
if (isLoading) return <div>Loading...</div>;
if (error) return <div>{error.message}</div>;
if (user) {return ( <div>Willkommen {user.name}! <a href="/api/auth/logout">Logout</a> </div>);
}
return <a href="/api/auth/login">Login</a>;}Die nächsten Linting-Regeln könnten die Verwendung der
LinkKomponente anstelle eines Ankertags vorschlagen. DieLinkKomponente soll clientseitige Übergänge zwischen Seiten durchführen. Da die Links auf eine API-Route und nicht auf eine Seite verweisen, sollten Sie sie als Anker-Tags behalten.
Sehen Sie sich „Verwenden dieses SDK mit React Server-Komponenten“ an, bevor Sie fortfahren.
Erstellen Sie einen umfassenden, dynamischen API-Routen-Handler im Verzeichnis /app/api (streng genommen müssen Sie keine API-Routen unter /api ablegen, wir behalten jedoch der Einfachheit halber die Konvention bei):
Erstellen Sie ein api -Verzeichnis unter dem Verzeichnis /app/ .
Erstellen Sie ein auth unter dem neu erstellten Verzeichnis /app/api/ .
Erstellen Sie ein [auth0] -Verzeichnis unter dem neu erstellten auth Verzeichnis.
Erstellen Sie eine route.js Datei im neu erstellten Verzeichnis [auth0] .
Der Pfad zu Ihrer dynamischen API-Routendatei lautet /app/api/auth/[auth0]/route.js . Füllen Sie diese Datei wie folgt:
import { handleAuth } from '@auth0/nextjs-auth0';export const GET = handleAuth();UserProvider zu Ihrem Layout hinzu Umschließen Sie Ihre app/layout.js -Komponente mit der UserProvider -Komponente:
// app/layout.jsimport React from 'react';import { UserProvider } from '@auth0/nextjs-auth0/client';export default function App({children }) {
return (<UserProvider> <body>{children}</body></UserProvider>
);} Sie können jetzt feststellen, ob ein Benutzer authentifiziert ist, indem Sie überprüfen, ob das vom useUser() Hook zurückgegebene user definiert ist. Sie können Ihre Benutzer auch auf der Frontend-Ebene Ihrer Next.js-Anwendung an- oder abmelden, indem Sie sie auf die entsprechende automatisch generierte Route umleiten:
// page/index.js'use client';import { useUser } from '@auth0/nextjs-auth0/client';export default function Index() {
const { user, error, isLoading } = useUser();
if (isLoading) return <div>Loading...</div>;
if (error) return <div>{error.message}</div>;
if (user) {return ( <div>Willkommen {user.name}! <a href="/api/auth/logout">Logout</a> </div>);
}
return <a href="/api/auth/login">Login</a>;}Die nächsten Linting-Regeln könnten die Verwendung der
LinkKomponente anstelle eines Ankertags vorschlagen. DieLinkKomponente soll clientseitige Übergänge zwischen Seiten durchführen. Da die Links auf eine API-Route und nicht auf eine Seite verweisen, sollten Sie sie als Anker-Tags behalten.
Serverkomponenten im App-Verzeichnis (einschließlich Seiten und Layouts) können nicht in ein Cookie schreiben.
Wenn Sie sich zum Lesen und Aktualisieren Ihrer Sitzung ausschließlich auf Serverkomponenten verlassen, sollten Sie Folgendes beachten:
Wenn Sie eine fortlaufende Sitzung haben (die Standardeinstellung für dieses SDK), wird der Ablauf nicht aktualisiert, wenn der Benutzer Ihre Website besucht. Daher läuft die Sitzung möglicherweise früher ab als erwartet (Sie können withMiddlewareAuthRequired verwenden, um dies zu entschärfen).
Wenn Sie das Zugriffstoken aktualisieren, bleibt das neue Zugriffstoken nicht in der Sitzung bestehen. Nachfolgende Versuche, ein Zugriffstoken abzurufen, führen daher immer zu einer Aktualisierung des abgelaufenen Zugriffstokens in der Sitzung.
Wenn Sie weitere Aktualisierungen an der Sitzung vornehmen, werden diese zwischen den Anforderungen nicht beibehalten.
Das Cookie kann von Middleware, Routenhandlern und Serveraktionen geschrieben werden.
Weitere umfassende Beispiele finden Sie im Dokument EXAMPLES.md.
import * from @auth0/nextjs-auth0
import * from @auth0/nextjs-auth0/edge
Konfigurationsoptionen und Umgebungsvariablen
initAuth0
handleAuth
handleLogin
handleCallback
handleLogout
handleProfile
withApiAuthRequired
withPageAuthRequired
getSession
updateSession
getAccessToken
withMiddlewareAuthRequired (nur Edge)
import * from @auth0/nextjs-auth0/client
Benutzeranbieter
useUser
withPageAuthRequired
import * from @auth0/nextjs-auth0/testing
generierenSessionCookie
Weitere Informationen finden Sie in den automatisch generierten API-Dokumenten
Alle Cookies werden auf HttpOnly, SameSite=Lax und auf Secure gesetzt, wenn die AUTH0_BASE_URL der Anwendung https ist.
Die Einstellung HttpOnly stellt sicher, dass clientseitiges JavaScript nicht auf das Cookie zugreifen kann, um die Angriffsfläche von XSS-Angriffen zu verringern.
Die Einstellung SameSite=Lax trägt dazu bei, CSRF-Angriffe abzuschwächen. Erfahren Sie mehr über SameSite, indem Sie den Blogbeitrag „Bevorstehende Änderungen im Browserverhalten: Was Entwickler wissen müssen“ lesen.
Viele Hosting-Anbieter bieten an, Ihre Inhalte am Edge zwischenzuspeichern, um Ihren Benutzern Daten so schnell wie möglich bereitzustellen. Beispielsweise speichert Vercel Ihre Inhalte im Vercel Edge-Netzwerk für alle statischen Inhalte und serverlosen Funktionen zwischen, wenn Sie in Ihrer Antwort die erforderlichen Caching-Header angeben.
Im Allgemeinen ist es keine gute Idee, jede Antwort zwischenzuspeichern, die eine Authentifizierung erfordert. Auch wenn der Inhalt der Antwort sicher zum Zwischenspeichern erscheint, kann die Antwort andere Daten enthalten, die dies nicht sind.
Dieses SDK bietet standardmäßig eine fortlaufende Sitzung, was bedeutet, dass jede Antwort, die die Sitzung liest, einen Set-Cookie -Header hat, um den Ablauf des Cookies zu aktualisieren. Vercel und möglicherweise andere Hosting-Anbieter fügen den Set-Cookie -Header in die zwischengespeicherte Antwort ein. Selbst wenn Sie glauben, dass der Inhalt der Antwort öffentlich zwischengespeichert werden kann, ist dies Set-Cookie -Header der Antworten nicht der Fall.
Überprüfen Sie die Caching-Regeln Ihres Hosting-Anbieters, aber im Allgemeinen sollten Sie niemals Antworten zwischenspeichern, die entweder eine Authentifizierung erfordern oder sogar die Sitzung berühren, um die Authentifizierung zu überprüfen (z. B. bei Verwendung withApiAuthRequired , withPageAuthRequired oder einfach nur getSession oder getAccessToken ).
Fehler, die von Auth0 im redirect_uri Rückruf stammen, können reflektierte Benutzereingaben über die OpenID Connect-Abfrageparameter error und error_description enthalten. Aus diesem Grund führen wir einige grundlegende Escape-Vorgänge für die Eigenschaften message , error und error_description des IdentityProviderError durch.
Wenn Sie jedoch Ihren eigenen Fehlerhandler schreiben, sollten Sie die Eigenschaften „error message oder error und error_description nicht rendern, ohne eine Vorlagen-Engine zu verwenden, die sie zuerst ordnungsgemäß für andere HTML-Kontexte maskiert.
Mit Next.js können Sie eine Next.js-Anwendung unter einem Unterpfad einer Domäne mithilfe von Base Path bereitstellen und internationalisierte (i18n) Routen mithilfe von Internationalized Routing bereitstellen.
Wenn Sie diese Funktionen verwenden, ändern sich die URLs Ihrer Anwendung und damit auch die URLs zu den nextjs-auth0-Routen. Um dies zu berücksichtigen, gibt es im SDK verschiedene Stellen, an denen Sie die URL anpassen können.
Wenn beispielsweise basePath: '/foo' lautet, sollten Sie dies der in Ihrem Auth0Provider angegebenen loginUrl und profileUrl voranstellen:
// _app.jsxfunction App({ Component, pageProps }) {
return (<UserProvider loginUrl="/foo/api/auth/login" profileUrl="/foo/api/auth/me"> <Component {...pageProps} /></UserProvider>
);} Außerdem sollten alle Links zum Anmelden oder Abmelden den basePath enthalten:
<a href="/foo/api/auth/login">Anmelden</a><br /><a href="/foo/api/auth/logout">Abmelden</a>
Sie sollten die baseUrl (oder die Umgebungsvariable AUTH0_BASE_URL ) konfigurieren. Zum Beispiel:
# .env.localAUTH0_BASE_URL=http://localhost:3000/foo
Für alle Seiten, die serverseitig mit PageAuthRequired geschützt sind, sollten Sie bei Bedarf den Parameter returnTo “ je nach basePath und locale aktualisieren.
// ./pages/my-ssr-page.jsxexport default MySsrPage = () => <></>;const getFullReturnTo = (ctx) => {
// TODO: getFullReturnTo basierend auf ctx.resolvedUrl und ctx.locale implementieren
// und die BasePath- und i18n-Einstellungen Ihrer next.config.js.
return '/foo/en-US/my-ssr-page';};export const getServerSideProps = (ctx) => {
const returnTo = getFullReturnTo(ctx.req);
return withPageAuthRequired({ returnTo })(ctx);};Wir bieten auch ein Auth0 React SDK, auth0-react, an, das möglicherweise für Ihre Next.js-Anwendung geeignet ist.
Das von auth0-react verwendete SPA-Sicherheitsmodell unterscheidet sich vom von diesem SDK verwendeten Webanwendungs-Sicherheitsmodell. Kurz gesagt, dieses SDK schützt Seiten und API-Routen mit einer Cookie-Sitzung (siehe „Cookies und Sicherheit“). Eine SPA-Bibliothek wie auth0-react speichert das ID-Token und das Zugriffstoken des Benutzers direkt im Browser und verwendet sie für den direkten Zugriff auf externe APIs.
Sie sollten sich der Sicherheitsauswirkungen beider Modelle bewusst sein. Allerdings ist auth0-react möglicherweise besser für Ihre Anforderungen geeignet, wenn eines der folgenden Szenarios auf Sie zutrifft:
Sie verwenden den statischen HTML-Export mit Next.js.
Während des serverseitigen Renderns müssen Sie nicht auf Benutzerdaten zugreifen.
Sie möchten das Zugriffstoken erhalten und externe APIs direkt von der Frontend-Ebene aufrufen, anstatt Next.js-API-Routen als Proxy zum Aufrufen externer APIs zu verwenden.
Standardmäßig erstellt und verwaltet das SDK eine Singleton-Instanz, die während der gesamten Lebensdauer der Anwendung ausgeführt wird. Beim Testen Ihrer Anwendung müssen Sie diese Instanz möglicherweise zurücksetzen, damit ihr Status zwischen den Tests nicht verloren geht.
Wenn Sie Jest verwenden, empfehlen wir, nach jedem Test jest.resetModules() zu verwenden. Alternativ können Sie auch eine eigene Instanz des SDK erstellen, damit diese zwischen den Tests neu erstellt werden kann.
Schauen Sie sich für End-to-End-Tests an, wie wir einen simulierten OIDC-Anbieter verwenden.
Sehen Sie sich zur Bereitstellung an, wie wir unsere Beispiel-App auf Vercel bereitstellen.
Wir freuen uns über Feedback und Beiträge zu diesem Repo! Bevor Sie beginnen, lesen Sie bitte Folgendes:
Allgemeine Beitragsrichtlinien von Auth0
Verhaltenskodex-Richtlinien von Auth0
Der Beitragsleitfaden dieses Repos
Bitte melden Sie Sicherheitslücken nicht im öffentlichen GitHub-Issue-Tracker. Das Responsible Disclosure Program beschreibt detailliert das Verfahren zur Offenlegung von Sicherheitsproblemen.
Auth0 ist eine einfach zu implementierende, anpassbare Authentifizierungs- und Autorisierungsplattform. Weitere Informationen finden Sie unter Warum Auth0?
Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Informationen finden Sie in der LICENSE-Datei.
