Partager via

Autoriser la connexion à Microsoft Graph avec l’authentification unique

  • Article

Les utilisateurs se connectent à Office à l’aide de leur compte Microsoft personnel ou de leur compte Microsoft 365 Éducation ou professionnel. Le meilleur moyen pour un complément Office d’obtenir un accès autorisé à Microsoft Graph est d’utiliser les informations d’identification Office de l’utilisateur. Cela leur permet d’accéder à leurs données Microsoft Graph sans avoir à se connecter une deuxième fois.

Architecture de complément pour l’authentification unique et Microsoft Graph

Outre l’hébergement des pages et du JavaScript de l’application Web, le complément doit également héberger, dans le même nom de domaine complet, une ou plusieurs API Web qui recevront un jeton d’accès à Microsoft Graph et effectueront des requêtes.

Le manifeste du complément contient un <élément WebApplicationInfo> qui fournit des informations importantes sur l’inscription des applications Azure à Office, notamment les autorisations pour Microsoft Graph requises par le complément.

Mode de fonctionnement en cours d’exécution

Le diagramme suivant montre les étapes nécessaires à la connexion et à l’accès à Microsoft Graph. L’ensemble du processus utilise des jetons d’accès OAuth 2.0 et JWT.

Diagramme montrant le processus d’authentification unique.

  1. Le code côté client du complément appelle l’API Office.js getAccessToken. Cela indique à l’hôte Office d’obtenir un jeton d’accès pour le complément.

    Si l’utilisateur n’est pas connecté, l’hôte Office conjointement avec la plateforme d’identités Microsoft fournit une interface utilisateur permettant à l’utilisateur de se connecter et de donner son consentement.

  2. L’hôte Office demande un jeton d’accès à partir de la plateforme d’identités Microsoft.

  3. La plateforme d’identités Microsoft retourne le jeton d’accès A à l’hôte Office. Le jeton d’accès A fournit uniquement l’accès aux propres API côté serveur du complément. Il ne fournit pas l’accès à Microsoft Graph.

  4. L’hôte Office retourne le jeton d’accès A au code côté client du complément. Le code côté client peut désormais effectuer des appels authentifiés aux API côté serveur.

  5. Le code côté client effectue une requête HTTP à une API web côté serveur qui nécessite une authentification. Il inclut le jeton d’accès A comme preuve d’autorisation. Le code côté serveur valide le jeton d’accès A.

  6. Le code côté serveur utilise le flux OAuth 2.0 On-Behalf-Of (OBO) pour demander un nouveau jeton d’accès avec des autorisations sur Microsoft Graph.

  7. La plateforme d’identités Microsoft retourne le nouveau jeton d’accès B avec des autorisations à Microsoft Graph (et un jeton d’actualisation, si le complément demande offline_access autorisation). Le serveur peut éventuellement mettre en cache le jeton d’accès B.

  8. Le code côté serveur effectue une requête à une API Microsoft Graph et inclut le jeton d’accès B avec des autorisations pour Microsoft Graph.

  9. Microsoft Graph retourne les données au code côté serveur.

  10. Le code côté serveur retourne les données au code côté client.

Lors des requêtes suivantes, le code client transmet toujours le jeton d’accès A lors des appels authentifiés au code côté serveur. Le code côté serveur peut mettre en cache le jeton B afin qu’il n’ait pas besoin de le demander à nouveau lors de futurs appels d’API.

Développer un complément authentification unique qui accède à Microsoft Graph

Vous développez un complément qui accède à Microsoft Graph comme vous le feriez pour toute autre application qui utilise l’authentification unique. Pour obtenir une description détaillée, voir Activer l’authentification unique pour les compléments Office. La différence est qu’il est obligatoire que le complément dispose d’une API web côté serveur.

Selon votre langue et votre infrastructure, des bibliothèques peuvent être disponibles pour simplifier le code côté serveur que vous devez rédiger. Votre code côté serveur doit effectuer les opérations suivantes :

  • Validez le jeton d’accès A chaque fois qu’il est passé à partir du code côté client. Pour plus d’informations, voir Valider le jeton d’accès.
  • Lancez le flux On-Behalf-Of (OBO) OAuth 2.0 avec un appel à la plateforme d’identités Microsoft qui inclut le jeton d’accès, certaines métadonnées sur l’utilisateur et les informations d’identification du complément (son ID et son secret). Pour plus d’informations sur le flux OBO, consultez Plateforme d’identités Microsoft et Flux On-Behalf-Of OAuth 2.0.
  • Si vous le souhaitez, une fois le flux terminé, mettez en cache le jeton d’accès B retourné avec des autorisations sur Microsoft Graph. Nous vous conseillons de le faire si le complément effectue plusieurs appels à Microsoft Graph. Pour plus d’informations, consultez Acquérir et mettre en cache des jetons à l’aide de la bibliothèque d’authentification Microsoft (MSAL)
  • Créez une ou plusieurs méthodes d’API web qui obtiennent des données Microsoft Graph en passant le jeton d’accès B (éventuellement mis en cache) à Microsoft Graph.

