Freigeben über

Aktualisieren von SharePoint-Anwendungen von Azure Access Control Service auf Azure Active Directory

  • Artikel

Mit dem SharePoint-Add-In-Modell können Sie Anwendungen in Azure Access Control Service (ACS) registrieren, um nur App-Zugriff auf Ihre SharePoint Online-Ressourcen zu erhalten. Je nachdem, wie Sie den reinen App-Zugriff konfigurieren, können Sie verschiedene Berechtigungsebenen von schreibgeschützt bis vollzugriff gewähren. In den Artikeln "Zugreifen auf SharePoint mithilfe eines Anwendungskontexts, auch als App-only bezeichnet" und "Gewähren des Zugriffs mithilfe von SharePoint-Apps" finden Sie eine schritt-für-Schritt-Anleitung zum Konfigurieren solcher Anwendungen.

Wichtig

Azure Access Control (ACS), ein Dienst von Azure Active Directory (Azure AD), wurde 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 Außerbetriebnahme von Azure Access Control für SharePoint-Add-Ins. 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.

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.

Das SharePoint-Add-In-Modell ist jedoch ein altes Modell, und es gibt neuere, modernere und vielseitigere Entwicklungsmodelle, wie z. B. die SharePoint-Framework. Darüber hinaus erhalten aus technischer Sicht die Berechtigungen, die einer reinen App-Anwendung gewährt werden, die beim SharePoint-Add-In-Modell registriert ist, Zugriff auf den gesamten Mandanten, und Sie können nicht selektiv die Zielwebsitesammlungen auswählen, für die Sie Berechtigungen erteilen möchten.

Als geeignete und sicherere Alternative können Sie sich darauf verlassen, eine Anwendung in Azure Active Directory (Azure AD) schließlich mithilfe des RSC-Modells (Resource Specific Consent) zu registrieren, das im Artikel "Grundlegendes zur ressourcenspezifischen Zustimmung für Microsoft Graph und SharePoint Online" behandelt wird, um nur bestimmte Websitesammlungen anstelle des gesamten Mandanten als Ziel festzulegen.

In diesem Artikel finden Sie ausführliche Informationen zur Funktionsweise des Azure AD-Anwendungsregistrierungsmodells und zum Upgrade auf das Azure AD-Modell einer bereits vorhandenen Anwendung, die mit dem SharePoint-Add-In-Modell in ACS registriert ist.

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.

Aktualisieren von SharePoint-Apps vom Azure Access Control-Dienst auf Azure Active Directory

Upgrade von ACS auf Azure AD

In diesem Abschnitt wird davon ausgegangen, dass Sie bereits eine reine App-Anwendung in SharePoint Online registriert haben, die das SharePoint-Add-In-Modell und ACS verwendet.

Die Anwendung, von der migriert werden soll

Im folgenden Screenshot sehen Sie eine Beispielkonfiguration für die Anwendung, die unter Verwendung der https://[your-tenant].sharepoint.com/_layouts/15/appregnew.aspx URL Ihres Zielmandanten in ACS registriert ist.

Die Seite Anwendungsregistrierung mit Formularfeldern zum Registrieren einer Anwendung in ACS. Die Felder sind: Client-ID, Geheimer Clientschlüssel, Titel, App-Domäne und Umleitungs-URI.

Der Anwendung wurde das Recht "FullControl" auf dem SharePoint Online-Zielmandanten durch die folgende Richtlinie gewährt, die über die https://[your-tenant]-admin.sharepoint.com/_layouts/15/appinv.aspx URL des SharePoint Online-Admin Central registriert wurde.

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

Im folgenden Screenshot sehen Sie die Benutzeroberflächeneinstellungen, die zum Erteilen der Vollzugriffsberechtigung für die Anwendung verwendet werden.

