Erstellen von mehrinstanzenfähigen Anwendungen für SharePoint Online

Ein sehr häufiger Anwendungsfall bei der Entwicklung von Anwendungen für SharePoint Online ist die Notwendigkeit, wiederverwendbare Lösungen zu erstellen, die für mehrere Mandanten installiert und freigegeben werden können. Es kann sein, dass Sie einfach eine Lösung für ein Unternehmen organization mit einer mehrinstanzenfähigen Topologie entwickeln, oder dass Sie eine Lösung für einen Multi-Geo-Mandanten erstellen, oder einfach, dass Sie ein ISV sind und planen, Ihre Lösung an mehrere Kunden zu verkaufen. Daher muss Ihre Lösung mehrere Mandanten mit angemessenen Isolations- und Sicherheitsgrenzen behandeln.

Im SharePoint-Add-In-Modell gab es kein echtes Konzept einer mehrinstanzenfähigen Lösung, aber Sie konnten eine vom Anbieter gehostete Anwendung erstellen, und im vom Anbieter gehosteten Code könnten Sie verschiedene Zielmandanten und Anwendungsidentitäten behandeln, wenn Sie mit Azure Access Control Service (ACS) kommunizieren, um ein Token für die Nutzung von SharePoint Online abzurufen.

Wichtig

Dieser Artikel bezieht sich auf so genannte PnP-Komponenten, Beispiele und/oder Tools, bei denen es sich um Open-Source-Ressourcen handelt, die von einer aktiven Community unterstützt werden, die unterstützung für sie bereitstellt. Es gibt keine SLA für die Unterstützung von Open Source-Tools durch offizielle Microsoft-Supportkanäle. Diese Komponenten oder Beispiele verwenden jedoch standardmäßig von Microsoft unterstützte APIs und Features, die von Microsoft unterstützt werden.

Wenn Sie möchten, können Sie das folgende Video watch, anstatt den gesamten Artikel zu lesen, den Sie immer noch als eine viel detailliertere Referenz betrachten können.

Registrieren von mehrinstanzenfähigen Anwendungen in Azure Active Directory

Heutzutage können Sie mit SharePoint-Framework problemlos die Benutzeroberfläche/Benutzeroberfläche Ihrer Lösungen erstellen, unabhängig davon, ob die Lösungen ein oder mehrere Mandanten sind, und Sie sollten über eine Back-End-Infrastruktur verfügen, z. B. in Microsoft Azure gehostet, um die tatsächliche Geschäftslogik für Ihre Lösung bereitzustellen. Die Back-End-Infrastruktur sollte mithilfe von SharePoint-REST-APIs und/oder Microsoft Graph implementiert werden und auf einer in Azure Active Directory registrierten Anwendung basieren.

Im Artikel Upgraden von SharePoint-Anwendungen von Azure Access Control Service auf Azure Active Directory finden Sie weitere Details zum Migrieren einer Anwendung von Azure ACS zu Azure AD. Wenn Sie jedoch eine mehrinstanzenfähige Lösung erstellen möchten, müssen Sie einige zusätzliche Informationen berücksichtigen.

Beim Erstellen einer mehrinstanzenfähigen Anwendung müssen Sie die entsprechende Azure AD-Anwendung als mehrinstanzenfähige Anwendung registrieren. Dazu können Sie im Abschnitt "Unterstützte Kontotypen" die Option "Konten in jedem Organisationsverzeichnis (Beliebiges Azure AD-Verzeichnis – mehrinstanzenfähig)" auswählen, während Sie die Anwendung manuell im Azure-Portal registrieren, wie im folgenden Screenshot zu sehen ist.

Wenn Sie eine solche Option auswählen, kann die Azure AD-Anwendung auf jeden Azure Active Directory-Mandanten (und microsoft 365)-Mandanten ausgerichtet werden, solange Ihrer Anwendung die richtige Berechtigung im Zielmandanten erteilt wird. Wenn Sie den Bereich "Endpunkte" einer anwendung öffnen, die im Azure-Portal als mehrinstanzenfähig registriert ist, sehen Sie, dass alle URLs der OAuth- und OpenID Connect-Endpunkte die Organisationen Schlüsselwort (keyword) anstelle einer expliziten Mandanten-ID aufweisen, da die Anwendung auf jeden organization und nicht nur auf einen bestimmten Mandanten abzielen kann.

Wenn Sie nun bestimmte Berechtigungen für Ihre Anwendung über die Seite API-Berechtigungen konfigurieren, werden die Berechtigungen der Anwendung innerhalb des aktuellen Mandanten erteilt. Sie können jedoch auch Benutzer oder Administratoren anderer Mandanten auffordern, Ihrer Anwendung in ihren eigenen Mandanten dieselben Berechtigungen zu gewähren. Im folgenden Screenshot sehen Sie eine Anwendung mit zwei delegierten Berechtigungen, die im aktuellen Mandanten erteilt wurden:

• Mail.Send: Ermöglicht der Anwendung das Senden von E-Mail-Nachrichten im Namen des aktuellen Benutzers. Hierfür ist die Zustimmung des Benutzers oder Administrators erforderlich.
• User.Read.All: Ermöglicht der Anwendung, die gesamte Liste der Benutzer im Mandanten im Namen des aktuellen Benutzers zu lesen. Hierfür ist die Administratoreinwilligung erforderlich.

Hinweis

Weitere Informationen zu delegierten Berechtigungen finden Sie im Artikel Grundlegendes zu Azure Active Directory und OAuth 2.0 im Kontext der modernen SharePoint Online-Entwicklung.

Stellen Sie sich nun vor, Sie möchten dieselbe Anwendung verwenden, um Daten auf anderen Mandanten als dem Mandanten zu nutzen, in dem Sie die mehrinstanzenfähige Anwendung registriert haben. Azure Active Directory ermöglicht das Anfordern der Zustimmung von Benutzern oder Administratoren, damit diese Ihrer Anwendung Berechtigungen in ihren eigenen Mandanten erteilen können. Die Benutzereinwilligung erfordert, dass Sie den Tokenanforderungs- und Autorisierungsflow durchlaufen. Wenn die Anwendung also ein Zugriffstoken abrufen muss, damit es im Namen des aktuellen Benutzers funktioniert, wird der Benutzer beim ersten Mal aufgefordert, der Berechtigung für Ihre App zuzustimmen.

Im folgenden Screenshot sehen Sie, wie die Zustimmungs-UI aussieht.

Um eine solche Seite zu erhalten, können Sie beispielsweise die Anwendung für die Webauthentifizierung konfigurieren und den Benutzer an eine URL wie die folgende senden:

https://login.microsoftonline.com/{tenant-id}/oauth2/authorize?client_id={client-id}&response_type=code&redirect_uri={redirect-uri}&response_mode=query&scope={scope}

Wenn {tenant-id} für eine mehrinstanzenfähige Anwendung Organisationen sein kann, muss {client-id} der Wert der Eigenschaft "Anwendungs-ID (Client)" der Anwendung im Bereich Übersicht in Azure Active Directory sein, {redirect-uri} ist eine der URLs, die Sie im Bereich Authentifizierung der Anwendung konfiguriert haben, und {scope} stellt die Berechtigungsbereiche dar, für die Sie die Autorisierung abrufen möchten. Um nur ein Beispiel zu machen, könnte die Autorisierungs-URL für eine mehrinstanzenfähige Anwendung in einem realen Szenario etwa wie die folgende sein.

https://login.microsoftonline.com/organizations/oauth2/authorize?client_id=2025da15-1b1a-4f7c-8005-1400b88f5c33&response_type=code&redirect_uri=https://pnp.github.io/&response_mode=query&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.send

Falls der Benutzer, der die obige URL anfordert, ein Mandantenadministrator ist, unterscheidet sich die Benutzeroberfläche geringfügig. Der Administratorbenutzer kann den Berechtigungen für den gesamten Mandanten im Namen des organization zustimmen.

Wenn eine der angeforderten Berechtigungen eine Mandantenadministratorgenehmigung erfordert, z. B. der Berechtigungsbereich User.Read.All , ist ein Mandantenadministrator erforderlich, um dem Anwendungszugriff auf einen Zielmandanten zuzustimmen. Wenn Sie daher mit einem regulären Benutzer, der kein Mandantenadministrator ist, zur Autorisierungs-URL navigieren, wird eine Benutzeroberfläche wie die folgende angezeigt.

Die Meldung weist den Benutzer eindeutig an, einen Mandantenadministrator aufzufordern, die Berechtigungsanforderungen auf Mandantenebene zu genehmigen.

Ein Mandantenadministrator kann zur gleichen URL wie zuvor oder zu einer bestimmten ADMINISTRATOReinwilligungs-URL wie der folgenden navigieren.

https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id={client-id}&redirect_uri={redirect-uri}

Das {tenant-id}-Argument für eine mehrinstanzenfähige Anwendung kann Organisationen sein. {client-id} muss der Wert der Eigenschaft "Anwendungs-ID (Client)" der Anwendung im Bereich Übersicht in Azure Active Directory sein. Sie können auch eine Rückgabe-URL angeben, sofern sie im Authentifizierungsbereich der Anwendung ordnungsgemäß konfiguriert ist, oder Sie können sie überspringen, und der Browser wird nach der Zustimmung zu einer für die Anwendung konfigurierten Umleitungs-URL umgeleitet. Um nur ein Beispiel zu machen, könnte die URL für die Administratoreinwilligung für eine mehrinstanzenfähige Anwendung in einem realen Szenario etwa wie die folgende sein.

