Exercice - Créer un complément Office pour Word qui implémente l’authentification unique

  • 18 minutes

Au cours de cet exercice, vous allez créer un complément Word qui insère des informations sur l’utilisateur actuellement connecté avec Microsoft Graph. Ce processus utilise le modèle d’authentification unique (SSO).

Conditions préalables

Le développement de modules complémentaires Office pour Microsoft Word nécessite le client Web ou les clients de bureau suivants :

  • Windows v16.0.12215.20006 (ou ultérieure)
  • macOS v16.32.19102902 (ou ultérieure)

Vous utiliserez Node.js pour créer le complément Word personnalisé dans ce module. Les exercices de ce module partent du principe que vous avez installé les outils suivants sur votre station de travail de développeur :

Importante

Dans la plupart des cas, installer la dernière version des outils suivants est la meilleure option. Les versions répertoriées ici ont été utilisées lors de la publication et du dernier test de ce module.

Importante

Cet exercice est écrit pour fonctionner avec le générateur Yeoman pour Microsoft Office v1.8.8. Vérifiez que vous utilisez cette version en installant une version spécifique à l’aide de la commande npm install generator-office@1.8.8 --global. Les versions ultérieures du générateur ont supprimé, puis modifié la structure du projet SSO qui ne correspond pas aux étapes de ce labo.

Créer votre projet de complément

Exécutez la commande suivante pour créer un projet de complément à l’aide du générateur Yeoman :

yo office

Remarque

Lorsque vous exécutez la commande yo office, il est possible que vous receviez des messages d’invite sur les règles de collecte de données de Yeoman et les outils CLI de complément Office. Utilisez les informations fournies pour répondre aux invites comme vous l’entendez.

Lorsque vous y êtes invité, fournissez les informations suivantes pour créer votre projet de complément :

  • Sélectionner un type de projet : projet du volet de tâches du complément Office prenant en charge l’authentification unique
  • Sélectionnez un type de script : JavaScript
  • Comment souhaitez-vous nommer votre complément ? MyWordSsoAddin
  • Quelle application client Office voulez-vous prendre en charge ? Word

Capture d’écran des invites et réponses pour le générateur Yeoman.

Après avoir exécuté des invites, le générateur crée le projet, puis installe les composants des nœuds de prise en charge.

Explorer le projet initial

Tous les projets de module complémentaire pour Word comprennent divers dossiers et fichiers qui mettent en œuvre un module complémentaire pour Microsoft Word. L’implémentation du complément se produit principalement implémenté dans les dossiers ./src/commands et ./src/taskpane. Les fichiers de ces deux dossiers implémentent le complément de base du volet des tâches et les commandes facultatives pour le déclencher.

Examinons certains des autres fichiers ajoutés au projet qui prennent en charge l’implémentation d’une expérience SSO pour les utilisateurs. Ces fichiers se trouvent dans le dossier ./src/helpers.

  • ./src/helpers/documentHelper.js : ce fichier utilise la bibliothèque d’API JavaScript Office pour récupérer les données de Microsoft Graph, puis les ajouter au document Word.
  • ./src/helpers/fallbackauthdialog.html : ce fichier est la page sans interface utilisateur qui charge le code JavaScript de la stratégie d’authentification de secours.
  • fallbackauthdialog.js : ce fichier contient le JavaScript de la stratégie d’authentification qui utilise la bibliothèque d’authentification Microsoft pour JavaScript (MSAL.js) pour connecter l’utilisateur.
  • ./SRC/helpers/fallbackauthhelper.js : ce fichier contient le JavaScript du volet des tâches qui appelle la stratégie d’authentification de secours dans les scénarios lorsque l’authentification unique n’est pas prise en charge.
  • ./src/helpers/ssoauthhelper.js : ce fichier contient l’appel JavaScript à l’API d’authentification unique, getAccessToken(), reçoit le jeton d’amorçage, initialise l’échange du jeton d’amorçage contre un jeton d’accès qui permet d’appeler Microsoft Graph. Ce fichier inclut également le code d’appel du point de terminaison Microsoft Graph.

Importante

L’exemple de cet exercice est destiné à être utilisé uniquement comme ressource d’apprentissage et n’est pas destiné à être utilisé dans un scénario de production, car il transmet le jeton OAuth utilisé pour envoyer des demandes à Microsoft Graph au client afin d’effectuer l’appel directement.

