Aktivieren des einmaligen Anmeldens für Office-Add-Ins (Vorschau)Enable single sign-on for Office Add-ins (preview)

Benutzer melden sich bei Office (Online-, Mobil- und Desktopplattform) an, wofür sie entweder ihr persönliches Microsoft-Konto oder ihr Geschäfts-, Schul- oder Unikonto (Office 365) verwenden.Users sign in to Office (online, mobile, and desktop platforms) using either their personal Microsoft account or their work or school (Office 365) account. Mithilfe von einmaligem Anmelden (Single Sign-On, SSO) können Sie die Verwendung Ihres Add-Ins durch den Benutzer autorisieren, ohne dass sich dieser ein zweites Mal anmelden muss.You can take advantage of this and use single sign-on (SSO) to authorize the user to your add-in without requiring the user to sign in a second time.

Abbildung des Anmeldeprozesses für ein Add-In

VorschaustatusPreview Status

Die Single Sign-On-API wird derzeit nur in der Vorschauversion unterstützt.The Single Sign-on API is currently supported in preview only. Entwickler können damit experimentieren, sie sollte jedoch nicht in einem Add-In für die Produktion verwendet werden.It is available to developers for experimentation; but it should not be used in a production add-in. Darüber hinaus werden Add-Ins, die SSO verwenden, in AppSource nicht akzeptiert.In addition, add-ins that use SSO are not accepted in AppSource.

SSP erfordert Office 365 (die Abonnementversion von Office).SSO requires Office 365 (the subscription version of Office). Sie sollten die neueste monatliche Version und den neuesten monatlichen Build aus dem Insider-Kanal verwenden.You should use the latest monthly version and build from the Insiders channel. Sie müssen Office-Insider sein, um diese Version nutzen zu können.You need to be an Office Insider to get this version. Weitere Informationen finden Sie unter Office-Insider werden.For more information, see Be an Office Insider. Bitte beachten Sie: Wenn ein Build zum halbjährlichen Produktionskanal hochgestuft wird, ist der Support für Vorschaufeatures, einschließlich SSO, bei diesem Build deaktiviert.Please note that when a build graduates to the production semi-annual channel, support for preview features, including SSO, is turned off for that build.

Nicht alle Office-Anwendungen unterstützen die SSO-Vorschau.Not all Office applications support the SSO preview. Sie ist in Word, Excel, PowerPoint und Outlook verfügbar.It is available in Word, Excel, Outlook, and PowerPoint. Weitere Informationen dazu, wo die Single Sign-On-API derzeit unterstützt wird, finden Sie unter Identity-API-Anforderungssätze.For more information about where the Single Sign-on API is currently supported, see IdentityAPI requirement sets.

Anforderungen und bewährte MethodenRequirements and Best Practices

Hinweis

Um dieses Feature verwenden zu können, müssen Sie die Preview-Version der Office-JavaScript-Bibliothek im Office. js-CDNverwenden.To use this feature, you must use the preview version of the Office JavaScript library from the Office.js CDN. Die Typdefinitionsdatei für die Kompilierung mit dem Satz und IntelliSense finden Sie unter CDN und DefinitelyTyped.The type definition file for TypeScript compilation and IntelliSense is found at the CDN and DefinitelyTyped. Sie können diese Typen mit npm install --save-dev @types/office-js-previewinstallieren.You can install these types with npm install --save-dev @types/office-js-preview.

Bei Verwendung eines Outlook-Add-Ins müssen Sie die moderne Authentifizierung für den Office 365-Mandanten aktivieren.If you are working with an Outlook add-in, be sure to enable Modern Authentication for the Office 365 tenancy. Informationen hierzu finden Sie unter Exchange Online: Aktivieren des Mandanten für die moderne Authentifizierung.For information about how to do this, see Exchange Online: How to enable your tenant for modern authentication.