Die Seite Anwendungsbestand mit Formularfeldern zum Erteilen von Berechtigungen für die Anwendung in ACS. Die Felder sind: App-ID, eine Nachschlageschaltfläche zum Suchen nach der App nach App-ID, Informationsfelder zur Anwendung und die Berechtigungsanforderungs-XML der App, um die Berechtigungen zu definieren, die der Anwendung gewährt werden sollen.

Wir gehen auch davon aus, dass Sie auf eine SharePoint Online-Zielwebsitesammlung zugreifen, um die Elemente einer SharePoint-Bibliothek zu lesen und zu schreiben.

Im folgenden Codeauszug , der von einer .NET 6-Konsolenanwendung abgerufen wird, können Sie sehen, wie Sie mithilfe der PnP-Frameworkbibliothek, die als Open Source NuGet-Paket verfügbar ist, Zugriff auf den SharePoint Online-Zielmandanten erhalten.

// Use the PnP Framework AuthenticationManager class to get access to SharePoint Online
var am = new AuthenticationManager();

using (var context = am.GetACSAppOnlyContext(settings.SiteUrl, settings.ClientId, settings.ClientSecret))
{
    // Read the target library title
    var targetLibrary = context.Web.Lists.GetByTitle(settings.ListTitle);
    context.Load(targetLibrary, l => l.Title);
    await context.ExecuteQueryAsync();

    Console.WriteLine($"The title of the library is: \"{targetLibrary.Title}\"");

    // Add a new document to the target library
    using (var fileContent = new MemoryStream())
    {
        // Create some random text content
        var randomContent = Encoding.UTF8.GetBytes($"Some random content {DateTime.Now}");
        fileContent.Write(randomContent, 0, randomContent.Length);
        fileContent.Position = 0;

        // Upload the content as a random name file
        await targetLibrary.RootFolder.UploadFileAsync($"{Guid.NewGuid().ToString("n")}.txt", fileContent, true);
    }
}

Der Codeauszug liest den Titel einer Zielbibliothek und lädt dann eine neue Textdatei in die Zielbibliothek hoch, nur um eine hypothetische benutzerdefinierte Logik zu zeigen, die SharePoint Online nur per App nutzt.

Hinweis

Das Codebeispiel basiert auf der PnP-Frameworkbibliothek, um den Zugriff auf SharePoint Online zu erleichtern. Sie können jedoch letztendlich nur das Client Side Object Model (CSOM) von SharePoint Online verwenden. Der Zweck der PnP-Frameworkbibliothek besteht lediglich darin, Ihren Entwicklungsprozess zu beschleunigen und die Lebensqualität von Entwicklern zu verbessern.

Registrieren der neuen Anwendung in Azure AD

Da Sie über eine acs registrierte Anwendung verfügen, sehen wir uns an, wie Sie sie in eine moderne Azure AD-Anwendung transformieren.

Zunächst müssen Sie die Anwendung in Azure AD registrieren. Anschließend müssen Sie die Authentifizierung für die Anwendung konfigurieren. Schließlich müssen Sie die Berechtigungen konfigurieren, die Sie der Anwendung für den Zugriff auf SharePoint Online gewähren möchten.

Aus Sicherheitsgründen müssen Sie für den Zugriff auf SharePoint Online im reinen App-Modus über eine in Azure AD registrierte Anwendung auch ein X.509-Zertifikat für die Anwendungsauthentifizierung erstellen und konfigurieren.

In den folgenden Abschnitten erfahren Sie, wie Sie mit der Azure AD-Anwendungsregistrierung fortfahren, entweder mithilfe eines automatischen oder manuellen Ansatzes.

Automatisches Registrieren einer neuen Anwendung in Azure AD mit PnP PowerShell

Die schnellste und einfachste Möglichkeit, eine Azure AD-Anwendung für den Zugriff auf SharePoint Online im reinen App-Modus zu registrieren, ist die Verwendung von PnP PowerShell.

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.

Tatsächlich gibt es das Cmdlet Register-PnPAzureADApp , mit dem alle Registrierungsschritte mit nur einer Codezeile ausgeführt werden können. Im folgenden Codeauszug sehen Sie dazu ein PowerShell-Skript.

