Démarrer

Microsoft Graph OAuth : authentifier les boîtes aux lettres Outlook et Microsoft 365 (Guide 2026)

Microsoft Graph OAuth 2026

Microsoft Graph OAuthAuthentifier les boîtes aux lettres Outlook et Microsoft 365

Un guide complet 2026 pour Microsoft Graph OAuth pour les développeurs SaaS. Couvre l'enregistrement des applications Microsoft Entra, les points de terminaison d'autorité, les étendues Mail, les autorisations déléguées vs d'application, le consentement de l'administrateur, le code d'autorisation + PKCE, la rotation des jetons de rafraîchissement, les codes d'erreur AADSTS, et comment Unipile élimine 5 semaines de travail de plomberie OAuth en 5 minutes.

Construisez-le avec Unipile Guide MS Graph
lier_compte_outlook.py
import demandes # Étape 1 : Générer un lien d'authentification hébergé response = requests.poste( "https://apiXXX.unipile.com:XXX /api/v1/hébergé/comptes/lier", en-têtes={"X-API-KEY": clé_api}, json={ "type": "créer", "fournisseurs": ["MICROSOFT"], "api_url": votre_dsn, "expireLe": "2026-12-31T23:59:59Z" } ) # Étape 2 : Rediriger l'utilisateur vers l'URL auth_url = réponse.json()["url"] # Unipile gère l'intégralité du processus OAuth #, comprenant Entra, les oscilloscopes, les jetons et la mise à jour
Microsoft OAuth traité. Boîte aux lettres prête.
Contexte 2026

Pourquoi Microsoft Graph OAuth est non négociable en 2026

Si votre application SaaS lit, envoie ou synchronise des e-mails Outlook ou Microsoft 365, l'authentification OAuth de Microsoft Graph n'est plus facultative. Trois dépréciations majeures ont rendu obsolètes l'authentification de base, les protocoles hérités et les mots de passe d'application. L'authentification OAuth 2.0 via l'API Microsoft Graph est la seule voie prise en charge.

Authentification de base - Totalement obsolète
Microsoft a désactivé l'authentification de base pour Exchange Online en octobre 2022. Cela affecte IMAP, POP3, SMTP, EWS, MAPI, OAB, Outlook Anywhere et RPC sur HTTP. Aucune exception, aucune prolongation de délai de grâce restante.
Désactivé Oct 2022
EWS - Calendrier du coucher du soleil
Les Services web Exchange (EWS) sont en mode maintenance. Microsoft n'a annoncé aucune nouvelle fonctionnalité et recommande de migrer vers Microsoft Graph. Bien qu'il ne soit pas encore complètement désactivé, la création de nouvelles intégrations sur EWS en 2026 serait une décision de dette technique que vous regretteriez.
Mode maintenance
OAuth 2.0 - La norme requise
L'authentification OAuth via Microsoft Graph et Microsoft Entra ID (anciennement Azure AD) est la seule méthode d'authentification officiellement prise en charge pour les applications SaaS en production accédant aux boîtes aux lettres Outlook et Microsoft 365 en 2026. Ce guide couvre l'implémentation complète.
Norme requise
Ce que Microsoft Graph OAuth débloque
Lire, envoyer et synchroniser les boîtes aux lettres Outlook au nom des utilisateurs authentifiés
Accéder aux boîtes aux lettres Microsoft 365 et Outlook.com personnelles avec une seule inscription d'application
Jetons d'actualisation à longue durée de vie avec rotation automatique (pas de réauthentification pour les utilisateurs actifs)
Contrôle granulaire de la portée : demandez uniquement les autorisations dont votre application a réellement besoin
Prise en charge multi-locataire : une inscription d'application dessert tous les locataires clients
Conformité aux stratégies d'accès conditionnel et d'authentification multifacteur de l'entreprise
Flux OAuth

Les 3 flux OAuth pris en charge par Microsoft (et lequel est nécessaire pour les SaaS)

La plateforme d'identité de Microsoft prend en charge plusieurs types d'octroi OAuth 2.0. Choisir le mauvais type est une source courante de perte de temps d'ingénierie. Voici la répartition pour les applications SaaS qui accèdent à la messagerie au nom de leurs utilisateurs.

