Google

Gmail, Drive, Agenda et Feuilles de calcul. Chaque accès s’autorise séparément.

Une connexion Google permet à Mankomail d'agir sur le compte Google d'un membre : refléter et envoyer son courrier Gmail et — si le membre l'autorise — déposer des fichiers dans Google Drive, créer des événements Google Agenda et ajouter des lignes à Google Sheets. Chaque membre connecte son propre compte ; personne ne peut connecter une boîte à la place d'un autre.

L'accès est découpé en capacités (boîte mail, fichiers, agenda, feuilles de calcul). Chaque capacité fait l'objet d'un consentement distinct, accordé à part et ajouté aux précédents : connecter une boîte ne donne aucun accès à Drive, et autoriser Drive ne redemande pas l'accès au courrier. La mise en place se fait en deux temps : un administrateur enregistre une fois l'application OAuth Google propre à l'organisation (« apportez votre application »), puis chaque membre connecte son compte.

En bref

• Identifiant : google
• Famille : Compte
• Configurée par : Chaque membre, pour lui-même
• Authentification : Connexion OAuth, capacité par capacité
• Type de credential : gmail_oauth

Capacités et scopes

Chaque capacité s’accorde séparément, quand un membre en a besoin pour la première fois. Chaque autorisation demande aussi openid, email.

Capacité	Scopes	Nœuds
mail	https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.send, https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/gmail.labels
drive	https://www.googleapis.com/auth/drive.file	Drive — déposer un fichier, Drive — chercher des fichiers, Drive — créer un dossier
calendar	https://www.googleapis.com/auth/calendar.events, https://www.googleapis.com/auth/calendar.freebusy, https://www.googleapis.com/auth/calendar.calendarlist.readonly	Agenda — créer un événement, Agenda — trouver des créneaux
sheets	https://www.googleapis.com/auth/spreadsheets	Sheets — ajouter une ligne

Avant de commencer

• Un administrateur de l'instance Mankomail enregistre l'application OAuth. Les membres ne voient jamais le secret client.
• Un projet Google Cloud dans lequel vous pouvez créer un client OAuth et activer des API.
• L'adresse publique de votre instance. L'URI de redirection est dérivée du réglage PUBLIC_BASE_URL ; ce doit être l'adresse que vos membres utilisent réellement dans leur navigateur. Voir les variables d'environnement.
• Une clé de chiffrement (ENCRYPTION_KEY) configurée sur l'instance. Sans elle, l'instance ne peut stocker ni le secret client ni les jetons des membres, et toute connexion échoue avec oauth.encryption_disabled.
• Savoir qui sont vos membres. S'ils appartiennent tous à la même organisation Google Workspace, l'écran de consentement peut utiliser le type d'utilisateurs Interne. Des comptes Gmail personnels, ou des comptes de plusieurs organisations, imposent le type Externe (voir l'avertissement de la section suivante).

Enregistrer l'application OAuth (administrateur)

Dans Mankomail, ouvrez Administration › Applications OAuth et choisissez Google sous Fournisseur à configurer. La page indique ce qu'il faut emporter dans la console Google Cloud : l'URI de redirection, et les scopes demandés capacité par capacité. L'URI de redirection a toujours cette forme :

<PUBLIC_BASE_URL>/api/v1/oauth/google/callback

Puis, dans la console Google Cloud (les libellés ci-dessous sont ceux de la console en anglais) :

1. Créez ou sélectionnez un projet.
2. Activez les API correspondant aux capacités que vos membres utiliseront : Gmail API pour la boîte mail, Google Drive API pour les fichiers, Google Calendar API pour l'agenda, Google Sheets API pour les feuilles de calcul. Une API non activée fait échouer les nœuds correspondants même quand le membre a donné son consentement.
3. Configurez l'écran de consentement (Google Auth platform › Branding, puis Audience). Choisissez le type d'utilisateurs Internal quand tous vos membres font partie de votre organisation Google Workspace. Vous n'avez pas à déclarer de scopes côté Google : Mankomail les demande lui-même quand un membre se connecte.
4. Créez le client OAuth (Google Auth platform › Clients › Create client), de type d'application Web application. Sous Authorized redirect URIs, ajoutez l'URI de redirection copiée depuis Mankomail, au caractère près.
5. Copiez l'identifiant client et le secret client.

De retour dans Mankomail, sous Les identifiants de l'application :

1. Collez l'Identifiant client (client_id). Il doit se terminer par .apps.googleusercontent.com ; le champ refuse toute autre forme (une autocomplétion du navigateur qui ajoute une adresse à la suite est la cause habituelle).
2. Collez le Secret client (client_secret).
3. Cliquez sur Enregistrer. Le badge d'état passe à Application enregistrée et le secret n'est plus montré que par ses quatre derniers caractères.

