Verwenden des einmaligen Anmeldens (Single Sign-On, SSO) in Office-Add-Ins mit Microsoft Graph
Benutzer melden sich bei Office (Online-, Mobil- und Desktopplattform) an, wofür sie entweder ihr persönliches Microsoft-Konto, ihr Microsoft 365 Education-Konto oder ihr Geschäftskonto verwenden.
Der beste Weg, wie ein Office-Add-In autorisierten Zugriff auf Microsoft Graph erhalten kann, besteht darin, die Anmeldeinformationen aus der Office-Anmeldung des Benutzers zu verwenden. Dies erlaubt ihnen den Zugriff auf ihre Microsoft Graph-Daten, ohne sich ein zweites Mal anmelden zu müssen.
In dieser Einheit erfahren Sie, wie Sie SSO in ein Office-Add-In implementieren, um Anforderungen einzureichen und Informationen aus Microsoft Graph abzurufen.
Office-Add-Ins, SSO und Microsoft Graph
Lassen Sie uns zunächst einen Blick darauf werfen, wie der Authentifizierungsablauf zur Laufzeit funktioniert, wenn ein Office-Add-In SSO mit dem Endziel implementiert, auf Microsoft Graph zuzugreifen.
Der JavaScript-Code im Add-In ruft die Office.js-API-Methode
getAccessToken()auf. Diese Methode weist die Office-Clientanwendung an, ein Zugriffstoken für das Add-In abzurufen.Hinweis
Dieses Token wird üblicherweise als Bootstrap-Zugriffstoken bezeichnet, da es später im Prozess durch ein zweites Token ersetzt wird.
Wenn der Benutzer nicht angemeldet ist, öffnet die Office-Clientanwendung ein Popupfenster, in dem sich der Benutzer anmelden kann.
Wenn der aktuelle Benutzer das Add-In zum ersten Mal verwendet, wird er zur Zustimmung aufgefordert.
Die Office-Clientanwendung fordert das Bootstrap-Zugriffstoken vom Azure AD V2.0-Endpunkt für den aktuellen Benutzer an.
Microsoft Entra ID gibt das Bootstraptoken an die Office-Clientanwendung zurück.
Die Office-Clientanwendung sendet das Bootstrap-Zugriffstoken als Teil des Ergebnisobjekts, das vom
getAccessToken()-Aufruf zurückgegeben wird, an das Add-In.Der JavaScript-Code im Add-In sendet eine HTTP-Anforderung an eine Web-API, die in der gleichen vollqualifizierten Domäne gehostet ist wie das Add-In. Das Bootstrap-Zugriffstoken wird als Autorisierungsnachweis eingeschlossen.
Serverseitiger Code validiert das empfangene Bootstrap-Zugriffstoken.
Serverseitiger Code verwendet den OAuth2-Fluss „im Auftrag von“ (On-Behalf-Of, OBO), um ein Zugriffstoken für Microsoft Graph im Austausch für das Bootstrap-Zugriffstoken abzurufen.
Microsoft Entra ID gibt das Zugriffstoken an Microsoft Graph und ein Aktualisierungstoken an das Add-In zurück, wenn das Add-In offline_access Berechtigung anfordert.
Der serverseitige Code speichert das Zugriffstoken f?r Microsoft Graph.
Serverseitiger Code sendet Anforderungen an Microsoft Graph und schließt das Zugriffstoken für Microsoft Graph ein.
Microsoft Graph gibt Daten an das Add-In zurück, welches diese an die Benutzeroberfläche des Add-In weitergeben kann.
Wenn das Zugriffstoken f?r Microsoft Graph abl?uft, kann der serverseitige Code sein Refresh-Token verwenden, um ein neues Zugriffstoken f?r Microsoft Graph zu erhalten.
Office kann nicht zur Zustimmung von Microsoft Graph-Berechtigungen auffordern
Die oben beschriebenen Schritte besagen, dass Office den Benutzer auffordern kann, den Add-In-Berechtigungen zum Anmelden zuzustimmen. Es ist jedoch anzumerken, dass Office nur die Zustimmung zum OpenID-profile-Bereich anfordern kann. Office kann den Benutzer nicht auffordern, einer der Microsoft Graph-Berechtigungen zuzustimmen.
Dies kann eine Herausforderung für Ihr Add-In darstellen, da es nicht wissen kann, ob dieses anfängliche Bootstrap-Token im OAuth2-Fluss „im Auftrag von“ verwendet werden kann, um ein Zugriffstoken zum Aufruf von Microsoft Graph zu erhalten.
Wenn Ihr Code Berechtigungen für Microsoft Graph oder weitere Berechtigungen benötigt, denen der Benutzer noch nicht zugestimmt hat, wenn Microsoft Graph das Bootstrap-Token empfängt, schlägt er mit einem bestimmten Fehlercode fehl: AADSTS65001. Dieser Fehlercode zeigt an, dass die Zustimmung zu den angeforderten Microsoft Graph-Berechtigungen noch nicht erteilt wurde.
In diesem Fall sollte Ihr Add-In dieses Szenario elegant mit einem Fallback-Autorisierungssystem behandeln, das den Benutzer auffordert, den erforderlichen Microsoft Graph-Berechtigungen zuzustimmen.
Vermeiden Sie mehrfache Umläufe: Fail-Fast
Eine Sache, die Sie bei diesen Schritten bemerken werden, sind die vielen Roundtrips zur Microsoft Entra ID. Dies gilt insbesondere für die Anforderung eines Zugriffstokens zur Verwendung mit Microsoft Graph. Ihr Add-In muss mehrere Umläufe starten müssen, bevor es herausfinden kann, ob der Benutzer weiteren Berechtigungen für Microsoft Graph zustimmen muss.
Die getAccessToken()-Methode im Office.js-SDK akzeptiert ein Optionsobjekt, das Sie für das Implementieren eines Fail-Fast-Ansatzes verwenden können. Wenn Sie an diese Methode übergeben { forMSGraphAccess: true } , führt Microsoft Entra ID eine zusätzliche Überprüfung durch, bevor das Bootstraptoken zurückgegeben wird.
Wenn der Benutzer den angeforderten Microsoft Graph-Berechtigungen zugestimmt hat, erhält Ihr Add-In das Bootstrap-Token, das Sie mithilfe des OAuth2-Flusses „im Auftrag von“ (On-Behalf-Of, OBO) zum Austausch mit Microsoft Graph verwenden können, um ein Zugriffstoken zu erhalten, mit dem Microsoft Graph aufgerufen werden kann.
Wenn der Benutzer jedoch den angeforderten Microsoft Graph-Berechtigungen nicht zugestimmt hat, antwortet Microsoft Entra ID mit dem Fehler 13012 . Ihr Code kann diesen Fehler behandeln, indem er auf das alternative Autorisierungssystem zurückgreift. Dieser alternative Prozess wird ein Dialogfeld öffnen und den Benutzer auffordern, seine Zustimmung für die notwendigen Microsoft Graph-Berechtigungen zu geben.
Auf diese Weise kann Ihr Add-In mehrfache Anforderungen vermeiden, nur um herauszufinden, dass der Benutzer Microsoft Graph-Berechtigungen zustimmen muss.
Der Code im Standard-Office-Add-In-SSO-Projekt enthält Codebausteine, der zum Implementieren dieses Fallback-Autorisierungsprozesses erforderlich ist. Diese werden alle als ./helpers/fallbackauth*.* -Dateien gefunden, eine Sammlung von HTML- und JavaScript-Dateien, die das Popupdialogfeld implementieren.
Aufrufen von Microsoft Graph aus dem clientseitigen Code
Um eine Anforderung an Microsoft Graph zu übermitteln, müssen Sie zuerst die getAccessToken()-Methode wie folgt aufrufen. In diesem Beispiel übergeben wir die allowSignInPrompt: true-Option, die Sie verwenden können, wenn das Add-In verwendet werden kann, wenn es gestartet wird und kein angemeldeter Benutzer vorhanden ist.
const sso = require("office-addin-sso");
// ...
let bootstrapToken = await OfficeRuntime.auth.getAccessToken({ allowSignInPrompt: true });
Als nächstes versuchen Sie das Bootstrap-Token gegen ein Zugriffstoken einzutauschen, welches für den Aufruf von Microsoft Graph verwendet werden kann. Es ist dieser Schritt, der den OAuth2-Fluss „im Auftrag von“ (on-behalf-of, OBO) startet:
let exchangeResponse = await sso.getGraphToken(bootstrapToken);
Unter der Voraussetzung, dass der Benutzer den erforderlichen Microsoft Graph-Berechtigungen zugestimmt hat, können Sie die Profilinformationen des Benutzers von Microsoft Graph abfragen, indem Sie die makeGraphApiCall()-Methode aufrufen, die im mitgelieferten office-addin-sso-JavaScript-Paket enthalten ist:
const response = await sso.makeGraphApiCall(exchangeResponse.access_token);
Wenn Sie mehr Kontrolle über die Anforderung an Microsoft Graph benötigen, einschließlich des Aufrufs eines bestimmten Endpunkts oder der Bereitstellung von mehr Kontrolle über die URL-Parameter, können Sie die folgende getGraphData()-Methode verwenden:
const endpoint = "/me/messages";
const urlParams = "?$select=receivedDateTime,subject,isRead&$orderby=receivedDateTime&$top=10";
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);
Wie bereits erwähnt, können alle zuvor erwähnten Codeausschnitte in einen try-catch Block eingeschlossen werden, der Authentifizierungs- und Autorisierungsfehler behandelt, die von der Microsoft Entra-ID zurückgegeben werden, wenn der Benutzer Microsoft Graph keine Einwilligung für die erforderlichen Berechtigungen erteilt hat oder sich anmelden muss. In diesen Fällen wird das Dialogsystem für die Fallbackautorisierung implementiert:
const fallbackAuthHelper = require("./fallbackAuthHelper");
// ...
try {
// 1. get bootstrap token
// 2. exchange bootstrap token for access token
// 3. call Microsoft Graph
} catch (exception) {
if (exception.code) {
if (sso.handleClientSideErrors(exception)) {
fallbackAuthHelper.dialogFallback();
}
} else {
sso.showMessage("EXCEPTION: " + JSON.stringify(exception));
}
}