创建 SharePoint 高信任加载项

项目
04/08/2023

高信任加载项是提供程序托管的 SharePoint 加载项，它使用数字证书在远程 Web 应用程序和 SharePoint 之间建立信任。 "高信任"与"完全信任"不同。高信加载项仍必须请求加载项权限。加载项之所以被视为“高信任”是因为信任它使用加载项所需的任何用户标识，并且因为为加载项负责创建它传递到 SharePoint 的访问令牌的用户部分。

高信任 SharePoint 加载项主要用于本地环境。高信任加载项无法安装到 Microsoft SharePoint Online，但远程组件通常可以本地安装在企业防火墙中。因此，SharePoint 加载项的实例特定于每个公司。

高信任加载项使用证书（而不是上下文令牌）建立信任。 (一个提供程序托管的外接程序，它使用 Microsoft Azure 访问控制服务 (ACS) ，因为需要修改其信任代理才能用作高信任应用。) ）高信任外接程序需要 SharePoint 场和托管远程 Web 应用程序的服务器上的某些配置。

在 SharePoint 中，服务器间安全令牌服务 (STS) 为服务器间身份验证提供访问令牌。服务器间 STS 支持通过临时访问令牌访问其他应用程序服务（如 Exchange、Lync 和 SharePoint 加载项）。使用 Windows PowerShell cmdlet 和证书可在应用程序服务之间建立信任关系（例如，在 SharePoint 和远程加载项之间建立信任）。

注意

服务器间 STS 不适用于用户身份验证。因此，在管理中心中用户登录页的“身份验证提供程序”部分，或 SharePoint 的人员选取器中不会列出服务器间 STS。

本文介绍如何创建高信任加载项，并提供了通过选择 F5 在 Visual Studio 中运行该加载项的安装说明。你将了解：

配置加载项以用作高信任加载项。
配置 SharePoint 以使用高信任外接程序。
创建基本高信任加载项。

配置测试、暂存或生产环境的操作稍有不同，相关信息请参阅主题打包和发布高信任 SharePoint 加载项。

先决条件

要执行本文中的步骤，请确保具备以下内容：

本地 SharePoint 开发环境。有关设置说明，请参阅设置 SharePoint 加载项的本地开发环境。特别是，确保你已完成在 SharePoint 中配置服务以使用服务器间加载项部分中的步骤。
创建提供程序托管的 SharePoint 加载项的经验。请参阅开始创建提供程序托管的 SharePoint 加载项。
远程安装的或在已安装 SharePoint 的计算机上安装的 Visual Studio。
Visual Studio Microsoft Office 开发人员工具。
熟悉数字证书：它们是什么以及如何使用它们。请参阅：
- 数字证书
- 使用证书

获取证书或创建公用和专用测试证书

需要适用于高信任加载项的远程 Web 应用程序的 X.509 数字证书。若要全面测试 SharePoint 加载项，需要域颁发的证书或由证书颁发机构颁发的商业证书。但是，在调试的初始阶段，可以使用自签名证书。

以下过程介绍了如何使用 IIS 来创建和导出测试证书。在下面的使用域颁发的证书或商业证书完成调试部分中，你将了解如何将自签名证书替换为域颁发的证书或商业证书。

此外，还可以使用 MakeCert 测试程序生成 X.509 证书。有关如何使用 MakeCert 的详细信息，请参阅使用验证码对代码进行签名和检查。

首先将创建测试 .pfx 证书文件，然后创建相应的测试 .cer 文件。 .pfx 证书包含由远程 Web 应用程序使用的私钥以将其通信签名到 SharePoint。 .cer 包含 SharePoint 使用的公钥来解密消息，验证它们是否来自远程 Web 应用程序以及验证远程 Web 应用程序是否具有 SharePoint 信任的令牌颁发者提供的的访问令牌。有关 .pfx 文件和 .cer 文件的详细信息，请参阅软件发布者证书。

