Authentifizieren eines Benutzers mit einem Single Sign-On-Token in einem Outlook-Add-InAuthenticate a user with an single-sign-on token in an Outlook add-in

Single Sign-On-Zugriffstoken bieten Ihrem Add-In eine nahtlose Möglichkeit, Zugriffstoken zum Aufrufen der Microsoft Graph-API zu authentifizieren und abzurufen.Single sign-on access tokens provide a seamless way for your add-in to authenticate and obtain access tokens to call the Microsoft Graph API. Erwägen Sie die Verwendung von SSO-Zugriffstoken, wenn für Ihr Add-In Folgendes gilt:Consider using SSO access tokens if your add-in:

  • Es wird hauptsächlich von Office 365-Benutzern verwendetIs used primarily by Office 365 users
  • Es benötigt Zugriff auf:Needs access to:
    • Microsoft-Dienste, die im Rahmen von Microsoft Graph bereitgestellt werdenMicrosoft services that are exposed as part of the Microsoft Graph
    • Ein Nicht-Microsoft-Dienst, den Sie steuernA non-Microsoft service that you control

Die SSO-Authentifizierungsmethode verwendet den von Azure Active Directory bereitgestellten OAuth2-Im-Auftrag-von-Ablauf.The SSO authentication method uses the OAuth2 On-Behalf-Of flow provided by Azure Active Directory. Sie erfordert, dass sich das Add-In im Anwendungsregistrierungsportal registriert und alle erforderlichen Microsoft Graph-Bereiche im Manifest angibt.It requires that the add-in register in the Application Registration Portal and specify any required Microsoft Graph scopes in its manifest.

Mit dieser Methode kann Ihr Add-In ein Zugriffstoken abrufen, das auf Ihre Server-Back-End-API ausgelegt ist.Using this method, your add-in can obtain an access token scoped to your server back-end API. Das Add-In verwendet dieses als Bearertoken in der Authorization-Kopfzeile, um einen Aufruf wieder bei Ihrer API zu authentifizieren.The add-in uses this as a bearer token in the Authorization header to authenticate a call back to your API. An diesem Punkt kann Ihr Server Folgendes:At that point your server can:

  • Den Im-Auftrag-von-Ablauf abschließen, um ein Zugriffstoken zu erhalten, das auf die Microsoft Graph-API ausgelegt istComplete the On-Behalf-Of flow to obtain an access token scoped to the Microsoft Graph API
  • Die Identitätsinformationen im Token verwenden, um die Identität des Benutzers zu ermitteln und bei Ihren eigenen Back-End-Diensten zu authentifizierenUse the identity information in the token to establish the user's identity and authenticate to your own back-end services

Registrieren Ihres Add-InsRegistering your add-in

Um am Azure-OAuth-Fluss teilzunehmen, muss das Add-In im Anwendungsregistrierungsportal registriert sein.In order to participate in the Azure OAuth flows, the add-in must be registered in the Application Registration Portal. Das Add-In muss zumindest eine Web-API registrieren, damit das Add-In einen SSO-Token erhält.Minimally the add-in must register a Web API in order for the add-in to obtain an SSO token. Wenn das Add-In Zugriff auf die Microsoft Graph-API benötigt, muss das Add-In auch eine Web-App registrieren.If the add-in requires access to the Microsoft Graph API, then the add-in must also register a web app.

Der Registrierungsvorgang beginnt mit der Erstellung einer Anwendung im Portal.The registration process starts by creating an application in the portal. Dadurch wird eine Anwendungs-ID generiert.This generates an application ID. Nachdem die App erstellt wurde, werden Komponenten als Plattformen hinzugefügt.After the app is created, then components are added as platforms.

Registrieren einer Web-APIRegistering a Web API

Die Web-API-Komponente des Add-Ins ist der Endpunkt, der den SSO-Token erhält.The Web API component of the add-in is the endpoint that will receive the SSO token.

  1. Wählen Sie in den Details der Anwendung im Portal die Schaltfläche Plattform hinzufügen aus.In the details of the application in the portal, select the Add Platform button.
  2. Wählen Sie Web-API aus.Select Web API.
  3. Geben Sie die folgenden Details ein:Enter the following details:
    • Application-ID-URI: Verwenden Sie das Format api://{add-in server host}/{application id}Application ID URI: Use the format api://{add-in server host}/{application id}
    • Durch diese API definierte Bereiche: Standardwert beibehaltenScopes defined by this API: Leave default value
    • Vorautorisierte Anwendungen: Fügen Sie die Anwendungs-ID für Office hinzu: d3590ed6-52b3-4102-aeff-aad2292ab01c, mit dem Bereich api://{add-in server host}/{application id}/access_as_userPre-authorized applications: Add the application ID for Office: d3590ed6-52b3-4102-aeff-aad2292ab01c, with the scope api://{add-in server host}/{application id}/access_as_user

