Isolierte Webparts

Mit dieser Funktion können Sie Webparts erstellen, die sicher mit durch Azure AD geschützten APIs kommunizieren, ohne dass Zugriffstoken an andere Komponenten auf dieser Seite oder Skripts im Mandanten weitergegeben werden.

Warum isolierte Webparts?

Um Ihren Sharepoint-Framework-Lösungen einen sicheren Zugriff auf durch Azure AD gesicherte APIs zu ermöglichen, können Sie die API-Verwaltung verwenden, um anzugeben, auf welche APIs Skripte in Ihrem Mandanten zugreifen können und welche Genehmigungen dafür erforderlich sind. Als nächstes können Sie mithilfe von Sharepoint-Framework ganz einfach ein Zugriffstoken für eine bestimmte API erhalten. Während es die Kommunikation mit durch Azure AD gesicherten APIs deutlich vereinfacht, ermöglicht es allen Skripts – nicht nur bestimmten Sharepoint-Framework-Lösungen – ein Zugriffstoken für jede genehmigte API zu erhalten. Wenn eines der Skripts, die Sie in Ihrem Mandanten verwenden, mit unlauteren Absichten genutzt wird, könnte es im Namen des aktuellen Benutzers auf jede genehmigte API zugreifen.

Isolierte Webparts stellen eine neue Möglichkeit dar, den Zugriff auf mit Azure AD gesicherte APIs zu isolieren, ein und stellen sicher, dass nur bestimmte SharePoint-Framework-Webparts berechtigt sind, ein Zugriffstoken für die spezifische API abzurufen.

Wie funktionieren isolierte Webparts?

Wichtig

Die Funktion für isolierte Webparts ist nur in SharePoint-Framework v1.8 und höher verfügbar. Isolierte Webparts werden nur auf modernen Seiten unterstützt. Obwohl Sie klassischen Seiten möglicherweise isolierte Webparts hinzufügen können, wird das Webpart bei der Veröffentlichung nicht gerendert und generiert einen Fehler. Isolierte Webparts können nur im Mandanten-App-Katalog installiert werden. Sie funktionieren nicht in einem Websitesammlungs-App-Katalog.

Bei Lösungen, die die Funktion für isolierte Webparts verwenden, ist in den Projektmetadaten in der Datei *.sppkg ein bestimmtes Flag festgelegt. Bei der Bereitstellung dieser Lösungen im App-Katalog werden alle API-Berechtigungsanforderungen als isoliert angegeben.

Nachdem eine isolierte API-Berechtigungsanforderung genehmigt wurde, erstellt SharePoint eine separate Azure AD-Anwendung in der Azure AD, die mit dem Microsoft 365 Mandanten verknüpft ist. Diese Azure AD-Anwendung ist spezifisch für die SharePoint-Framework-Lösung, die API-Berechtigungen angefordert hat, und verfügt über die OAuth-Berechtigungen, die von dieser Lösung angefordert wurden. Für die Rückgabe-URL dieser Azure AD-Anwendung, die vom impliziten OAuth-Fluss verwendet wird, wird eine eindeutige Domäne festgelegt, die an diese bestimmte SharePoint-Framework-Anwendung gebunden ist.

Alle Webparts von Lösungen, die isolierte Berechtigungen verwenden, werden, wenn sie einer Seite hinzugefügt werden, mithilfe eines iframe-Elements angezeigt, das auf eine eindeutige Domäne verweist, die an die bestimmte SharePoint-Framework-Lösung gebunden ist. Auf diese Weise kann SharePoint-Framework eindeutige API-Berechtigungen erzwingen und sicherstellen, dass keine andere Lösung oder kein anderes Skript im Mandanten ein Zugriffstoken für diese API erhält.

Gerüst eines Projekts, das isolierte Berechtigungen verwendet

Wenn Sie ein Gerüst für ein neues SharePoint-Framework-Projekt erstellen, das auf SharePoint Online ausgerichtet ist, zeigt der Yeoman-Generator von SharePoint Framework die folgende Eingabeaufforderung an:

Benötigen die Komponenten in der Lösung Berechtigungen für den Zugriff auf eindeutige, nicht für andere Komponenten des Mandanten freigegebene Web-APIs?:

Wenn Sie mit Jaantworten, fügt der Generator der Projektkonfiguration in der config/package-solution.json-Datei ein Flag hinzu, indem er die isDomainIsolated-Eigenschaft auf truefestlegt. Weil die isolierte Webpart-Funktion nur auf Webparts zutrifft, lässt der Generator nur die Erstellung von Webparts in Ihrem Projekt zu.

Wichtig

Theoretisch könnten Sie SharePoint-Framework-Erweiterungen in einem Projekt, das isolierte Berechtigungen verwendet, manuell erstellen. Die ist jedoch eine schlechte Idee, die Sie niemals ausführen sollten und die nicht unterstützt wird.

