Aktivieren des einmaligen Anmeldens (Single Sign-On, SSO) in einem Office-Add-In

Benutzer melden sich mit ihrem persönlichen Microsoft-Konto oder ihrem Microsoft 365 Education- oder Geschäftskonto bei Office an. Nutzen Sie dies, und verwenden Sie einmaliges Anmelden (Single Sign-On, SSO), um den Benutzer bei Ihrem Add-In zu authentifizieren und zu autorisieren, ohne dass er sich ein zweites Mal anmelden muss.

Funktionsweise von SSO zur Laufzeit

Das folgende Diagramm veranschaulicht die Funktionsweise des SSO-Prozesses. Die blauen Elemente stehen für Office oder die Microsoft-Identitätsplattform. Die grauen Elemente stellen den von Ihnen geschriebenen Code dar und umfassen den clientseitigen Code (Aufgabenbereich) und den serverseitigen Code für Ihr Add-In.

1. Im Add-In ruft Ihr JavaScript-Code die Office.js-API getAccessTokenauf. Wenn der Benutzer bereits bei Office angemeldet ist, gibt der Office-Host das Zugriffstoken mit den Angaben des angemeldeten Benutzers zurück.
2. Wenn der Benutzer nicht angemeldet ist, öffnet die Office-Hostanwendung ein Dialogfeld, in dem sich der Benutzer anmelden kann. Office leitet Sie zur Microsoft-Identitätsplattform weiter, um den Anmeldevorgang abzuschließen.
3. Wenn der aktuelle Benutzer Ihr Add-In zum ersten Mal verwendet, wird er zur Zustimmung aufgefordert.
4. Die Office-Hostanwendung fordert das Zugriffstoken von der Microsoft-Identitätsplattform für den aktuellen Benutzer an.
5. Die Microsoft-Identitätsplattform gibt das Zugriffstoken an Office zurück. Office speichert das Token in Ihrem Namen zwischen, sodass zukünftige Aufrufe von getAccessToken einfach das zwischengespeicherte Token zurückgeben.
6. Die Office-Hostanwendung gibt das Zugriffstoken als Teil des vom getAccessTokenAufruf zurückgegebenen Ergebnisobjekts an das Add-In zurück.
7. Das Token ist sowohl ein Zugriffstoken als auch ein Identitätstoken. Sie können es als Identitätstoken verwenden, um Angaben über den Benutzer zu analysieren und zu prüfen, z. B. den Namen und die E-Mail-Adresse des Benutzers.
8. Optional kann das Add-In das Token als Zugriffstoken verwenden, um authentifizierte HTTPS-Anforderungen an APIs auf der Serverseite zu senden. Da das Zugriffstoken Identitätsansprüche enthält, kann der Server Informationen speichern, die der Identität des Benutzers zugeordnet sind, z. B. die Präferenzen des Benutzers.

Anforderungen und bewährte Methoden

Das Zugriffstoken nicht zwischenspeichern

Zwischenspeichern oder speichern Sie das Zugriffstoken niemals in Ihrem clientseitigen Code. Rufen Sie immer getAccessToken auf, wenn Sie ein Zugriffstoken benötigen. Office speichert das Zugriffstoken im Zwischenspeicher (oder fordert ein neues an, wenn es abgelaufen ist). Dadurch wird verhindert, dass das Token versehentlich von Ihrem Add-In weitergegeben wird.

Moderne Authentifizierung für Outlook aktivieren

Wenn Sie mit einem Outlook-Add-In arbeiten, müssen Sie die moderne Authentifizierung für den Microsoft 365-Mandanten aktivieren. Informationen dazu finden Sie unter Aktivieren oder Deaktivieren der modernen Authentifizierung für Outlook in Exchange Online.

Implementierung eines Fallback-Authentifizierungssystems

SSO sollte nicht als einzige Authentifizierungsmethode Ihres Add-Ins verwendet werden. Es empfiehlt sich, ein alternatives Authentifizierungssystem zu implementieren, auf das Ihr Add-In in bestimmten Fehlersituationen zurückgreifen kann. Wenn Ihr Add-In beispielsweise in einer älteren Version von Office geladen wird, die SSO nicht unterstützt, schlägt der getAccessToken Aufruf fehl.

