将 SharePoint 应用程序从 Azure 访问控制服务升级到 Azure Active Directory

2023-08-28

SharePoint 外接程序模型允许在 Azure 访问控制 Service (ACS) 中注册应用程序，以便获取对 SharePoint Online 资源的仅限应用的访问权限。根据配置仅应用访问权限的方式，可以授予从只读到完全控制的不同级别的权限。在文章“使用应用程序上下文访问 SharePoint，也称为仅限应用程序” 和 “使用 SharePoint App-Only 授予访问权限” 中，可以找到有关如何配置此类应用程序的分步指南。

重要

Azure 访问控制 (ACS)（Azure Active Directory (Azure AD) 的一项服务）已与 2018 年 11 月 7 日停用。此停用不会影响使用 https://accounts.accesscontrol.windows.net 主机名（不受此停用影响）的 SharePoint 加载项模型。有关详细信息，请参阅 Azure 访问控制停用 SharePoint 外接程序的影响。对于新租户，默认禁用使用仅 ACS 应用访问令牌的应用。建议使用新式且更安全的仅限 Azure AD 应用的模型。

重要

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

但是，SharePoint 外接程序模型是旧模型，有更新、更现代、更通用的开发模型，例如，SharePoint 框架。此外，从技术角度来看，向注册 SharePoint 外接程序模型的仅限应用的应用程序授予的权限将获取对整个租户的访问权限，并且无法有选择地选择要为其授予权限的目标网站集。

作为一种合适且更安全的替代方法，你可以依靠在 Azure Active Directory (Azure AD) 最终使用资源特定的同意 (RSC) 模型（本文“ 了解 Microsoft Graph 和 SharePoint Online 的资源特定同意”中介绍）来注册应用程序，以便仅面向特定的网站集，而不是整个租户。

在本文中，可以找到有关 Azure AD 应用程序注册模型工作原理的详细信息，以及如何使用 SharePoint 外接程序模型将已在 ACS 中注册的现有应用程序升级到 Azure AD 模型。

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

从 ACS 升级到 Azure AD

在本部分中，我们假设你已使用 SharePoint 外接程序模型和 ACS 在 SharePoint Online 中注册了一个仅限应用程序的应用程序。

要从中迁移的应用程序

在下面的屏幕截图中，可以看到使用 https://[your-tenant].sharepoint.com/_layouts/15/appregnew.aspx 目标租户的 URL 在 ACS 中注册的应用程序的示例配置。

“应用程序注册”页，其中包含用于在 ACS 中注册应用程序的表单字段。字段包括：客户端 ID、客户端密码、标题、应用域和重定向 URI。

通过以下策略向应用程序授予了目标 SharePoint Online 租户的 FullControl 权限，该策略是通过 https://[your-tenant]-admin.sharepoint.com/_layouts/15/appinv.aspx SharePoint Online 管理员 Central 的 URL 注册的。

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

在以下屏幕截图中，可以看到用于向应用程序授予完全控制权限的 UI 设置。

“应用程序清单”页，其中包含用于向 ACS 中的应用程序授予权限的窗体字段。字段包括：应用 ID、按应用 ID 搜索应用的查找按钮、有关应用程序的信息字段以及用于定义要授予应用程序的权限的应用权限请求 XML。

我们还假设您访问的是目标 SharePoint Online 网站集，以便读取和写入 SharePoint 库的项目。

在以下代码摘录中（从 .NET 6 控制台应用程序获取）中，可以看到如何使用 PnP 框架库（作为开放源代码 NuGet 包提供）获取对目标 SharePoint Online 租户的访问权限。

// 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);
    }
}

代码摘录读取目标库的标题，然后将新的文本文件上传到目标库，只是为了显示通过仅限应用程序使用 SharePoint Online 的假设自定义逻辑。

注意

代码示例依赖于 PnP 框架库，以便更轻松地访问 SharePoint Online。但是，您最终只能将 SharePoint Online 客户端对象模型 (CSOM) 。 PnP 框架库的目的是加快开发过程并提高开发人员的生活质量。

在 Azure AD 中注册新应用程序

由于你有一个已注册 ACS 的应用程序，因此让我们了解如何将其转换为新式 Azure AD 应用程序。

首先，需要在 Azure AD 中注册应用程序。然后，需要为应用程序配置身份验证。最后，需要配置要授予应用程序的权限才能访问 SharePoint Online。

出于安全原因，若要通过 Azure AD 注册的应用程序以仅应用模式访问 SharePoint Online，还需要创建并配置和 X.509 证书进行应用程序身份验证。

在以下部分中，你将了解如何使用自动方法或手动方法继续 Azure AD 应用程序注册。

使用 PnP PowerShell 在 Azure AD 中自动注册新应用程序

注意

