Behandeln von Sicherheitstoken in vom Anbieter gehosteten wenig vertrauenswürdigen SharePoint-Add-Ins

Wichtig

In diesem Artikel geht es um die Verwendung von Sicherheitstoken im Autorisierungssystem mit niedriger Vertrauensebene, nicht um das besonders vertrauenswürdige System. Informationen zur Verwendung von Token im besonders vertrauenswürdigen System finden Sie unter Erstellen und Verwenden von Zugriffs-Tokens in vom Anbieter gehosteten SharePoint-Add-Ins mit hoher Vertrauenswürdigkeit.

SharePoint-Add-Ins, die das Autorisierungssystem mit niedriger Vertrauensebene verwenden, um Zugriff auf SharePoint-Daten zu erhalten, nehmen an einem OAuth-Ablauf teil, der die Übergabe von Sicherheitstoken (im JSON Web Token-Format) zwischen SharePoint, Microsoft Azure Access Control Service (ACS), den Remotekomponenten des SharePoint-Add-Ins und, in einigen Fällen, dem Browser des Benutzers umfasst.

Wichtig

Azure Access Control (ACS), 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.

Je nach Design des Add-Ins gibt es verschiedene Abläufe, aber alle umfassen mindestens die folgenden beiden Tokentypen:

• Zugriffstoken. Enthalten in jeder CRUD-Anforderung (Erstellen, Lesen, Aktualisieren oder Löschen) von den Remotekomponenten des Add-Ins an SharePoint. SharePoint überprüft das Token und verarbeitet die Anforderung.
• Aktualisierungstoken. Verwendet zum Abrufen des ersten Zugriffstokens im Kontexttokenablauf und zum Ersetzen ablaufender Zugriffstoken sowohl im Kontexttoken- als auch im Autorisierungscodeablauf des Autorisierungssystems mit niedriger Vertrauensebene.

Je nachdem, welchen OAuth-Ablauf das Add-In verwendet, ist eine der folgenden beiden Optionen Teil des Prozesses:

• Kontexttoken. Im Kontexttokenablauf verwendet, um der Remotekomponente ein Aktualisierungstoken und Informationen bereitzustellen, die sie benötigt, um ein Zugriffstoken von Azure ACS anzufordern.
• Autorisierungscode. Kein Token, sondern ein Autorisierungscode, der für jede Kombination von Benutzer und Anwendung eindeutig ist. Er wird im Autorisierungscodefluss verwendet, um ein erstes Zugriffstoken und ein Aktualisierungstoken abzurufen.

Zugriffstoken

Im Autorisierungssystem mit niedriger Vertrauensebene werden die Zugriffstoken von Azure ACS erstellt und an die Remotekomponente Ihrer SharePoint-Add-In gesendet. (Zum Zeitpunkt, an dem dieser Artikel geschrieben wurde, hatten von ACS ausgestellte Zugriffstoken für SharePoint eine Lebensspanne von 12 Stunden, das kann sich aber geändert haben.) Die wichtigsten Dinge, die der Code in Ihrer SharePoint-Add-In implementieren muss, sind die folgenden:

• Anfordern eines Zugriffstokens von Azure ACS. Je nachdem, welcher OAuth-Ablauf verwendet wird, nutzt das Add-In entweder einen Autorisierungscode oder Informationen, die es aus einem Kontexttoken extrahiert, um die Anforderung zu erstellen.
• Einschließen des Tokens in jede HTTP-Anforderung an SharePoint. Das Token wird der Anforderung als Authorization-Header hinzugefügt. Der Wert des Headers ist das Wort "Bearer", gefolgt von einem Leerzeichen, gefolgt von dem Base64-codierten Zugriffstoken.
• Optional (aber empfohlen) können Sie das Zugriffstoken zwischenspeichern, damit es in nachfolgenden Anforderungen erneut verwendet werden kann.
• Optional können Sie das Zugriffstoken an Back-End-Systeme weiterleiten, damit diese direkt auf SharePoint zugreifen können.

Diese Aufgaben müssen mit serverseitigem Code ausgeführt werden. Falls Sie verwalteten Code verwenden möchten, finden Sie Beispielcode für einige dieser Aufgaben in den Dateien SharePointContext.cs (oder .vb) und TokenHelper.cs (oder .vb), die Teil der Microsoft Office Developer Tools für Visual Studio sind. Ein Beispiel für PHP-Code, der einige dieser Aufgaben ausführt, finden Sie unter MSDN: SharePoint 2013 – Erläuterungen zur REST-Schnittstelle von SharePoint und zu ihrer Verwendung.

Zwischenspeichern des Zugriffstokens

Je nach der Architektur Ihres SharePoint-Add-Ins und der Hostingplattform gibt es verschiedene Wege zum Zwischenspeichern des Zugriffstokens auf dem Server:

• Im Sitzungszustand
• Im Anwendungszustand
• Im Windows Server AppFabric-Cache oder seiner Entsprechung in einem anderen Betriebssystem als von Microsoft.
• Im Microsoft Azure Caching Service oder seiner Entsprechung in einem anderen Betriebssystem als von Microsoft.
• In einer Datenbank
• In einem memcached-System

Hinweis

In den meisten Szenarien können Sie nicht so einfache Begriffe wie "Zugriffstoken" als Cacheschlüssel verwenden, weil Ihr Add-In die Token für verschiedene Benutzer und SharePoint-Farmen/-Mandanten voneinander unterscheiden können muss. Wenn Ihr Add-In den Kontexttokenablauf verwendet, wird ein spezieller CacheKey von SharePoint bereitgestellt, der verwendet werden kann, um zwischengespeicherte Token zu unterscheiden. In diesem Abschnitt wird erklärt, worin die Probleme liegen und was Sie tun können, wenn Ihre Anwendung nicht den Kontexttokenablauf verwendet.

Das Zwischenspeichern des Zugriffstokens im Sitzungszustand ist für die meisten Szenarien geeignet. Wenn die Remotewebanwendung auf andere Dienste zugreift, die OAuth (zusätzlich zu SharePoint) verwenden, und sie die verschiedenen Zugriffstoken im Sitzungsstatus zwischenspeichert, müssen Sie sicherstellen, dass Sie eindeutige Cacheschlüssel für die Token verwenden. Verwenden Sie beispielsweise anstelle von "AccessToken", "SharePoint_AccessToken", "Facebook_AccessToken", "SAP_Gateway_AccessToken", und so weiter. (Wenn Sie nicht den Sitzungsstatus oder eine andere Methode zum Zwischenspeichern verwenden, die den jeweiligen Cache aller Benutzer automatisch trennt, müssten Sie Ihre Schlüssel für Benutzer relativieren.)

Wenn die Anwendung auf mehrere SharePoint-Farmen oder -Onlinemandanten zugreift, können Sie die SharePoint-Domäne als Teil des primären Cacheschlüssels der Anwendung verwenden (SharePoint<mydomain>.sharepoint.com_AccessToken) oder den Bereich der Farm/des Mandanten benutzen (SharePoint<realmGUID>_AccessToken), die beide vom Zugriffstoken gelesen werden können. (Ihr Code muss die Base64-Codierung des Tokens umkehren, um es lesen zu können. In verwaltetem Code enthält die Datei TokenHelper.cs, oder .vb, Beispielcode für diesen Zweck, der Klassen aus den Namespaces Microsoft.IdentityModel.S2S.Tokens und System.IdentityModel.Tokens verwendet.) Eine weitere Option steht zur Verfügung, wenn die Anwendung den Kontexttokenablauf wie im folgenden Absatz beschrieben verwendet.

In manchen Szenarien muss Ihre Anwendung möglicherweise das Zugriffstoken an einem Ort zwischenspeichern, der für die Anwendung über Sitzungen hinweg oder nach dem Ende einer Sitzung verfügbar ist. Die Anwendung kann beispielsweise so entworfen sein, dass Benutzer Aktionen planen können, die erst nach dem Schließen der Anwendung ausgeführt werden. Wenn diese Aktionen den Zugriff auf SharePoint enthalten, muss das Add-In das Zugriffstoken abrufen. In einem solchen Szenario muss die Anwendung die Zugriffstoken verschiedener Benutzer unterscheiden können.

Wenn Sie den Kontexttokenablauf verwenden, wird für diesen Zweck eine Cacheschlüsselzeichenfolge im Kontexttoken bereitgestellt, das SharePoint an die Remotekomponente Ihres SharePoint-Add-Ins übergibt, wenn das Add-In gestartet wird. Weitere Informationen zu diesem speziellen Cacheschlüssel und seiner Verwendung finden Sie unter Grundlegendes zum Cacheschlüssel. Sie können diese Zeichenfolge auch für das zuvor beschriebene Szenario verwenden. Das Planungssystem verfügt über eine Möglichkeit, die erforderlichen Konfigurationsdaten zu speichern, beispielsweise dazu, wann die geplante Aktion ausgeführt wird und was sie bewirken soll. Verwenden Sie diesen Speicher, um den Cacheschlüssel für das Zugriffstoken abzulegen.

Wenn der von Ihnen verwendete sitzungsübergreifende Cache auch von mehreren Anwendungen gemeinsam verwendet wird, müssen die Cacheschlüssel für Anwendungen sowie für Benutzer und SharePoint-Bereiche relativiert werden. Der Cacheschlüssel, der im Kontexttoken bereitgestellt wird, ist für Anwendungen sowie für Benutzer und SharePoint-Bereiche eindeutig.

Wenn Ihre Anwendung den Autorisierungscodeablauf verwendet, gibt es kein Kontexttoken und somit keinen speziell erstellten Cacheschlüssel. In diesem Fall müssen Sie ein eigenes System von Schlüsseln für zwischengespeicherte Daten erstellen, die je nach potenziellen Namenskonflikten in den vorgesehenen Anwendungsfällen Ihrer Anwendung für eins oder mehrere der folgenden Elemente relativiert werden: den Benutzer, den SharePoint-Bereich und die Anwendung. Sie können für diesen Zweck die Ansprüche im Zugriffstoken verwenden, zum Beispiel nameId und aud (siehe Tabellen unten). Ihr Code kann einfach die Zeichenfolgen verknüpfen oder sie als Startwert verwenden, um einen eindeutigen Hashwert zu erstellen, der als Cacheschlüssel dienen kann.

Wenn Ihre Anwendung schließlich sowohl SharePoint-Aufrufe nur für das Add-In als auch für Benutzer und Add-In ausführt, hat sie zwei verschiedene Zugriffstoken. Also benötigen Sie unterschiedliche Cacheschlüssel. Wenn Sie sich für einen grundlegenden Cacheschlüssel entschieden haben, hängen Sie ihm einfach "__nur-add-in" oder "__add-in+benutzer" an.

Warnung

Das Speichern des Zugriffstokens in einem Cookie ist keine sichere Vorgehensweise. Für gewöhnlich wird als eine bewährte Methode vermieden, das Zugriffstoken über den Browser zu übergeben.

Weiterleiten des Zugriffstokens an Back-End-Systeme

Ein SharePoint-Add-In hat möglicherweise Back-End-Server, die nicht in derselben Domäne gehostet sind wie die Remotewebanwendung. Wenn ein Back-End-Server CRUD-Vorgänge in SharePoint durchführen muss, zeigt das Add-In eine schnellere Leistung, wenn diese Vorgänge direkt vom Back-End-System zu SharePoint gehen können. Zum Glück ist die Domäne nur wichtig, wenn Ihre Anwendung ein Zugriffstoken von ACS erhält. Wenn sie das Token hat, kann sie es an die Back-End-Dienste weiterleiten und diese können damit SharePoint aufrufen.

Code in diesen Systemen muss abgelaufene Zugriffstoken behandeln und eine Anforderung für ein neues Token zurück an die übergeordnete Webanwendung senden, die bei ACS registriert ist (siehe Umgang mit abgelaufenen Zugriffstoken). Diese Technik sollte nur für die eigenen Back-End-Server Ihrer Anwendung, nicht für externe Webdienste verwendet werden. Außerdem sollten Sie bei Verwendung dieser Technik überlegen, ob Sie die Back-End-Dienste so entwerfen können, dass sie möglichst immer Nur-Add-In-Aufrufe verwenden.

Umgang mit abgelaufenen Zugriffstoken

Ein Zugriffstoken läuft nach einigen Stunden ab (12 Stunden zu dem Zeitpunkt, an dem der Artikel geschrieben wurde, aber das kann sich geändert haben). Wenn die Anwendung immer noch auf SharePoint zugreift, nachdem das Zugriffstoken abgelaufen ist, führt die erste Anforderung an SharePoint nach dem Ablaufzeitpunkt zu einem Fehler 401 - Nicht autorisiert. Ihr Code muss diese Antwort verarbeiten.

Alternativ kann er den Ablaufzeitpunkt des Zugriffstokens testen, bevor es verwendet wird. Ihr Code verwendet das Aktualisierungstoken, um ein anderes Zugriffstoken von ACS abzurufen. Im Kontexttokenablauf ist das Aktualisierungstoken im Kontexttoken enthalten, das Ihr Add-In zu Beginn der ersten Sitzung mit SharePoint von SharePoint erhält. Im Autorisierungscodeablauf wird es zusammen mit dem ersten Zugriffstoken an die Anwendung übergeben. Ihr Code muss es zwischenspeichern, damit es bei Bedarf verfügbar ist. Das Aktualisierungstoken ist für einige Monate gültig und kann in einem Cookie oder in serverseitigem Speicher beibehalten werden. Weitere Informationen finden Sie unter Grundlegendes zur Handhabung und zum Zwischenspeichern von Aktualisierungstoken.

Beispiele für Zugriffstoken für Autorisierungssysteme mit niedriger Vertrauensebene

In diesem Abschnitt werden Zugriffstoken anhand von Beispielen beschrieben, und es wird erläutert, wie sie sich je nach der verwendeten Autorisierungsrichtlinie unterscheiden.

Benutzer-und-Add-In-Richtlinie

Im Folgenden sehen Sie ein decodiertes Beispiel für ein Benutzer-und-Add-In-Token, das von ACS für Aufrufe an SharePoint mithilfe der Benutzer-und-Add-In-Richtlinie generiert wurde. Zur besseren Lesbarkeit wurden Leerzeichen eingefügt. Das Token entspricht dem JSON Web Token-Protokoll. Das JSON-Objekt (JavaScript Object Notation) im Token wird als Anspruchssatz bezeichnet. (Ausführliche Informationen zu den Eigenschaften im Anspruchssatz finden Sie in Tabelle 1.)

Alle Werte müssen in Kleinbuchstaben geschrieben werden. (Benutzer-und-Add-In-Zugriffstoken sind im Kontexttokenablauf und im Autorisierungscodeablauf identisch.)

{
 "aud": "00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss": "00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf": 1377549246,
 "exp": 1377592446,
 "nameid": "2303000085ff9abc",
 "actor": "964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73",
 "identityprovider": "urn:federation:microsoftonline"
}

Tabelle 1: Von ACS ausgestellte Benutzer-und-Add-In-Zugriffstoken-Ansprüche

Anspruch	Beschreibung	Entsprechender Wert im Beispiel-Zugriffstoken
aud	Abkürzung für "audience", das ist der Prinzipal, für den das Token vorgesehen ist. Das Format ist audience principal ID/SharePoint domain@SharePoint realm, wobei audience principal ID eine dauerhafte Sicherheitsprinzipal-ID für SharePoint ist (siehe Konstanten für Microsoft-Produktanwendungsprinzipale). SharePoint realm ist die GUID des SharePoint Online-Mandanten oder der lokalen SharePoint-Farm, auf die mit dem Zugriffstoken zugegriffen wird. Diese GUID fungiert als ID des Bereichs für den Tokenaussteller, in diesem Fall Azure ACS.	00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss	Abkürzung für "issuer". Sie stellt den Prinzipal dar, der das Token erstellt hat. Das Format ist Issuer GUID@SharePoint realm GUID. Im Autorisierungssystem mit niedriger Vertrauensebene ist der Aussteller Azure ACS und seine GUID lautet 00000001-0000-0000-c000-000000000000.	00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf	Abkürzung für "not before". Sie steht für den Zeitpunkt in Sekunden ab dem 1. Januar 1970 um Mitternacht, ab dem das Token beginnt, gültig zu werden. Standardmäßig wird der Wert auf den Moment festgelegt, in dem das Token erstellt wird (siehe JWT-Zeitwerte).	1377549246
exp	Abkürzung für "expiration". Sie steht für die Zeit, zu der das Token abläuft. Standardmäßig ist dies 12 Stunden nach der nbf-Zeit (siehe JWT-Zeitwerte).	1377592446
nameid	Ein eindeutiger Bezeichner für den Benutzer, für den das Token ausgestellt wurde. Das Format variiert je nach Identitätsanbieter. In diesem Beispiel ist der Anbieter Microsoft Online, wäre es jedoch Active Directory, würde die ID wie folgt aussehen: s-1-5-21-2127521184-1604012920-1887927527-415149.	2303000085ff9abc
actor	Der Prinzipal, der Zugriff auf die SharePoint-Farm oder den -Mandanten erhalten möchte. Er hat das Format Client ID of Application@SharePoint realm.	964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73
identityprovider	Der eindeutige Name des Identitätsanbieters wie er bei der Internet Assigned Numbers Authority (IANA) registriert ist. Bei einem Add-In, das in SharePoint Online installiert ist, ist der Wert in der Regel der gleiche wie in diesem Beispiel. Bei einem Add-In, das in einer lokalen Farm installiert ist, wäre dies normalerweise ein lokaler Identitätsanbieter, z. B. urn:office:idp:activedirectory.	urn:federation:microsoftonline

Nur-Add-In-Richtlinie

Im Folgenden sehen Sie ein decodiertes Beispiel für ein Nur-Add-In-Zugriffstoken, das von ACS für Aufrufe an SharePoint mithilfe der Nur-Add-In-Richtlinie generiert wurde. Zur besseren Lesbarkeit wurden Leerzeichen eingefügt. Das Token entspricht dem JSON Web Token-Protokoll. Einzelheiten zu den Eigenschaften im Anspruchssatz finden Sie in Tabelle 2. (Die Nur-Add-In-Richtlinie ist nicht für Anwendungen verfügbar, die den Autorisierungscodeablauf verwenden, weil diese nicht über eine Add-In-Manifestdatei verfügen und deshalb keine Berechtigung für die Verwendung von Nur-Add-In-Aufrufen anfordern können.)

{
 "aud":"00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf":1403304705,
 "exp":1403347905,
 "nameid":"c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73",
 "sub":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
 "oid":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
 "trustedfordelegation":"false",
 "identityprovider":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73"
}

Tabelle 2: Von ACS ausgestellte Nur-Add-In-Zugriffstoken-Ansprüche

Anspruch	Beschreibung	Entsprechender Wert im Beispiel-Zugriffstoken
aud	Wie bei Benutzer-und-Add-In-Token in Tabelle 1.	00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss	Wie bei Benutzer-und-Add-In-Token in Tabelle 1.	00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf	Wie bei Benutzer-und-Add-In-Token in Tabelle 1.	1403304705
exp	Wie bei Benutzer-und-Add-In-Token in Tabelle 1.	1403347905
nameid	Ein eindeutiger Bezeichner für das Add-In, anstelle des Benutzers, da die Identität des Benutzers bei der Nur-Add-In-Richtlinie keine Rolle spielt. Das Format ist client ID@SharePoint realm.	c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73
sub	Abkürzung für "subject". Dies ist der Betreff des Tokens, der dem Prinzipal entspricht, der Zugriff auf SharePoint erhalten möchte. In diesem Fall ist dies die Remotewebanwendung. Als Wert wird die Objekt-ID verwendet. Siehe den oid-Anspruch.	1d47ac31-498b-4988-8aac-85fc9bd2e1ce
oid	Abkürzung für "Objekt-ID". Es ist die Objekt-ID in Azure Active Directory für die Remotewebanwendung. In einem Nur-Add-In-Zugriffstoken sind die Betreff- und Objekt-ID ein identischer Wert.	1d47ac31-498b-4988-8aac-85fc9bd2e1ce
trustedfordelegation	Ein boolescher Wert, der angibt, ob SharePoint dem SharePoint-Add-In bei der Authentifizierung und Autorisierung des Benutzers vertrauen soll. In Nur-Add-In-Aufrufen ist der Wert auf "falsch" festgelegt, da die Benutzeridentität keine Rolle spielt.	false
identityprovider	Der eindeutige Name des Identitätsanbieters. Da es sich um das Add-In und nicht um einen Benutzer handelt, deren Identität bereitgestellt wird, ist ACS der Identitätsanbieter. Das Format ist ACS GUID@SharePoint realm.	00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73

Kontexttoken

Ein Kontexttoken wird nur im Kontexttokenablauf des Autorisierungssystems mit niedriger Vertrauensebene verwendet. Wenn das SharePoint-Add-In in SharePoint gestartet wird, fordert SharePoint an, dass Azure ACS ein Kontexttoken erstellt, das SharePoint dann an die Remotekomponente des SharePoint-Add-Ins übergibt. Das Token wird als ausgeblendeter Parameter namens SPAppToken in einer Anforderung von SharePoint für die Startseite der Remotekomponente übergeben. Das Token wird mit einem geheimen Clientschlüssel signiert, der nur ACS und dem SharePoint-Add-In bekannt ist.

Das Kontexttoken enthält ein Aktualisierungstoken, das das Add-In, zusammen mit anderen Informationen aus dem Kontexttoken, verwendet, um ein Zugriffstoken von ACS anzufordern. (Zum Zeitpunkt, zu dem dieser Artikel geschrieben wurde, hatten von ACS ausgestellte Kontexttoken für SharePoint eine Lebensdauer von 12 Stunden, das kann sich aber geändert haben.)

Die Hauptaufgaben für den Code im SharePoint-Add-In sind die folgenden:

• Verwenden Sie den geheimen Clientschlüssel des Add-Ins, um das Kontexttoken zu überprüfen.
• Speichern Sie das Kontexttoken zwischen, oder extrahieren Sie das Aktualisierungstoken und andere Elemente daraus, und speichern Sie diese separat zwischen.
• Verwenden Sie das Aktualisierungstoken und andere Informationen, um ein Zugriffstoken von ACS anzufordern (das dann selbst zwischengespeichert wird).
• Speichern Sie den CacheKey aus dem Kontexttoken zwischen.

Wichtig

Die ersten beiden Aufgaben müssen ausgeführt werden, bevor der Benutzer zu einer anderen Seite navigiert oder die Seite aktualisiert, da sonst das Token verloren geht. Ziehen Sie beispielsweise bei einer ASP.NET-Web Forms-Anwendung in Betracht, diese Aufgaben in der Page_Load-Methode auszuführen (in einem Bedingungscodeblock, der nur ausgeführt wird, wenn die Anforderung kein Postback ist). Bei einer ASP.NET-MVC-Anwendung können Sie diese Aufgaben in der Standardcontrollermethode ausführen.

Wenn Sie verwalteten Code verwenden, befindet sich Beispielcode für einige dieser Aufgaben in den Dateien SharePointContext.cs (oder .vb) und TokenHelper.cs (oder .vb), die in Microsoft Office-Entwicklertools für Visual Studio enthalten sind. Sie müssen nur einfache Aufrufe an die Mitglieder der TokenHelper-Klasse durchführen. Ihr Code kann die erste Aufgabe beispielsweise mit der folgenden einzelnen Codezeile durchführen:

SharePointContextToken contextToken =
    TokenHelper.ReadAndValidateContextToken(contextTokenString,
    Request.Url.Authority);

Zwischenspeichern des Kontexttokens oder von Teilen davon

Sie können ganze Kontexttoken oder nur das Aktualisierungstoken und bestimmte andere darin enthaltene Elemente, die Ihr Code verwendet, um Zugriffstoken abzurufen zwischenspeichern, entweder in serverseitigem oder in clientseitigem Speicher. Zu Zwecken der Einfachheit wird in diesem Artikel davon ausgegangen, dass Sie das Kontexttoken als Einheit zwischenspeichern.

Wichtig

Wir erinnern Sie noch einmal, weil es wirklich wichtig ist: Verwenden Sie keinen clientseitigen Cache für das Zugriffstoken. Dieser ist nur für das Kontexttoken sicher.

Sie haben dieselben serverseitigen Cacheoptionen wie oben für das Zugriffstoken aufgeführt. Zu den clientseitigen Optionen zählen ein Cookie und ein ausgeblendetes Formularfeld auf einer HTML-Seite. Eine weitere Option besteht darin, das Kontexttoken im Sitzungscache zu speichern, aber den daraus abgerufenen Cacheschlüssel auf dem Client zu speichern.

Wenn Ihre Anwendung auf SharePoint zugreift, nachdem eine Sitzung beendet wurde, sind weder der Sitzungscache noch der clientseitige Cache eine Option, weil das Aktualisierungstoken für die Anwendung verfügbar sein muss, falls das Originalzugriffstoken abgelaufen ist, während die Aufgaben nach der Sitzung ausgeführt werden. In diesem Szenario benötigen Sie einen dauerhaften (sitzungsübergreifenden) Cache, der von mehreren Benutzern und/oder SharePoint-Bereichen und/oder Anwendungen gemeinsam verwendet wird. Ihr Code muss also Cacheschlüssel verwenden, die Benutzer, SharePoint-Bereich und/oder Anwendung unterscheiden, wie weiter oben unter Zwischenspeichern des Zugriffstokens beschrieben.

Sie können für diesen Zweck den speziellen Cacheschlüssel verwenden, der sich im Kontexttoken befindet, so wie Sie ihn für das Zugriffstoken verwendet haben. (Siehe nächster Abschnitt Grundlegendes zum Cacheschlüssel.)

Grundlegendes zum Cacheschlüssel

Der Cacheschlüssel ist eine opake Zeichenfolge, die für die Kombination aus Benutzer, Benutzernamenaussteller, Add-In und SharePoint-Farm oder SharePoint Online-Mandant eindeutig ist. Bevor er verschlüsselt wird, hat er das folgende Format, wobei Realm die GUID der lokalen SharePoint-Farm oder des SharePoint Online-Mandanten ist.

UserNameId + "," + UserNameIdIssuer + "," + ApplicationId + "," + Realm

Der Cacheschlüssel enthält keine Website-URL-Informationen. Jeder SharePoint Online-Mandant (oder jede lokale SharePoint-Farm) hat einen eindeutigen Bereich, deshalb ist der Cacheschlüssel für jede Kombination aus Benutzername, Benutzernamen-Aussteller, Anwendung und Farm eindeutig. Im Beispielkontexttoken ist der Wert für den verschlüsselten Cacheschlüssel wie folgt:

KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=

Da Ihre Anwendung möglicherweise mehrere Elemente zwischenspeichert, zum Beispiel sowohl das Zugriffstoken als auch das Kontexttoken im selben Cache mit demselben Cacheschlüssel, sollten Sie in Betracht ziehen, den Cacheschlüssel als Stamm zu verwenden und dann eine bestimmte Zeichenfolge wie "Zugriffstoken" oder "Kontexttoken" nach Bedarf anzuhängen oder voranzustellen, um einen vollständigen Cacheschlüssel zu bilden.

Eine weitere Option besteht darin, eine Klasse zu erstellen, die Eigenschaften für die verschiedenen Dinge enthält, die Sie zwischenspeichern möchten, und dann ein Objekt dieses Typs zwischenzuspeichern.

Eine dritte Option, zumindest wenn Sie eine Datenbank als Cache verwenden, besteht darin, eine Tabelle mit einer Spalte für den Cacheschlüssel und weiteren Spalten für die zwischengespeicherten Elemente (Zugriffstoken, Kontexttoken usw.) zu verwenden.

Ihre Anwendung muss natürlich nicht denselben Cache für alles verwenden, was sie zwischenspeichert. Ein typisches Muster ist, das Zugriffstoken im Sitzungscache, das Kontexttoken (oder das daraus stammende Aktualisierungstoken) in einer Datenbank und den Cacheschlüssel in einem Cookie zwischenzuspeichern.

Verwenden des Kontexttokens zum Abrufen eines Zugriffstokens

Um ein Zugriffstoken zu erhalten, sendet Ihre Anwendung eine Anforderung direkt an ACS. Die Anforderung enthält drei Informationen, die aus dem Kontexttoken (und anderen Informationen) extrahiert werden:

• Das Aktualisierungstoken
• Die Anwendungsprinzipal-GUID von SharePoint
• Die Bereich-GUID der SharePoint-Farm oder des SharePoint Online-Mandanten, auf die bzw. den das Add-In Zugriff erlangen möchte.

Die Datei TokenHelper.cs (oder .vb) enthält Code, der diese Anforderung erstellt. Einen Beispiel-PHP-Code für diese Aufgabe finden Sie unter SharePoint: Durchführen von Vorgängen in der SharePoint-Dokumentbibliothek von einer PHP-Website.

Die Anwendung kann den Bereich des SharePoint-Mandanten oder der Farm zur Laufzeit abrufen, statt ihn aus dem Kontexttoken zu extrahieren. Wenn Sie verwalteten Code verwenden, gibt es eine TokenHelper.GetRealmFromTargetUrl-Methode, um den Bereich abzurufen. Stellen Sie sicher, dass Sie den Wert zwischenspeichern, damit Ihr Code nicht einen weiteren Netzwerkaufruf ausführt, um ihn erneut abzurufen.

Abrufen eines neuen Kontexttokens

Wenn Sie ein neues Kontexttoken benötigen, normalerweise weil das Aktualisierungstoken (das in Kontexttoken enthalten ist) abgelaufen ist, kann Ihr Code ein neues Token abrufen, indem er den Browser auf eine spezielle Seite auf jeder SharePoint-Website umleitet: AppRedirect.aspx. Zwei Abfrageparameter müssen an die URL dieser Seite anhängen:

• client_id: Die Client-ID Ihres SharePoint-Add-Ins.
• redirect_uri: Der URI, an den der Browser umgeleitet werden soll, nachdem das neue Kontexttoken abgerufen wurde. SharePoint fügt das Kontexttoken in diesen URI ein. Normalerweise ist das dieselbe Seite, Contollermethode oder Webdienstmethode, die das neue Kontexttoken angefordert hat. Der Wert muss URL-codiert sein.

Nachfolgend ist die Struktur der URL dargestellt:

https://<SharePointDomain> /_layouts/15/appredirect.aspx?client_id=<app_client_GUID> &amp;redirect_uri=<URL-encoded_redirect_URI>

Im Folgenden finden Sie ein Beispiel für die Durchführung der Anforderung in ASP.NET, bei der die TokenHelper-Datei verwendet wird:

Response.Redirect(TokenHelper.GetAppContextTokenRequestUrl(sharePointUrl, Server.UrlEncode(Request.Url.ToString())));

Beispiel für ein Kontexttoken

Es folgt ein Beispiel für ein Kontexttoken. Das kleine JSON-Objekt (JavaScript Object Notation) im oberen Bereich enthält Metadaten zum Token. Die Eigenschaften sind dieselben wie bei Zugriffstoken (siehe oben). Der Wert der alg-Eigenschaft ist der Name des Algorithmus, der zum Generieren der Signatur verwendet wird, die ACS an das Token anhängt. Details zu den Eigenschaften in der Nutzlast des Tokens finden Sie in Tabelle 3. Alle Werte müssen in Kleinbuchstaben geschrieben werden. (Zur besseren Lesbarkeit wurden Leerzeichen eingefügt.)

{"typ":"JWT","alg":"HS256"}
.
{
 "aud":"a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf":"1335822895",
 "exp":"1335866095",
 "appctxsender":"00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "appctx":"{
            \"CacheKey\":\"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\",
            \"SecurityTokenServiceUri\":\"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\"
           }",
 "refreshtoken":"IAAAAC1Lv5w0OrcFAmJx0xk6aaBdhgsw3VPnPzNEDAWypTHtCYytZ2/dBBUKj+HLK8YB3IUCUfDxYpAque
NHKtgs4rYJJ5AegQpNMOJR1yYK8ngivQx0oetj7aSPuGVb+k6at6G0Kx5LZ5vhxkAq8iUSwu8p4L2cvNMzDF1mDKfMivqxgrIZkr2nbf9as0SJFL6VG5hZnDE4HKq
xJnejSW3umatKM4fsfY1MClVCxrkXb2EQ8H/TmwaJc388YW063GEVUS/3BTSgSIRBKQUmXJuJ6BZY7WTm84LaGrx3mIjnUTM/jnqPoPG55JbCC9sS/MeGNPtzPPCDg
6Vv7dVhQ1Dq5Y3fQ65e9LpJ580jCgzYYvpIFT+Wx5V+17mjY2T8wug04K2ts87Znsr+GfFCorf7NS/lj5HjoxRAQ2tva/8dwguSLwxcUwi/Q9MbpR0NNtlpwVazqi9O
hJ4Df7gVhUDdJ0Dtc6aFCPbl5ZLDDRs42xK2",
 "isbrowserhostedapp": "true"
}

Die Ansprüche aud, iss, nbf und exp sind genau dieselben wie bei einem Zugriffstoken (siehe Tabelle 1).

Die Ansprüche appctxsender, appctx, CacheKey, SecurityTokenServiceUri, refreshtoken und isbrowserhostedapp werden in der folgenden Tabelle beschrieben.

Tabelle 3: Kontexttokenansprüche und -informationen

Anspruch	Beschreibung	Entsprechender Wert im Beispielkontexttoken
aud		a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss		00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf		1335822895
exp		1335866095
appctxsender	Abkürzung für "application context sender". Sie steht für die Anwendung, die das Kontexttoken an das SharePoint-Add-in gesendet hat. Der Wert hat das Format GUID of principal@SharePoint realm, wobei GUID of principal die konstante ID des Anwendungsprinzipals ist, entweder SharePoint, Exchange, Lync oder Workflow.	00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
appctx	Abkürzung für "Add-in-Kontext". Ein JSON-Objekt, das CacheKey und SecurityTokenServiceURI enthält.	CacheKey:"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\", SecurityTokenServiceUri:"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\"
CacheKey	Ein eindeutiger Wert, der als Schlüssel in jedem nach Schlüssel/Wert strukturierten Cache verwendet werden kann, um das Kontexttoken zu speichern und abzurufen. Er kann auch als Wert einer Schlüsselspalte in einer Zeile einer Datenbank verwendet werden.	KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=
SecurityTokenServiceURI	Der URI des tokenausstellenden Diensts.	https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2
refreshtoken	Das Aktualisierungstoken für das Add-In.	IAAAAC1Lv5w0OrcFAmJx0xk6???
isbrowserhostedapp	Ein Boolean-Feld, in dem angegeben wird, ob die Anforderung an das Add-In, das das Kontexttoken enthält, von einem Browser (true) oder von einem Remoteereignisempfänger (false) kommt	true

Verwenden des Kontexttokens, um den Zugriff auf SharePoint-Benutzer zu beschränken

Wenn Sie den Zugriff auf Ihre Remotekomponente wie einen WCF-Dienst auf SharePoint-Benutzer beschränken möchten, kann Ihr Code einfach das Kontexttoken in der HTTP-Anforderung überprüfen. (Wenn Sie verwalteten Code verwenden, können Sie einfach TokenHelper.ReadAndValidateContextToken() aufrufen).

Ihr Code kann überprüfen, ob der Akteuranspruch des Tokens mit 00000003-0000-0ff1-ce00-000000000000 beginnt, wenn Sie sicherstellen möchten, dass es sich um SharePoint handelt (und z. B. nicht um Exchange, Lync oder Workflow). Wenn Sie eine zusätzliche Prüfung ausführen möchten, für die ein Rückruf an SharePoint nötig ist, z. B. um den Zugriff auf Benutzer mit einer bestimmten Rolle in SharePoint zu beschränken, können Sie die Tatsache, dass Sie diese Prüfung für einen bestimmten Benutzer ausgeführt haben, zwischenspeichern (mithilfe des CacheKey des Kontexttokens), damit Sie dies nur einmal tun müssen.

Aktualisierungstoken

Ein Aktualisierungstoken ist in dem Kontexttoken enthalten, das SharePoint an Ihre Webanwendung veröffentlicht, wenn sie gestartet wird. Das Aktualisierungstoken ist ein verschlüsseltes Token, das Ihr SharePoint-Add-In nicht entschlüsseln kann. Ihr Code verwendet es, zusammen mit anderen Informationen, um ein neues Zugriffstoken abzurufen, wenn das aktuelle Zugriffstoken abgelaufen ist. Es wird auch verwendet, um das erste Zugriffstoken im Kontexttokenablauf abzurufen. (Zum Zeitpunkt, zu dem dieser Artikel geschrieben wurde, hatten von ACS ausgestellte Aktualisierungstoken für SharePoint eine Lebensdauer von sechs Monaten, das kann sich aber geändert haben.)

Da ein Zugriffstoken für Stunden gültig ist (derzeit 12) und ein Endbenutzer jedes Mal, wenn er Ihr SharePoint-Add-In von SharePoint aus startet, ein neues bekommt, brauchen Sie das Aktualisierungstoken nur in den folgenden Szenarien:

• Benutzer haben über lange Zeit laufende Sitzungen mit Ihrem Add-In, in denen das Add-In über viele Stunden (derzeit mehr als 12) nach ihrem Start Aufrufe an SharePoint durchführt.

• Das Design des Add-Ins ermöglicht Benutzern, den Zugriff des Add-Ins auf SharePoint für einen Zeitpunkt nach dem Beenden der Sitzung zu planen.

Für beide Szenarien muss Ihr Add-In das Aktualisierungstoken zwischenspeichern, und im zweiten Szenario ist ein serverseitiger Cache erforderlich, der über Sitzungen hinweg erhalten bleibt. Ihre Optionen zum Zwischenspeichern sind dieselben wie für das Zugriffstoken, und im Kontexttokenablauf können Sie den Cacheschlüssel im Kontexttoken verwenden. (Im Kontexttokenablauf speichern Sie nur das Kontexttoken zwischen. Es enthält das Aktualisierungstoken und andere Informationen, die Sie benötigen, um ein neues Zugriffstoken abzurufen. Im Autorisierungscodeablauf gibt es kein Kontexttoken, deshalb speichern Sie das Aktualisierungstoken selbst zwischen.)

Wenn Sie das Aktualisierungstoken in einem Speicher zwischenspeichern, der über die Sitzungen eines bestimmten Benutzers mit Ihrem Add-In bestehen bleibt, achten Sie darauf, dass Sie es durch das neueste Aktualisierungstoken ersetzen. Sowohl im Cloud-gehosteten als auch im Autorisierungscodeablauf erhält der Benutzer jedes Mal ein neues Aktualisierungstoken, wenn er das Add-In startet.

Wenn das Aktualisierungstoken abgelaufen ist, führt eine Anforderung an ACS für ein neues Zugriffstoken zu einem Fehler 401 - Nicht autorisiert. Das Add-In sollte auf diesen Fehler reagieren, indem es ein neues Aktualisierungstoken abruft und es verwendet, um ein neues Zugriffstoken zu erhalten. (Da das Aktualisierungstoken verschlüsselt ist, kann Ihr Code den Ablaufzeitpunkt nicht überprüfen, bevor er es verwendet.)

Im Kontexttokenablauf erhält Ihr Add-In ein neues Aktualisierungstoken durch Abrufen eines neuen Kontexttokens. Im Autorisierungscodeablauf erhält Ihr Add-In ein neues Aktualisierungstoken, indem es den Ablauf neu startet. Ihr Code sollte spezifisch auf den Fehler reagieren, indem er den Benutzer zur SharePoint-Seite OAuthAuthorize.aspx umleitet, wie unter Grundlegendes zum OAuth-Ablauf für Add-Ins, die Berechtigungen dynamisch anfordern beschrieben.

Autorisierungscodes

Im Ablauf des Autorisierungscodes beginnt der Autorisierungsprozess mit einem Autorisierungscode, den ACS auf Anfrage von SharePoint ausgibt und den SharePoint dann als Abfrageparameter an die Remoteanwendung weitergibt. Der Autorisierungscode ist für jedes Paar aus Benutzer und Remoteanwendung eindeutig. (Als dieser Artikel geschrieben wurde, hatten die von ACS ausgegebenen Autorisierungscodes für SharePoint eine Lebensdauer von 5 Minuten, aber das kann sich ändern).

Die Logik in Ihrer Anwendung muss den Autorisierungscode aus dem Abfrageparameter abrufen und ihn in einer Anforderung an ACS für ein Zugriffstoken verwenden. Wenn Sie verwalteten Code verwenden, finden Sie Beispielcode für das Erstellen des Tokens in der Datei TokenHelper.cs (und .vb). Beispielcode für das Lesen des Abfrageparameters finden Sie unter CodeBehind-Beispiel für eine Seite, die auf SharePoint zugreift. ACS macht den Autorisierungscode direkt nach der Ausgabe des Zugriffscodes ungültig, damit er nur einmal verwendet werden kann. Somit macht es keinen Sinn, ihn zwischenzuspeichern.

JWT-Zeitwerte

Die Ansprüche nbf und exp haben das durch die JWT-Spezifikation angegebene Format. Sie werden als Anzahl der Sekunden seit dem 1. Januar 1970 dargestellt. In C# können Sie diese Werte mit dem folgenden Code übersetzen, wobei jWTTimeStamp der Wert aus dem Token ist, z. B. 1335822895.

DateTime exp = new DateTime(1970,1,1).AddSeconds(jWTTimeStamp);

Token-Problembehandlung

Das kostenlose Fiddler Tool kann zum Erfassen der HTTP-Anforderungen verwendet werden, die von der Remotekomponente Ihres Add-Ins an SharePoint gesendet werden. Es gibt eine kostenlose Erweiterung für dieses Tool, die automatisch die Token in den Anforderungen decodiert.

Siehe auch

• SharePoint-Codebeispiel: Remote-Add-In „Hello World“ mit CSOM
• Beispielpaket für SharePoint-Add-Ins
• Erstellen von SharePoint-Add-Ins, die Autorisierung mit einer niedrigen Vertrauensebene verwenden
• Autorisierung und Authentifizierung für Add-Ins in SharePoint