Erstellen von SharePoint-Add-Ins, die eine Autorisierung mit niedriger Vertrauensebene verwenden

  • Artikel

Remotekomponenten in einem SharePoint-Add-In (oder einer externen Anwendung) können eine Autorisierung für SharePoint-Ressourcen erhalten, indem sie bei jeder HTTP-Anforderung ein Zugriffstoken an SharePoint übergeben. Die Remotekomponenten erhalten das Zugriffstoken von einem Microsoft Azure Access Control Service.Konto (ACS), das mit dem Office 365-Mandanten des Kunden verknüpft ist. Azure ACS fungiert als Autorisierungsserver in einer OAuth 2.0-Transaktion (als Ablauf bezeichnet), wobei SharePoint als Ressourcenserver und die Remotekomponenten als Client fungieren. Damit im Zusammenhang stehende Protokollspezifikationen finden Sie unter Webautorisierungsprotokoll (oauth).

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.

Vom Anbieter gehostete SharePoint-Add-Ins, die das System mit niedriger Vertrauensebene verwenden, können im Office Store verkauft und entweder auf Microsoft SharePoint Online oder in einer lokalen SharePoint-Farm installiert werden, die zur Verwendung des Office 365-Mandanten konfiguriert wurde, um eine Vertrauensstellung mit Azure ACS herzustellen. Der Kunde muss über einen Office 365-Mandanten verfügen, um SharePoint-Add-Ins zu installieren, die das System mit niedriger Vertrauensebene verwenden. Der Kunde muss den Mandanten jedoch nicht für andere Zwecke verwenden. Informationen zum Verknüpfen einer lokalen Farm mit einem Office 365-Mandanten finden Sie unter Verwenden einer Office 365 SharePoint-Website, um vom Anbieter gehostete Add-Ins auf einer lokalen SharePoint-Website zu autorisieren.

Registrierung mit Azure ACS

Um das System mit niedriger Vertrauensebene zu verwenden, muss das SharePoint-Add-In zuerst bei Azure ACS und dann beim App-Verwaltungsdienst der SharePoint-Farm oder bei dem SharePoint Online-Mandanten registriert werden. (Dieser wird als „App-Verwaltungsdienst“ bezeichnet, da SharePoint-Add-Ins ursprünglich „Apps für SharePoint“ hießen.)

Add-Ins, die über den Office Store verkauft werden, erfolgt die Registrierung bei ACS im Verkäufer-Dashboard, und die Registrierung bei dem Dienst wird bei der Installation des Add-Ins ausgeführt.

Für Add-Ins, die im Add-In-Katalog der Organisation verteilt werden, erfolgt die Registrierung sowohl bei ACS als auch beim Dienst auf der Seite _Layouts\15\AppRegNew.aspx eines beliebigen SharePoint-Mandanten oder einer SharePoint-Farm, in der das Add-In installiert werden soll. Externe, Nicht-SharePoint-Anwendungen, die auf SharePoint zugreifen, müssen auch registriert werden. Diese Kategorie umfasst Office-Add-Ins, Windows Store-Apps, Webanwendungen und Geräte-Apps, wie Smartphone-Apps.

Hinweis

Für die Registrierung muss die Anwendung über eine Internetdomäne verfügen. Zu diesem Zweck kann jede vorhandene Domäne verwendet werden, Sie können jedoch nicht zu 100 % sicher sein, dass eine Domäne, die Sie nicht besitzen, auch existiert, deshalb muss eine Webanwendung Teil einer systemeigenen Geräteanwendung sein, selbst wenn die Webanwendungskomponente nur zum Aktivieren der Registrierung dient. Weitere Informationen finden Sie in einem so konzipierten Codebeispiel unter Bereitstellen von Websites in Batches mit dem Add-In-Modell.

Weitere Informationen über die Registrierung finden Sie unter Registrieren von SharePoint-Add-Ins.

Ablauf des geheimen Add-In-Schlüssels

Der geheime Add-In-Schlüssel muss alle 12 Monate erneuert werden. Weitere Informationen finden Sie unter Austauschen eines ablaufenden geheimen Clientschlüssels in einem SharePoint-Add-In.

Autorisierungsrichtlinien

Ein SharePoint-Add-In kann für die Verwendung einer der drei folgenden Autorisierungsrichtlinien ausgelegt sein:

  • Richtlinie nur für Benutzer. Wenn die Richtlinie nur für Benutzer verwendet wird, überprüft SharePoint nur die Berechtigungen für den Benutzer. SharePoint verwendet diese Richtlinie, wenn der Benutzer direkt auf Ressourcen zugreift, ohne ein Add-In zu verwenden, z. B. wenn ein Benutzer zum ersten Mal die Startseite einer SharePoint-Website öffnet oder über PowerShell auf SharePoint-APIs zugreift.

  • Nur-Add-In-Richtlinie Ein Add-In, das diese Richtlinie verwendet, kann eine Aktion ausführen, für die es über eine Berechtigung verfügt, auch wenn der Benutzer keine Berechtigung für die Aktion besitzt. Der Entwickler muss anfordern, dass diese Richtlinie im Add-In-Manifest des Add-Ins verwendet wird. Die Anforderung muss vom Benutzer, der das Add-In installiert, genehmigt werden. Diese Richtlinie ist nur für vom Anbieter gehostete SharePoint-Add-Ins zulässig.

  • Benutzer-und-Add-In-Richtlinie Add-Ins, die diese Richtlinie verwenden, können nur Aktionen ausführen, für die sowohl das Add-In als auch der Benutzer über eine Berechtigung verfügen. Dies ist die Standardrichtlinie, die verwendet wird, es sei denn, der Entwickler setzt durch, dass eine andere Richtlinie verwendet wird.

Weitere Informationen über Autorisierungsrichtlinien finden Sie unter Add-In-Autorisierungsrichtlinientypen in SharePoint.

Zwei OAuth-Laufzeitabläufe

Jedes Mal, wenn ein cloudgehostetes Add-In oder eine externe Anwendung, die auf SharePoint zugreift, ausgeführt wird, tritt ein Ablauf bzw. eine Reihe von Interaktionen zwischen dem Add-In, SharePoint, ACS und manchmal auch dem Endbenutzer auf. Das Endergebnis des Ablaufs besteht darin, dass SharePoint ein Zugriffstoken empfängt, das in jeder CRUD-Anforderung (Erstellen, Lesen, Aktualisieren, Löschen) enthalten ist, die die Anwendung an SharePoint stellt.

Es gibt zwei wichtige OAuth-Flows, die von SharePoint verwendet werden. Eine ist für in der Cloud gehostete SharePoint-Add-Ins. Die andere , die als "on the fly" bezeichnet wird, ist für Anwendungen auf anderen Plattformen vorgesehen, die auf SharePoint-Daten zugreifen.

  • Kontexttokenablauf. Die Remotekomponente des SharePoint-Add-Ins verwendet das SharePoint-Clientobjektmodell (CSOM) oder REST-Endpunkte für Aufrufe an SharePoint. SharePoint fordert ein Kontexttoken von ACS an, das es an den Remoteserver senden kann. Der Remoteserver verwendet das Kontexttoken, um ein Zugriffstoken von ACS anzufordern. Der Remoteserver verwendet dann das Zugriffstoken, um wieder mit SharePoint zu kommunizieren.

    Weitere Informationen zu diesem Ablauf finden Sie unter OAuth-Ablauf mit Kontexttoken für SharePoint-Add-Ins

  • Authentifizierungscode-Ablauf. Einem SharePoint-Add-In werden die Berechtigungen erteilt, die es für SharePoint-Ressourcen benötigt, wenn es installiert wird. Anwendungen, die nicht in SharePoint installiert sind, müssen jedoch spontan um Berechtigungen bitten, d.h. jedes Mal, wenn sie ausgeführt werden. Es gibt es kein SharePoint-Kontexttoken in diesem Ablauf. Wenn das Add-In stattdessen ausgeführt wird und versucht, auf SharePoint zuzugreifen, wird der Benutzer von SharePoint aufgefordert, die Berechtigungen der Anwendung zu erteilen, die diese anfordert. Wenn der Benutzer die Berechtigungen erteilt, erhält SharePoint einen Autorisierungscode von ACS, den es an die Anwendung übergibt. Die Anwendung verwendet den Code, um ein Zugriffstoken aus ACS abzurufen, das es dann für die Kommunikation mit SharePoint verwenden kann.

    Weitere Informationen zu diesem Ablauf finden Sie unter OAuth-Ablauf mit Autorisierungscode für SharePoint-Add-Ins.

Problembehandlung bei SharePoint-Add-Ins mit niedriger Vertrauensebene

Dieser Artikel bietet einige allgemeine Informationen zur Problembehandlung sowie Informationen über einige spezielle Probleme mit SharePoint-Add-Ins, die das Autorisierungssystem mit niedriger Vertrauensebene verwenden.

Verwenden des Fiddler-Tools

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 Zugriffstoken in den Anforderungen entschlüsselt.

Deaktivieren der HTTPS-Anforderung für OAuth während der Entwicklung

OAuth erfordert, dass SharePoint HTTPS ausführt (nicht nur Ihren Dienst, sondern auch SharePoint). Dies kann Ihnen beim Entwickeln des Add-Ins im Wege stehen. Möglicherweise wird die Meldung „403 (Verboten)“ angezeigt, wenn versucht wird, einen Aufruf an SharePoint beim Debuggen des Add-Ins zu tätigen, weil die SSL-Unterstützung im „localhost“, auf dem Ihr Add-In ausgeführt wird, nicht vorhanden ist.

Sie können die HTTPS-Anforderung während der Entwicklung mithilfe der folgenden Windows PowerShell-Cmdlets deaktivieren.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $true
$serviceConfig.Update()

Um die HTTPS-Anforderung später wieder zu aktivieren, verwenden Sie die folgenden Windows PowerShell-Cmdlets.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $false
$serviceConfig.Update()

Die fehlende Übereinstimmung von Domänennamen in Konfigurationsdateien und Registrierungsformularen kann die Autorisierung verhindern. Die folgenden vier Werte müssen exakt gleich sein:

  • Die Add-In-Domäne, die bei der SharePoint-Add-In-Registrierung auf „AppRegNew.aspx" oder im Verkäuferdashboard angegeben wird.

  • Die Domäne, unter der das Sicherheitszertifikat der Remotewebanwendung registriert ist

  • Der Domänenteil des Werts StartPage in der Datei „AppManifest.xml".

  • Der Domänenteil der URL aller Ereignisempfänger, die in der Datei „AppManifest.xml“ angegeben sind

Beachten Sie in Verbindung mit diesem Punkt Folgendes:

  • Wenn die Remotekomponente Ihres SharePoint-Add-In einen anderen Port als 443 verwendet, müssen Sie den Port ausdrücklich als Teil der Domäne an allen vier Stellen einschließen, beispielsweise contoso.com:3333. (Sie müssen das HTTPS-Protokoll verwenden, für das der Standardport 443 ist.)

  • Wenn Sie einen DNS CNAME-Alias für Ihre Remotewebanwendung erstellen, verwenden Sie an allen vier Stellen den CNAME-Alias für den Domänenwert. Wenn Ihre Anwendung beispielsweise unter contoso.cloudapp.net gehostet wird und Sie den CNAME contososoftware.com dafür erstellen, verwenden Sie contososoftware.com als Domäne.

  • Die Domäne muss im StartPage-Wert (und in allen Ereignisempfänger-URLs) der Datei „AppManifest.xml“ hartcodiert werden, bevor das Add-In verpackt wird. Wenn Sie den Veröffentlichungs-Assistenten in Visual Studio zum Verpacken des Add-Ins verwenden, werden Sie nach der Domäne gefragt, und die Office Developer Tools für Visual Studio fügen diese in den Wert StartPage für Sie ein (anstelle des ~remoteWebUrl-Tokens, das beim Debuggen verwendet wird. Wenn Sie den Veröffentlichungs-Assistenten jedoch nicht verwenden, oder wenn Sie ihn verwenden, Ihre Remotewebanwendung aber in Azure bereitgestellt wird, müssen Sie das Token manuell durch die Domäne (und das Protokoll) ersetzen, z. B. https://contososoftware.com oder https://MyCloudVM:3333.

Fehler „Die zugrunde liegende Verbindung wurde geschlossen: Für den geschützten SSL/TLS-Kanal konnte keine Vertrauensstellung hergestellt werden“.

Dieser Fehler ist ein SSL Handshake-, kein OAuth-Problem. Stellen Sie sicher, dass das von Ihnen verwendete Zertifikat für SharePoint vertrauenswürdig ist und das Zertifikat mit dem Endpunktnamen übereinstimmt.

Fehler bei der Verwendung der HTTP-DAV-Methode zum Lesen von Dateien aus SharePoint

HTTP DAV funktioniert nicht zusammen mit OAuth. Wenn Sie das SharePoint-Clientobjektmodell (CSOM) nutzen, verwenden Sie zum Lesen einer Datei den folgenden Code.

File f = clientContext.Web.GetFileByServerRelativeUrl( url);
ClientResult<Stream> r = f.OpenBinaryStream();
clientContext.ExecuteQuery();

Siehe auch