Authentifizierung und Autorisierung mithilfe der Office-Dialog-API

Verwenden Sie immer die Office-Dialog-API, um Benutzer mit Ihrem Office-Add-In zu authentifizieren und zu autorisieren. Sie müssen auch die Office-Dialogfeld-API verwenden, wenn Sie die Fallbackauthentifizierung implementieren, wenn einmaliges Anmelden (Single Sign-On, SSO) nicht verwendet werden kann.

Office-Add-Ins werden in einem iframe ausgeführt, wenn sie in Office im Web geöffnet werden. Viele Identitätsautoritäten, auch als Secure Token Services (STS) bezeichnet, verhindern, dass ihre Anmeldeseite in einem iframe geöffnet wird. Dazu gehören Google, Facebook und Dienste, die durch die Microsoft Identity Platform (früher Azure AD V 2.0) geschützt sind, z. B. ein Microsoft-Konto, ein Microsoft 365 Education- oder Geschäftskonto oder ein anderes allgemeines Konto. Auch Sicherheitsfeatures, die in der Webansicht implementiert werden, wenn Office-Add-Ins in Office unter Windows oder Office auf Mac ausgeführt werden, können verhindern, dass Anmeldeseiten ordnungsgemäß funktionieren.

Damit die Autorisierung ordnungsgemäß funktioniert, muss die Anmeldeseite in einem separaten Browser oder einer webview-Steuerelementinstanz geöffnet werden. Aus diesem Grund stellt Office die Office-Dialog-API bereit, insbesondere die displayDialogAsync-Methode .

Das mit dieser API geöffnete Dialogfeld weist die folgenden Merkmale auf.

• Es ist nicht modal.
• Es handelt sich dabei um eine vollkommen separate Browserinstanz gegenüber dem Aufgabenbereich, was Folgendes bedeutet:
  • Es verfügt über eine eigene Laufzeitumgebung, ein Fensterobjekt und eine eigene globale Variablen.
  • Es gibt keine gemeinsame Ausführungsumgebung mit dem Aufgabenbereich.
  • Er verwendet nicht denselben Sitzungsspeicher (die Window.sessionStorage-Eigenschaft ) wie der Aufgabenbereich.
• Die erste im Dialogfeld geöffnete Seite muss in derselben Domäne wie der Aufgabenbereich gehostet werden, einschließlich Protokoll, Unterdomänen und Gegebenenfalls Port.
• Das Dialogfeld kann Mithilfe der messageParent-Methode Informationen zurück an den Aufgabenbereich senden. Diese Methode sollte jedoch nur von einer Seite aufgerufen werden, die in derselben Domäne wie der Aufgabenbereich gehostet ist, einschließlich Protokoll, Unterdomänen und Port. Andernfalls gibt es Komplikationen beim Aufrufen der Methode und Verarbeiten der Nachricht. Weitere Informationen finden Sie unter Domänenübergreifendes Senden von Nachrichten an die Hostlaufzeit.

Standardmäßig wird das Dialogfeld in einem neuen Webansichtssteuerelement und nicht in einem iframe geöffnet. Dadurch wird sichergestellt, dass die Anmeldeseite eines Identitätsanbieters geöffnet werden kann. Wie Sie weiter unten in diesem Artikel sehen werden, haben die Merkmale des Office-Dialogfelds Auswirkungen auf die Verwendung von Authentifizierungs- oder Autorisierungsbibliotheken wie Microsoft Authentication Library (MSAL) und Passport.

Authentifizierungsablauf mit dem Office-Dialogfeld

Nachfolgend wird ein typischer Authentifizierungsablauf beschrieben.

