Microsoft

Outlook, OneDrive et Agenda, via Microsoft Graph.

Une connexion Microsoft permet à Mankomail d'agir sur le compte professionnel ou scolaire Microsoft 365 d'un membre, via Microsoft Graph : refléter et envoyer son courrier Outlook et — si le membre l'autorise — travailler avec ses fichiers OneDrive, son agenda Outlook et les sites SharePoint auxquels il a déjà accès. Chaque membre connecte son propre compte.

L'accès est découpé en capacités (boîte mail, fichiers, agenda, SharePoint). 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 à OneDrive, et autoriser OneDrive ne redemande pas l'accès au courrier. La mise en place se fait en deux temps : un administrateur inscrit une fois l'application propre à l'organisation dans Microsoft Entra ID (« apportez votre application »), puis chaque membre connecte son compte.

En bref

• Identifiant : microsoft
• Famille : Compte
• Configurée par : Chaque membre, pour lui-même
• Authentification : Connexion OAuth, capacité par capacité
• Type de credential : msgraph_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, offline_access.

Capacité	Scopes	Nœuds
mail	Mail.ReadWrite, Mail.Send
calendar	Calendars.ReadWrite	Créer un événement Outlook, Trouver un créneau Outlook
files	Files.ReadWrite	Déposer dans OneDrive, Chercher dans OneDrive, Créer un dossier OneDrive, Excel
sharepoint	Sites.Read.All, Sites.ReadWrite.All	SharePoint, Excel

Avant de commencer

• Comptes professionnels ou scolaires uniquement. Mankomail connecte les membres par le point de terminaison organizations de Microsoft, qui accepte les comptes Microsoft Entra (professionnels ou scolaires). Les comptes Microsoft personnels (Outlook.com, Hotmail, Live) ne peuvent pas être connectés.
• Un administrateur de l'instance Mankomail enregistre l'application. Les membres ne voient jamais le secret client.
• Un rôle Microsoft Entra autorisé à inscrire des applications dans votre tenant (au moins Développeur d'applications). Accorder le consentement administrateur pour toute l'organisation, nécessaire à SharePoint, demande un rôle habilité à le faire.
• 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. Voir les variables d'environnement.
• Une clé de chiffrement (ENCRYPTION_KEY) configurée sur l'instance. Sans elle, rien ne peut être stocké et toute connexion échoue avec oauth.encryption_disabled.

Inscrire l'application (administrateur)

Dans Mankomail, ouvrez Administration › Applications OAuth et choisissez Microsoft sous Fournisseur à configurer. La page affiche l'URI de redirection et les autorisations Microsoft Graph demandées capacité par capacité. L'URI de redirection a toujours cette forme :

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

Puis, dans le centre d'administration Microsoft Entra :

1. Ouvrez Entra ID › Inscriptions d'applications et créez une nouvelle inscription.
2. Donnez-lui un nom que vos membres reconnaîtront : il s'affiche sur l'écran de consentement.
3. Dans Types de comptes pris en charge, choisissez l'option multilocataire (Multiple Entra ID tenants dans la console en anglais). Microsoft refuse le point de terminaison organizations utilisé par Mankomail à une application inscrite en monolocataire (erreur AADSTS50194).
4. Validez l'inscription. Sur la page Vue d'ensemble, copiez l'ID d'application (client).
5. Dans Authentification, ajoutez une plateforme Web et collez-y l'URI de redirection copiée depuis Mankomail, au caractère près.
6. Dans Certificats et secrets, créez un nouveau secret client. Copiez sa valeur — pas son identifiant : elle ne s'affiche qu'une fois. Notez sa date d'expiration.

Inutile d'ajouter les autorisations de courrier, de fichiers ou d'agenda dans l'inscription : Mankomail les demande quand un membre connecte chaque capacité. SharePoint fait exception (voir l'avertissement ci-dessous).

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