https://login.microsoftonline.com/organizations/adminconsent?client_id=2025da15-1b1a-4f7c-8005-1400b88f5c33&redirect_uri=https://pnp.github.io/

Im folgenden Screenshot sehen Sie, welche Art von Benutzeroberfläche einem Mandantenadministrator angezeigt wird.

Aus Sicht des Zielmandanten wird die mehrinstanzenfähige Anwendung nach erfolgreichem Abschluss der Berechtigungserteilung in der Liste der "Unternehmensanwendungen" in Azure Active Directory angezeigt.

Hinweis

Weitere Informationen zu den Azure AD-Zustimmungsflows finden Sie im Artikel Zustimmungserfahrung für Anwendungen in Azure Active Directory.

Behandeln von mehrinstanzenfähigen Anwendungen in SharePoint-Framework

Angenommen, Sie müssen eine SharePoint-Framework Lösung erstellen, die auf einer Back-End-API basiert, und Sie möchten, dass Ihre Lösung mehrinstanzenfähig sein soll, z. B. weil Sie planen, sie über den Microsoft AppSource Store zu verkaufen.

Hinweis

Microsoft AppSource ist der offizielle Marketplace für Microsoft 365, Microsoft Power Platform und Microsoft Dynamics 365, der von Microsoft unter der folgenden URL angeboten wird: https://appsource.microsoft.com/.

Basierend auf dem, was Sie gerade in diesem Artikel gesehen haben, sollten Sie zum Erreichen des soeben beschriebenen Ziels eine Azure Active Directory-Anwendung registrieren, die für die mehrinstanzenfähige Authentifizierung konfiguriert ist, und Ihre Kunden auffordern, Berechtigungen für Ihre Anwendung in jedem Zielmandanten zu erteilen.

Im folgenden Diagramm sehen Sie, wie der Registrierungs- und Zustimmungsflow funktionieren sollte.

Hier sind die Standard Schritte des Registrierungs- und Zustimmungsflows:

1. Der ISV registriert eine neue Azure AD-Anwendung in seinem eigenen Mandanten und konfiguriert die Anwendung für die mehrinstanzenfähige Authentifizierung. Außerdem werden Berechtigungsbereiche für Microsoft Graph (oder eine andere Ressource/API) konfiguriert und eine benutzerdefinierte API für Consumer verfügbar gemacht.
2. ISV hostet die Back-End-APIs seiner Anwendung in Azure, z. B. mithilfe einer Funktions-App oder eines anderen Cloudhostinganbieters.
3. ClientId und ClientSecret der Azure AD-Anwendung sind eindeutig und sind diejenigen, die im Mandanten des ISV definiert sind.
4. ISV registriert seine mehrinstanzenfähige Anwendung im Mandanten des Kunden.
5. Der Mandantenadministrator des Kunden erteilt der Anwendung des ISV seine Zustimmung.
6. Anpassungen, die auf Kundenmandanten ausgeführt werden, nutzen die Back-End-API, die Zugriffstoken bereitstellt, die von ihrem eigenen Mandanten ausgestellt werden.
7. Die Back-End-API kann den Mandanten von Kunden dank der Berechtigungserteilung nutzen.

Während das Registrieren und Hosten einer mehrinstanzenfähigen Anwendung (Schritte 1, 2 und 3) trivial ist, kann die Registrierung und Zustimmung der App in jedem Zielmandanten (Schritt 4 und 5) eine Herausforderung darstellen. Aus diesem Grund hat Microsoft in SharePoint-Framework seit Version 1.15 die Möglichkeit eingeführt, die Registrierung und Zustimmung einer Anwendung mit mehreren Mandanten zu automatisieren.

Wenn Sie Back-End-APIs in SharePoint-Framework mithilfe des AadHttpClient -Objekts nutzen, sollten Sie auch in der package-solution.json-Datei der Lösung die Berechtigungen konfigurieren, die Ihre SPFx-Lösung benötigt. Hier sehen Sie ein Beispiel package-solution.json Datei aus einer Referenzlösung , die auf GitHub verfügbar ist.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "contoso-orders-client-side-solution",
    "id": "093eebef-9dbb-4b13-ba09-4da180bceb6d",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "developer": {
      "name": "Microsoft 365 PnP",
      "websiteUrl": "https://aka.ms/m365pnp",
      "privacyUrl": "",
      "termsOfUseUrl": "",
      "mpnId": "Undefined-1.13.0"
    },
    "webApiPermissionRequests": [
      {
        "resource": "PnP.Contoso.Orders",
        "scope": "Orders.FullControl"
      }
    ],
    "metadata": {
      "shortDescription": {
        "default": "PnP Contoso Orders sample"
      },
      "longDescription": {
        "default": "PnP Contoso Orders sample"
      },
      "screenshotPaths": [],
      "videoUrl": "",
      "categories": []
    }
  },
  "paths": {
    "zippedPackage": "solution/contoso-orders.sppkg"
  }
}