SSO sollte nicht als einzige Authentifizierungsmethode Ihres Add-Ins verwendet werden.You should not rely on SSO as your add-in's only method of authentication. Es empfiehlt sich, ein alternatives Authentifizierungssystem zu implementieren, auf das Ihr Add-In in bestimmten Fehlersituationen zurückgreifen kann.You should implement an alternate authentication system that your add-in can fall back to in certain error situations. Sie können ein System mit Benutzertabellen und Authentifizierung verwenden oder einen der Anbieter für die Anmeldung über ein soziales Netzwerk nutzen.You can use a system of user tables and authentication, or you can leverage one of the social login providers. Eine entsprechende Anleitung für ein Office-Add-In finden Sie unter Autorisieren von externen Diensten in Ihrem Office-Add-In.For more information about how to do this with an Office add-in, see Authorize external services in your Office Add-in. Für Outlook gibt es ein empfohlenes Ausweichsystem.For Outlook, there is a recommended fallback system. Weitere Informationen finden Sie unter Szenario: Implementieren von Single Sign-On bei Ihrem Dienst in einem Outlook-Add-In.For more information, see Scenario: Implement single sign-on to your service in an Outlook add-in. Beispiele, bei denen Azure Active Directory als Ausweichsystem verwendet wird, finden Sie unter Office-Add-In NodeJS SSO und Office-Add-In ASP.NET SSO.For samples that use Azure Active Directory as the fallback system, see Office Add-in NodeJS SSO and Office Add-in ASP.NET SSO.

Funktionsweise von SSO zur LaufzeitHow SSO works at runtime

Das folgende Diagramm veranschaulicht die Funktionsweise des SSO-Prozesses.The following diagram shows how the SSO process works.

Diagramm, das den SSO-Prozess darstellt

  1. Der JavaScript-Code im Add-In ruft eine neue Office.js-API (getAccessToken) auf.In the add-in, JavaScript calls a new Office.js API getAccessToken. Dadurch wird die Office-Hostanwendung angewiesen, ein Zugriffstoken für das Add-In abzurufen.This tells the Office host application to obtain an access token to the add-in. Ein Beispielzugriffstoken finden Sie hier.See Example access token.
  2. Wenn der Benutzer nicht angemeldet ist, öffnet die Office-Hostanwendung ein Popupfenster, in dem sich der Benutzer anmelden kann.If the user is not signed in, the Office host application opens a pop-up window for the user to sign in.
  3. Wenn der aktuelle Benutzer das Add-In zum ersten Mal verwendet, wird er zum Zustimmen aufgefordert.If this is the first time the current user has used your add-in, he or she is prompted to consent.
  4. Die Office-Hostanwendung fordert das Add-In-Token vom Azure AD v2. 0-Endpunkt für den aktuellen Benutzer an.The Office host application requests the add-in token from the Azure AD v2.0 endpoint for the current user.
  5. Azure AD sendet das Add-In-Token an die Office-Hostanwendung.Azure AD sends the add-in token to the Office host application.
  6. Die Office-Hostanwendung sendet das Add-In-Token als Teil des Ergebnisobjekts, das vom getAccessToken-Aufruf zurückgegeben wird, an das Add-In.The Office host application sends the add-in token to the add-in as part of the result object returned by the getAccessToken call.
  7. Der JavaScript-Code im Add-In kann das Token analysieren und die benötigten Informationen (etwa die E-Mail-Adresse des Benutzers) extrahieren.JavaScript in the add-in can parse the token and extract the information it needs, such as the user's email address.
  8. Das Add-In kann optional auch eine HTTP-Anforderung an den Server senden, um weitere Daten zum Benutzer zu erhalten (beispielsweise die Präferenzen des Benutzers).Optionally, the add-in can send HTTP request to its server-side for more data about the user; such as the user's preferences. Alternativ kann das Token selbst zur Analyse und Überprüfung an den Server gesendet werden.Alternatively, the access token itself could be sent to the server-side for parsing and validation there.

Entwickeln eines SSO-Add-InsDevelop an SSO add-in