1. Collez l'Identifiant client (client_id). Ce doit être un GUID (00000000-0000-0000-0000-000000000000) ; le champ refuse toute autre forme.
2. Collez le Secret client (client_secret) (la valeur).
3. Cliquez sur Enregistrer. Le badge d'état passe à Application enregistrée.

SharePoint exige le consentement administrateur

La capacité SharePoint demande Sites.Read.All et Sites.ReadWrite.All. Dans un tenant Microsoft 365 laissé à ses réglages par défaut, les utilisateurs ne peuvent pas y consentir eux-mêmes : un administrateur doit accorder le consentement une fois pour toute l'organisation. Dans Entra, ouvrez l'inscription d'application, puis Autorisations d'API, ajoutez les deux autorisations déléguées Microsoft Graph Sites.Read.All et Sites.ReadWrite.All, et choisissez Accorder le consentement administrateur. Sans cette étape, le premier membre qui clique sur Connecter SharePoint voit la page Microsoft « Approbation d'un administrateur requise » (AADSTS65001).

Expiration du secret client

Les secrets clients Entra expirent. Une fois le secret expiré, Microsoft refuse tout rafraîchissement de jeton (AADSTS7000222) et les connexions cessent de fonctionner. Avant la date d'expiration, créez un nouveau secret, collez-le dans Mankomail avec l'identifiant client et enregistrez : le secret n'est jamais conservé d'un enregistrement à l'autre et doit être ressaisi à chaque fois.

Connecter un compte (membre)

1. Ouvrez Connexions, cliquez sur Ajouter une connexion, puis sur Connecter sur la carte Microsoft.
2. Microsoft vous demande de choisir un compte. Choisissez votre compte professionnel — ce choix est toujours proposé, pour qu'un navigateur connecté à un autre compte ne branche pas la mauvaise boîte.
3. Acceptez les autorisations demandées. Vous revenez dans Mankomail avec le message Boîte … connectée. et la boîte commence à se synchroniser 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 : Connecter OneDrive, Connecter l'agenda, Connecter SharePoint. Chaque clic ouvre un consentement pour cet accès seulement ; une fois accordée, la capacité apparaît en badge sur le compte. Le consentement Microsoft est cumulatif : accorder une nouvelle capacité ne retire jamais les précédentes.

• 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).
• Autoriser de nouveau la même adresse Microsoft met à jour la connexion existante au lieu d'en créer une seconde.
• Microsoft n'a pas de capacité « feuilles de calcul » propre : les classeurs Excel s'atteignent par OneDrive ou SharePoint.

Ce que permet chaque autorisation

Toutes les autorisations sont déléguées : Mankomail agit en tant que membre, avec ses propres droits, jamais avec un accès à l'échelle de l'application.