Type d'utilisateurs Externe

Avec le type External et le statut de publication Testing, seuls les utilisateurs de test déclarés dans la console peuvent se connecter, et Google délivre des jetons de rafraîchissement qui expirent au bout de 7 jours : les boîtes cessent alors de se synchroniser et doivent être reconnectées. Les scopes Gmail sont classés « restreints » par Google : publier une application externe qui les demande passe par la vérification de Google. Préférez le type Internal dès que vos membres partagent une organisation Google Workspace.

Renouveler le secret

Le secret n'est jamais réaffiché et n'est pas conservé à l'enregistrement : ressaisissez-le à chaque enregistrement, même pour ne corriger que l'identifiant client. Pour le renouveler, créez un nouveau secret dans la console, collez-le avec l'identifiant client, puis enregistrez.

Connecter un compte (membre)

1. Ouvrez Connexions, cliquez sur Ajouter une connexion, puis sur Connecter sur la carte Google.
2. Google vous demande de choisir un compte et affiche l'écran de consentement. Laissez cochés tous les accès demandés et acceptez.
3. Vous revenez dans Mankomail avec le message Boîte … connectée. La boîte commence à se synchroniser ; sa progression se suit dans Boîtes (voir boîtes et miroir).

La première connexion accorde toujours la capacité boîte mail. Les autres capacités s'ajoutent depuis la ligne du compte dans Connexions, sous Comptes mail et cloud : chaque capacité manquante a son bouton — Connecter Google Drive, Connecter l'agenda, Connecter les feuilles de calcul. Chaque clic ouvre un nouvel écran de consentement pour cet accès seulement ; une fois accordée, la capacité apparaît en badge sur le compte.

Quelques points à connaître :

• Autorisation incrémentale. Chaque autorisation demande à Google de conserver les scopes déjà accordés : ajouter Drive ne coupe jamais la boîte.
• Laissez toutes les cases cochées. Google présente certains accès sous forme de cases à cocher. Si vous en décochez une, la connexion est refusée avec Vous n'avez pas accordé tous les accès demandés et rien n'est enregistré : recommencez en laissant les cases cochées.
• Dix minutes. Une autorisation doit aboutir dans les dix minutes qui suivent le clic ; au-delà, ou si le lien est réutilisé, elle est refusée (oauth.invalid_state).
• Même compte, même connexion. Autoriser de nouveau la même adresse Google met à jour la connexion existante au lieu d'en créer une seconde.
• Depuis un nœud. Un nœud qui a besoin d'une capacité que vous n'avez pas accordée renvoie vers Connexions ; après le consentement, Retour au workflow vous y ramène.

Ce que permet chaque accès

Mankomail demande les scopes les plus étroits qui permettent à chaque capacité de fonctionner :

