Guide complet OAuth Next.js : Google, GitHub, WeChat — configuration et bonnes pratiques

Cliquer sur « Se connecter avec Google », être redirigé vers Google, autoriser, revenir — et vous êtes connecté.

Vous avez vécu ce scénario des centaines de fois. Mais quand vient le moment d’ajouter une connexion tierce à votre projet, tout devient flou : pourquoi deux redirections ? Qu’est-ce qu’une URL de callback ? C’est quoi redirect_uri_mismatch ? Ça marche en local, et en production ça plante ?

La première fois que j’ai configuré OAuth, j’ai lu des tonnes de docs remplies de « code d’autorisation », « access_token », « client_secret » — de plus en plus confus. Deux jours et une montagne de pièges plus tard, j’ai enfin compris.

Cet article explique OAuth en termes simples : comment ça fonctionne vraiment et comment configurer Google, GitHub et WeChat dans Next.js. Vous verrez que ce n’est pas si compliqué.

OAuth 2.0, c’est quoi ? (en langage clair)

Une analogie du quotidien

Imaginez : vous habitez dans une résidence sécurisée. Vous commandez en ligne et voulez qu’un livreur dépose le colis chez vous. Problème : le livreur ne peut pas entrer.

La méthode naïve ? Lui donner votre badge. Risqué — il pourrait revenir quand il veut.

La bonne approche : vous allez voir le gardien et dites « j’attends un colis ». Le gardien délivre un laissez-passer temporaire : « accès uniquement de 14 h à 16 h, bâtiment A uniquement ». Une fois la livraison faite, le pass expire.

C’est l’idée centrale d’OAuth.

Dans cette analogie :

• Vous = l’utilisateur (celui qui veut se connecter)
• Le livreur = l’application tierce (votre site)
• Le gardien = le fournisseur OAuth (Google, WeChat, GitHub, etc.)
• Le badge = votre mot de passe (à ne jamais partager)
• Le laissez-passer temporaire = access_token (limité dans le temps et en permissions)

Vous n’avez pas besoin de donner votre mot de passe à l’application tierce — vous l’autorisez seulement à obtenir un « laissez-passer temporaire » auprès du fournisseur OAuth.

Le flux OAuth en cinq étapes (mode code d’autorisation)

Appliquons ce flux à la connexion OAuth dans Next.js.

Étape 1 : l’utilisateur clique sur « Se connecter avec Google » sur votre site.

Étape 2 : votre site redirige l’utilisateur vers la page d’autorisation Google, avec une URL du type :

https://accounts.google.com/o/oauth2/auth?
  client_id=ID_de_votre_app
  &redirect_uri=http://localhost:3000/api/auth/callback/google
  &response_type=code
  &scope=openid email profile
  &state=chaîne_aléatoire

Votre site dit à Google : « Je suis telle application (client_id), cet utilisateur veut se connecter avec votre compte — merci de lui demander confirmation, puis de le renvoyer à cette adresse (redirect_uri). »

Étape 3 : l’utilisateur voit « Telle application souhaite accéder à vos informations de base » et clique sur « Autoriser ».

Étape 4 : Google redirige l’utilisateur vers votre site (redirect_uri) avec un code d’autorisation (code) dans l’URL :

http://localhost:3000/api/auth/callback/google?code=ABCD1234&state=chaîne_aléatoire

Ce code n’est qu’un justificatif, pas le laissez-passer final. Il expire vite (environ 10 minutes) et ne s’utilise qu’une fois.

Étape 5 : votre backend envoie ce code, plus votre client_secret, à Google pour obtenir le vrai access_token :

// Code backend (version simplifiée)
const response = await fetch('https://oauth2.googleapis.com/token', {
  method: 'POST',
  body: JSON.stringify({
    code: 'ABCD1234',
    client_id: 'ID_de_votre_app',
    client_secret: 'secret_de_votre_app',
    redirect_uri: 'http://localhost:3000/api/auth/callback/google',
    grant_type: 'authorization_code',
  }),
})