Bei einem Add-In, das beispielsweise bei https://addin.contoso.com mit der Anwendungs-ID 5661fed9-f33d-4e95-b6cf-624a34a2f51d gehostet wird, sieht der Abschnitt Web-API Teil der Anwendungsregistrierung in etwa folgendermaßen aus.For example, for an addin that is hosted at https://addin.contoso.com with an application ID of 5661fed9-f33d-4e95-b6cf-624a34a2f51d, the Web API section of the application registration looks like the following.

Ein Screenshot des Abschnitts „Web-API“ einer Anwendungsregistrierung für ein Add-In, das Single Sign-On verwendet

Registrieren einer Web-AppRegistering a Web app

Mithilfe der Web-App-Komponente des Add-Ins kann Ihr Server-Back-End den Im-Auftrag-von-Ablauf abschließen, um den ersten Token gegen einen Zugriffstoken auszutauschen, der Zugriff auf die Microsoft Graph-API erlaubt.The Web app component of the add-in allows your server back-end to complete the On-Behalf-Of flow to exchange the initial token for an access token that allows access to the Microsoft Graph API.

  1. Wählen Sie in den Details der Anwendung im Portal die Schaltfläche Plattform hinzufügen aus.In the details of the application in the portal, select the Add Platform button.
  2. Wählen Sie Web aus.Select Web.
  3. Geben Sie die folgenden Details ein:Enter the following details:
    • Umleitungs-URLs: Geben Sie die Basis-URL des Add-Ins ein.Redirect URLs: Enter the base URL of the add-in.

Bei dem oben beschriebenen Add-In beispielsweise, das bei https://addin.contoso.com gehostet wird, sieht der Abschnitt Web der Anwendungsregistrierung in etwa folgendermaßen aus.For example, for the add-in described above, hosted at https://addin.contoso.com, the Web section of the application registration looks like the following.

Ein Screenshot des Abschnitts „Web“ einer Anwendungsregistrierung für ein Add-In, das Single Sign-On verwendet

Generieren eines AnwendungskennwortsGenerate an application password

Um einen Microsoft Graph-Token anzufordern, muss die Web-App-Registrierung in den client_secret-Parameter der Tokenanforderung einen gemeinsamen geheimen Schlüssel einschließen.In order to request a Microsoft Graph token, the Web app registration needs a shared secret to include in the client_secret parameter of the token request.

  1. Wählen Sie die Schaltfläche Neues Kennwort generieren unter Anwendungsgeheimnisse.Choose the Generate New Password button under Application Secrets.
  2. Kopieren Sie das generierte Kennwort, wenn es angezeigt wird, und speichern Sie es an einem sicheren Ort.Copy the generated password when it is displayed and save it in a safe place.

Konfigurieren erforderlicher Microsoft Graph-BerechtigungenConfigure necessary Microsoft Graph permissions

Als letzter Schritt im Registrierungsvorgang werden die erforderlichen Berechtigungen für Microsoft Graph konfiguriert.The final step in the registration process is to configure the required permissions to the Microsoft Graph. Diese Berechtigungen sollten als delegierte Berechtigungen hinzugefügt werden, NICHT als Anwendungsberechtigungen.These permissions should be added as delegated permissions, NOT application permissions.

Beachten Sie die folgenden Richtlinien:Keep in mind the following guidelines:

  • Die Office-JS-API setzt voraus, dass Sie sowohl User.Read als auch profile zu den delegierten Berechtigungen hinzufügen.The Office JS API requires that you add both User.Read and profile to the delegated permissions.
  • Wenn Sie eine OAuth-Bibliothek zum Verarbeiten der Tokenanforderungen von Ihrem Back-End verwenden, fordert sie (zusätzlich zu denen, die Sie speziell anfordern) möglicherweise weitere Bereiche an, die auch hier aufgelistet werden sollten.If you are using an OAuth library to handle the token requests from your back-end, it may request additional scopes (in addition to the ones you specifically request) that you should also list here. So fügt z. B. die Microsoft Authentication Library immer openid und offline_access zu Tokenanforderungen hinzu.For example, the Microsoft Authentication Library always adds openid and offline_access to token requests.

Wenn Ihr Add-In z. B. Lesezugriff auf die OneDrive-Dateien des Benutzers erfordert, sieht der Abschnitt Microsoft Graph-Berechtigungen in etwa folgendermaßen aus.For example, if your add-in requires read access to the user's OneDrive files, the Microsoft Graph Permissions section looks like the following.