In diesem Abschnitt werden die Aufgaben beschrieben, die bei der Erstellung eines Office-Add-Ins, das SSO verwendet, ausgeführt werden müssen.This section describes the tasks involved in creating an Office Add-in that uses SSO. Diese Aufgaben werden hier auf eine von Sprache und Framework unabhängige Weise beschrieben.These tasks are described here in a language- and framework-agnostic way. Ausführliche exemplarische Vorgehensweisen finden Sie unter:For detailed walkthroughs, see:

Hinweis

Sie können den Yeoman-Generator zum Erstellen Ihres Node.js Office-Add-Ins mit SSO-Aktivierung verwenden.You can use the Yeoman generator to create an SSO-enabled, Node.js Office Add-in. Der Yeoman-Generator vereinfacht den Vorgang des Erstellens eines SSO-fähigen Add-Ins durch Automatisierung der Schritte, die erforderlich sind, um SSO in Azure zu konfigurieren und den Code zu generieren, der für die Verwendung eines SSO durch ein Add-In erforderlich ist.The Yeoman generator simplifies the process of creating an SSO-enabled add-in, by automating the steps required to configure SSO within Azure and generating the code that's necessary for an add-in to use SSO. Weitere Informationen finden Sie unter Einmaliges Anmelden (SSO) Schnellstart.For more information, see the Single sign-on (SSO) quick start.

Erstellen der DienstanwendungCreate the service application

Registrieren Sie das Add-In im Registrierungsportal für den Azure v2.0-Endpunkt.Dieser Prozess dauert fünf bis zehn Minuten und umfasst die folgenden Aufgaben:Register the add-in at the registration portal for the Azure v2.0 endpoint. This is a 5–10 minute process that includes the following tasks:

  • Abrufen einer Client-ID und eines Geheimnisses für das Add-InGet a client ID and secret for the add-in.
  • Angeben der Berechtigungen, die das Add-In für den AAD v.Specify the permissions that your add-in needs to AAD v. 2.0-Endpunkt (und optional für Microsoft Graph) benötigt.2.0 endpoint (and optionally to Microsoft Graph). Die Berechtigung „profile“ ist immer erforderlich.The "profile" permission is always needed.
  • Einrichten einer Vertrauensbeziehung zwischen Office-Hostanwendung und Add-InGrant the Office host application trust to the add-in.
  • Vorautorisieren der Office-Hostanwendung für das Add-In mit der Standardberechtigung access_as_userPreauthorize the Office host application to the add-in with the default permission access_as_user.

Weitere Informationen zu diesem Prozess finden Sie unter Registrieren eines Office-Add-Ins, das SSO mit dem Azure AD v2.0-Endpunkt verwendet.For more details about this process, see Register an Office Add-in that uses SSO with the Azure AD v2.0 endpoint.

Konfigurieren des Add-InsConfigure the add-in

Fügen Sie dem Add-In-Manifest neues Markup hinzu:Add new markup to the add-in manifest:

  • WebApplicationInfo: Das übergeordnete Element der folgenden Elemente.WebApplicationInfo - The parent of the following elements.
  • Id: Die Client-ID des Add-Ins. Dies ist eine Anwendungs-ID, die Sie im Rahmen der Registrierung des Add-Ins erhalten.Id - The client ID of the add-in This is an application ID that you obtain as part of registering the add-in. Weitere Informationen finden Sie unter Registrieren eines Office-Add-Ins, das SSO mit dem Azure AD v2.0-Endpunkt verwendet.See Register an Office Add-in that uses SSO with the Azure AD v2.0 endpoint.
  • Resource: Die URL des Add-Ins.Resource - The URL of the add-in. Hierbei handelt es sich um den gleichen URI (einschließlich des Protokolls api:), den Sie bei der Registrierung des Add-Ins in AAD verwendet haben.This is the same URI (including the api: protocol) that you used when registering the add-in in AAD. Der Domänenteil dieses URI muss der Domäne (einschließlich sämtlicher Unterdomänen) entsprechen, die in den URLs im Abschnitt <Resources> des Add-In-Manifests verwendet werden.The domain part of this URI should match the domain, including any subdomains, used in the URLs in the <Resources> section of the add-in's manifest.
  • Scopes: Das übergeordnete Element anderer Elemente vom Typ Scope.Scopes - The parent of one or more Scope elements.
  • Scope: Gibt eine Berechtigung an, die das Add-In für AAD benötigt.Scope - Specifies a permission that the add-in needs to AAD. Die Berechtigung profile wird immer benötigt und kann die einzige Berechtigung sein, wenn Ihr Add-In nicht auf Microsoft Graph zugreift.The profile permission is always needed and it may be the only permission needed, if your add-in does not access Microsoft Graph. Andernfalls benötigen Sie auch Scope-Elemente für die erforderlichen Microsoft Graph-Berechtigungen (beispielsweise User.Read und Mail.Read).If it does, you also need Scope elements for the required Microsoft Graph permissions; for example, User.Read, Mail.Read. Für Bibliotheken, die Sie in Ihrem Code für den Zugriff auf Microsoft Graph verwenden, sind möglicherweise zusätzliche Berechtigungen erforderlich.Libraries that you use in your code to access Microsoft Graph may need additional permissions. So benötigt beispielsweise Microsoft Authentication Library (MSAL) für .NET die Berechtigung offline_access.For example, Microsoft Authentication Library (MSAL) for .NET requires offline_access permission. Weitere Informationen finden Sie unter Berechtigung für Microsoft Graph in Ihrem Office-Add-In (Vorschau).For more information, see Authorize to Microsoft Graph from an Office Add-in.