创建自签名测试 .pfx 证书文件

当你在 Visual Studio 中调试高信任 SharePoint 加载项时，远程 Web 应用程序将在安装了 Visual Studio 的计算机上的 IIS Express 中托管。因此，远程 Web 应用程序计算机不具有可以在其中创建证书的 IIS 管理器。出于此原因，可以在 SharePoint 测试服务器上使用 IIS 创建证书。

在 IIS 管理器中，选择左侧树视图中的“ServerName”节点。

选择“服务器证书”图标，如下图所示。

IIS 中的“服务器证书”选项

从右侧链接集中选择“创建自签名证书”链接。

“创建自签名证书”链接

将证书命名为 HighTrustSampleCert，然后选择“确定”。
右键单击证书，然后选择“导出”。

导出测试证书

在 Windows 或命令行中，创建名为 C:\Certs 的文件夹。
回到 IIS 管理器中，将文件导出到 C:\Certs 并为它提供密码。本示例中，密码为 password。
如果测试 SharePoint 安装不在运行 Visual Studio 的同一台计算机上，请在 Visual Studio 计算机上创建一个 C：\Certs 文件夹，并将 HighTrustSampleCert.pfx 文件移到其中。当你在 Visual Studio 中调试时，该计算机将是在其上运行远程 Web 应用程序的计算机。

创建一个相应的 .cer 文件

在 SharePoint 服务器上，确保以下 IIS 加载项池的加载项池标识具有对 C:\Certs 文件夹的读取权限：

SecurityTokenServiceApplicationPool
可服务于 IIS 网站的加载项池，该网站托管用于测试 SharePoint 网站的父 SharePoint Web 应用程序。对于 SharePoint - 80 IIS 网站，该池称为 OServerPortalAppPool。

在 IIS 管理器中，选择左侧树视图中的“ServerName”节点。
双击“服务器证书”。
在“服务器证书”视图中，双击 HighTrustSampleCert 以显示证书详细信息。
在“详细信息”选项卡上，选择“复制到文件”以启动“证书导出向导”，然后选择“下一步”。
使用默认值“不，不要导出私钥”，然后选择“下一步”。
使用默认值，然后选择“下一步”。
选择“浏览”，浏览到 C:\Certs，将证书命名为 HighTrustSampleCert，然后选择“保存”。将证书另存为 .cer 文件。
选择“下一步”。
选择“完成”。

配置 SharePoint 以使用证书并配置对加载项的信任

此部分中创建的 Windows PowerShell 脚本旨在支持在 Visual Studio 中使用 F5。它将不会正确配置暂存或生产 SharePoint 安装。有关配置生产 SharePoint 以使用证书的说明，请参阅打包和发布高信任 SharePoint 加载项。

重要

请仔细检查是否已完成在 SharePoint 中配置服务以供服务器间加载项使用中的步骤（本文将它们列为先决条件）。如果未完成，必须立即进行配置，然后才能继续操作。

配置 SharePoint 的具体步骤

在文本编辑器或 Windows PowerShell 编辑器中，启动一个新文件并向其添加下面的行以创建证书对象。

  $publicCertPath = "C:\Certs\HighTrustSampleCert.cer"
  $certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)

添加下面的行以确保 SharePoint 将证书视为根证书颁发机构。

  New-SPTrustedRootAuthority -Name "HighTrustSampleCert" -Certificate $certificate

添加以下行来获取授权领域的 ID。

  $realm = Get-SPAuthenticationRealm

远程 Web 应用程序将使用访问令牌获取对 SharePoint 数据的访问权限。该访问令牌必须是由 SharePoint 信任的令牌颁发者颁发的。在高信任 SharePoint 加载项中，证书是令牌颁发者。添加以下行以 SharePoint 所需的格式构造颁发者 ID： _specific_issuer_GUID_@_realm_GUID_。

  $specificIssuerId = "11111111-1111-1111-1111-111111111111"
  $fullIssuerIdentifier = $specificIssuerId + '@' + $realm

