Next.js OAuth-Anmeldung: Google, GitHub, WeChat – Konfiguration und Best Practices

Auf „Mit Google anmelden“ klicken, zur Google-Seite springen, autorisieren, zurückkehren – und schon sind Sie eingeloggt.

Diesen Ablauf kennen Sie vermutlich auswendig. Beim eigenen Projekt stellt man sich plötzlich Fragen: Warum zweimal weiterleiten? Was ist eine Callback-URL? Was bedeutet redirect_uri_mismatch? Lokal läuft alles, nach dem Deployment bricht es zusammen?

Beim ersten OAuth-Setup habe ich Doku gelesen, bis mir schwindelig wurde – Autorisierungscode, access_token, client_secret überall. Zwei Tage und unzählige Fehler später war das Bild klarer.

In diesem Artikel erkläre ich OAuth-Login in einfachen Worten: wie es wirklich funktioniert und wie Sie Google-, GitHub- und WeChat-Login in Next.js einrichten. Am Ende ist es weniger mysteriös, als es wirkt.

Was ist OAuth 2.0? (In einfachen Worten)

Zuerst ein Alltagsbeispiel

Stellen Sie sich vor, Sie wohnen in einer Wohnsiedlung und bestellen online etwas zur Lieferung nach Hause. Problem: Die Siedlung hat Zugangskontrolle, der Kurier kommt nicht rein.

Klassisch würden Sie dem Kurier Ihre Zugangskarte geben. Riskant – er könnte später jederzeit eintreten.

Besser: Sie melden sich beim Pförtner und sagen „Ich erwarte ein Paket“. Der Pförtner stellt dem Kurier einen Kurzzeit-Ausweis aus: „Nur heute 14–16 Uhr, nur Gebäude A.“ Nach der Lieferung ist der Ausweis ungültig.

Das ist die Kernidee von OAuth.

In diesem Bild:

• Sie = Nutzer (will sich anmelden)
• Kurier = Drittanbieter-App (Ihre Website)
• Pförtner = OAuth-Provider (Google, WeChat, GitHub usw.)
• Zugangskarte = Ihr Passwort (nicht weitergeben)
• Kurzzeit-Ausweis = access_token (zeitlich und in Rechten begrenzt)

Sie geben kein Passwort an die Drittanbieter-App, sondern autorisieren sie, beim OAuth-Provider einen „Kurzzeit-Ausweis“ abzuholen.

Der OAuth-Ablauf in fünf Schritten (Authorization Code Flow)

Übertragen auf Next.js OAuth-Login:

Schritt 1: Der Nutzer klickt auf „Mit Google anmelden“.

Schritt 2: Ihre Website leitet zu Googles Autorisierungsseite weiter, URL etwa so:

https://accounts.google.com/o/oauth2/auth?
  client_id=Ihre_App_ID
  &redirect_uri=http://localhost:3000/api/auth/callback/google
  &response_type=code
  &scope=openid email profile
  &state=Zufallsstring

Ihre App sagt Google: „Ich bin App X (client_id), der Nutzer will sich mit eurem Konto anmelden – bitte bestätigen lassen. Danach bitte an diese Adresse zurück (redirect_uri).“

Schritt 3: Der Nutzer sieht „App X möchte auf Ihre Basisdaten zugreifen“ und klickt „Zulassen“.

Schritt 4: Google leitet zurück zu redirect_uri und hängt einen Autorisierungscode (code) an:

http://localhost:3000/api/auth/callback/google?code=ABCD1234&state=Zufallsstring

Der code ist nur ein Beleg, kein endgültiger Ausweis. Er läuft schnell ab (meist ~10 Minuten) und gilt einmal.

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

Schritt 5: Ihr Backend tauscht code plus client_secret bei Google gegen ein echtes access_token:

// Backend-Code (vereinfacht)
const response = await fetch('https://oauth2.googleapis.com/token', {
  method: 'POST',
  body: JSON.stringify({
    code: 'ABCD1234',
    client_id: 'Ihre_App_ID',
    client_secret: 'Ihr_App_Secret',
    redirect_uri: 'http://localhost:3000/api/auth/callback/google',
    grant_type: 'authorization_code',
  }),
})