PnP PowerShell 是一种开放源代码解决方案，其中包含为其提供支持的活动社区。没有用于 Microsoft 开放源代码工具支持的 SLA。

事实上， Register-PnPAzureADApp cmdlet 允许仅使用一行代码执行所有注册步骤。在以下代码摘录中，可以看到要执行此操作的 PowerShell 脚本。

$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'

cmdlet 执行以下步骤：

在 Azure AD 中注册应用程序
创建用于应用程序身份验证的 X.509 证书
将证书及其私钥导入当前用户证书存储区
导出。PFX 和。 OutPath 参数指定的文件夹中证书的 CER 文件
将证书的公钥上传到 Azure AD，以配置用于应用程序身份验证的证书
在 Azure AD 中为应用程序配置预定义的权限集

上述脚本输出应用程序的客户端 ID 和自动生成的证书的指纹。

在整个过程中，你将看到一个提示对话框，用于向应用程序授予权限。在以下屏幕截图中，可以看到 cmdlet 自动授予应用程序的权限。

授予由 PnP PowerShell cmdlet 注册的应用程序的权限。Microsoft Graph 的应用程序权限为：Group.ReadWrite.All、User.ReadWrite.All。SharePoint Online 的应用程序权限为：Sites.FullControl.All、User.ReadWrite.All。

有很多选项可用于配置 Register-PnPAzureADApp cmdlet 的行为。例如，可以使用 GraphApplicationPermissions 和 SharePointApplicationPermissions 参数自定义要授予应用程序的权限。

如果对手动过程不感兴趣，可以跳到 “通过 Azure AD 注册的应用程序在仅应用模式下使用 SharePoint Online” 部分，了解如何通过新注册的 Azure AD 应用程序使用 SharePoint Online。

在 Azure AD 中手动注册新应用程序

用于自动注册 Azure AD 应用程序的 PnP PowerShell cmdlet 非常强大。但是，在某些情况下，你需要对进程进行更多控制。在这种情况下，可以在 Azure AD 中手动注册新应用程序。若要实现前面演示的相同结果，需要打开浏览器，转到 https://aad.portal.azure.com/。选择左侧选项卡上的“Azure Active Directory”以激活“Azure AD”边栏选项卡，然后在“Azure AD”边栏选项卡左侧菜单中可用的部分列表中选择“应用注册”。在下面的屏幕截图中，可以看到在这种情况下的 Azure AD 边栏选项卡的用户界面。

“Azure AD”边栏选项卡，其中应用注册部分为高格。有一个已注册的应用程序列表，可以通过单击“新建注册”按钮添加新应用程序。

选择“ 新建注册 ”按钮以启动手动应用程序注册过程。在以下屏幕截图中，可以看到用于注册新应用程序的表单。

用于注册新应用程序的表单。要填写的字段是“名称”、“支持的帐户类型 (可以是单租户、多租户、多租户和 Microsoft 个人帐户，Microsoft 个人帐户仅) ，应用程序的可选重定向 URI。

需要为新应用程序提供名称。然后，需要选择要支持的帐户。可用选项包括：

仅此组织目录中的帐户：应用程序面向单个租户 (即单租户) 。
任何组织目录中的帐户：应用程序面向任何租户 (即多租户) 。
任何组织目录和个人 Microsoft 帐户中的帐户：该应用程序是多租户的，将支持任何个人 Microsoft 帐户 (（如 Skype、Xbox 等 ) ）。
仅限个人 Microsoft 帐户：应用程序支持任何个人 Microsoft 帐户 (，例如 Skype、Xbox 等 ) 。

对于当前方案，可以选择单租户或多租户选项。我们来了解一个单租户。

选择“ 注册 ”按钮并注册实际应用程序。现在，系统会提示你显示一个页面，其中包含一组有关已注册应用程序的有用信息。可以在以下屏幕截图中看到页面。

已注册的应用信息页，包括名称、客户端 ID、对象 ID、租户 ID 等。

为应用程序配置 X.509 证书

可以使用所选的任何工具为应用程序手动创建 X.509 证书。但是，为 Azure AD 身份验证创建 X.509 证书的最简单快捷方法是再次依赖 PnP PowerShell ，特别是 依赖于 New-PnPAzureCertificate cmdlet。下面是用于创建新的 X.509 证书的 PowerShell 语法示例。

$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

上述脚本创建新的 X.509 证书，并存储其。PFX 和。指定文件路径中的 CER 文件。然后，它输出生成的证书的指纹。

注意

如果要使用从本地开发计算机生成的证书，则必须导入生成的。PFX 文件 (，其中包括本地证书存储中) 私钥。该过程可能因开发计算机的操作系统而异。如果使用自动过程，证书将自动导入当前用户证书存储区。

