Implementieren des einmaligen Anmeldens (Single Sign-On, SSO) für Office-Add-Ins

  • 11 Minuten

Single Sign-On (SSO) bietet Ihrem Add-In eine nahtlose Möglichkeit, Benutzer zu authentifizieren. Mittels dieser Methode kann Ihr Add-In den Benutzer authentifizieren, um Identitätsinformationen abzurufen oder sie von einem anderen gesicherten Endpunkt wie z. B Microsoft Graph zu erhalten. Dazu muss Ihr Add-In eine serverseitige Web-API aufrufen, die mit der Microsoft Entra-ID registriert ist.

In dieser Einheit werden Sie erfahren, wie die Authentifizierung mit Office-Add-Ins funktioniert und wie Sie SSO für Ihre Office-Add-Ins verwenden.

Authentifizierung und Autorisierung in Office-Add-Ins

Webanwendungen und Office-Add-Ins ermöglichen standardmäßig den anonymen Zugriff, Sie können jedoch festlegen, dass sich Benutzer bei einer Anmeldung authentifizieren müssen. Beispielsweise können Sie festlegen, dass Ihre Benutzer mit einem Microsoft-Konto bzw. einem Microsoft 365 Education- oder Geschäftskonto angemeldet sein müssen. Diese Aufgabe wird als "Benutzerauthentifizierung" bezeichnet, weil Sie dem Add-In die Möglichkeit gibt, den Benutzer zu erkennen.

Das Add-In kann auch die Zustimmung des Benutzer für den Zugriff auf seine Microsoft Graph-Daten (z. B. das Microsoft 365-Profil, OneDrive-Dateien und SharePoint-Daten) oder Daten in anderen externen Quellen wie Google, Facebook, LinkedIn, Salesforce und GitHub einholen. Diese Aufgabe wird als Add-In-Autorisierung (oder App-Autorisierung) bezeichnet, da es das Add-In ist, das autorisiert wird, nicht der Benutzer.

Sie können zwischen zwei Möglichkeiten zur Durchführung der Authentifizierung und Autorisierung wählen.

  • Einmaliges Anmelden (Single Sign-On, SSO) von Office: Ein System, das es der Benutzeranmeldung bei Office ermöglicht, auch als Anmeldung beim Add-In zu fungieren. Optional kann das Add-In auch die Office-Anmeldeinformationen des Benutzers verwenden, um das Add-In für Microsoft Graph zu autorisieren.
  • Webanwendungsauthentifizierung und -autorisierung mit Microsoft Entra ID: Auf diese Weise authentifizierten Office-Add-Ins (und andere Web-Apps) Benutzer und autorisierte Apps, bevor es ein Office SSO-System gab, und es wird weiterhin in Szenarien verwendet, in denen Office SSO nicht möglich ist. Darüber hinaus gibt es Szenarien, in denen Sie möchten, dass sich Ihre Benutzer separat bei Ihrem Add-in anmelden, auch wenn SSO verfügbar ist. Beispielsweise dann, wenn Sie Ihren Benutzer die Möglichkeit geben wollen, sich beim Add-in mit einer anderen ID anzumelden, als diejenige, mit der sie derzeit bei Office angemeldet sind.

Office-Add-Ins und Single Sign-On

Microsoft hat in 2020 die Unterstützung für SSO zu Office-Add-Ins hinzugefügt. Diese Funktionalität reduziert die Anzahl der Anmeldeaufforderungen für einen Benutzer zu Drittanbieterdiensten.

Office SSO-Unterstützung wird in Kombination mit Code in Ihren benutzerdefinierten Add-Ins, Unterstützung für SSO im Office Runtime JavaScript SDK und Microsoft Entra ID implementiert. Um einmaliges Anmelden zu unterstützen, muss ein Office-Add-In über eine entsprechende Microsoft Entra-Anwendungsregistrierung verfügen. Diese App-Registrierung definiert, welche Berechtigungen das Add-In unterstützt und welchen Office-Clientanwendungen es vertraut, um im Namen des Benutzers zu handeln.

Mithilfe dieser Unterstützung für SSO können Add-Ins die Profilinformationen des Benutzers oder Informationen von Microsoft Graph anfordern.

Benutzer können Office-Add-Ins für sich selbst zustimmen, damit das Add-In ihre Profilinformationen abrufen kann. Das Add-In kann dann diese Profilinformationen, die von Microsoft Entra ID und Office bereitgestellt werden, als ID des aktuell angemeldeten Benutzers verwenden.

Administratoren können die Zustimmung im Namen einer ganzen Organisation über einen zentralisierten Bereitstellungsprozess erteilen, sodass nicht jeder Benutzer den Einwilligungsprozess einzeln durchlaufen muss.

