PnP Webparts in SharePoint Online aktivieren: App Catalog, Bereitstellung und Berechtigungen

Wie lassen sich PnP Webparts in SharePoint Online aktivieren, ohne das Paket versehentlich im gesamten Tenant freizugeben oder unnötige API-Berechtigungen zu erteilen? Entscheidend sind drei getrennte Entscheidungen: In welchem App Catalog wird das SPFx-Paket abgelegt, für welche Sites wird es bereitgestellt und welche optionalen Microsoft-Graph-Berechtigungen werden tatsächlich benötigt.

Für einen kontrollierten Einstieg sollte das Paket zunächst in einer Test-Site oder einem Site Collection App Catalog geprüft werden. Erst wenn Webparts, Berechtigungen, Suchergebnisse und Update-Verhalten getestet sind, folgt die Bereitstellung für produktive Sites.

Was PnP Modern Search als SPFx-Paket mitbringt

PnP Modern Search wird als SharePoint-Framework-Lösung bereitgestellt. Das heruntergeladene Paket trägt üblicherweise den Namen pnp-modern-search-parts-v4.sppkg und enthält mehrere miteinander kombinierbare Webparts, darunter:

• Search Box für die Eingabe von Suchbegriffen
• Search Results für die Ausgabe der Treffer
• Search Filters für Filter und Refinements
• Search Verticals für unterschiedliche Suchbereiche

Die Bereitstellung des Pakets konfiguriert noch keine fertige Suchseite. Sie sorgt zunächst nur dafür, dass die Webparts in den vorgesehenen Sites verfügbar werden. Suchabfragen, Ergebnislayouts, Filter, Managed Properties und Verbindungen zwischen den Webparts werden anschließend auf den jeweiligen Seiten eingerichtet.

So läuft eine Anfrage technisch ab

Die Webparts werden als clientseitige SPFx-Komponenten im Browser ausgeführt. Sie verwenden den Kontext des angemeldeten Benutzers und greifen abhängig von der Konfiguration auf SharePoint Search, Microsoft Search oder Microsoft Graph zu.

Das bedeutet insbesondere: Die Webparts umgehen keine bestehenden Inhaltsberechtigungen. Ein Benutzer erhält nur Treffer und Detailinformationen, auf die er auch ohne die individuelle Suchseite zugreifen darf. Das Deployment erweitert die Oberfläche, nicht die Zugriffsrechte auf Dokumente, Listen oder Sites.

Optionale API-Berechtigungen

Das Paket kann zusätzliche Microsoft-Graph-Berechtigungen anfordern. Diese werden beispielsweise für Personeninformationen, Anwesenheitsstatus, Microsoft-Search-Lesezeichen oder Graph-basierte Datei- und Personensuchen verwendet.

Die angeforderten Berechtigungen sind nicht automatisch für jede Suchseite erforderlich. Werden sie nicht genehmigt, bleiben die grundlegenden Webparts grundsätzlich verfügbar, während einzelne Zusatzfunktionen eingeschränkt sein können.

Prüfen Sie deshalb vor der Genehmigung:

• Welche Funktionen in der geplanten Suchlösung tatsächlich verwendet werden
• Welche Berechtigungen die konkret heruntergeladene Paketversion anfordert
• Ob besonders weitreichende Bereiche wie organisationsweiter Datei- oder Benutzerzugriff benötigt werden
• Wer die fachliche und technische Verantwortung für diese Freigaben übernimmt

Voraussetzungen, bevor Sie PnP Webparts aktivieren

Bevor Sie die PnP Webparts in SharePoint Online aktivieren, sollten folgende Voraussetzungen erfüllt sein:

• Ein Tenant App Catalog ist vorhanden.
• Die gewünschte Bereitstellungsstrategie wurde festgelegt.
• Eine separate Test- oder Pilot-Site steht zur Verfügung.
• Die aktuelle Paketdatei stammt aus dem offiziellen Release-Bereich des Projekts.
• Die vorherige produktive Paketversion wurde für einen möglichen Rückfall gesichert.
• Die benötigten Administratorrollen sind verfügbar.
• Mindestens eine moderne SharePoint-Seite steht für den Funktionstest bereit.

Notieren Sie zusätzlich die heruntergeladene Version, das Download-Datum und die zugehörigen Release Notes. Der Dateiname allein reicht für eine spätere Versionszuordnung häufig nicht aus.

Tenant App Catalog oder Site Collection App Catalog?

