authkit nextjs

AuthKit Next.js-Bibliothek

Die AuthKit-Bibliothek für Next.js bietet praktische Helfer für die Authentifizierung und Sitzungsverwaltung mithilfe von WorkOS und AuthKit mit Next.js.

Hinweis: Diese Bibliothek ist für die Verwendung mit dem Next.js App Router vorgesehen.

Installation

Installieren Sie das Paket mit:

 npm i @workos-inc/authkit-nextjs

oder

 yarn add @workos-inc/authkit-nextjs

Video-Tutorial

Vor dem Flug

Stellen Sie sicher, dass die folgenden Werte in Ihrer Umgebungsvariablendatei .env.local vorhanden sind. Die Client-ID und der API-Schlüssel finden Sie im WorkOS-Dashboard, auch der Weiterleitungs-URI kann dort konfiguriert werden.

WORKOS_CLIENT_ID= " client_... " # retrieved from the WorkOS dashboard
WORKOS_API_KEY= " sk_test_... " # retrieved from the WorkOS dashboard
WORKOS_COOKIE_PASSWORD= " <your password> " # generate a secure password here
NEXT_PUBLIC_WORKOS_REDIRECT_URI= " http://localhost:3000/callback " # configured in the WorkOS dashboard

WORKOS_COOKIE_PASSWORD ist der private Schlüssel, der zum Verschlüsseln des Sitzungscookies verwendet wird. Es muss mindestens 32 Zeichen lang sein. Sie können den 1Password-Generator oder die openssl -Bibliothek verwenden, um über die Befehlszeile ein sicheres Passwort zu generieren:

 openssl rand -base64 24

Um die signOut -Methode verwenden zu können, müssen Sie die Startseite Ihrer App in den Einstellungen Ihres WorkOS-Dashboards unter „Weiterleitungen“ festlegen.

Optionale Konfiguration

Bestimmte Umgebungsvariablen sind optional und können zum Debuggen oder Konfigurieren von Cookie-Einstellungen verwendet werden.

WORKOS_COOKIE_MAX_AGE= ' 600 ' # maximum age of the cookie in seconds. Defaults to 400 days, the maximum allowed in Chrome
WORKOS_COOKIE_DOMAIN= ' example.com '
WORKOS_COOKIE_NAME= ' authkit-cookie '
WORKOS_API_HOSTNAME= ' api.workos.com ' # base WorkOS API URL
WORKOS_API_HTTPS=true # whether to use HTTPS in API calls
WORKOS_API_PORT=3000 # port to use for API calls

WORKOS_COOKIE_DOMAIN kann verwendet werden, um WorkOS-Sitzungen zwischen Apps/Domänen zu teilen. Hinweis: Das WORKOS_COOKIE_PASSWORD muss für alle Apps/Domänen gleich sein. Für die meisten Anwendungsfälle nicht erforderlich.

Aufstellen

Rückrufroute

WorkOS erfordert, dass Sie über eine Rückruf-URL verfügen, zu der Benutzer nach der Authentifizierung zurückgeleitet werden können. Stellen Sie in Ihrer Next.js-App eine API-Route bereit und fügen Sie Folgendes hinzu.

 import { handleAuth } from '@workos-inc/authkit-nextjs' ;

export const GET = handleAuth ( ) ;

Stellen Sie sicher, dass diese Route mit der Variablen WORKOS_REDIRECT_URI und dem konfigurierten Umleitungs-URI in Ihrem WorkOS-Dashboard übereinstimmt. Wenn Ihr Weiterleitungs-URI beispielsweise http://localhost:3000/auth/callback lautet, fügen Sie den obigen Code in /app/auth/callback/route.ts ein.

Sie können auch den Pfadnamen steuern, zu dem der Benutzer nach der Anmeldung weitergeleitet wird, indem Sie eine returnPathname -Option wie folgt an handleAuth übergeben:

 export const GET = handleAuth ( { returnPathname : '/dashboard' } ) ;

handleAuth kann mit mehreren Optionen verwendet werden.

Option	Standard	Beschreibung
returnPathname	/	Der Pfadname, zu dem der Benutzer nach der Anmeldung umgeleitet werden soll
baseURL	undefined	Die Basis-URL, die anstelle der in der Anfrage für den Umleitungs-URI verwendet werden soll. Nützlich, wenn die App in einem Container wie Docker ausgeführt wird, wobei der Hostname sich von dem in der Anfrage unterscheiden kann

Middleware

