Autorisieren bei Microsoft Graph mit SSO

  • Artikel

Benutzer melden sich mit ihrem persönlichen Microsoft-Konto oder ihrem Microsoft 365 Education- oder Geschäftskonto bei Office an. Die beste Möglichkeit für ein Office-Add-In, autorisierten Zugriff auf Microsoft Graph zu erhalten, 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.

Add-In-Architektur f?r SSO und Microsoft Graph

Zusätzlich zu den Seiten und dem JavaScript der Webanwendung muss das Add-In in derselben vollqualifizierten Domäne eine oder mehrere Web-APIs hosten, die ein Zugriffstoken für Microsoft Graph abrufen und Abfragen an das Tool stellen.

Das Add-In-Manifest enthält ein <WebApplicationInfo-Element> , das wichtige Informationen zur Azure-App-Registrierung für Office bereitstellt, einschließlich der Berechtigungen für Microsoft Graph, die das Add-In benötigt.

Funktionsweise zur Laufzeit

Das folgende Diagramm zeigt die Schritte, die für die Anmeldung und den Zugriff auf Microsoft Graph erforderlich sind. Der gesamte Prozess verwendet OAuth 2.0- und JWT-Zugriffstoken.

Diagramm, das den SSO-Prozess zeigt.

  1. Der clientseitige Code des Add-Ins ruft die Office.js API getAccessToken auf. Dadurch wird der Office-Host aufgefordert, ein Zugriffstoken für das Add-In abzurufen.

    Wenn der Benutzer nicht angemeldet ist, stellt der Office-Host in Verbindung mit dem Microsoft Identity Platform eine Benutzeroberfläche für die Anmeldung und Zustimmung des Benutzers bereit.

  2. Der Office-Host fordert ein Zugriffstoken vom Microsoft Identity Platform an.

  3. Die Microsoft Identity Platform gibt das Zugriffstoken A an den Office-Host zurück. Zugriffstoken A bietet nur Zugriff auf die eigenen serverseitigen APIs des Add-Ins. Es bietet keinen Zugriff auf Microsoft Graph.

  4. Der Office-Host gibt Zugriffstoken A an den clientseitigen Code des Add-Ins zurück. Jetzt kann der clientseitige Code authentifizierte Aufrufe an die serverseitigen APIs ausführen.

  5. Der clientseitige Code sendet eine HTTP-Anforderung an eine Web-API auf der Serverseite, die eine Authentifizierung erfordert. Es enthält Zugriffstoken A als Autorisierungsnachweis. Serverseitiger Code überprüft Zugriffstoken A.

  6. Der serverseitige Code verwendet den OAuth 2.0 On-Behalf-Of-Flow (OBO), um ein neues Zugriffstoken mit Berechtigungen für Microsoft Graph anzufordern.

  7. Die Microsoft Identity Platform gibt das neue Zugriffstoken B mit Berechtigungen für Microsoft Graph zurück (und ein Aktualisierungstoken, wenn das Add-In offline_access Berechtigung anfordert). Der Server kann optional Zugriffstoken B zwischenspeichern.

  8. Der serverseitige Code sendet eine Anforderung an eine Microsoft Graph-API und enthält Zugriffstoken B mit Berechtigungen für Microsoft Graph.

  9. Microsoft Graph gibt Daten an den serverseitigen Code zurück.

  10. Der serverseitige Code gibt die Daten an den clientseitigen Code zurück.

Bei nachfolgenden Anforderungen übergibt der Clientcode immer zugriffstoken A , wenn authentifizierte Aufrufe an serverseitigen Code ausgeführt werden. Der serverseitige Code kann Token B zwischenspeichern, sodass es bei zukünftigen API-Aufrufen nicht erneut angefordert werden muss.

Entwickeln Sie ein SSO-Add-In, das auf Microsoft Graph zugreift

Sie entwickeln ein Add-In, das genauso wie jede andere Anwendung, die SSO verwendet, auf Microsoft Graph zugreift. Eine ausführliche Beschreibung finden Sie unter Aktivieren des einmaligen Anmeldens für Office-Add-Ins. Der Unterschied besteht darin, dass es obligatorisch ist, dass das Add-In über eine serverseitige Web-API verfügt.

Abhängig von Ihrer Sprache und Ihrem Framework sind möglicherweise Bibliotheken verfügbar, die den serverseitigen Code vereinfachen, den Sie schreiben müssen. Ihr Code sollte die folgenden Aktionen ausführen:

Beispiele für ausführliche Vorgehensweisen und Szenarien finden Sie unter:

Verteilen von SSO-fähigen Add-Ins in Microsoft AppSource

Wenn ein Microsoft 365-Administrator ein Add-In aus AppSource erwirbt, kann der Administrator es über integrierte Apps neu verteilen und dem Add-In die Administratoreinwilligung für den Zugriff auf Microsoft Graph-Bereiche erteilen. Es ist jedoch auch möglich, dass der Endbenutzer das Add-In direkt aus AppSource abruft. In diesem Fall muss der Benutzer dem Add-In seine Zustimmung erteilen. Dies kann zu einem potenziellen Leistungsproblem führen, für das wir eine Lösung bereitgestellt haben.