const { access_token } = await response.json()

Avec l’access_token, votre site peut interroger Google pour obtenir e-mail, avatar, nom, etc.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Étape 6 (optionnelle) : récupérer les infos utilisateur avec l’access_token :

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

Une fois le flux terminé, votre site sait « qui est cet utilisateur » et peut créer une session.

Concepts clés, en langage clair

• client_id : l’« identifiant » de votre app chez Google. Peut être public.

• client_secret : le « mot de passe » de votre app. Ne jamais le divulguer — usage backend uniquement. S’il fuit, un attaquant peut usurper votre application.

• redirect_uri : l’adresse où Google renvoie l’utilisateur après autorisation. Doit être enregistrée à l’avance dans Google Cloud Console — Google vérifie strictement ; un slash en trop déclenche redirect_uri_mismatch.

• state : chaîne aléatoire anti-CSRF. Vous la générez au départ ; Google la renvoie telle quelle. Si elle ne correspond pas, la requête est probablement falsifiée.

• code : code d’autorisation temporaire (~10 min), usage unique. Prouve que l’utilisateur a accepté chez Google.

• access_token : le vrai « laissez-passer ». Permet d’accéder aux infos utilisateur chez Google. Durée de vie variable (1 h à plusieurs jours).

Pourquoi code puis access_token, en deux temps ?

Le code transite via le navigateur (visible côté client) ; l’access_token s’échange entre serveurs (invisible côté client). Retourner directement l’access_token dans l’URL l’exposerait à l’historique, aux logs, à la surveillance réseau. L’échange code → token exige le client_secret, stocké côté serveur — bien plus sûr.

Next.js + NextAuth.js : configurer Google (le plus simple pour débuter)

Pourquoi NextAuth.js ?

Implémenter OAuth soi-même, c’est lourd : callbacks, sessions, CSRF, stockage des tokens…

NextAuth.js (aujourd’hui Auth.js v5) fait tout ça. 15k+ stars sur GitHub, 50+ fournisseurs (Google, GitHub, WeChat, Twitter…), compatible App Router Next.js 14+. En bref, NextAuth.js vous épargne ~80 % du travail répétitif.

Étape 1 : créer l’application dans Google Cloud

Avant le code, enregistrez votre app chez Google pour obtenir client_id et client_secret.

1. Ouvrez Google Cloud Console et connectez-vous.

2. Créez un projet si nécessaire (ex. « My Next.js App »).

3. Menu gauche : « API et services » → « Identifiants » (Credentials).

4. « Créer des identifiants » → « ID client OAuth ».

5. Si c’est la première fois, configurez l’« écran de consentement OAuth » : nom de l’app, e-mail de support ; type « Externe », pas de revue en phase de test.

6. Créez l’ID client OAuth, type « Application Web ».

7. Point crucial : « URI de redirection autorisés » :

   • Développement local : http://localhost:3000/api/auth/callback/google
   • Production (à ajouter après déploiement) : https://yourdomain.com/api/auth/callback/google

   L’URL doit correspondre exactement au code — un slash en trop ou en moins = redirect_uri_mismatch. Je me suis fait avoir au début.

8. Cliquez « Créer », copiez Client ID et Client Secret.

Étape 2 : installer NextAuth.js et les variables d’environnement

Dans votre projet Next.js :

npm install next-auth@beta

Installez la version @beta (v5, la plus récente).

Créez .env.local à la racine :

GOOGLE_CLIENT_ID=votre_Client_ID.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=votre_Client_Secret
NEXTAUTH_SECRET=chaîne_aléatoire
NEXTAUTH_URL=http://localhost:3000

Générez NEXTAUTH_SECRET avec :

openssl rand -base64 32

En production, remplacez NEXTAUTH_URL par votre domaine.

Étape 3 : fichier de configuration NextAuth

Créez 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 }) {
      // Callback après connexion réussie — sauvegarder l'utilisateur en BDD si besoin
      console.log("Utilisateur connecté:", user)
      return true // true = autoriser la connexion
    },
    async session({ session, token }) {
      // Personnaliser le contenu de la session
      if (session.user) {
        session.user.id = token.sub // ajouter l'id utilisateur à la session
      }
      return session
    },
  },
}

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

