Zum Inhalt springen

OIDC im Next.js App Router mit Lucia

Symbol einer Person und eines Schlosses auf einem galaktischen Hintergrund als Symbol für sichere persönliche Daten.
«Update Oktober 2024: Lucia wird bis März 2025 deprecated 😱 Für neue Projekte können wir die Library zwar nicht mehr empfehlen, die Konzepte und Patterns sind aber nach wie vor gültig. Statt auf etwas anderes umzusteigen, lohnt es sich, das Session-Handling selbst zu übernehmen, kombiniert mit arctic oder oslo, und dabei die Patterns von lucia zu nutzen.»


Wer ist diese Lucia, von der du da sprichst?!

In diesem Blogpost geht es um OIDC und Session-Handling in einer Next.js-App-Router-Applikation. Ich zeige dir, warum es eine richtig gute Idee ist, Lucia mit einem persistenten Session Storage wie Redis zu kombinieren.

Falls du mit OIDC noch nicht vertraut bist, lies zuerst diesen Blogpost über die Grundlagen von OIDC.

Aber wer ist Lucia?!?! Lucia ist eine kleine, aber mächtige Auth-Library, mit der du ganz einfach Sessions verwaltest und grundlegende OIDC-Flows umsetzt. Und weisst du was? Sie hat eine richtig gute Dokumentation. Und das Beste: Es gibt bereits Beispiele für die Integration mit dem Next.js App Router!

Lucia-Auth-Dokumentation

App-Router-Beispiel auf GitHub

Wozu also noch ein Blogpost, fragst du dich vielleicht?

Die Dokumentation von Lucia ist hervorragend, aber dieser Post geht über die Grundlagen hinaus. Wir behandeln

  • Access Tokens erneuern mit Refresh Tokens
  • Session-Handling für Client Components

Mit diesen fortgeschrittenen Themen kannst du eine robuste, praxistaugliche Authentifizierungslösung umsetzen, die genau auf deine Next.js-Applikation zugeschnitten ist.

PS: Das grundlegende Setup von lucia und oslo behandeln wir nicht. Ich hoffe, du hast die Dokumentation gelesen und verstanden.

Refresh Tokens

Mit dem App Router wandert immer mehr Logik zurück auf den Server. Das gibt dir mehr Kontrolle über Server-side Rendering und Session-Management, heisst aber auch: Eine zuverlässige serverseitige Session ist unverzichtbar.

Aus UX-Sicht ist es entscheidend, dass eine Session so lange wie möglich aktiv bleibt. Läuft sie zu schnell ab, sehen Nutzer*innen nervige Flicker-Effekte: Das UI zeigt kurz einen ausgeloggten Zustand, bevor die erneute Authentifizierung greift. Das stört die User Experience und lässt die App weniger nahtlos wirken.

Genau hier kommen Refresh Tokens ins Spiel. Mit Refresh Tokens kann der Server die Session still und leise erneuern, ohne dass sich jemand neu einloggen muss. Die Nutzer*innen bleiben eingeloggt und die Session wird im Hintergrund verlängert – kein Flackern, keine Unterbrechungen.

So gehst du dabei vor:

1. Erkennen, wann das Access Token bald abläuft:

  • Bevor das Token abläuft, rufst du in der Methode getServerSession eine Methode auf, die das Access Token erneuert. Nennen wir sie refreshAccessToken.

2. Mit dem oslo-Package erneuern:

  • Mit dem oslo-Package bekommst du ein neues Access Token, indem du Folgendes aufrufst
const response = await client.refreshAccessToken(session.refreshToken || "",
      {
        credentials: process.env.OIDC_CLIENT_SECRET,
        authenticateWith: "request_body",
      }
  );
  • Falls beim Refresh ein Fehler auftritt, aktualisiere die Session mit einem Error-Flag und behandle diesen Fall (zum Beispiel mit einem OIDC-Login-Flow mit prompt=none auf der Client-Seite).

3. Session mit den neuen Tokens aktualisieren:

  • Sobald du das neue Access Token hast, musst du die bestehende Session aktualisieren. Mit Lucia ist das ganz einfach:
const updatedSession = await lucia.createSession(
      userId,
      yourUpdatedSession,
      { sessionId: session.id }
    );
  • Wichtig: Verwende dieselbe sessionId wie zuvor. So wird die bestehende Session mit den neuen Tokens aktualisiert, statt dass eine neue entsteht.

Ein vollständigeres Beispiel findest du in unserer Beispiel-App auf GitHub.

«💣 Wichtig 💣: Speichere Session-Daten nicht verschlüsselt in einem Cookie, wie es NextAuth standardmässig tut, wenn du Refresh Tokens verwenden willst! »