Für andere Office-Hosts als Oultook fügen Sie das Markup dem Ende des <VersionOverrides ... xsi:type="VersionOverridesV1_0">-Abschnitts hinzu. Für Outlook fügen Sie das Markup dem Ende des <VersionOverrides ... xsi:type="VersionOverridesV1_1">-Abschnitts hinzu.For Office hosts other than Outlook, add the markup to the end of the <VersionOverrides ... xsi:type="VersionOverridesV1_0"> section. For Outlook, add the markup to the end of the <VersionOverrides ... xsi:type="VersionOverridesV1_1"> section.

Im Anschluss sehen Sie ein Beispiel für das Markup:The following is an example of the markup:

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

Hinzufügen des clientseitigen CodesAdd client-side code

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

  • Rufen Sie getAccessToken auf.Call getAccessToken.

  • Analysieren des Zugriffstokens oder Übergeben des Tokens an den serverseitigen Code des Add-InsParse the access token or pass it to the add-in’s server-side code.

Im Anschluss sehen Sie ein einfaches Beispiel für einen Aufruf von getAccessToken.Here's a simple example of a call to getAccessToken.

Hinweis

Dieses Beispiel behandelt nur eine Fehlerart explizit.This example handles only one kind of error explicitly. Beispiele für eine ausführlichere Fehlerbehandlung finden Sie unter Office Add-In NodeJS SSO und Office Add-In ASP.NET SSO.For examples of more elaborate error handling, see Office Add-in NodeJS SSO and Office Add-in ASP.NET SSO.

async function getGraphData() {
    try {
        let bootstrapToken = await OfficeRuntime.auth.getAccessToken({ allowSignInPrompt: true, forMSGraphAccess: true });

        // The /api/values controller will make the token exchange and use the
        // access token it gets back to make the call to MS Graph.
        getData("/api/DoSomething", bootstrapToken);
    }
    catch (exception) {
        if (exception.code === 13003) {
            // SSO is not supported for domain user accounts, only
            // work or school (Office 365) or Microsoft Account IDs.
        } else {
            // Handle error
        }
    }
}

Hier sehen Sie ein einfaches Beispiel für das Übergeben des Add-In-Tokens an den Server.Here's a simple example of passing the add-in token to the server-side. Das Token wird beim Zurücksenden einer Anforderung an den Server als Authorization-Header eingefügt.The token is included as an Authorization header when sending a request back to the server-side. Dieses Beispiel sieht das Senden von JSON-Daten vor und verwendet deshalb die Methode POST. Zum Senden des Zugriffstokens ist jedoch GET ausreichend, wenn Sie nicht auf den Server schreiben.This example envisions sending JSON data, so it uses the POST method, but GET is sufficient to send the access token when you are not writing to the server.

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

