Szenario: Implementieren von Single Sign-On bei Ihrem Dienst in einem Outlook-Add-InScenario: Implement single sign-on to your service in an Outlook Add-in

In diesem Artikel wird eine empfohlene Methode zur gemeinsamen Verwendung des Single Sign-On-Zugriffstokens und des Exchange-Identitätstokens beschrieben, um für Ihren eigenen Back-End-Dienst eine Single Sign-On-Implementierung bereitzustellen.In this article we'll explore a recommended method of using the single sign-on access token and the Exchange identity token together to provide a single-sign on implementation to your own backend service. Durch die gemeinsame Verwendung beider Token können Sie von den Vorteilen des SSO-Zugriffstokens profitieren, wenn er verfügbar ist, und dabei sicherstellen, dass das Add-In funktioniert, wenn der Token nicht verfügbar ist, z. B. wenn der Benutzer zu einem Client wechselt, von dem es nicht unterstützt werden, oder wenn sich das Postfach des Benutzers auf einem lokalen Exchange-Server befindet.By using both tokens together, you can take advantage of the benefits of the SSO access token when it is available, while ensuring that your add-in will work when it is not, such as when the user switches to a client that does not support them, or if the user's mailbox is on an on-premises Exchange server.

Gründe für die Verwendung des SSO-ZugriffstokensWhy use the SSO access token?

Der Exchange-Identitätstoken steht in allen Anforderungssätzen der Add-In-APIs zur Verfügung, sodass es verlockend sein kann, nur diesen Token zu verwenden und den SSO-Token vollständig zu ignorieren.The Exchange identity token is available in all requirement sets of the add-in APIs, so it may be tempting to just rely on this token and ignore the SSO token altogether. Der SSO-Token bietet jedoch einige Vorteile gegenüber dem Exchange-Identitätstoken, was diesen (sofern verfügbar) zur empfohlenen Methode macht.However, the SSO token offers some advantages over the Exchange identity token which make it the recommended method to use when it is available.

  • Der SSO-Token verwendet ein OpenID-Standardformat und wird von Azure ausgestellt.The SSO token uses a standard OpenID format and is issued by Azure. Dies vereinfacht den Vorgang der Überprüfung dieser Token erheblich.This greatly simplifies the process of validating these tokens. Exchange-Identitätstoken verwenden dagegen ein benutzerdefiniertes Format, das auf dem JSON-Webtoken-Standard basiert, und erfordern benutzerdefinierte Schritte zur Überprüfung.In comparison, Exchange identity tokens use a custom format based on the JSON Web Token standard, requiring custom work to validate the token.
  • Der SSO-Token kann von Ihrem Back-End zum Abruf eines Zugriffstokens für Microsoft Graph verwendet werden, ohne dass der Benutzer zusätzliche Anmeldeschritte durchführen muss.The SSO token can be used by your backend to retrieve an access token for Microsoft Graph without the user having to do any additional sign in action.
  • Der SSO-Token bietet umfangreichere Identitätsinformationen, z. B. den Anzeigenamen des Benutzers.The SSO token provides richer identity information, such as the user's display name.

Add-In-SzenarioAdd-in scenario

In diesem Beispiel verwenden wir ein Add-In, das sowohl aus der Add-In-Benutzeroberfläche und Skripts (HTML + JavaScript) als auch aus einer Back-End-Web-API besteht, die vom Add-In aufgerufen wird.For the purposes of this example, consider an add-in that consists of both the add-in UI and scripts (HTML + JavaScript) and a backend Web API that is called by the add-in. Die Back-End-Web-API ruft sowohl die Microsoft Graph-API als auch die Contoso-Daten-API auf, eine fiktive API, die von einem Drittanbieter erstellt wurde.The backend Web API makes calls both to the Microsoft Graph API and the Contoso Data API, a fictional API created by a third party. Wie die Microsoft Graph-API erfordert die Contoso-Daten-API OAuth-Authentifizierung.Like the Microsoft Graph API, the Contoso Data API requires OAuth authentication. Es besteht die Anforderung, dass die Back-End-Web-API beide APIs aufrufen können soll, ohne dass der Benutzer jedes Mal zur Eingabe seiner Anmeldeinformationen aufgefordert wird, wenn ein Zugriffstoken abgelaufen ist.The requirement is that the backend Web API should be able to call both APIs without having to prompt the user for their credentials every time an access token expires.

Dazu erstellt die Back-End-API eine sichere Datenbank von Benutzern.To do this, the backend API creates a secure database of users. Jeder Benutzer erhält einen Eintrag in der Datenbank,wobei das Back-End sowohl für die Microsoft Graph-API als auch für die Contoso-Daten-API langlebige Aktualisierungstoken speichern kann.Each user will get an entry in the database where the backend can store long-lived refresh tokens for both the Microsoft Graph API and the Contoso Data API. Das folgende JSON-Markup steht für den Eintrag eines Benutzers in der Datenbank.The following JSON markup represents a user's entry in the database.