• Boîte mail — lire, envoyer et classer le courrier de la boîte connectée (scopes Gmail de lecture, d'envoi, de modification et de libellés). Ce sont les scopes de l'API Gmail, pas un accès IMAP complet.
• Fichiers — drive.file uniquement : Mankomail n'accède qu'aux fichiers qu'il a créés lui-même ou que le membre lui a explicitement désignés — jamais à tout le Drive. Un nœud ne peut donc pas voir un dossier que Mankomail n'a pas créé, même s'il appartient au membre.
• Agenda — calendar.events : créer et modifier des événements, pas administrer les agendas ni leurs partages. Créer un événement n'envoie aucune invitation par e-mail sauf si le nœud le demande (voir Agenda — créer un événement).
• Feuilles de calcul — lire et écrire des feuilles de calcul.

openid et email sont demandés avec chaque capacité : l'adresse du compte est ce qui identifie la connexion et permet de rattacher une deuxième capacité au même compte.

Déconnecter, révoquer, reconnecter

• Retirer la boîte. Un compte Google ne se supprime pas depuis Connexions : on déconnecte sa boîte depuis Boîtes. La déconnexion arrête la synchronisation, laisse l'historique lisible et retire la capacité boîte mail. Si le compte porte encore d'autres capacités (Drive, agenda…), la connexion est conservée pour que ces nœuds continuent de fonctionner ; sinon elle est effacée.
• Révoquer chez Google. Déconnecter dans Mankomail ne révoque pas l'accès chez Google. Pour le couper entièrement, retirez l'accès de l'application dans les paramètres de sécurité du compte Google. Google révoque l'autorisation entière, pas une capacité : toutes les capacités de ce compte cessent de fonctionner.
• Quand l'accès est perdu. Google cesse d'honorer une connexion quand le membre révoque l'accès, change son mot de passe (scopes Gmail), la laisse inutilisée six mois, ou dépasse 100 jetons de rafraîchissement actifs pour le même compte et le même client OAuth. Mankomail marque alors la connexion comme révoquée, la boîte apparaît en erreur dans Connexions et Boîtes, et les nœuds qui ont besoin du compte échouent avec credential.capability_missing.
• Reconnecter. Connectez de nouveau le même compte : commencez par la boîte (Reconnecter cette boîte dans Boîtes, ou la carte Google dans Connexions), puis chaque capacité nécessaire. La connexion et la boîte existantes sont réutilisées, historique compris.

Erreurs fréquentes

Les erreurs du parcours de connexion s'affichent dans un bandeau sur Connexions au retour de Google.

Message ou code	Cause	Que faire
oauth.app_not_configured — Aucune application n'est configurée pour ce fournisseur.	Aucune application Google n'est enregistrée, ou elle est désactivée.	Un administrateur l'enregistre dans Administration › Applications OAuth.
oauth.invalid_client_id — L'identifiant client n'a pas la forme attendue par ce fournisseur.	L'identifiant collé ne se termine pas par .apps.googleusercontent.com, ou porte du texte en plus.	Collez l'identifiant client seul, sans espace.
oauth.encryption_disabled	ENCRYPTION_KEY n'est pas configurée.	Configurez la clé de chiffrement et redémarrez l'instance.
Page Google redirect_uri_mismatch	L'URI enregistrée dans la console diffère de celle qu'envoie Mankomail, ou PUBLIC_BASE_URL ne correspond pas à l'adresse utilisée.	Recopiez l'URI de redirection de la page d'administration dans Authorized redirect URIs.
oauth.access_denied — Vous avez refusé l'autorisation chez le fournisseur.	Le membre a annulé ou refusé le consentement.	Relancez la connexion et acceptez.
oauth.capability_not_granted — Vous n'avez pas accordé tous les accès demandés.	Une case a été décochée sur l'écran de consentement Google.	Recommencez en laissant toutes les cases cochées.
oauth.invalid_state — Le lien d'autorisation a expiré ou a déjà été utilisé.	Plus de dix minutes se sont écoulées, le lien a servi deux fois, ou un autre membre est connecté à Mankomail dans le même navigateur.	Relancez la connexion.
oauth.missing_refresh_token — Le fournisseur n'a pas renvoyé de jeton de rafraîchissement.	Google n'a rendu aucun jeton de rafraîchissement : la connexion ne durerait qu'une heure.	Retirez l'accès de l'application dans le compte Google, puis reconnectez.
oauth.exchange_failed	Google a refusé l'échange du code d'autorisation (secret client erroné, par exemple).	Réessayez ; si l'erreur persiste, vérifiez l'identifiant et le secret enregistrés par l'administrateur.
credential.capability_missing — Cette action a besoin d'un accès supplémentaire (Drive, Agenda…).	L'étape a besoin d'une capacité que le membre n'a jamais accordée, ou qui a été révoquée.	Cliquez sur le bouton Connecter … correspondant dans Connexions.
google.insufficient_permissions	Le scope a été retiré côté Google.	Reconnectez le compte dans Connexions.
google.auth_failed	Google a refusé le jeton (accès révoqué).	Reconnectez le compte dans Connexions.
google.not_found	La ressource n'existe pas, ou drive.file la masque parce que Mankomail ne l'a pas créée.	Désignez au nœud un fichier ou un dossier créé par Mankomail, ou choisi par le membre.
google.rejected	Google a refusé l'opération elle-même (paramètre invalide).	Vérifiez les paramètres du nœud.
google.unavailable	Quota dépassé ou panne passagère.	Rien : l'étape refait automatiquement une tentative.
google.bad_locator	La valeur collée n'est ni un identifiant ni une URL Google reconnue.	Collez l'identifiant de la ressource ou son URL complète.

Pour la façon dont les étapes en échec sont retentées, voir la gestion des erreurs.

Nœuds qui utilisent cette connexion

• Drive — déposer un fichier — google_drive.upload (capacité drive)
• Drive — chercher des fichiers — google_drive.search (capacité drive)
• Drive — créer un dossier — google_drive.create_folder (capacité drive)
• Sheets — ajouter une ligne — google_sheets.append (capacité sheets)
• Agenda — créer un événement — google_calendar.create_event (capacité calendar)
• Agenda — trouver des créneaux — google_calendar.find_free (capacité calendar)