Für Excel-, Word- und PowerPoint-Add-Ins sollten Sie in der Regel auf die Verwendung der Microsoft-Identitätsplattform zurückgreifen. Weitere Informationen finden Sie unter Authentifizieren mit der Microsoft-Identitätsplattform.

Für Outlook-Add-Ins gibt es ein empfohlenes Notfallsystem. Weitere Informationen finden Sie unter Szenario: Implementieren von Single Sign-On bei Ihrem Dienst in einem Outlook-Add-In.

Sie können auch ein System von Benutzertabellen und Authentifizierung verwenden, oder Sie können einen der Social-Login-Anbieter nutzen. Eine entsprechende Anleitung für ein Office-Add-In finden Sie unter Autorisieren von externen Diensten in Ihrem Office-Add-In.

Codebeispiele, welche die Microsoft-Identitätsplattform als Notfallsystem verwenden, finden Sie unter Office Add-In NodeJS SSO und Office Add-In ASP.NET SSO.

Entwickeln eines SSO-Add-Ins

In diesem Abschnitt werden die Aufgaben beschrieben, die bei der Erstellung eines Office-Add-Ins, das SSO verwendet, ausgeführt werden müssen. Diese Aufgaben werden hier unabhängig von Sprache oder Framework beschrieben. Schrittweise Anweisungen finden Sie unter:

• Erstellen eines Node.js-Office-Add-Ins, das einmaliges Anmelden verwendet
• Erstellen eines ASP.NET-Office-Add-Ins, das einmaliges Anmelden verwendet

Registrieren Ihres Add-Ins bei der Microsoft-Identitätsplattform

Um mit SSO arbeiten zu können, müssen Sie Ihr Add-In bei der Microsoft-Identitätsplattform registrieren. Dadurch wird die Microsoft-Identitätsplattform in die Lage versetzt, Authentifizierungs- und Autorisierungsdienste für Ihr Add-In bereitzustellen. Das Erstellen der App-Registrierung umfasst die folgenden Aufgaben.

• Rufen Sie eine Anwendungs-ID (Client-ID) ab, um Ihr Add-In auf der Microsoft-Identitätsplattform zu identifizieren.
• Generieren Sie einen geheimen Clientschlüssel, der beim Anfordern eines Tokens als Kennwort für Ihr Add-In dient.
• Geben Sie die Berechtigungen an, die Ihr Add-In benötigt. Die Microsoft Graph-Berechtigungen „profile“ und „openid“ sind immer erforderlich. Je nachdem, was Ihr Add-In tun muss, benötigen Sie möglicherweise zusätzliche Berechtigungen.
• Gewähren Sie dem Add-In die Vertrauensstellung der Office-Anwendungen.
• Autorisieren Sie die Office-Anwendungen vorab für das Add-In mit dem Standardbereich access_as_user.

Weitere Informationen zu diesem Prozess finden Sie unter Registrieren eines Office-Add-Ins, das SSO mit der Microsoft-Identitätsplattform verwendet.

Konfigurieren des Add-Ins

Fügen Sie dem Add-In-Manifest neues Markup hinzu.

• <WebApplicationInfo> : Das übergeordnete Element der folgenden Elemente.
• <ID>: Die Anwendungs-ID (Client-ID), die Sie erhalten haben, als Sie das Add-In beim Microsoft Identity Platform registriert haben. Weitere Informationen finden Sie unter Registrieren eines Office-Add-Ins, das SSO mit der Microsoft-Identitätsplattformverwendet.
• <Ressource> : Der URI des Add-Ins. Dies ist derselbe URI (einschließlich des api:Protokolls), den Sie bei der Registrierung des Add-Ins bei der Microsoft-Identitätsplattform verwendet haben. Der Domänenteil dieses URI muss mit der Domäne übereinstimmen, einschließlich aller Unterdomänen, die <in den URLs im Abschnitt Ressourcen> des Add-In-Manifests verwendet werden, und der URI muss mit der im <Id-Element> angegebenen Client-ID enden.
• <Bereiche:> Das übergeordnete Element eines oder mehrerer Scope-Elemente<>.
• <Bereich> : Gibt eine Berechtigung an, die das Add-In benötigt. Die Berechtigungen profile und openID werden immer benötigt und sind möglicherweise die einzigen erforderlichen Berechtigungen. Wenn Ihr Add-In Zugriff auf Microsoft Graph oder andere Microsoft 365-Ressourcen benötigt, benötigen Sie zusätzliche <Scope-Elemente> . Für Microsoft Graph-Berechtigungen können Sie zum Beispiel die BereicheUser.Read undMail.Read anfordern. Für Bibliotheken, die Sie in Ihrem Code für den Zugriff auf Microsoft Graph verwenden, sind möglicherweise zusätzliche Berechtigungen erforderlich. Weitere Informationen finden Sie unter Berechtigung für Microsoft Graph in Ihrem Office-Add-In (Vorschau).