Diese Bibliothek basiert auf der Next.js-Middleware, um die Sitzungsverwaltung für Routen bereitzustellen. Fügen Sie Folgendes in Ihre middleware.ts Datei im Stammverzeichnis Ihres Projekts ein:

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin' ] } ;

Die Middleware kann mit mehreren Optionen konfiguriert werden.

Option	Standard	Beschreibung
redirectUri	undefined	Wird in Fällen verwendet, in denen Ihr Weiterleitungs-URI dynamisch festgelegt werden muss (z. B. Vercel-Vorschaubereitstellungen).
middlewareAuth	undefined	Wird zum Konfigurieren von Middleware-Authentifizierungsoptionen verwendet. Weitere Informationen finden Sie unter Middleware-Authentifizierung.
debug	false	Aktiviert Debug-Protokolle.
signUpPaths	[]	Wird verwendet, um Pfade anzugeben, die bei der Umleitung zu AuthKit den Hinweis auf dem Anmeldebildschirm verwenden sollen.

Benutzerdefinierter Weiterleitungs-URI

In Fällen, in denen Ihr Umleitungs-URI dynamisch festgelegt werden muss (z. B. Vercel-Vorschaubereitstellungen), verwenden Sie die Option redirectUri in authkitMiddleware :

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  redirectUri : 'https://foo.example.com/callback' ,
} ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin' ] } ;

Benutzerdefinierte Umleitungs-URIs werden über einem in den Umgebungsvariablen konfigurierten Umleitungs-URI verwendet.

Verwendung

Wickeln Sie Ihre App in AuthKitProvider ein

Verwenden Sie AuthKitProvider , um Ihr App-Layout zu umschließen, was einige Schutzmaßnahmen für Authentifizierungs-Edge-Fälle bietet.

 import { AuthKitProvider } from '@workos-inc/authkit-nextjs' ;

export default function RootLayout ( { children } : { children : React . ReactNode } ) {
  return (
    < html lang = "en" >
      < body >
        < AuthKitProvider > { children } < / AuthKitProvider >
      < / body >
    < / html >
  ) ;
}

Rufen Sie den aktuellen Benutzer ab

Für Seiten, auf denen Sie eine Anmelde- und Abmeldeansicht anzeigen möchten, verwenden Sie withAuth um das Benutzerprofil von WorkOS abzurufen.

 import Link from 'next/link' ;
import { getSignInUrl , getSignUpUrl , withAuth , signOut } from '@workos-inc/authkit-nextjs' ;

export default async function HomePage ( ) {
  // Retrieves the user from the session or returns `null` if no user is signed in
  const { user } = await withAuth ( ) ;

  if ( ! user ) {
    // Get the URL to redirect the user to AuthKit to sign in
    const signInUrl = await getSignInUrl ( ) ;

    // Get the URL to redirect the user to AuthKit to sign up
    const signUpUrl = await getSignUpUrl ( ) ;

    return (
      < >
        < Link href = { signInUrl } > Log in < / Link >
        < Link href = { signUpUrl } > Sign Up < / Link >
      < / >
    ) ;
  }

  return (
    < form
      action = { async ( ) => {
        'use server' ;
        await signOut ( ) ;
      } }
    >
      < p > Welcome back { user ?. firstName && `, ${ user ?. firstName } ` } < / p >
      < button type = "submit" > Sign out < / button >
    < / form >
  ) ;
}

Authentifizierung erforderlich

Für Seiten, auf denen ein angemeldeter Benutzer obligatorisch ist, können Sie die Option ensureSignedIn verwenden:

 const { user } = await withAuth ( { ensureSignedIn : true } ) ;

Durch die Aktivierung von ensureSignedIn werden Benutzer zu AuthKit umgeleitet, wenn sie versuchen, ohne Authentifizierung auf die Seite zuzugreifen.

Middleware-Authentifizierung

Das Standardverhalten dieser Bibliothek besteht darin, die Authentifizierung über die withAuth -Methode auf Seitenbasis anzufordern. Es gibt einige Anwendungsfälle, in denen Sie withAuth nicht aufrufen möchten (z. B. benötigen Sie keine Benutzerdaten für Ihre Seite) oder wenn Sie einen „standardmäßig sicheren“ Ansatz bevorzugen, bei dem jede in Ihrem Middleware-Matcher definierte Route geschützt ist sofern nicht anders angegeben. In diesen Fällen können Sie sich stattdessen für die Verwendung der Middleware-Authentifizierung entscheiden:

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  middlewareAuth : {
    enabled : true ,
    unauthenticatedPaths : [ '/' , '/about' ] ,
  } ,
} ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin/:path*' , '/about' ] } ;

