Next.js OAuth-Login in der Praxis: Google, GitHub und WeChat Schritt für Schritt

Letzte Woche ein Community-Projekt: Der Product Manager sagte: „Füg mal Google-Login hinzu, sollte schnell gehen.“ Dachte ich – Third-Party-Login, ein paar Tutorials gelesen, kein Problem. Stattdessen ein ganzer Nachmittag: redirect_uri-Fehler, Token-Abruf schlägt fehl, rote Meldungen in der Konsole – eine nach der anderen. Am frustrierendsten: Schritt für Schritt die offizielle Doku befolgt, und es lief trotzdem nicht.

Später wurde klar: Das Problem lag nicht im Code, sondern im zu flachen Verständnis des OAuth-Flows. Authorization Code, Access Token, Callback – einzeln verständlich, zusammen verwirrend.

In diesem Artikel erkläre ich OAuth in einfachen Worten – nicht als abstrakte RFC-Beschreibung, sondern mit der Analogie „Paket für jemand anderen abholen“. Sie verstehen, warum Code und Token getrennt sind, was der Callback macht und wo Konfigurationen typischerweise scheitern. Danach richten wir drei Logins ein: Google (internationaler Standard), GitHub (entwicklerfreundlich) und WeChat (im Inland unverzichtbar, aber aufwendig).

Ehrlich gesagt ist WeChat-Login der größte Brocken: wenig hilfreiche Doku, Unternehmensnachweis nötig, lokales Debugging mühsam. Weil man an Inlandsprojekten kaum vorbeikommt, dokumentiere ich die Stolpersteine – inklusive Tunnel für lokale Tests und Custom Provider. Nach dem Lesen sollten Sie mit einer Architektur Login-Anforderungen im In- und Ausland abdecken können.

Was OAuth eigentlich macht

OAuth mit der Paket-Abhol-Analogie

Beim ersten OAuth-Kontakt wirkten Authorization Code und Access Token überwältigend. Die Idee ist simpel: jemand holt ein Paket für Sie ab.

Stellen Sie sich vor: In der Post liegt Ihr Paket (Nutzerdaten), Sie sind im Büro und können nicht selbst hin. Ein Freund (Ihre Next.js-App) bietet an, abzuholen. Die Post gibt nichts an Unbekannte – es braucht Ihre Erlaubnis. Der Ablauf:

1. Sie geben dem Freund einen Abholcode – das ist der authorization code. Nach Klick auf „Mit Google anmelden“ landen Sie auf Googles Seite; nach Zustimmung sendet Google einen temporären code per URL-Parameter an Ihre App.

2. Der Freund geht mit dem Code zur Post – Ihr Backend tauscht den Code gegen einen access token. Die Post prüft, ob der Freund wirklich vertrauenswürdig ist – dafür haben Sie vorher eine „Ausweisnummer“ hinterlegt (client_secret).

3. Nach Prüfung gibt es das Paket – Code und Ausweis stimmen, die Post übergibt das Paket (Nutzerdaten) an den Freund, der es Ihnen weitergibt. Das ist der Abruf mit access_token.

Der Punkt: Der Abholcode ist einmalig und allein wertlos – ohne Ausweis (secret) gibt die Post nichts heraus. Deshalb darf der Code in der Browser-URL stehen, das Secret aber nur im Backend.

Die vier Schritte im Detail

Technisch sieht es so aus:

Schritt 1: Weiterleitung zur OAuth-Autorisierungsseite

Der Nutzer klickt „Mit Google anmelden“, das Frontend leitet zu Google weiter:

https://accounts.google.com/o/oauth2/v2/auth?
  client_id=Ihre_App-ID
  &redirect_uri=http://localhost:3000/api/auth/callback/google
  &response_type=code
  &scope=email profile

Wichtige Parameter:

• client_id: Ihre App-ID bei Google
• redirect_uri: wohin Google nach der Autorisierung zurückschickt
• scope: welche Nutzerdaten Sie anfordern

Schritt 2: Zustimmung und Code

Nach „Zulassen“ leitet Google zurück, die URL sieht etwa so aus:

http://localhost:3000/api/auth/callback/google?code=4/0AfJohXl...&state=random123

Der code ist der Abholcode – kurze Gültigkeit (oft 5–10 Minuten), einmalige Verwendung.

Schritt 3: Backend tauscht Code gegen access_token

Nur das Backend (nicht das Frontend) sendet Code plus client_secret an Google:

