Applications Microsoft Entra pour les compléments Office et l’authentification unique

  • 8 minutes

Les outils de développement fournis par Microsoft pour créer des compléments Office avec ASP.NET ou Node.js des utilitaires inclus pour inscrire l’application Microsoft Entra requise. Cet outil, Configurer l'authentification unique, simplifie non seulement l’inscription de l’application, mais également la configuration de votre station de travail de développeur.

Dans cette unité, vous allez apprendre à créer l’inscription de l’application Microsoft Entra pour un complément Office qui implémente l’authentification unique (SSO). Vous découvrirez également des meilleures pratiques recommandées par Microsoft lors de la création de compléments Office qui implémentent l’authentification unique.

Inscrire une application Microsoft Entra pour l’authentification unique du complément Office

Examinons les conditions requises pour l’inscription d’une application Microsoft Entra utilisée par un complément Office qui implémente l’authentification unique.

Inscription de l’application Microsoft Entra

La première étape consiste à inscrire une application Microsoft Entra dans le centre d’administration Microsoft Entra (https://aad.portal.azure.com).

Lors de l’inscription de l’application, veillez à définir les types de comptes pris en charge sur Comptes dans n’importe quelle application d’annuaire d’organisation (n’importe quel annuaire Microsoft Entra - Multilocataire).

Importante

Les applications d’un complément Office ne peuvent pas être un client unique. mais multitenant.

Authentification

L'étape suivante consiste à configurer les paramètres d’authentification de l’application.

Votre application doit avoir au moins deux URIs répertoriées :

  • une page du complément, telle que l’URL de la page HTML du volet des tâches.
  • page de retour, telle que la page fallbackauthdialoghtml

Les deux options de jeton du Flux d’octroi implicite et hybride doivent être activées, car les compléments Office sont généralement des applications côté client :

  • Jetons d’accès (utilisés pour les flux implicites)
  • Jetons d’ID (utilisés pour les flux implicites et hybrides).

Capture d’écran des paramètres d’authentification de l’application.

Autorisations de l’API

Une autre partie importante de l’application Microsoft Entra est les autorisations dont elle a besoin pour fonctionner.

Chaque application doit avoir les autorisations OpenID openid et profile. Certaines bibliothèques nécessitent des autorisations supplémentaires. Par exemple, Microsoft Authentication Library pour .NET nécessite l’autorisation office_access.

Si votre complément a besoin d’autorisations pour Microsoft Graph, elles doivent également être ajoutées ici.

Bien que ce ne soit pas obligatoire, lors de l’inscription de l’application, en tant qu’administrateur, vous pouvez approuver préalablement ces autorisations au nom de tous les utilisateurs de votre client. Cela simplifie le flux d’authentification de sorte que les utilisateurs n’ont pas à approuver le complément pour la première utilisation.

Capture d’écran des autorisations ajoutées.

Exposer une API

Votre application doit exposer ses propres autorisations aux clients Microsoft Entra ID et Office. Dans l’écran Exposer une API , définissez l’URI ID d’application. Par défaut, c’est api://<APP_ID>. Vous devez toutefois le mettre à jour pour inclure le domaine sur lequel la base de codes de votre complément est hébergé.

Incluez l’URL avant la partie <APP_ID> de l’URI. Par exemple : api://addin.contoso.com/<APP_UD>. Ce domaine doit correspondre au domaine à partir duquel toutes les ressources définies dans le fichier manifest.xml de votre complément sont servies.

L’étape suivante consiste à exposer une autorisation, également appelée Étendue. Cette étendue, access_as_user, sera utilisée par les clients Office pour indiquer qu’ils peuvent agir pour le compte de l’utilisateur connecté lors de la fourniture du jeton bootstrap à Microsoft Graph lors du démarrage du flux OAuth2.

Pour terminer, vous devez accorder cette autorisation à toutes les applications clientes Office. Cette configuration permet à l’application d’autoriser toutes les applications clientes Office à obtenir l’autorisationaccess_as_user.

Chaque type de client Office est représenté par un ID unique. Veillez à inclure l’application suivante. Dans ce cas, veillez à activer l’autorisation access_as_user :

  • ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (Microsoft Office)

Capture d’écran montrant l’ID et les clients autorisés qui peuvent accéder à l’API du complément.

Importante

Le service ea5a67f6-b6f3-4338-b240-c655ddc3cc8e étant une autorisation de groupe qui inclut tous les autres hôtes Office, vous pouvez simplement inclure celui-ci au lieu de répertorier chacune des applications individuelles suivantes :

  • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)
  • 57fb890c-0dab-4253-a5e0-7188c88b2bb4 (Office sur le web)
  • 08e18876-6177-487e-b8b5-cf950c1e598c (Office sur le web)
  • bc59ab01-8403-45c6-8796-ac3ef710b3e3 (Outlook sur le web)
  • 93d53678-613d-4013-afc1-62e9e444a0a5 (Office sur le web)

