Grundlegendes zur ressourcenspezifischen Zustimmung für Microsoft Graph und SharePoint Online
In der Vergangenheit gab es in Microsoft SharePoint sowohl lokal als auch online die Möglichkeit, Anwendungen in Azure Access Control Services (ACS) mit präzisen Berechtigungen nur für bestimmte Websitesammlungen zu registrieren. Mit diesem Verfahren konnten Sie eine benutzerdefinierte Anwendung autorisieren, um bestimmte Websitesammlungen mit Nur-Anwendungsberechtigungen zu lesen, zu schreiben, zu verwalten oder voll zu steuern.
ACS ist jedoch nicht mehr die beste Option zum Verwalten der Anwendungsregistrierung und -sicherheit für SharePoint. Sie sollten sich auf Microsoft Entra -Anwendungsregistrierung (früher Azure Active Directory) und OAuth verlassen. Wenn Sie eine Anwendung in Microsoft Entra registrieren, können Sie standardmäßig Microsoft Graph-Anwendungsberechtigungen wie Sites.Read.All, Sites.ReadWrite.All, Sites.Manage.All oder Sites.FullControl.All konfigurieren. Dies sind Berechtigungen, die auf alle Websitesammlungen im Zielmandanten ausgerichtet sind, wie das Wort Alle im Namen der Berechtigungsbereiche impliziert.
Das Ziel "Alle " wird nicht immer von Kunden begrüßt, insbesondere von Unternehmenskunden mit Tausenden von Websitesammlungen, die über präzisere Berechtigungen verfügen und die Zielwebsitesammlungen auswählen können, in denen die Anwendung Lese-, Schreib-, Verwaltungs- oder Vollzugriffsberechtigungen haben soll.
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 von Microsoft unterstützte sofort einsatzbereite 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.
Hinweis
Weitere Informationen zum Registrieren von Anwendungen in Microsoft Entra anstelle von Azure ACS finden Sie im Artikel Upgraden von SharePoint-Anwendungen von Azure Access Control Service auf Microsoft Entra.
Mit der ressourcenspezifischen Zustimmung (Resource Specific Consent, RSC) können Sie Anwendungen in Microsoft Entra registrieren und ihnen Anwendungsberechtigungen erteilen, die nur auf bestimmte Websitesammlungen abzielen können, wie Sie es bei ACS gewohnt haben. In diesem Artikel erfahren Sie, wie Sie von dieser Funktion profitieren können.
Registrieren einer Anwendung mit ressourcenspezifischen Zustimmungsberechtigungen
Um eine Microsoft Entra-Anwendung mit RSC-Berechtigung zu registrieren, müssen Sie lediglich eine reguläre Anwendung in Microsoft Entra registrieren. Wenn Sie jedoch die API-Berechtigungen der Anwendung konfigurieren, wählen Sie keine der Websites aus.<etwas>. Für alle Anwendungsberechtigungen für Microsoft Graph müssen Sie die Berechtigung Sites.Ausgewählte Anwendung auswählen, wie im folgenden Screenshot dargestellt.
Dann muss ein Mandantenadministrator, der letztendlich immer noch Sie sein kann, der Anwendung Sites.Selected die Berechtigung für die Anwendung erteilen.
Es gibt auch eine Anwendungsberechtigung Sites.Selected für SharePoint Online, falls Sie SharePoint Online über REST-APIs nutzen möchten, anstatt SharePoint Online über Microsoft Graph zu nutzen. Im folgenden Screenshot sehen Sie, wie die Berechtigung Sites.Selected für SharePoint Online in Microsoft Entra aussieht.
Erteilen von Berechtigungen für eine bestimmte Websitesammlung
Nachdem die Anwendungsberechtigung Sites.Selected zugewiesen und erteilt wurde, kann die Anwendung immer noch nicht auf eine Zielwebsitesammlung zugreifen. Um auf eine beliebige Zielwebsite zugreifen zu können, benötigen Sie einen globalen Mandantenadministrator oder eine Anwendung mit der Anwendungsberechtigung Sites.FullControl.All , um explizite Berechtigungen für die ausgewählten Zielwebsites zu erteilen.
Erteilen von Berechtigungen über Microsoft Graph
Um den ausgewählten Zielwebsites Berechtigungen zu erteilen, können Sie eine Microsoft Graph-API POST-Anforderung verwenden, die auf die folgende URL ausgerichtet ist:
https://graph.microsoft.com/v1.0/sites/{siteId}/permissions
Dabei ist {siteId} die eindeutige Microsoft Graph-ID der Zielwebsitesammlung mit einem Format wie dem folgenden:
contoso.sharepoint.com,5a58bb09-1fba-41c1-8125-69da264370a0,9f2ec1da-0be4-4a74-9254-973f0add78fd
Der Text der HTTP POST-Anforderung sollte eine Struktur wie der folgende Codeauszug aufweisen.
{
"roles": ["{role}"],
"grantedToIdentities": [{
"application": {
"id": "{clientId}",
"displayName": "{application-name}"
}
}]
}
Dabei kann {role} einen der folgenden Werte oder ein Array mit einem der folgenden Werte sein:
- read: bietet die Möglichkeit, die Metadaten und inhalte des Elements zu lesen.
- write: bietet die Möglichkeit, die Metadaten und Inhalte des Elements zu lesen und zu ändern.
- manage: bietet die Möglichkeit, die Metadaten und Inhalte des Elements zu lesen und zu ändern und die Website zu verwalten.
- fullcontrol: bietet vollständige Kontrolle über die Website und ihren Inhalt.
Das Attribut {client-id} ist die tatsächliche Client-ID der Microsoft Entra Anwendung, und {application-name} ist eine Beschreibung für die Anwendung.
Die Antwort, die Sie von Microsoft Graph erhalten, sieht wie die folgende JSON-Datei aus.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('contoso.sharepoint.com,5a58bb09-1fba-41c1-8125-69da264370a0,9f2ec1da-0be4-4a74-9254-973f0add78fd')/permissions/$entity",
"id": "aTowaS50fG1zLnNwLmV4dHxlMDBiNWUzZi0yMzI1LTQ3MWQtOTljZi1iOGM5ZDlmNDU2N2FANmM5NDA3NWEtZGEwYS00YzZhLTg0MTEtYmFkZjY1MmU4YjUz",
"roles": [
"write"
],
"grantedToIdentitiesV2": [
{
"application": {
"displayName": "AddInGuidanceRSC",
"id": "e00b5e3f-2325-471d-99cf-b8c9d9f4567a"
}
}
],
"grantedToIdentities": [
{
"application": {
"displayName": "AddInGuidanceRSC",
"id": "e00b5e3f-2325-471d-99cf-b8c9d9f4567a"
}
}
]
}
Beachten Sie, dass die id-Eigenschaft in der Antwort die eindeutige ID darstellt, um die benutzerdefinierte zugewiesene Berechtigung zu identifizieren. Mithilfe dieser ID können Sie auch bereits zugewiesene ausgewählte Berechtigungen mithilfe von REST verwalten und GET-, PATCH- oder DELETE-Anforderungen für den Permissions/{permission-id}- Endpunkt der Zielwebsitesammlung senden, wobei {permission-id} die eindeutige ID der Berechtigung darstellt.
Natürlich können Sie auch das Microsoft Graph SDK verwenden, um die Berechtigungen zu verwalten, anstatt sich auf HTTP-Anforderungen auf niedriger Ebene zu verlassen.
Erteilen von Berechtigungen über PnP PowerShell
Zum Erteilen und Verwalten von Berechtigungen für die ausgewählten Zielwebsites können Sie auch eine Reihe von PnP-PowerShell-Cmdlets verwenden:
- Grant-PnPAzureAdAppSitePermission: Fügt Berechtigungen für eine bestimmte Microsoft Entra Anwendungsregistrierung hinzu.
- Get-PnPAzureAdAppSitePermission: Gibt Microsoft Entra App-Berechtigungen für eine Website zurück.
- Set-PnPAzureAdAppSitePermission: Aktualisiert die Berechtigungen für eine bestimmte Microsoft Entra Anwendungsregistrierung.
- Revoke-PnPAzureAdAppSitePermission: Widerruft Berechtigungen für eine bestimmte App.
Wenn Sie beispielsweise einer Zielanwendung für eine ausgewählte Website Schreibberechtigungen erteilen möchten, können Sie die folgende PowerShell-Syntax verwenden:
Grant-PnPAzureADAppSitePermission -AppId {client-id} -DisplayName {display-name} -Permissions <Read|Write|Manage|FullControl> -Site {site-object}
Wie beim Microsoft Graph-Endpunkt ist das {client-id}-Argument die Client-ID der Microsoft Entra Anwendung, und {display-name} ist eine Beschreibung für die Anwendung. Das Berechtigungsargument kann mindestens einer der folgenden Werte sein:
- Lesen: bietet die Möglichkeit, die Metadaten und inhalte des Elements zu lesen.
- Schreiben: Bietet die Möglichkeit, die Metadaten und Inhalte des Elements zu lesen und zu ändern.
- Verwalten: Bietet die Möglichkeit, die Metadaten und Inhalte des Elements zu lesen und zu ändern und die Website zu verwalten.
- FullControl: bietet vollständige Kontrolle über die Website und deren Inhalt.
Der Wert {site-object} kann ein Websiteobjekt sein, das mit dem Cmdlet Get-PnPSite abgerufen wurde, oder es kann weggelassen werden, um die ausgewählte Website als Ziel zu verwenden, mit der Sie mit dem Cmdlet Connect-PnPOnline verbunden sind.
Die Ausgabe eines solchen Befehls sieht in der PowerShell-Konsole wie folgt aus.
Id : aTowaS50fG1zLnNwLmV4dHxlMDBiNWUzZi0yMzI1LTQ3MWQtOTljZi1iOGM5ZDlmNDU2N2FANmM5NDA3NWEtZGEwYS00YzZhLTg0MTEtYmFkZjY
1MmU4YjUz
Roles : {fullcontrol}
Apps : {AddInGuidanceRSC, e00b5e3f-2325-471d-99cf-b8c9d9f4567a}
Beachten Sie, dass das Cmdlet die gewährte Berechtigung und die eindeutige ID des Berechtigungsobjekts zurückgibt.
Falls Sie eine Berechtigungszuweisung für eine ausgewählte Website aktualisieren möchten, können Sie eine PowerShell-Syntax wie die folgende verwenden:
Set-PnPAzureADAppSitePermission -PermissionId {permission-id} -Permissions <Read|Write|Manage|FullControl>
Dabei ist das Argument {permission-id} die ID , die Sie beim Aufrufen des Cmdlets Grant-PnPAzureADAppSitePermission erhalten haben.
Wenn Sie eine Berechtigungsgewährung für eine ausgewählte Website widerrufen möchten, können Sie das Cmdlet Revoke-PnPAzureADAppSitePermission mit der folgenden Syntax verwenden.
Revoke-PnPAzureADAppSitePermission -PermissionId {permission-id}
Hinweis
Im Diesem Artikel zugeordneten Ordner samples finden Sie ein PowerShell-Beispielskript , das die Verwendung der PnP PowerShell-Cmdlets für RSC veranschaulicht.
Verwenden der Zielwebsitesammlung
Nachdem Sie eine Microsoft Entra Anwendung mit der Berechtigung Websites.Ausgewählte Anwendung registriert haben, entweder mit Microsoft Graph, mit SharePoint Online oder mit beiden, können Sie dann mit der Nutzung der ausgewählten Websitesammlungen gemäß den erteilten Berechtigungen beginnen.
Sie müssen ein reines Anwendungszugriffstoken von Microsoft Entra anfordern und mit der Nutzung der ausgewählten Websitesammlungen beginnen. Wenn Sie eine Website als Ziel verwenden, für die Ihrer Anwendung Berechtigungen erteilt wurden, erreichen Sie dies erfolgreich. Wenn Sie eine andere Websitesammlung als Ziel verwenden, für die Ihrer Anwendung keine Berechtigungen erteilt wurden, schlägt Ihr Code fehl, und Es wird die Ausnahme "Zugriff verweigert" angezeigt.
Wenn Sie mehr darüber erfahren möchten, wie Sie SharePoint Online über die SharePoint-REST-API oder über Microsoft Graph mithilfe eines reinen Anwendungstokens nutzen können, lesen Sie den Abschnitt Verwenden von SharePoint Online im reinen App-Modus über eine registrierte Azure AD-Anwendung im Artikel Upgraden von SharePoint-Anwendungen von Azure Access Control Service auf Microsoft Entra.
Hinweis
Im diesem Artikel zugeordneten Ordner samples finden Sie eine .NET 6-Beispiel-Konsolenanwendung , die veranschaulicht, wie SharePoint Online-Websites mithilfe des RSC-Modells genutzt werden.
Empfohlene Inhalte
Weitere Informationen zu diesem Artikel finden Sie in den folgenden Dokumenten: