Kontext-Token-OAuth-Ablauf für SharePoint-Add-Ins

  • Artikel

In SharePoint umfasst der OAuth-Authentifizierungs- und Autorisierungsablauf für ein von einem Anbieter gehosteten Add-In mit niedriger Vertrauensebene eine Reihe von Interaktionen zwischen dem Add-In, SharePoint, dem Autorisierungsserver und dem Browser zur Laufzeit. Der Autorisierungsserver ist in diesem Szenario ist Microsoft Azure Access Control Service (ACS).

Wichtig

Azure ACS (Access Control), ein Dienst von Azure Active Directory (Azure AD), wird am 7. November 2018 eingestellt. Diese Deaktivierung hat keinen Einfluss auf das SharePoint-Add-In-Modell, das den Hostnamen https://accounts.accesscontrol.windows.net verwendet, der von der Deaktivierung nicht betroffen ist. Weitere Informationen finden Sie unter Auswirkungen der Deaktivierung von Azure Access Control für SharePoint-Add-Ins.

Mit einem vom Anbieter gehosteten Add-In besitzen Sie eine Remote-Webanwendung oder einen -Webdienst, die bzw. der von SharePoint getrennt und nicht Teil der SharePoint-Farm oder des SharePoint Online-Mandanten ist. Das Hosting kann in der Cloud oder auf einem lokalen Server erfolgen. In diesem Artikel wird die Remotekomponente Contoso.com genannt.

Hinweis

Die Remotekomponente kann zudem Ereignisempfänger hosten, die auf Ereignisse reagieren können, die in SharePoint-Elementen, wie z. B. Listen oder Listenelementen, stattfinden. Beispiele für Remote-Ereignisse, auf die Contoso.com möglicherweise antwortet, sind Listenereignisse, wie z. B. das Hinzufügen oder Entfernen eines Listenelements, oder Webereignisse, wie z. B. das Hinzufügen oder Löschen einer Website. Weitere Informationen zum Erstellen von Remote-Ereignisempfängern finden Sie unter Erstellen eines Remote-Ereignisempfängers in SharePoint-Add-Ins.

Contoso.com verwendet das SharePoint-Clientobjektmodell (CSOM) oder die SharePoint-REST-APIs für Aufrufe an SharePoint. Die Anwendung Contoso.com verwendet einen OAuth-Tokenübergabe-Ablauf für die Authentifizierung mit SharePoint. SharePoint und Contoso.com vertrauen einander nicht, aber beide vertrauen ACS und akzeptieren von ACS ausgegebene Token.

Es sind drei Token beteiligt: SharePoint sorgt dafür, dass ACS ein Kontexttoken erstellt, das SharePoint an Constoso.com weiterleitet. Contoso.com überprüft, ob das Kontexttoken von ACS ausgestellt wurde, damit es ihm vertrauen kann. Contoso.com extrahiert dann ein Aktualisierungstoken aus dem Kontexttoken und verwendet es, um direkt von ACS ein Zugriffstoken zu erhalten. Das Zugriffstoken wird in alle Anfragen an SharePoint eingefügt. SharePoint überprüft, ob das Zugriffstoken von ACS ausgestellt wurde, und reagiert somit auf die Anfrage von Contoso.com.

Sie stellen den Code für die Tokenverarbeitung in der Remotekomponente bereit (wenn Ihre Remotekomponente allerdings auf .NET gehostet wird, stellen die Microsoft Office Developer Tools für Visual Studio Beispielcode bereit, der den größten Teil der Arbeit für Sie übernimmt). Ausführliche Informationen zum Code für die Tokenverarbeitung finden Sie unter Handhabung von Sicherheitstoken in vom Anbieter gehosteten Add-Ins mit niedriger Vertrauensebene für SharePoint.

Voraussetzungen

Die folgenden vorbereitenden Schritte müssen abgeschlossen werden, bevor ein SharePoint-Add-In den Kontexttokenablauf verwenden kann:

  • Die folgenden Anforderungen gelten nur, wenn Sie das SharePoint-Add-In zusätzlich zu SharePoint Online lokal installieren. Diese Anforderungen gelten nicht, wenn Sie nur das SharePoint-Add-In für SharePoint Online installieren

  • Unabhängig davon, ob das Add-In auf SharePoint Online oder einer lokalen SharePoint-Farm installiert wird, muss die SharePoint-Add-In über ACS registriert werden. Informationen dazu finden Sie unter Registrieren von SharePoint-Add-Ins. Unter anderem stellt das Add-In ACS bei der Registrierung die Client-ID und den geheimen Clientschlüssel bereit.

Schritte des Kontexttokenablaufs

Der OAuth-Authentifizierungs- und -Autorisierungsablauf für vom Anbieter gehostete SharePoint-Add-Ins ist in der folgenden Abbildung dargestellt.

OAuth des Kontexttokenablaufs

Autorisierungsprozessablauf von OAuth