const response = await fetch('https://oauth2.googleapis.com/token', {
  method: 'POST',
  body: JSON.stringify({
    code: 'der_erhaltene_code',
    client_id: 'your_client_id',
    client_secret: 'your_secret', // niemals ans Frontend
    redirect_uri: 'http://localhost:3000/api/auth/callback/google',
    grant_type: 'authorization_code'
  })
})

const { access_token } = await response.json()

Der access_token ist der Schlüssel zu Nutzerdaten.

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

Schritt 4: Nutzerprofil abrufen

Mit dem Token rufen Sie die Google-API auf:

const userInfo = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
  headers: {
    Authorization: `Bearer ${access_token}`
  }
})

const user = await userInfo.json()
// { email: "[email protected]", name: "Max", picture: "Avatar-URL" }

Danach legen oder aktualisieren Sie den Nutzer in Ihrer Datenbank, erzeugen eine Session – Login fertig.

Begriffe auf einen Blick

State: Beim Start erzeugen Sie einen Zufallswert (z. B. abc123), speichern ihn in der Session und senden ihn mit. Beim Callback muss derselbe Wert zurückkommen – sonst Abbruch. NextAuth.js erledigt das automatisch.

Warum nicht direkt ein Token in der URL?

Sicherheit.

Die Browser-URL ist lesbar – Verlauf, Server-Logs, Extensions. Ein Token dort wäre ein offener Schlüssel zu Nutzerdaten.

Ein abgefangener Code hilft dem Angreifer wenig:

1. Code ist einmalig
2. Tausch erfordert client_secret (nur Backend)
3. redirect_uri muss passen

Das ist der Authorization Code Flow – sicherste Variante von OAuth 2.0 für Web-Apps mit Backend. Der veraltete Implicit Flow liefert Token direkt in der URL und gilt als unsicher.

NextAuth.js schnell einrichten

Warum NextAuth.js

In Next.js gibt es mehrere Wege – selbst implementieren oder eine Bibliothek. Selbst gebaut: viele Fallstricke; ich bin zu NextAuth.js gewechselt.

Grund 1: etabliert

Offiziell in der Next.js-Doku empfohlen, große Community, v5 unterstützt App Router und Server Components.

Grund 2: 30+ Provider

Google, GitHub, Facebook, Twitter fast plug-and-play. Für WeChat ohne Built-in: Custom Provider, ohne OAuth von Null.

Grund 3: Komplexität ausgelagert

Sessions, JWT-Signatur, DB-Speicher, CSRF – automatisch. Sie konzentrieren sich auf Business-Logik (z. B. Willkommens-Mail beim ersten Login).

Kernkonfiguration

Zentrale API-Route im App Router:

app/api/auth/[...nextauth]/route.ts