Wenn die von Ihnen hinzugefügte Erweiterung mit durch Azure AD gesicherten APIs kommunizieren würde, wäre die nicht in der Lage, Zugriffstoken auf eine isolierte Weise abzurufen und würde die Runtime überschreiten.

Kommunikation mit APIs

Abgesehen von dem Webpart, der isolierte Berechtigungen verwendet, gibt es nichts, was Sie beim Abrufen eines Zugriffstoken zu einer durch Azure AD gesicherten API in Ihrem Code beachten müssen. Obwohl auf Runtime isolierte Webparts in einem iframe geladen werden, der auf eine eindeutige Domäne zeigt, können Sie mit der SharePoint REST API auf die selbe Weise kommunizieren, wie Sie es in nicht-isolierten Webparts tun würden.

Bereitstellungslösungen mit isolierten Webparts

Lösungen mit isolierten Webparts werden auf dieselbe Weise bereitgestellt wie herkömmliche SharePoint Framework-Lösungen. Der einzige Unterschied besteht darin, dass die API-Berechtigungsanfragen isoliert bereitgestellt werden. Dies ist deutlich sichtbar auf der API-Verwaltungsseite, auf der die API-Berechtigungsanfragen nach Lösungen gruppiert sind, auf die sie zutreffen:

Auf der Mandantenebene erteilte API-Berechtigungen können von jeder Sharepoint-Framework-Lösung oder jedem Teil des Skripfs auf dem Mandanten verwendet werden. Isolierte Berechtigungen können dagegen, nur von der Lösung verwendet werden, die sie angefordert.

Isolierte Webparts verwenden

Isolierte Webparts werden, wenn sie zur Seite hinzugefügt werden, unter Verwendung eines iframe angezeigt. Dieses Iframe verweist auf eine eindeutige Domäne, die der Sharepoint-Framework-Lösung zugewiesen ist, auf der sich der Webpart befindet. Auf diese Domäne wird auch in der Rückgabe-URL der Azure AD-Anwendung zugegriffen, die erstellt wurde, um die isolierten Genehmigungen für die bestimmte SharePoint Framework-Lösung zu hosten. Die Verwendung der eindeutigen Domäne stellt sicher, dass nur Webparts aus der jeweiligen SharePoint-Framework-Lösung ein Zugriffstoken für den isolierten Berechtigungssatz abrufen können.

Eigenschaftenbereich für isolierte Webparts

Der Eigenschaftenbereich für isolierte Webparts wird als separater iFrame mit einer zusätzlichen Instanz desselben Webparts gerendert. Es enthält einige Besonderheiten, die Entwickler beachten sollten:

• Die Lebenszyklusereignisse eines isolierten Webparts wie z. B. render werden zweimal aufgerufen: einmal für das Webpart selbst und einmal für den Eigenschaftenbereich.
• Die iFrame-Größe des Eigenschaftenbereichs ist auf die Abmessungen des Bereichs beschränkt. Berücksichtigen Sie dies, wenn Sie modale Elemente oder breite Steuerelemente in Ihrem Eigenschaftenbereich verwenden möchten.

Entsorgung isolierter Webparts

onDispose Methode für isolierte Webparts kann nicht aufgerufen werden, da das Entfernen eines iframe aus DOM automatisch alle Ressourcen, einschließlich Socketverbindungen, die mit dem Dokument des iframe zugeordnet sind, bereinigt.

Vorhandenes Projekt upgraden, um isolierte Berechtigungen zu verwenden

Wenn Sie ein vorhandenes SharePoint-Framework-Projekt auf Version 1.8.0 aktualisieren und die Funktion für isolierte Berechtigungen verwenden möchten, können Sie dazu in der config/package-solution.json-Datei, die isDomainIsolated-Eigenschaft auf true festlegen. Sie sollten sicherstellen, dass Ihr Projekt nur Webparts enthält.

Nachdem Sie Ihr Projekt so geändert haben, dass es isolierte Genehmigungen verwendet, sollten Sie es erneut bereitstellen. Dadurch werden neue API-Berechtigungsanfragen erstellt, unabhängig von Ihrer Lösung, die vom Mandantenadministrator genehmigt werden müssen.

Entfernen von Lösungen mit isolierten Berechtigungen

Wenn isolierte-API-Berechtigungen genehmigt werden, erstellt SharePoint eine dedizierte Azure AD-Anwendung, die für Sharepoint-Framework-Lösung spezifisch ist, die die Berechtigungen angefordert hat. Wenn die SharePoint-Framework-Lösung aus dem App-Katalog entfernt wird, werden die API-Berechtigungen und die Azure AD-Anwendung nicht entfernt.