Ein Screenshot des Abschnitts „Microsoft Graph-Berechtigungen“ einer Anwendungsregistrierung für ein Add-In, das Single Sign-On verwendet

Wenn ein Add-In, das SSO verwendet, aus dem Office Store erworben wird, wird der Benutzer auf der Store-Benutzeroberfläche aufgefordert, den angeforderten Graph-Berechtigungen zuzustimmen.When an add-in that uses SSO is acquired from the Office Store, the store UI handles prompting the user for consent to the requested Graph permissions. Wird das Add-In allerdings zum Testen quergeladen, wird die Store-Benutzeroberfläche mit der Zustimmung umgangen.However, when sideloading the add-in for testing purposes, the store consent UI is bypassed. Damit das Add-In Token erhält, müssen Sie Ihre Zustimmung geben.In order for the add-in to obtain tokens, you need to provide consent.

Sie haben zwei Möglichkeiten, Ihre Zustimmung zu geben.You have two choices for providing consent. Sie können ein Administratorkonto verwenden und einmal für alle Benutzer in Ihrer Office 365-Organisation zustimmen, oder Sie können jedes beliebige Konto verwenden, um nur für diesen Benutzer zuzustimmen.You can use an administrator account and consent once for all users in your Office 365 organization, or you can use any account to consent for just that user.

Wenn Sie Zugriff auf ein Mandantenadministratorkonto haben, können Sie mit dieser Methode Ihre Zustimmung für alle Benutzer in Ihrer Organisation geben. Das kann praktisch sein, wenn Sie mehrere Entwickler haben, die Ihr Add-In entwickeln und testen müssen.If you have access to a tenant administrator account, this method will allow you to provide consent for all users in your organization, which can be convenient if you have multiple developers that need to develop and test your add-in.

  1. Navigieren Sie zu https://login.microsoftonline.com/common/adminconsent?client_id={application_ID}&state=12345, wobei {application_ID} die Anwendungs-ID ist, die in der Registrierung Ihrer App angezeigt wird.Browse to https://login.microsoftonline.com/common/adminconsent?client_id={application_ID}&state=12345, where {application_ID} is the application ID shown in your app registration.
  2. Melden Sie sich mit Ihrem Administratorkonto an.Sign in with your administrator account.
  3. Überprüfen Sie die Berechtigungen, und klicken Sie auf Annehmen.Review the permissions and click Accept.

Der Browser versucht, Sie wieder zu Ihrer App umzuleiten, die möglicherweise nicht ausgeführt wird.The browser will attempt to redirect back to your app, which may not be running. Nachdem Sie auf Annehmen geklickt haben, wird möglicherweise die Fehlermeldung angezeigt, dass diese Website nicht erreicht werden kann.You might see a "this site cannot be reached" error after clicking Accept. Das ist in Ordnung. Die Zustimmung wurde dennoch erfasst.This is OK, the consent was still recorded.

Wenn Sie keinen Zugriff auf ein Mandantenadministratorkonto haben oder Sie Ihre Zustimmung nur für ein paar Benutzer geben möchten, können Sie mithilfe dieser Methode Ihre Zustimmung für einen einzelnen Benutzer geben.If you don't have access to a tenant administrator account, or you just want to limit consent to a few users, this method will allow you to provide consent for a single user.

  1. Navigieren Sie zu https://login.microsoftonline.com/common/oauth2/authorize?client_id={application_ID}&state=12345&response_type=code, wobei {application_ID} die Anwendungs-ID ist, die in der Registrierung Ihrer App angezeigt wird.Browse to https://login.microsoftonline.com/common/oauth2/authorize?client_id={application_ID}&state=12345&response_type=code, where {application_ID} is the application ID shown in your app registration.
  2. Melden Sie sich mit Ihrem Konto an.Sign in with your account.
  3. Überprüfen Sie die Berechtigungen, und klicken Sie auf Annehmen.Review the permissions and click Accept.

Der Browser versucht, Sie wieder zu Ihrer App umzuleiten, die möglicherweise nicht ausgeführt wird.The browser will attempt to redirect back to your app, which may not be running. Nachdem Sie auf Annehmen geklickt haben, wird möglicherweise die Fehlermeldung angezeigt, dass diese Website nicht erreicht werden kann.You might see a "this site cannot be reached" error after clicking Accept. Das ist in Ordnung. Die Zustimmung wurde dennoch erfasst.This is OK, the consent was still recorded.

Aktualisieren des Add-In-ManifestsUpdating the add-in manifest