Bei Word-, Excel- und PowerPoint-Add-Ins fügen Sie die Markierung am Ende des Abschnitts<VersionOverrides ... xsi:type="VersionOverridesV1_0">ein. Fügen Sie für Outlook-Add-Ins das Markup am Ende des <VersionOverrides ... xsi:type="VersionOverridesV1_1"> Abschnitts hinzu.

Im Folgenden finden Sie ein Beispiel für das Markup.

<WebApplicationInfo>
    <Id>5661fed9-f33d-4e95-b6cf-624a34a2f51d</Id>
    <Resource>api://addin.contoso.com/5661fed9-f33d-4e95-b6cf-624a34a2f51d</Resource>
    <Scopes>
        <Scope>openid</Scope>
        <Scope>user.read</Scope>
        <Scope>files.read</Scope>
        <Scope>profile</Scope>
    </Scopes>
</WebApplicationInfo>

Wichtig

Wenn Ihr Add-In von einem oder mehreren Administratoren für ihre Organisationen bereitgestellt wird, erfordert das Hinzufügen neuer Bereiche zum Manifest, dass der Administrator den Updates zustimmen muss. Benutzer werden für das Add-In gesperrt, bis die Zustimmung erteilt wurde.

Hinweis

Wenn Sie die Formatanforderungen im Manifest für SSO nicht einhalten, wird Ihr Add-In von AppSource abgelehnt, bis es dem erforderlichen Format entspricht.

Einbindung des Identity-API-Anforderungssatzes

Um SSO zu verwenden, erfordert Ihr Add-In den Anforderungssatz für die Identitäts-API 1.3. Weitere Informationen finden Sie unter IdentityAPI.

Hinzufügen des clientseitigen Codes

Fügen Sie dem Add-In JavaScript-Code für folgende Aufgaben hinzu:

• Rufen Sie getAccessToken auf.
• Analysieren des Zugriffstokens oder Übergeben des Tokens an den serverseitigen Code des Add-Ins

Der folgende Code zeigt ein einfaches Beispiel für das Aufrufen getAccessToken und Analysieren des Tokens für den Benutzernamen und andere Anmeldeinformationen.

Hinweis

Dieses Beispiel behandelt nur eine Fehlerart explizit. Beispiele für eine ausführlichere Fehlerbehandlung finden Sie unter Office Add-In NodeJS SSO und Office Add-In ASP.NET SSO.

async function getUserData() {
    try {
        let userTokenEncoded = await OfficeRuntime.auth.getAccessToken();
        let userToken = jwt_decode(userTokenEncoded); // Using the https://www.npmjs.com/package/jwt-decode library.
        console.log(userToken.name); // user name
        console.log(userToken.preferred_username); // email
        console.log(userToken.oid); // user id     
    }
    catch (exception) {
        if (exception.code === 13003) {
            // SSO is not supported for domain user accounts, only
            // Microsoft 365 Education or work account, or a Microsoft account.
        } else {
            // Handle error
        }
    }
}

Zeitpunkt des Aufrufs von getAccessToken

Wenn ihr Add-In einen angemeldeten Benutzer erfordert, sollten Sie getAccessToken innerhalb Office.initializeaufrufen. Sie sollten auch allowSignInPrompt: true im options Parameter von getAccessTokenübergeben. Beispiel: OfficeRuntime.auth.getAccessToken( { allowSignInPrompt: true }); Dadurch wird sichergestellt, dass Office den Benutzer über die Benutzeroberfläche auffordert, sich jetzt anzumelden, wenn er noch nicht angemeldet ist.

