Exercice - Créer un complément Office pour Excel qui implémente l’authentification unique
Dans cet exercice, vous allez créer un complément Excel qui ajoute une liste des e-mails récents reçus par l’utilisateur actuellement connecté à l’aide de Microsoft Graph dans une feuille de calcul. Ce processus utilise le modèle d’authentification unique (SSO).
Conditions préalables
Le développement de modules complémentaires Office pour Microsoft Excel 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 allez utiliser Node.js pour créer le complément Excel 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.
- Node.js (la dernière version LTS)
- NPM (installé avec Node.js), v6.x (ou version ultérieure)
- Yeoman, v3.x (ou version ultérieure)
- Yeoman Generator pour Microsoft Office - v1.8.8
- Visual Studio Code
La version minimale de ces conditions préalables doit être installée sur votre station de travail.
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.
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.
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 ? MyExcelSsoAddin
- Quelle application client Office voulez-vous prendre en charge ? Excel
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.
Inscrire l’application Microsoft Entra
Ensuite, inscrivez l’application Microsoft Entra et mettez à 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.
À 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 à Microsoft Entra ID. 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 effectuera ces tâches :
- Inscrire l’application Microsoft Entra
- Configurer l’audience et les paramètres d’autorisation de l’application
- Créer une clé secrète client, puis l’enregistrer dans le magasin des secrets des stations de travail des développeurs
- Mettre à jour le projet avec l’ID client de l’application Microsoft Entra
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.
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
Tester le complément du client de bureau Excel
Au bout d'un moment, Excel se chargera avec le bouton de complément dans le ruban et dans le volet des tâches.
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.
Après votre connexion, le complément récupère vos informations de profil de base depuis Microsoft Graph, puis les ajoute au document.
Mettre à jour l’application pour afficher les e-mails récents
À présent, nous allons mettre à jour l’application du volet des tâches pour ajouter une liste des e-mails récents reçus par l’utilisateur actuellement connecté avec Microsoft Graph.
Mettre à jour les autorisations de l’application Microsoft Entra
L’application Microsoft Entra inscrite doit d’abord se voir accorder des autorisations pour l’application.
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.
Dans le volet de navigation gauche, sélectionnez Gérer>Autorisations d’API.
Ajoutez une nouvelle autorisation en sélectionnant l' Ajouter une autorisation.
Sur l’écran Sélectionner une API , sélectionnez Microsoft Graph, puis sélectionnez Autorisations déléguées. Recherchez et sélectionnez la valeurMail.Read d’une autorisation puis sélectionnez Ajouter des autorisations.
Sélectionnez ensuite L’octroi du consentement d’administrateur pour contoso, puis acceptez l’invite de confirmation en sélectionnant Oui.
Mettre à jour le volet des tâches du complément
L’étape suivante consiste à mettre à jour le code du complément.
Mettre à jour le volet des tâches
Localisez et ouvrez le fichier ./src/taskpane/taskpane.html.
Localisez l'élément HTML suivant dans le volet des tâches :
<div class="ms-firstrun-instructionstep__welcome-body">
Localisez la première puce dans le HTML et changez spanle contenu de l'élément en :
<span class="ms-ListItem-primaryText">Click the <b>Get my last 10 emails</b> button.</span>
Localisez la dernière puce dans le HTML et changezspan le contenu de l'élément en :
<span class="ms-ListItem-primaryText">Your last 10 emails will be displayed in the document.</span>
Localisez le bouton et modifiez le texte à Get last 10 emails.
Mettre à jour le code du volet des tâches
À présent, mettez à jour le code qui reçoit les 10 derniers e-mails de l’utilisateur.
Recherchez et ouvrez le fichier ./src/helpers/ssoauthhelper.js.
Dans la méthode getGraphData(), recherchez cette ligne :
const response = await sso.makeGraphApiCall(exchangeResponse.access_token);
Supprimez cette ligne pour la remplacer par ce code. Ce code utilise une autre méthode dans l’aide pour l’authentification unique pour soumettre une demande spécifique à Microsoft Graph :
const endpoint = "/me/messages";
const urlParams = "?$select=receivedDateTime,subject,isRead&$orderby=receivedDateTime&$top=10";
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);
Ensuite, recherchez et ouvrez le fichier ./src/helpers/documentHelper.js.
Recherchez la méthode writeDataToExcel(). Vous remplacerez le code plus souvent dans cette méthode, mais vous devez conserver la structure de base. Supprimez le contenu de la méthode et remplacez-le par le code suivant :
return Excel.run(function(context) {
const sheet = context.workbook.worksheets.getActiveWorksheet();
// TODO
return context.sync();
});
Tout d'abord, remplacez le// TODO par le code suivant pour créer quelques titres de colonne dans la feuille :
const rangeHeading = sheet.getRange("A1:D1");
rangeHeading.values = [["Received Date/Time", "Subject", "Read?", "ID"]];
Ajoutez ensuite ce code après le code précédent que vous venez d’ajouter. Cela a pour effet de convertir les résultats de la demande Microsoft Graph en tableau multidimensionnel pour les écrire dans la feuille de calcul.
Il écrit ensuite les résultats dans la feuille de calcul et définit la forme des colonnes pour que toutes les données soient visibles :
// convert data to a list
const mailResults = result.value;
for (let i = 0; i < mailResults.length; i++) {
if (mailResults[i] !== null) {
let innerArray = [];
innerArray.push(mailResults[i].receivedDateTime);
innerArray.push(mailResults[i].subject);
innerArray.push(mailResults[i].isRead);
innerArray.push(mailResults[i].id);
let data = [];
data.push(innerArray);
let rangeData = sheet.getRange(`A${i+2}:D${i+2}`);
rangeData.values = data;
}
}
rangeHeading.format.autofitColumns();
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
Tester l’application dans Excel
Au bout d'un moment, Excel se chargera avec le bouton de complément dans le ruban et dans le volet des tâches. Nous allons tester ceci dans le client web Excel.
Ouvrez un navigateur, puis à OneDrive (https://onedrive.com)). Connectez-vous en utilisant un compte professionnel ou scolaire.
Ajoutez un nouveau classeur Excel en sélectionnant le bouton Nouveau , puis sélectionnez Classeur Excel.
Installez le complément Excel en chargeant la 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 des tâches, puis sélectionnez le bouton Obtenir les 10 derniers e-mails.
Étant donné que vous êtes déjà connecté, au bout d’un moment, les e-mails récents s’affichent dans la feuille de calcul sans besoin de connexion.