Comme meilleure pratique de sécurité, utilisez toujours le code côté serveur pour effectuer des appels Microsoft Graph ou d’autres appels nécessitant la transmission d’un jeton d’accès. Ne renvoyez jamais le jeton OBO au client pour permettre au client d’effectuer des appels directs vers Microsoft Graph. Cela aide à protéger le jeton contre l’interception ou la fuite. Pour plus d’informations sur le flux de protocole approprié, consultez le diagramme de protocole OAuth 2.0.

Inscrire l’application Microsoft Entra

Vous avez appris dans une unité précédente qu’un complément Office doit avoir une inscription d’application Microsoft Entra associée pour que l’utilisateur se connecte et obtienne un jeton d’accès pour appeler Microsoft Graph.

Avant de pouvoir tester le projet, vous devez inscrire l’application Microsoft Entra, puis mettre à jour le projet pour utiliser l’application Microsoft Entra.

Conseil

Pour plus d’informations sur l’inscription manuelle de l’application Microsoft Entra, consultez : Créer un complément Office Node.js qui utilise l’authentification unique : Inscrire le complément auprès du point de terminaison Azure AD v2.0.

Le projet de complément Office inclut un utilitaire qui peut créer l’inscription de l’application Microsoft Entra et mettre à jour le projet.

À partir de l’invite de commande, assurez-vous que vous êtes actuellement dans le dossier racine du projet. Puis exécutez cette commande :

npm run configure-sso

La commande lance un navigateur et vous invite à vous connecter à l’ID Microsoft Entra. Veillez à vous connecter en tant qu’utilisateur disposant des autorisations nécessaires pour inscrire une application Microsoft Entra, par exemple un utilisateur affecté au rôle Administrateur général .

Après l’authentification, le script effectue les tâches suivantes :

  1. Inscrire l’application Microsoft Entra
  2. Configurer l’audience et les paramètres d’autorisation de l’application
  3. Créer une clé secrète client, puis l’enregistrer dans le magasin des secrets des stations de travail des développeurs
  4. Mettre à jour le projet avec l’ID client de l’application Microsoft Entra

Capture d’écran de la sortie d’exécution du script configure-sso.

Avertissement

La commande configure-sso échoue si votre locataire Microsoft Entra est configuré pour l’authentification multifacteur (MFA)/l’authentification à deux facteurs. Dans ce cas, vous devez créer manuellement l’inscription de l’application Microsoft Entra comme indiqué dans l’article Créer un complément Office Node.js qui utilise l’authentification unique : Inscrire le complément auprès du point de terminaison Azure AD v2.0 .

Examinons le travail effectué par le script configure-sso.