NextAuth.js gère tout le flux OAuth. La route /api/auth/callback/google est générée automatiquement.

Étape 4 : bouton de connexion

Dans n’importe quel composant :

'use client' // App Router : composant client requis

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

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

  if (session) {
    // Utilisateur connecté
    return (
      <div>
        <p>Bienvenue, {session.user?.name}</p>
        <img src={session.user?.image || ''} alt="Avatar" />
        <button onClick={() => signOut()}>Se déconnecter</button>
      </div>
    )
  }

  // Non connecté
  return <button onClick={() => signIn('google')}>Se connecter avec Google</button>
}

signIn('google') redirige vers Google ; après autorisation, l’utilisateur revient connecté.

Étape 5 : envelopper l’app avec SessionProvider

Pour que useSession fonctionne partout, enveloppez la racine :

// 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>
  )
}

Voilà — une app Next.js avec connexion Google.

Dépannage courant

Problème 1 : redirect_uri_mismatch

L’erreur la plus fréquente — je l’ai eue dès la première config.

Message typique : Error 400: redirect_uri_mismatch

Cause : l’URL de callback configurée dans Google Cloud Console ne correspond pas à la requête réelle.

Solutions :

1. Vérifier « URI de redirection autorisés » : http://localhost:3000/api/auth/callback/google (pas de slash en trop)
2. Vérifier NEXTAUTH_URL=http://localhost:3000 dans .env.local
3. Si vous changez de port (ex. 3001), mettez à jour des deux côtés

Problème 2 : OK en local, échec après déploiement

Classique aussi. Local parfait, sur Vercel le bouton ne répond pas ou erreur.

Cause : variables d’environnement de production non mises à jour.

Solutions :

1. Ajouter dans Google Cloud : https://yourdomain.com/api/auth/callback/google
2. Sur Vercel (ou votre hébergeur) : NEXTAUTH_URL=https://yourdomain.com
3. Redéployer

Problème 3 : session null après connexion

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Si useSession() retourne toujours null, vérifiez que <SessionProvider> enveloppe bien la racine.

Problème 4 : TypeError: Cannot read property ‘user’ of null

Souvent parce que la session charge encore et vous accédez déjà à session.user.

Solution :

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

if (status === 'loading') {
  return <div>Chargement...</div>
}

if (!session) {
  return <div>Non connecté</div>
}

// Accès sécurisé à session.user

Configuration GitHub (comprendre les différences)

Avec Google en place, GitHub est plus simple — mais quelques différences méritent attention.

GitHub vs Google OAuth

Similitudes : OAuth 2.0 standard, mode code d’autorisation, même flux.

Différences :

1. Scopes plus fins : par défaut, infos publiques seulement ; pour l’e-mail privé, scope user:email requis.
2. Callback plus souple : Google exige l’URL complète ; GitHub accepte souvent le domaine seul.
3. Types d’app : compte personnel ou organisation.

Étape 1 : créer une OAuth App sur GitHub

1. GitHub → avatar → Settings → « Developer settings ».

2. « OAuth Apps » → « New OAuth App ».

3. Renseignez :

   • Application name : nom visible lors de l’autorisation
   • Homepage URL : ex. http://localhost:3000
   • Authorization callback URL : http://localhost:3000/api/auth/callback/github

4. « Register application », puis « Generate a new client secret » — copiez Client ID et Client Secret.

Étape 2 : variables d’environnement

Dans .env.local :

GITHUB_CLIENT_ID=votre_GitHub_Client_ID
GITHUB_CLIENT_SECRET=votre_GitHub_Client_Secret

Étape 3 : mettre à jour NextAuth

Dans route.ts, ajoutez GitHubProvider :

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!,
      // Pour l'e-mail privé :
      authorization: {
        params: {
          scope: 'read:user user:email'
        }
      }
    }),
  ],
  callbacks: {
    // ... callbacks existants
  },
}

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

