Microsoft Entra-Anwendungen für Office-Add-Ins und SSO
Die von Microsoft bereitgestellten Entwicklertools zum Erstellen von Office-Add-Ins mit ASP.NET oder Node.js enthaltene Hilfsprogramme, um die erforderliche Microsoft Entra-Anwendung zu registrieren. Dieses Tool configure-sso, vereinfacht nicht nur die App-Registrierung, sondern auch die Konfiguration Ihrer Entwickler-Workstation.
In dieser Lerneinheit erfahren Sie, wie Sie die Microsoft Entra-App-Registrierung für ein Office-Add-In erstellen, das einmaliges Anmelden (Single Sign-On, SSO) implementiert. Darüber hinaus lernen Sie einige von Microsoft empfohlene Best Practices kennen, wenn Sie Office-Add-Ins erstellen, die SSO implementieren.
Registrieren einer Microsoft Entra-Anwendung für Office-Add-In-SSO
Sehen wir uns die Anforderungen für die Registrierung einer Microsoft Entra-Anwendung an, die von einem Office-Add-In verwendet wird, das einmaliges Anmelden implementiert.
Registrierung einer Microsoft Entra-Anwendung
Der erste Schritt besteht darin, eine Microsoft Entra-Anwendung im Microsoft Entra Admin Center (https://aad.portal.azure.com).
Stellen Sie beim Registrieren der App sicher, dass Sie die unterstützten Kontotypen auf Konten in einer beliebigen Organisationsverzeichnisanwendung (Beliebiges Microsoft Entra-Verzeichnis – mehrinstanzenfähig) festlegen.
Wichtig
Office-Add-In-Apps können keine einzelnen Mandanten sein. Sie müssen Mehrfachmandanten sein.
Authentifizierung
Der nächste Schritt ist es, die Authentifizierungseinstellungen für die App zu konfigurieren.
In Ihrer App sollten mindestens zwei Umleitungs-URIs aufgeführt sein:
- Add-In-Seite, z. B. die URL der HTML-Seite des Aufgabenbereichs
- Fallbackseite, z. B. die fallbackauthdialog.html-Seite
Sowohl implizite Grand- als auch Hybrid-Flow-Token-Optionen sollten aktiviert sein, da Office-Add-Ins normalerweise clientseitige Apps sind:
- Zugriffstoken (werden für implizite Flows verwendet)
- ID-Token (werden für implizite und hybride Flows verwendet)
API-Berechtigungen
Ein weiterer wichtiger Teil der Microsoft Entra-App sind die Berechtigungen, die sie benötigt, um zu funktionieren.
Jeder App müssen die OpenID-Berechtigungen openid und profile erteilt werden. Einige Bibliotheken erfordern zusätzliche Berechtigungen. Für die Microsoft Authentication Library für .NET ist beispielsweise die office_access-Berechtigung erforderlich.
Wenn Ihr Add-In Berechtigungen für Microsoft Graph benötigt, sollten diese auch hier hinzugefügt werden.
Obwohl dies nicht erforderlich ist, können Sie bei der Registrierung der App als Administrator diese Berechtigungen im Namen aller Benutzer Ihres Mandanten vorab genehmigen. Dadurch wird der Authentifizierungsablauf vereinfacht, sodass die Benutzer dem Add-In bei der ersten Verwendung nicht zustimmen müssen.
Bereitstellen einer API
Ihre App muss ihre eigenen Berechtigungen für Microsoft Entra ID- und Office-Clients verfügbar machen. Legen Sie auf dem Bildschirm Api verfügbar machen den Anwendungs-ID-URI fest. Standardmäßig ist dies api://<APP_ID>, aber Sie sollten es aktualisieren, um die Domäne einzuschließen, in der Ihre Add-In-Codebasis gehostet wird.
Fügen Sie die URL vor dem <APP_ID>-Teil der URI ein. Zum Beispiel: api://addin.contoso.com/<APP_UD>. Diese Domäne muss mit der Domäne übereinstimmen, von der aus alle in der Datei manifest.xml Ihres Add-Ins definierten Ressourcen bereitgestellt werden.
Der nächste Schritt ist es, eine Berechtigung bereitzustellen, die auch als Bereich bezeichnet wird. Dieser Bereich, access_as_user, wird von den Office-Clients verwendet, um anzugeben, dass sie beim Bereitstellen des Bootstrap-Tokens für Microsoft Graph beim Starten des OAuth2-Ablaufs im Namen des angemeldeten Benutzers handeln können.
Abschließend sollten Sie diese Berechtigung allen Office-Client-Apps erteilen. Dadurch wird die App so konfiguriert, dass sie allen Office-Clientanwendungen vertraut, um die access_as_user Berechtigung zu erhalten.
Jeder Office-Clienttyp wird durch eine eindeutige ID dargestellt. Stellen Sie sicher, dass Sie die folgende Anwendung einschließen. Stellen Sie dabei sicher, dass Sie die access_as_user Berechtigung aktivieren:
ea5a67f6-b6f3-4338-b240-c655ddc3cc8e(Microsoft Office)
Wichtig
Der Dienst ea5a67f6-b6f3-4338-b240-c655ddc3cc8e ist eine Gruppenautorisierung, die alle anderen Office-Hosts umfasst, sodass Sie einfach diesen einschließen können, anstatt jede der folgenden einzelnen Anwendungen aufzulisten:
d3590ed6-52b3-4102-aeff-aad2292ab01c(Microsoft Office)57fb890c-0dab-4253-a5e0-7188c88b2bb4(Office im Web)08e18876-6177-487e-b8b5-cf950c1e598c(Office im Web)bc59ab01-8403-45c6-8796-ac3ef710b3e3(Outlook im Web)93d53678-613d-4013-afc1-62e9e444a0a5(Office im Web)
Der letzte oben aufgeführte Dienst, 93d53678-613d-4013-afc1-62e9e444a0a5, ist ein neuer SSO-Dienst , der im Januar 2022 eingeführt wurde.
Best Practices für die Entwicklung von Office-Add-In-SSOs
Microsoft empfiehlt Folgendes, wenn Sie Office-Add-Ins erstellen, die SSO implementieren.
Verwenden Sie allowConsentPrompt, wenn Sie nur das Benutzerprofil benötigen.
In einigen Szenarien verwendet Ihr Office-Add-In möglicherweise nur SSO, um das Benutzerprofil abzurufen. In diesen Fällen sollten Sie das Standardverhalten des Anmeldevorgangs überschreiben, indem Sie die { allowConsentPrompt: true } Option beim Aufrufen getAccessToken() des Office.js-SDK übergeben.
Der Standardwert dieser Eigenschaft ist false. Diese Eigenschaft ermöglicht es Office, im Hintergrund ein Zugriffstoken oder eine interaktive Einwilligung zu erhalten, falls dies erforderlich ist. Wenn die Eigenschaft auf false festgelegt ist und Office kein Token erhält, weil der Benutzer nicht zugestimmt hat, wird ein beschreibender Fehler angezeigt.
Bei der Einstellung true zeigt Office jedoch eine interaktive Einwilligung an, nachdem kein Zugriffstoken im Hintergrund abgerufen wurde.
Wichtig
Denken Sie daran, dass Office den Benutzer nur auffordern kann, der OpenID profile-Berechtigung zuzustimmen, jedoch keinen Microsoft Graph-Berechtigungen.
Implementieren einer Fallback-Autorisierungsmethode
Die Authentifizierung und Autorisierung mit Office-Add-Ins ist nicht immer ein direkter Weg zum Erfolg. Wie in diesem Modul erläutert, gibt es mehrere Szenarien, in denen Ihr Add-In während des Autorisierungsprozesses möglicherweise fehlschlägt.
Dies kann das Szenario einschließen, in dem Ihr Benutzer den für Ihr Add-In erforderlichen Microsoft Graph-Berechtigungen nicht zugestimmt hat. In diesem Fall ist es besser, wenn Ihr Add-In schnell fehlschlägt und Ihr Benutzer frühzeitig aufgefordert wird, den erforderlichen Berechtigungen zuzustimmen. Dies ist ein besserer Ansatz, als bis zu einem späteren Zeitpunkt zu warten, um den Benutzer zu benachrichtigen.
Implementieren Sie den "Fail Fast" -Ansatz für die Autorisierung
Denken Sie beim Wiederholen des vorherigen Abschnitts daran, was Sie in einer vorherigen Lektion gelernt haben. Wenn Office das anfängliche Bootstrap-Token anfordert, kann es { forGraphAccess: true } die Autorisierungsoption beim Anruf getAccessToken() des Office.js-SDK enthalten.
Wenn Microsoft Entra ID diese erhält, wird eine weitere Überprüfung durchgeführt, um festzustellen, ob der Benutzer den angeforderten Microsoft Graph-Berechtigungen bereits zugestimmt hat. Wenn dies nicht der Fall ist, antwortet Microsoft Entra ID mit einem bestimmten Fehlercode, den Ihr Add-In im Fallbackautorisierungssystem behandeln kann, um den Benutzer zur Zustimmung zu den Microsoft Graph-Berechtigungen aufzufordern.
Vorabautorisieren aller Office-Clients mit Ihrem Add-In
Wie in dieser Lerneinheit gezeigt, können Sie Ihre Microsoft Entra-Anwendungsregistrierung, die von Ihrem Office-Add-In verwendet wird, vorab autorisieren, um allen Office-Client-Apps zu vertrauen. Dies umfasst alle Desktop-, Mobil- und Web-Office-Clients.
Auf diese Weise wird sichergestellt, dass Ihr Add-In für die maximale Anzahl von Szenarien funktioniert.