MOTOKO BASE

Dokumentation

OAuth-Setup

Schrittweises Google- und GitHub-OAuth-Setup für Motoko Base — Provider-Apps anlegen, Callback-URLs konfigurieren und .env ausfüllen.

Öffnen inChatGPT (öffnet in neuem Tab)Claude (öffnet in neuem Tab)Cursor (öffnet in neuem Tab)Schrittweises Google- und GitHub-OAuth-Setup für Motoko Base — Provider-Apps anlegen, Callback-URLs konfigurieren und .env ausfüllen.

Google- und GitHub-Sign-in sind optional. Lassen Sie die OAuth-Env-Vars ungesetzt und die App startet normal — Social-Buttons auf /sign-in und /sign-up bleiben deaktiviert.

Einmal konfiguriert, übernimmt Better Auth den OAuth-Flow und speichert verknüpfte Konten in der Tabelle account. Callback-URLs müssen exakt zu Ihrer BETTER_AUTH_URL passen.

Bevor Sie starten

Stellen Sie sicher, dass diese Auth-Env-Vars bereits gesetzt sind:

# .env or .env.local
DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=your-generated-secret
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

Für die lokale Entwicklung verwenden Sie http://localhost:3000 für beide URL-Variablen. In Produktion setzen Sie sie auf Ihren öffentlichen HTTPS-Origin (z. B. https://app.example.com).

Erzeugen Sie BETTER_AUTH_SECRET, falls noch nicht geschehen:

openssl rand -base64 32

Starten Sie den Dev-Server nach jeder Env-Änderung neu:

pnpm dev

Google OAuth

Schritt 1 — Google-Cloud-Projekt anlegen

  1. Öffnen Sie die Google Cloud Console
  2. Erstellen Sie ein neues Projekt (oder wählen Sie ein bestehendes)
  3. Gehen Sie zu APIs & Services → OAuth consent screen
  4. Wählen Sie External (oder Internal für Workspace-only Apps)
  5. Füllen Sie App-Name, Support-E-Mail und Entwicklerkontakt aus
  6. Scopes hinzufügen: email, profile und openid (Defaults reichen meist)
  7. Testnutzer hinzufügen, wenn die App im Modus Testing ist

Schritt 2 — OAuth-Credentials erstellen

  1. Gehen Sie zu APIs & Services → Credentials
  2. Klicken Sie auf Create Credentials → OAuth client ID
  3. Anwendungstyp: Web application
  4. Benennen Sie ihn (z. B. Motoko Base local)

Schritt 3 — Redirect-URI setzen

Unter Authorized redirect URIs hinzufügen:

{BETTER_AUTH_URL}/api/auth/callback/google

Beispiele:

EnvironmentRedirect URI
Localhttp://localhost:3000/api/auth/callback/google
Productionhttps://app.example.com/api/auth/callback/google

Der Pfad muss genau /api/auth/callback/google sein — Better Auth registriert diese Route automatisch.

Optional Authorized JavaScript origins für die lokale Entwicklung hinzufügen:

http://localhost:3000

Schritt 4 — Credentials in .env kopieren

Nach dem Erstellen des Clients zeigt Google eine Client ID und ein Client secret. Fügen Sie sie in .env ein:

GOOGLE_CLIENT_ID=123456789-abcdef.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxx

Beide Werte sind server-only — legen Sie sie nie auf NEXT_PUBLIC_*.

Schritt 5 — Lokal verifizieren

  1. Dev-Server neu starten: pnpm dev
  2. http://localhost:3000/sign-in öffnen
  3. Der Button Sign in with Google sollte aktiviert sein (nicht ausgegraut)
  4. Klicken — Sie sollten zu Google und zurück zu /dashboard gelangen

Bleibt der Button deaktiviert, prüfen Sie, dass beide GOOGLE_CLIENT_ID und GOOGLE_CLIENT_SECRET gesetzt und nicht leer sind.

Google-Troubleshooting

