了解 Microsoft Graph 和 SharePoint Online 的资源特定许可

2024-02-23

过去，在 Microsoft SharePoint（本地和联机）中，在 Azure 访问控制服务 (ACS) 中注册应用程序的功能仅限于特定网站集。通过此技术，你可以授权自定义应用程序以读取、写入、管理特定网站集，或者拥有对特定网站集的完全控制权限。

但是，ACS 不再是管理 SharePoint 的应用程序注册和安全性的最佳选择。应依赖以前Microsoft Entra (Azure Active Directory) 应用程序注册和 OAuth。默认情况下，在 Microsoft Entra 中注册应用程序时，可以配置 Microsoft Graph 应用程序权限，例如 Sites.Read.All、Sites.ReadWrite.All、Sites.Manage.All 或 Sites.FullControl.All，这些权限是面向目标租户中所有网站集的权限，正如权限范围名称中“All”一词所暗示的那样。

并非始终欢迎客户，尤其是拥有数千个网站集的企业客户，他们愿意拥有更精细的权限，能够选择应用程序应具有读取、写入、管理或完全控制权限的目标网站集。

重要

本文指的是所谓的 PnP 组件、示例和/或工具，它们是由提供支持的活动社区支持的开源资产。没有来自 Microsoft 的官方支持渠道的开放源代码工具支持的 SLA。但是，这些组件或示例使用 Microsoft 支持的现成 API 和 Microsoft 支持的功能。

如果愿意，可以watch以下视频，而不是阅读整篇文章，你仍然可以将其视为更详细的参考。

注意

阅读将 SharePoint 应用程序从 Azure 访问控制服务升级到Microsoft Entra一文，了解有关在 Microsoft Entra 中注册应用程序而不是依赖 Azure ACS 的详细信息。

使用资源特定同意 (RSC) 可以在 Microsoft Entra 中注册应用程序，并向其授予仅面向特定网站集的仅限应用程序的权限，就像以前使用 ACS 一样。在本文中，你将了解如何从此功能中获益。

若要使用 RSC 权限注册Microsoft Entra应用程序，只需在 Microsoft Entra 中注册常规应用程序。但是，配置应用程序的 API 权限时，而不是选择任何 站点。<的东西>。 Microsoft Graph 的所有应用程序权限都需要选择 Sites.Selected 应用程序权限，如以下屏幕截图所示。

通过 Microsoft Graph 为应用程序配置 Sites.Selected 应用程序权限时Microsoft Entra的 UI。

然后，租户管理员（最终仍可以是你）必须向 应用程序授予 Sites.Selected 应用程序权限。

此外，还具有 SharePoint Online 的 Sites.Selected 应用程序权限，以防您希望通过 REST API 使用 SharePoint Online，而不是通过 Microsoft Graph 使用 SharePoint Online。在以下屏幕截图中，可以看到 SharePoint Online 的 Sites.Selected 权限在 Microsoft Entra 中的外观。

通过 SharePoint Online 为应用程序配置 Sites.Selected 应用程序权限时Microsoft Entra的 UI。

授予对特定网站集的权限

分配并授予 Sites.Selected 应用程序权限后，应用程序仍无法访问任何目标网站集。为了能够访问任何目标站点，需要租户全局管理员或具有 Sites.FullControl.All 应用程序权限的应用程序来授予所选目标站点的显式权限。

通过 Microsoft Graph 授予权限

若要向所选目标网站授予权限，可以使用面向以下 URL 的 Microsoft 图形 API POST 请求：

https://graph.microsoft.com/v1.0/sites/{siteId}/permissions

其中{siteId} 是目标网站集的 Microsoft Graph 唯一 ID，格式如下：

contoso.sharepoint.com,5a58bb09-1fba-41c1-8125-69da264370a0,9f2ec1da-0be4-4a74-9254-973f0add78fd

HTTP POST 请求的正文应具有类似于以下代码摘录的结构。

{
  "roles": ["{role}"],
  "grantedToIdentities": [{
    "application": {
      "id": "{clientId}",
      "displayName": "{application-name}"
    }
  }]
}

其中 {role} 可以是以下任何值，也可以是以下任何值的数组：

read：提供读取项的元数据和内容的功能。
写入：提供读取和修改项的元数据和内容的功能。
manage：提供读取和修改项的元数据和内容以及管理网站的功能。
fullcontrol：提供对网站及其内容的完全控制。

{client-id} 属性是Microsoft Entra应用程序的实际客户端 ID，{application-name} 是应用程序的说明。

