MOTOKO BASE

Documentation

Configuration OAuth

Configuration pas à pas OAuth Google et GitHub pour Motoko Base — créez les apps fournisseur, configurez les callback URLs et renseignez le .env.

Ouvrir dansChatGPT (s’ouvre dans un nouvel onglet)Claude (s’ouvre dans un nouvel onglet)Cursor (s’ouvre dans un nouvel onglet)Configuration pas à pas OAuth Google et GitHub pour Motoko Base — créez les apps fournisseur, configurez les callback URLs et renseignez le .env.

La connexion Google et GitHub est optionnelle. Laissez les variables OAuth non définies et l’app démarre normalement — les boutons sociaux sur /sign-in et /sign-up restent désactivés.

Une fois configuré, Better Auth gère le flux OAuth et stocke les comptes liés dans la table account. Les callback URLs doivent correspondre exactement à votre BETTER_AUTH_URL.

Avant de commencer

Assurez-vous que ces variables d’auth sont déjà définies :

# .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

Pour le développement local, utilisez http://localhost:3000 pour les deux variables d’URL. En production, définissez-les sur votre origine HTTPS publique (ex. https://app.example.com).

Générez BETTER_AUTH_SECRET si ce n’est pas déjà fait :

openssl rand -base64 32

Redémarrez le serveur de développement après toute modification de variable d’environnement :

pnpm dev

Google OAuth

Étape 1 — Créer un projet Google Cloud

  1. Ouvrez la Google Cloud Console
  2. Créez un nouveau projet (ou sélectionnez-en un existant)
  3. Allez dans APIs & Services → OAuth consent screen
  4. Choisissez External (ou Internal pour les apps Workspace uniquement)
  5. Remplissez le nom de l’app, l’e-mail de support et le contact développeur
  6. Ajoutez les scopes : email, profile et openid (les defaults suffisent souvent)
  7. Ajoutez des utilisateurs de test si l’app est en mode Testing

Étape 2 — Créer des identifiants OAuth

  1. Allez dans APIs & Services → Credentials
  2. Cliquez sur Create Credentials → OAuth client ID
  3. Type d’application : Web application
  4. Nommez-le (ex. Motoko Base local)

Étape 3 — Définir le redirect URI

Sous Authorized redirect URIs, ajoutez :

{BETTER_AUTH_URL}/api/auth/callback/google

Exemples :

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

Le chemin doit être exactement /api/auth/callback/google — Better Auth enregistre cette route automatiquement.

Ajoutez optionnellement des Authorized JavaScript origins pour le développement local :

http://localhost:3000

Étape 4 — Copier les identifiants dans .env

Après création du client, Google affiche un Client ID et un Client secret. Ajoutez-les à .env :

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

Les deux valeurs sont serveur uniquement — ne les mettez jamais sur NEXT_PUBLIC_*.

Étape 5 — Vérifier en local

  1. Redémarrez le serveur de développement : pnpm dev
  2. Ouvrez http://localhost:3000/sign-in
  3. Le bouton Sign in with Google doit être activé (pas grisé)
  4. Cliquez — vous devez être redirigé vers Google, puis revenir sur /dashboard

Si le bouton reste désactivé, vérifiez que les deux GOOGLE_CLIENT_ID et GOOGLE_CLIENT_SECRET sont définis et non vides.

Dépannage Google

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

Étape 1 — Créer une GitHub OAuth App

  1. Ouvrez GitHub Developer Settings → OAuth Apps
  2. Cliquez sur New OAuth App
  3. Remplissez :
    • Application name — ex. Motoko Base
    • Homepage URL — l’URL de votre app (local : http://localhost:3000)
    • Authorization callback URL — voir l’étape 2

Étape 2 — Définir le callback URL

Le Authorization callback URL doit être :

{BETTER_AUTH_URL}/api/auth/callback/github

Exemples :

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

Cliquez sur Register application.

Étape 3 — Générer un client secret

  1. Sur la page de l’OAuth app, cliquez sur Generate a new client secret
  2. Copiez immédiatement le Client ID et le Client secret — le secret n’est affiché qu’une fois

Étape 4 — Copier les identifiants dans .env

GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx
GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Les deux valeurs sont serveur uniquement.

Étape 5 — Vérifier en local

  1. Redémarrez le serveur de développement : pnpm dev
  2. Ouvrez http://localhost:3000/sign-in
  3. Le bouton Sign in with GitHub doit être activé
  4. Cliquez — autorisez l’app, puis atterrissez sur /dashboard

GitHub Apps vs OAuth Apps

Motoko Base utilise une OAuth App standard (pas une GitHub App). Si vous utilisez une GitHub App à la place, assurez-vous que Account permissions → Email addresses est en Read-only pour que Better Auth puisse lire l’e-mail vérifié de l’utilisateur.

Dépannage GitHub

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

Checklist production

Utilisez cette checklist lors du déploiement OAuth en staging ou production :

  1. Définir les URLs canoniques

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

  2. Ajouter les callback URLs de production dans Google Console et les paramètres de l’OAuth app GitHub (gardez les URI locales si vous développez encore en local)

  3. Optionnel — origines supplémentaires pour les déploiements preview :

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

  4. Redémarrer / redéployer après les changements d’env

  5. Tester les deux fournisseurs sur l’URL live — se connecter, se déconnecter et confirmer que la session persiste

Où OAuth est câblé dans le code

En général, les variables d’environnement suffisent. Pour personnaliser le comportement, éditez ces fichiers :

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

Les secrets OAuth n’appartiennent jamais aux fichiers TypeScript de config — uniquement à .env.

Prochaines étapes

Better Auth — Vue d’ensemble complète de l’auth, sessions, routes protégées et carte des fichiers.

Variables d’environnement — Toutes les variables d’auth au même endroit.