1. Die erste Seite, die im Dialogfeld geöffnet wird, ist eine Seite (oder eine andere Ressource), die in der Domäne des Add-Ins gehostet wird. d. h. dieselbe Domäne wie das Aufgabenbereichfenster. Diese Seite kann über eine Benutzeroberfläche verfügen, die nur besagt: "Bitte warten Sie, wir leiten Sie zu der Seite um, auf der Sie sich bei NAME-OF-PROVIDER anmelden können." Der Code auf dieser Seite erstellt die URL der Anmeldeseite des Identitätsanbieters mit Informationen, die entweder an das Dialogfeld übergeben werden, wie unter Übergeben von Informationen an den Dialog beschrieben, oder in eine Konfigurationsdatei des Add-Ins hartcodiert ist, z. B. eine web.config-Datei.
2. Anschließend leitet das Dialogfenster auf die Anmeldeseite weiter. Die URL enthält einen Abfrageparameter, der den Identitätsanbieter anweist, das Dialogfeld nach der Anmeldung des Benutzers auf eine bestimmte Seite umzuleiten. In diesem Artikel wird diese Seite redirectPage.html genannt. Auf dieser Seite können die Ergebnisse des Anmeldeversuchs mit einem Aufruf von messageParent an den Aufgabenbereich übergeben werden. Hierbei sollte es sich um eine Seite in derselben Domäne wie das Hostfenster handeln.
3. Der Dienst des Identitätsanbieters verarbeitet nun die eingehende GET-Anforderung aus dem Dialogfeldfeld. Wenn der Benutzer bereits angemeldet ist, wird das Fenster sofort zu redirectPage.html weitergeleitet und Benutzerdaten werden als Abfrageparameter eingeschlossen. Wenn der Benutzer noch nicht angemeldet ist, wird die Anmeldeseite des Anbieters im Fenster angezeigt und der Benutzer meldet sich an. Wenn sich der Benutzer bei den meisten Anbietern nicht erfolgreich anmelden kann, zeigt der Anbieter im Dialogfeld eine Fehlerseite an und leitet nicht an redirectPage.htmlum. Der Benutzer muss das Fenster über die Schaltfläche X in der Ecke schließen. Konnte sich der Benutzer erfolgreich anmelden, wird das Dialogfeld zu redirectPage.html umgeleitet und Benutzerdaten werden als Abfrageparameter eingeschlossen.
4. Wenn die Seite redirectPage.html geöffnet wird, wird messageParent aufgerufen, um den Erfolg oder Fehler an den Aufgabenbereich und optional auch die Benutzerdaten oder Fehlerdaten zu melden. Weitere mögliche Meldungen umfassen das Übergeben eines Zugriffstokens oder die Mitteilung an den Aufgabenbereich, dass das Token im Speicher ist.
5. Das DialogMessageReceived-Ereignis wird im Aufgabenbereich ausgelöst, und der zugehörige Handler schließt das Dialogfeld und führt eventuell weitere Verarbeitungsschritte der Meldung aus.

Unterstützung mehrerer Identitätsanbieter

Wenn Ihr Add-In dem Benutzer eine Auswahl an Anbietern bietet, z. B. ein Microsoft-Konto, Google oder Facebook, benötigen Sie eine lokale erste Seite (siehe vorheriger Abschnitt), die eine Benutzeroberfläche bereitstellt, auf der der Benutzer einen Anbieter auswählen kann. Die Auswahl löst die Erstellung der Anmelde-URL und die Umleitung an diese aus.

Autorisierung des Add-Ins bei einer externen Ressource

Im modernen Web sind Benutzer und Webanwendungen Sicherheitsprinzipale. Die Anwendung verfügt über eine eigene Identität und über Berechtigungen für eine Onlineressource wie etwa Microsoft 365, Google Plus, Facebook oder LinkedIn. Die Anwendung wird vor der Bereitstellung beim Ressourcenanbieter registriert. Die Registrierung umfasst:

• Eine Liste der Berechtigungen, die die Anwendung benötigt.
• Eine URL, an die der Ressourcendienst ein Zugriffstoken zurückgeben soll, wenn die Anwendung auf den Dienst zugreift.

Wenn ein Benutzer eine Funktion in der Anwendung aufruft, die auf die Benutzerdaten im Ressourcendienst zugreift, wird der Benutzer aufgefordert, sich bei dem Dienst anzumelden und der Anwendung die Berechtigungen zu gewähren, die diese für die Benutzerressourcen benötigt. Der Dienst leitet dann das Anmeldefenster an die zuvor registrierte URL weiter und übergibt das Zugriffstoken. Die Anwendung verwendet das Zugriffstoken, um auf die Benutzerressourcen zuzugreifen.

