Einmaliges Anmelden (Single Sign-On, SSO) Schnellstart

  • Artikel

In diesem Artikel verwenden Sie den Yeoman-Generator für Office-Add-Ins, um ein Office-Add-In für Excel, Outlook, Word oder PowerPoint zu erstellen, das einmaliges Anmelden (Single Sign-On, SSO) verwendet.

Hinweis

Die vom Yeoman-Generator für Office-Add-Ins bereitgestellte SSO-Vorlage wird nur auf localhost ausgeführt und kann nicht bereitgestellt werden. Wenn Sie ein neues Office-Add-In mit SSO für Produktionszwecke erstellen, befolgen Sie die Anweisungen unter Erstellen eines Node.js Office-Add-Ins, das einmaliges Anmelden verwendet.

Voraussetzungen

  • Node.js (die aktuellsteLTS-Version).

  • Die neueste Version von Yeoman und des Yeoman-Generators für Office-Add-Ins. Um diese Tools global zu installieren, führen Sie den folgenden Befehl an der Eingabeaufforderung aus.

    npm install -g yo generator-office

    Hinweis

    Selbst wenn Sie bereits den Yeoman-Generator installiert haben, empfehlen wir Ihnen, das npm-Paket auf die neueste Version zu aktualisieren.

  • Wenn Sie einen Mac verwenden und die Azure CLI nicht auf Ihrem Rechner installiert haben, müssen Sie Homebrew installieren. Das SSO-Konfigurationsskript, das Sie während dieses Schnellstarts ausführen werden, verwendet "Homebrew", um die Azure-Befehlszeilenschnittstelle zu installieren, und verwendet dann die Azure-Befehlszeilenschnittstelle, um SSO innerhalb von Azure zu konfigurieren.

Erstellen des Add-In-Projekts

Tipp

Der Yeoman-Generator kann ein SSO-fähiges Office-Add-In für Excel, Outlook, Word oder PowerPoint mit dem Skripttyp JavaScript oder TypeScript erstellen. In den folgenden Anweisungen werden JavaScript und Excelangegeben. Sie sollten jedoch den für Ihr Szenario am besten geeigneten Skripttyp und die Office-Clientanwendung auswählen.

Führen Sie den folgenden Befehl aus, um ein Add-In-Projekt mit dem Yeoman-Generator zu erstellen: Ein Ordner, der das Projekt enthält, wird dem aktuellen Verzeichnis hinzugefügt.

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:

  • Wählen Sie einen Projekttyp aus:Office Add-in Task Pane project supporting single sign-on (localhost)
  • Wählen Sie einen Skripttyp aus:JavaScript
  • Wie möchten Sie Ihr Add-In benennen?My Office Add-in
  • Which Office client application would you like to support? Wählen Sie Excel, Outlook, Wordoder Powerpointaus.

Eingabeaufforderungen und Antworten für den Yeoman-Generator in einer Befehlszeilenschnittstelle.

Nach Abschluss des Assistenten erstellt der Generator erstellt das Projekt und installiert unterstützende Node-Komponenten.

Hinweis

Wenn Sie Node.js Version 20.0.0 oder höher verwenden, wird möglicherweise eine Warnung angezeigt, wenn der Generator die Installation ausführt, die über eine nicht unterstützte Engine verfügt. Wir arbeiten an einer Lösung dafür. In der Zwischenzeit wirkt sich die Warnung nicht auf den Generator oder das von Ihnen generierte Projekt aus, sodass sie ignoriert werden kann.

Tipp

Die vom Yeoman-Generator nach der Erstellung des Add-In-Projekts unter Nächste Schritte bereitgestellten Anweisungen können Sie ignorieren. Die Schritt-für-Schritt-Anleitungen in diesem Artikel enthalten alle Anweisungen, die Sie zum Durchführen dieses Tutorials benötigen.

Erkunden des Projekts

Das Add-In-Projekt, das Sie mit dem Yeoman-Generator erstellt haben, enthält Code für ein SSO-fähiges Aufgabenbereich-Add-In.

Konfiguration