Étape 4 : boutons de connexion

return (
  <div>
    <button onClick={() => signIn('google')}>Se connecter avec Google</button>
    <button onClick={() => signIn('github')}>Se connecter avec GitHub</button>
  </div>
)

À propos des scopes

Scopes GitHub courants :

• read:user : infos publiques et privées (nom, avatar, bio…)
• user:email : e-mails, y compris privés
• public_repo : dépôts publics
• repo : tous les dépôts (privés inclus — à utiliser avec prudence)

Pour la connexion, read:user user:email suffit.

Sans user:email, NextAuth.js n’obtient que l’e-mail public. Si l’utilisateur le masque sur GitHub, session.user.email sera null — j’ai perdu du temps à croire que c’était un bug de code.

Piège : e-mail non public sur GitHub

Contrairement à Google, GitHub permet de masquer l’e-mail. Si votre app en a besoin (notifications, etc.), vérifiez dans le callback signIn :

async signIn({ user, account }) {
  if (account?.provider === 'github' && !user.email) {
    // Pas d'e-mail public — refuser ou demander à l'utilisateur
    console.log("Utilisateur GitHub sans e-mail")
    return false // refuser la connexion
  }
  return true
}

Configuration WeChat (cas particulier en Chine)

WeChat est nettement plus complexe que Google et GitHub — écosystème et contraintes différents.

Pourquoi WeChat est spécial ?

1. QR code obligatoire : sur PC, l’utilisateur scanne un QR code avec son téléphone (pas un simple clic comme Google/GitHub).
2. Pas de provider NextAuth natif : provider personnalisé requis.
3. Callbacks restrictifs : domaine enregistré ICP, pas de localhost — debug local difficile.
4. openid et unionid : openid différent par app ; unionid pour unifier les utilisateurs entre plusieurs apps.

Étape 1 : inscription plateforme ouverte WeChat

1. Plateforme ouverte WeChat — créer un compte.

2. Créer une « application web » (pas compte officiel ni mini-programme).

3. Renseigner les infos, captures d’écran — validation 1 à 3 jours ouvrés.

4. Après validation : AppID et AppSecret (équivalents client_id / client_secret).

5. Dans « Informations de développement », configurer le domaine de callback (domaine seul, ex. yourdomain.com).

Étape 2 : provider WeChat personnalisé

Créez 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",
    
    // URL d'autorisation WeChat (application web PC)
    authorization: {
      url: "https://open.weixin.qq.com/connect/qrconnect",
      params: {
        scope: "snsapi_login",
        appid: options.clientId,
        response_type: "code",
      },
    },
    
    // Échange code → access_token
    token: {
      url: "https://api.weixin.qq.com/sns/oauth2/access_token",
      params: {
        appid: options.clientId,
        secret: options.clientSecret,
        grant_type: "authorization_code",
      },
    },
    
    // Infos utilisateur
    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()
      },
    },
    
    // Conversion au format NextAuth
    profile(profile) {
      return {
        id: profile.openid,
        name: profile.nickname,
        email: null, // WeChat ne fournit pas d'e-mail
        image: profile.headimgurl,
      }
    },
    
    options,
  }
}

Étape 3 : variables d’environnement

WECHAT_CLIENT_ID=votre_AppID_WeChat
WECHAT_CLIENT_SECRET=votre_AppSecret_WeChat

Étape 4 : utiliser dans NextAuth

Mettez à jour route.ts :

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!,
    }),
  ],
}

Étape 5 : tester en local ?

WeChat n’accepte pas localhost comme domaine de callback — test local impossible directement.

Option 1 : tunnel (recommandé)

Avec ngrok ou cpolar :

# Installer ngrok
brew install ngrok

# Exposer le port local
ngrok http 3000

ngrok fournit un domaine temporaire, ex. https://abc123.ngrok.io. Ajoutez-le comme domaine de callback WeChat et mettez à jour .env.local :

NEXTAUTH_URL=https://abc123.ngrok.io