Pour obtenir des exemples de scénarios et procédures détaillées, consultez les rubriques suivantes :

Distribution de compléments prenant en charge l’authentification unique dans Microsoft AppSource

Lorsqu’un administrateur Microsoft 365 acquiert un complément à partir d’AppSource, l’administrateur peut le redistribuer par le biais d’applications intégrées et accorder le consentement de l’administrateur au complément pour accéder aux étendues Microsoft Graph. Toutefois, il est également possible pour l’utilisateur final d’acquérir le complément directement à partir d’AppSource, auquel cas l’utilisateur doit donner son consentement au complément. Cela peut créer un problème de performances potentiel pour lequel nous avons fourni une solution.

Si votre code passe l’option allowConsentPrompt dans l’appel de getAccessToken, comme OfficeRuntime.auth.getAccessToken( { allowConsentPrompt: true } );, Office peut inviter l’utilisateur à donner son consentement si la plateforme d’identités Microsoft signale à Office que le consentement n’a pas encore été accordé au complément. Toutefois, pour des raisons de sécurité, Office peut uniquement inviter l’utilisateur à donner son consentement à l’étendue Microsoft Graph profile . Office ne peut pas demander le consentement à d’autres étendues Microsoft Graph, pas même User.Read. Cela signifie que si l’utilisateur donne son consentement à l’invite, Office retourne un jeton d’accès. Toutefois, la tentative d’échange du jeton d’accès contre un nouveau jeton d’accès avec des étendues Microsoft Graph supplémentaires échoue avec une erreur AADSTS65001, ce qui signifie que le consentement (aux étendues Microsoft Graph) n’a pas été accordé.

Remarque

La demande de consentement avec { allowConsentPrompt: true } peut toujours échouer même pour l’étendue profile si l’administrateur a désactivé le consentement de l’utilisateur final. Pour plus d’informations, consultez Configurer le consentement des utilisateurs finaux aux applications à l’aide d’Azure Active Directory.

Votre code peut et doit gérer cette erreur en revenant à un autre système d’authentification, qui invite l’utilisateur à donner son consentement aux étendues Microsoft Graph. Pour obtenir des exemples de code, consultez Créer un complément Office Node.js qui utilise l’authentification unique et Créer un complément Office ASP.NET qui utilise l’authentification unique et les exemples auxquels ils sont liés. L’ensemble du processus nécessite plusieurs allers-retours vers la plateforme d’identités Microsoft. Pour éviter cette pénalité de performances, incluez l’option forMSGraphAccess dans l’appel de getAccessToken; par exemple, OfficeRuntime.auth.getAccessToken( { forMSGraphAccess: true } ). Cela signale à Office que votre complément a besoin d’étendues Microsoft Graph. Office demandera à la plateforme d’identités Microsoft de vérifier que le consentement aux étendues Microsoft Graph a déjà été accordé au complément. Si c’est le cas, le jeton d’accès est retourné. Si ce n’est pas le cas, l’appel de getAccessToken retourne l’erreur 13012. Votre code peut gérer cette erreur en revenant immédiatement à un autre système d’authentification, sans effectuer une tentative vouée à l’échec d’échanger des jetons avec la plateforme d’identités Microsoft.

Comme meilleure pratique, passez toujours forMSGraphAccess à getAccessToken quand votre complément sera distribué dans AppSource et a besoin d’étendues Microsoft Graph.

Détails sur l’authentification unique avec un complément Outlook

Si vous développez un complément Outlook qui utilise l’authentification unique et que vous le chargez à des fins de test, Office retourne toujours l’erreur 13012 quand forMSGraphAccess est passé à getAccessToken , même si le consentement de l’administrateur a été accordé. Pour cette raison, vous devez commenter l’option lors duforMSGraphAccess développement d’un complément Outlook. Veillez à supprimer les marques de commentaire de l’option lorsque vous déployez pour la production. Le faux 13012 se produit uniquement lorsque vous chargez une version test dans Outlook.

Pour les compléments Outlook, veillez à activer l’authentification moderne pour la location Microsoft 365. Pour plus d’informations sur la procédure à suivre, voir Activer ou désactiver l’authentification moderne pour Outlook dans Exchange Online.

Google Chrome s’efforce de donner aux utilisateurs plus de contrôle sur leur expérience de navigation. Les utilisateurs pourront bloquer les cookies tiers dans leur navigateur Chrome. Cela empêchera votre complément d’utiliser de tels cookies. Cela peut entraîner des problèmes lorsque le complément authentifie l’utilisateur, par exemple plusieurs demandes d’authentification ou des erreurs.

Pour des expériences d’authentification améliorées, consultez Utilisation de l’état de l’appareil pour une expérience d’authentification unique améliorée sur les navigateurs avec des cookies tiers bloqués.

Pour plus d’informations sur le déploiement de Google Chrome, consultez Un nouveau chemin d’accès pour le bac à sable de confidentialité sur le web.

Voir aussi