Wenn das Add-In über funktionen verfügt, für die kein angemeldeter Benutzer erforderlich ist, können Sie aufrufen getAccessToken, wenn der Benutzer eine Aktion ausführt, die einen angemeldeten Benutzer erfordert. Es gibt keine signifikanten Leistungseinbußen bei redundanten Aufrufen vongetAccessToken, da Office das Zugriffstoken im Cache speichert und es bis zum Ablauf wiederverwendet, ohne bei jedem Aufruf vongetAccessTokeneinen weiteren Aufruf an die Microsoft-Identitätsplattform zu tätigen. Sie können Aufrufe von getAccessToken also allen Funktionen und Handlern hinzufügen, die eine Aktion initiieren, für die das Token erforderlich ist.

Wichtig

Als bewährte Sicherheitsmethode sollten Sie immer getAccessToken aufrufen, wenn Sie ein Zugriffstoken benötigen. Office speichert es für Sie zwischen. Zwischenspeichern oder speichern Sie das Zugriffstoken nicht mit Ihrem eigenen Code.

Übergeben des Zugriffstokens an serverseitigen Code

Wenn Sie auf Web-APIs auf Ihrem Server oder auf zusätzliche Dienste wie Microsoft Graph zugreifen müssen, müssen Sie das Zugriffstoken an Ihren serverseitigen Code übergeben. Das Zugriffstoken ermöglicht den Zugriff (für den authentifizierten Benutzer) auf Ihre Web-APIs. Außerdem kann der serverseitige Code das Token nach Identitätsinformationen durchsuchen, wenn er diese benötigt. (Siehe Verwenden des Zugriffstokens als Identitätstoken weiter unten.) Es sind viele Bibliotheken für verschiedene Sprachen und Plattformen verfügbar, die ihnen helfen können, den von Ihnen geschriebenen Code zu vereinfachen. Weitere Informationen finden Sie unter Überblick über die Microsoft Authentication Library (MSAL).

Wenn Sie auf Microsoft Graph-Daten zugreifen müssen, sollte ihr serverseitiger Code wie folgt vorgehen:

• Überprüfen des Zugriffstokens. (Weitere Informationen finden Sie weiter unten unter Überprüfen des Zugriffstokens.)
• Initiieren Sie den OAuth 2.0 On-Behalf-Of-Flow mit einem Aufruf an die Microsoft-Identitätsplattform, der das Zugriffstoken, einige Metadaten über den Benutzer und die Anmeldedaten des Add-Ins (seine ID und sein Geheimnis) enthält. Die Microsoft-Identitätsplattform gibt ein neues Zugriffstoken zurück, das für den Zugriff auf Microsoft Graph verwendet werden kann.
• Rufen Sie Daten aus Microsoft Graph unter Verwendung des neuen Tokens ab.
• Wenn Sie das neue Zugriffstoken für mehrere Aufrufe zwischenspeichern müssen, wird empfohlen, Token-Cache-Serialisierung in MSAL.NETzu verwenden.

Wichtig

Als bewährte Sicherheitsmethode sollten Sie immer den serverseitigen Code verwenden, um Microsoft Graph-Aufrufe oder andere Aufrufe auszuführen, welche die Übergabe eines Zugriffstokens erfordern. Geben Sie niemals das OBO-Token an den Client zurück, damit der Client direkte Aufrufe an Microsoft Graph durchführen kann. Dadurch wird verhindert, dass der Token abgefangen oder weitergegeben werden kann. Weitere Informationen zum richtigen Protokollablauf finden Sie im OAuth 2.0-Protokolldiagramm

Der folgende Code zeigt ein Beispiel für die Übergabe des Zugriffstokens an die Server-Seite. Das Token wird in einem Authorization Header übergeben, wenn eine Anforderung an eine serverseitige Web-API gesendet wird. In diesem Beispiel werden JSON-Daten gesendet, daher wird die POST-Methode verwendet, aber GET reicht aus, um das Zugriffstoken zu senden, wenn Sie nicht auf den Server schreiben.

