Gewähren des Zugriffs mithilfe von SharePoint App-Only

SharePoint App-Only ist das ältere, aber immer noch sehr relevante Modell zum Einrichten von App-Prinzipalen. Dieses Modell funktioniert sowohl für SharePoint Online als auch für sharePoint lokal (2013/2016/2019/abonnementedition) und ist ideal, um Ihre Anwendungen für die Migration von sharePoint lokal zu SharePoint Online vorzubereiten. Die folgenden Schritte zeigen, wie Sie einen App-Prinzipal mit Vollzugriffsberechtigungen für Mandanten einrichten, aber Sie können mit diesem Ansatz auch nur Leseberechtigungen erteilen.

Wichtig

Die Verwendung von Azure ACS (Access Control Services) für SharePoint Online wurde am 27. November 2023 eingestellt. Weitere Informationen finden Sie in der Ankündigung zur vollständigen Einstellung. Die Verwendung von Azure ACS außerhalb des SharePoint-Kontexts wurde bereits am 7. November 2018 eingestellt und endet jetzt.

Die Einstellung bedeutet, dass das Feature keine neuen Investitionen erhält, aber weiterhin unterstützt wird. Ende der Lebensdauer bedeutet, dass das Feature nicht mehr zur Verfügung steht.

Für neue Mandanten sind Apps, die nur ein ACS-App-Zugriffstoken verwenden, standardmäßig deaktiviert. Es wird empfohlen, das reine Azure AD-App-Modell zu verwenden, das modern und sicherer ist. Sie können das Verhalten jedoch ändern, indem Sie "set-spotenant -DisableCustomAppAuthentication $false" ausführen (erfordert die neueste SharePoint-Administrator-PowerShell).

Einrichten eines reinen App-Prinzipals mit Mandantenberechtigungen

Hinweis

Der Websitesammlungsadministrator kann das Add-In standardmäßig nicht bei Azure ACS in AppRegNew.aspx registrieren, es sei denn, der SharePoint-Mandantenadministrator hat dies explizit zugelassen. Weitere Informationen finden Sie unter Set-SPOTenant.

Navigieren Sie zu einer Website in Ihrem Mandanten (z. B. https://contoso.sharepoint.com), und rufen Sie dann die Seite appregnew.aspx auf (z. B. https://contoso.sharepoint.com/_layouts/15/appregnew.aspx). Klicken Sie auf dieser Seite auf die Schaltfläche Generieren, um eine Client-ID und einen geheimen Clientschlüssel zu generieren und die restlichen Informationen auszufüllen, wie im folgenden Screenshot gezeigt.

Wichtig

Speichern Sie die abgerufenen Informationen (Client-ID und geheimer Clientschlüssel), da Sie diese im nächsten Schritt benötigen!

Der nächste Schritt besteht darin, dem neu erstellten Prinzipal Berechtigungen zu erteilen. Da wir mandantenbezogene Berechtigungen gewähren, kann diese Gewährung nur über die Seite appinv.aspx auf der Mandantenverwaltungswebsite erfolgen. Sie können diese Website über https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspxerreichen. Nachdem die Seite geladen wurde, fügen Sie Ihre Client-ID hinzu, und suchen Sie nach dem erstellten Prinzipal:

Um Berechtigungen zu erteilen, müssen Sie die Berechtigungs-XML angeben, die die erforderlichen Berechtigungen beschreibt. Da diese Anwendung in der Lage sein muss, auf alle Websites zuzugreifen und auch die Suche mit Nur-App verwendet, benötigt sie die folgenden Berechtigungen:

<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
</AppPermissionRequests>

Wenn Sie auf Erstellen klicken, wird ein Zustimmungsdialogfeld angezeigt. Klicken Sie auf Vertrauen, um die Berechtigungen zu erteilen:

Wichtig

Schützen Sie die erstellte Kombination aus Client-ID und Geheimnis genauso wie Ihr Administratorkonto. Mit dieser Client-ID/dem geheimen Schlüssel kann man alle Daten in Ihrer SharePoint Online-Umgebung lesen/aktualisieren!

Nachdem die Vorbereitungsarbeiten abgeschlossen sind, fahren wir mit dem nächsten Kapitel fort, das zeigt, wie Sie den erstellten App-Prinzipal über die Kombination aus Client-ID und Geheimnis verwenden können.

Verwenden dieses Prinzipals mit PnP PowerShell

Wenn Sie die generierte app-only-Registrierung mit PnP PowerShell verwenden möchten, können Sie dazu eine Verbindung mit Ihrer lokalen SharePoint- oder Online-Umgebung herstellen:

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/demo -ClientId [Your Client ID] -ClientSecret "[Your Client Secret]"

Hinweis

PnP PowerShell ist eine Open Source-Lösung mit aktiver Community, die Support dafür bietet. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Verwenden dieses Prinzipals in Ihrer Anwendung mithilfe der PnP Framework-Bibliothek

In einem ersten Schritt fügen Sie das NuGet-Paket der PnP Framework-Bibliothek hinzu: https://www.nuget.org/packages/PnP.Framework. Anschließend können Sie das folgende Codekonstrukt verwenden:

string siteUrl = "https://contoso.sharepoint.com/sites/demo";
using (var cc = new AuthenticationManager().GetACSAppOnlyContext(siteUrl, "[Your Client ID]", "[Your Client Secret]"))
{
    cc.Load(cc.Web, p => p.Title);
    cc.ExecuteQuery();
    Console.WriteLine(cc.Web.Title);
};

Verwenden dieses Prinzipals in Ihrer Anwendung ohne Verwendung der PnP Framework-Bibliothek

Nachdem der Prinzipal erstellt und zugestimmt wurde, können Sie die ID und das Geheimnis des Prinzipals verwenden, um einen Zugriff anzufordern. Die TokenHelper.cs-Klasse verwendet die ID und das Geheimnis aus der Konfigurationsdatei der Anwendung.

using Microsoft.SharePoint.Client;
using System;

namespace AzureACSAuth
{
    class Program
    {
        static void Main(string[] args)
        {
            string siteUrl = "https://contoso.sharepoint.com/sites/demo";

            //Get the realm for the URL
            string realm = TokenHelper.GetRealmFromTargetUrl(new Uri(siteUrl));

            //Get the access token for the URL.  
            string accessToken = TokenHelper.GetAppOnlyAccessToken(TokenHelper.SharePointPrincipal, new Uri(siteUrl).Authority, realm).AccessToken;

            //Create a client context object based on the retrieved access token
            using (ClientContext cc = TokenHelper.GetClientContextWithAccessToken(siteUrl, accessToken))
            {
                cc.Load(cc.Web, p => p.Title);
                cc.ExecuteQuery();
                Console.WriteLine(cc.Web.Title);
            }
        }
    }
}

Ein Beispiel app.config sieht wie folgt aus:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <!-- Use AppRegNew.aspx and AppInv.aspx to register client id with secret -->
    <add key="ClientId" value="[Your Client ID]" />
    <add key="ClientSecret" value="[Your Client Secret]" />
  </appSettings>
</configuration>

Hinweis

Sie können die TokenHelper.cs-Klasse ganz einfach in Ihr Projekt einfügen, indem Sie Ihrer Projektmappe das NuGet-Paket AppForSharePointOnlineWebToolkit hinzufügen.