Recommandé pour le SaaS
Code d'autorisation + PKCE
RFC 6749 Section 4.1 + RFC 7636
L'utilisateur est redirigé vers la page de connexion de Microsoft, s'authentifie et accorde son consentement. Votre application échange le code d'autorisation renvoyé contre des jetons d'accès et de rafraîchissement. Le PKCE (Proof Key for Code Exchange) empêche les attaques par interception de code et est obligatoire pour les clients publics et recommandé pour tous les clients en 2026.
Utilisez ceci pour les applications SaaS accédant aux boîtes aux lettres des utilisateurs
Identifiants client
OAuth 2.0 Section 4.4 (pour les applications uniquement)
Aucune interaction utilisateur. Votre application s'authentifie en tant que telle à l'aide d'un ID client et d'un secret (ou d'un certificat). Nécessite des autorisations d'application (pas d'autorisations déléguées), ce qui signifie qu'un administrateur de locataire doit donner son consentement pour accéder à toutes les boîtes aux lettres de l'organisation. Pas d'écran de consentement utilisateur.
Uniquement pour les outils internes avec accès accordé par l'administrateur
Flux de code d'appareil
Octroi d'autorisation pour appareil OAuth 2.0
Conçu pour les appareils sans navigateur (CLI, IoT, smart TV). L'utilisateur visite une URL sur un autre appareil pour s'authentifier. Non pertinent pour les applications web SaaS où une redirection est possible.
Non applicable aux applications web SaaS standard
Commencez à construire votre flux OAuth Microsoft
Unipile - Enregistrement d'application Microsoft Entra
Configuration étape par étape

Enregistrement d'application Microsoft Entra : 7 étapes

Avant que votre application puisse demander des jetons OAuth, vous avez besoin d'une application enregistrée dans Microsoft Entra ID (anciennement Azure Active Directory). Voici les étapes exactes, y compris les valeurs de champs qui sont importantes et celles qui sont cosmétiques.

1
Créer un enregistrement d'application dans le portail Azure
Naviguer vers portal.azure.com, allez à Microsoft Entra ID (rechercher dans la barre supérieure), puis Enregistrements d'applications, puis cliquez + Nouvelle inscription. Voir le Documentation complète de Microsoft OAuth pour plus de contexte.
Nom
Nom de votre application. C'est ce que les utilisateurs voient sur l'écran de consentement de Microsoft. Utilisez le nom de votre produit, pas un identifiant technique.
Types de comptes pris en charge
Pour un SaaS multi-locataire servant à la fois les utilisateurs professionnels et personnels : sélectionner Comptes dans tout répertoire organisationnel (n'importe quel tenant Microsoft Entra ID - multitenant) et comptes Microsoft personnels. Cela correspond à la /commun point de terminaison d'autorité.
Astuce : Si vous ne servez que les comptes professionnels Microsoft 365 (pas les comptes Outlook.com personnels), sélectionnez uniquement " Multilocataire ". Ceci utilise le /organisations l'autorité et réduit votre surface de consentement. Plus sur les points d'extrémité d'autorité dans la section 4.
2
Configurer les URI de redirection
Après l'inscription, allez à Authentification dans le panneau de gauche. Ajouter une plateforme : sélectionner Web. Ajoutez votre ou vos URI de redirection, l'URL vers laquelle Microsoft redirigera l'utilisateur avec le code d'autorisation.
Type de plateforme
Web pour les applications côté serveur. Utiliser Application monopage (SPA) pour les flux côté client (active PKCE automatiquement).
URI de redirection
Doit être HTTPS en production. Exemple : https://app.yourproduct.com/auth/microsoft/callback. Correspondance exacte requise, toute déviation entraîne AADSTS50011.
URL de déconnexion (facultatif)
Microsoft appellera cette URL lorsque l'utilisateur se déconnectera de n'importe quelle application de son locataire. Facultatif pour les intégrations par e-mail uniquement.
Erreur courante : Les URI localhost sont autorisées pendant le développement (http://localhost:3000/callback) mais les URI de production doivent utiliser HTTPS. Enregistrez les deux séparément.
3
Ajouter des autorisations pour l'API Microsoft Graph
Aller à Permissions API. Cliquer + Ajouter une permission, sélectionner Microsoft Graph, puis Autorisations déléguées. Ajoutez les champs d'application dont votre application a besoin.
Minimum pour lire
Mail.Read, accès_hors_ligne, openid, profil
Pour lire + envoyer
Mail.ReadWrite, Mail.Send, accès_hors_ligne, openid, profil
accès_hors_ligne
Critique. Sans cette portée, Microsoft ne délivre pas de jeton d'actualisation. Vos utilisateurs devront se ré-authentifier toutes les 60 à 90 minutes.
Remarque : L'ajout d'autorisations ici ne les accorde pas, il déclare votre intention. L'utilisateur consent lorsqu'il termine le flux OAuth. Le consentement de l'administrateur est requis pour certains étendues de privilèges supérieurs (voir section 7).
4
Générer un secret client
Aller à Certificats et secrets. Cliquer + Nouveau secret client. Définir une description et une date d'expiration.
Recommandation de péremption
730 jours (24 mois) est le maximum. Réglez un rappel de calendrier 60 jours avant l'expiration, la rotation d'un secret expiré provoque des échecs d'authentification immédiats pour tous les utilisateurs.
Copiez la valeur immédiatement
La valeur secrète n'est affichée qu'une seule fois. Stockez-la dans votre gestionnaire de secrets (par ex. AWS Secrets Manager, HashiCorp Vault, Azure Key Vault). Elle ne sera plus jamais affichée après avoir quitté cette page.
Alternative recommandée : Pour la production, utilisez un certificat au lieu d'un secret client. Les certificats sont plus sécurisés (clé asymétrique), n'expirent jamais par accident et sont privilégiés par Microsoft pour les applications de niveau entreprise.
5
Copiez votre ID client et votre ID de locataire
De la Vue d'ensemble page d'enregistrement de votre application, copiez deux valeurs dont vous aurez besoin dans chaque requête OAuth :
ID d'application (client)
Un UUID qui identifie de manière unique votre enregistrement d'application. Utilisé comme client_id paramètre dans toutes les requêtes d'authentification.
ID d'annuaire (locataire)
L'ID du locataire de votre organisation. Utilisé dans les URL d'autorité à locataire unique. Pour les applications multi-locataires, vous utilisez /commun au lieu de cela, mais conservez cette valeur pour les URL de consentement d'administrateur.
6
Activer les jetons d’identification (facultatif mais recommandé)
De retour Authentification, sous Flux implicite et flux hybrides, vous pouvez activer Jetons d'identification. Cela vous permet de recevoir un JWT contenant les revendications d'identité de l'utilisateur (nom, e-mail, identifiant de locataire) aux côtés du jeton d'accès, ce qui est utile pour les flux d'intégration où vous souhaitez pré-remplir les données du profil utilisateur.
Perspectives 2026 : Pour les flux auth-code purs + PKCE, les jetons d'ID sont retournés via le point de terminaison du jeton, et non le flux implicite. Vous n'avez pas besoin d'activer le flux implicite. Ne l'activez que si vous avez une SPA existante qui ne peut pas utiliser PKCE.
7
Facultatif : Vérifier votre domaine d'éditeur
En Image de marque et propriétés, définissez votre domaine d'éditeur sur le domaine de votre produit. Cela remplace l'étiquette " non vérifié " sur l'écran de consentement par le nom de votre domaine. Pour les applications multi-locataires ciblant des clients d'entreprise, la vérification du réseau de partenaires Microsoft et l'obtention du statut d"" éditeur vérifié " suppriment l'avertissement proéminent " Cette application n'est pas couramment utilisée ».
Domaine de l'éditeur
Un domaine que vous possédez et que vous avez vérifié via un enregistrement TXT ou via le flux de validation de domaine d'App Service.
Éditeur vérifié
Nécessite un identifiant Microsoft Partner Network (MPN) lié à une identité commerciale vérifiée. Prend 1 à 5 jours ouvrables. Améliore considérablement la conversion des clients d'entreprise sur les écrans de consentement.
Simplifiez l'installation : Créez avec Unipile à la place
Points d'extrémité d'autorisation

Choisir le bon point de terminaison d'autorité Microsoft

L'URL d'autorité que vous utilisez dans vos requêtes OAuth détermine quels types de comptes Microsoft peuvent s'authentifier et quels jetons vous recevez. Une erreur à ce niveau entraîne des échecs silencieux où certains utilisateurs ne peuvent pas du tout s'authentifier.

URL d'autorité Accepte Cas d'utilisation Mises en garde
/communLa plupart des SaaS Comptes Microsoft Entra (professionnels/scolaires) et comptes Microsoft personnels (Outlook.com, Hotmail, Live) Logiciel en tant que service multi-locataire desservant tous les utilisateurs Microsoft. Un seul point d'accès gère l'ensemble de votre base d'utilisateurs. Les jetons sont émis par le locataire d'accueil de chaque utilisateur, pas par le vôtre. La validation des jetons doit utiliser l'émetteur spécifique au locataire ou accepter plusieurs émetteurs. Impossible d'appliquer les stratégies d'accès conditionnel.
/organisations Comptes Microsoft Entra ID uniquement (professionnels/scolaires). Aucun compte Microsoft personnel. Logiciel SaaS B2B ciblant uniquement les clients d'entreprise, jamais les utilisateurs grand public d'Outlook.com. Les utilisateurs ayant des comptes Microsoft personnels recevront une erreur. Validation de jeton plus simple (modèle d'émetteur unique acceptable).
consommateurs Comptes Microsoft personnels uniquement (Outlook.com, Hotmail, Live). Applications grand public ciblant les boîtes de réception personnelles. Rare pour les SaaS B2B. Les comptes Microsoft 365 d'entreprise sont rejetés. Inutile pour une offre SaaS destinée aux utilisateurs professionnels.
/{identifiant-du-locataire} Comptes dans un client Microsoft Entra spécifique uniquement. Outils internes à locataire unique (application de votre propre entreprise). Flux de consentement administrateur ciblant un locataire spécifique. Également utilisé dans le modèle d'URL de redirection du consentement administrateur. Chaque autre utilisateur du locataire est rejeté. Approprié uniquement pour les applications internes ou lorsque l'on verrouille délibérément un seul locataire client.
/commun La plupart des SaaS
Accepte Comptes Microsoft Entra (professionnels/scolaires) et comptes Microsoft personnels (Outlook.com, Hotmail, Live)
Cas d'utilisation Logiciel en tant que service multi-locataire desservant tous les utilisateurs Microsoft. Un seul point d'accès gère l'ensemble de votre base d'utilisateurs.
Mises en garde Les jetons sont émis par le locataire d'accueil de chaque utilisateur, pas par le vôtre. La validation des jetons doit utiliser l'émetteur spécifique au locataire ou accepter plusieurs émetteurs. Impossible d'appliquer les stratégies d'accès conditionnel.
/organisations
Accepte Comptes Microsoft Entra ID uniquement (professionnels/scolaires). Aucun compte Microsoft personnel.
Cas d'utilisation Logiciel SaaS B2B ciblant uniquement les clients d'entreprise, jamais les utilisateurs grand public d'Outlook.com.
Mises en garde Les utilisateurs ayant des comptes Microsoft personnels recevront une erreur. Validation de jeton plus simple (modèle d'émetteur unique acceptable).
consommateurs
Accepte Comptes Microsoft personnels uniquement (Outlook.com, Hotmail, Live).
Cas d'utilisation Applications grand public ciblant les boîtes de réception personnelles. Rare pour les SaaS B2B.
Mises en garde Les comptes Microsoft 365 d'entreprise sont rejetés. Inutile pour une offre SaaS destinée aux utilisateurs professionnels.
/{identifiant-du-locataire}
Accepte Comptes dans un client Microsoft Entra spécifique uniquement.
Cas d'utilisation Outils internes à locataire unique (application de votre propre entreprise). Flux de consentement administrateur ciblant un locataire spécifique. Également utilisé dans le modèle d'URL de redirection du consentement administrateur.
Mises en garde Chaque autre utilisateur du locataire est rejeté. Approprié uniquement pour les applications internes ou lorsque l'on verrouille délibérément un seul locataire client.
Note de validation de jeton pour /common : En utilisant le /commun point de terminaison, le Tss la revendication (issuer) dans le JWT sera https://login.microsoftonline.com/{tenantId}/v2.0 où {tenantId} varie par utilisateur. Configurez votre bibliothèque de validation JWT pour accepter n'importe quel émetteur correspondant https://login.microsoftonline.com/{tenantId}/v2.0 plutôt qu'une chaîne d'émetteur fixe.
Portée des e-mails

Microsoft Graph Mail Scopes : Répartition Granulaire

Microsoft Graph utilise des étendues d'autorisation pour contrôler ce que votre application peut faire. Demander trop d'étendues augmente les frictions sur l'écran de consentement et réduit la conversion. En demander trop peu entraîne des erreurs d'exécution. Voici toutes les étendues de courrier que vous devez connaître.

Portée Type Ce qu'il permet Consentement de l'administrateur ?
Mail.Read Délégué Lire tous les messages dans la boîte aux lettres de l'utilisateur authentifié. Comprend les en-têtes, le corps, les pièces jointes. Lecture seule - ne peut pas modifier ni envoyer. Utilisateur
Mail.ReadBasic Délégué Lire les propriétés limitées du message : sujet, expéditeur, destinataires, date. Impossible de lire le corps du message ou les pièces jointes. Utile pour la liste d'e-mails légère sans accès au contenu complet. Utilisateur
Mail.ReadWrite Délégué Lire et modifier tous les messages. Inclut la création, la mise à jour et la suppression de messages et de dossiers. Sur-ensemble de Mail.Read – ne demandez pas les deux. Utilisateur
Mail.Send Délégué Envoyer des e-mails en tant qu’utilisateur authentifié. Requis même si vous disposez également de Mail.ReadWrite - l’envoi est une autorisation distincte dans Microsoft Graph. Utilisateur
Mail.Recharge.Partagé Délégué Lire les e-mails dans les boîtes aux lettres partagées ou les boîtes aux lettres d'autres utilisateurs auxquels l'utilisateur authentifié a été autorisé à accéder. Pas pour lire la boîte aux lettres de l'utilisateur lui-même. Utilisateur
Mail.ReadWrite.Shared Délégué Lire et modifier les courriels dans les boîtes aux lettres partagées auxquelles l'utilisateur a accès. Utilisateur
Courriel.Envoyer.Partager Délégué Envoyer des e-mails à partir de boîtes aux lettres partagées ou "envoyer au nom de" un autre utilisateur (si cet utilisateur a accordé l'accès). Utilisateur
accès_hors_ligne Délégué Demande à Microsoft d'émettre un jeton de mise à jour. Sans cela, vous ne recevez qu'un jeton d'accès de courte durée, sans possibilité de le renouveler. Toujours requis pour les applications SaaS. Utilisateur
openid Délégué Retourne un jeton d'identification avec les informations d'identité de base de l'utilisateur. Nécessaire si vous souhaitez savoir qui s'est authentifié sans effectuer d'appel API /me distinct. Utilisateur
profil Délégué Ajoute les revendications name et preferred_username au jeton d'identification. Généralement inclus avec openid. Utilisateur
Mail.Lire (App) Application Lire tous les e-mails dans toutes les boîtes aux lettres du locataire sans interaction de l'utilisateur. Utilisé par les services démons. Nécessite le consentement de l'administrateur du locataire. Administrateur requis
Mail.ReadWrite (Application) Application Lire et écrire tous les e-mails dans toutes les boîtes aux lettres des locataires. Permission très large. Uniquement pour les outils internes de confiance avec l'approbation explicite de l'administrateur du locataire. Administrateur requis
Mail.Read Délégué
Lire tous les messages dans la boîte aux lettres de l'utilisateur authentifié. Comprend les en-têtes, le corps, les pièces jointes. Lecture seule - ne peut pas modifier ni envoyer.
Consentement de l'utilisateur
Mail.ReadBasic Délégué
Lire les propriétés limitées du message : sujet, expéditeur, destinataires, date. Impossible de lire le corps du message ou les pièces jointes. Utile pour la liste d'e-mails légère sans accès au contenu complet.
Consentement de l'utilisateur
Mail.ReadWrite Délégué
Lire et modifier tous les messages. Inclut la création, la mise à jour et la suppression de messages et de dossiers. Sur-ensemble de Mail.Read – ne demandez pas les deux.
Consentement de l'utilisateur
Mail.Send Délégué
Envoyer des e-mails en tant qu’utilisateur authentifié. Requis même si vous disposez également de Mail.ReadWrite - l’envoi est une autorisation distincte dans Microsoft Graph.
Consentement de l'utilisateur
Mail.Recharge.Partagé Délégué
Lire les e-mails dans les boîtes aux lettres partagées ou les boîtes aux lettres d'autres utilisateurs auxquels l'utilisateur authentifié a été autorisé à accéder. Pas pour lire la boîte aux lettres de l'utilisateur lui-même.
Consentement de l'utilisateur
Mail.ReadWrite.Shared Délégué
Lire et modifier les courriels dans les boîtes aux lettres partagées auxquelles l'utilisateur a accès.
Consentement de l'utilisateur
Courriel.Envoyer.Partager Délégué
Envoyer des e-mails à partir de boîtes aux lettres partagées ou "envoyer au nom de" un autre utilisateur (si cet utilisateur a accordé l'accès).
Consentement de l'utilisateur
accès_hors_ligne Délégué
Demande à Microsoft d'émettre un jeton de mise à jour. Sans cela, vous ne recevez qu'un jeton d'accès de courte durée, sans possibilité de le renouveler. Toujours requis pour les applications SaaS.
Consentement de l'utilisateur
openid Délégué
Retourne un jeton d'identification avec les informations d'identité de base de l'utilisateur. Nécessaire si vous souhaitez savoir qui s'est authentifié sans effectuer d'appel API /me distinct.
Consentement de l'utilisateur
profil Délégué
Ajoute les revendications name et preferred_username au jeton d'identification. Généralement inclus avec openid.
Consentement de l'utilisateur
Mail.Lire (App) Application
Lire tous les e-mails dans toutes les boîtes aux lettres du locataire sans interaction de l'utilisateur. Utilisé par les services démons. Nécessite le consentement de l'administrateur du locataire.
Administrateur requis
Mail.ReadWrite (Application) Application
Lire et écrire tous les e-mails dans toutes les boîtes aux lettres des locataires. Permission très large. Uniquement pour les outils internes de confiance avec l'approbation explicite de l'administrateur du locataire.
Administrateur requis
Portée minimale définie : lecteur de boîte de réception
scope=Mail.Readaccès hors ligneopenidprofil
Lire les messages, actualiser les jetons, identité utilisateur. Aucune capacité d'écriture ou d'envoi.
Portée standard définie : intégration complète des e-mails
scope=Mail.ReadWriteMail.Sendoffline_accessopenidprofile
Lire, écrire, envoyer. L'ensemble le plus courant pour les intégrations CRM et les outils de vente.
Voir le guide complet de l'API par courrier électronique
Modèle d'autorisations

Autorisations déléguées vs autorisations d'application : Quand utiliser chacune

Microsoft Graph utilise deux modèles d'autorisations fondamentalement différents. La plupart des développeurs SaaS optent par défaut pour le mauvais, ce qui entraîne des exigences inutiles de consentement administrateur et une expérience utilisateur dégradée. Voici exactement quand utiliser chacun.

Permissions déléguées
Agir au nom de l'utilisateur connecté
L'application accède à Microsoft Graph en utilisant l'identité de l'utilisateur authentifié. L'application ne peut faire que ce que l'utilisateur lui-même pourrait faire. Si l'utilisateur ne peut pas lire un dossier, votre application ne le peut pas non plus.
L'utilisateur consent pendant le flux OAuth - aucun administrateur requis pour les scopes standard
L'accès est limité à la boîte aux lettres de chaque utilisateur individuel.
Les utilisateurs peuvent révoquer l'accès à tout moment depuis les paramètres de leur compte Microsoft
Respecte les autorisations au niveau de l'utilisateur, les attributions de rôles et les stratégies d'accès aux boîtes aux lettres
Utilisez ceci pour les applications SaaS où chaque utilisateur s'authentifie individuellement
Permissions de l'application
Agir en tant que l'application elle-même
L'application accède à Microsoft Graph sans qu'aucun utilisateur ne soit présent. Utilisée pour les services d'arrière-plan, les démons et les flux de travail automatisés. L'application s'authentifie à l'aide de ses propres informations d'identification (flux d'informations d'identification client).
Nécessite le consentement de l'administrateur du locataire - une barrière importante pour les utilisateurs externes
L'accès est global pour le locataire – peut lire TOUTES les boîtes aux lettres une fois que l'administrateur a donné son consentement
Aucune connexion utilisateur interactive requise - fonctionne pour l'automatisation sans tête
Convient aux outils informatiques internes où l'administrateur de votre organisation contrôle le déploiement
Uniquement pour les outils internes où l'administrateur de votre organisation accorde un accès complet au locataire
La règle de décision SaaS
Si vous construisez un produit utilisé par des clients externes qui se connecte individuellement, utilise Autorisations déléguées. Chaque client s'authentifie avec son propre compte Microsoft, accepte les étendues de votre application, et votre application fonctionne au nom de cet utilisateur authentifié. Les autorisations d'application nécessitent qu'un administrateur de locataire pré-approuve votre application pour l'ensemble de leur organisation, une étape qui tue la conversion dans un parcours SaaS en libre-service. La seule exception est si vous créez un outil d'entreprise interne déployé par votre propre équipe informatique dans votre propre locataire.
Solution complète

Code d'authentification + PKCE : exemples cURL étape par étape

Voici le flux d'autorisation OAuth 2.0 avec PKCE complet de Microsoft Graph, de la génération du code verifier à l'échange des jetons. Ce sont des exemples de qualité de production que vous pouvez adapter directement à votre stack.

Étape 1 sur 4 - Générer les paramètres PKCE
Générer code_verifier et code_challenge
PKCE fonctionne en générant un secret aléatoire (code_verifier), puis un hachage SHA-256 de celui-ci (code_challenge). Vous envoyez le défi à l'étape 2, et le vérificateur à l'étape 4. Microsoft vérifie qu'ils correspondent, empêchant ainsi l'interception du code.
pkce_generate.py
import système, base64, hashlib # 1. Générer un code_verifier (43 à 128 caractères, codage Base64 compatible URL) code_verifier = base64.urlsafe_b64encode( os.urandom(32) ).décoder('utf-8').enlever les espaces de fin('=') # 2. Générer code_challenge = BASE64URL(SHA256(code_verifier)) défi_code = base64.urlsafe_b64encode( hashlib.sha256(code_verifier.encoder('utf-8')).résumé() ).décoder('utf-8').enlever les espaces de fin('=') # Enregistrez la valeur de « code_verifier » dans la session — vous en aurez besoin à l'étape 4 # Envoyer le code_challenge dans l'URL d'autorisation
Étape 2 de 4 - Demande d'autorisation
Construire l'URL /authorize et rediriger l'utilisateur
Redirigez le navigateur de l'utilisateur vers le point de terminaison d'autorisation de Microsoft. L'utilisateur voit la page de connexion Microsoft, s'authentifie et consent aux étendues de votre application. Microsoft redirige ensuite vers votre redirect_uri avec un code d'autorisation.
client_id
Votre ID d'application (client) de l'enregistrement d'application Entra
type_de_réponse
code - demande un code d'autorisation
uri_de_redirection
Doit correspondre exactement à un URI enregistré dans votre application Entra. Encodé en URL.
portée
Liste séparée par des espaces. Inclure toujours accès_hors_ligne pour les jetons de rafraîchissement.
état
Valeur opaque que vous générez. Renvoyée inchangée dans la fonction de rappel. Utilisez-la pour empêcher les CSRF et restaurer l'état de l'interface utilisateur.
défi_code
La valeur BASE64URL(SHA256(code_verifier)) de l'étape 1.
méthode_défi_code
S256 - toujours utiliser SHA-256, jamais en clair
authorize_url.sh
# Générer l'URL d'autorisation (format optimisé pour la lisibilité) URL_AUTH="https://login.microsoftonline.com/common/oauth2/v2.0/authorize ?client_id=VOTRE_CLIENT_ID &type_de_réponse=code &redirect;_uri=https://3aapp.com/3aauth/3ams/3acb &scope;=Mail.ReadWriteMail.Sendoffline_access &state=VALEUR_ETAT_ALEATOIRE &défi_code=VOTRE_DÉFI_CODE &code_challenge_method=S256" # Rediriger l'utilisateur vers $AUTH_URL # : Microsoft gère la connexion, l'authentification à plusieurs facteurs (MFA) et l'écran de consentement # En cas de réussite : redirect_uri?code=AUTH_CODE&state;=...
Étape 3 sur 4 - Gérer le rappel
Recevez le code d'autorisation à votre redirect_uri
Microsoft redirige vers votre redirect_uri avec un code paramètre de requête. Valider le état Le paramètre correspond à ce que vous avez envoyé. Le code expire dans 10 minutes - échangez-le immédiatement à l'étape 4.
Étape 4 sur 4 - Échange de jetons
Échanger le code d'autorisation contre des jetons d'accès + d'actualisation
POSTez au point de terminaison du jeton avec le code et votre code_verifier. Microsoft renvoie un jeton d'accès (valide pendant environ 60 à 90 minutes) et un jeton de rafraîchissement (de longue durée). Stockez les deux en toute sécurité.
token_exchange.sh
Code d'autorisation d'échange # pour les jetons curl -X POST "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type : application/x-www-form-urlencoded" \ -d "client_id=VOTRE_CLIENT_ID" \ -d "client_secret=VOTRE_CLIENT_SECRET" \ -d "grant_type=authorization_code" \ -d "code=AUTH_CODE_FROM_CALLBACK" \ -d "redirect_uri=https://app.com/auth/ms/cb" \ -d "code_verifier=VOTRE_CODE_VERIFICATEUR" \ -d "scope=Mail.ReadWrite Mail.Send offline_access"
Retours : access_token, refresh_token, expires_in, scope
token_response.json
{ "type_de_jeton": "Porteur", "portée": "Mail.ReadWrite Mail.Send offline_access", "expire_dans": 3600, "jeton_d'accès": "eyJ0eXAiOiJKV1Qi...", "jeton_rafraîchissement": "0.ARoAi7W...", "jeton_identifiant": "eyJ0eXAi..." }
Cycle de vie du jeton

Gestion des jetons de rafraîchissement : rotation, expiration et accès conditionnel

Les jetons d’actualisation Microsoft Graph sont de longue durée mais pas permanents. Plusieurs conditions peuvent les invalider silencieusement. Comprendre ces cas limites est ce qui distingue une intégration Microsoft OAuth de qualité de production d’une intégration qui échoue aléatoirement pour les utilisateurs d’entreprise.

Expiration après 90 jours d'inactivité
Les jetons de rafraîchissement de Microsoft expirent après 90 jours d'inactivité. Si un utilisateur n'utilise pas votre application pendant 90 jours, son jeton de rafraîchissement devient invalide et il doit se réauthentifier. Il n'y a aucun moyen de prolonger cela sans interaction de l'utilisateur. Gérez toujours grant_invalide En cas d'erreur, inviter à une nouvelle authentification.
Modifications des stratégies d'accès conditionnel
Les locataires d'entreprise utilisent des stratégies d'accès conditionnel (exigences MFA, conformité des appareils, restrictions de localisation). Si une stratégie change après qu'un utilisateur s'est authentifié, son jeton de rafraîchissement peut être invalidé à la prochaine utilisation. Il s'agit d'une décision côté client - vous ne pouvez pas la contrôler ni la prévoir. Propagez toujours les erreurs d'authentification aux utilisateurs avec une invite de réauthentification claire.
Rotation des jetons d'actualisation
Lorsque vous utilisez un jeton de rafraîchissement pour obtenir un nouveau jeton d'accès, Microsoft peut émettre un nouveau jeton de rafraîchissement. Enregistrez toujours le nouveau jeton de rafraîchissement de la réponse, en remplaçant l'ancien. Si vous continuez à utiliser l'ancien jeton de rafraîchissement après qu'il a été mis à jour, vous finirez par atteindre un grant_invalide erreur.
Révocation de l'administrateur
Un administrateur de locataire peut révoquer tous les jetons de rafraîchissement pour un utilisateur ou pour l'ensemble de l'organisation à tout moment (par exemple, lorsqu'un employé quitte l'entreprise ou lors d'un incident de sécurité). Votre application reçoit grant_invalide. Ceci est un comportement attendu - gérez-le en marquant le compte lié comme nécessitant une ré-autorisation.
refresh_token.sh
# Actualiser le jeton d'accès à l'aide du jeton d'actualisation enregistré curl -X POST "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type : application/x-www-form-urlencoded" \ -d "client_id=VOTRE_CLIENT_ID" \ -d "client_secret=VOTRE_CLIENT_SECRET" \ -d "grant_type=refresh_token" \ -d "refresh_token=TOKEN_DE_RAFFRAÎCHISSEMENT_ENREGISTRÉ" \ -d "scope=Mail.ReadWrite Mail.Send offline_access" # Vérifiez TOUJOURS si la réponse contient un nouveau refresh_token. # Si présent, remplacez immédiatement celui qui est stocké. # Si vous obtenez une erreur « invalid_grant », demandez à l'utilisateur de se réauthentifier.
Dépannage

Erreurs courantes AADSTS décodées

Les erreurs Microsoft Graph OAuth suivent un schéma cohérent de code d'erreur AADSTS. Voici les plus courantes que vous rencontrerez lors du développement et de la production, avec leurs causes profondes exactes et leurs correctifs.

Code d'erreur Ce que cela signifie Cause principale et correction
AADSTS65001 Le consentement n'a pas été accordé pour une ou plusieurs des portées demandées L'utilisateur n'a pas consenti aux étendues de votre application, ou un administrateur de locataire a bloqué le consentement de l'utilisateur pour votre application. Correction : Inclure consentement dans votre URL d'autorisation pour forcer un écran de consentement réinitialisé, ou envoyer l'URL de consentement de l'administrateur à l'administrateur de locataire.
Ajoutez prompt=consentement ou demandez le consentement de l'administrateur
AADSTS50011 Incompatibilité de l'URI de redirection Le uri_de_redirection Dans votre requête, l'URI de redirection ne correspond exactement à aucun URI de redirection enregistré dans votre inscription d'application Entra. Même une différence de barre oblique finale suffit. Correction : Copiez l'URI exact de votre inscription d'application Entra et utilisez-le tel quel.
Correction : correspondance exacte de l'URI dans l'enregistrement d'application Entra
AADSTS700016 Application introuvable dans le tenant Le client_id n'existe pas dans le locataire auquel vous vous authentifiez. Courant lorsque vous utilisez une autorité spécifique à un locataire (/{identifiant-du-locataire}) pour une application multi-locataire. Correction : Utiliser /commun ou /organisations autorité pour les applications multi-locataires.
Correction : passer à l'autorité /common ou /organizations
AADSTS90099 Application non autorisée dans ce locataire (consentement requis) L'application existe mais n'a pas été consentie dans le locataire de l'utilisateur. Diffère de AADSTS65001 en ce que toute l'application est bloquée, et pas seulement des étendues spécifiques. Correction : Envoyez l'URL de consentement de l'administrateur à l'administrateur informatique du client.
Correction : URL de consentement admin vers l'admin du client
AADSTS70011 Le don fourni est invalide ou expiré Le jeton d'actualisation ou le code d'autorisation a expiré ou a été révoqué. Les codes d'autorisation expirent dans les 10 minutes. Les jetons d'actualisation expirent après 90 jours d'inactivité ou après révocation par l'administrateur. Correction : Invitez l'utilisateur à se réauthentifier depuis le début du flux OAuth.
Correction : ré-authentification complète du prompt
AADSTS50076 L'authentification multifacteur est requise par la stratégie d'accès conditionnel Le locataire de l'utilisateur nécessite l'authentification multifacteur pour votre application. C'est une décision côté client appliquée par l'administrateur du locataire. Votre application ne peut pas la contourner. L'utilisateur doit terminer l'MFA. Si vous utilisez le flux de code d'autorisation, Microsoft affichera automatiquement l'invite MFA dans le navigateur. Des problèmes surviennent dans les flux automatisés (informations d'identification client) qui ne peuvent pas terminer l'MFA.
Attendu : l'utilisateur doit effectuer l'authentification multifacteur
AADSTS50020 Le compte utilisateur du fournisseur d'identité externe n'existe pas dans le locataire L'utilisateur essaie de s'authentifier avec un compte Microsoft personnel dans un répertoire qui n'autorise que les comptes professionnels, ou vice versa. Correction : Vérifiez votre point de terminaison d'autorité - si vous utilisez /organisations, les comptes personnels ne peuvent pas s'authentifier. Basculez vers /commun si vous avez besoin des deux.
Corriger : changer l'autorité à /common
AADSTS53003 Accès bloqué par la stratégie d'accès conditionnel La stratégie d'accès conditionnel du locataire a complètement bloqué cette tentative d'authentification (par exemple, pays bloqué, appareil non géré, application bloquée). Il s'agit d'une décision côté client. Vous ne pouvez pas la substituer. Affichez l'erreur à l'utilisateur et conseillez-lui de contacter son administrateur informatique.
Côté client : conseillez à l'utilisateur de contacter l'administrateur informatique
Laissez Unipile s'occuper de tout cela pour vous
L'alternative Unipile

Évitez 5 semaines de plomberie OAuth avec Unipile

Tout dans ce guide - enregistrement d'applications Entra, points de terminaison d'autorité, sélection des étendues, PKCE, rotation des jetons, gestion des erreurs AADSTS - représente du temps d'ingénierie qui n'avance pas votre produit. Unipile gère l'intégralité de la pile OAuth Microsoft Graph en tant que service géré, ainsi votre équipe écrit un appel d'API au lieu de 500 lignes de code OAuth.

Le construire soi-même
Enregistrement et configuration de l'application Entra
Implémentation PKCE et génération de défi de code
Stockage, rotation et gestion de l'expiration des jetons d'actualisation
Flux de consentement de l'administrateur pour les clients professionnels
Gestion des erreurs et invites de ré-authentification AADSTS
Rotation de secret client avant expiration
Traitement des exceptions d'accès conditionnel par locataire
Piles OAuth séparées pour les fournisseurs Gmail et IMAP
En utilisant Unipile
Un POST pour générer un lien d'authentification hébergé
Unipile gère automatiquement le PKCE, les jetons et le rafraîchissement
Les tokens ne sont jamais stockés dans votre base de données - Unipile s'en charge
Même API pour les comptes Microsoft, Gmail et IMAP
Notifications par webhook lorsque les comptes nécessitent une réauthentification
Écran de consentement personnalisé avec vos propres identifiants d'application Entra
Expédiez votre intégration de messagerie en quelques heures, pas en quelques semaines.
Comment fonctionne l'authentification OAuth Microsoft d'Unipile
Votre backend appelle un point de terminaison pour générer un lien d'authentification hébergé. Votre utilisateur clique dessus, s'authentifie auprès de Microsoft, et Unipile gère l'intégralité du flux OAuth : redirection Entra, gestion des scopes, échange de jetons et rafraîchissement. Le compte lié est alors disponible via l'API de messagerie unifiée d'Unipile.
unipile_microsoft_oauth.py
import demandes URL_API_UNIPILE = "https://apiXXX.unipile.com:XXX" CLÉ_API_UNIPILE = "votre-api-clé" # Étape 1 : Générer un lien d'authentification hébergé pour Microsoft response = requests.poste( "{UNIPILE_API_URL}/api/v1/hosted/accounts/link", en-têtes={ "X-API-KEY": UNIPILE_API_KEY, "Content-Type": "application/json" }, json={ "type": "créer", "fournisseurs": ["MICROSOFT"], "api_url": UNIPILE_API_URL, "expireLe": "2026-12-31T23:59:59Z", # Facultatif : associer ce lien à un utilisateur spécifique "nom": "id_utilisateur_123", # (facultatif) : recevoir une notification lorsque le compte est associé "url_de_notification": "https://app.yourproduct.com/webhooks/account-linked" } ) # Étape 2 : Redirigez votre utilisateur vers cette URL hébergé_url_authentification = réponse.json()["url"] Exemple # : https://account.unipile.com/[encoded-token] # Gestion des piles : redirection Entra, écran de consentement, PKCE, Échange de jetons #, actualisation du stockage des jetons, gestion de la portée # Étape 3 : Une fois l'authentification effectuée, utilisez l'API de messagerie d'Unipile pour lire/envoyer des e-mails courriels = demandes.obtenir( f"{UNIPILE_API_URL}/api/v1/emails", en-têtes={"X-API-KEY": {UNIPILE_API_KEY}, params={"account_id": "identifiant-compte-lie"} )
Microsoft OAuth terminé. Boîte aux lettres disponible via l'API unifiée.
Flux d'authentification hébergé
Unipile héberge l'écran de consentement OAuth. Vos utilisateurs voient un flux élégant et marqué. Aucune maintenance de l'URI de redirection, pas de problèmes CORS, pas de jonglage d'URL entre localhost et la production.
Gestion des jetons
Unipile stocke et fait pivoter les jetons OAuth Microsoft en votre nom. La rotation des jetons d'actualisation, la surveillance de l'inactivité sur 90 jours et les notifications de réauthentification sont gérées automatiquement.
API d'e-mail unifiée
Après la liaison, les boîtes aux lettres Microsoft, Gmail et IMAP répondent aux mêmes points d'extrémité de messagerie Unipile. Une intégration dessert les trois fournisseurs.
Vos propres identifiants Entra
Configurez vos propres identifiants d'application Microsoft Entra dans le tableau de bord Unipile. Vos utilisateurs verront le nom de votre application sur l'écran de consentement de Microsoft, et non celui d'Unipile.
Notifications par webhook
Recevez un webhook lorsqu'un compte lié nécessite une réauthentification (jeton d'actualisation expiré, révocation par l'administrateur, changement de stratégie d'accès conditionnel). Affichez immédiatement l'invite de réauthentification dans votre produit.
Lire, envoyer et synchroniser
Après l'authentification OAuth de Microsoft via Unipile, vous pouvez lire des e-mails, envoyer des e-mails, synchroniser des conversations, gérer des dossiers et traiter des pièces jointes – le tout via l'API unifiée de messagerie d'Unipile. Aucun client Microsoft Graph séparé n'est nécessaire.
Comment fonctionne Unipile
Unipile est un intermédiaire technique indépendant qui agit pour le compte de chaque utilisateur authentifié via des jetons OAuth émis par Microsoft. Lorsqu'un utilisateur connecte sa boîte aux lettres Outlook ou Microsoft 365, Unipile opère exclusivement en utilisant les autorisations déléguées de cet utilisateur. Unipile n'est affilié, approuvé ou parrainé par Microsoft. Nous utilisons l'API publique Microsoft Graph au nom des utilisateurs finaux authentifiés. Chaque compte opère dans le cadre de l'identité Microsoft Entra de cet utilisateur et des stratégies d'accès conditionnel de son organisation.
Commencez à construire votre flux OAuth Microsoft Guide de messagerie MS Graph
FAQ

Questions fréquemment posées

Les questions les plus fréquentes sur l'authentification OAuth de Microsoft Graph pour l'intégration d'e-mails, de la sélection des étendues à la gestion du cycle de vie des jetons en passant par les flux de consentement d'entreprise.

01
Microsoft Graph OAuth fonctionne-t-il pour les comptes Outlook.com et Microsoft 365 ?
Oui. En utilisant le /commun point de terminaison d'autorité, qu'une seule inscription d'application Microsoft Entra gère l'authentification des comptes Outlook.com personnels et des comptes professionnels/scolaires Microsoft 365. La clé est de sélectionner "Comptes dans n'importe quel répertoire d'organisation et comptes Microsoft personnels" lors de l'inscription de votre application dans le portail Azure.
02
Que deviennent les jetons OAuth lorsqu'un utilisateur de Microsoft 365 quitte son entreprise ?
Lorsqu'un administrateur informatique désactive ou supprime un compte d'utilisateur dans Microsoft Entra ID, tous les jetons de rafraîchissement de cet utilisateur sont immédiatement révoqués. Votre prochaine tentative de rafraîchissement de jeton renvoie un grant_invalide Erreur. Gérez ceci avec élégance : marquez le compte lié comme nécessitant une réauthentification et affichez une invite de réauthentification claire dans votre produit. C'est un comportement attendu - une décision côté client échappant à votre contrôle.
03
Le consentement de l'administrateur est-il requis pour lire les e-mails Outlook via l'authentification OAuth de Microsoft Graph ?
Non, pour les autorisations déléguées standard. Mail.Read, Mail.ReadWrite, ou encore Mail.Send sont des scopes de consentement utilisateur - les utilisateurs individuels peuvent les approuver lors du flux OAuth. Le consentement de l'administrateur n'est requis que pour les permissions d'application ou les scopes à privilèges élevés comme `Utilisateur.Lire.Tous`. Certains locataires d'entreprise configurent des stratégies qui bloquent tout consentement d'application tierce - c'est une décision côté client.
04
La durée de vie des jetons d'actualisation de Microsoft Graph varie.
Les jetons d'actualisation expirent après 90 jours d'inactivité. Tant que votre application utilise régulièrement le jeton d'actualisation (ce qui se produit automatiquement lors de l'actualisation des jetons d'accès avant leur expiration toutes les 60 à 90 minutes), le jeton d'actualisation reste valide. Les modifications de la stratégie d'accès conditionnel, les réinitialisations de mot de passe ou la révocation par un administrateur peuvent les invalider prématurément. Gérez toujours grant_invalide erreurs et remplacer les anciens jetons de rafraîchissement par le nouveau retourné dans chaque réponse de jeton.
05
Quelle est la différence entre AADSTS65001 et AADSTS90099 ?
AADSTS65001: L'utilisateur n'a pas encore consenti à une ou plusieurs étendues spécifiques. Correction : ajouter consentement vers votre URL d'autorisation pour forcer un nouvel écran de consentement. AADSTS90099L'application entière n'a pas été autorisée dans ce locataire. L'administrateur du locataire doit pré-approuver votre application. Envoyez l'URL de consentement de l'administrateur à l'administrateur informatique du client. Les deux erreurs sont courantes dans les scénarios d'entreprise où les locataires restreignent le consentement des utilisateurs.
06
Puis-je utiliser la même inscription à une application Entra pour lire et envoyer des e-mails ?
Oui. Demander les deux Mail.ReadWrite et Mail.Send dans le même portée de chaîne. Notez que Mail.ReadWrite et Mail.Send sont des étendues séparées - avoir un accès en lecture/écriture ne vous accorde pas automatiquement l'autorisation d'envoi. Incluez toujours accès_hors_ligne pour vous assurer de recevoir un jeton de rafraîchissement. Voir le Page de l'API de messagerie pour les détails de mise en œuvre.
07
Unipile stocke-t-il les jetons d'authentification OAuth de Microsoft dans ma base de données ?
Non. Lorsque vous utilisez le flux d'authentification Microsoft hébergé par Unipile, Unipile gère tous les jetons OAuth pour vous. Votre application ne manipule jamais directement les jetons d'accès ou de rafraîchissement Microsoft. Vous interagissez avec les comptes liés exclusivement via l'API d'e-mail unifiée d'Unipile en utilisant votre clé d'API Unipile. Cela élimine les exigences de stockage, de rotation et de sécurité des jetons de votre propre infrastructure.
08
Unipile est-il affilié à Microsoft ?
Non. Unipile n'est pas affilié, approuvé ou sponsorisé par Microsoft. Unipile est un intermédiaire technique indépendant qui utilise l'API Microsoft Graph publique pour le compte des utilisateurs finaux authentifiés. Chaque intégration fonctionne via des jetons OAuth émis par Microsoft sous l'identité de l'utilisateur et les stratégies d'accès conditionnel de son organisation. Microsoft Graph et Microsoft Entra sont des marques commerciales de Microsoft Corporation.
Vous avez encore des questions ? Notre équipe peut vous guider à travers l'authentification OAuth de Microsoft Graph pour votre cas d'utilisation spécifique.
fr_FRFR
en_USEN es_ESES de_DEDE it_ITIT pt_BRBR nl_NLNL pl_PLPL tr_TRTR fr_FRFR