Die folgenden Schritte entsprechen den Nummern in der Abbildung:

  1. Ein Benutzer startet die SharePoint-Add-In von SharePoint. Die genaue Vorgehensweise wird vom Design des Add-Ins bestimmt:

    • Wenn das Add-In darauf ausgelegt ist, die Remote-Webanwendung (bei Contoso.com) in einem Add-In-Webpart bereitzustellen (wobei es sich im Wesentlichen um einen Wrapper um ein iFRAME handelt), starten Sie das Add-In einfach, indem Sie zu einer SharePoint-Seite navigieren, die das Add-In-Webpart enthält. (Wenn der Benutzer noch nicht angemeldet ist, fordert SharePoint den Benutzer auf, sich anzumelden.) SharePoint verarbeitet die Seite und erkennt, dass eine Komponente aus der Anwendung Contoso.com auf der Seite vorhanden ist. (Weitere Informationen über Add-In-Webparts finden Sie unter Erstellen von Add-In-Webparts zur Installation mit Ihrem SharePoint-Add-In.)
    • Wenn das Add-In für die Verwendung als komplette Seite im Browser vorgesehen ist, startet der Benutzer es durch Auswählen der Add-In-Kachel auf der Seite Websiteinhalte der SharePoint-Website. (Das Add-In kann auch ein benutzerdefiniertes Menü oder Menüband-Element enthalten, über das die Remotekomponente gestartet wird.)

  2. Unabhängig davon, wie das Add-In gestartet wird, muss SharePoint ein Kontexttoken abrufen, das an die Contoso.com-Anwendung gesendet werden kann. Deshalb fordert SharePoint ACS auf, ein Kontexttoken zu erstellen, das die Informationen zum SharePoint-Kontext enthält, einschließlich des aktuellen Benutzers, der URL der Remoteanwendung und anderer Informationen. Das Kontexttoken enthält auch ein verschlüsseltes Aktualisierungstoken.

  3. ACS signiert das Kontexttoken durch die Verwendung eines Algorithmus, der den geheimen Contoso.com-Add-In-Schlüssel verwendet, und gibt es an SharePoint zurück. Nur ACS und das Contoso.com-Add-In kennen den geheimen Schlüssel.

  4. Wenn die Anwendung Contoso.com in einem Webpart-Add-In bereitgestellt wird, rendert SharePoint die Seite, die das Add-In-Webpart enthält, und fügt das Kontexttoken zur der URL hinzu, das das iFRAME im Add-In-Webpart aufruft, um die Inhalte zu erhalten. Wenn die Anwendung Contoso.com eine ganze Seite ist, leitet SharePoint den Browser auf Contoso.com um und integriert das Kontexttoken als Teil der Umleitungsantwort.

  5. Das Kontexttoken ist in der Browseranforderung enthalten, die an den Server Contoso.com gesendet wird.

  6. Der Server Contoso.com erhält das Kontexttoken und überprüft die Signatur, was möglich ist, da der Server den geheimen Clientschlüssel kennt. Dadurch erhält Contoso.com die Sicherheit, dass das Token von ACS und keinem Betrüger, der nur vorgibt, SharePoint zu sein, ausgestellt wurde. Contoso.com extrahiert das Aktualisierungstoken aus dem Kontexttoken und sendet es zusammen mit anderen Informationen, einschließlich der Client-ID und dem geheimen Clientschlüssel, in einer Anforderung für ein Zugriffstoken für den Zugriff auf SharePoint an ACS.

  7. ACS überprüft das Aktualisierungstoken, um sicherzustellen, dass es das Token ausgestellt hat, und gibt dann ein Zugriffstoken an Contoso.com zurück. Optional kann Contoso.com dieses Zugriffstoken zwischenspeichern, damit es ACS nicht bei jedem Zugriff auf SharePoint um ein Zugriffstoken bitten muss. Standardmäßig sind Zugriffstoken einige Stunden gültig. (Als dieser Artikel erfasst wurde, betrug die standardmäßige Ablaufzeit für von ACS bereitgestellte Zugriffstoken an SharePoint 12 Stunden, aber dies kann sich ändern.)

Jedes Zugriffstoken gilt nur für das Benutzerkonto, das in der ursprünglichen Anforderung für die Autorisierung angegeben ist, und gewährt nur auf den Dienst Zugriff (in diesem Fall SharePoint), der in dieser Anforderung festgelegt wurde. Aktualisierungstoken sind länger gültig (sechs Monate zum Zeitpunkt der Erfassung dieses Artikels) und können auch zwischengespeichert werden. Daher kann das gleiche Aktualisierungstoken gegen ein neues Zugriffstoken von ACS eingetauscht werden, bis das Aktualisierungstoken selbst abläuft. (Ausführliche Informationen zum Zwischenspeichern von Token finden Sie unter Handhabung von Sicherheitstoken in vom Anbieter gehosteten Add-Ins für SharePoint mit niedriger Vertrauensebene.)

Wenn das Aktualisierungstoken abläuft, kann Contoso.com durch Abrufen eines neuen Kontexttokens ein neues Aktualisierungstoken erhalten. Weitere Informationen finden Sie unter Abrufen eines neuen Kontexttokens.

  1. Contoso.com verwendet das Zugriffstoken, um einen SharePoint-REST-API-Aufruf oder eine CSOM-Anforderung an spnv zu richten. Dies geschieht durch die Übergabe des OAuth-Zugriffstokens in der Kopfzeile der HTTP-Autorisierung. (Beispielcode für die Erstellung der Kopfzeile wird in den Office Developer Tools für Visual Studio bereitgestellt, wenn die Remotekomponente auf der .NET-Plattform gehostet wird.)
  2. SharePoint überprüft das Zugriffstoken, sodass sichergestellt ist, dass das Token von ACS ausgestellt wurde. Dann werden die von Contoso.com angeforderten Daten an Contoso.com gesendet oder der von Contoso.com angeforderte CRUD-Vorgang (Erstellen, Lesen, Aktualisieren oder Löschen) durchgeführt.
  3. Die Contoso.com-Anwendungsseite wird im Browser (oder im IFRAME des Add-In-Webparts) wiedergegeben.

Siehe auch