Im obigen Beispiel erfordert die Seite /admin die Anmeldung eines Benutzers, während auf / “ und /about ohne Anmeldung zugegriffen werden kann.

unauthenticatedPaths verwendet dieselbe Glob-Logik wie der Next.js-Matcher.

Sitzung in der Middleware abrufen

Manchmal ist es nützlich, die Benutzersitzung zu überprüfen, wenn Sie benutzerdefinierte Middleware erstellen möchten. Die Hilfsmethode getSession ruft die Sitzung aus dem Cookie ab und überprüft das Zugriffstoken.

 import { authkitMiddleware , getSession } from '@workos-inc/authkit-nextjs' ;
import { NextRequest , NextFetchEvent } from 'next/server' ;

export default async function middleware ( request : NextRequest , event : NextFetchEvent ) {
  // authkitMiddleware will handle refreshing the session if the access token has expired
  const response = await authkitMiddleware ( ) ( request , event ) ;

  // If session is undefined, the user is not authenticated
  const session = await getSession ( response ) ;

  // ...add additional middleware logic here

  return response ;
}

// Match against pages that require auth
export const config = { matcher : [ '/' , '/account/:path*' ] } ;

Abmelden

Verwenden Sie die signOut -Methode, um den aktuell angemeldeten Benutzer abzumelden und zur Startseite Ihrer App umzuleiten. Die Homepage-Weiterleitung wird in Ihren WorkOS-Dashboard-Einstellungen unter „Weiterleiten“ eingestellt.

Visualisierung einer Imitation

Rendern Sie die Komponente Impersonation in Ihrer App, sodass klar erkennbar ist, wenn sich jemand als Benutzer ausgibt. Die Komponente zeigt einen Rahmen mit einigen Informationen über den imitierten Benutzer sowie eine Schaltfläche zum Stoppen des Identitätswechsels an.

 import { Impersonation } from '@workos-inc/authkit-nextjs' ;

export default function App ( ) {
  return (
    < div >
      < Impersonation / >
      { /* Your app content */ }
    < / div >
  ) ;
}

Holen Sie sich das Zugriffstoken

Manchmal ist es nützlich, das Zugriffstoken direkt zu erhalten, beispielsweise um API-Anfragen an einen anderen Dienst zu stellen.

 import { withAuth } from '@workos-inc/authkit-nextjs' ;

export default async function HomePage ( ) {
  const { accessToken } = await withAuth ( ) ;

  if ( ! accessToken ) {
    return < div > Not signed in < / div > ;
  }

  const serviceData = await fetch ( '/api/path' , {
    headers : {
      Authorization : `Bearer ${ accessToken } ` ,
    } ,
  } ) ;

  return < div > { serviceData } < / div > ;
}

Aktualisierung der Sitzung

Verwenden Sie die Methode refreshSession in einer Serveraktion oder einem Routenhandler, um die neuesten Sitzungsdetails abzurufen, einschließlich aller Änderungen an den Rollen oder Berechtigungen des Benutzers.

Der Parameter organizationId kann an refreshSession übergeben werden, um die Sitzung auf eine andere Organisation umzustellen. Wenn die aktuelle Sitzung nicht für die nächste Organisation autorisiert ist, wird ein entsprechender Authentifizierungsfehler zurückgegeben.

Anmeldepfade

Die Option signUpPaths kann an authkitMiddleware übergeben werden, um Pfade anzugeben, die bei der Umleitung zu AuthKit den Bildschirmhinweis „Anmeldung“ verwenden sollen. Dies ist in Fällen nützlich, in denen Sie möchten, dass ein Pfad, der eine Authentifizierung vorschreibt, als Anmeldeseite behandelt werden soll.

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  signUpPaths : [ '/account/sign-up' , '/dashboard/:path*' ] ,
} ) ;

Debuggen

Um Debug-Protokolle zu aktivieren, initialisieren Sie die Middleware mit aktiviertem Debug-Flag.

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( { debug : true } ) ;

Fehlerbehebung

NEXT_REDIRECT-Fehler bei Verwendung von Try/Catch-Blöcken

Das Einschließen eines withAuth({ ensureSignedIn: true }) Aufrufs in einen try/catch-Block führt zu einem NEXT_REDIRECT Fehler. Dies liegt daran, dass withAuth versucht, den Benutzer zu AuthKit umzuleiten, wenn keine Sitzung erkannt wird und Weiterleitungen in Next außerhalb eines Try/Catch aufgerufen werden müssen.