Exercice - Créer un complément Office pour Outlook qui implémente l’authentification unique
Dans cet exercice, vous allez créer un module complémentaire pour Outlook qui ajoute une liste d'événements de calendrier à venir dans le corps d'un courriel envoyé par 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 Outlook 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 Outlook personnalisé dans ce module. Les exercices de ce module partent du principe que vous avez installé ces outils 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 ? MyOutlookSsoAddin
- Quelle application client Office voulez-vous prendre en charge ? Outlook
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 et démarrer le processus de débogage :
npm start
Tester le complément dans le client web Outlook
Ouvrez un navigateur et accédez à Outlook (https://outlook.office.com). Connectez-vous en utilisant un compte professionnel ou scolaire.
Créer un message en sélectionnant le bouton Nouveau message.
Dans la section Nouveau message, recherchez le bouton ... en bas du nouveau message dans le même dossier que les boutons Envoyer et Abandonner .
Sélectionnez l'élément de menuObtenir des compléments.
Dans la boîte de dialogue Compléments Outlook, sélectionnez Mes compléments dans le menu de gauche.
Dans l’écran Mes compléments, sélectionnez le bouton Ajouter un complément personnalisé>Ajouter à partir d’un fichier....
Sélectionnez le fichier manifest.xml à la racine du dossier de votre projet et sélectionnez Charger .
Lorsque vous y êtes invité, sélectionnez le bouton Installer dans la boîte de Avertissement.
Fermez la boîte de dialogue et sélectionnez le bouton... en bas de l’e-mail. Vérifiez l’affichage de votre complément personnalisé :
Sélectionnez le complément pour ouvrir le volet des tâches. Lorsque le volet des tâches s’affiche, sélectionnez le bouton Obtenir les informations de mon profil d’utilisateur.
Comme vous êtes déjà connecté, vous verrez apparaître dans l'e-mail les informations de base du profil de l'utilisateur, sans avoir à vous connecter.
Mettre à jour l’application pour afficher des réunions à venir
À présent, nous allons mettre à jour l’application du volet des tâches pour afficher la liste des réunions à venir pour l’utilisateur actuellement connecté. Ces informations sont collectées avec Microsoft Graph.
Mettre à jour le volet des tâches
Recherchez et ouvrez le ./src/taskpane/taskpane.html.
Remplacez l’élément <body> par ce HTML. Cela mettra à jour le rendu du volet des tâches :
<body class="ms-font-m ms-welcome ms-Fabric">
<header class="ms-welcome__header ms-bgColor-neutralLighter">
<img width="90" height="90" src="../../assets/logo-filled.png" alt="Contoso" title="Contoso" />
<h1 class="ms-font-su">My upcoming meetings... </h1>
</header>
<main class="ms-firstrun-instructionstep">
<ul class="ms-List ms-welcome__features">
<li class="ms-ListItem">
<i class="ms-Icon ms-Icon--Ribbon ms-font-xl"></i>
<span class="ms-font-m">Share your day with others...</span>
</li>
</ul>
<section class="ms-firstrun-instructionstep__header">
<h2 class="ms-font-m">This add-in adds a list of your upcoming meetings to the current email.</h2>
<div class="ms-firstrun-instructionstep__header--image"></div>
</section>
<p align="center">
<button id="getGraphDataButton" class="popupButton ms-Button ms-Button--primary"><span class="ms-Button-label">Add
upcoming schedule to email</span></button>
</p>
</div>
</main>
</body>
Mettre à jour le code du volet des tâches
Maintenant, mettez à jour le code qui obtiendra les prochains événements du calendrier 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 différente dans l’aide à l’authentification unique pour soumettre une demande spécifique à Microsoft Graph.
Cette requête permettra d’obtenir toutes les réunions du calendrier de l’utilisateur actuel à partir de l’heure actuelle pour les prochaines 24 heures :
const startDate = new Date();
let endDate = new Date(startDate);
endDate.setDate(startDate.getDate() + 1);
const endpoint = "/me/calendarview";
const urlParams = `?startdatetime=${ startDate.toISOString() }&enddatetime=${ endDate.toISOString() }&$select=subject,start,end`;
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);
Ensuite, recherchez et ouvrez le fichier ./src/helpers/documentHelper.js.
Recherchez la méthode writeDataToOutlook(). Vous allez remplacer le contenu de cette méthode pour créer une chaîne HTML des réunions à venir renvoyées à partir de la demande Microsoft Graph et ajouter la liste à l’e-mail actuel.
Remplacez le contenu de lawriteDataToOutlook() méthode par le code suivant :
let emailMessage = "";
result.value.forEach(function(meeting){
let startDateTime = new Date(meeting.start.dateTime + "Z");
let endDateTime = new Date(meeting.end.dateTime + "Z");
emailMessage += `<li><strong><em>${startDateTime.toLocaleTimeString()}-${endDateTime.toLocaleTimeString()}</em></strong><br />${meeting.subject}</li>`;
});
// wrap meeting
emailMessage = `Here's what my upcoming calendar looks like for the rest of the day: <ul>${emailMessage}</ul>`;
Office.context.mailbox.item.body.setSelectedDataAsync(emailMessage, { coercionType: Office.CoercionType.Html });
Créer une application Microsoft Entra pour le complément
Les exercices précédents de ce module ont utilisé le script de l’utilitaire de Configuration de l’authentification unique inclus dans tous les projets créés avec le générateur Yeoman pour Microsoft Office. Pour cet exercice, vous allez apprendre à inscrire manuellement une application Microsoft Entra et à configurer votre environnement de développement pour utiliser l’application créée manuellement.
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 Microsoft Entra’ID 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.
Sur la page Inscription d’application, sélectionnez Nouvelle Inscription et définissez ces valeurs sur l’écran Inscrire une application écran. Lorsque vous avez terminé, sélectionnez le boutonEnregistrer.
- Nom : MyOutlookSoAddin2
- Types de comptes pris en charge : Comptes dans n’importe quel annuaire organisationnel (n’importe quel annuaire Microsoft Entra - Multilocataire)
- URI de redirection (option): Laisser les valeurs vides par défaut
Authentification d’application
L’étape suivante consiste à configurer les détails d’inscription de l’application.
Ensuite, dans le volet de navigation le plus à gauche, sélectionnez Gérer>Authentification.
Sur l’écran Authentification, sélectionnez Ajouter une plateforme. Sélectionnez ensuite la plateforme Web dans la liste des options :
Pour lesURIs de redirection, entrez https://localhost:3000/taskpane.html.
Pour lesFlux d’octroi implicite et hybrides, sélectionnez ces deux options, puis sélectionnez Configurer:
- Jetons d’accès (utilisés pour les flux implicites)
- Jetons d’ID (utilisés pour les flux implicites et hybrides).
Après le rechargement de l’écran, sélectionnez Ajouter une URI dans la plateformeWeb, puis entrez https://localhost:3000/fallbackauthdialog.html.
Sélectionnez Enregistrer en haut de l’écran pour enregistrer vos modifications.
Certificats et secrets d’applications
Vous devez à présent créer une clé secrète client pour l’application
Sélectionnez Certificats & secrets dans le volet de navigation le plus à gauche.
Sélectionnez le bouton Nouvelle clé secrète client :
Lorsque vous y êtes invité, donnez une description à la clé secrète, sélectionnez une des options de durée d’expiration fournies, puis sélectionnez Ajouter. Ce que vous entrez et sélectionnez n’a pas d'importance pour l’exercice.
La page secrets & certificat affiche le nouveau secret.
Importante
Il est important que vous copiiez cette valeur, car elle n’est affichée qu’une seule fois. Si vous quittez la page et que vous y êtes revenez, elle s’affiche uniquement sous forme de valeur masquée.
Après avoir copié la clé secrète client, nous allons également copier l’ID client. Dans le volet de navigation le plus à gauche, sélectionnez Gérer>Vue d’ensemble.
Autorisations d’API
Ensuite, vous devez octroyer les autorisations de l’application à Microsoft Graph.
Dans le volet de navigation le plus à gauche, sélectionnez Gérer>Autorisations d’API.
Il est pratique de demander uniquement les autorisations dont votre application a besoin. Nous allons donc supprimer l’autorisation User.Read initiale en la sélectionnant, puis sélectionner Supprimer l’autorisation, suivie de Oui, supprimer pour confirmer.
Ajoutons ensuite les autorisations minimales requises pour que les utilisateurs se connectent à l’aide de l'authentification unique.
Ajoutez une nouvelle autorisation en sélectionnant Ajouter des autorisations.
Sur l’écran Sélectionner une API , sélectionnez Microsoft Graph, puis sélectionnez Autorisations déléguées. Sélectionnez ces autorisations dans ces sections ou utilisez la zone de recherche pour trouver ces autorisations :
- Autorisations OpenID
- openid
- profil
- Calendriers
- Calendars.Read
Une fois ces autorisations sélectionnées, sélectionnez le Ajouter des autorisations.
Sélectionnez ensuite L’octroi du consentement d’administrateur pour contoso, puis acceptez l’invite de confirmation en sélectionnant Oui.
Exposer une API : URI de l’ID d’application
Enfin, sélectionnez Gérer>Exposer une APIdans le volet de navigation le plus à gauche. Il y a plusieurs choses à faire sur cette page :
Tout d’abord, sélectionnez Définir en regard de L’URI de l’ID d’application. Ceci représente l’ID unique de notre application. Ajoutez localhost:3000/ juste avant le protocole et l’ID de l’application afin qu’il ressemble à celui-ci, puis sélectionnez Enregistrer:
api://localhost:3000/f7b53c32-c205-40d8-84dc-0c15b662054c
Remarque
Le GUID est l'identifiant unique de chaque application. Votre identifiant ne correspondra pas à celui présenté dans cet exercice.
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.
Sélectionnez Ajouter une étendue, puis utiliser ces valeurs pour remplir le formulaire :
- Nom de l’étendue : access_as_user
- Qui peut consentir ? Administrateurs et utilisateurs
- Nom d’affichage du consentement d’administrateur : Office peut agir en tant qu’utilisateur.
- Description consentement administrateur : activez Office pour qu’il appelle l’API de complément web avec les mêmes droits que l’utilisateur actuel.
- Nom d'affichage du consentement de l’utilisateur : Office peut agir en tant que vous.
- Description du consentement d’utilisateur : Activez Office pour qu’il appelle l’API du complément web avec les mêmes droits dont vous disposez.
- État : activé
Exposer une API : applications clientes autorisées
La dernière section indique que l’API approuve automatiquement des applications spécifiques et ne demande pas le consentement de l’utilisateur lorsque l’application appelle cette API.
Cela permet aux applications de bureau et web Office d’appeler l’API de votre complément.
Sélectionnez le Ajouter une application cliente à ces applications. Des applications sont ajoutées en tant que GUIDs. Pour chacune d’elles, veillez à sélectionner uniquement les Étendues autorisées répertoriées pour accorder à l’application l’accès à l’étendue précédemment définie :
d3590ed6-52b3-4102-aeff-aad2292ab01c(Microsoft Office)ea5a67f6-b6f3-4338-b240-c655ddc3cc8e(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)
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.
Mettre à jour le projet et la station de travail des développeurs
Une fois l’application Microsoft Entra créée, la dernière étape consiste à mettre à jour votre projet et votre station de travail pour utiliser la nouvelle application.
Dans votre projet, recherchez et ouvrez le fichier.ENV.
Mettez à jour les CLIENT_ID pour utiliser L’ID client que vous avez copié à partir du processus d’inscription de l’application.
Recherchez et ouvrez le fichier ./manifest.xml. À la fin du fichier, recherchez l'élément <WebApplicationInfo>. Dans cet élément, mettez à jour les éléments <ID> et <Resource> pour utiliser le nouvel ID client.
Recherchez et ouvrez le fichier./src/helpers/fallbackauthdialog.js. Recherchez la ligne qui commence par const msalConfig. Il s’agit de l’objet de configuration MSAL.js. Mettez à jour la propriété clientId de l’objet pour en faire le nouvel ID client.
Vous devez ensuite enregistrer la clé secrète client de l’application dans le magasin d’informations d’identification sur votre station de travail de développeur. La commande que vous exécuterez dépend de votre plateforme.
Windows
Exécutez ce PowerShell, après avoir mis à jour les trois premières valeurs :
$ssoAppName: Le nom de votre projet, par exemple MyOutlookSsoAddin$user: votre nom d’utilisateur du compte Windows, par exemple, MyDomain\MyUserName$secret: clé secrète client que vous avez copiée lors de l’inscription de l’application Microsoft Entra
$ssoAppName = "MyOutlookSsoAddin"
$user = "MyDomain\MyUserName"
$secret = "....."
[void][Windows.Security.Credentials.PasswordVault, Windows.Security.Credentials, ContentType = WindowsRuntime]
$creds = New-Object Windows.Security.Credentials.PasswordCredential
$creds.Resource = $ssoAppName
$creds.UserName = $user
$creds.Password = $secret
$vault = New-Object Windows.Security.Credentials.PasswordVault
$vault.Add($creds)
macOS
Exécutez ces opérations dans la console, après avoir mis à jour les trois premières valeurs :
SSOAPPNAME: Le nom de votre projet, par exemple MyOutlookSsoAddinUSER: nom d’utilisateur de connexion macOS, tel que myusernameSECRET: clé secrète client que vous avez copiée lors de l’inscription de l’application Microsoft Entra
SSOAPPNAME="MyOutlookSsoAddin"
USER="myusername"
SECRET="...."
sudo security add-generic-password -a $USER -s $SSOAPPNAME -w $SECRET -U
Générer et tester l’application à nouveau
Exécutez cette commande dans une invite de commandes pour transposer et démarrer le processus de débogage :
npm start
Tester à nouveau le complément dans le client web Outlook
Ouvrez un navigateur et accédez à Outlook (https://outlook.office.com). Connectez-vous en utilisant un compte professionnel ou scolaire.
Répétez le processus de test du complément que vous avez effectué au début de cet exercice. Toutefois, avant d’activer le complément, vous devez le supprimer, car le complément actuellement installé utilise toujours l’ancien fichier manifest.xml avec l’ancienne inscription de l’application Microsoft Entra.
Pour supprimer le complément, suivez la même procédure pour l’installation d’un nouveau complément, sauf avant de charger votre fichier manifest.xml personnalisé, supprimez le complément précédemment installé :
Après avoir installé le fichier manifest.xml du complément mis à jour, terminez le processus de test pour tester la nouvelle logique de votre complément.
