Übersicht über Authentifizierung und Autorisierung in Office-Add-Ins

Artikel
06/28/2023

Office-Add-Ins ermöglichen standardmäßig anonymen Zugriff. Sie können jedoch festlegen, dass sich Benutzer zur Verwendung Ihres Add-Ins mit einem Microsoft-Konto, einem Microsoft 365 Education- oder Geschäftskonto oder einem anderen allgemeinen Konto anmelden müssen. Diese Aufgabe wird als "Benutzerauthentifizierung" bezeichnet, weil Sie dem Add-In die Möglichkeit gibt, den Benutzer zu erkennen.

Ihr Add-In kann auch die Zustimmung des Benutzers für den Zugriff auf seine Microsoft Graph-Daten (z. B. sein 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.

Wichtige Ressourcen für Authentifizierung und Autorisierung

In dieser Dokumentation wird erläutert, wie Sie Office-Add-Ins erstellen und konfigurieren, um die Authentifizierung und Autorisierung erfolgreich zu implementieren. Viele der genannten Konzepte und Sicherheitstechnologien gehen jedoch über den Rahmen dieser Dokumentation hinaus. Allgemeine Sicherheitskonzepte wie OAuth-Flüsse, Tokenzwischenspeicherung oder Identitätsverwaltung werden hier beispielsweise nicht erläutert. Diese Dokumentation enthält auch keine spezifischen Informationen zu Microsoft Azure oder dem Microsoft Identity Platform. Es wird empfohlen, die folgenden Ressourcen zurate zu ziehen, wenn Sie weitere Informationen in diesen Bereichen benötigen.

SSO-Szenarien

Die Verwendung des einmaligen Anmeldens (Single Sign-On, SSO) ist für Benutzer praktisch, da sie sich nur einmal bei Office anmelden müssen. Sie müssen sich nicht separat bei Ihrem Add-In anmelden. SSO wird nicht in allen Versionen von Office unterstützt, sodass Sie weiterhin einen alternativen Anmeldeansatz implementieren müssen, indem Sie die Microsoft Identity Platform verwenden. Weitere Informationen zu unterstützten Office Versionen finden Sie unter Identitäts-API-Anforderungssätze.

Abrufen der Identität des Benutzers über SSO

Häufig benötigt Ihr Add-In nur die Identität des Benutzers. Beispielsweise möchten Sie ihr Add-In vielleicht nur personalisieren und den Namen des Benutzers im Aufgabenbereich anzeigen. Oder Sie möchten eine eindeutige ID verwenden, um den Benutzer den Daten in Ihrer Datenbank zuzuordnen. Dies kann erreicht werden, indem nur das Zugriffstoken für den Benutzer von Office abgerufen wird.

Rufen Sie die getAccessToken-Methode auf, um die Identität des Benutzers über SSO abzurufen. Die Methode gibt ein Zugriffstoken zurück, das auch ein Identitätstoken mit mehreren Ansprüche ist, die für den aktuell angemeldeten Benutzer eindeutig sind, beispielsweise preferred_username, name, sub und oid. Weitere Informationen zu diesen Eigenschaften finden Sie unter Microsoft Identity Platform – ID-Token. Ein Beispiel für das von getAccessToken zurückgegebene Token finden Sie unter Beispielzugriffstoken.

Wenn der Benutzer nicht angemeldet ist, öffnet Office ein Dialogfeld und verwendet die Microsoft Identity Platform, um den Benutzer aufzufordern, sich anzumelden. Anschließend gibt die Methode ein Zugriffstoken zurück oder löst einen Fehler aus, wenn sich der Benutzer nicht anmelden kann.

In einem Szenario, in dem Sie Daten für den Benutzer speichern müssen, finden Sie unter Microsoft Identity Platform – ID-Token Informationen dazu, wie Sie einen Wert aus dem Token abrufen, um den Benutzer eindeutig zu identifizieren. Verwenden Sie diesen Wert, um den Benutzer in einer Benutzertabelle oder Benutzerdatenbank nachzuschlagen, die Sie verwalten. Verwenden Sie die Datenbank zum Speichern von benutzerbezogenen Informationen, z. B. Benutzereinstellungen oder Benutzerkontostatus. Da Sie SSO verwenden, melden sich Ihre Benutzer nicht separat bei Ihrem Add-In an, sodass Sie kein Kennwort für den Benutzer speichern müssen.

Bevor Sie mit der Implementierung der Benutzerauthentifizierung mit SSO beginnen, sollten Sie mit dem Artikel Aktivieren des einmaligen Anmeldens für Office-Add-Ins vertraut sein.

Zugreifen auf Ihre Web-APIs über SSO

Wenn Ihr Add-In über serverseitige APIs verfügt, die einen autorisierten Benutzer erfordern, rufen Sie die getAccessToken-Methode auf, um ein Zugriffstoken abzurufen. Das Zugriffstoken bietet Zugriff auf Ihren eigenen Webserver (konfiguriert über eine Microsoft Azure-App-Registrierung). Wenn Sie APIs auf Ihrem Webserver aufrufen, übergeben Sie auch das Zugriffstoken, um den Benutzer zu autorisieren.

Der folgende Code zeigt, wie Sie eine HTTPS GET-Anforderung an die Webserver-API des Add-Ins erstellen, um bestimmte Daten abzurufen. Der Code wird clientseitig ausgeführt, z. B. in einem Aufgabenbereich. Zuerst wird das Zugriffstoken durch Aufrufen von getAccessToken abgerufen. Anschließend wird ein AJAX-Aufruf mit dem richtigen Autorisierungsheader und der richtigen URL für die Server-API erstellt.

function getOneDriveFileNames() {

    let accessToken = await Office.auth.getAccessToken();

    $.ajax({
        url: "/api/data",
        headers: { "Authorization": "Bearer " + accessToken },
        type: "GET"
    })
        .done(function (result) {
            //... work with data from the result...
        });
}

Der folgende Code zeigt ein Beispiel für einen /api/data-Handler für den REST-Aufruf aus dem vorherigen Codebeispiel. Der Code ist ASP.NET-Code, der auf einem Webserver ausgeführt wird. Das [Authorize] Attribut erfordert, dass ein gültiges Zugriffstoken vom Client übergeben wird, oder es gibt einen Fehler an den Client zurück.

    [Authorize]
    // GET api/data
    public async Task<HttpResponseMessage> Get()
    {
        //... obtain and return data to the client-side code...
    }

Zugreifen auf Microsoft Graph über SSO

In einigen Szenarien benötigen Sie nicht nur die Identität des Benutzers, sondern sie müssen auch im Namen des Benutzers auf Microsoft Graph-Ressourcen zugreifen. Beispielsweise müssen Sie vielleicht eine E-Mail senden oder einen Chat in Teams im Namen des Benutzers erstellen. Diese und weitere Aktionen können über Microsoft Graph ausgeführt werden. Sie müssen die folgenden Schritte ausführen:

Rufen Sie das Zugriffstoken für den aktuellen Benutzer über SSO ab, indem Sie getAccessToken aufrufen. Wenn der Benutzer nicht angemeldet ist, öffnet Office ein Dialogfeld und meldet den Benutzer mit dem Microsoft Identity Platform an. Nach der Anmeldung des Benutzers oder wenn der Benutzer bereits angemeldet ist, gibt die Methode ein Zugriffstoken zurück.
Übergeben Sie das Zugriffstoken an Ihren serverseitigen Code.
Verwenden Sie serverseitig den OAuth 2.0 On-Behalf-Of-Fluss, um das Zugriffstoken gegen ein neues Zugriffstoken auszutauschen, das die erforderliche Identität des delegierten Benutzers und die erforderlichen Berechtigungen des delegierten Benutzers zum Aufrufen von Microsoft Graph enthält.

Hinweis

Um optimale Sicherheit zu gewährleisten und einen Verlust des Zugriffstokens zu vermeiden, führen Sie den On-Behalf-Of-Fluss immer serverseitig aus. Rufen Sie Microsoft Graph-APIs vom Server aus und nicht vom Client aus auf. Geben Sie das Zugriffstoken nicht an den clientseitigen Code zurück.

Bevor Sie mit der Implementierung von SSO für den Zugriff auf Microsoft Graph in Ihrem Add-In beginnen, stellen Sie sicher, dass Sie mit den folgenden Artikeln gründlich vertraut sind.

Sie sollten auch mindestens einen der folgenden Artikel lesen, die Sie durch das Erstellen eines Office-Add-Ins für die Verwendung von SSO und den Zugriff auf Microsoft Graph führen. Auch wenn Sie die Schritte nicht ausführen, enthalten sie wertvolle Informationen dazu, wie Sie SSO und den On-Behalf-Of-Fluss implementieren.

Erstellen eines ASP.NET-Office-Add-Ins, das einmaliges Anmelden verwendet, das Sie durch das Beispiel unter Office Add-In ASP.NET SSO führt.
Erstellen eines Node.js-Office-Add-Ins, das einmaliges Anmelden verwendet, das Sie durch das Beispiel unter Office Add-In NodeJS SSO führt.

Nicht-SSO-Szenarien

In einigen Szenarien möchten Sie möglicherweise nicht SSO verwenden. Beispielsweise müssen Sie sich unter Umständen mit einem anderen Identitätsanbieter als Microsoft Identity Platform authentifizieren. Außerdem wird einmaliges Anmelden nicht in allen Szenarien unterstützt. Beispielsweise unterstützen ältere Versionen von Office SSO nicht. In diesem Fall müssen Sie auf ein alternatives Authentifizierungssystem für Ihr Add-In zurückgreifen.

Authentifizieren mit Microsoft Identity Platform.

Ihr Add-In kann Benutzer unter Verwendung von Microsoft Identity Platform als Authentifizierungsanbieter anmelden. Nachdem Sie sich beim Benutzer angemeldet haben, können Sie die Microsoft Identity Platform verwenden, um das Add-In für Microsoft Graph oder andere von Microsoft verwaltete Dienste zu autorisieren. Verwenden Sie diesen Ansatz als alternative Anmeldemethode, wenn SSO über Office nicht verfügbar ist. Außerdem gibt es Szenarien, in denen Sich Ihre Benutzer separat bei Ihrem Add-In anmelden sollen, auch wenn SSO verfügbar ist. Beispielsweise, wenn sie die Möglichkeit haben sollen, sich mit einer anderen ID als der, mit der sie derzeit bei Office angemeldet sind, beim Add-In anzumelden.

Es ist wichtig zu beachten, dass die Microsoft Identity Platform das Öffnen der Anmeldeseite in einem iframe nicht zulässt. Wenn ein Office-Add-In in Office im Web ausgeführt wird, ist der Aufgabenbereich ein iframe. Dies bedeutet, dass Sie die Anmeldeseite mithilfe eines über die Office-Dialogfeld-API geöffneten Dialogfelds öffnen müssen. Dies wirkt sich auf die Verwendung von Authentifizierungshilfsbibliotheken aus. Weitere Informationen finden Sie unter Authentifizierung mit der Office-Dialogfeld-API.

Informationen zum Implementieren der Authentifizierung mit Microsoft Identity Platform finden Sie unter Microsoft Identity Platform (v2.0) – Übersicht. Die Dokumentation enthält viele Tutorials und Leitfäden sowie Links zu relevanten Beispielen und Bibliotheken. Wie unter Authentifizierung mit der Office-Dialogfeld-API erläutert, müssen Sie den Code in den Beispielen möglicherweise so anpassen, dass er im Office-Dialogfeld ausgeführt wird.

Zugriff auf Microsoft Graph ohne SSO

Eine Autorisierung für Microsoft Graph-Daten für Ihr Add-In können Sie erhalten, indem Sie ein Zugriffstoken für Microsoft Graph aus Microsoft Identity Platform abrufen. Sie können dies tun, ohne sich auf SSO über Office zu verlassen (oder wenn SSO fehlgeschlagen ist oder nicht unterstützt wird). Weitere Informationen sowie weitere Details und Links zu Beispielen finden Sie unter Zugriff auf Microsoft Graph ohne SSO.

Zugriff auf Datenquellen, die nicht von Microsoft stammen

Mit beliebten Onlinediensten, wie Google, Facebook, LinkedIn, SalesForce und GitHub, können Entwickler Benutzern Zugriff auf ihre Konten in anderen Anwendungen gewähren. Damit erhalten Sie die Möglichkeit, diese Dienste in Ihr Office-Add-In einzuschließen. Eine Übersicht über die Möglichkeiten, wie dies mit Ihrem Add-In möglich ist, finden Sie unter Autorisieren externer Dienste in Ihrem Office-Add-In.

Wichtig

Bevor Sie mit dem Programmieren beginnen, sollten Sie herausfinden, ob die Datenquelle das Öffnen der Anmeldeseite in einem iFrame zulässt. Wenn ein Office-Add-In in Office im Web ausgeführt wird, ist der Aufgabenbereich ein iframe. Wenn die Datenquelle das Öffnen der Anmeldeseite in einem iframe nicht zulässt, müssen Sie die Anmeldeseite in einem Dialogfeld öffnen, das mit der Office-Dialogfeld-API geöffnet wird. Weitere Informationen finden Sie unter Authentifizierung mit der Office-Dialogfeld-API.