Die folgenden Dateien geben Konfigurationseinstellungen für das Add-In an.

  • Die ./manifest.xml-Datei im Stammverzeichnis des Projekts definiert die Einstellungen und Funktionen des Add-Ins.

  • Die Datei ./.ENV im Stammverzeichnis des Projekts definiert Konstanten, die vom Add-in-Projekt verwendet werden.

Aufgabenbereich

Die folgenden Dateien definieren die Benutzeroberfläche und Funktionalität des Aufgabenbereichs des Add-Ins.

  • Die ./src/taskpane/taskpane.html-Datei enthält das HTML-Markup für den Aufgabenbereich.

  • Die ./src/taskpane/taskpane.css-Datei enthält das CSS, das auf die Inhalte im Aufgabenbereich angewendet wird.

  • Die Datei ./src/taskpane/taskpane.js enthält Code zum Initialisieren des Add-Ins sowie Code, der die Office JavaScript-API-Bibliothek verwendet, um die Daten aus Microsoft Graph dem Office-Dokument hinzuzufügen.

Authentifizierung

Die folgenden Dateien erleichtern den SSO-Prozess und schreiben Daten in das Office-Dokument.

  • In einem JavaScript-Projekt enthält die Datei ./src/helpers/documentHelper.js Code, der die Profilinformationen des Benutzers zum Einfügen in das aktuelle Office-Dokument kapselt. Es gibt keine solche Datei in einem TypeScript-Projekt. Stattdessen befindet sich der Code, der die Profilinformationen sammelt, inline in der Datei ./src/taskpane/taskpane.ts .

  • Die Datei ./src/helpers/fallbackauthdialog.html ist die Seite ohne Benutzeroberfläche, die das JavaScript für die Ausweich-Authentifizierungsstrategie lädt. Das <script> Tag zum Laden des JavaScript wird in die Datei eingefügt, wenn Webpack.config.js ausgeführt wird.

  • Die Datei ./src/helpers/fallbackauthdialog.js enthält das JavaScript für die Ausweich-Authentifizierungsstrategie, die den Benutzer mit msal.js. anmeldet.

  • Die Datei ./src/helpers/message-helper.js enthält JavaScript, das Fehlermeldungen für den Benutzer ein- oder ausblendet.

  • Die Datei ./src/helpers/middle-tier-calls.js enthält das JavaScript, das Ihre Web-API zum Abrufen von Daten aufruft.

  • Die Datei ./src/helpers/sso-helper.js enthält den JavaScript-Aufruf der SSO-API, getAccessTokenempfängt das Zugriffstoken und schließt es in einen Aufruf von Microsoft Graph für die Daten ein. Im Falle eines Fehlers oder in Szenarien, in dem die SSO-Authentifizierung nicht unterstützt wird, wird die Fallbackstrategie aufgerufen.

Konfigurieren von SSO

Nachdem Ihr Add-In-Projekt erstellt wurde und den Code enthält, der zum Vereinfachen des SSO-Prozesses erforderlich ist, führen Sie die folgenden Schritte aus, um einmaliges Anmelden für Ihr Add-In zu konfigurieren.

  1. Wechseln Sie zum Stammordner des Projekts.

    cd "My Office Add-in"

  2. Führen Sie zum Konfigurieren des SSO für das Add-In den folgenden Befehl aus.

    npm run configure-sso

    Warnung

    Dieser Befehl schlägt fehl, wenn der Mandant so konfiguriert ist, dass eine zweistufige Authentifizierung erforderlich ist. In diesem Szenario müssen Sie die Schritte zur Azure-App-Registrierung und SSO-Konfiguration manuell ausführen, indem Sie alle Schritte im Tutorial Erstellen eines Node.js Office-Add-Ins, das einmaliges Anmelden verwendet, ausführen.

  3. Ein Webbrowserfenster wird geöffnet, und Sie werden aufgefordert, sich bei Azure anzumelden. Melden Sie sich mit Ihren Microsoft 365-Administratoranmeldeinformationen bei Azure an. Diese Anmeldeinformationen werden verwendet, um eine neue Anwendung in Azure zu registrieren und die für SSO erforderlichen Einstellungen zu konfigurieren.

    Hinweis

    Wenn Sie sich während dieses Schritts bei Azure mit nicht-Administratoranmeldeinformationen anmelden, kann das Skript "configure-sso" für Benutzer in Ihrer Organisation keine Zustimmung des Administrators für das Add-in bereitstellen. SSO steht dann den Benutzern des Add-Ins nicht zur Verfügung und Sie werden aufgefordert, sich anzumelden.

  4. Schließen Sie nach der Eingabe Ihrer Anmeldeinformationen das Browserfenster und kehren Sie zur Eingabeaufforderung zurück. Während der Ausführung des SSO-Konfigurationsvorgangs werden Statusmeldungen auf die Konsole geschrieben. Wie in den Konsolenmeldungen beschrieben, werden Dateien im Add-In-Projekt, das vom Yeoman-Generator erstellt wird, automatisch mit den Daten aktualisiert, die für den SSO-Vorgang erforderlich sind.

