OIDC im Next.js App Router mit Lucia

«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!
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
getServerSessioneine Methode auf, die das Access Token erneuert. Nennen wir sierefreshAccessToken.
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=noneauf 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
sessionIdwie 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
SessionContextauf 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:
useOptimistichilft 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
updateUserSessionelegant 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.

Geschrieben von
Lorenz Bösch
Ähnliche Challenge auf dem Tisch? Lass uns drüber reden.