现在，已准备好将证书上传到 Azure AD。返回显示应用程序信息的 Azure AD 网页，然后在应用程序页左侧的“证书 & 机密”菜单中选择。选择页面中的“ 证书 ”选项卡，然后在“ 上传证书 ”中选择并上传。来自该处的 CER 文件。在以下屏幕截图中，可以看到上传 X.509 证书时 Azure AD 门户 UI 的外观。

用于为 Azure AD 应用程序上传 X.509 证书的接口。右侧有“上传证书”按钮和上传面板，需要在其中指定。CER 证书文件路径和证书的可选说明。单击“添加”按钮以上传证书。

向应用程序授予权限

现在可以向应用程序授予权限。只需在屏幕左侧的“ API 权限 ”菜单中选择，然后选择“ 添加权限” 命令。在以下屏幕截图中，可以看到用户界面的外观。

用于向 Azure AD 应用程序添加权限的接口。可以单击“添加权限”按钮开始添加新权限。

多步骤向导将提示你，通过该向导可以选择要添加的权限。若要访问 SharePoint Online，可以选择 Microsoft Graph 或 SharePoint 作为目标 API。由于本文讨论的是配置应用程序以仅应用程序访问 SharePoint，因此应选择添加类型为 “应用程序权限”的权限。最后，必须选择要添加的权限。

撰写本文时，以下列表说明了当前方案的可用应用程序权限：

Microsoft Graph
- 应用程序权限：
  - Sites.FullControl.All：完全控制所有网站集
  - Sites.Manage.All：创建、编辑和删除所有网站集中的项和列表
  - Sites.Read.All：读取所有网站集中的项
  - Sites.ReadWrite.All：读取和写入所有网站集中的项
  - Sites.Select：访问所选网站集 (文章“了解 Microsoft Graph 和 SharePoint Online 的资源特定许可”)
SharePoint
- 应用程序权限：
  - Sites.FullControl.All：完全控制所有网站集
  - Sites.Manage.All：读取和写入所有网站集中的项和列表
  - Sites.Read.All：读取所有网站集中的项
  - Sites.ReadWrite.All：读取和写入所有网站集中的项
  - Sites.Selected：访问所选网站集 (文章“了解 Microsoft Graph 和 SharePoint Online 的资源特定许可”)
  - TermStore.Read.All：读取托管元数据
  - TermStore.ReadWrite.All：读取和写入托管元数据
  - User.Read.All：读取用户配置文件
  - User.ReadWrite.All：读取和写入用户配置文件

如你所看到的，有很多选项可供选择，根据你的目标，你可以使用 Microsoft Graph（应始终是主要选择），或者使用 SharePoint Online REST API 作为替代方法。你甚至可以在同一应用程序中同时使用这两者，具体取决于实际需要执行的操作。

为了举例说明，我们来添加以下权限：

Microsoft Graph
- 应用程序权限：
  - Sites.ReadWrite.All
SharePoint
- 应用程序权限：
  - Sites.ReadWrite.All

向 Azure AD 中的应用程序添加权限后，可能需要显式授予这些权限。在权限列表中，可以看到名为 “状态 ”的列，如果值为“未授予 [租户名称]”且带有橙色感叹号，则需要在“ 授予 [租户名称] 管理员同意 ”按钮上选择，以便授予对这些权限的同意，如以下屏幕截图所示。

用于向 Azure AD 应用程序授予许可的接口。可以单击“授予管理员同意...”按钮并授予对应用程序的权限。

通过授予同意，权限的“状态”列的值将变为“已授予 [租户名称]”，并且将有一个绿色检查标记。

通过 Azure AD 注册的应用程序在仅应用模式下使用 SharePoint Online

现在，你已准备好通过新注册的 Azure AD 应用程序使用 SharePoint Online。

注意

如果要从开发计算机在本地使用它，则必须在证书存储中安装生成的证书。如果通过 PnP PowerShell 使用了自动注册，则证书将已注册。如果使用了手动过程，则必须在当前用户证书存储中手动导入证书。

在以下代码摘录中（从 .NET 6 控制台应用程序获取）中，可以看到如何使用 PnP 框架库获取对目标 SharePoint Online 租户的访问权限。

// 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);
    }
}

与上一个示例中一样，代码摘录读取目标库的标题，然后将新的文本文件上传到目标库中。如你所看到的，代码看起来几乎与前一个示例类似。但是，在后一个示例中，你使用的是已注册 Azure AD 的应用程序，并且引用了用于身份验证的 X.509 证书。除此之外，你仍在使用 PnP 框架库和 CSOM 语法来访问 SharePoint Online。由于这种新方法，你现在对应用程序权限具有更高级别的自定义，并且不再使用 ACS。

建议的内容

有关本主题的其他信息，请参阅以下文档：

通过

将 SharePoint 应用程序从 Azure 访问控制 服务升级到 Azure Active Directory