注意

$specificIssuerId 值必须是 GUID，因为在生产环境中，每个证书必须具有唯一颁发者。但是，在此上下文中，使用相同的证书来调试所有高信任加载项，可以硬编码值。如果出于任何原因使用与此处不同的 GUID，请确保 GUID 中的任何字母均为小写形式。 SharePoint 基础结构目前要求证书颁发者 GUID 为小写形式。

添加以下行将证书注册为受信任的令牌颁发者。 -Name 参数必须是唯一的，以便在生产配置中，通常可以使用 GUID 作为部分（或全部）名称，但是在此上下文中，可以使用友好名称。需要 -IsTrustBroker 开关以确保可以为你开发的所有高信任加载项使用相同的证书。要立即注册令牌颁发者，需要 iisreset 命令。如果没有该命令，可能需要等待 24 小时能注册新的颁发者。

  New-SPTrustedSecurityTokenIssuer -Name "High Trust Sample Cert" -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
  iisreset

SharePoint 通常不接受自签名证书。因此，当使用自签名证书进行调试时，请添加下面的行，关闭在远程 Web 应用程序调用到 SharePoint 中时使用 HTTPS 的 SharePoint 一般要求。如果未添加，当远程 Web 应用程序使用自签名证书调用 SharePoint 时，会收到 403 (禁止访问) 消息。你将在之后的过程中撤消此步骤。关闭 HTTPS 要求意味着从远程 Web 应用程序到 SharePoint 的请求未加密，但证书仍然可以用作访问令牌的受信任颁发者，这是它在高信任 SharePoint 加载项中的主要用途。

  $serviceConfig = Get-SPSecurityTokenServiceConfig
  $serviceConfig.AllowOAuthOverHttp = $true
  $serviceConfig.Update()

使用名称 HighTrustConfig-ForDebugOnly.ps1 保存文件。
以管理员身份打开“SharePoint 命令行管理程序”，然后使用下面的行运行文件：

  ./HighTrustConfig-ForDebugOnly.ps1

创建高信任 SharePoint 加载项

在本节中，你将了解如何使用 Visual Studio 创建高信任 SharePoint 加载项。

注意

如创建高信任加载项的先决条件部分中所述，本文假定你了解如何创建提供程序托管的 SharePoint 加载项。有关详细信息，请参阅开始创建提供程序托管的 SharePoint 加载项。

创建高信任 SharePoint 加载项

在 Visual Studio 中，依次选择“文件”>“新建”>“项目”。
在“新建项目”向导中，展开“Visual C#”或“Visual Basic”节点，然后展开“Office/SharePoint”节点。
选择“加载项”，然后选择创建“SharePoint 加载项”项目。
为 HighTrustSampleApp 项目命名。
将项目保存到选择的位置，然后选择“确定”。
指定 SharePoint 开发人员网站的完整 URL。例如，http://TestServer/sites/devsite/
选择“提供程序托管”选项，然后选择“下一步”。
如果系统提示你指定 Web 项目的类型，请选择“ASP.NET Web 窗体应用程序”以获取本主题中的后续示例，然后选择“下一步”。
向导的“配置身份验证设置”页面将打开。添加到此窗体的值会自动添加到 web.config 文件。在“要加载项如何进行身份验证?”下，选择“使用证书”。
单击“证书位置”框旁边的“浏览”，然后转到已创建的自签名证书（.pfx 文件）的位置 (C:\Certs)。此字段的值应该是完整路径 C:\Certs\HighTrustSampleCert.pfx。
在“密码”框中，键入此证书的密码。在本例中，是 password。
在“颁发者 ID”框中键入颁发者 ID (11111111-1111-1111-1111-111111111111)。
选择“完成”。许多配置都是在解决方案打开时完成的。将在 Visual Studio 解决方案中创建两个项目：一个适用于 SharePoint 加载项，另一个适用于 ASP.NET Web 应用程序。

