Authentifizierung von Nutzern für Nuxt Anwendungen mit KeycloakNuxt & Keycloak: Anleitung zur einfachen Integration für SSR

Die Integration von Keycloak in eine Nuxt-Anwendung für eine robuste Authentifizierung kann eine Herausforderung sein, besonders im Hinblick auf Server-Side Rendering (SSR). In diesem Artikel vergleichen wir zwei führende Module, nuxt-auth-utils und @sidebase/nuxt-auth, und bieten eine schrittweise Anleitung, um Ihnen bei der Auswahl der richtigen Lösung zu helfen.

SSR, Hybrid, Generate - Authentifizierung je Modus

Als erstes ist es wichtig zu identifizieren, in welchem Modus die Nuxt Applikation betrieben wird. Hieraus ergeben sich unterschiedliche Anforderungen an die Authentifizierung. Einen Blogartikel zu den unterschiedlichen Modi gibt’s hier.

Server-Side Rendering - Werden während des Server-Side Renderings Nutzer-Informationen verarbeitet wie Berechtigungen, Namen o.ä. - so benötigt der Nitro Server Zugriff auf diese. Entsprechend muss der Nitro/Nuxt Server validieren können ob eine Session authentifiziert bzw. autorisiert ist.

Client-Side Rendering - Es existiert keine Server-Logik. Alles wird auf der Client-Seite (dem Browser) verarbeitet - entsprechend läuft auch das Handling der Nutzer-Informationen/Session lediglich client-seitig.

Hybrid-Rendering - Je nach dem, ob die SSR Routen Nutzer-Session-Informationen benötigen oder nicht, muss die Keycloak Integration mitgedacht werden.

Option 1: Integration mit nuxt-auth-utils - New and improved

Die Integration von Keycloak und Nuxt durch nuxt-auth-utils könnte kaum einfacher sein. Ein wenig Konfiguration in der nuxt.config.js und schon steht das Grundgerüst:

runtimeConfig: {
    oauth: {
      keycloak: {
        serverUrl: 'https://keycloak.blueshoe.de',
        realm: 'Blueshoe',
        clientId: 'blueshoe-website',
        // clientSecret: '',
        redirectURL: 'https://blueshoe.de/auth/keycloak',
      },
    },
  },
  modules: [
    'nuxt-auth-utils',
  ]

Nun stehen komfortable Composables zur Verfügung:

const { loggedIn, user, session, fetch, clear, openInPopup } = useUserSession()

Mit den Informationen lassen sich schnell und einfach nutzerspezifische Informationen rendern:

<template>
  <span v-if="loggedIn">Hallo, {{ user.firstName }} {{ user.lastName }}span>
  <span v-else>Hallo Gastspan>
template>

Ebenso stehen auf SSR Seite nützliche Utils zur Verfügung. Benötigt eine Route zwingend eine gültige User-Session lässt sich dies einfach mit dem folgenden Composable realisieren:

const session = await requireUserSession(event)

Soweit so gut - doch wie funktioniert der Login?

Durch die Umgebungsvariablen hat das Modul nuxt-auth-utils alle Informationen zur Verfügung um die Login Weiterleitung zu Erzeugen und im Redirect (zurück) auf die Nuxt Applikation die Session zu verwenden.

💡 Hinweis: Die runtimeConfig ist selbst keine Umgebungsvariable, sondern die Art, wie Nuxt den Zugang zu Umgebungsvariablen ermöglicht. Mehr dazu in der Nuxt Dokumentation.

Hierfür wird einfach eine serverseitige Route erzeugt - unter server/auth/keycloak.get.ts :

export default defineOAuthKeycloakEventHandler({
  async onSuccess(event, { user }) {
    await setUserSession(event, {
      user: {
        keycloak: user.preferred_username,
      },
      loggedInAt: Date.now(),
    })

    return sendRedirect(event, '/')
  },
})

Ruft man nun /auth/keycloak/ auf - so wird man automatisch auf die laufende Keycloak Instanz weitergeleitet und erhält nach erfolgreichem Login eine Session.

Das Modul ist von Sébastien Chopin - dem Autor von Nuxt persönlich und hat mit (Stand Sep 2025) 95.000 Downloads pro Monat, regelmäßigen Updates sowie 1.400 Stargazern ein solides Standing und kann guten Gewissens empfohlen werden.