Beide App-Catalog-Varianten können SPFx-Pakete aufnehmen. Der Unterschied liegt im Gültigkeitsbereich und damit im möglichen Einfluss einer Änderung.

Wann der Tenant App Catalog sinnvoll ist

Der Tenant App Catalog eignet sich, wenn PnP Modern Search als zentral betreute Plattformkomponente eingesetzt werden soll. Das ist beispielsweise sinnvoll, wenn mehrere Intranet-, Wissens- oder Fachbereichssites dieselbe Paketversion verwenden sollen.

Die zentrale Bereitstellung reduziert den Installationsaufwand, vergrößert aber den Wirkungsbereich eines fehlerhaften Updates. Ein Paketwechsel kann dann alle Seiten betreffen, auf denen die Webparts eingesetzt werden.

Wann ein Site Collection App Catalog sinnvoll ist

Ein Site Collection App Catalog eignet sich für einen begrenzten Pilotbetrieb oder für Sites, deren Erweiterungen unabhängig vom restlichen Tenant verwaltet werden sollen.

Der Katalog muss zunächst durch einen SharePoint-Administrator für die betreffende Site Collection aktiviert werden. Dafür kann beispielsweise die SharePoint Online Management Shell verwendet werden:

Connect-SPOService -Url https://contoso-admin.sharepoint.com