Im obigen Auszug wird im Abschnitt webApiPermissionRequests der Konfigurationsdatei deklariert, dass die Lösung den Berechtigungsbereich mit dem Namen Orders.FullControl benötigt, der von der Azure AD-Anwendung mit dem Namen PnP.Contoso.Orders bereitgestellt wird. In der Praxis stellt PnP.Contoso.Orders die mehrinstanzenfähige Back-End-Anwendung dar, die die SharePoint-Framework Lösung nutzen möchte und die in den Zielmandanten registriert werden sollte, während der Bereich Orders.FullControl die Berechtigung ist, die Mandantenadministratoren in ihren Mandanten erteilen sollten, bevor sie die Back-End-API nutzen können.

Hinweis

Sie können sich mit der Nutzung externer APIs in SharePoint-Framework vertraut machen, indem Sie die Artikel Herstellen einer Verbindung mit azure AD-geschützten APIs in SharePoint-Framework-Lösungen und Nutzen von mehrinstanzenfähigen Unternehmens-APIs, die mit Azure AD geschützt sind, in SharePoint-Framework lesen.

Eine Möglichkeit, wie bereits in diesem Artikel veranschaulicht, besteht darin, die URL für die Administratoreinwilligung für einen Mandantenadministrator eines Zielmandanten bereitzustellen und den manuellen Zustimmungsfluss zu befolgen. Eine weitere und bessere Option, die Sie seit SharePoint-Framework 1.15 haben, besteht darin, den WebApiPermissionRequests-Abschnitt der package-solution.json-Datei wie im folgenden Codeauszug anzureichern.

"webApiPermissionRequests": [
    {
    "appId": "a47390a4-f0cb-42ee-b3de-0a0af6e44f2d",
    "replyUrl": "https://aka.ms/m365pnp",
    "resource": "PnP.Contoso.Orders",
    "scope": "Orders.FullControl"
    }
],

Beachten Sie die neuen Eigenschaften appId und replyUrl, die jeweils die eindeutige ID der Anwendung für die Zustimmung auf dem Zielmandanten definieren, und die URL, an die der Benutzer umgeleitet werden soll, nachdem der Zustimmungsfluss abgeschlossen ist. Auch hier definieren die oben genannten Eigenschaften praktisch, was wir in der URL für die Administratoreinwilligung angegeben haben: {client-id} und {redirect-uri}.

Wenn ein Benutzer eine solche SharePoint-Framework Lösung im Mandanten-App-Katalog bereitstellt und die Berechtigungsanforderungen für das benutzerdefinierte Paket genehmigt, fordert SharePoint Online den Administratorbenutzer zunächst auf, die mehrinstanzenfähige Anwendung im Zielmandanten zu registrieren und den erforderlichen Berechtigungen zuzustimmen, und erlaubt dem Administratorbenutzer dann, die Berechtigungsanforderungen der SharePoint-Framework Lösung. Der Registrierungs-, Zustimmungs- und Genehmigungsflow wird vollständig in den SharePoint-Framework Lösungsbereitstellungsflow integriert, ohne dass die Administratoreinwilligungs-URLs für die Zielmandantenadministratoren freigegeben werden müssen.

Empfohlene Inhalte

Weitere Informationen zu diesem Thema finden Sie in den folgenden Dokumenten:

• Mandantschaften und Bereitstellungsbereiche von SharePoint- Add-Ins
• Zustimmungserfahrung für Anwendungen in Azure Active Directory
• Microsoft Identity Platform- und OAuth 2.0-Autorisierungscodeflow
• Herstellen einer Verbindung mit durch Azure AD gesicherten APIs in SharePoint-Framework-Lösungen.
• Nutzen von mehrinstanzenfähigen mit Azure AD gesicherten Unternehmens-APIs in SharePoint-Framework
• Erstellen eines ISV-Angebots für Microsoft Viva mit SPFx-ACEs und mehrinstanzenfähigen APIs, die in Azure gehostet werden
• Nutzen einer mehrinstanzenfähigen API innerhalb einer Gruppe von Microsoft Viva Connections Adaptive Card Extensions (ACEs)