$app = Register-PnPAzureADApp -ApplicationName "Here the name of your application" -Store CurrentUser -Tenant yourtenant.onmicrosoft.com -Username "your-username" -Password (Read-Host -AsSecureString -Prompt "Enter Password") -CertificatePassword (Read-Host -AsSecureString -Prompt "Enter Certificate Password") -OutPath .\

$app.'AzureAppId/ClientId'
$app.'Certificate Thumbprint'

Das Cmdlet führt die folgenden Schritte aus:

  • registriert die Anwendung in Azure AD.
  • erstellt ein X.509-Zertifikat für die Anwendungsauthentifizierung.
  • importiert das Zertifikat mit seinem privaten Schlüssel in den Zertifikatspeicher "Aktueller Benutzer".
  • exportiert . PFX und . CER-Dateien des Zertifikats in dem durch das OutPath-Argument angegebenen Ordner
  • Lädt den öffentlichen Schlüssel des Zertifikats in Azure AD hoch, um das Zertifikat für die Anwendungsauthentifizierung zu konfigurieren.
  • konfiguriert einen vordefinierten Berechtigungssatz für die Anwendung in Azure AD.

Das obige Skript gibt die Client-ID der Anwendung und den Fingerabdruck des automatisch generierten Zertifikats aus.

Während des gesamten Prozesses wird ein Aufforderungsdialogfeld angezeigt, um der Anwendung die Berechtigungen zu erteilen. Im folgenden Screenshot sehen Sie die Berechtigungen, die der Anwendung vom Cmdlet automatisch gewährt werden.

Die Berechtigungen, die der Anwendung gewährt werden, die vom PnP PowerShell-Cmdlet registriert wurde. Die Anwendungsberechtigungen für Microsoft Graph lauten: Group.ReadWrite.All, User.ReadWrite.All. Die Anwendungsberechtigungen für SharePoint Online lauten: Sites.FullControl.All, User.ReadWrite.All.

Es gibt viele Optionen zum Konfigurieren des Verhaltens des Cmdlets Register-PnPAzureADApp . Sie können beispielsweise die Berechtigungen anpassen, die der Anwendung mit den Argumenten GraphApplicationPermissions und SharePointApplicationPermissions gewährt werden sollen.

Wenn Sie nicht an dem manuellen Prozess interessiert sind, können Sie zum Abschnitt "Verwenden von SharePoint Online im reinen App-Modus über eine in Azure AD registrierte Anwendung" wechseln, um zu erfahren, wie Sie SharePoint Online mit Ihrer neu registrierten Azure AD-Anwendung nutzen.

Manuelles Registrieren einer neuen Anwendung in Azure AD

Das PnP-PowerShell-Cmdlet zum automatischen Registrieren der Azure AD-Anwendung ist leistungsstark. Es gibt jedoch Szenarien, in denen Sie mehr Kontrolle über den Prozess wünschen. In solchen Szenarien können Sie eine neue Anwendung manuell in Azure AD registrieren. Um das zuvor gezeigte Ergebnis zu erzielen, müssen Sie einen Browser öffnen und zu https://aad.portal.azure.com/wechseln. Wählen Sie auf der linken Registerkarte Azure Active Directory aus, um das Blatt Azure AD zu aktivieren, und wählen Sie dann App-Registrierungen in der Liste der Abschnitte aus, die im linken Menü des Blatts Azure AD verfügbar sind. Im folgenden Screenshot sehen Sie die Benutzeroberfläche des Azure AD-Blatts in einem solchen Szenario.

Das Azure AD-Blatt mit dem abschnitt App-Registrierungen. Es gibt eine Liste der registrierten Anwendungen, und Sie können neue Anwendungen hinzufügen, indem Sie auf die Schaltfläche Neue Registrierung klicken.

Wählen Sie die Schaltfläche Neue Registrierung aus, um den manuellen Anmeldevorgang zu starten. Im folgenden Screenshot sehen Sie das Formular zum Registrieren einer neuen Anwendung.

Das Formular zum Registrieren einer neuen Anwendung. Die Felder, die ausgefüllt werden müssen, sind Name, Unterstützte Kontotypen (kann einzelinstanzenfähig, mehrinstanzenfähig, mehrinstanzenfähig und microsoft-persönliches Konto sein, nur Persönliches Microsoft-Konto), optionaler Umleitungs-URI für die Anwendung.

Sie müssen einen Namen für Ihre neue Anwendung angeben. Anschließend müssen Sie die Konten auswählen, die Sie unterstützen möchten. Folgende Optionen sind verfügbar:

  • Nur Konten in diesem Organisationsverzeichnis: Die Anwendung ist auf einen einzelnen Mandanten (d. h. einen einzelnen Mandanten) ausgerichtet.
  • Konten in einem beliebigen Organisationsverzeichnis: Die Anwendung ist auf jeden Mandanten (d. h. mehrinstanzenfähig) ausgerichtet.
  • Konten in einem beliebigen Organisationsverzeichnis und persönliche Microsoft-Konten: Die Anwendung ist mehrinstanzenfähig und unterstützt jedes persönliche Microsoft-Konto (z. B. Skype, Xbox usw.).
  • Nur persönliche Microsoft-Konten: Die Anwendung unterstützt jedes persönliche Microsoft-Konto (z. B. Skype, Xbox usw.).

Für das aktuelle Szenario können Sie entweder die Option "Einzelmandanten" oder "Mehrinstanzenfähig" auswählen. Lassen Sie uns für einen einzelnen Mandanten verwenden.

Wählen Sie die Schaltfläche Registrieren aus, und registrieren Sie die eigentliche Anwendung. Sie werden nun mit einer Seite mit nützlichen Informationen zur registrierten Anwendung aufgefordert. Sie können die Seite im folgenden Screenshot sehen.

Die Registrierte App-Informationsseite, einschließlich Name, Client-ID, Objekt-ID, Mandanten-ID usw.

Konfigurieren eines X.509-Zertifikats für die Anwendung

Sie können ein X.509-Zertifikat für Ihre Anwendung manuell erstellen, indem Sie ein beliebiges Tool verwenden. Die einfachste und schnellste Möglichkeit zum Erstellen eines X.509-Zertifikats für die Azure AD-Authentifizierung besteht jedoch darin, sich einmal mehr auf PnP PowerShell und insbesondere auf das Cmdlet New-PnPAzureCertificate zu verlassen. Hier folgt ein Beispiel für die PowerShell-Syntax zum Erstellen eines neuen X.509-Zertifikats.

$cert = New-PnPAzureCertificate -CommonName "my-certificate-common-name" -OutPfx .\my-certificate.pfx -OutCert .\my-certificate.cer -ValidYears 2 -CertificatePassword (Read-Host -AsSecureString -Prompt "Enter Certificate Password")

$cert.Thumbprint

Das obige Skript erstellt ein neues X.509-Zertifikat und speichert sein . PFX und . CER-Dateien in den angegebenen Dateipfaden. Anschließend wird der Fingerabdruck des generierten Zertifikats ausgegeben.

Hinweis

Falls Sie das generierte Zertifikat von Ihrem lokalen Entwicklungscomputer verwenden möchten, müssen Sie das generierte importieren. PFX-Datei (die den privaten Schlüssel enthält) in Ihrem lokalen Zertifikatspeicher. Das Verfahren kann je nach Betriebssystem Ihres Entwicklungscomputers variieren. Falls Sie den automatischen Prozess verwendet haben, wird das Zertifikat automatisch in Den Zertifikatspeicher "Aktueller Benutzer" importiert.