ProblemFix
redirect_uri_mismatchRedirect URI in Google Console must match {BETTER_AUTH_URL}/api/auth/callback/google exactly (scheme, host, port, path)
Button disabledBoth GOOGLE_* vars must be set; restart dev server
access_denied in Testing modeAdd your Google account as a test user on the consent screen
Works locally, fails in productionAdd production redirect URI and set BETTER_AUTH_URL to your live domain

GitHub OAuth

Schritt 1 — GitHub OAuth App anlegen

  1. Öffnen Sie GitHub Developer Settings → OAuth Apps
  2. Klicken Sie auf New OAuth App
  3. Ausfüllen:
    • Application name — z. B. Motoko Base
    • Homepage URL — Ihre App-URL (lokal: http://localhost:3000)
    • Authorization callback URL — siehe Schritt 2

Schritt 2 — Callback-URL setzen

Die Authorization callback URL muss sein:

{BETTER_AUTH_URL}/api/auth/callback/github

Beispiele:

EnvironmentCallback URL
Localhttp://localhost:3000/api/auth/callback/github
Productionhttps://app.example.com/api/auth/callback/github

Klicken Sie auf Register application.

Schritt 3 — Client Secret erzeugen

  1. Auf der OAuth-App-Seite auf Generate a new client secret klicken
  2. Client ID und Client secret sofort kopieren — das Secret wird nur einmal angezeigt

Schritt 4 — Credentials in .env kopieren

GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx
GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Beide Werte sind server-only.

Schritt 5 — Lokal verifizieren

  1. Dev-Server neu starten: pnpm dev
  2. http://localhost:3000/sign-in öffnen
  3. Der Button Sign in with GitHub sollte aktiviert sein
  4. Klicken — die App autorisieren und auf /dashboard landen

GitHub Apps vs OAuth Apps

Motoko Base verwendet eine Standard-OAuth App (keine GitHub App). Wenn Sie stattdessen eine GitHub App nutzen, stellen Sie sicher, dass Account permissions → Email addresses auf Read-only steht, damit Better Auth die verifizierte E-Mail des Users lesen kann.

GitHub-Troubleshooting

ProblemFix
redirect_uri mismatchCallback URL must be {BETTER_AUTH_URL}/api/auth/callback/github exactly
Button disabledBoth GITHUB_* vars must be set; restart dev server
Missing email / sign-in failsFor GitHub Apps, enable Email addresses read permission; OAuth Apps include email by default
Works locally, fails in productionUpdate callback URL in GitHub settings and set production BETTER_AUTH_URL

Produktions-Checkliste

Nutzen Sie diese Checkliste beim Deploy von OAuth auf Staging oder Produktion:

  1. Kanonische URLs setzen

    BETTER_AUTH_URL=https://app.example.com
NEXT_PUBLIC_APP_URL=https://app.example.com

  2. Produktions-Callback-URLs in Google Console und GitHub-OAuth-App-Einstellungen hinzufügen (lokale URIs behalten, wenn Sie weiter lokal entwickeln)

  3. Optional — Extra-Origins für Preview-Deployments:

    BETTER_AUTH_TRUSTED_ORIGINS=https://staging.example.com,https://*.vercel.app

  4. Neu starten / neu deployen nach Env-Änderungen

  5. Beide Provider auf der Live-URL testen — anmelden, abmelden und bestätigen, dass die Session bestehen bleibt

Wo OAuth im Code verdrahtet ist

Meist reichen Env-Vars. Zum Anpassen des Verhaltens diese Dateien bearbeiten:

FilePurpose
src/lib/auth/auth.tsRegisters socialProviders.google and socialProviders.github
src/lib/auth/social.tsisGoogleAuthConfigured() / isGitHubAuthConfigured()
src/app/sign-in/sign-in-form.tsxGoogle/GitHub sign-in handlers
src/app/sign-up/sign-up-form.tsxGoogle/GitHub sign-up handlers
src/app/sign-in/page.tsxPasses enabled flags to the form

OAuth-Secrets gehören nie in TypeScript-Config-Dateien — nur in .env.

Nächste Schritte

Better Auth — Vollständiger Auth-Überblick, Sessions, geschützte Routen und Dateikarte.

Umgebungsvariablen — Alle auth-bezogenen Env-Vars an einem Ort.