Office-Add-In-SSO unterstützt beide Arten von Konten, die von Microsoft unterstützt werden: Geschäfts-, Schul- und Unikonten (Microsoft Entra-Konten) und Microsoft-Konten (MSA).

Office-Add-Ins-SSO wird in Office-Webclients und den folgenden Desktop-Clients unterstützt:

  • Windows v16.0.12215.20006 (oder höher)
  • macOS v16.32.19102902 (oder höher)

SSO-Authentifizierungsfluss verstehen

Schauen wir uns an, wie der SSO-Prozess zur Laufzeit funktioniert.

Übersichtsdiagramm des Prozessablaufs der SSO-Laufzeit.

  1. JavaScript ruft im Add-In ruft eine neue Office.js-API auf: getAccessToken(). Diese Methode weist die Office-Clientanwendung an, ein Zugriffstoken für das Add-In abzurufen.
  2. Wenn der Benutzer nicht angemeldet ist, öffnet die Office-Clientanwendung ein Popupfenster, in dem sich der Benutzer anmelden kann.
  3. Der Benutzer wird zur Zustimmung aufgefordert, wenn der aktuelle Benutzer Ihr Add-In zum ersten Mal verwendet hat.
  4. Die Office-Clientanwendung fordert das Add-In-Token vom Azure AD V2.0-Endpunkt für den aktuellen Benutzer an.
  5. Microsoft Entra ID sendet das Add-In-Token an die Office-Clientanwendung.
  6. Die Office-Clientanwendung sendet das Add-In-Token als Teil des Ergebnisobjekts, das vom getAccessToken()-Aufruf zurückgegeben wird, an das Add-In.
  7. JavaScript im Add-In kann das Token analysieren und die benötigten Informationen extrahieren.
  8. Das Add-In kann optional auch eine HTTP-Anforderung an seine Serverseite senden, um weitere Daten zum Benutzer zu erhalten (beispielsweise die Präferenzen des Benutzers). Stattdessen könnte das Token selbst zur Analyse und Überprüfung an die Serverseite gesendet werden.

Implementierung von SSO in Office-Add-Ins

Damit ein Office-Add-In SSO unterstützt, müssen Sie Folgendes tun:

  1. Registrieren einer Microsoft Entra-Anwendung
  2. Zuordnen eines Office-Add-Ins zur Microsoft Entra-Anwendung
  3. Clientseitigen Code implementieren, um ein Zugriffstoken vom hostenden Office-Client zu erhalten

Lassen Sie uns jeden dieser Punkte betrachten.

Registrieren einer Microsoft Entra-Anwendung

Der erste Schritt besteht darin, eine Microsoft Entra-Anwendung für das Add-In zu registrieren.

Microsoft Entra-Anwendungen, die zur Unterstützung des einmaligen Anmeldens in Office-Add-Ins verwendet werden, haben viele Anforderungen. Sie müssen beispielsweise Multimandanten-Anwendungen sein, sie werden die access_as_user-Berechtigung offenlegen und sie sollten auch allen Office-Client-Anwendungen vertrauen, welche die App aufrufen.

Zu den von Microsoft bereitgestellten Entwicklertools gehört das Hilfsprogramm configure-sso , mit dem die Microsoft Entra-Anwendung während ihres Entwicklungsprozesses mit allen erforderlichen Einstellungen registriert wird.

In einer weiteren Lerneinheit in diesem Modul wird ausführlich erläutert, wie Sie eine neue Microsoft Entra-Anwendung für die Verwendung durch ein Office-Add-In erstellen, das einmaliges Anmelden implementiert.

Zuordnen des Office-Add-Ins zur Microsoft Entra-Anwendung

Nachdem die Microsoft Entra-Anwendung erstellt wurde, muss sie dem Office-Add-In zugeordnet werden. Dies wird in der manifest.xml-Datei des Add-In im Abschnitt <WebApplicationInfo> getan:

<WebApplicationInfo>
  <Id>056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Id>
  <Resource>api://localhost:3000/056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Resource>
  <Scopes>
    <Scope>User.Read</Scope>
    <Scope>profile</Scope>
    <Scope>openid</Scope>
  </Scopes>
</WebApplicationInfo>