Le dernier service répertorié ci-dessus, 93d53678-613d-4013-afc1-62e9e444a0a5, est un nouveau service SSO introduit en janvier 2022.

Meilleures pratiques en matière de développement de l’authentification unique d’un complément Office

Microsoft recommande ces pratiques lors de la création de compléments Office qui implémentent l’authentification unique.

Utiliser allowConsentPrompt si vous n’avez besoin que du profil de l’utilisateur

Dans certains cas, votre complément Office peut utiliser uniquement l’authentification unique pour obtenir le profil de l’utilisateur. Dans ce cas, envisagez le remplacement du comportement par défaut du processus de connexion en passant l’option { allowConsentPrompt: true } lors de l’appel de getAccessToken() dans le SDK Office.js.

La valeur par défaut de cette propriété false. Cette propriété permet à Office d’obtenir silencieusement un jeton d’accès ou via un consentement interactif si nécessaire. Lorsque la propriété est définie sur false, si Office ne parvient pas à obtenir un jeton parce que l’utilisateur n’a pas approuvé, il reçoit une erreur descriptive.

Toutefois, lorsque la valeur est définie sur true, Office affiche un consentement interactif lorsqu’il ne parvient pas à obtenir silencieusement un jeton d’accès.

Importante

N’oubliez pas qu’Office peut uniquement demander à l’utilisateur d’approuver l’autorisation profile OpenID, et pas les autorisations Microsoft Graph.

Implémenter une méthode d’autorisation de récupération

L’authentification et l’autorisation avec des compléments Office ne réussissent pas toujours. Comme l’a expliqué ce module, il existe plusieurs scénarios où votre complément peut échouer pendant le processus d’autorisation.

Cela peut inclure le scénario où votre utilisateur n’a pas approuvé les autorisations Microsoft Graph dont votre complément a besoin. Dans ce cas, il est préférable que votre complément échoue vite pour solliciter de l’utilisateur l’approbation rapide des autorisations nécessaires. Cette approche est plus avantageuse que d’attendre pour informer l’utilisateur ultérieurement pendant le processus.

Implémenter l’approche « Échec rapide » de l’autorisation

En répétant la section précédente, souvenez-vous de ce que vous avez appris lors d’une leçon précédente. Lorsque Office demande le jeton bootstrap initial, il peut inclure l’option d’autorisation { forGraphAccess: true } lors de l’appel degetAccessToken() dans le SDK Office.js.

Lorsque l’ID Microsoft Entra reçoit cela, il effectue une autre vérification pour voir si l’utilisateur a déjà consenti aux autorisations Microsoft Graph demandées. Si ce n’est pas le cas, l’ID Microsoft Entra répond avec un code d’erreur spécifique que votre complément peut gérer dans le système d’autorisation de secours pour inviter l’utilisateur à donner son consentement aux autorisations Microsoft Graph.

Pré-autoriser tous les clients Office avec votre complément

Comme indiqué dans cette unité, vous pouvez pré-autoriser l’inscription de votre application Microsoft Entra utilisée par votre complément Office pour approuver toutes les applications clientes Office. Cela inclut tous les clients Office de bureau, mobiles et web.

Cela garantit le fonctionne votre complément dans le plus grand nombre de scénarios.