Sie können die Office-Dialog-API verwenden, um diesen Prozess mithilfe eines Flusses zu verwalten, der jenem ähnlich ist, der für die Anmeldung von Benutzern beschrieben wurde. Die einzigen Unterschiede sind:

• Wenn der Benutzer der Anwendung noch nicht die erforderlichen Berechtigungen erteilt hat, wird der Benutzer nach der Anmeldung im Dialogfeld dazu aufgefordert.
• Ihr Code im Dialogfeld sendet das Zugriffstoken an das Hostfenster, indem entweder verwendet messageParent wird, um das zeichenfolgenierte Zugriffstoken zu senden, oder indem das Zugriffstoken gespeichert wird, in dem das Hostfenster es abrufen kann (und indem verwendet messageParent wird, um dem Hostfenster mitzuteilen, dass das Token verfügbar ist). Das Token weist ein Zeitlimit auf, solange es jedoch gültig ist, kann das Hostfenster es verwenden, um direkt ohne weitere Aufforderung auf die Ressourcen des Benutzers zuzugreifen.

Einige Beispiele für Authentifizierungs-Add-ins, in denen die Office-Dialog-API für diesen Zweck verwendet wird, finden Sie unter Beispiele.

Verwenden von Authentifizierungsbibliotheken mit dem Dialogfeld

Da das Office-Dialogfeld und der Aufgabenbereich in unterschiedlichen Browserruntimeinstanzen ausgeführt werden, müssen Sie Authentifizierungs-/Autorisierungsbibliotheken anders verwenden als bei der Authentifizierung und Autorisierung im selben Fenster. In den folgenden Abschnitten wird beschrieben, wie Sie diese Bibliotheken verwenden und nicht verwenden können.

In der Regel können Sie den internen Cache der Bibliothek nicht zum Speichern von Token verwenden.

In der Regel stellen authentifizierungsbezogene Bibliotheken einen Cache im Arbeitsspeicher bereit, um das Zugriffstoken zu speichern. Wenn aufeinanderfolgende Aufrufe des Ressourcenanbieters (z. B. Google, Microsoft Graph, Facebook usw.) vorgenommen werden, überprüft die Bibliothek zuerst, ob das Token im Cache abgelaufen ist. Ist es nicht abgelaufen ist, gibt die Bibliothek das zwischengespeicherte Token zurück, anstatt einen weiteren Roundtrip zum STS für ein neues Token zu machen. Dieses Muster kann jedoch nicht in Office-Add-Ins verwendet werden. Da der Anmeldevorgang in der Browserinstanz des Office-Dialogfelds stattfindet, befindet sich der Tokencache in dieser Instanz.

Damit eng verbunden ist die Tatsache, dass eine Bibliothek in der Regel sowohl interaktive als auch „automatische“ Methoden bereitstellt, um ein Token zu erhalten. Wenn sowohl die Authentifizierung als auch die Datenaufrufe an die Ressource in derselben Browserinstanz durchführbar sind, ruft Ihr Code die automatische Methode auf, um ein Token zu erhalten, kurz bevor der Code das Token zum Datenanruf hinzufügt. Die automatische Methode überprüft, ob ein nicht abgelaufenes Token im Cache verfügbar ist, und gibt es ggf. zurück. Andernfalls ruft die silent-Methode die interaktive Methode auf, die zur Anmeldung des STS umleitet. Nach Abschluss der Anmeldung gibt die interaktive Methode das Token zurück, speichert es aber auch im Arbeitsspeicher zwischen. Wenn jedoch die Office-Dialog-API verwendet wird, befinden sich die Datenaufrufe an die Ressource, die die automatische Methode aufrufen würden, in der Browserinstanz des Aufgabenbereichs. In dieser Instanz gibt es den Tokenspeicher der Bibliothek nicht.

Alternativ kann die Dialogbrowserinstanz Ihres Add-Ins direkt die interaktive Methode der Bibliothek aufrufen. Wenn diese Methode ein Token zurückgibt, muss Ihr Code das Token explizit an einem Ort speichern, an dem die Browserinstanz des Aufgabenbereichs es abrufen kann, z. B. lokaler Speicher oder eine serverseitige Datenbank.