Zeitpunkt für den MethodenaufrufWhen to call the method

Falls Ihr Add-In nicht verwendet werden kann, wenn kein Benutzer bei Office angemeldet ist, sollten Sie getAccessToken beim Start des Add-Ins aufrufen und allowSignInPrompt: true im options-Parameter von getAccessToken übergeben.If your add-in cannot be used when no user is logged into Office, then you should call getAccessToken when the add-in launches and pass allowSignInPrompt: true in the options parameter of getAccessToken.

Falls das Add-In über Funktionen verfügt, die keinen angemeldeten Benutzer erfordern, rufen Sie getAccessToken auf, wenn der Benutzer einen Vorgang ausführt, der einen angemeldeten Benutzer erfordert.If the add-in has some functionality that doesn't require a logged in user, then you call getAccessToken when the user takes an action that requires a logged in user. Die Leistung bei redundanten Aufrufen von getAccessToken verschlechtert sich nicht nennenswert, da Office das Bootstraptoken zwischenspeichert und wiederverwendet, bis es abläuft (ohne weiteren Aufruf des AAD v.There is no significant performance degradation with redundant calls of getAccessToken because Office caches the bootstrap token and will reuse it, until it expires, without making another call to the AAD v. 2.0-Endpunkts, wenn getAccessToken aufgerufen wird).2.0 endpoint whenever getAccessToken is called. Sie können Aufrufe von getAccessToken also allen Funktionen und Handlern hinzufügen, die eine Aktion initiieren, für die das Token erforderlich ist.So you can add calls of getAccessToken to all functions and handlers that initiate an action where the token is needed.

Hinzufügen des serverseitigen CodesAdd server-side code

In den meisten Szenarien würde es wenig Sinn machen, das Zugriffstoken abzurufen, wenn das Add-In dieses nicht an eine Serverseite übergibt und es dort verwendet.In most scenarios, there would be little point to obtaining the access token, if your add-in does not pass it on to a server-side and use it there. Ihr Add-In kann beispielsweise folgende serverseitige Aufgaben ausführen:Some server-side tasks your add-in could do:

  • Erstellen von Web-API-Methoden, die aus dem Token extrahierte Benutzerinformationen verwenden – beispielsweise eine Methode, die die Präferenzen des Benutzers in Ihrer gehosteten Datenbank nachschlägt.Create one or more Web API methods that use information about the user that is extracted from the token; for example, a method that looks up the user's preferences in your hosted data base. (Weitere Informationen finden Sie weiter unten unter Verwenden des SSO-Tokens als eine Identität.) Je nach Sprache und Framework sind ggf. Bibliotheken verfügbar, die den zu schreibenden Code vereinfachen.(See Using the SSO token as an identity below.) Depending on your language and framework, libraries might be available that will simplify the code you have to write.

  • Abrufen von Microsoft Graph-Daten.Get Microsoft Graph data. Ihr serverseitiger Code muss folgende Aktionen ausführen:Your server-side code should do the following:

    • Initiieren des Flusses „Im Auftrag von“ mit einem Aufruf des Azure AD v2.0-Endpunkts, der das Zugriffstoken, einige Metadaten für den Benutzer sowie die Anmeldeinformationen des Add-Ins (ID und Geheimnis) enthält.Initiate the “on behalf of” flow with a call to the Azure AD v2.0 endpoint that includes the access token, some metadata about the user, and the credentials of the add-in (its ID and secret). In diesem Kontext wird das Zugriffstoken als Bootstrap-Token bezeichnet.In this context, the access token is called the bootstrap token.
    • Rufen Sie Daten aus Microsoft Graph unter Verwendung des neuen Tokens ab.Get data from Microsoft Graph by using the new token.
    • Optional können Sie vor dem Initiieren des Flusses das Zugriffstoken überprüfen. (Weitere Informationen finden Sie weiter unten unter Überprüfen des Zugriffstokens.)Optionally, before initiating the flow, validate the access token (see Validate the access token below).
    • Optional können Sie nach Abschluss des Flusses "Im-Auftrag-von" das neue, vom Fluss zurückgegebene Zugriffstoken zwischenspeichern, damit es in anderen Aufrufen von Microsoft Graph weiterverwendet werden kann, bis es abläuft.Optionally, after the on-behalf-of flow completes, cache the new access token that is returned from the flow so that it an be reused in other calls to Microsoft Graph until it expires.

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).For more details about getting authorized access to the user's Microsoft Graph data, see Authorize to Microsoft Graph in your Office Add-in.