In diesem Abschnitt gibt es drei Bereiche, die für Ihre Anwendung aktualisiert werden müssen:

  • ID: Dies ist die Client-ID der registrierten Microsoft Entra-Anwendung.
  • Ressource: Dies ist die URL des Add-Ins, die mit dem URI identisch ist, der beim Registrieren des Add-Ins in der Microsoft Entra-ID verwendet wurde. Der Domänenteil des URI muss mit der Domäne übereinstimmen, die in einer der URLs im <Resources>-Abschnitt der manifest.xml-Datei des Add-Ins verwendet wird.
  • Bereiche: Dies sind die Berechtigungen oder Bereiche, die das Add-In von Microsoft Entra ID benötigt.

Wichtig

Die OpenID-Berechtigungen profile und openid werden von Ihrem Add-In immer benötigt. Dies sind möglicherweise die einzigen benötigten Berechtigungen, außer wenn Ihr Add-In andere Dienste, wie z. B. Microsoft Graph, aufrufen muss.

Zusätzlich benötigen einige von Ihrem Add-In verwendete Bibliotheken möglicherweise weitere Berechtigungen. Beispielsweise benötigt MSAL.NET die offline_access-Berechtigung.

Implementieren des clientseitigen Codes

Schlussendlich muss ein Add-In clientseitigen Code implementieren, um SSO zu implementieren und zu unterstützen. Wenn Sie die von Microsoft bereitgestellten Tools verwenden, enthält Ihr Add-In-Projekt den Großteil der Codebausteine zur Unterstützung von SSO. Dies gilt, wenn Sie entweder die Office-Entwicklertools für Visual Studio 2019 für ein ASP.NET-Add-In oder den Yeoman-Generator für Microsoft Office für VS-Code für ein Node.js-basiertes Add-In verwenden.

Die API-Methode [OfficeRuntime.Auth.getAccessToken()](/javascript/api/office-runtime/officeruntime.auth) wird vom Add-In verwendet, um ein Zugriffstoken vom hostenden Office-Client anzufordern.

Der Office-Client fordert ein Zugriffstoken von Microsoft Entra ID mithilfe der Anwendung an, die zuvor mit Microsoft Entra ID registriert wurde.

Das von der Microsoft Entra-ID zurückgegebene Token kann zur Identifizierung des Benutzers verwendet werden, kann aber auch als Bootstraptoken zum Abrufen eines Zugriffstokens verwendet werden, das zum Übermitteln von Anforderungen an Microsoft Graph verwendet werden kann (vorausgesetzt, dem Add-In und dem Benutzer wurden bestimmte Microsoft Graph-Berechtigungen erteilt).

Verwenden des Zugriffstokens zum Identifizieren des Benutzers

Ihr Add-In muss möglicherweise den Benutzer identifizieren. In diesem Fall stellt Ihr Add-In dieses Token normalerweise Ihrem eigenen Backend-System zur Verfügung, welches das Token zum Speichern von Benutzereinstellungen oder anderen Informationen verwendet, die für den aktuell angemeldeten Benutzer spezifisch sind.

In diesem Szenario enthält das zurückgegebene Token einige Eigenschaften, die für Ihre Anwendung nützlich sein können:

  • name: Dies ist der Anzeigename des Benutzers.
  • preferred_username: Dies ist die UPN des Benutzers, oder die E-Mail-Adresse.
  • old: Dies ist die eindeutige Objekt-ID des Benutzers. Diese sollte verwendet werden, um den Benutzer in Ihrem Backend-System zu identifizieren, da die Eigenschaften name und preferred_username durch den Benutzer oder einen Administrator geändert werden können
  • tid: Dies ist die eindeutige Mandanten-ID, der der Benutzer angehört.

Verwendung des Zugriffstokens in Ihrer API

Wenn Sie in Ihrem API Zugriffstoken verwenden, sollten Sie akzeptiere bewährte Methoden implementieren, wenn Sie ein von Office erhaltenes Zugriffstoken weiterleiten. Dies umfasst die Überprüfung des Tokens, um sicherzustellen, dass es von der Microsoft Entra ID erstellt wurde, es von der erwarteten Autorität stammt, das Add-In die beabsichtigte Zielgruppe des Tokens ist, das Token nicht abgelaufen ist und der Bereich auf access_as_userfestgelegt ist.

Verwendung des Zugriffstokens zum Zugriff auf Microsoft Graph

In einem Szenario, in dem Ihr Add-In auf Microsoft Graph zugreifen muss, kann Ihr Code dieses von Office für Ihr Add-In bereitgestellte Token verwenden, um den OAuth2-Fluss „im Auftrag von“ (on-behalf-of, OBO) zu starten. Wenn das Token auf diese Weise verwendet wird, wird es als "Bootstrap-Token" bezeichnet, da es nur verwendet wird, um ein Zugriffstoken zu erhalten, das zum Aufrufen von Microsoft Graph verwendet werden kann.