Szenario: Implementieren von Single Sign-On bei Ihrem Dienst in einem Outlook-Add-In

Artikel
08/14/2023

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. 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.

Hinweis

Die Single Sign-On-API wird derzeit für Word, Excel, Outlook und PowerPoint unterstützt. Weitere Informationen dazu, wo die Single Sign-On-API derzeit unterstützt wird, finden Sie unter Identity-API-Anforderungssätze. 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.

Gründe für die Verwendung des SSO-Zugriffstokens

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. Der SSO-Token bietet jedoch einige Vorteile gegenüber dem Exchange-Identitätstoken, was diesen (sofern verfügbar) zur empfohlenen Methode macht.

Der SSO-Token verwendet ein OpenID-Standardformat und wird von Azure ausgestellt. Dies vereinfacht den Vorgang der Überprüfung dieser Token erheblich. Exchange-Identitätstoken verwenden dagegen ein benutzerdefiniertes Format, das auf dem JSON-Webtoken-Standard basiert, und erfordern benutzerdefinierte Schritte zur Überprüfung.
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.
Der SSO-Token bietet umfangreichere Identitätsinformationen, z. B. den Anzeigenamen des Benutzers.

Add-In-Szenario

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. 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. Wie die Microsoft Graph-API erfordert die Contoso-Daten-API OAuth-Authentifizierung. 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.

Dazu erstellt die Back-End-API eine sichere Datenbank von Benutzern. 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. Das folgende JSON-Markup steht für den Eintrag eines Benutzers in der Datenbank.

{
  "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.

Add-In-Start

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. In diesen Aufruf schließt das AddIn sowohl den SSO-Token (sofern verfügbar) als auch den Identitätstoken ein.
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.
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.
- Wenn kein Eintrag vorhanden war, fahren Sie mit dem nächsten Schritt fort.
- Wenn ein Eintrag vorhanden ist, fahren Sie mit Schritt 5 fort.
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.
- 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.
- Wenn ein Eintrag vorhanden ist und kein SSO-Token angegeben wurde, fahren Sie mit Schritt 5 fort.
- Wenn kein Eintrag vorhanden ist, erstellen Sie einen neuen Eintrag. 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.
Prüfen Sie den graphRefreshToken-Wert des Benutzers auf einen gültiges Aktualisierungstoken.
- 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. Speichern Sie den Aktualisierungstoken im graphRefreshToken-Wert für den Benutzer.
Prüfen Sie sowohl in graphRefreshToken als auch contosoRefreshToken auf gültige Aktualisierungstoken.
- Wenn beide Werte gültig sind, antworten Sie auf das Add-In, um anzugeben, dass der Benutzer bereits registriert und konfiguriert ist.
- 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.
Das Add-In überprüft die Antwort.
- Wenn der Benutzer bereits registriert und konfiguriert ist, wird das Add-In weiterhin normal ausgeführt.
- Wenn eine Benutzereinrichtung erforderlich ist, wechselt das Add-In in den Einrichtungsmodus und fordert den Benutzer auf, das Add-In zu autorisieren.

Autorisieren der Back-End-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.

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. Da beide APIs OAuth2-Authentifizierung verwenden, wird für beide eine ähnliche Methode verwendet.

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.
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.
Die Back-End-Web-API sucht den Benutzer in der Datenbank und aktualisiert den entsprechenden Aktualisierungstoken.
Das Add-In wird weiterhin normal ausgeführt.

Normaler Betrieb

Immer wenn das Add-In die Back-End-Web-API aufruft, schließt es entweder den SSO-Token oder den Exchange-Identitätstoken ein. 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. Solange die Aktualisierungstoken gültig sind, muss sich der Benutzer nicht erneut anmelden.