将从 Microsoft Graph 返回的响应将类似于以下 JSON 文件。

{
  "@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"
      }
    }
  ]
}

请注意，响应中的 id 属性表示用于标识自定义分配权限的唯一 ID。使用该 ID，还可以使用 REST 管理已分配的选定权限，并针对目标网站集 的权限/{permission-id} 终结点发出 GET、PATCH 或 DELETE 请求，其中 {permission-id} 表示权限的唯一 ID。

显然，你还可以选择使用 Microsoft Graph SDK 来管理权限，而不是依赖于低级别 HTTP 请求。

通过 PnP PowerShell 授予权限

若要向所选目标站点授予和管理权限，还可以使用一组 PnP PowerShell cmdlet：

Grant-PnPAzureAdAppSitePermission：添加给定Microsoft Entra应用程序注册的权限。
Get-PnPAzureAdAppSitePermission：返回网站Microsoft Entra应用权限。
Set-PnPAzureAdAppSitePermission：更新给定Microsoft Entra应用程序注册的权限。
Revoke-PnPAzureAdAppSitePermission：撤销给定应用的权限。

例如，如果要向所选站点的目标应用程序授予写入权限，可以使用以下 PowerShell 语法：

Grant-PnPAzureADAppSitePermission -AppId {client-id} -DisplayName {display-name} -Permissions <Read|Write|Manage|FullControl> -Site {site-object}

与 Microsoft Graph 终结点一样，{client-id} 参数是Microsoft Entra应用程序的客户端 ID，{display-name} 是应用程序的说明。 Permissions 参数可以是以下一个或多个值：

读取：提供读取项的元数据和内容的功能。
写入：提供读取和修改项的元数据和内容的功能。
管理：提供读取和修改项的元数据和内容以及管理网站的功能。
FullControl：提供对网站及其内容的完全控制。

{site-object} 值可以是使用 Get-PnPSite cmdlet 检索到的站点对象，也可以省略作为所选站点的目标，即你与 Connect-PnPOnline cmdlet 连接的站点。

在 PowerShell 控制台中，此类命令的输出将如下所示。

Id    : aTowaS50fG1zLnNwLmV4dHxlMDBiNWUzZi0yMzI1LTQ3MWQtOTljZi1iOGM5ZDlmNDU2N2FANmM5NDA3NWEtZGEwYS00YzZhLTg0MTEtYmFkZjY
        1MmU4YjUz
Roles : {fullcontrol}
Apps  : {AddInGuidanceRSC, e00b5e3f-2325-471d-99cf-b8c9d9f4567a}

请注意，cmdlet 返回授予的权限和权限对象的唯一 ID 。

如果要更新所选站点的权限分配，可以使用 PowerShell 语法，如下所示：

Set-PnPAzureADAppSitePermission -PermissionId {permission-id} -Permissions <Read|Write|Manage|FullControl>

其中 {permission-id} 参数是调用 Grant-PnPAzureADAppSitePermission cmdlet 时已返回的 ID。

如果要从所选网站撤销权限授予，可以使用 Revoke-PnPAzureADAppSitePermission cmdlet 和以下语法。

Revoke-PnPAzureADAppSitePermission -PermissionId {permission-id}

注意

在与本文关联的 samples 文件夹中，可以找到一个示例 PowerShell 脚本，该脚本演示如何将 PnP PowerShell cmdlet 用于 RSC。

使用目标网站集

使用 Sites.Selected 应用程序权限、Microsoft Graph 或 SharePoint Online 注册Microsoft Entra应用程序后，可以根据授予的权限开始使用所选网站集。

需要从 Microsoft Entra 请求仅限应用程序的访问令牌，然后开始使用所选网站集。如果你将目标定位到已向其应用程序授予权限的站点，你将成功实现它。如果面向任何其他网站集（尚未为其应用程序授予权限），则代码将失败，你将看到“拒绝访问”异常。

若要详细了解如何通过 SharePoint REST API 或 Microsoft Graph 使用仅限应用程序的令牌使用 SharePoint Online，可以阅读将 SharePoint 应用程序从 Azure 访问控制服务升级为Microsoft Entra一文中的通过 Azure AD 注册的应用程序在仅应用模式下使用 SharePoint Online 部分。

注意

在与本文关联的 samples 文件夹中，可以找到一个示例 .NET 6 控制台应用程序，该应用程序演示如何利用 RSC 模型使用 SharePoint Online 网站。

建议的内容

可以通过阅读以下文档来查找有关本文的其他信息：

通过