const { access_token } = await response.json()

Mit access_token holt Ihre App Nutzerdaten (E-Mail, Avatar, Name) von Google.

Schritt 6 (optional): Nutzerinfos mit access_token abrufen:

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

Danach weiß Ihre App, wer der Nutzer ist – Session anlegen, Login abgeschlossen.

Wichtige Begriffe in einfachen Worten

• client_id: Die „Ausweisnummer“ Ihrer App bei Google. Darf öffentlich sein.

• client_secret: Das „Passwort“ Ihrer App. Niemals leaken – nur serverseitig. Mit Ihrem client_secret könnte jemand Ihre App imitieren.

• redirect_uri: Wohin Google nach erfolgreicher Autorisierung zurückleitet. Muss in der Google Cloud Console registriert sein – Google prüft strikt, ein extra Schrägstrich reicht für redirect_uri_mismatch.

• state: Zufallsstring gegen CSRF. Sie senden state mit, Google gibt ihn zurück – stimmt er nicht, könnte die Anfrage gefälscht sein.

• code: Kurzlebiger Autorisierungscode (~10 Minuten, einmal nutzbar). Beweist: Der Nutzer hat bei Google zugestimmt.

• access_token: Der echte „Ausweis“. Damit holt Ihre App Nutzerdaten. Laufzeit oft 1 Stunde bis wenige Tage.

Warum code und access_token getrennt?

Der code kommt per Browser-Redirect (Frontend sichtbar), access_token per Server-zu-Server (Frontend unsichtbar). Direktes access_token in der URL wäre riskant (Verlauf, Logs, Monitoring). Der Tausch braucht client_secret – nur im Backend.

Next.js + NextAuth.js: Google-Login (einfacher Einstieg)

Warum NextAuth.js?

OAuth selbst bauen ist mühsam: Callbacks, Sessions, CSRF, Token-Speicher – viele Details.

NextAuth.js (heute Auth.js v5) übernimmt das: 15k+ Stars, 50+ Provider, App Router ab Next.js 14. Grob 80 % weniger Boilerplate.

Schritt 1: App in Google Cloud anlegen

Vor dem Code brauchen Sie client_id und client_secret.

1. Google Cloud Console öffnen und anmelden.

2. Falls nötig, ein Projekt anlegen (Name beliebig, z. B. „My Next.js App“).

3. Links: „APIs & Dienste“ → „Anmeldedaten“ (Credentials).

4. „Anmeldedaten erstellen“ → „OAuth-Client-ID“.

5. Beim ersten Mal ggf. „OAuth-Zustimmungsbildschirm“ – App-Name, Support-E-Mail; „Extern“, Testphase ohne Review.

6. OAuth-Client-ID: Typ „Webanwendung“.

7. Wichtig – „Autorisierte Weiterleitungs-URIs“:

   • Lokal: http://localhost:3000/api/auth/callback/google
   • Produktion (später): https://yourdomain.com/api/auth/callback/google

   Muss exakt zum Code passen – Schrägstrich zu viel oder zu wenig → redirect_uri_mismatch.

8. Erstellen – Client ID und Client Secret kopieren.

Schritt 2: NextAuth.js installieren und Umgebungsvariablen

npm install next-auth@beta

@beta = v5.

.env.local im Projektroot:

GOOGLE_CLIENT_ID=Ihre_Client_ID.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=Ihr_Client_Secret
NEXTAUTH_SECRET=Zufallsstring
NEXTAUTH_URL=http://localhost:3000

NEXTAUTH_SECRET generieren:

openssl rand -base64 32

In Produktion NEXTAUTH_URL auf Ihre Domain setzen.

Schritt 3: NextAuth-Konfiguration

Datei app/api/auth/[...nextauth]/route.ts (Pages Router: pages/api/auth/[...nextauth].ts):

import NextAuth from "next-auth"
import GoogleProvider from "next-auth/providers/google"