Überprüfen des ZugriffstokensValidate the access token

Die Web-API kann das empfangene Zugriffstoken vor der Verwendung überprüfen.Once the Web API receives the access token, it can validate it before using it. 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.The token is a JSON Web Token (JWT), which means that validation works just like token validation in most standard OAuth flows. Es gibt eine Reihe von Bibliotheken, welche die JWT-Überprüfung verarbeiten können, aber zu den grundlegenden Schritten zählen folgende:There are a number of libraries available that can handle JWT validation, but the basics include:

  • Überprüfen, ob der Token wohlgeformt istChecking that the token is well-formed
  • Überprüfen, ob der Token von der vorgesehenen Autorität ausgestellt wurdeChecking that the token was issued by the intended authority
  • Überprüfen, ob der Token auf die Web-API ausgerichtet istChecking that the token is targeted to the Web API

Beachten Sie bei der Überprüfung des Tokens die folgenden Richtlinien:Keep in mind the following guidelines when validating the token:

  • Gültige SSO-Token werden von der Azure-Autorität, https://login.microsoftonline.com, ausgestellt.Valid SSO tokens will be issued by the Azure authority, https://login.microsoftonline.com. Der iss-Anspruch im Token sollte mit diesem Wert beginnen.The iss claim in the token should start with this value.
  • Der aud-Parameter des Tokens wird auf die Anwendungs-ID der Registrierung des Add-Ins festgelegt.The token's aud parameter will be set to the application ID of the add-in's registration.
  • Der scp-Parameter des Tokens wird auf access_as_user festgelegt.The token's scp parameter will be set to access_as_user.

Verwenden des SSO-Tokens als eine IdentitätUsing the SSO token as an identity

Wenn Ihr Add-In die Identität des Benutzers überprüfen muss, enthält der SSO-Token Informationen, mit denen die Identität ermittelt werden kann.If your add-in needs to verify the user's identity, the SSO token contains information that can be used to establish the identity. Die folgenden Ansprüche im Token beziehen sich auf die Identität.The following claims in the token relate to identity.

  • name: Der Anzeigename des Benutzers.name - The user's display name.
  • preferred_username: Die E-Mail-Adresse des Benutzers.preferred_username - The user's email address.
  • oid: Eine GUID, die die ID des Benutzers in Azure Active Directory darstellt.oid - A GUID representing the ID of the user in the Azure Active Directory.
  • tid: Eine GUID, die die ID der Organisation des Benutzers in Azure Active Directory darstellt.tid - A GUID representing the ID of the user's organization in the Azure Active Directory.

Da sich die Werte name und preferred_username ändern könnten, empfiehlt es sich, die Werte oid und tid zu verwenden, um die Identität mit dem Autorisierungsdienst Ihres Back-Ends zu korrelieren.Since the name and preferred_username values could change, we recommend that the oid and tid values be used to correlate the identity with your back-end's authorization service.

Wenn Ihr Dienst z. B. diese Werte wie {oid-value}@{tid-value} zusammen formatieren konnte, speichern Sie dies in Ihrer internen Benutzerdatenbank als Wert im Datensatz des Benutzers.For example, your service could format those values together like {oid-value}@{tid-value}, then store that as a value on the user's record in your internal user database. Bei nachfolgenden Anforderungen könnte der Benutzer mit demselben Wert abgerufen werden, und der Zugriff auf bestimmte Ressourcen könnte basierend auf Ihren vorhandenen Zugriffskontrollmechanismen ermittelt werden.Then on subsequent requests, the user could be retrieved by using the same value, and access to specific resources could be determined based on your existing access control mechanisms.

