Comprendre l’authentification avec Github (OAuth)

Proposer un bouton "Se connecter avec GitHub" dans une application est un super moyen d’optimiser son taux de conversion : C'est pratique pour l'utilisateur, qui n'a pas besoin de créer un nouveau mot de passe.

Mais aussi pour le développeur, qui délègue l'authentification à GitHub. Pourtant, beaucoup de développeurs utilisent OAuth sans réellement comprendre ce qu'il se passe derrière.

Votre application ne connaît jamais le mot de passe GitHub de l'utilisateur. À la place, elle laisse GitHub vérifier son identité, puis récupère uniquement les informations dont elle a besoin.

C'est tout le principe d'OAuth : déléguer l'authentification à un service tiers.

Créer une OAuth App

La première étape consiste à créer une application sur GitHub.

Pour cela, rendez-vous dans les paramètres de votre compte, puis dans Developer settings > OAuth Apps.

Vous devrez notamment renseigner :

• le nom de votre application ;
• son URL ;
• une URL de callback.

Par exemple :

http://localhost:3000/auth/github/callback

Une fois l'application créée, GitHub vous fournit deux informations importantes :

Client ID
Client Secret

Le Client ID identifie votre application.

Le Client Secret, lui, est confidentiel.

Il ne doit jamais être envoyé au navigateur ni intégré dans votre code frontend.

Astuce

Vous pouvez créer autant d’application que vous voulez, donc il est au moins recommandé d’en créer une pour votre environnement de production, et une pour le local.

Vous pouvez l’appeler “MonApp (local)” par exemple.

Rediriger l'utilisateur vers GitHub

Lorsque l'utilisateur clique sur "Se connecter avec GitHub", votre application ne tente pas de l'authentifier elle-même.

Elle le redirige simplement vers GitHub.

Par exemple :

const params = new URLSearchParams({
  client_id: process.env.GITHUB_CLIENT_ID,
  redirect_uri: "http://localhost:3000/auth/github/callback",
  scope: "read:user user:email",
  state: crypto.randomUUID(),
});

response.redirect(
  `https://github.com/login/oauth/authorize?${params}`
);

Le paramètre scope indique les informations que votre application souhaite récupérer.

Le paramètre state est un identifiant aléatoire permettant de protéger le flux contre certaines attaques. Il doit être enregistré avant la redirection puis vérifié lorsque GitHub renvoie l'utilisateur.

GitHub authentifie l'utilisateur

L'utilisateur arrive alors sur GitHub et s'il n'est pas déjà connecté, GitHub lui demande de s'authentifier.

GitHub lui affiche ensuite les permissions demandées par votre application et lui demande de les accepter. Votre application ne voit jamais cette étape.

Elle attend simplement que GitHub renvoie l'utilisateur vers l'URL de callback.

Récupérer un code temporaire

Une fois les permissions acceptées, GitHub redirige le navigateur vers votre callback.

L'URL ressemble à ceci :

/auth/github/callback?code=...&state=...

Le code est un identifiant temporaire. À lui seul, il ne permet pas d'appeler l'API GitHub.

Votre serveur doit d'abord l'échanger contre un Access Token.

const tokenResponse = await fetch(
  "https://github.com/login/oauth/access_token",
  {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      client_id: process.env.GITHUB_CLIENT_ID,
      client_secret: process.env.GITHUB_CLIENT_SECRET,
      code,
    }),
  }
);

const { access_token } = await tokenResponse.json();

Cette requête doit toujours être effectuée côté serveur, car elle utilise votre Client Secret.

Récupérer l'email de l'utilisateur

Une fois le token obtenu, vous pouvez appeler l'API GitHub, par exemple pour récupérer les adresses email du compte :

const emailsResponse = await fetch(
  "https://api.github.com/user/emails",
  {
    headers: {
      Authorization: `Bearer ${access_token}`,
      Accept: "application/vnd.github+json",
    },
  }
);

const emails = await emailsResponse.json();

const primaryEmail = emails.find(
  (email) => email.primary && email.verified
)?.email;

L'adresse email principale est généralement le meilleur identifiant à utiliser.

En effet, si un utilisateur possède déjà un compte créé avec Google ou avec un email et un mot de passe, il est probable que cette adresse soit la même.

Cela permet de proposer plusieurs méthodes de connexion tout en conservant un seul compte utilisateur.

Générer le JWT de votre application

À ce stade, GitHub a terminé son travail, votre application connaît désormais l'identité de l'utilisateur.

Il ne reste plus qu'à rechercher un utilisateur possédant cette adresse email.

• S'il n'existe pas encore, vous pouvez lui créer un compte automatiquement.
• Sinon, on récupère simplement ses infos dans la base de données

Une fois cette étape terminée, vous générez votre propre token JWT :

const token = jwt.sign(
  {
    userId: user.id,
    email: user.email,
  },
  process.env.JWT_SECRET,
  {
    expiresIn: "7d",
  }
);

Ce JWT est ensuite renvoyé au navigateur, généralement dans un cookie sécurisé ou dans la réponse de votre API.

Le token GitHub sert uniquement à communiquer avec GitHub. Une fois l'utilisateur authentifié, c'est votre propre JWT qui permettra de l'identifier sur votre application.

Le fonctionnement résumé

Même si OAuth peut sembler impressionnant au premier abord, le mécanisme est finalement assez simple :

1. Votre application redirige l'utilisateur vers GitHub.
2. GitHub vérifie son identité et renvoie un code temporaire.
3. Votre serveur échange ce code contre un token, récupère l'adresse email de l'utilisateur, puis génère son propre JWT.
4. Au final, GitHub ne fait qu'une seule chose : confirmer l'identité de l'utilisateur.

Toute la gestion des comptes, des permissions et de l'authentification au sein de votre application reste sous votre responsabilité.