---
title: "Nuxt & Keycloak: Anleitung zur einfachen Integration für SSR"
description: "✅ Anleitung zur Integration von Keycloak in Nuxt.js. Wir vergleichen nuxt-auth-utils und @sidebase/nuxt-auth, zeigen Code-Beispiele und erklären die Unterschiede für SSR, Hybrid- und Static-Rendering, um die beste Authentifizierungslösung für Ihr Projekt zu finden."
canonical_url: "https://www.blueshoe.de/blog/nuxt-keycloak-integration/"
---

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.

![Nuxt und Keycloak](/img/blogs/nuxtkeycloak.svg)

<global-blog-level-info>

- [Keycloak](https://www.keycloak.org/) und [OAuth2](https://en.wikipedia.org/wiki/OAuth)
- [Nuxt Rendering Modes](https://nuxt.com/docs/4.x/guide/concepts/rendering)

Solltest du Fragen haben, oder dir etwas unklar sein, kannst du die Kommentarfunktion unter dem Artikel nutzen.

</global-blog-level-info>

## 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](/blog/nuxt-generate-vs-server/).

**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`](https://github.com/atinux/nuxt-auth-utils) könnte kaum einfacher sein. Ein wenig Konfiguration in der `nuxt.config.js` und schon steht das Grundgerüst:

```json
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](https://github.com/atinux/nuxt-auth-utils/?tab=readme-ov-file#user-session) zur Verfügung:

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

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

```vue
<template>
  <span v-if="loggedIn">Hallo, {{ user.firstName }} {{ user.lastName }}</span>
  <span v-else>Hallo Gast</span>
</template>
```

Ebenso stehen auf SSR Seite [nützliche Utils zur Verfügung](https://github.com/atinux/nuxt-auth-utils/?tab=readme-ov-file#session-management). Benötigt eine Route zwingend eine gültige User-Session lässt sich dies einfach mit dem folgenden Composable realisieren:

```javascript
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](https://nuxt.com/docs/4.x/guide/going-further/runtime-config#environment-variables).

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

```javascript
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](https://github.com/atinux) - 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:

```json
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:

```javascript
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](https://my-keycloak-domain.com/realms/My_Realm).

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

```javascript
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:

```vue
<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](https://sidebase.io/) 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](https://github.com/atinux/nuxt-auth-utils/issues/356) 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?

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.