export const authOptions = {
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
  callbacks: {
    async signIn({ user, account, profile }) {
      // Nach erfolgreichem Login – Nutzer in DB speichern
      console.log("Benutzer angemeldet:", user)
      return true // true = Login erlauben
    },
    async session({ session, token }) {
      // Session anpassen
      if (session.user) {
        session.user.id = token.sub // User-ID in Session
      }
      return session
    },
  },
}

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

NextAuth.js übernimmt den OAuth-Flow. /api/auth/callback/google entsteht automatisch.

Schritt 4: Login-Button

'use client' // App Router: Client-Komponente

import { signIn, signOut, useSession } from "next-auth/react"

export default function LoginButton() {
  const { data: session } = useSession()

  if (session) {
    // Bereits eingeloggt
    return (
      <div>
        <p>Willkommen, {session.user?.name}</p>
        <img src={session.user?.image || ''} alt="Profilbild" />
        <button onClick={() => signOut()}>Abmelden</button>
      </div>
    )
  }

  // Nicht eingeloggt
  return <button onClick={() => signIn('google')}>Mit Google anmelden</button>
}

signIn('google') → Google → zurück → eingeloggt.

Schritt 5: SessionProvider im Root-Layout

Damit useSession überall funktioniert:

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

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

Fertig – Google-Login in Next.js.

Häufige Probleme

Problem 1: redirect_uri_mismatch

Sehr häufig beim ersten Setup.

Meldung etwa: Error 400: redirect_uri_mismatch

Ursache: Callback in Google Cloud passt nicht zur tatsächlichen Anfrage.

Lösung:

1. „Autorisierte Weiterleitungs-URIs“ = http://localhost:3000/api/auth/callback/google (kein extra Schrägstrich)
2. .env.local: NEXTAUTH_URL=http://localhost:3000
3. Anderer Port (z. B. 3001) → überall anpassen

Problem 2: Lokal OK, nach Deployment Fehler

Oft fehlende Produktions-Umgebungsvariablen.

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Lösung:

1. In Google Cloud Produktions-URI: https://yourdomain.com/api/auth/callback/google
2. Auf Vercel o. ä.: NEXTAUTH_URL=https://yourdomain.com
3. Neu deployen

Problem 3: session ist null nach Login

Root-Layout ohne <SessionProvider>?

Problem 4: TypeError: Cannot read property ‘user’ of null

Session noch am Laden – schon session.user gelesen.

Lösung:

const { data: session, status } = useSession()

if (status === 'loading') {
  return <div>Lädt...</div>
}

if (!session) {
  return <div>Nicht angemeldet</div>
}

// Jetzt session.user sicher nutzen

GitHub-Login (Unterschiede verstehen)

Mit Google-Erfahrung ist GitHub schneller – es gibt aber Nuancen.

GitHub vs. Google OAuth

Gleich: OAuth 2.0 Authorization Code, gleicher Ablauf.

Unterschiede:

1. Feinere scopes: GitHub braucht für private E-Mails extra user:email.
2. Callback lockerer: Google will volle URL, GitHub oft nur Domain.
3. App-Typen: Persönliches Konto oder Organisation.

Schritt 1: OAuth App auf GitHub

1. GitHub → Avatar → Settings → „Developer settings“.

2. „OAuth Apps“ → „New OAuth App“.

3. Angaben:

   • Application name: sichtbar bei Autorisierung
   • Homepage URL: z. B. http://localhost:3000
   • Authorization callback URL: http://localhost:3000/api/auth/callback/github

4. „Register application“ → „Generate a new client secret“ → ID und Secret kopieren.

Schritt 2: Umgebungsvariablen

GITHUB_CLIENT_ID=Ihre_GitHub_Client_ID
GITHUB_CLIENT_SECRET=Ihr_GitHub_Client_Secret

Schritt 3: NextAuth erweitern

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_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
      // Private E-Mail: scope erweitern
      authorization: {
        params: {
          scope: 'read:user user:email'
        }
      }
    }),
  ],
  callbacks: {
    // ... wie zuvor
  },
}

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

Schritt 4: Login-Buttons

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

scopes (Berechtigungen)