{
  "userDisplayName": "...",
  "ssoId": "...",
  "exchangeId": "...",
  "graphRefreshToken": "...",
  "contosoRefreshToken": "..."
}

Das Add-In fügt bei jedem Aufruf, der an die Back-End-Web-API vorgenommen wird, entweder den SSO-Zugriffstoken (falls dieser verfügbar ist) oder den Exchange-Identitätstoken (wenn der SSO-Token nicht verfügbar ist) hinzu.The add-in includes either the SSO access token (if it is available) or the Exchange identity token (if the SSO token is not available) with every call it makes to the backend Web API.

Add-In-StartAdd-in startup

  1. Wenn das Add-In gestartet wird, sendet es eine Anforderung an die Back-End-Web-API, um zu ermitteln, ob der Benutzer registriert ist (d. h. ob ein entsprechender Eintrag in der Benutzerdatenbank vorhanden ist) und dass die API Aktualisierungstoken sowohl für Contoso als auch für Graph aufweist.When the add-in starts, it sends a request to the backend Web API to determine if the user is registered (i.e. has an associated record in the user database) and that the API has refresh tokens for both Graph and Contoso. In diesen Aufruf schließt das Add-In sowohl den SSO-Token (sofern verfügbar) als auch den Identitätstoken ein.In this call, the add-in includes both the SSO token (if available) and the identity token.

  2. Die Web-API verwendet die Methoden in Authentifizieren eines Benutzers mit einem Single Sign-On-Token in einem Outlook-Add-In und Authentifizieren eines Benutzers mit einem Identitätstoken für Exchange, um einen eindeutigen Bezeichner aus beiden Token zu generieren.The Web API uses the methods in Authenticate a user with an single-sign-on token in an Outlook Add-in and Authenticate a user with an identity token for Exchange to validate and generate a unique identifier from both tokens.

  3. Wenn ein SSO-Token bereitgestellt wurde, fragt die Web-API dann die Benutzerdatenbank nach einem Eintrag ab, der einen ssoId-Wert aufweist, der dem eindeutigen Bezeichner entspricht, der aus dem SSO-Token generiert wurde.If an SSO token was provided, the Web API then queries the user database for an entry that has an ssoId value that matches the unique identifier generated from the SSO token.

    • Wenn kein Eintrag vorhanden war, fahren Sie mit dem nächsten Schritt fort.If an entry did not exist, continue to the next step.
    • Wenn ein Eintrag vorhanden ist, fahren Sie mit Schritt 5 fort.If an entry exists, proceed to step 5.
  4. Die Web-API fragt die Datenbank nach einem Eintrag ab, der einen exchangeId-Wert aufweist, der dem eindeutigen Bezeichner entspricht, der aus dem Exchange-Identitätstoken generiert wurde.The Web API queries the database for an entry that has an exchangeId value that matches the unique identifier generated from the Exchange identity token.

    • Wenn ein Eintrag vorhanden ist und ein SSO-Token angegeben wurde, aktualisieren Sie den Datensatz des Benutzers in der Datenbank, und legen Sie dabei den ssoId-Wert auf den eindeutigen Bezeichner fest, der aus dem SSO-Token generiert wurde. Fahren Sie dann mit Schritt 5 fort.If an entry exists and an SSO token was provided, update the user's record in the database to set the ssoId value to the unique identifier generated from the SSO token and proceed to step 5.
    • Wenn ein Eintrag vorhanden ist und kein SSO-Token angegeben wurde, fahren Sie mit Schritt 5 fort.If an entry exists and no SSO token was provided, proceed to step 5.
    • Wenn kein Eintrag vorhanden ist, erstellen Sie einen neuen Eintrag.If no entry exists, create a new entry. Legen Sie ssoId auf den eindeutigen Bezeichner fest, der aus dem SSO-Token generiert wurde (sofern vorhanden), und legen Sie exchangeId auf den eindeutigen Bezeichner fest, der aus dem Exchange-Identitätstoken generiert wurde.Set ssoId to the unique identifier generated from the SSO token (if available), and set exchangeId to the unique identifier generated from the Exchange identity token.
  5. Prüfen Sie den graphRefreshToken-Wert des Benutzers auf einen gültiges Aktualisierungstoken.Check for a valid refresh token in the user's graphRefreshToken value.

    • Wenn der Wert fehlt oder ungültig ist und ein SSO-Token angegeben wurde, verwenden Sie den OAuth2-Im-Auftrag-von-Ablauf, um einen Zugriffstoken und Aktualisierungstoken für Graph zu erhalten.If the value is missing or invalid and an SSO token was provided, use the OAuth2 On-Behalf-Of flow to obtain an access token and refresh token for Graph. Speichern Sie den Aktualisierungstoken im graphRefreshToken-Wert für den Benutzer.Save the refresh token in the graphRefreshToken value for the user.
  6. Prüfen Sie sowohl in graphRefreshToken als auch contosoRefreshToken auf gültige Aktualisierungstoken.Check for valid refresh tokens in both graphRefreshToken and contosoRefreshToken.

    • Wenn beide Werte gültig sind, antworten Sie auf das Add-In, um anzugeben, dass der Benutzer bereits registriert und konfiguriert ist.If both values are valid, respond to the add-in to indicate that the user is already registered and configured.
    • Wenn ein Wert ungültig ist, antworten Sie auf das Add-In, um anzugeben, dass eine Benutzereinrichtung erforderlich ist, und geben Sie an, welche Dienste (Graph oder Contoso) konfiguriert werden müssen.If either value is invalid, respond to the add-in to indicate that user setup is required, along with which services (Graph or Contoso) need to be configured.
  7. Das Add-In überprüft die Antwort.The add-in checks the response.

    • Wenn der Benutzer bereits registriert und konfiguriert ist, wird das Add-In weiterhin normal ausgeführt.If the user is already registered and configured, the add-in continues with normal operation.
    • Wenn eine Benutzereinrichtung erforderlich ist, wechselt das Add-In in den Einrichtungsmodus und fordert den Benutzer auf, das Add-In zu autorisieren.If user setup is required, the add-in enters "setup" mode and prompts the user to authorize the add-in.