$.ajax({
    type: "POST",
    url: "/api/DoSomething",
    headers: {
        "Authorization": "Bearer " + accessToken
    },
    data: { /* some JSON payload */ },
    contentType: "application/json; charset=utf-8"
}).done(function (data) {
    // Handle success
}).fail(function (error) {
    // Handle error
}).always(function () {
    // Cleanup
});

Weitere Informationen dazu, wie Sie autorisierten Zugriff auf Microsoft Graph-Daten des Benutzers erhalten, finden Sie unter Berechtigung für Microsoft Graph in Ihrem Office-Add-In (Vorschau).

Überprüfen des Zugriffstokens

Web-APIs auf Ihrem Server müssen das Zugriffstoken validieren, wenn es vom Client gesendet wird. Der Token ist ein JSON-Webtoken (JWT), was bedeutet, dass die Überprüfung genauso wie die Tokenüberprüfung in den meisten standardmäßigen OAuth-Flüssen erfolgt. Es gibt eine Reihe von Bibliotheken, welche die JWT-Überprüfung verarbeiten können, aber zu den grundlegenden Schritten zählen folgende:

• Überprüfen, ob der Token wohlgeformt ist
• Überprüfen, ob der Token von der vorgesehenen Autorität ausgestellt wurde
• Überprüfen, ob der Token auf die Web-API ausgerichtet ist

Beachten Sie bei der Überprüfung des Tokens die folgenden Richtlinien.

• Gültige SSO-Token werden von der Azure-Autorität, https://login.microsoftonline.com, ausgestellt. Der iss-Anspruch im Token sollte mit diesem Wert beginnen.
• Der audParameter des Tokens wird auf die Anwendungs-ID der Azure-App-Registrierung des Add-Ins gesetzt.
• Der scp-Parameter des Tokens wird auf access_as_user festgelegt.

Weitere Informationen zur Token-Validierung finden Sie unter Microsoft Identitätsplattform-Zugriffstoken.

Verwenden des Zugriffstokens als Identitätstoken

Wenn Ihr Add-In die Identität des Benutzers überprüfen muss, enthält das von getAccessToken() zurückgegebene Zugriffstoken Informationen, die zum Einrichten der Identität verwendet werden können. Die folgenden Ansprüche im Token beziehen sich auf die Identität.

• name: Der Anzeigename des Benutzers.
• preferred_username: Die E-Mail-Adresse des Benutzers.
• oid: Eine GUID, welche die ID des Benutzers im Microsoft-Identitätssystem darstellt.
• tid: Eine GUID, die den Mandanten darstellt, bei dem sich der Benutzer anmeldet.

Weitere Einzelheiten zu diesen und anderen Ansprüchen finden Sie unter Microsoft Identitätsplattform ID-Token. Wenn Sie eine eindeutige ID erstellen müssen, um den Benutzer in Ihrem System darzustellen, finden Sie weitere Informationen unter Verwenden von Ansprüchen, um einen Benutzer zuverlässig zu identifizieren.

Beispielzugriffstoken

Das folgende Beispiel zeigt eine typische dekodierte Nutzlast eines Zugriffstokens. Informationen zu den Eigenschaften finden Sie unter Microsoft Identitätsplattform-Zugriffstoken.

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

Verwenden von SSO mit einem Outlook-Add-In

Es gibt einige geringfügige, aber entscheidende Unterschiede zwischen der Verwendung von SSO in einem Outlook-Add-In und der Verwendung in einem Excel-, PowerPoint- oder Word-Add-In. Weitere Informationen finden Sie unter Authentifizieren eines Benutzers mit einem Single Sign-On-Token in einem Outlook-Add-In (Vorschau) sowie unter Szenario: Implementieren von Single Sign-On in Ihrem Dienst in einem Outlook-Add-In.

Unterstützung von Cookies von Drittanbietern in Google Chrome

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:

• Der nächste Schritt zum Auslaufen von Drittanbieter-Cookies in Chrome.
• Die Datenschutz-Sandbox-Zeitachse für das Web

Siehe auch

• Microsoft Identitätsplattform – Dokumentation
• Anforderungssätze
• IdentityAPI