运行并调试加载项

创建 ASP.NET 项目时，Visual Studio 的 Office 开发人员工具自动生成 default.aspx 和 default.aspx.cs 文件。生成的代码会提取 SharePoint 主机 Web 的标题，并将其显示在远程 Web 应用程序的默认页面上。这些文件中的确切标记和代码有所不同，具体取决于工具版本。在本主题中，可以使用生成的 default.aspx 和 default.aspx.cs 文件，无需进行修改。
若要测试 SharePoint 加载项及其远程 Web 应用程序，请在 Visual Studio 中选择 F5。 Web 应用程序将部署到 localhost 的 IIS Express 中。 SharePoint 加载项安装到目标 SharePoint 网站。 SharePoint 将提示你授予 SharePoint 加载项请求的权限。 Visual Studio 的 Office 开发人员工具某些版本会立即启动加载项；其他版本将打开目标 SharePoint 网站的“网站内容”页面，你将看到其中列出了新的加载项。

如果加载项不自动启动，则启动它。远程 Web 应用程序打开在 AppManifest.xml 文件中指定为“起始页”的页面，即 Default.aspx。加载项应类似于下图。

检索 Web 标题的示例应用

使用颁发的域或商业证书完成调试

之前创建的 Windows PowerShell 脚本已禁用远程 Web 应用程序使用 HTTPS 协议访问 SharePoint 的 SharePoint 一般要求。禁用使用 HTTPS 功能可能导致您作为开发人员在构建外接程序时，错过某些在需要 HTTPS 的生产部署中出现的问题。因此，在将测试证书替换为域颁发证书或商业证书并在开启 HTTPS 要求的情况下重新测试外接程序之前，不应考虑开发和调试已完成的阶段。

当您获得新证书时，需要向其添加密码（如果它还没有密码）。在生产环境中，将使用强密码，但对于调试 SharePoint 加载项，可以使用任何密码。将需要两种格式（pfx 和 cer）的证书。如果获得的证书不是 pfx 格式，可能需要使用实用工具将其转换为 pfx。如果具有 pfx 文件，可以按以下过程所述将其导入 IIS 中并导出 cer 文件。

导入新证书

将 .pfx 文件置于 SharePoint 服务器上的 C:\Certs 中。在本文中，我们假定该文件名为“MyCert.pfx”。应将所有这些说明中的 MyCert 替换为证书的实际名称。
在 IIS 管理器中，选择左侧树视图中的“ServerName”节点。
双击“服务器证书”图标。
在右侧“操作”窗格中选择“导入”。
在“导入证书”对话框中，使用“浏览”按钮浏览到 C:\Certs\ MyCert.pfx，然后输入证书密码。
确保启用“允许导出此证书”，然后单击“确定”。
在“服务器证书”列表中，右键单击该证书，然后选择“导出”。
将文件导出到 C:\Certs，并指定其密码。
如果测试 SharePoint 安装不在运行 Visual Studio 的同一台计算机上，请将 MyCert.pfx 文件移动到 Visual Studio 计算机上的 C：\Certs 文件夹。
在“服务器证书”视图中，双击 MyCert 以显示证书详细信息。
在“详细信息”选项卡上，选择“复制到文件”以启动“证书导出向导”，然后选择“下一步”。
使用默认值“不，不要导出私钥”，然后选择“下一步”。
使用默认值。选择“下一步”。
选择“浏览”，浏览到 C:\Certs，将证书命名为 MyCert，然后选择“保存”。将证书另存为 .cer 文件。
选择“下一步”。
选择“完成”。

配置 SharePoint 以使用新证书

打开 HighTrustConfig-ForDebugOnly.ps1 文件进行编辑并做出以下更改：