Ouvrez un navigateur et accédez au Centre d’administration Microsoft Entra (https://aad.portal.azure.com). Connectez-vous à l’aide d’un Compte professionnel ou scolaire possédant des droits d’administrateur général sur l’entreprise.

Sélectionnez ID Microsoft Entra dans le volet de navigation le plus à gauche.

Inscription d’application

Sélectionnez Gérer>Inscriptions d'applications dans le volet de navigation le plus à gauche.

Capture d’écran des inscriptions d’applications dans le portail du centre d’administration Microsoft Entra.

Dans la page Inscriptions d’applications, sélectionnez l’application MyWordSsoAddin. Il s’agit du nom de l’application précédemment créée avec le générateur Yeoman pour Microsoft Office.

Dans la page dessoAddin MyWordSoAddin, notez l’ID d’application. Le script configure-sso qui a créé cette application Microsoft Entra définit cette valeur dans le de votre projet . Fichier ENV :

CLIENT_ID=056b1e8c-747d-4b45-94b1-f61ac2c19a5e
GRAPH_URL_SEGMENT=/me
NODE_ENV=development
PORT=3000
QUERY_PARAM_SEGMENT=
SCOPE=User.Read

Authentification

Ensuite, dans le volet de navigation le plus à gauche, sélectionnez Gérer>Authentification. Vous remarquerez que le programme définit les URI de redirection sur les pages taskpane.html et fallbackauthdialog.html dans notre application.

Capture d’écran de la section URI de redirection.

Notez également que la section Octroi implicite et flux hybrides a été mise à jour pour garantir que l’ID Microsoft Entra retourne des jetons d’accès et des jetons d’ID lorsqu’un utilisateur s’authentifie auprès de l’application :

Capture d’écran de la sélection d’octroi implicite et de flux hybrides.

Certificats et secrets

Ensuite, dans le volet de navigation le plus à gauche, sélectionnez Gérer>Authentification. Notez que les URI de redirection se trouvent dans le volet de navigation le plus à gauche, sélectionnez Gérer>Certificats et secrets.

Le script configure-sso a créé une clé secrète client pour l’application. L’exécution de ce script apparaissait dans l’invite de commandes comme vous l’avez vu précédemment, puis le script a ajouté le magasin des secrets de votre station de travail de développeur.

Autorisations d’API

Dans le volet de navigation le plus à gauche, sélectionnez Gérer>Autorisations d’API. Notez la manière dont nous avons configuré plusieurs autorisations déléguées pour l’application. Le script console-sso a également accordé le consentement administrateur à tous les utilisateurs du client. Ainsi, le programme ne leur demandera pas de consentir à utiliser l’application lors de la première utilisation.

Capture d’écran des autorisations configurées et accordées sur l’application.

Exposer une API : URI de l’ID d’application

Enfin, sélectionnez Gérer>Exposer une APIdans le volet de navigation le plus à gauche. Cette page comporte éléments à prendre en compte :

Notez tout d’abord l’URI de l’ID d’application. Ceci représente l’ID unique de notre application. Notez que cet élément contient l’ID de l’application dans la chaîne complète.

Exposer une API : étendues définies par l’API

La section suivante contient les étendues définies par l’API. Il peut s’agir d’étendues personnalisées qui vous permettent de restreindre l’accès aux données et aux fonctionnalités protégées par l’API. Dans notre cas, l’application configure-sso a ajouté l’étendue suivante :

api://localhost:3000/056b1e8c-747d-4b45-94b1-f61ac2c19a5e/access_as_user

L’ID de l’étendue correspondra à celui de votre application. Notez la fin de l’étendue. Cette étendue, access_as_user, permet aux applications clientes Office d’utiliser les API web du complément avec les mêmes droits que l’utilisateur actuellement connecté.

Exposer une API : applications clientes autorisées

La dernière section indique que l’API approuve automatiquement ces applications spécifiques et ne demande pas le consentement de l’utilisateur lorsque l’application appelle cette API.

Cela autorise les applications Web et de bureau d'Office à appeler l'API de votre module complémentaire.

Les applications répertoriées sont les suivantes :

  • Microsoft Office : d3590ed6-52b3-4102-aeff-aad2292ab01c
  • Microsoft Office : ea5a67f6-b6f3-4338-b240-c655ddc3cc8e
  • Office sur le web : 57fb890c-0dab-4253-a5e0-7188c88b2bb4
  • Office sur le web : 08e18876-6177-487e-b8b5-cf950c1e598c
  • Outlook sur le web : bc59ab01-8403-45c6-8796-ac3ef710b3e3

Si vous sélectionnez l’une de ces applications, chacune d’elles a l’étendue définie précédemment en tant qu’étendue autorisée.

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

Concevoir et tester l’application

Exécutez cette commande dans une invite de commandes pour transposer, puis démarrer le processus de débogage :

npm start

Le script start effectue trois actions :

  1. générer le projet de complément
  2. démarrer un serveur web local pour héberger le complément sur votre station de travail locale
  3. démarrer le client Office, puis charger une version test du complément Office dedans

Conseil

Surveillez bien l’invite de commande. Vous devrez sans doute entrer votre mot de passe pour terminer le processus de démarrage, de chargement d’une version test, puis de débogage.

Tester le complément dans le client de bureau Word

Après un moment, Word se chargera avec le bouton du complément dans le ruban et dans le volet des tâches.

Capture d’écran du complément dans Word.

Pour tester le complément, sélectionnez le bouton Obtenir les informations de mon profil d’utilisateur.

Si ce n’est déjà fait, vous devrez vous connecter au client Office sur invite.

Capture d’écran du processus de connexion dans Word.

Une fois que l’utilisateur s’est connecté, le complément récupère vos informations de profil de base à partir de Microsoft Graph et les ajoute au document.

Capture d’écran du test réussi dans Word.

Tester le complément dans le client web Word

Pour voir l’authentification unique en action, essayez le complément dans client web Office depuis OneDrive.

Ouvrez un navigateur, puis à OneDrive (https://onedrive.com)). Connectez-vous en utilisant un compte professionnel ou scolaire.

Ajoutez un nouveau document Word en sélectionnant le bouton Nouveau, puis sélectionnez Document Word.

Installez le complément Word en chargeant une version test. Dans le ruban, sélectionnez Insérer>Compléments.

Dans la boîte de dialogue Compléments Office, sélectionnez Charger mon complément.

Sélectionnez le fichier manifest.xml à la racine de votre projet, puis sélectionnez Charger.

Microsoft Word charge une version test du complément, puis affiche le bouton Afficher le volet de tâches dans le ruban, tout comme le client de bureau.

Sélectionnez le bouton Afficher le volet de tâches, puis Obtenir les informations de mon profil d’utilisateur.

Étant donné que vous êtes déjà connecté, vous verrez au bout d’un moment que les mêmes informations de profil apparaissent dans le document sans avoir à vous connecter.

Explorer le projet

Voyons maintenant comment le complément Word utilise le SSO pour se connecter à Microsoft Graph et afficher dans le document les informations relatives au profil de l'utilisateur actuellement connecté.

Ouvrez le projet précédemment créé au début de cet exercice dans Visual Studio Code.

Recherchez, puis ouvrez le fichier ./manifest.xml. Dans le manifeste du module d'extension, localisez SourceLocationl'élément :

<OfficeApp>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:{PORT}/taskpane.html"/>
  </DefaultSettings>
</OfficeApp>

La valeur de cet élément indique au client Office d’hébergement l’URL à charger dans l’IFRAME du volet des tâches.

Recherchez, puis ouvrez le fichier ./src/taskpane/taskpane.html. Ce fichier contient deux éléments importants :

  1. Dans la section <head> de la page, notez la référence <script> au fichier office.js. Il s’agit du Kit de développement logiciel (SDK) JavaScript Office permettant à votre complément de communiquer avec le client Office hôte.
  2. Faites défiler l’écran vers le bas du fichier jusqu’au bouton <button id="getGraphDataButton">. Ce bouton démarre le processus d’obtention d’un jeton d’accès pour que l’utilisateur demande les informations de profil de l’utilisateur actuellement connecté depuis Microsoft Graph.

Recherchez, puis ouvrez le fichier ./src/taskpane/taskpane.js. Après avoir chargé le complément, le client Office d’hébergement joint la méthode ssoAuthHelper.getGraphData() à l’événement de clic du bouton du volet des tâches.

Recherchez, puis ouvrez le fichier ./src/helpers/ssoauthhelper.js. Ce fichier contient le code qui fait la plupart du travail d’authentification de l’utilisateur par l’authentification unique, puis en obtenant les données de profil de l’utilisateur depuis Microsoft Graph. La méthode getGraphData() implémente tout cela. Cette méthode procède comme suit :

  1. Connecte l’utilisateur en obtenant un jeton d’accès à partir de l’ID Microsoft Entra. Ce jeton d’accès, appelé bootstrapToken, contient un jeton d’ID et un jeton d’accès.

  2. Échangez le jeton d’accès avec l’ID Microsoft Entra pour un jeton qui peut être utilisé pour appeler Microsoft Graph.

    Le jeton bootstrapToken obtenu au cours de la première étape ne contiennent pas les étendues nécessaires pour appeler Microsoft Graph, car il sert à authentifier l’utilisateur, puis à obtenir un jeton d’ID.

    Remarque

    La méthode sso.getGraphToken() appelée dans cette étape appelle à son tour le point de terminaison https://graph.microsoft.com/v1.0/auth pour obtenir un jeton d’accès utilisable pour Microsoft Graph.

  3. Envoyez une demande HTTP à l’API REST de Microsoft Graph pour obtenir les données de profil de l’utilisateur. Cette opération s’effectue via la méthode sso.makeGraphApiCall().

    Remarque

    La méthode sso.makeGraphApiCall() appelle le point de terminaison https://graph.microsoft.com/v1.0/getuserdata pour récupérer les informations de profil de l’utilisateur.

Si le processus d’authentification échoue, le code utilise un processus d’authentification de secours à l’aide des fichiers ./src/helpers/fallbackauth*.* .

Le code ajouté par le générateur Yeoman de Microsoft Office au projet de complément initial récupère les informations de profil de l’utilisateur depuis Microsoft Graph. Les autres exercices de ce module montrent comment demander des informations supplémentaires à Microsoft Graph.

Testez vos connaissances

1.

Le processus d’authentification unique peut obtenir un jeton d’accès pour l’utilisateur actuellement connecté pouvant être utilisé pour appeler Microsoft Graph.

2.

Pour que le processus d’authentification unique fonctionne avec les compléments Office, l’utilisateur doit déjà être connecté à son compte personnel ou à son compte Microsoft Entra professionnel et scolaire.

3.

Consentement d’autorisations probablement nécessaire pour la première connexion de l’utilisateur à partir d’un complément sur invitation du client Office.