• read:user: öffentliche und private Profildaten
• user:email: E-Mails inkl. privat
• public_repo: öffentliche Repos
• repo: alle Repos (vorsichtig)

Für Login reicht read:user user:email.

Ohne user:email nur öffentliche E-Mail – versteckte E-Mail → session.user.email null.

Fallstrick: Keine öffentliche E-Mail auf GitHub

Anders als Google (E-Mail Pflicht) kann GitHub E-Mail verbergen. Bei Pflicht-E-Mail im signIn-Callback prüfen:

async signIn({ user, account }) {
  if (account?.provider === 'github' && !user.email) {
    // Keine E-Mail – Login ablehnen oder Hinweis
    console.log("GitHub-Nutzer ohne E-Mail")
    return false // Login verweigern
  }
  return true
}

WeChat-Login (besondere Anforderungen)

WeChat ist aufwendiger als Google/GitHub – anderes Ökosystem.

Warum WeChat anders ist

1. QR-Code: PC-Login per Handy-Scan, nicht nur Klick wie bei Google/GitHub.
2. Kein eingebauter NextAuth-Provider: Custom Provider nötig.
3. Strenge Callback-Regeln: Domain mit ICP, kein localhost – lokales Debuggen schwierig.
4. openid und unionid: openid pro App unterschiedlich; unionid für mehrere Apps.

Schritt 1: WeChat Open Platform

1. WeChat Open Platform – Konto registrieren.

2. „Website-App“ anlegen (nicht Official Account oder Mini Program).

3. Infos, Screenshots, Review (1–3 Werktage).

4. AppID und AppSecret (entspricht client_id/client_secret).

5. Autorisierte Callback-Domain (nur Domain, z. B. yourdomain.com).

Schritt 2: Custom WeChat Provider

lib/wechat-provider.ts:

import type { OAuthConfig, OAuthUserConfig } from "next-auth/providers"

export interface WeChatProfile {
  openid: string
  nickname: string
  headimgurl: string
  sex: number
  province: string
  city: string
  country: string
  unionid?: string
}

export default function WeChatProvider<P extends WeChatProfile>(
  options: OAuthUserConfig<P>
): OAuthConfig<P> {
  return {
    id: "wechat",
    name: "WeChat",
    type: "oauth",
    
    // WeChat-Autorisierung (PC-Website)
    authorization: {
      url: "https://open.weixin.qq.com/connect/qrconnect",
      params: {
        scope: "snsapi_login",
        appid: options.clientId,
        response_type: "code",
      },
    },
    
    // Code gegen access_token
    token: {
      url: "https://api.weixin.qq.com/sns/oauth2/access_token",
      params: {
        appid: options.clientId,
        secret: options.clientSecret,
        grant_type: "authorization_code",
      },
    },
    
    // Nutzerinfos
    userinfo: {
      url: "https://api.weixin.qq.com/sns/userinfo",
      async request({ tokens, provider }) {
        const res = await fetch(
          `${provider.userinfo?.url}?access_token=${tokens.access_token}&openid=${tokens.openid}&lang=zh_CN`
        )
        return await res.json()
      },
    },
    
    // WeChat-Profil → NextAuth-Format
    profile(profile) {
      return {
        id: profile.openid,
        name: profile.nickname,
        email: null, // WeChat liefert keine E-Mail
        image: profile.headimgurl,
      }
    },
    
    options,
  }
}

Schritt 3: Umgebungsvariablen

WECHAT_CLIENT_ID=Ihre_WeChat_AppID
WECHAT_CLIENT_SECRET=Ihr_WeChat_AppSecret

Schritt 4: In NextAuth einbinden

import WeChatProvider from "@/lib/wechat-provider"

export const authOptions = {
  providers: [
    GoogleProvider({...}),
    GitHubProvider({...}),
    WeChatProvider({
      clientId: process.env.WECHAT_CLIENT_ID!,
      clientSecret: process.env.WECHAT_CLIENT_SECRET!,
    }),
  ],
}

Schritt 5: Lokal testen?

WeChat erlaubt kein localhost als Callback.

Option 1: Tunnel