• Boîte mail — Mail.ReadWrite pour lire le miroir et classer les messages (indicateurs, déplacements, brouillons), Mail.Send pour envoyer.
• Fichiers — Files.ReadWrite : le OneDrive du membre, en lecture et en écriture. Ni les OneDrive des collègues (Files.ReadWrite.All n'est jamais demandé), ni les sites SharePoint.
• Agenda — Calendars.ReadWrite : créer des événements et chercher des créneaux libres dans l'agenda du membre.
• SharePoint — Sites.Read.All et Sites.ReadWrite.All : lire et écrire les documents et les éléments de liste des sites auxquels le membre a déjà accès. Mankomail crée des éléments, jamais des listes ni des colonnes : il ne demande donc jamais Sites.Manage.All ni Sites.FullControl.All.

openid, email et offline_access sont demandés avec chaque capacité : l'adresse identifie la connexion, et offline_access est ce qui fournit un jeton de rafraîchissement — sans lui, l'accès ne durerait qu'une heure.

Invitations d'agenda

Microsoft Graph prévient les participants dès qu'un événement est créé avec eux. Quand l'option Envoyer les invitations du nœud Créer un événement Outlook est désactivée (le défaut), Mankomail n'envoie pas les participants en tant que tels : il les liste dans le corps de l'événement, et personne ne reçoit de mail.

Déconnecter, révoquer, reconnecter

• Retirer la boîte. Un compte Microsoft 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 (OneDrive, agenda, SharePoint), la connexion est conservée pour que ces nœuds continuent de fonctionner ; sinon elle est effacée.
• Révoquer chez Microsoft. Déconnecter dans Mankomail ne retire pas le consentement enregistré chez Microsoft. Microsoft révoque une autorisation entière, pas une capacité isolée.
• Quand l'accès est perdu. Si Microsoft refuse de rafraîchir le jeton, Mankomail marque la connexion comme révoquée et la boîte apparaît en erreur. Les nœuds qui ont besoin du compte échouent alors avec credential.capability_missing ou microsoft.access_denied.
• Reconnecter. Connectez de nouveau le même compte — la boîte d'abord (Reconnecter cette boîte dans Boîtes, ou la carte Microsoft 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 Microsoft. Les erreurs levées par les nœuds apparaissent dans le détail de l'étape de l'exécution.

Message ou code	Cause	Que faire
oauth.app_not_configured — Aucune application n'est configurée pour ce fournisseur.	Aucune application Microsoft 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.	La valeur collée n'est pas un GUID (souvent l'identifiant du secret, ou du texte en plus).	Collez l'ID d'application (client) seul.
oauth.encryption_disabled	ENCRYPTION_KEY n'est pas configurée.	Configurez la clé de chiffrement et redémarrez l'instance.
Page Microsoft AADSTS50011	L'URI de redirection inscrite dans Entra diffère de celle qu'envoie Mankomail.	Recopiez l'URI de redirection dans la plateforme Web de l'inscription.
Page Microsoft AADSTS50194	L'application est inscrite en monolocataire.	Passez les types de comptes pris en charge en multilocataire.
Page Microsoft AADSTS65001 / « Approbation d'un administrateur requise »	Le tenant ne laisse pas les utilisateurs consentir à cette autorisation (SharePoint, typiquement).	Un administrateur accorde le consentement dans Autorisations d'API.
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.	Le jeton rendu ne porte pas les autorisations de la capacité demandée.	Relancez la connexion et acceptez toutes les autorisations.
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.exchange_failed	Microsoft a refusé l'échange du code (secret client erroné ou expiré, 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.	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.
microsoft.access_denied	Le compte est connecté mais l'autorisation manque ou a été révoquée.	Reconnectez le compte dans Connexions.
microsoft.auth_failed	Microsoft n'accepte plus le jeton.	Reconnectez le compte dans Connexions.
microsoft.not_found	Le dossier, le fichier, le site ou l'agenda n'existe plus.	Vérifiez la cible du nœud.
microsoft.rejected	Graph a refusé la requête elle-même (format, colonne SharePoint non indexée…).	Vérifiez les paramètres du nœud ; l'étape ne refait pas de tentative.
microsoft.conflict	L'élément a changé depuis sa lecture.	Relisez-le et décidez ; l'étape ne refait pas de tentative.
microsoft.locked	Le fichier est ouvert ou extrait par quelqu'un d'autre.	Rien : l'étape refait des tentatives jusqu'à ce que le fichier soit libéré.
microsoft.storage_full	Le OneDrive ou le site SharePoint est plein.	Libérez de l'espace ou augmentez le quota ; l'étape ne refait pas de tentative.
microsoft.unavailable	Limitation de débit, plafond de bande passante, panne ou erreur réseau.	Rien : l'étape refait automatiquement une tentative.

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

Nœuds qui utilisent cette connexion

• Déposer dans OneDrive — onedrive.upload (capacité files)
• Chercher dans OneDrive — onedrive.search (capacité files)
• Créer un dossier OneDrive — onedrive.create_folder (capacité files)
• Créer un événement Outlook — outlook_calendar.create_event (capacité calendar)
• Trouver un créneau Outlook — outlook_calendar.find_free (capacité calendar)
• SharePoint — sharepoint.api (capacité sharepoint)
• Excel — excel.api (capacité sharepoint)
• Excel — excel.api (capacité files)