Jetzt können Sie das Zertifikat in Azure AD hochladen. Zurück zur Azure AD-Webseite mit den Anwendungsinformationen, und wählen Sie im Menü Zertifikate & Geheimnisse auf der linken Seite der Anwendungsseite aus. Wählen Sie auf der Seite die Registerkarte Zertifikate aus, und wählen Sie Zertifikat hochladen und hochladen aus. CER-Datei von dort aus. Im folgenden Screenshot sehen Sie, wie die Benutzeroberfläche des Azure AD-Portals beim Hochladen eines X.509-Zertifikats aussieht.

Die Schnittstelle zum Hochladen eines X.509-Zertifikats für eine Azure AD-Anwendung. Es gibt die Schaltfläche Zertifikat hochladen und den Uploadbereich auf der rechten Seite, in dem Sie angeben müssen. Cer-Zertifikatdateipfad und eine optionale Beschreibung für das Zertifikat. Klicken Sie auf die Schaltfläche Hinzufügen, um das Zertifikat hochzuladen.

Erteilen von Berechtigungen für die Anwendung

Jetzt können Sie der Anwendung Berechtigungen erteilen. Sie müssen lediglich im Menü API-Berechtigungen auf der linken Seite des Bildschirms auswählen und dann den Befehl Berechtigung hinzufügen auswählen. Im folgenden Screenshot sehen Sie, wie die Benutzeroberfläche aussieht.

Die Schnittstelle zum Hinzufügen von Berechtigungen zu einer Azure AD-Anwendung. Sie können auf die Schaltfläche

Sie werden von einem mehrstufigen Assistenten aufgefordert, über den Sie die hinzuzufügenden Berechtigungen auswählen können. Für den Zugriff auf SharePoint Online können Sie entweder Microsoft Graph oder SharePoint als Ziel-API auswählen. Da wir in diesem Artikel über das Konfigurieren einer Anwendung für den reinen App-Zugriff auf SharePoint sprechen, sollten Sie berechtigungen vom Typ Anwendungsberechtigungen hinzufügen. Schließlich müssen Sie die Berechtigungen auswählen, die Sie hinzufügen möchten.

Zum Zeitpunkt dieses Schreibens sind die verfügbaren Anwendungsberechtigungen für das aktuelle Szenario in der folgenden Liste dargestellt:

  • Microsoft Graph
  • SharePoint
    • Anwendungsberechtigungen:
      • Sites.FullControl.All: Vollzugriff auf alle Websitesammlungen
      • Sites.Manage.All: Lesen und Schreiben von Elementen und Listen in allen Websitesammlungen
      • Sites.Read.All: Lesen von Elementen in allen Websitesammlungen
      • Sites.ReadWrite.All: Lesen und Schreiben von Elementen in allen Websitesammlungen
      • Sites.Selected: Zugreifen auf ausgewählte Websitesammlungen (dies wird im Artikel "Grundlegendes zur ressourcenspezifischen Zustimmung für Microsoft Graph und SharePoint Online" behandelt)
      • TermStore.Read.All: Lesen verwalteter Metadaten
      • TermStore.ReadWrite.All: Verwaltete Metadaten lesen und schreiben
      • User.Read.All: Lesen von Benutzerprofilen
      • User.ReadWrite.All: Benutzerprofile mit Lese- und Schreibzugriff

Wie Sie sehen können, gibt es viele Optionen, die Sie auswählen können, und abhängig von Ihrem Ziel können Sie entweder Microsoft Graph nutzen, das immer die primäre Wahl sein sollte, oder die SharePoint Online-REST-APIs als Alternative. Sie können sogar beide innerhalb derselben Anwendung verwenden, je nachdem, was Sie tatsächlich tun müssen.

Um ein Beispiel zu erstellen, fügen wir die folgenden Berechtigungen hinzu:

  • Microsoft Graph
    • Anwendungsberechtigungen:
      • Sites.ReadWrite.All
  • SharePoint
    • Anwendungsberechtigungen:
      • Sites.ReadWrite.All