Eine weitere Möglichkeit besteht darin, das Token mithilfe der messageParent-Methode an den Aufgabenbereich zu übergeben. Diese Alternative ist nur möglich, wenn die interaktive Methode das Zugriffstoken an einem Ort speichert, an dem es von Ihrem Code ausgelesen werden kann. Manchmal ist die interaktive Methode einer Bibliothek so ausgelegt, dass das Token in einer privaten Eigenschaft eines Objekts gespeichert wird, auf das der Code nicht zugreifen kann.

In der Regel können Sie das Objekt "Authentifizierungskontext" der Bibliothek nicht verwenden.

Authentifizierungsbezogene Bibliotheken verwenden häufig eine Methode, bei der sowohl interaktiv ein Token abgerufen als auch ein "auth-Context"-Objekt erstellt wird, das von der Methode zurückgegeben wird. Das Token ist eine Eigenschaft des Objekts (möglicherweise privat und nicht direkt über Ihren Code zugänglich). Dieses Objekt enthält die Methoden, mit denen Daten aus der Ressource abgerufen werden. Diese Methoden beziehen das Token in die HTTP-Anforderungen ein, die sie an den Ressourcenanbieter (z. B. Google, Microsoft Graph, Facebook usw.) senden.

Diese Authentifizierungskontextobjekte und die Methoden, die sie erstellen, können in Office-Add-Ins nicht verwendet werden. Da die Anmeldung in der Browserinstanz des Office-Dialogfelds erfolgt, muss das Objekt dort erstellt werden. Die Datenaufrufe an die Ressource befinden sich jedoch in der Browserinstanz des Aufgabenbereichs, und es gibt keine Möglichkeit, das Objekt aus einer Instanz in eine andere zu übertragen. Sie können beispielsweise ein Objekt nicht mithilfe von messageParent übertragen, da messageParent nur Zeichenfolgenwerte übergeben kann. Ein JavaScript-Objekt mit Methoden kann nicht zuverlässig als Zeichenfolge dargestellt werden.

Verwenden von Bibliotheken mit der Office-Dialog-API

Zusätzlich zu oder anstelle von starren authentifizierungsbezogenen Objekten bieten die meisten Bibliotheken APIs auf einer niedrigeren Abstraktionsebene, die es Ihrem Code ermöglichen, weniger starre Hilfsobjekte zu erstellen. Beispielsweise verfügt MSAL.NET Version 3.x.x über eine API zum Erstellen einer Anmelde-URL und eine weitere API, die ein AuthResult-Objekt erstellt, das ein Zugriffstoken in einer Eigenschaft enthält, auf die Ihr Code zugreifen kann. Beispiele für MSAL.net in einem Office-Add-In finden Sie unter Office Add-In, Microsoft Graph ASP.NET und Outlook Add-In, Microsoft Graph ASP.NET. Ein Beispiel für die Verwendung von msal.js in einem Add-In finden Sie unter Office-Add-In Microsoft Graph React.

Weitere Informationen zu Authentifizierungs- und Autorisierungsbibliotheken finden Sie unter Microsoft Graph: empfohlene Bibliotheken und Andere externe Dienste: Bibliotheken.

Beispiele

• Office-Add-In Microsoft Graph ASP.NET: Ein ASP.NET-basiertes Add-In (Excel, Word oder PowerPoint), in dem die MSAL.NET-Bibliothek und der Autorisierungscodefluss zum Anmelden und Abrufen eines Zugriffstokens für Microsoft Graph-Daten verwendet werden.
• Outlook-Add-In Microsoft Graph ASP.NET: Genau wie im vorhergehenden Beispiel, aber die Office-Anwendung ist hier Outlook.
• Office-Add-In Microsoft Graph React: Ein NodeJS-basiertes Add-In (Excel, Word oder PowerPoint), in dem die msal.js-Bibliothek und der implizite Fluss zum Anmelden und Abrufen eines Zugriffstokens für Microsoft Graph-Daten verwendet werden.

Weitere Artikel

• Autorisieren von externen Diensten in Ihrem Office-Add-in
• Verwenden der Office-Dialog-API in Ihren Office-Add-ins