Configurer OAuth2 pour Google dans n8n : Gmail, Sheets, Drive et Calendar pas à pas

Connecter Gmail, Google Sheets, Drive ou Calendar à n8n est souvent la toute première chose qu'on veut faire — et la toute première qui bloque. Contrairement à une simple clé API à copier-coller, Google impose le protocole OAuth2 : un projet dans Google Cloud Console, des API à activer, un écran de consentement à configurer, un identifiant client à créer, et une URI de redirection à faire correspondre au caractère près. Rien d'insurmontable, mais l'enchaînement des étapes déroute la plupart des débutants, et une seule case mal cochée suffit à produire un message d'erreur opaque. Ce guide déroule le parcours complet, du projet Google Cloud jusqu'au bouton « Sign in with Google » dans n8n, puis passe en revue les pièges qui font perdre des heures.

Précisons d'emblée que cette complexité n'est pas qu'une impression de débutant. L'analyse formelle du protocole menée par Fett, Küsters et Schmitz et publiée à la conférence ACM CCS en 2016 (A Comprehensive Formal Security Analysis of OAuth 2.0, voir sur Google Scholar) a mis en évidence plusieurs vulnérabilités dans des configurations et implémentations OAuth réelles, notamment autour des URI de redirection. Autrement dit : la rigueur que Google exige sur chaque URI et chaque scope n'est pas du zèle administratif, c'est précisément ce qui empêche un tiers de détourner vos jetons d'accès. Prendre dix minutes pour configurer proprement n'est pas du temps perdu.

Vue d'ensemble : ce qu'on va construire

Le principe d'OAuth2 tient en une phrase : plutôt que de donner votre mot de passe Google à n8n, vous enregistrez n8n comme une « application » auprès de Google, et Google délivre à cette application des jetons d'accès limités aux permissions (scopes) que vous avez explicitement accordées. Concrètement, il vous faut :

1. Un projet dans Google Cloud Console.
2. Les API activées pour chaque service visé (Gmail API, Google Sheets API, Google Drive API, Google Calendar API).
3. Un écran de consentement OAuth configuré.
4. Un identifiant OAuth 2.0 de type application web, qui vous donne un client ID et un client secret.
5. Une credential n8n dans laquelle coller ces deux valeurs, avant de vous authentifier via « Sign in with Google ».

Bonne nouvelle : les étapes 1 à 4 ne se font qu'une fois. Le même projet et le même couple client ID / client secret servent ensuite pour toutes vos credentials Google dans n8n.

Étape 1 : créer un projet dans Google Cloud Console

Rendez-vous sur console.cloud.google.com, connectez-vous avec le compte Google que vous comptez utiliser dans vos workflows, et créez un nouveau projet. Le nom n'a aucune importance technique — « n8n-automations » fera l'affaire. Aucune carte bancaire n'est requise : les API Google Workspace utilisées ici sont gratuites dans les limites de quotas largement suffisantes pour un usage d'automatisation classique.

Étape 2 : activer les API nécessaires

Dans la bibliothèque d'API du projet (section « API et services »), recherchez et activez chaque API correspondant aux services que vous voulez piloter depuis n8n :

• Gmail API pour lire et envoyer des emails — le prérequis de tout workflow d'automatisation d'emails avec l'IA ;
• Google Sheets API pour manipuler des feuilles de calcul (voir notre guide Google Sheets) ;
• Google Drive API pour les fichiers et dossiers (notre guide Google Drive en détaille les cas d'usage) ;
• Google Calendar API pour les événements d'agenda (guide Google Calendar).

Activez-les toutes dès maintenant si vous savez que vous en aurez besoin : c'est gratuit, et cela vous évitera un aller-retour plus tard. Une API non activée produit côté n8n une erreur d'autorisation trompeuse, alors que le problème est simplement que le projet n'a pas le droit d'appeler ce service.

Étape 3 : configurer l'écran de consentement OAuth

L'écran de consentement est la page que Google affichera au moment du « Sign in with Google » pour vous demander d'accorder les permissions. Sa configuration demande quelques choix :

• Type d'utilisateurs : si votre compte appartient à une organisation Google Workspace, choisissez « Interne » — l'application sera limitée aux comptes de votre organisation, sans processus de vérification. Avec un compte Gmail personnel, seul le type « Externe » est disponible.
• Informations de base : nom de l'application (ce que vous verrez sur l'écran de consentement), email d'assistance, email de contact développeur. Là encore, les valeurs exactes importent peu pour un usage personnel.
• Mode test ou production : une application externe démarre en mode test. Dans ce mode, seuls les comptes de test explicitement ajoutés dans la configuration peuvent s'authentifier — ajoutez-y impérativement l'adresse Google que vous utiliserez dans n8n, sinon la connexion sera refusée d'entrée.