BeispielzugriffstokenExample access token

Das folgende Beispiel zeigt eine typische dekodierte Nutzlast eines Zugriffstokens.The following is a typical decoded payload of an access token. Informationen zu den Eigenschaften finden Sie in der Tokenreferenz für Azure Active Directory v2.0.For information about the properties, see Azure Active Directory v2.0 tokens reference.

{
    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-InUsing SSO with an 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.There are some small, but important differences in using SSO in an Outlook add-in from using it in an Excel, PowerPoint, or 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.Be sure to read Authenticate a user with a single sign-on token in an Outlook add-in and Scenario: Implement single sign-on to your service in an Outlook add-in.

SSO-API-ReferenzSSO API reference

getAccessTokengetAccessToken

Der OfficeRuntime-Auth-Namespace, OfficeRuntime.Auth, liefert eine Methode getAccessToken, mithilfe der Office-Host ein Zugriffstoken für die Webanwendung des Add-Ins abrufen kann.The OfficeRuntime Auth namespace, OfficeRuntime.Auth, provides a method, getAccessToken that enables the Office host to obtain an access token to the add-in's web application. Dadurch kann das Add-In indirekt auch auf die Microsoft Graph-Daten des angemeldeten Benutzers zugreifen, ohne dass sich der Benutzer ein zweites Mal anmelden muss.Indirectly, this also enables the add-in to access the signed-in user's Microsoft Graph data without requiring the user to sign in a second time.

getAccessToken(options?: AuthOptions: (result: AsyncResult<string>) => void): void;

Die Methode ruft den Azure Active Directory v2.0-Endpunkt auf, um ein Zugriffstoken für die Webanwendung Ihres Add-Ins abzurufen.The method calls the Azure Active Directory V 2.0 endpoint to get an access token to your add-in's web application. Dies ermöglicht Add-Ins die Identifizierung von Benutzern.This enables add-ins to identify users. Der serverseitige Code kann dieses Token verwenden, um für das Add-In der Web-Anwendung mithilfe von "on behalf of" OAuth flow auf Microsoft Graph zuzugreifen.Server side code can use this token to access Microsoft Graph for the add-in's web application by using the "on behalf of" OAuth flow.

Hinweis

In Outlook wird diese API nicht unterstützt, wenn das Add-In in einem Outlook.com- oder Gmail-Postfach geladen wird.In Outlook, this API is not supported if the add-in is loaded in an Outlook.com or Gmail mailbox.

HostsHosts Excel, OneNote, Outlook, PowerPoint, WordExcel, OneNote, Outlook, PowerPoint, Word
AnforderungssätzeRequirement sets IdentityAPIIdentityAPI

ParameterParameters

options: Optional.options - Optional. Akzeptiert ein AuthOptions-Objekt (siehe weiter unten) zum Definieren von Verhaltensweisen beim Anmelden.Accepts an AuthOptions object (see below) to define sign-on behaviors.

callback: Optional.callback - Optional. Akzeptiert eine Rückrufmethode, die das Token analysieren kann, um die Benutzer-ID zu ermitteln, oder die das Token im Fluss „Im Auftrag von“ verwenden kann, um Zugriff auf Microsoft Graph zu erhalten.Accepts a callback method that can parse the token for the user's ID or use the token in the "on behalf of" flow to get access to Microsoft Graph. Wenn „AsyncResult.status den Status „Erfolgreich“ hat, ist AsyncResult.value das für AAD v.If AsyncResult.status is "succeeded", then AsyncResult.value is the raw AAD v. 2.0 formatierte Zugriffstoken.2.0-formatted access token.

Die AuthOptions-Schnittstelle stellt Optionen für die Benutzererfahrung bereit, wenn Office ein Zugriffstoken für das Add-In aus AAD v.The AuthOptions interface provides options for the user experience when Office obtains an access token to the add-in from AAD v. 2.0 abruft (mit der Methode getAccessToken).2.0 with the getAccessToken method.