Autorisieren der Back-End-Web-APIAuthorize the backend Web API

Das Verfahren zum Autorisieren der Back-End-Web-API zum Aufrufen der Microsoft Graph-API und Contoso-Daten-API sollte im Idealfall nur einmal ausgeführt werden müssen, damit der Benutzer nicht mehrmals zur Anmeldung aufgefordert wird.The procedure for authorizing the backend Web API to call the Microsoft Graph API and Contoso Data API should ideally only have to happen once, to minimize having to prompt the user for sign-in.

Je nach der Antwort von der Back-End-Web-API muss das Add-In möglicherweise den Benutzer für die Microsoft Graph-API, die Contoso-Daten-API oder beide autorisieren.Based on the response from the backend Web API, the add-in may need to authorize the user for the Microsoft Graph API, the Contoso Data API, or both. Da beide APIs OAuth2-Authentifizierung verwenden, wird für beide eine ähnliche Methode verwendet.Since both APIs use OAuth2 authentication, the method is similar for both.

  1. Das Add-In benachrichtigt den Benutzer, dass er die Verwendung der API autorisieren muss, und fordert ihn auf, auf einen Link oder eine Schaltfläche zu klicken, um den Vorgang zu starten.The add-in notifies the user that it needs them to authorize their use of the API and asks them to click a link or button to start the process.

  2. Das Add-in verwendet die Dialog-API oder die Office-Js-Hilfsprogramme-Bibliothek zum Starten des OAuth2-Autorisierungscodeflusses für die API.The add-in uses the Dialog API or the office-js-helpers library to start the OAuth2 Authorization Code flow for the API.

  3. Nach Abschluss des Ablaufs sendet das Add-In den Aktualisierungstoken an die Back-End-Web-API und schließt den SSO-Token (sofern verfügbar) oder den Exchange-Identitätstoken ein.Once the flow completes, the add-in sends the refresh token to the backend Web API and includes the SSO token (if available) or the Exchange identity token.

  4. Die Back-End-Web-API sucht den Benutzer in der Datenbank und aktualisiert den entsprechenden Aktualisierungstoken.The backend Web API locates the user in the database and updates the appropriate refresh token.

  5. Das Add-In wird weiterhin normal ausgeführt.The add-in continues with normal operation.

Normaler BetriebNormal operation

Immer wenn das Add-In die Back-End-Web-API aufruft, schließt es entweder den SSO-Token oder den Exchange-Identitätstoken ein.Whenever the add-in calls the backend Web API, it includes either the SSO token or the Exchange identity token. Die Back-End-Web-API sucht den Benutzer anhand dieses Tokens und verwendet dann die gespeicherten Aktualisierungstoken zum Abrufen von Zugriffstoken für die Microsoft Graph-API und die Contoso-Daten-API.The backend Web API locates the user by this token, then uses the stored refresh tokens to obtain access tokens for the Microsoft Graph API and the Contoso Data API. Solange die Aktualisierungstoken gültig sind, muss sich der Benutzer nicht erneut anmelden.As long as the refresh tokens are valid, the user will not have to sign in again.