Wenn Ihr Code die allowConsentPrompt Option im Aufruf von getAccessTokenübergibt, kann OfficeRuntime.auth.getAccessToken( { allowConsentPrompt: true } );Office den Benutzer zur Zustimmung auffordern, wenn die Microsoft Identity Platform Office meldet, dass dem Add-In noch keine Zustimmung erteilt wurde. Aus Sicherheitsgründen kann Office den Benutzer jedoch nur auffordern, dem Microsoft Graph-Bereich profile zuzustimmen. Office kann nicht zur Zustimmung für andere Microsoft Graph-Bereiche auffordern, nicht einmal User.Read. Dies bedeutet, dass Office ein Zugriffstoken zurückgibt, wenn der Benutzer bei der Eingabeaufforderung seine Zustimmung erteilt. Der Versuch, das Zugriffstoken gegen ein neues Zugriffstoken mit zusätzlichen Microsoft Graph-Bereichen auszutauschen, schlägt jedoch mit einem Fehler AADSTS65001 fehl, was bedeutet, dass die Zustimmung (für Microsoft Graph-Bereiche) nicht erteilt wurde.

Hinweis

Die Anforderung der Zustimmung mit { allowConsentPrompt: true } kann auch für den profile Bereich weiterhin fehlschlagen, wenn der Administrator die Zustimmung des Endbenutzers deaktiviert hat. Weitere Informationen finden Sie unter Konfigurieren der Zustimmung von Endbenutzern für Anwendungen mithilfe von Azure Active Directory.

Ihr Code kann und sollte diesen Fehler behandeln, indem er auf ein alternatives Authentifizierungssystem zurückgreift, das den Benutzer zur Zustimmung zu Microsoft Graph-Bereichen auffordert. Codebeispiele finden Sie unter Erstellen eines Node.js Office-Add-Ins, das einmaliges Anmelden verwendet , und Erstellen eines ASP.NET Office-Add-Ins, das einmaliges Anmelden verwendet, und den Beispielen, mit denen sie verknüpft sind. Der gesamte Prozess erfordert mehrere Roundtrips zum Microsoft Identity Platform. Um diese Leistungseinbußen zu vermeiden, schließen Sie die forMSGraphAccess Option in den Aufruf von getAccessTokenein, OfficeRuntime.auth.getAccessToken( { forMSGraphAccess: true } )z. B. . Dies signalisiert Office, dass Ihr Add-In Microsoft Graph-Bereiche benötigt. Office fordert den Microsoft Identity Platform auf, zu überprüfen, ob dem Add-In bereits die Zustimmung zu Microsoft Graph-Bereichen erteilt wurde. Falls vorhanden, wird das Zugriffstoken zurückgegeben. Wenn dies nicht der Fall ist, gibt der Aufruf von getAccessToken den Fehler 13012 zurück. Ihr Code kann diesen Fehler behandeln, indem er sofort auf ein alternatives Authentifizierungssystem zurückfällt, ohne einen verhedderten Versuch zu unternehmen, Token mit dem Microsoft Identity Platform auszutauschen.

Als bewährte Methode sollten Sie immer an getAccessToken übergebenforMSGraphAccess, wenn Ihr Add-In in AppSource verteilt wird und Microsoft Graph-Bereiche benötigt.

Details zum einmaligen Anmelden mit einem Outlook-Add-In

Wenn Sie ein Outlook-Add-In entwickeln, das SSO verwendet, und sie zu Testzwecken querladen, gibt Office immer den Fehler 13012 zurück, wenn forMSGraphAccess an getAccessToken übergeben wird, auch wenn die Administratoreinwilligung erteilt wurde. Aus diesem Grund sollten Sie die forMSGraphAccess Option beim Entwickeln eines Outlook-Add-Ins auskommentieren. Stellen Sie sicher, dass Sie die Auskommentierung der Option aufheben, wenn Sie die Bereitstellung für die Produktion durchführen. Die gefälschte Version 13012 tritt nur beim Querladen in Outlook auf.

Achten Sie für Outlook-Add-Ins darauf, die moderne Authentifizierung für den Microsoft 365-Mandanten zu aktivieren. Informationen dazu finden Sie unter Aktivieren oder Deaktivieren der modernen Authentifizierung für Outlook in Exchange Online.

Google Chrome stellt cookies von Drittanbietern im Jahr 2024 aus und führt ein Feature namens Tracking Prevention ein. Wenn die Nachverfolgungsverhinderung im Chrome-Browser aktiviert ist, kann Ihr Add-In keine Cookies von Drittanbietern verwenden. Ihr Add-In kann bei der Authentifizierung des Benutzers auf Probleme stoßen, z. B. mehrfache Anmeldeanforderungen oder Fehler.

Informationen zu verbesserten Authentifizierungsfunktionen finden Sie unter Verwenden des Gerätezustands für eine verbesserte SSO-Erfahrung in Browsern mit blockierten Cookies von Drittanbietern.

Weitere Informationen zum Google Chrome-Rollout finden Sie in den folgenden Ressourcen:

Siehe auch