Übung: Erstellen eines Office-Add-Ins für Outlook, das einmaliges Anmelden implementiert
In dieser Übung erstellen Sie ein Outlook-Add-In, über das eine Liste anstehender Kalenderereignisse dem Textkörper einer E-Mail des aktuell angemeldeten Benutzers mit Microsoft Graph hinzugefügt wird. Bei diesem Prozess wird das SSO (Single Sign-On)-Authentifizierungsschema verwendet.
Voraussetzungen
Für die Entwicklung von Office-Add-Ins für Microsoft Outlook sind der Webclient oder die folgenden Desktopclients erforderlich:
- Windows v16.0.12215.20006 (oder höher)
- macOS v16.32.19102902 (oder höher)
Sie werden Node.js verwenden, um in diesem Modul das benutzerdefinierte Outlook-Add-In zu erstellen. Bei den Übungen in diesem Modul wird vorausgesetzt, dass die folgenden Tools auf Ihrer Entwicklerarbeitsstation installiert sind:
Wichtig
In den meisten Fällen ist die Installation der neuesten Versionen folgender Tools die beste Option. Die hier aufgeführten Versionen wurden verwendet, als dieses Modul veröffentlicht und zuletzt getestet wurde.
- Node.js (die aktuellste LTS-Version).
- NPM (mit Node.js installiert), v6.x (oder höher)
- Yeoman, v3.x (oder höher)
- Yeoman-Generator für Microsoft Office – v1.8.8
- Visual Studio Code
Sie müssen die erforderlichen Mindestversionen dieser Voraussetzungen auf Ihrer Arbeitsstation installiert haben.
Wichtig
Diese Übung wurde für die Arbeit mit dem Yeoman-Generator für Microsoft Office v1.8.8 geschrieben. Stellen Sie sicher, dass Sie diese Version verwenden, indem Sie eine bestimmte Version mit dem Befehl npm install generator-office@1.8.8 --global installieren. In späteren Versionen des Generators wurde das SSO-Projektgerüst entfernt und dann geändert, das nicht mit den Schritten in diesem Lab übereinstimmt.
Wichtig
Das Beispiel in dieser Übung soll nur als Lernressource verwendet werden und ist nicht für die Verwendung in einem Produktionsszenario vorgesehen, da es das OAuth-Token zum Senden von Anforderungen an Microsoft Graph zurück an den Client übergibt, um den Aufruf direkt durchzuführen.
Als bewährte Sicherheitsmethode sollten Sie immer den serverseitigen Code verwenden, um Microsoft Graph-Aufrufe oder andere Aufrufe auszuführen, welche die Übergabe eines Zugriffstokens erfordern. Geben Sie niemals das OBO-Token an den Client zurück, damit der Client direkte Aufrufe an Microsoft Graph durchführen kann. Dadurch wird verhindert, dass der Token abgefangen oder weitergegeben werden kann. Weitere Informationen zum richtigen Protokollfluss finden Sie im OAuth 2.0-Protokolldiagramm.
Erstellen eines Add-In-Projekts
Führen Sie den folgenden Befehl aus, um ein Add-In-Projekt mit dem Yeoman-Generator zu erstellen:
yo office
Hinweis
Wenn Sie den yo office-Befehl ausführen, werden möglicherweise Eingabeaufforderungen zu den Richtlinien für die Datensammlung von Yeoman und den CLI-Tools des Office-Add-In angezeigt. Verwenden Sie die bereitgestellten Informationen, um auf die angezeigten Eingabeaufforderungen entsprechend zu reagieren.
Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Informationen an, um das Add-In-Projekt zu erstellen:
- Projekttyp auswählen: Aufgabenbereichsprojekt für Office-Add-In, das einmaliges Anmelden unterstützt
- Skripttyp auswählen: JavaScript
- Wie soll Ihr Add-In heißen? MyOutlookSsoAddin
- Welche Office-Clientanwendung soll unterstützt werden? Outlook
Nachdem Sie die Aufforderungen erledigt haben, erstellt der Generator das Projekt und installiert unterstützende Node-Komponenten.
Registrieren der Microsoft Entra-App
Registrieren Sie als Nächstes die Microsoft Entra-Anwendung, und aktualisieren Sie das Projekt für die Verwendung der Microsoft Entra-Anwendung.
Tipp
Ausführliche Informationen zum manuellen Registrieren der Microsoft Entra-Anwendung finden Sie unter Erstellen eines Node.js Office-Add-Ins, das einmaliges Anmelden verwendet: Registrieren des Add-Ins beim Azure AD v2.0-Endpunkt.
Stellen Sie mithilfe der Eingabeaufforderung sicher, dass Sie sich aktuell im Stammverzeichnis des Projekts befinden. Führen Sie anschließend den folgenden Befehl aus:
npm run configure-sso
Der Befehl startet einen Browser und fordert Sie auf, sich bei Microsoft Entra ID anzumelden. Stellen Sie sicher, dass Sie sich als Benutzer anmelden, der über Berechtigungen zum Registrieren einer Microsoft Entra-Anwendung verfügt, z. B. als Benutzer, der der Rolle "Globaler Administrator " zugewiesen ist.
Nach der Authentifizierung werden durch das Skript die folgenden Aufgaben ausgeführt:
- Registrieren der Microsoft Entra-Anwendung
- Konfigurieren der Benutzergruppe und der Berechtigungseinstellungen für die Anwendung
- Erstellen eines neuen geheimen Clientschlüssels und Speichern dieses Schlüssels im Geheimnisspeicher Ihrer Entwicklerarbeitsstation
- Aktualisieren des Projekts mit der Client-ID der Microsoft Entra-Anwendung
Warnung
Der Befehl configure-sso schlägt fehl, wenn Ihr Microsoft Entra-Mandant für die mehrstufige Authentifizierung (Multi-Factor Authentication, MFA)/zweistufige Authentifizierung konfiguriert ist. In diesem Fall müssen Sie die Microsoft Entra-App-Registrierung manuell erstellen, wie im Artikel Erstellen eines Node.js Office-Add-Ins, das einmaliges Anmelden verwendet: Registrieren des Add-Ins beim Azure AD v2.0-Endpunkt beschrieben wird.
Erstellen und Testen der Anwendung
Führen Sie den folgenden Befehl in einer Eingabeaufforderung aus, um zu transpilieren und Debuggen zu starten:
npm start
Testen des Add-Ins im Outlook-Webclient
Öffnen Sie einen Browser, und navigieren Sie zu Outlook (https://outlook.office.com). Melden Sie sich mit einem Geschäfts-, Schul- oder Unikonto an.
Erstellen Sie mithilfe der Schaltfläche Neue Nachricht eine neue Nachricht.
Suchen Sie im Abschnitt für neue Nachrichten die Schaltfläche ... unten in der neuen Nachricht. Sie befindet sich in derselben Fußzeile, in der sich auch die Schaltflächen Senden und Verwerfen befinden.
Wählen Sie das Menüelement Add-Ins aus.
Wählen Sie im Dialogfeld Add-Ins für Outlook im Menü auf der linken Seite die Option Meine Add-Ins.
Wählen Sie Bildschirm Meine Add-Ins die Schaltfläche Benutzerdefiniertes Add-In hinzufügen>Aus Datei hinzufügen… aus.
Wählen Sie die Datei manifest.xml im Stammverzeichnis des Projekts aus, und klicken Sie dann auf Hochladen.
Wenn Sie dazu aufgefordert werden, wählen Sie die Schaltfläche Installieren im Dialogfeld Warnung aus.
Schließen Sie das Dialogfeld, und wählen Sie die Schaltfläche … unten in der E-Mail aus. Beachten Sie, dass jetzt das benutzerdefinierte Add-In angezeigt wird:
Wählen Sie das Add-In aus, um den Aufgabenbereich zu öffnen. Wenn der Aufgabenbereich angezeigt wird, wählen Sie die Schaltfläche Meine Benutzerprofilinformationen abrufen aus.
Da Sie bereits angemeldet sind, werden nach einem kurzen Moment die grundlegenden Profilinformationen in der E-Mail angezeigt, ohne dass eine Anmeldung erforderlich ist.
Aktualisieren der App zum Anzeigen anstehender Besprechungen
Aktualisieren wir nun den Aufgabenbereich der App-Anzeige, um eine Liste der anstehenden Besprechungen für den aktuell angemeldeten Benutzer anzuzeigen. Diese Informationen werden mithilfe von Microsoft Graph gesammelt.
Aktualisieren des Aufgabenbereichs
Suchen und öffnen Sie die Datei ./src/taskpane/taskpane.html.
Ersetzen Sie das Element <body> durch den nachfolgende HTML-Code. Dadurch wird das Rendering des Aufgabenbereichs aktualisiert:
<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>
Aktualisieren des Codes des Aufgabenbereichs
Aktualisieren Sie nun den Code, über den die nächsten Kalenderereignisse des Benutzers angezeigt werden.
Suchen und öffnen Sie die Datei ./src/helpers/ssoauthhelper.js.
Suchen Sie die folgende Zeile in der Methode getGraphData():
const response = await sso.makeGraphApiCall(exchangeResponse.access_token);
Suchen Sie diese Zeile, und ersetzen Sie sie durch den folgenden Code. Dieser Code verwendet eine andere Methode im SSO-Hilfsprogramm, um eine bestimmte Anforderung an Microsoft Graph zu senden.
Mithilfe dieser Abfrage werden alle Besprechungen im Kalender des aktuellen Benutzers ab der aktuellen Uhrzeit für die nächsten 24 Stunden abgerufen:
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);
Als Nächstes suchen und öffnen Sie die ./src/helpers/documentHelper.js -Datei.
Suchen Sie die Methode writeDataToOutlook(). Sie ersetzen den Inhalt dieser Methode, um eine HTML-Zeichenfolge der anstehenden Besprechungen zu erstellen, die von der Microsoft Graph-Anforderung zurückgegeben wird, und fügen die Liste der aktuellen E-Mail hinzu.
Löschen Sie die Inhalte der Methode writeDataToOutlook(), und ersetzen Sie sie durch folgenden Code:
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 });
Erstellen einer neuen Microsoft Entra-Anwendung für das Add-In
Frühere Übungen in diesem Modul haben das Utility-Skript configure-sso verwendet, das in allen Projekten enthalten ist, die mit dem Yeoman-Generator für Microsoft Office erstellt worden sind. In dieser Übung erfahren Sie, wie Sie eine Microsoft Entra-Anwendung manuell registrieren und Ihre Entwicklerumgebung für die Verwendung der manuell erstellten App konfigurieren.
Öffnen Sie einen Browser, und navigieren Sie zum Microsoft Entra Admin Center (https://aad.portal.azure.com). Melden Sie sich mit einem Geschäfts-, Schul- oder Uni-Konto an, das über globale Administratorrechte für den Mandanten verfügt.
Wählen Sie im Navigationsbereich ganz links Microsoft Entra ID aus.
App-Registrierung
Wählen Sie im Navigationsbereich ganz links Verwalten der>App-Registrierungen aus.
Wählen Sie auf der Seite App-Registrierungen die Option Neue Registrierung aus, und legen Sie auf dem Bildschirm Eine Anwendung registrieren die folgenden Werte fest. Wenn Sie fertig sind, klicken Sie auf die Schaltfläche Registrieren.
- Name: MyOutlookSsoAddin2
- Unterstützte Kontotypen: Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft Entra-Verzeichnis – mehrinstanzenfähig)
- URI umleiten (optional): den Standardwert auf leer belassen
App-Authentifizierung
Im nächsten Schritt konfigurieren Sie die Registrierungsdetails der App.
Wählen Sie als Nächstes im Navigationsbereich ganz links Verwalten der>Authentifizierung aus.
Wählen Sie auf dem Bildschirm Authentifizierung die Option Eine Plattform hinzufügen aus. Wählen Sie dann die Plattform Web aus der Liste der Optionen aus:
Geben Sie als Umleitungs-URIhttps://localhost:3000/taskpane.html ein.
Wählen Sie für Implizite Genehmigung und hybride Flows, die beiden folgenden Optionen aus, und wählen Sie dann Konfigurieren:
- Zugriffstoken (werden für implizite Flows verwendet)
- ID-Token (werden für implizite und hybride Flows verwendet)
Wählen Sie nach dem erneuten Laden des Bildschirms URI hinzufügen auf der Plattform Web aus, und geben Sie https://localhost:3000/fallbackauthdialog.html ein.
Wählen Sie am oberen Bildschirmrand aus Speichern aus, um Ihre Änderungen zu speichern.
App-Zertifikate und Geheimnisse
Jetzt müssen Sie einen für die App einen neuen geheimen Clientschlüssel erstellen.
Wählen Sie im Navigationsbereich ganz links Zertifikate und Geheimnisse aus.
Wählen Sie die Schaltfläche Neuer geheimer Clientschlüssel aus:
Geben Sie, wenn Sie dazu aufgefordert werden, eine Beschreibung für den geheimen Schlüssel ein, und wählen Sie eine der bereitgestellten Optionen für Ablaufzeiten aus, und wählen Sie Hinzufügen aus. Was Sie eingeben und auswählen, spielt für die Übung keine Rolle.
Auf der Seite Zertifikate und Geheimnisse wird der neue geheime Schlüssel angezeigt.
Wichtig
Es ist wichtig, dass Sie diesen Wert kopieren, da er nur dieses eine Mal angezeigt wird. Wenn Sie die Seite verlassen und zurückkehren, wird er nur noch als maskierter Wert angezeigt.
Nach dem Kopieren des geheimen Clientschlüssels kopieren wir auch die Client-ID. Wählen Sie im Navigationsbereich ganz links Verwalten der>Übersicht aus.
API-Berechtigungen
Als Nächstes müssen Sie Microsoft Graph die Anwendungsberechtigungen erteilen.
Wählen Sie im Navigationsbereich ganz links Verwalten der>API-Berechtigungen aus.
Es ist eine bewährte Methode, nur Berechtigungen anzufordern, die für Ihre App erforderlich sind. Entfernen wir daher die ursprüngliche Berechtigung User.Read, indem wir sie auswählen und dann Berechtigung entfernen auswählen. Dann bestätigen wir mit Ja, entfernen.
Als Nächstes fügen wir die minimalen Berechtigungen hinzu, die für die Benutzer erforderlich sind, um sich mithilfe von SSO anmelden zu können.
Fügen Sie eine neue Berechtigung hinzu, indem Sie Berechtigung hinzufügen auswählen.
Wählen Sie im Bildschirm API auswählen die Option Microsoft Graph und dann Delegierte Berechtigungen aus. Wählen Sie in den nächsten Abschnitten die folgenden Berechtigungen aus, oder verwenden Sie das Suchfeld, um nach diesen Berechtigungen zu suchen:
- OpenID-Berechtigungen
- openid
- profile
- Kalender
- Calendars.Read
Nachdem Sie diese Berechtigungen ausgewählt haben, wählen Sie die Schaltfläche Berechtigungen hinzufügen aus.
Wählen Sie als Nächstes die Option Contoso die Zustimmung des Administrators gewähren. In der nun folgenden Bestätigungsaufforderung wählen Sie Ja.
Verfügbarmachen einer Anwendungs-ID-URI
Wählen Sie abschließend im Navigationsbereich ganz links Verwalten des>Verfügbarmachens einer API aus. Aus dieser Seite müssen Sie mehrere Dinge erledigen:
Wählen Sie zuerst Festlegen neben der AnwendungsID-URI aus. Dies ist die eindeutige ID unserer Anwendung. Fügen Sie localhost:3000/ direkt vor dem Protokoll und der ID der Anwendung hinzu, damit es ähnlich wie das folgende aussieht, und wählen Sie Speichern:
api://localhost:3000/f7b53c32-c205-40d8-84dc-0c15b662054c
Hinweis
Die GUID stellt die eindeutige ID für jede App dar. Ihre ID wird nicht mit der in dieser Übung verwendeten übereinstimmen.
Verfügbarmachen einer API: Von der API definierte Bereiche
Der nächste Abschnitt enthält die von der API definierten Bereiche. Dies können benutzerdefinierte Bereiche sein, mit denen Sie den Zugriff auf Daten und Funktionen einschränken können, die von der API geschützt werden.
Wählen Einen Bereich hinzufügen aus, und verwenden Sie die folgenden Werte zum Ausfüllen des Formulars:
- Bereichsname: access_as_user
- Wer kann zustimmen? Administratoren und Benutzer
- Anzeigename der Administratoreinwilligung: Office kann als Benutzer fungieren
- Beschreibung der Administratoreinwilligung: Office ermöglichen, die Web-APIs des Add-Ins mit den gleichen Berechtigungen wie der aktuelle Benutzer aufzurufen.
- Anzeigename der Benutzereinwilligung: Office kann anstelle von Ihnen fungieren.
- Beschreibung der Benutzereinwilligung: Office ermöglichen, die Web-APIs des Add-Ins mit den gleichen Berechtigungen aufzurufen, über die Sie verfügen.
- Status: Aktiviert
Verfügbarmachen einer API: Autorisierte Clientanwendungen
Im letzten Abschnitt wird angegeben, dass die API bestimmten Anwendungen automatisch vertraut und den Benutzer nicht zur Zustimmung auffordert, wenn die Anwendung diese API aufruft.
Dadurch werden die Office-Desktop- und Webanwendungen autorisiert, die API Ihres Add-Ins aufzurufen.
Wählen Sie Eine Clientanwendung hinzufügen aus, um die folgenden Anwendungen hinzuzufügen. Anwendungen werden als GUIDs hinzugefügt. Wählen Sie für jede die einzigen autorisierten Bereiche aus, die aufgeführt sind, um der Anwendung Zugriff auf den zuvor definierten Bereich zu gewähren:
d3590ed6-52b3-4102-aeff-aad2292ab01c(Microsoft Office)ea5a67f6-b6f3-4338-b240-c655ddc3cc8e(Microsoft Office)57fb890c-0dab-4253-a5e0-7188c88b2bb4(Office im Web)08e18876-6177-487e-b8b5-cf950c1e598c(Office im Web)bc59ab01-8403-45c6-8796-ac3ef710b3e3(Outlook im Web)93d53678-613d-4013-afc1-62e9e444a0a5(Office im Web)
Wenn Sie eine dieser Apps auswählen, verfügt jede von ihnen über den zuvor als autorisierten Bereich definierten Bereich.
Aktualisieren des Projekts und der Entwicklerarbeitsstation
Nachdem die Microsoft Entra-Anwendung erstellt wurde, besteht der letzte Schritt darin, Ihr Projekt und Ihre Arbeitsstation für die Verwendung der neuen App zu aktualisieren.
Suchen und öffnen Sie in Ihrem Projekt die .ENV-Datei.
Aktualisieren Sie die CLIENT_ID, um die -Client-ID, die Sie aus dem App-Registrierungsprozess kopiert haben, zu verwenden.
Suchen und öffnen Sie die Datei ./manifest.xml-Datei. Suchen Sie am Ende der Datei nach dem <WebApplicationInfo>-Element. Aktualisieren Sie in diesem Element die Elemente <ID> und <Resource>, um die neue Client-ID zu verwenden.
Suchen und öffnen Sie die ./src/helpers/fallbackauthdialog.js-Datei. Suchen Sie die Zeile, die mit const msalConfig beginnt. Dies ist das Konfigurationsobjekt „MSAL.js“. Aktualisieren Sie die clientId-Eigenschaft des Objekts mit der neuen Client-ID.
Als Nächstes müssen Sie den geheimen Clientschlüssel für die App im Anmeldeinformationsspeicher auf der Entwicklerarbeitsstation speichern. Der auszuführende Befehl hängt dabei von Ihrer Plattform ab.
Windows
Führen Sie nach dem Aktualisieren der ersten drei Werte die folgende PowerShell aus:
$ssoAppName: den Namen Ihres Projekts, z. B. MyOutlookSsoAddin$user: Ihren Windows-Benutzernamen für die Anmeldung, z. B. "MyDomain\MyUserName"$secret: Der geheime Clientschlüssel, den Sie beim Registrieren der Microsoft Entra-App kopiert haben
$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
Führen Sie nach dem Aktualisieren der ersten drei Werte in der Konsole Folgendes aus:
SSOAPPNAME: den Namen Ihres Projekts, z. B. MyOutlookSsoAddinUSER: Ihr macOS-Anmeldebenutzername, z. B. myusernameSECRET: Der geheime Clientschlüssel, den Sie beim Registrieren der Microsoft Entra-App kopiert haben
SSOAPPNAME="MyOutlookSsoAddin"
USER="myusername"
SECRET="...."
sudo security add-generic-password -a $USER -s $SSOAPPNAME -w $SECRET -U
Erstellen und erneutes Testen der App
Führen Sie den folgenden Befehl in einer Eingabeaufforderung aus, um zu transpilieren und Debuggen zu starten:
npm start
Erneutes Testen des Add-Ins im Outlook-Webclient
Öffnen Sie einen Browser, und navigieren Sie zu Outlook (https://outlook.office.com). Melden Sie sich mit einem Geschäfts-, Schul- oder Unikonto an.
Wiederholen Sie den Vorgang zum Testen des Add-Ins wie zu Beginn dieser Übung. Bevor Sie das Add-In aktivieren, müssen Sie es jedoch entfernen, da das derzeit installierte Add-In weiterhin die alte manifest.xml-Datei mit der alten Microsoft Entra-Anwendungsregistrierung verwendet.
Um das Add-In zu entfernen, führen Sie dieselben Schritte zum Installieren eines neuen Add-Ins mit lediglich dem Unterschied aus, dass Sie vor dem Hochladen Ihrer benutzerdefinierten manifest.xml-Datei die zuvor installierte entfernen:
Nachdem Sie die aktualisierte manifest.xml-Datei für das Add-In installiert haben, schließen Sie den Testvorgang ab, um die neue Logik des Add-Ins zu testen.