Nachdem Sie einer Anwendung in Azure AD Berechtigungen hinzugefügt haben, müssen Sie diese Berechtigungen möglicherweise explizit erteilen. In der Liste der Berechtigungen wird eine Spalte mit dem Namen Status angezeigt, und wenn der Wert "Nicht erteilt für [Name Ihres Mandanten]" mit einem orangefarbenen Ausrufezeichen lautet, müssen Sie die Schaltfläche Administratoreinwilligung für [Name Ihres Mandanten] erteilen auswählen, um die Zustimmung für diese Berechtigungen zu erteilen, wie im folgenden Screenshot dargestellt.

Die Schnittstelle zum Erteilen der Zustimmung für die Berechtigung einer Azure AD-Anwendung. Sie können auf

Wenn Sie die Zustimmung erteilen, wird der Wert der Spalte Status der Berechtigungen zu "Gewährt für [Name Ihres Mandanten]" und es wird ein grünes Häkchen angezeigt.

Verwenden von SharePoint Online im reinen App-Modus über eine bei Azure AD registrierte Anwendung

Sie können SharePoint Online jetzt über Ihre neu registrierte Azure AD-Anwendung nutzen.

Hinweis

Wenn Sie es lokal nutzen möchten, müssen Sie das generierte Zertifikat von Ihrem Entwicklungscomputer aus in Ihrem Zertifikatspeicher installieren. Wenn Sie die automatische Registrierung über PnP PowerShell verwendet haben, ist das Zertifikat bereits registriert. Wenn Sie den manuellen Prozess verwendet haben, müssen Sie das Zertifikat manuell in Ihren Zertifikatspeicher für den aktuellen Benutzer importieren.

Im folgenden Codeauszug , der von einer .NET 6-Konsolenanwendung abgerufen wird, können Sie sehen, wie Sie mithilfe der PnP-Frameworkbibliothek Zugriff auf den SharePoint Online-Zielmandanten erhalten.

// Use the PnP Framework AuthenticationManager class to get access to SharePoint Online
var certificate = X509CertificateUtility.LoadCertificate(StoreName.My, StoreLocation.CurrentUser, settings.CertificateThumbprint);
var am = AuthenticationManager.CreateWithCertificate(settings.ClientId, certificate, settings.TenantId);

using (var context = am.GetContext(settings.SiteUrl))
{
    // Read the target library title
    var targetLibrary = context.Web.Lists.GetByTitle(settings.ListTitle);
    context.Load(targetLibrary, l => l.Title);
    await context.ExecuteQueryAsync();

    Console.WriteLine($"The title of the library is: \"{targetLibrary.Title}\"");

    // Add a new document to the target library
    using (var fileContent = new MemoryStream())
    {
        // Create some random text content
        var randomContent = Encoding.UTF8.GetBytes($"Some random content {DateTime.Now}");
        fileContent.Write(randomContent, 0, randomContent.Length);
        fileContent.Position = 0;

        // Upload the content as a random name file
        await targetLibrary.RootFolder.UploadFileAsync($"{Guid.NewGuid().ToString("n")}.txt", fileContent, true);
    }
}

Wie im vorherigen Beispiel liest der Codeauszug den Titel einer Zielbibliothek und lädt dann eine neue Textdatei in die Zielbibliothek hoch. Wie Sie sehen können, sieht der Code fast wie das vorherige Beispiel aus. Im letzteren Beispiel verwenden Sie jedoch eine bei Azure AD registrierte Anwendung und verweisen auf ein X.509-Zertifikat für die Authentifizierung. Abgesehen davon verwenden Sie weiterhin die PnP-Frameworkbibliothek und die CSOM-Syntax für den Zugriff auf SharePoint Online. Dank dieses neuen Ansatzes verfügen Sie jetzt über ein höheres Maß an Anpassungen für Ihre Anwendungsberechtigungen, und Sie verwenden ACS nicht mehr.

Empfohlene Inhalte

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