Add-SPOSiteCollectionAppCatalog `
  -Site https://contoso.sharepoint.com/sites/search-pilot

Voraussetzung ist ein bereits vorhandener Tenant App Catalog. Das ausführende Konto muss außerdem als Site-Collection-Administrator sowohl im zentralen App Catalog als auch in der Ziel-Site eingetragen sein.

Vermeiden Sie nach Möglichkeit, dieselbe Lösung gleichzeitig unkoordiniert im Tenant App Catalog und in mehreren Site Collection App Catalogs zu betreiben. Unterschiedliche Paketstände erschweren Fehleranalyse, Updates und die Zuordnung der tatsächlich geladenen Version.

Paket hochladen, freigeben und in Sites sichtbar machen

1. Paket und Release prüfen

Laden Sie die stabile Paketversion aus dem offiziellen Release-Bereich von PnP Modern Search herunter. Prüfen Sie vor dem Upload mindestens:

• Versionsnummer und Veröffentlichungsdatum
• Hinweise zu Breaking Changes
• Bekannte Fehler und Einschränkungen
• Geänderte oder neue API-Berechtigungen
• Hinweise zur verwendeten SPFx-Version

Testen Sie keine Vorabversion direkt in einem produktiven App Catalog. Auch bei stabilen Releases sollte der Wechsel zuerst auf einer kopierten oder eigens angelegten Suchseite erfolgen.

2. Paket in den App Catalog hochladen

Öffnen Sie im SharePoint Admin Center den Bereich für Apps beziehungsweise die zentrale Seite zur App-Verwaltung. Laden Sie dort die Datei pnp-modern-search-parts-v4.sppkg hoch.

Beim Upload zeigt SharePoint einen Freigabedialog an. Prüfen Sie dort insbesondere, ob die Option zur Bereitstellung auf allen Sites aktiviert ist.

3. Bereitstellungsumfang festlegen

Für das Paket stehen grundsätzlich zwei Wege zur Verfügung:

1. Zentrale Bereitstellung: Die Lösung wird für alle Sites verfügbar gemacht. Die Webparts erscheinen ohne separate App-Installation in den vorgesehenen Sites.
2. Installation je Site: Das Paket liegt im App Catalog, muss aber auf jeder Ziel-Site ausdrücklich über „Aus Ihrer Organisation“ beziehungsweise die Site-Inhalte installiert werden.

Für einen Pilotbetrieb ist die Installation je Site meist leichter kontrollierbar. Bei einem breiten produktiven Rollout reduziert die zentrale Bereitstellung den Verwaltungsaufwand, setzt jedoch einen belastbaren Test- und Freigabeprozess voraus.

Bei einem Site Collection App Catalog bezieht sich die vermeintlich tenantweite Bereitstellungsoption nur auf die betreffende Site Collection. Andere Site Collections erhalten dadurch keinen Zugriff auf das Paket.

4. Optionale API-Anforderungen prüfen

Nach dem Upload können im SharePoint Admin Center unter API-Zugriff neue Berechtigungsanforderungen erscheinen. Diese Anforderungen sind vom eigentlichen Paket-Upload getrennt.

Gehen Sie bei jeder Anforderung einzeln vor:

1. Öffnen Sie die ausstehende Berechtigungsanforderung.
2. Prüfen Sie Ressource, Berechtigungsname und Gültigkeitsbereich.
3. Ordnen Sie die Berechtigung einer konkret geplanten Funktion zu.
4. Genehmigen Sie nur die tatsächlich benötigten Anforderungen.
5. Dokumentieren Sie Genehmiger, Datum und Begründung.

Microsoft-Graph-Berechtigungen erfordern für die Genehmigung in der Regel eine entsprechend privilegierte Entra-ID-Administratorrolle. Der Zugriff auf den App Catalog allein reicht dafür nicht aus.

5. App auf der Ziel-Site installieren

Wurde das Paket nicht zentral für alle Sites bereitgestellt, öffnen Sie die Ziel-Site und installieren Sie die App über die Site-Inhalte beziehungsweise über den Bereich Aus Ihrer Organisation.

Warten Sie anschließend, bis die Installation abgeschlossen ist. Erst danach sollten die enthaltenen Webparts im Webpart-Auswahlmenü moderner Seiten erscheinen.

6. Webparts auf einer Testseite prüfen

Erstellen Sie zunächst eine separate Testseite. Fügen Sie dort mindestens ein Search-Box- und ein Search-Results-Webpart ein. Für den reinen Deployment-Test genügt eine einfache Abfrage ohne benutzerdefiniertes Layout und ohne komplexe Filter.

Erweitern Sie die Seite erst dann um Search Filters und Search Verticals, wenn die grundlegende Ergebnisausgabe funktioniert.

Wer welche Rechte für Deployment und Nutzung braucht

Aufgabe	Benötigte Rolle oder Berechtigung
Tenant App Catalog erstellen oder verwalten	SharePoint-Administrator beziehungsweise Globaler Administrator
SPFx-Paket im Tenant App Catalog hochladen	Berechtigung zur Verwaltung des App Catalogs
Site Collection App Catalog aktivieren	SharePoint-Administration sowie Site-Collection-Administration in App Catalog und Ziel-Site
Microsoft-Graph-Berechtigungen genehmigen	Passende Microsoft-Entra-Administratorrolle, bei Microsoft-APIs in der Regel Globaler Administrator
App auf einer Site installieren	Site Owner oder vergleichbare Vollzugriffsberechtigung
Webparts auf einer Seite einfügen	Bearbeitungsrechte für die betreffende Seite
Suchergebnisse anzeigen	Leserechte auf die gefundenen Inhalte

Trennen Sie möglichst die Rollen für Paketbereitstellung, API-Genehmigung und Seitenkonfiguration. Dadurch lässt sich nachvollziehen, wer eine technische Lösung freigegeben und wer sie inhaltlich eingerichtet hat.

Bereitstellung systematisch testen

Ein erfolgreicher Upload bedeutet noch nicht, dass das Paket auf allen vorgesehenen Sites korrekt funktioniert. Verwenden Sie deshalb eine kurze Testmatrix.

Technischer Basistest

• Die App wird im App Catalog als aktiviert angezeigt.
• Die App ist auf der Pilot-Site installiert oder tenantweit verfügbar.
• Die PnP-Webparts erscheinen im Webpart-Auswahlmenü.
• Eine einfache Suchabfrage liefert Ergebnisse.
• Die Browser-Konsole enthält keine wiederkehrenden Ladefehler.
• Die Seite funktioniert nach vollständigem Neuladen und in einem privaten Browserfenster.

Berechtigungstest

Testen Sie mindestens mit zwei Konten:

• einem Site Owner oder Administrator
• einem normalen Benutzer mit eingeschränkten Leserechten

Beide Konten dürfen unterschiedliche Treffer erhalten. Das ist kein Fehler, sondern die erwartete Sicherheitsfilterung der Suche.

Falls externe Benutzer auf die Suchseite zugreifen sollen, muss zusätzlich geprüft werden, ob alle SPFx-Ressourcen für Gäste erreichbar sind. Fehlender Zugriff auf Paket- oder Asset-Speicherorte kann dazu führen, dass ein Webpart für interne Benutzer funktioniert, für Gäste aber nicht geladen wird.

Test optionaler Funktionen

Prüfen Sie Funktionen mit zusätzlichen API-Abhängigkeiten getrennt von der normalen SharePoint-Suche. Dazu gehören beispielsweise:

• Personenkarten
• Anwesenheitsinformationen
• Graph-basierte Dateisuchen
• Microsoft-Search-Lesezeichen
• weitere organisationsweite Graph-Daten

So lässt sich unterscheiden, ob ein Fehler aus dem Paket-Deployment, aus einer fehlenden API-Genehmigung oder aus der eigentlichen Suchkonfiguration stammt.

Typische Fehler und ihre Ursachen

Die Webparts erscheinen nicht in der Auswahl

Prüfen Sie zuerst, ob das Paket nur hochgeladen oder auch aktiviert wurde. Bei einer Bereitstellung je Site muss die App zusätzlich in der Ziel-Site installiert sein. Kontrollieren Sie außerdem, ob Sie im richtigen App Catalog arbeiten und ob die Seite eine moderne SharePoint-Seite ist.

Die App ist installiert, aber einzelne Funktionen fehlen

In diesem Fall fehlen häufig optionale API-Berechtigungen. Öffnen Sie im SharePoint Admin Center den Bereich API-Zugriff und prüfen Sie ausstehende oder abgelehnte Anforderungen. Genehmigen Sie diese nicht pauschal, sondern nur für die verwendeten Funktionen.

Nur Administratoren sehen Ergebnisse

Das Deployment funktioniert dann meist grundsätzlich. Prüfen Sie die Berechtigungen auf den erwarteten Inhalten, den Suchindex und die verwendete Abfrage. Testen Sie, ob der betroffene Benutzer das Dokument oder Listenelement direkt öffnen kann.

Die Suche liefert überhaupt keine Ergebnisse

Reduzieren Sie die Konfiguration auf eine einfache Abfrage. Entfernen Sie testweise benutzerdefinierte Templates, Filter und dynamische Verbindungen. Liefert auch die vereinfachte Abfrage keine Treffer, liegt das Problem eher bei Suchbereich, Query Template, Indexierung oder Berechtigungen als beim App Catalog.

Nach einem Update bleibt die alte Darstellung sichtbar

Leeren Sie nicht sofort globale Konfigurationen oder entfernen Sie das Paket. Prüfen Sie zunächst:

• ob tatsächlich die neue Paketdatei im richtigen App Catalog liegt
• ob der Upload als Update erkannt und bestätigt wurde
• ob die Paketversion geändert wurde
• ob Browser- oder CDN-Caches noch alte Assets liefern
• ob die getestete Site eine lokale Version aus einem Site Collection App Catalog verwendet

Der API-Zugriff wird im Admin Center nicht angezeigt

Prüfen Sie, ob der Tenant App Catalog vollständig eingerichtet und korrekt registriert ist. Fehlt der zentrale App Catalog, können auch die zugehörigen Bereiche zur Verwaltung von API-Anforderungen fehlen.

Versionswechsel, Tests und Rückfallwege

Ein Update wird üblicherweise durchgeführt, indem die neue .sppkg-Datei in den bestehenden App Catalog hochgeladen und die vorhandene Datei ersetzt wird. Bei einer zentral bereitgestellten Lösung verwenden bestehende Webpart-Instanzen anschließend die aktualisierten Komponenten.

Dadurch muss nicht jede Seite neu bearbeitet werden. Gleichzeitig kann ein inkompatibles Update viele Seiten auf einmal beeinträchtigen.

Vor jedem Update sichern

• Aktuell produktive .sppkg-Datei
• Versionsnummer und Release Notes
• Liste der Sites und produktiven Suchseiten
• Screenshots wichtiger Webpart-Einstellungen
• Exportierte Seiten oder Site Templates, soweit im Betrieb vorgesehen
• Liste genehmigter API-Berechtigungen
• Ergebnisse der letzten Funktionstests

Die Konfiguration eines PnP-Webparts liegt in der jeweiligen Seite. Ein gesichertes Paket allein stellt daher nicht automatisch alle Seitenkonfigurationen wieder her.

Update in Bereitstellungsringen durchführen

Ein praktikabler Ablauf besteht aus drei Stufen:

1. Technische Test-Site: Paket laden, Webparts öffnen und Basistests ausführen.
2. Pilot-Sites: Reale Konfigurationen, Benutzerrollen und Suchszenarien testen.
3. Produktiver Rollout: Paket im zentralen App Catalog aktualisieren oder kontrolliert auf weitere Sites verteilen.

Zwischen Pilot und produktivem Rollout sollten mindestens die wichtigsten Suchseiten, Templates, Filterverbindungen und API-abhängigen Funktionen geprüft werden.

Rückfallweg vorbereiten

Bewahren Sie die zuletzt funktionierende Paketdatei außerhalb des App Catalogs auf. Zusätzlich sollte die Versionsverwaltung der App-Catalog-Bibliothek aktiviert bleiben.

Bei einem fehlerhaften Update besteht der Rückfallweg typischerweise darin, die vorherige Dateiversion im App Catalog wiederherzustellen oder das zuletzt funktionierende Paket erneut bereitzustellen. Anschließend müssen Aktivierungsstatus, API-Anforderungen und betroffene Suchseiten erneut geprüft werden.

Beachten Sie, dass eine mit einer neueren Webpart-Version gespeicherte Seitenkonfiguration nicht zwingend vollständig mit einer älteren Version kompatibel sein muss. Testen Sie den Rückfall deshalb vor dem breiten Rollout auf einer Kopie der produktiven Seite.

Das Löschen des Pakets sollte nur der letzte Schritt sein. Wird eine produktiv verwendete SPFx-Lösung aus dem App Catalog entfernt oder deaktiviert, können bestehende Webpart-Instanzen auf vielen Seiten nicht mehr geladen werden.

Governance und Rollout über mehrere Sites

Sobald PnP Modern Search auf mehreren Sites eingesetzt wird, sollte das Paket wie eine gemeinsam genutzte Plattformkomponente verwaltet werden. Eine einfache technische Dokumentation sollte mindestens folgende Informationen enthalten:

• Paketname und produktive Version
• Quelle und Veröffentlichungsdatum
• Verwendeter App Catalog
• Bereitstellungsumfang
• Genehmigte API-Berechtigungen
• Verantwortliche für Paket und Suchkonfiguration
• Pilot- und Produktiv-Sites
• Update- und Rückfallverfahren

Für viele Sites ist ein zentraler Tenant App Catalog meist wartbarer als mehrere voneinander unabhängige Paketkopien. Site Collection App Catalogs bleiben dennoch sinnvoll, wenn einzelne Lösungen bewusst isoliert, separat getestet oder durch unterschiedliche Teams verantwortet werden.

In Multi-Geo-Umgebungen muss zusätzlich berücksichtigt werden, dass App Catalogs und Bereitstellungen je Geo-Standort getrennt behandelt werden können. Der Rollout sollte dann nicht nur nach Site, sondern auch nach geografischem Speicherort dokumentiert und getestet werden.

Entscheidungshilfe für den ersten Rollout

Ob PnP Webparts zunächst lokal, pilotiert oder tenantweit bereitgestellt werden sollten, hängt weniger von der Paketdatei selbst ab als vom Betriebsmodell der SharePoint-Umgebung. Entscheidend ist, wer Änderungen freigibt, wie viele produktive Seiten betroffen sind und wie schnell ein Rückfallweg umgesetzt werden kann.

Nach der Bereitstellung ist die eigentliche Suchseite noch nicht fertig. Die nächsten Arbeitsschritte betreffen die konkrete Konfiguration von Search Box und Search Results, die Vorbereitung von Managed Properties für Filter und bei komplexeren Suchszenarien die Umsetzung von PnP Search Filtern mit Verfeinerern und KQL.

Checkliste für Freigabe und Betrieb

• Die Paketquelle, Version und Release Notes sind dokumentiert.
• Der Bereitstellungsumfang ist bewusst gewählt und nicht versehentlich tenantweit aktiviert.
• API-Berechtigungen wurden einzeln geprüft und fachlich begründet.
• Mindestens eine Pilot-Seite wurde mit normalem Benutzerkonto getestet.
• Die vorherige Paketversion und ein Rückfallverfahren sind verfügbar.
• Verantwortlichkeiten für Paketupdate und Seitenkonfiguration sind getrennt benannt.

Diese Governance ist besonders wichtig, wenn PnP Modern Search als gemeinsam genutzte Suchplattform im Intranet eingesetzt wird.

So führen Sie das Paket kontrolliert in produktive Sites ein

Für eine sichere Einführung sollten Sie zunächst den Bereitstellungsumfang festlegen, das Paket in einer Pilot-Site aktivieren und dort sowohl normale Suchabfragen als auch API-abhängige Funktionen testen. Erst danach folgt die Freigabe für weitere Sites.

Die wichtigsten Kontrollpunkte sind der verwendete App Catalog, die Option zur tenantweiten Bereitstellung, die separat genehmigten Graph-Berechtigungen und ein getesteter Rückfallweg. Werden diese Punkte dokumentiert, lassen sich spätere Updates wesentlich leichter eingrenzen und nachvollziehen.