Option 2: Integration mit @sidebase/nuxt-auth - Battle-tested und einsatzbereit

Eine weitere Möglichkeit Nuxt und Keycloak zusammenzubringen ist das Paket @sidebase/nuxt-auth. Mit ein paar Anpassungen in der nuxt.config.js lässt sich das Modul einfach konfigurieren:

runtimeConfig: {
    public: {
      authOrigin: 'http://localhost:3000',
    },
  },

  modules: [
    '@sidebase/nuxt-auth',
  ],

  auth: {
    isEnabled: true,
    disableServerSideAuth: false,
    provider: {
      type: 'authjs',
      trustHost: false,
      defaultProvider: 'keycloak',
      addDefaultCallbackUrl: true,
    },
    sessionRefresh: {
      enablePeriodically: true,
      enableOnWindowFocus: true,
    },
  },

Wie die Konfiguration schon zeigt kümmert sich @sidebase/nuxt-auth selbstständig darum die Session zu aktualisieren. Keycloak existiert als vorgefertigter Provider. Wir legen folgende Datei an server/api/auth/[...].ts und konfigurieren den Provider:

import KeycloakProvider from 'next-auth/providers/keycloak'
import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  secret: 'your-secret-here',
  providers: [
    KeycloakProvider.default({
      clientId: process.env.KEYCLOAK_ID,
      clientSecret: process.env.KEYCLOAK_SECRET,
      issuer: process.env.KEYCLOAK_ISSUER,
    })
  ]
})

Hier gilt es zu beachten, dass als Issuer die URL zum Keycloak Realm angegeben werden muss: https://my-keycloak-domain.com/realms/My_Realm.

Zusätzlich lassen sich Callbacks definieren, um auf verschiedene Events zu reagieren:

export default NuxtAuthHandler({
    ...
    callbacks: {
        /* on before signin */
        async signIn({ user, account, profile, email, credentials }) {
          return true
        },
        /* on redirect to another url */
        async redirect({ url, baseUrl }) {
          return baseUrl
        },
        /* on session retrieval */
        async session({ session, user, token }) {
          return session
        },
        /* on JWT token creation or mutation */
        async jwt({ token, user, account, profile, isNewUser }) {
          return token
        }
      }
})

@sidebase/nuxt-auth erzeugt selbstständig eine Seite, die den Login zur Verfügung stellt und mit den gegebenen Providern integriert.

Die Daten des Nutzers stehen dann wie folgt in der Applikation bereit:

<script setup>
const {
  status,
  data,
  lastRefreshedAt,
  getCsrfToken,
  getProviders,
  getSession,
  signIn,
  signOut
} = useAuth()
script>

Der Status gibt an, ob der Nutzer authentifiziert ist, oder nicht. data beinhaltet nutzerspezifische Daten.

Das Modul ist SSR kompatibel und erlaubt es basierend auf der Session unterschiedliche Informationen zu rendern.

@sidebase/nuxt-auth wird von der sidebase entwickelt und hat sich als zuverlässige Lösung für Authentifizierung in Nuxt-Anwendungen etabliert. Mit einer gut situierten Firma im Rücken und regelmäßigen Updates bietet es eine solide Grundlage für produktive Anwendungen und kann guten Gewissens empfohlen werden.

Fazit: nuxt-auth-utils oder @sidebase/nuxt

Wie so oft steckt der Teufel im Anwendungsfall. 😉 Beide Module haben einen guten Track-Record bezüglich Weiterentwicklung, die Integration ist einfach und die Composables sind sehr gut.

Möchte man die typischen Authentifizierungsseiten selbst überarbeiten, eignet sich @sidebase/nuxt-auth besser. Auch kommt das Modul mit einer konfigurierbaren einfachen Refresh-Logik für die User Session. nuxt-auth-utils hingegen "fühlt" sich etwas leichtgewichtiger an. Eine Anfrage für automatischen Session-Refresh steht aktuell noch aus. Diese lässt sich i.d.R. aber einfach selbständig nachrüsten.

Wir können beide Module wärmstens empfehlen und freuen uns auf Feedback zu den Erfahrungen mit Nuxt und Keycloak in den Kommentaren!

Wie habt ihr Nuxt und Keycloak "zusammengesteckt"? Gibt es bessere Wege? Was sind eure Erfahrungen mit den Modulen?