[...nextauth] ist ein Catch-all für /api/auth/*, u. a.:

• /api/auth/signin – Anmeldeseite
• /api/auth/callback/google – Google-Callback
• /api/auth/signout – Abmelden
• /api/auth/session – aktuelle Session

Basis:

// app/api/auth/[...nextauth]/route.ts
import NextAuth from "next-auth"
import GoogleProvider from "next-auth/providers/google"
import GitHubProvider from "next-auth/providers/github"

export const authOptions = {
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
    GitHubProvider({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!,
    }),
  ],
  pages: {
    signIn: '/login',
  },
  callbacks: {
    async signIn({ user, account, profile }) {
      return true // false blockiert Login
    },
    async session({ session, token }) {
      session.user.id = token.sub
      return session
    },
  },
}

const handler = NextAuth(authOptions)
export { handler as GET, handler as POST }

export { handler as GET, handler as POST } ist im App Router Pflicht.

Umgebungsvariablen

Pflicht (Beispiel .env.local):

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here
# v5 alternativ
AUTH_SECRET=your-secret-key-here

# Google
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
# v5: AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET

# GitHub
GITHUB_ID=your-github-client-id
GITHUB_SECRET=your-github-client-secret
# v5: AUTH_GITHUB_ID / AUTH_GITHUB_SECRET

Hinweise:

1. NEXTAUTH_URL: vollständige App-URL – lokal http://localhost:3000, Produktion mit https.

2. NEXTAUTH_SECRET / AUTH_SECRET: JWT-Signatur, zufällig erzeugen:

openssl rand -base64 32

Nicht committen; bei Leak sofort rotieren.

3. AUTH_-Präfix (v5): AUTH_PROVIDER_ID und AUTH_PROVIDER_SECRET werden automatisch erkannt.

Installation – Minimalsetup

Schritt 1: Installieren

npm install next-auth
# oder
pnpm add next-auth

Schritt 2: app/api/auth/[...nextauth]/route.ts anlegen (Code oben).

Schritt 3: .env.local

NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=<Ausgabe von openssl rand -base64 32>

Schritt 4: Login-Buttons

// app/login/page.tsx
'use client'

import { signIn } from 'next-auth/react'

export default function LoginPage() {
  return (
    <div>
      <button onClick={() => signIn('google')}>
        Mit Google anmelden
      </button>
      <button onClick={() => signIn('github')}>
        Mit GitHub anmelden
      </button>
    </div>
  )
}

Schritt 5: SessionProvider

// app/layout.tsx
import { SessionProvider } from 'next-auth/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SessionProvider>
          {children}
        </SessionProvider>
      </body>
    </html>
  )
}

Ohne OAuth-Apps bei Google/GitHub schlagen Klicks noch fehl – das folgt unten.

Google-Login einrichten

Google Cloud Console

Zwei Teile: OAuth-App in der Console, Anbindung in Next.js.

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

Schritt 1: https://console.cloud.google.com – ggf. neues Projekt, z. B. „Mein Blog“.

Schritt 2: „APIs & Services“ → „Library“, „Google+ API“ suchen und aktivieren (historischer Name, OAuth nutzt ihn noch).

Schritt 3: „Credentials“ → „Create Credentials“ → „OAuth client ID“. Beim ersten Mal: OAuth consent screen (Name, Support-E-Mail). Application type: Web application.

Schritt 4: Redirect URIs (kritisch)

Authorized redirect URIs, z. B.:

Entwicklung:

http://localhost:3000/api/auth/callback/google

Produktion (nach Deploy):

https://yourdomain.com/api/auth/callback/google

Details:

• http lokal, Produktion nur https
• Port muss stimmen (3001 → localhost:3001)
• Pfad exakt /api/auth/callback/google
• keine Query-Parameter in der Konfiguration

Nach „Create“ Client ID und Secret kopieren.

Schritt 5: .env.local

GOOGLE_CLIENT_ID=Ihre_Client_ID.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxx

Next.js-Integration

Optional erweitern:

GoogleProvider({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  authorization: {
    params: {
      prompt: "consent",
      access_type: "offline",
      response_type: "code"
    }
  }
}),

• prompt: "consent": jedes Mal Consent-Screen (gut zum Testen)
• access_type: "offline": Refresh Token
• response_type: "code": Authorization Code Flow

Testen

npm run dev

http://localhost:3000/login → „Mit Google anmelden“ → nach Zustimmung Redirect zurück.

Server:

import { getServerSession } from "next-auth"
import { authOptions } from "./api/auth/[...nextauth]/route"

export default async function Home() {
  const session = await getServerSession(authOptions)
  if (session) {
    return <div>Hallo, {session.user?.name}</div>
  }
  return <div>Nicht angemeldet</div>
}

Client:

'use client'
import { useSession } from "next-auth/react"

export default function Profile() {
  const { data: session, status } = useSession()
  if (status === "loading") return <div>Laden…</div>
  if (!session) return <div>Nicht angemeldet</div>
  return (
    <div>
      <img src={session.user?.image} alt="Avatar" />
      <p>{session.user?.name}</p>
      <p>{session.user?.email}</p>
    </div>
  )
}

Typische Fehler

Fehler 1: redirect_uri_mismatch

Error 400: redirect_uri_mismatch

Die URI in der Console muss exakt der im Request entsprechen.

Vorgehen: DevTools → Network → Login-Klick → redirect_uri in der Google-URL kopieren → 1:1 in Authorized redirect URIs eintragen (Protokoll, Port, Pfad, keine Extra-Slashes).

Fehler 2: Access blocked: This app’s request is invalid

OAuth consent screen fehlt oder Testnutzer nicht gesetzt → „OAuth consent screen“ konfigurieren, bei External unveröffentlicht Testnutzer-E-Mail hinzufügen.

Fehler 3: Port

App auf 3001, URI nur 3000 → Port angleichen oder mehrere URIs eintragen.

Fehler 4: HTTPS in Produktion

Google verlangt HTTPS in Produktion – Vercel/Netlify liefern das mit.

GitHub-Login

GitHub OAuth App

Einfacher als Google – keine separate API-Aktivierung.

Schritt 1: GitHub → Avatar → Settings → Developer settings → OAuth Apps → New OAuth App.

Schritt 2:

• Application name: beliebig
• Homepage URL: http://localhost:3000 (Produktion: Ihre Domain)
• Authorization callback URL: http://localhost:3000/api/auth/callback/github

GitHub ist bei Callback-URLs etwas flexibler als Google.

Vultr - Hochleistungs-NVMe-Cloud-Server mit 32 Standorten weltweit, Docker per Klick

Preise ansehen →Anzeige

Client ID notieren, „Generate a new client secret“ (einmal sichtbar).

Schritt 3: .env.local

GITHUB_ID=Ihre_Client_ID
GITHUB_SECRET=Ihr_Client_Secret

Next.js

GitHubProvider({
  clientId: process.env.GITHUB_ID!,
  clientSecret: process.env.GITHUB_SECRET!,
}),

Google vs. GitHub

GitHub-E-Mail kann null sein (Privatsphäre). Im Code absichern:

const userEmail = session.user?.email || 'E-Mail nicht angegeben'

WeChat-Login (Inlands-Szenario)

Drei WeChat-Varianten

Hier: Open Platform Web-Login für eine standalone Next.js-Site.

Open Platform (hohe Hürde)

Voraussetzungen: Gewerbeanmeldung, ICP-Domain, HTTPS.

Schritt 1: https://open.weixin.qq.com – „Website Application Developer“, Gewerbeschein, Prüfung (1–2 Werktage).

Schritt 2: Website-App anlegen – Name, Beschreibung, Domain (ICP). Authorized callback domain: nur Domain, z. B. yourdomain.com (ohne Protokoll/Pfad).

Prüfung 1–7 Tage, dann AppID und AppSecret.

Schritt 3:

WECHAT_APP_ID=Ihre_AppID
WECHAT_APP_SECRET=Ihr_AppSecret

Custom Provider in NextAuth.js

const WeChatProvider = {
  id: "wechat",
  name: "WeChat",
  type: "oauth",
  authorization: {
    url: "https://open.weixin.qq.com/connect/qrconnect",
    params: {
      appid: process.env.WECHAT_APP_ID,
      scope: "snsapi_login",
      response_type: "code",
    },
  },
  token: {
    url: "https://api.weixin.qq.com/sns/oauth2/access_token",
    async request({ params, provider }) {
      const response = await fetch(
        `https://api.weixin.qq.com/sns/oauth2/access_token?appid=${process.env.WECHAT_APP_ID}&secret=${process.env.WECHAT_APP_SECRET}&code=${params.code}&grant_type=authorization_code`
      )
      const tokens = await response.json()
      return { tokens }
    },
  },
  userinfo: {
    url: "https://api.weixin.qq.com/sns/userinfo",
    async request({ tokens }) {
      const response = await fetch(
        `https://api.weixin.qq.com/sns/userinfo?access_token=${tokens.access_token}&openid=${tokens.openid}`
      )
      return await response.json()
    },
  },
  profile(profile) {
    return {
      id: profile.unionid || profile.openid,
      name: profile.nickname,
      email: null,
      image: profile.headimgurl,
    }
  },
}

export const authOptions = {
  providers: [WeChatProvider, /* … */],
}