Testen Des Add-Ins

Wenn Sie ein Excel-, Word- oder PowerPoint-Add-In erstellt haben, führen Sie die Schritte im folgenden Abschnitt aus, um es auszuprobieren. Wenn Sie ein Outlook-Add-In erstellt haben, führen Sie stattdessen die Schritte im Abschnitt Outlook aus.

Excel, Word und PowerPoint.

Führen Sie die folgenden Schritte aus, um ein Excel-, Word- oder PowerPoint-Add-In zu testen.

  1. Führen Sie nach Abschluss des SSO-Konfigurationsvorgangs den folgenden Befehl aus, um das Projekt zu erstellen, den lokalen Webserver zu starten und das Add-In in der zuvor ausgewählten Office-Clientanwendung quer zu laden.

    Hinweis

    Office-Add-Ins sollten auch während der Entwicklung HTTPS und nicht HTTP verwenden. Wenn Sie aufgefordert werden, ein Zertifikat zu installieren, nachdem Sie einen der folgenden Befehle ausgeführt haben, akzeptieren Sie die Eingabeaufforderung, um das Zertifikat zu installieren, das der Yeoman-Generator bereitstellt. Möglicherweise ist es auch erforderlich, dass Sie Ihre Eingabeaufforderung oder Ihr Terminal als Administrator ausführen, damit die Änderungen vorgenommen werden können.

    npm start

  2. Wenn Excel, Word oder PowerPoint geöffnet wird, wenn Sie den vorherigen Befehl ausführen, stellen Sie sicher, dass Sie mit einem Benutzerkonto angemeldet sind, das Mitglied desselben Microsoft 365 organization wie das Microsoft 365-Administratorkonto ist, das Sie beim Konfigurieren von einmaligem Anmelden in Schritt 3 des vorherigen Abschnitts zum Herstellen einer Verbindung mit Azure verwendet haben. Auf diese Weise werden die geeigneten Voraussetzungen für eine erfolgreiche SSO-Implementierung festgelegt.

  3. Wählen Sie in der Office-Clientanwendung die Registerkarte Start und dann Aufgabenbereich anzeigen aus, um den Add-In-Aufgabenbereich zu öffnen.

    Excel-Add-In-Schaltfläche.

  4. Wählen Sie am unteren Rand des Aufgabenbereichs die Schaltfläche Eigene Benutzerprofilinformationen abrufen aus, um den SSO-Vorgang zu initiieren.

  5. Wenn ein Dialogfeld angezeigt wird, das Berechtigungen im Namen des Add-Ins anfordert, bedeutet dies, dass SSO für Ihr Szenario nicht unterstützt wird und das Add-In stattdessen auf eine alternative Methode zur Benutzerauthentifizierung gefallen ist. Dies kann vorkommen, wenn der Mandantenadministrator dem Add-In keinen Zugriff auf Microsoft Graph zugestimmt hat oder wenn der Benutzer nicht mit einem gültigen Microsoft-Konto oder einem gültigen Microsoft 365 Education- oder Geschäftskonto bei Office angemeldet ist. Wählen Sie Annehmen aus, um fortzufahren.

    Das Dialogfeld

    Hinweis

    Nachdem ein Benutzer diese Berechtigungsanforderung angenommen hat, wird er in Zukunft nicht mehr dazu aufgefordert.

  6. Das Add-In Ruft die Profilinformationen des angemeldeten Benutzers ab und schreibt Sie in das Dokument. Die folgende Abbildung zeigt ein Beispiel für Profilinformationen, die in ein Excel-Arbeitsblatt geschrieben wurden.

    Die Benutzerprofilinformationen im Excel-Arbeitsblatt.