Option 2 : fichier hosts

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

127.0.0.1 dev.yourdomain.com

Accédez à http://dev.yourdomain.com:3000 et configurez dev.yourdomain.com chez WeChat — mais WeChat exige un domaine enregistré ICP, donc cette option échoue souvent. Préférez ngrok.

Traitement spécifique WeChat

Pas d’e-mail WeChat — si votre app en dépend :

async signIn({ user, account }) {
  if (account?.provider === 'wechat') {
    // Demander l'e-mail après connexion, ou utiliser openid comme identifiant unique
    console.log("openid WeChat:", user.id)
  }
  return true
}

Bonnes pratiques de sécurité (éviter les pièges)

Quelques détails après la configuration OAuth — appris à mes dépens.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

1. client_secret : ne jamais le divulguer

Mauvaise pratique :

// ❌ Ne faites jamais ça !
const clientSecret = "abc123def456" // en dur dans le code

Exposé dans le front ou Git, un attaquant peut usurper votre app.

Bonne pratique :

• Variables d’environnement, .env.local dans .gitignore
• client_secret côté serveur uniquement (route API NextAuth = OK)
• Variables de plateforme en production (Vercel → Settings → Environment Variables)

2. Le paramètre state (anti-CSRF)

Scénario d’attaque : lien malveillant avec un faux code d’autorisation ; sans validation du state, votre app pourrait échanger ce code.

NextAuth.js gère le state automatiquement.

Implémentation manuelle :

1. Générer un state aléatoire, le stocker en session/cookie
2. À la callback, vérifier qu’il correspond
3. Sinon, refuser

3. Liste blanche des URLs de callback

Chez chaque fournisseur, listez explicitement :

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

Pas de wildcards (https://*.yourdomain.com) — pratique mais risqué.

4. Stockage sécurisé des tokens

NextAuth.js utilise JWT en session par défaut, stocké en cookie HttpOnly :

• HttpOnly : JavaScript ne peut pas lire le cookie (anti-XSS)
• Secure (production) : HTTPS uniquement (anti MITM)

À faire :

• Ne pas renvoyer access_token au front (NextAuth ne le fait pas par défaut — n’ajoutez pas ça)
• Persister en BDD dans signIn si besoin ; session = id, e-mail, etc.

5. Durée de vie du code d’autorisation

Le code expire vite (~10 min), usage unique. Même intercepté, il sera souvent expiré ou déjà consommé.

Si l’utilisateur traîne sur la page d’autorisation, le code peut expirer — NextAuth relance le flux.

6. Checklist production

Avant déploiement :

• Variables définies (NEXTAUTH_URL, NEXTAUTH_SECRET, client_id/secret de chaque provider) ?
• NEXTAUTH_URL = domaine de production (pas localhost) ?
• Callbacks production configurés chez chaque fournisseur ?
• .env.local dans .gitignore ?
• NEXTAUTH_SECRET de production unique (pas celui du dev) ?

Conclusion

OAuth, c’est un « laissez-passer temporaire » : pas de mot de passe partagé, juste une autorisation pour obtenir un access_token limité. Deux temps : code d’autorisation (preuve du consentement), puis échange code + client_secret.

Dans Next.js : Google le plus simple pour débuter ; GitHub un peu plus fin (scopes, e-mail parfois absent) ; WeChat le plus contraignant (QR, provider custom, domaine ICP, debug local via tunnel).

Sécurité — trois règles :

1. client_secret côté serveur uniquement
2. Valider le state (NextAuth le fait)
3. Liste blanche des callbacks, pas de wildcards

Première config OAuth ? Commencez par Google, suivez le code pas à pas — la satisfaction quand ça marche vaut le coup.

90 % des erreurs = redirect_uri mal configurée ou variable d’environnement manquante. Revérifiez, ça se règle souvent vite.

Consultez aussi la documentation NextAuth.js (session en BDD, pages custom, JWT…) et la RFC 6749 (OAuth 2.0) pour approfondir.

À vous de jouer — bonne configuration !