Le mode test cache un piège majeur qu'on détaillera plus bas : les refresh tokens y expirent au bout de 7 jours. Pour une instance n8n qui doit tourner en continu, prévoyez de passer l'application en production (un simple bouton dans l'écran de consentement) une fois vos premiers tests concluants. Pour un usage personnel avec vos propres scopes, ce passage ne déclenche pas d'exigence bloquante — vous verrez simplement l'avertissement « application non vérifiée », contournable.

Étape 4 : créer l'identifiant OAuth 2.0

Direction la section « Identifiants » du projet : créez un identifiant de type ID client OAuth, en choisissant Application Web comme type d'application. C'est ici que se joue l'étape la plus critique de tout le processus : le champ URI de redirection autorisées.

Ouvrez n8n dans un autre onglet, créez la credential visée (par exemple Gmail OAuth2 API pour le node Gmail) : n8n affiche en haut du formulaire une OAuth Redirect URL, du type https://votre-instance.exemple.com/rest/oauth2-credential/callback. Copiez cette URL exactement telle quelle et collez-la dans les URI de redirection autorisées côté Google. Le moindre écart — un http au lieu de https, un slash final en trop, un port différent, localhost d'un côté et un domaine de l'autre — provoquera l'erreur redirect_uri_mismatch au moment de la connexion.

Validez : Google vous remet un client ID et un client secret. Traitez ce secret comme un mot de passe — notre article sur la sécurisation des credentials dans n8n explique pourquoi et comment le protéger.

Étape 5 : connecter la credential dans n8n

Retour dans n8n : collez le client ID et le client secret dans les champs correspondants de la credential, enregistrez, puis cliquez sur Sign in with Google. Une fenêtre Google s'ouvre : choisissez le compte (celui ajouté en compte de test si l'application est en mode test), acceptez l'avertissement « application non vérifiée » le cas échéant, cochez les permissions demandées, et validez. La fenêtre se referme et la credential apparaît comme connectée.

Répétez uniquement cette étape 5 pour chaque service : une credential Google Sheets OAuth2, une credential Google Drive OAuth2, une credential Google Calendar OAuth2 — toutes avec le même client ID et le même client secret, chacune avec son propre « Sign in with Google » (les scopes demandés diffèrent selon le service).

Cas particulier du self-hosted : HTTPS obligatoire

Sur n8n Cloud, l'OAuth Redirect URL est propre d'office. Sur une instance self-hosted, elle est construite à partir de la variable d'environnement WEBHOOK_URL (ou à défaut de l'hôte configuré). Deux conséquences pratiques :

• Google exige une URI de redirection en HTTPS (hors localhost). Une instance accessible uniquement en http://ip-du-serveur:5678 ne pourra pas compléter le flux proprement : il vous faut un nom de domaine et un certificat TLS, ce que couvre notre guide HTTPS et nom de domaine avec Traefik ou Caddy.
• La variable WEBHOOK_URL doit pointer vers ce domaine public, faute de quoi n8n affichera une Redirect URL erronée. Notre guide des variables d'environnement détaille sa configuration.

Pièges fréquents

• Erreur redirect_uri_mismatch au clic sur « Sign in with Google ». L'URI collée côté Google ne correspond pas au caractère près à celle affichée par n8n. Recopiez l'OAuth Redirect URL depuis la credential n8n (sans la retaper à la main), vérifiez le protocole, le domaine, le port et l'absence de slash final surnuméraire. En self-hosted, vérifiez que WEBHOOK_URL pointe bien vers votre domaine HTTPS public.
• Credential qui expire au bout de 7 jours. Symptôme classique d'une application restée en mode test : Google invalide alors le refresh token après 7 jours, et n8n ne peut plus renouveler l'accès. Passez l'application en production dans l'écran de consentement, puis reconnectez la credential une dernière fois.
• Scopes insuffisants. Si un node échoue avec une erreur de permission alors que la connexion a réussi, la credential a probablement été autorisée avant l'ajout d'un scope, ou une case de permission a été décochée sur l'écran de consentement. Reconnectez la credential et acceptez l'ensemble des permissions demandées.
• Écran « Google n'a pas validé cette application ». Impressionnant mais non bloquant pour un usage personnel : un lien dans les paramètres avancés de l'avertissement permet de continuer vers l'application. La vérification formelle n'est requise que pour distribuer l'application à des utilisateurs externes.
• API non activée dans le projet. La connexion OAuth réussit, mais le premier appel du node échoue : vérifiez que l'API du service concerné (Gmail API, Sheets API…) est bien activée dans la bibliothèque d'API du projet.
• Compte de test manquant. En mode test, un compte non listé dans les comptes de test se voit refuser l'accès dès l'écran de connexion Google, avant même l'écran de consentement.

Et au-delà de Google ?

La bonne nouvelle, c'est que cet apprentissage est réutilisable : la logique est identique pour Microsoft (Azure), Slack, HubSpot et la plupart des services modernes. On enregistre une application chez le fournisseur, on déclare l'OAuth Redirect URL de n8n, on récupère un client ID et un client secret, on les colle dans la credential. Seuls changent les noms des consoles et quelques options d'écran. Une fois le flux Google maîtrisé, les suivants se configurent en quelques minutes.

Pour aller plus loin

Une credential Google OAuth2 propre — application en production, refresh token persistant, scopes complets — est le socle de tous les workflows Gmail sérieux. C'est exactement le prérequis des workflows du Pack Inbox IA (79 €), qui trient, classent et pré-rédigent vos réponses email : ils supposent une credential Gmail OAuth2 configurée comme décrit dans ce guide, et fonctionnent ensuite sans intervention. Et avant de multiplier les credentials sur votre instance, prenez le temps de lire notre article sur la sécurisation des credentials API dans n8n : chiffrement, clé d'instance et bonnes pratiques de partage y sont couverts en détail.