Outlook

Führen Sie die folgenden Schritte aus, um ein Outlook-Add-In zu testen.

  1. Führen Sie nach Abschluss des SSO-Konfigurationsprozesses den folgenden Befehl aus, um das Projekt zu erstellen und den lokalen Webserver zu starten.

    Hinweis

    Office-Add-Ins sollten auch während der Entwicklung HTTPS und nicht HTTP verwenden. Wenn Sie aufgefordert werden, ein Zertifikat zu installieren, nachdem Sie einen der folgenden Befehle ausgeführt haben, akzeptieren Sie die Eingabeaufforderung, um das Zertifikat zu installieren, das der Yeoman-Generator bereitstellt. Möglicherweise ist es auch erforderlich, dass Sie Ihre Eingabeaufforderung oder Ihr Terminal als Administrator ausführen, damit die Änderungen vorgenommen werden können.

    npm start

  2. Laden Sie das Add-In unter Verwendung der Anweisungen unter Querladen von Outlook-Add-Ins zu Testzwecken quer. Stellen Sie sicher, dass Sie sich mit einem Benutzerkonto bei Outlook angemeldet haben, das Mitglied der gleichen Microsoft 365-Organisation wie das Microsoft 365-Administratorkonto ist, das Sie beim Konfigurieren der einmaligen Anmeldung (SSO) in Schritt 3 des vorherigen Abschnitts zum Herstellen der Verbindung mit Azure verwendet haben. Auf diese Weise werden die geeigneten Voraussetzungen für eine erfolgreiche SSO-Implementierung festgelegt.

  3. Verfassen Sie in Outlook eine neue Nachricht.

  4. Wählen Sie im Fenster zum Verfassen von Nachrichten die Schaltfläche Aufgabenbereich anzeigen aus, um den Add-In-Aufgabenbereich zu öffnen.

    Die hervorgehobene Schaltfläche des Add-In-Menübands im Outlook-Fenster zum Verfassen von Nachrichten.

  5. Wählen Sie am unteren Rand des Aufgabenbereichs die Schaltfläche Eigene Benutzerprofilinformationen abrufen aus, um den SSO-Vorgang zu initiieren.

  6. Wenn ein Dialogfeld angezeigt wird, das Berechtigungen im Namen des Add-Ins anfordert, bedeutet dies, dass SSO für Ihr Szenario nicht unterstützt wird und das Add-In stattdessen auf eine alternative Methode zur Benutzerauthentifizierung gefallen ist. Dies kann vorkommen, wenn der Mandantenadministrator dem Add-In keinen Zugriff auf Microsoft Graph zugestimmt hat oder wenn der Benutzer nicht mit einem gültigen Microsoft-Konto oder einem gültigen Microsoft 365 Education- oder Geschäftskonto bei Office angemeldet ist. Wählen Sie Annehmen aus, um fortzufahren.

    Das Dialogfeld

    Hinweis

    Nachdem ein Benutzer diese Berechtigungsanforderung angenommen hat, wird er in Zukunft nicht mehr dazu aufgefordert.

  7. Das Add-In ruft die Profilinformationen des angemeldeten Benutzers ab und schreibt Sie in den Textkörper der E-Mail-Nachricht.

    Die Benutzerprofilinformationen im Outlook-Fenster zum Verfassen von Nachrichten.

Nächste Schritte

Herzlichen Glückwunsch, Sie haben erfolgreich ein Aufgabenfenster-Add-In erstellt, das, wenn möglich, SSO verwendet oder, wenn SSO nicht unterstützt wird, eine alternative Methode der Benutzerauthentifizierung verwendet. Wenn Sie erfahren möchten, wie Sie das Add-In anpassen können, um neue Funktionen hinzuzufügen, für die unterschiedliche Berechtigungen erforderlich sind, lesen Sie Anpassen Ihres Node.js-SSO-aktivierten Add-Ins.

Problembehandlung

Siehe auch