在出现 HighTrustSampleCert 的两处位置将其替换为 MyCert。
将特定颁发者 ID 11111111-1111-1111-1111-111111111111 替换为 22222222-2222-2222-2222-222222222222。
将“高信任示例证书”替换为“我的证书”或其他某些合适的友好名称。
在行 $serviceConfig.AllowOAuthOverHttp = $true 中，将 true 替换为 false。这将不符合使用 HTTPS 的要求。

保存文件。
以管理员身份打开“SharePoint 命令行管理程序”，然后使用下面的行运行文件：

  ./HighTrustConfig-ForDebugOnly.ps1

重新配置远程 Web 应用程序

在 Visual Studio 中，打开 Web 应用程序项目的 web.config 文件并进行以下更改：

在 ClientSigningCertificatePath 键中，将 C:\Certs\HighTrustSampleCert.pfx 替换为 C:\Certs\<MyCert>.pfx。
将 ClientSigningCertificatePassword 键值替换为证书的实际密码。
将 IssuerId 键值替换为 22222222-2222-2222-2222-222222222222。

按 F5 调试加载项。

在开发高信任加载项后，请查看打包和发布高度可信的 SharePoint 加载项，了解有关如何打包和发布此类 SharePoint 加载项的说明。

TokenHelper 和 SharePointContext 文件有何功能？

Visual Studio 的 office 开发人员工具将 TokenHelper.cs（或 .vb）文件加入远程 Web 应用程序。某些版本工具还包含 SharePointContext.cs（或 .vb）文件。

这些文件中的代码执行以下任务：

配置 .NET 以在进行网络调用时信任证书。
检索服务器间访问令牌，该令牌由远程 Web 应用程序的专用证书代表指定的 WindowsIdentity 对象进行签名，并且 SharePoint 可使用它建立信任。
获取 SharePoint 安全令牌服务 (STS) 证书
在使用低信任而不是高信任授权系统的加载项中，这些文件具有其他任务，例如处理 SharePoint 加载项的上下文令牌 OAuth 流中所述方案的 OAuth 令牌。该方案不在本文的讨论范围内。

高信任外接程序中没有上下文令牌。上下文令牌仅针对使用低信任授权的配置。但是，仍需要访问令牌。如果您使用的是高信任配置，则您的 Web 应用程序必须采用 SharePoint 所采用的方式对用户进行身份验证（即，外接程序负责创建访问令牌，包括用户和标识提供程序的 ID）。

在 Visual Studio 中使用 F5 进行调试时，Microsoft Visual Studio 的 Office 开发人员工具使用 Windows 身份验证，两个生成的代码文件使用运行加载项以创建访问令牌的用户的 Windows 标识。加载项发布后，如果你想要在不进行修改的情况下使用两个生成的文件，需要将 IIS 管理器中的远程 Web 应用程序配置为使用 Windows 身份验证。

如果加载项在生产环境中不使用 Windows 身份验证，则需要自定义生成的代码文件 TokenHelper 和/或 SharePointContext，以使用其他身份验证系统。如果远程 Web 应用程序以运行 SharePoint 加载项用户之外的其他身份访问 SharePoint，也可以对这些文件进行自定义。最后，如果远程 Web 应用程序是 PHP、node.js、Java 或其他非 ASP.NET 平台，代码需要从所使用的任何身份验证系统中获取用户 ID，然后将该 ID 添加到它构建的访问令牌。

创建 SharePoint 高信任加载项

先决条件

获取证书或创建公用和专用测试证书

创建自签名测试 .pfx 证书文件

创建一个相应的 .cer 文件

配置 SharePoint 以使用证书并配置对加载项的信任

配置 SharePoint 的具体步骤

创建高信任 SharePoint 加载项

创建高信任 SharePoint 加载项

运行并调试加载项

使用颁发的域或商业证书完成调试

导入新证书

配置 SharePoint 以使用新证书

重新配置远程 Web 应用程序

TokenHelper 和 SharePointContext 文件有何功能？

另请参阅

其他资源