ngrok oder cpolar:

# ngrok installieren
brew install ngrok

# Tunnel starten
ngrok http 3000

Temporäre Domain z. B. https://abc123.ngrok.io in WeChat als Callback-Domain und in NEXTAUTH_URL:

NEXTAUTH_URL=https://abc123.ngrok.io

Option 2: hosts-Datei

/etc/hosts (Mac/Linux) oder C:\Windows\System32\drivers\etc\hosts:

127.0.0.1 dev.yourdomain.com

http://dev.yourdomain.com:3000 – Callback dev.yourdomain.com. Problem: ICP-Pflicht – Option 1 ist zuverlässiger.

WeChat ohne E-Mail

Bei E-Mail-Pflicht nach Login erfassen oder openid als ID in der DB:

async signIn({ user, account }) {
  if (account?.provider === 'wechat') {
    // E-Mail nachträglich oder openid speichern
    console.log("WeChat openid:", user.id)
  }
  return true
}

Sicherheit – typische Fallen vermeiden

1. client_secret niemals leaken

Falsch:

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

Jetzt starten →Anzeige

// ❌ So nicht!
const clientSecret = "abc123def456" // Hardcoded

Im Frontend oder Git → jemand kann Ihre App imitieren.

Richtig:

• Umgebungsvariablen, .env.local in .gitignore
• client_secret nur serverseitig (NextAuth API Route)
• Deployment: Plattform-Umgebungsvariablen (Vercel Settings)

2. state gegen CSRF

Angriff: Gefälschter Autorisierungscode ohne state-Prüfung.

NextAuth.js validiert state automatisch.

Manuell: state erzeugen und speichern, beim Callback vergleichen.

3. Callback-Whitelist

Alle Umgebungen explizit eintragen:

• Entwicklung: http://localhost:3000/api/auth/callback/[provider]
• Preview: https://preview.yourdomain.com/api/auth/callback/[provider]
• Produktion: https://yourdomain.com/api/auth/callback/[provider]

Keine Wildcards wie https://*.yourdomain.com.

4. Token-Speicherung

NextAuth nutzt standardmäßig JWT in HttpOnly Cookies:

• HttpOnly: kein JS-Zugriff → weniger XSS-Risiko
• Secure (Produktion): nur HTTPS

access_token nicht ans Frontend geben. Persistenz in DB im signIn-Callback, Session minimal halten.

5. Kurzlebigkeit des Autorisierungscodes

code ~10 Minuten, einmalig – auch abgefangene Codes verlieren schnell Wert.

Lange Pause auf der Google-Seite → code abgelaufen; NextAuth startet neu.

6. Produktions-Checkliste

• Alle Umgebungsvariablen gesetzt (NEXTAUTH_URL, NEXTAUTH_SECRET, Provider-Secrets)?
• NEXTAUTH_URL = Produktions-Domain (nicht localhost)?
• OAuth-Provider: Produktions-Callbacks eingetragen?
• .env.local in .gitignore?
• Produktions-NEXTAUTH_SECRET neu generiert (nicht Dev-Wert)?

Fazit

OAuth = „Kurzzeit-Ausweis“: kein Passwort an Drittanbieter, sondern zeitlich und rechlich begrenztes access_token. Zuerst code (Zustimmung), dann code + client_secret → Token.

In Next.js: Google am einfachsten zum Einstieg; GitHub mit scope und fehlender öffentlicher E-Mail; WeChat mit QR, Custom Provider, ICP, schwierigem Local Debug.

Sicherheit in drei Sätzen:

1. client_secret nur Backend
2. state prüfen (NextAuth erledigt)
3. Callback-Whitelist, keine Wildcards

Erst Google wie im Artikel – danach fühlt sich der Erfolg gut an.

Die meisten Fehler: redirect_uri oder Umgebungsvariablen. Einmal durchgehen, meist behoben.

Mehr: NextAuth.js-Dokumentation – DB-Sessions, Custom Login, JWT. OAuth 2.0 (RFC 6749) lohnt sich für tieferes Verständnis.

Viel Erfolg beim Konfigurieren!