Next.js hat Einschränkungen, wenn es darum geht, Cookie-Werte während des Renderings zu aktualisieren. Das kann bei Refresh Tokens zu Problemen führen. Wenn deine App zum Beispiel ein Refresh Token verwendet, das Cookie aber nicht aktualisieren kann, versucht der nächste Request womöglich, das abgelaufene Refresh Token zu nutzen – und es hagelt Fehler.

Um das zu verhindern, speicherst du deine Session-Daten serverseitig in einer zuverlässigen Datenbank wie Redis. So lassen sich deine Refresh Tokens sauber verwalten, ohne dass du auf Cookie-Updates angewiesen bist. Das Ergebnis: ein reibungsloserer und sichererer Authentifizierungs-Flow.

Client-Context für die Session

Damit das Session-Management auch mit Client Components effizient funktioniert, helfen dir die folgenden Strategien bei einer konsistenten und robusten Integration:

1. Mit Context den State zwischen Client und Server synchronisieren:

  • Der SessionContext auf der Client-Seite macht den State in allen Komponenten verfügbar. Sobald der Server die Session aktualisiert (z. B. nach einem erfolgreichen Login oder Token-Refresh), wird auch der Client-Context aktualisiert. So bleiben beide synchron.

2. Mit useOptimistic und useTransition für eine nahtlose UX sorgen:

  • useOptimistic hilft dir, Zwischenzustände zu verwalten, während der Server Änderungen verarbeitet, etwa wenn jemand sein Profil aktualisiert. Das verhindert UI-Flackern und hält das Interface reaktionsschnell. Sobald eine Zustandsänderung angestossen wird, zeigen die optimistischen Updates auf dem Client sie sofort an. Bestätigt der Server die Änderung, wird der finale State abgeglichen.
"use client";
import { useOptimistic, useTransition } from "react";

const RootLayoutProvider = ({
  user, // user inside the session coming from server
  children,
}: PropsWithChildren<Props>) => {
const [sessionUser, setSessioUser] = useOptimistic<User | null>(user);
const [, startTransition] = useTransition();

return (
    <SessionContext.Provider
      value={
        sessionUser
          ? {
              user: sessionUser,
              updateUserSession: (user: DeepPartial<User> | null) => {
                if (user === null) {
                  startTransition(() => {
                    setSessioUser(null);
                  });
                } else {
                  startTransition(() => {
                    setSessioUser(all<User>([sessionUser as any, user]));
                  });
                  updateSession();
                }
              },
            }
          : { user: null, updateUserSession: () => {} }
      }
    >
      {children}
    </SessionContext.Provider>
  );

3. Mit deepmerge die Session effizient aktualisieren:

  • Mit der Library deepmerge lässt sich die Methode updateUserSession elegant nutzen. Damit übergibst du nur die geänderten Werte statt des ganzen Objekts. Zum Beispiel:
const { updateUserSession } = useSession();

updateUserSession({alias: 'my-new-alias'});

4. Einen Validate Session Provider implementieren:

  • Implementiere einen Provider, der regelmässig prüft, ob die Session noch gültig ist, vor allem wenn jemand den Tab wechselt. Dieser Provider kann auch das Access Token erneuern, bevor es abläuft.
useEffect(() => {
  const visibilityHandler = async () => {
    if (document.visibilityState === "visible") {
      setSessionState(await refetchSessionFromServer());
    }
  };
  document.addEventListener("visibilitychange", visibilityHandler, false);
  return () =>
    document.removeEventListener("visibilitychange", visibilityHandler, false);
}, []);
«💣 Wichtig 💣: Stell sicher, dass das Access Token nie in Client Components verfügbar ist.»

Alter, nimm doch einfach next-auth, das ist viel einfacher

Na ja, nicht ganz.NextAuth ist definitiv eine gute Option für schnelle Setups und kleinere Projekte, aber im App Router ist es noch kein First-Class Citizen. Der Session-Context hat einige Einschränkungen, und NextAuth v5 ist seit über einem Jahr in der Beta. Ausserdem gibt dir Lucia beim Datenbankschema und beim Erneuern von Tokens deutlich mehr Flexibilität und Kontrolle.

Wenn du also etwas Anpassbareres brauchst, ist Lucia eine super Wahl. NextAuth ist völlig in Ordnung für kleinere Projekte oder wenn schnell etwas laufen soll. Bei fortgeschritteneren, skalierbaren Lösungen glänzt aber Lucia.

Das vollständige Code-Beispiel auf GitHub

Ein Mann mit Bart und Schnurrbart steht vor einem hellblauen Hintergrund, lächelnd, mit verschränkten Armen, in einem grünen T-Shirt und Jeans.

Geschrieben von
Lorenz Bösch

Next.js|Juli 2024

Ähnliche Challenge auf dem Tisch? Lass uns drüber reden.

Weitere Artikel

© 2026 smartive AG