Lokales Debugging

WeChat verlangt HTTPS und registrierte Domain.

Option 1: Tunnel (empfohlen)

ngrok http 3000
# oder cpolar (Inland oft stabiler)
cpolar http 3000

Temporäre URL z. B. https://abc123.ngrok.io als Callback-Domain in der Open Platform.

Option 2: Sandbox

https://mp.weixin.qq.com/debug/cgi-bin/sandbox – Test-AppID/Secret, mit Tunnel-Domain. Nur für eigene Tests.

Besonderheiten WeChat

openid vs. unionid: openid pro App; unionid über Apps einer Open-Platform-ID – für eindeutige Nutzer-ID unionid bevorzugen, sonst openid.

Keine E-Mail: email bleibt null – ggf. nachträglich abfragen.

Kurze Token-Lebensdauer: ca. 2 Stunden, begrenzte Refreshes – Refresh-Logik planen.

Zusammenfassung

Vom OAuth-Prinzip bis Google, GitHub und WeChat – ein durchgängiger Third-Party-Login-Weg.

Kernpunkte:

• Code und Token getrennt aus Sicherheitsgründen; Secret nur im Backend
• NextAuth.js übernimmt Session, CSRF und mehr
• Google: strikte redirect URIs; GitHub: einfacher; WeChat: höchste Hürde, im Inland oft nötig
• WeChat: Unternehmen + ICP; lokal Tunnel + Sandbox

Praxis:

• openssl rand -base64 32 für NEXTAUTH_SECRET
• Mehrere Ports in Google Console eintragen
• GitHub-E-Mail kann fehlen
• unionid für appübergreifende Identität

Schwierig ist oft nicht der Code, sondern OAuth-Design und Plattform-Unterschiede. Wenn Sie beim nächsten „Google-Login einbauen“ weniger Stunden in der Konsole verbringen – Ziel erreicht.