Der nächste Schritt zum Aktivieren von SSO im Add-In besteht darin, ein WebApplicationInfo-Element in das VersionOverridesV1_1 VersionOverrides-Element einzufügen.The next step to enable SSO in the add-in is to add a WebApplicationInfo element into the VersionOverridesV1_1 VersionOverrides element. Dieses Element enthält die folgenden untergeordneten Elemente:This element contains the following child elements:

  • Id: festgelegt auf die Anwendungs-ID, die Sie bei der Registrierung der App erhalten habenId - set to the application ID obtained during app registration
  • Resource: festgelegt auf den Anwendungs-ID-URI, der im Abschnitt Web-API der App-Registrierung konfiguriert wurdeResource - set to the Application ID URI configured in the Web API section of the app registration
  • Scopes: enthält ein Scope-Element für jeden Microsoft Graph-Bereich, der vom Add-In benötigt wirdScopes - contains a Scope element for each Microsoft Graph scope required by the add-in

Bei dem Add-In, das in den vorherigen Beispielen genannt wurde, sieht das WebApplicationInfo-Element beispielsweise folgendermaßen aus.For example, for the add-in mentioned in the prior examples, the WebApplicationInfo element looks like the following.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">

  ...

  <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>
    </Scopes>
  </WebApplicationInfo>
</VersionOverrides>

Abrufen des SSO-TokensGetting the SSO token

Das Add-In erhält ein Token für einmaliges Anmelden, indem es Office.context.auth.getAccessTokenAsync aufruft.The add-in obtains an SSO token by calling .

Office.context.auth.getAccessTokenAsync(function (result) {
    if (result.status === "succeeded") {
        // No need to prompt user, use this token to call Web API
        var ssoToken = result.value;
        ...
    } else {
        if (result.error.code === 13003) {
            // SSO is not supported for this user, fallback
            // on another authentication method
        } else {
            // Handle error
        }
    }
});

Das Add-In schließt den Token in die Authorization-Kopfzeile ein, wenn es eine Anforderung an die Web-API zurücksendet.The add-in includes the token in the Authorization header when sending a request back to the Web API.

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

Verwenden des SSO-Tokens im Back-EndUsing the SSO token at the back-end

Nachdem die Web-API den Zugriffstoken erhalten hat, muss sie ihn vor Verwendung überprüfen.Once the Web API receives the access token, it must 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: der Anmeldename des Benutzers.preferred_username - The user's login name.
  • oid: eine GUID, welche die ID des Benutzers im Azure Active Directory darstellt.oid - A GUID representing the ID of the user in the Azure Active Directory.
  • tid: eine GUID, welche die ID der Organisation des Benutzers im 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, wird empfohlen, 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, it's recommended 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.

Wichtig

Wenn Sie den SSO-Token als Identität verwenden, sollten Sie auch den Exchange-Identitätstoken als eine andere Identität verwenden.When using the SSO token as an identity, it is recommended that you also use the Exchange identity token as an alternate identity. Benutzer Ihres Add-Ins verwenden möglicherweise mehrere Clients, von denen einige möglicherweise keine SSO-Token unterstützen.Users of your add-in may use multiple clients, and some may not support providing an SSO token. Wenn Sie den Exchange-Identitätstoken als eine Alternative verwenden, müssen diese Benutzer nicht mehrmals zur Eingabe von Anmeldeinformationen aufgefordert werden.By using the Exchange identity token as an alternate, you can avoid having to prompt these users for credentials multiple times. Weitere Informationen finden Sie unter .For more details, see .

Abzurufen eines Microsoft Graph-Tokens mithilfe eines SSO-TokensUsing the SSO token to get a Microsoft Graph token

Um auf die Microsoft Graph-API zuzugreifen, sendet das Add-In an den Azure Active Directory v2.0-Token-Endpunkt mithilfe des Im-Auftrag-von-Ablaufs eine Dienst-zu-Dienst-Anforderung unter Verwendung eines gemeinsamen geheimen Schlüssels.In order to access the Microsoft Graph API, the add-in sends a service-to-service request using the On-Behalf-Of flow to the Azure Active Directory v2.0 token endpoint using a shared secret.

Die Antwort enthält eine JSON-Nutzlast, wobei der Microsoft Graph-Token in der access_token-Eigenschaft bereitgestellt wird.The response contains a JSON payload, with the Microsoft Graph token supplied in the access_token property. Dieser Token wird in der Authorization-Kopfzeile verwendet, wenn Aufrufe an die Microsoft Graph-API durchgeführt werden.That token is used in the Authorization header when making calls to the Microsoft Graph API.

RessourcenResources

Ein Beispiel-Add-In, das mit dem SSO-Token auf die Microsoft Graph-API zugreift, finden Sie unter AttachmentsDemo-Beispiel-Add-In.For a sample add-in that uses the SSO token to access the Microsoft Graph API, see AttachmentsDemo Sample Add-in.