打包和发布高信任 SharePoint 加载项

先决条件

需要具备以下条件：

• 本地 SharePoint 开发环境。 有关设置说明，请参阅设置 SharePoint 加载项的本地开发环境。

• 用于承载远程 Web 应用程序的 IIS Web 服务器。 应安装 IIS 管理器。

• 远程安装的或在已安装 SharePoint 的计算机上安装的 Visual Studio。

• Microsoft Visual Studio 的 Office 开发人员工具。

• 安装在 Visual Studio 计算机上的 Web 部署，以及安装在远程 Web 应用程序服务器上的相同版本的 Web 部署。

表 1 列出了一些有助于你理解创建 SharePoint 外接程序所涉及的概念的有用文章。

表 1. 发布高信任外接程序的核心概念

文章标题	说明
开始创建提供程序托管的 SharePoint 外接程序	了解如何使用 Visual Studio 的 Office 开发人员工具创建基本的提供程序托管的 SharePoint 外接程序。
创建高信任 SharePoint 外接程序	了解如何使用 SharePoint 外接程序 通过自签名证书和关联的颁发者 ID 创建基本的高信任 Visual Studio Office 开发人员工具。
Web 部署	Web 部署简化了 Web 应用程序和网站到 IIS 服务器的部署。
数字证书和 使用证书	了解数字证书背后的基本理念。

注意

高信任 SharePoint 加载项只能安装到本地 SharePoint，不能安装到 SharePoint Online，它们主要用于本地 Web 应用程序，而不是基于云的 Web 应用程序。 本文介绍在该场景中如何发布加载项。 同样，在本文中，“客户”指安装 SharePoint 加载项并托管外接程序的远程组件的企业。

注册高信任加载项

在发布加载项之前，必须将其注册到 SharePoint 场的加载项管理服务。 高信任 SharePoint 加载项始终在安装加载项的 SharePoint 场上注册。 （它们不能通过 Office 应用商店出售。）注册在页面 http://SharePoint_website/_layouts/15/appregnew.aspx 上完成，如以下过程所述。

注册加载项

1. 转到 http://SharePoint_website/_layouts/15/appregnew.aspx 页面。

2. 选择“生成”按钮，生成加载项 ID 和密码的值。 （密码并不会在高信任 SharePoint 加载项中实际使用，但窗体需要密码。）

3. 提供将在其中运行加载项的远程 Web 应用程序的域的基 URL。 不要将协议 (HTTPS) 包含在域中，但必须包含远程组件将用于 HTTPS 请求的端口（如果不是 443）（例如，www.contoso.com:5555 orMyAppServer:4444）。

4. 如果需要重定向 URI，则还需输入它的值。 有关如何使用重定向 URI 的说明，请参阅 SharePoint 加载项的身份验证代码 OAuth 流。

   页面上的窗体应类似于下图。 在本示例中，远程 Web 应用程序服务器将侦听默认端口 443 上的 HTTPS 请求，因此不需要在加载项域中指定端口。

   

5. 选择“创建”。 为加载项输入的信息将显示在下一页上。 请务必保持此信息可用，因为在使用 Visual Studio 发布工具时将需要此信息。 可以考虑创建此页面的快速屏幕截图。

选择用于获取、维护并部署高信任 SharePoint 加载项的证书的策略

开发人员在 Visual Studio 中使用 F5 开发和调试高信任 SharePoint 加载项时，开发人员可以使用自签名证书，如创建高信任 SharePoint 加载项中所述。但是，当加载项已发布时，使用自签名证书将导致浏览器显示一个警告页面，然后才会打开远程 Web 应用程序的启动页面。 用户必须选择是否继续。 下图显示了此类警告的示例。

自签名证书的警告

此警告的困扰对于开发人员来说可能可以接受，但对于客户来说无法接受。 因此，在最终发布到生产环境之前，客户必须获得由受信任第三方签署的证书。 第三方可以为商业证书颁发机构 (CA) 或本地 CA。 对于商业 CA，请注意，行业将逐步淘汰用于 Web 服务器的“仅 Intranet”证书；这些证书已于 2016 年 11 月过期。 不需要将此类证书用于高信任 SharePoint 加载项，因为可用于面向 Intranet 的 Web 服务器的证书也可用于 Intranet Web 服务器，但后者通常成本更高。

证书应采用两种格式，个人信息交换 (pfx) 和安全证书 (cer)。 如果在最初获得证书时未采用任一格式，客户可以使用实用工具进行转换。 此外，在获取 pfx 格式版本后，可以将 pfx 文件导入到 IIS，然后导出 cer 版本，如本文后面所述。

如果最初获得的证书为 cer 格式，它将包含私钥和公钥。 常规做法是，SharePoint 使用的 .cer 文件不应包含私钥。 可以考虑将原始证书导入到 IIS，然后导出不包含私钥的新 cer 版本，如下所述。 有关 .pfx 文件和 .cer 文件的详细信息，请参阅软件发布者证书。

此外，客户必须考虑是对所有高信任 SharePoint 加载项使用一个证书，还是对每个加载项使用单独的证书。 有关此决定的详细信息，请参阅决定对高信任 SharePoint 加载项使用一个证书还是多个证书。

使用证书配置远程 Web 服务器

下列过程将在承载远程 Web 应用程序的远程 Web 服务器上执行。

配置远程 Web 服务器和 pfx 证书

1. 为 .pfx 证书指定一个强密码。 有关详细信息，请参阅创建强密码指南和强密码。

2. 执行下列步骤，将证书导入远程 Web 服务器上的 IIS 中：

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

   2. 双击“服务器证书”图标。

   3. 在右侧“操作”窗格中选择“导入”。

   4. 在“导入证书”对话框中，使用“浏览”按钮浏览到 .pfx 文件，然后输入证书密码。

   5. 如果使用的是 IIS 管理器 8，则会有“选择证书存储”列表。 选择“个人”。 （这是指计算机的而不是用户的“个人”证书存储。）

   6. 如果您还没有 cer 版本，或者您有 cer 版本但其中包含私钥，请启用"允许导出此证书"。

   7. 选择“确定”。

打开 Windows 证书存储

1. 在同一台服务器上，打开“Microsoft 管理控制台”，如打开 MMC 3.0 中所述。

2. 为计算机帐户添加“证书”管理单元，如将“证书”管理单元添加到 MMC中所述。 请确保对计算机而不是用户或服务执行此过程。 出现提示时，选择 本地 计算机，而不是“另一台”计算机。

如果使用的是 IIS 管理器 8，请跳过下一过程。

在 IIS 管理器 7 中将证书获取到 Windows 证书存储中的其他步骤

1. 在服务器文件系统上创建一个文件夹，用作证书的临时存储位置。

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

3. 双击“服务器证书”图标。

4. 在“服务器证书”列表中，右键单击该证书，然后选择“导出”。

   

5. 将文件导出到所创建的文件夹中，并输入密码。

6. 在“Microsoft 管理控制台”中导入证书，如导入证书中所述。 请务必指定“个人”存储。

7. 将控制台保持打开状态以用于下一过程。

8. 删除在第一步中创建的文件夹及其中的证书文件。 如果也将证书保留在文件系统中，将证书保留在证书存储中的安全优势将被抵消。

下一步适用于 IIS 管理器 7 和 8。

获取证书的序列号

1. 在"Microsoft 管理控制台"中，导航到"证书(本地计算机)"管理单元中"个人"文件夹下的"证书"文件夹（如果尚未打开）。

2. 双击 SharePoint 加载项证书将其打开，然后打开“详细信息”选项卡。

3. 选择“序列号”字段，将整个序列号显示在框中。

4. 将序列号（不包括空格）复制到文本文件，然后将其提供给 SharePoint 加载项的开发人员。

   提示

   某些开发人员博客文章和论坛问题报告称，将序列号直接复制到剪贴板会产生一个包含隐藏字符的字符串，导致序列号对 SharePoint 加载项中的代码不可识别。 可以考虑手动键入数字，而不是进行复制。

接下来，您将创建证书的 cer 版本。 此版本包含远程 Web 服务器的公钥，供 SharePoint 用于解密远程 Web 应用程序发出的请求并验证这些请求中的访问令牌。 此版本在远程 Web 服务器上创建，然后移至 SharePoint 服务器场。

创建 cer 证书

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

2. 双击“服务器证书”。

3. 在“服务器证书”视图中，双击证书以显示证书详细信息。

4. 在“详细信息”选项卡上，选择“复制到文件”以启动“证书导出向导”，然后选择“下一步”。

5. 使用默认值“不，不要导出私钥”，然后选择“下一步”。

6. 在下一页上使用默认值，然后选择“下一步”。

7. 选择“浏览”并浏览到任何文件夹。 （cer 文件仍将从此计算机中移出。）为该文件指定与 pfx 文件相同的名称，然后选择“保存”。 将证书另存为 .cer 文件。

8. 选择“下一步”。

9. 选择“完成”。

配置 SharePoint 以使用证书

本节中的过程可以在安装了 SharePoint 命令行管理程序的任何 SharePoint 服务器上执行。

将 cer 文件分发到 SharePoint

1. 创建一个文件夹，并确保以下 IIS 加载项池的加载项池标识符具有读取权限：

   • SecurityTokenServiceApplicationPool

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

2. 将 .cer 文件从远程 Web 服务器 移动（不只是复制）至刚刚在 SharePoint 服务器上创建的文件夹。 文件仅临时存储在该文件夹中。

以下过程将证书配置为 SharePoint 中的受信任令牌颁发者。 此过程对每个高信任 SharePoint 外接程序仅执行一次。

配置证书

1. 创建所需的高信任配置 Windows PowerShell 脚本（如果尚未创建），如 SharePoint 的高信任配置脚本中所述。

2. 将脚本复制到 SharePoint 服务器。

3. 以管理员身份打开"SharePoint 命令行管理程序"并运行相应的脚本。

4. 当客户在多个 SharePoint 外接程序之间共享单个证书时，可以使用其中一个脚本。该脚本输出包含令牌颁发者的 GUID 的文件。 如果使用该脚本，请将它输出的文件提供给高信任 SharePoint 外接程序的开发人员。

5. 从 SharePoint 服务器的文件系统中删除 cer 文件。

   注意

   将证书注册为令牌颁发者不会立即生效，加载项需等注册生效后才能运行。 可能需要 24 小时才能使所有 SharePoint 服务器识别新的令牌颁发者。 在所有 SharePoint 服务器上运行 iisreset 会使它们立即识别颁发者，前提是可以在不影响 SharePoint 用户的情况下执行此操作。

修改 web.config 文件

提示

对于包含已修改 web.config 的代码示例，请参阅 PnP/Samples/Core.OnPrem.S2S.WindowsCertStore。

编辑 web.config 文件，使其包含 appSettings 节点中以下注册表项的新值：

• ClientID：这是 Web 应用程序的客户端 ID (GUID)，在 appregnew.aspx 上生成。

• ClientSigningCertificateSerialNumber： (如果适用于 Visual Studio 的 Microsoft Office 开发人员工具未添加此密钥，则需要添加此密钥。) 这是证书的序列号。 值中不应包含空格或连字符。

• IssuerId：这是令牌颁发者的 GUID（必须为小写形式）。 它的值取决于客户的证书策略：

  • 如果高信任 SharePoint 外接程序具有自己的证书，表明它未与其他 SharePoint 外接程序共享， IssuerId 则 与 ClientId相同。

  • 如果 SharePoint 加载项与其他 SharePoint 加载项共享同一个证书，则 IssuerId 为任意 GUID。 用于此方案的脚本（可以在 SharePoint 高信任配置脚本中找到）将生成一个文本文件，其中包含此 GUID。 IT 员工可以将输出文件传送给加载项开发人员，以作为 IssuerId 插入到 web.config 文件中。

注意

Visual Studio 的 Office 开发人员工具可能已添加 ClientSigningCertificatePath 和 ClientSigningCertificatePassword 的加载项设置键。 这些键在生产加载项中不能使用，应该删除。

示例如下。 请注意，高信任 SharePoint 外接程序没有 ClientSecret 键。

<appSettings>
  <add key="ClientID" value="c1c12d4c-4900-43c2-8b89-c05725e0ba30" />
  <add key="ClientSigningCertificateSerialNumber" value="556a1c9c5a5415994941abd0ef2f947b" />
  <add key="IssuerId" value="f94591d5-89e3-47cd-972d-f1895cc158c6" />
</appSettings>

修改 TokenHelper 文件

Visual Studio 的 Office 开发人员工具生成的 TokenHelper.cs（或 .vb）文件需进行修改，以用于 Windows 证书存储中所存储的证书，并按其序列号进行检索。 下面是一个单向示例。 该示例使用 C#。

提示

对于包含已修改 tokenhelper.cs 的代码示例，请参阅 PnP/Samples/Core.OnPrem.S2S.WindowsCertStore。

修改 TokenHelper

1. 文件部分底部#region private fields附近是 、 ClientSigningCertificatePassword和 ClientCertificate的ClientSigningCertificatePath声明。 请全部删除。

2. 在对应的位置添加以下行：

   private static readonly string ClientSigningCertificateSerialNumber 
       = WebConfigurationManager.AppSettings.Get("ClientSigningCertificateSerialNumber");
   

3. 查找声明 SigningCredentials 字段的行。 将它替换为以下行：

   private static readonly X509SigningCredentials SigningCredentials 
       = GetSigningCredentials(GetCertificateFromStore());
   

4. 转到文件的 #region private methods 部分，添加以下两个方法：

   private static X509SigningCredentials GetSigningCredentials(X509Certificate2 cert)
   {
       return (cert == null) ? null 
                           : new X509SigningCredentials(cert, 
                                                       SecurityAlgorithms.RsaSha256Signature, 
                                                       SecurityAlgorithms.Sha256Digest);
   }
   
   private static X509Certificate2 GetCertificateFromStore()
   {
       if (string.IsNullOrEmpty(ClientSigningCertificateSerialNumber))
       {
           return null;
       }  
   
       // Get the machine's personal store
       X509Certificate2 storedCert;
       X509Store store = new X509Store(StoreName.My, StoreLocation.LocalMachine); 
   
       try
       {
           // Open for read-only access                 
           store.Open(OpenFlags.ReadOnly);
   
           // Find the cert
           storedCert = store.Certificates.Find(X509FindType.FindBySerialNumber, 
                                               ClientSigningCertificateSerialNumber, 
                                               true)
                       .OfType<X509Certificate2>().SingleOrDefault();
       }
       finally
       {
           store.Close();
       }
   
       return storedCert;
   }
   

使用 Visual Studio 向导打包远程 Web 应用程序和 SharePoint 加载项以便于发布

提示

Microsoft 对 Visual Studio 和 Visual Studio Office 开发人员工具的更新比过去频繁得多，文档无法始终与变更保持一致。 本节使用 2013 年 10 月发布的 Visual Studio 版本及其中的 Visual Studio 的 Office 开发人员工具版本编写。 如果你使用的是 Visual Studio 或工具的更早或更新版本，可能需要查阅 Visual Studio 帮助和博客文章，以查找执行这些过程中的步骤的等效方法。

打包远程 Web 应用程序

1. 在"解决方案资源管理器"中，右键单击 Web 应用程序项目（而不是 SharePoint 外接程序项目），然后选择"发布"。

2. 在“配置文件”选项卡上，从下拉列表中选择“新建配置文件”。

3. 出现提示时，为配置文件指定一个合适的名称。 例如，Payroll SP 加载项 - 远程 Web 应用程序。

4. 在“连接”选项卡上，在“发布方法”列表中选择“Web 部署包”。

5. 对于“打包位置”，可使用任何文件夹。 为简化后面的过程，这应该是一个空文件夹。 通常使用项目的 bin 文件夹的子文件夹。

6. 对于站点名称，输入将托管 Web 应用程序的 IIS 网站的名称。 请勿在名称中包含协议或端口或斜线；例如 PayrollSite。 如果希望 Web 应用程序是默认网站的子网站，请使用 default website/<website name>；例如，default website/PayrollSite。 （如果 IIS 网站尚不存在，会在稍后的过程中执行 Web 部署包时创建一个。）

7. 选择“下一步”。

8. 在“设置”选项卡上，从“配置”列表中选择“发布”或“调试”。

9. 选择“下一步”>“发布”。 将在打包位置创建一个 zip 文件和其他各种文件，在稍后的过程中将使用这些文件来安装 Web 应用程序。

创建 SharePoint 加载项包

1. 右键单击解决方案中的 SharePoint 加载项项目，然后选择“发布”。

2. 在“当前配置文件”列表中，选择在上一过程中创建的配置文件。

3. 如果“编辑”按钮旁边出现一个小的黄色警告符号，请选择“编辑”。 将打开一个窗体，要求你提供在 web.config 文件中提供的相同信息。 此信息并非必填，因为使用的是 Web 部署包发布方法，但不能将窗体留空。 在四个文本框中输入任何字符，然后选择“完成”。

4. 选择“打包加载项”按钮。 (不要选择“ 部署 Web 项目”。此按钮只是重复在最后一个过程的最后一个步骤中执行的操作。) 打开 加载项窗体的包 。

5. 在“网站托管在何处?”框中，输入远程 Web 应用程序的域 URL。 必须包含协议 HTTPS，如果 Web 应用程序侦听 HTTPS 请求的端口不是 443，则还必须包含端口;例如， https://MyServer:4444. （这是 Visual Studio 的 Office 开发人员工具用于替换 SharePoint 加载项的加载项清单中 ~remoteAppUrl 令牌的值。）

6. 在“加载项的客户端 ID 是什么?”框中，输入在 appregnew.aspx 页上生成的客户端 ID，在 web.config 文件中也输入了此客户端 ID。

7. 选择“完成”。 加载项包即已创建。

发布远程 Web 应用程序并安装 SharePoint 加载项

发布 Web 应用程序

1. 导航到打包远程 Web 应用程序时作为包位置的文件夹，然后将其中的所有文件复制到远程服务器上的某个文件夹中。

2. 在该文件夹中，打开 project_name.deploy-readme.txt 文件（其中 project_name 是 Visual Studio Web 应用程序项目的名称），然后按照文件中的说明，使用 project_name.deploy.cmd 文件安装 Web 应用程序。

为 Web 应用程序配置协议绑定

1. 在 IIS 管理器中，选择“连接”窗格中的新网站。 （如果新 Web 应用程序是默认网站的子网站，则选择默认网站并对默认网站执行此过程。）

2. 选择“操作”窗格中的“绑定”。

3. 选择“站点绑定”对话框中的“添加”。 在打开的“添加站点绑定”对话框中，执行以下步骤：

   1. 在“类型”列表中选择“HTTPS”。

   2. 在“IP 地址”列表中选择“所有未分配”。

   3. 在“端口”框中输入端口。 如果在 appregnew.aspx 上注册 SharePoint 加载项时，在加载项域中指定了端口（如注册高信任加载项中所述），必须在此处使用相同的端口号。 如果在 appregnew 上未指定端口，则在此处使用 443。

   4. 在“SSL 证书”列表中，选择在之前的使用证书配置远程 Web 服务器部分中配置服务器时使用的证书。

   5. 选择“确定”。

4. 选择“关闭”。

为 Web 应用程序配置身份验证

1. 在 IIS 中安装新的 Web 应用程序时，它最初配置为用于匿名访问，但几乎所有的高信任 SharePoint 加载项均设计为需要用户进行身份验证，因此需要对其进行更改。 在 IIS 管理器中，选择“连接”窗格中的 Web 应用程序。 它是默认网站的同级网站或子网站。

2. 双击中心窗格中的“身份验证”图标以打开“身份验证”窗格。

3. 选择“匿名身份验证”，然后选择“操作”窗格中的“禁用”。

4. 选择 Web 应用程序设计使用的身份验证系统，然后选择“操作”窗格中的“启用”。

   如果 Web 应用程序的代码使用 TokenHelper 和 SharePointContext 文件中的生成代码，而不修改文件的用户身份验证部分，则表示 Web 应用程序使用的是“Windows 身份验证”，这是应启用的选项。

5. 如果您使用生成的代码文件，而不修改文件的用户身份验证部分，则您还需要执行以下步骤以配置身份验证提供程序：

   1. 在“身份验证”窗格中选择“Windows 身份验证”。

   2. 选择“提供程序”。

   3. 在“提供程序”对话框中，确保“协商”上方列出了 NTLM。

   4. 选择“确定”。

上传并安装 SharePoint 加载项

1. 将 SharePoint 加载项的 *.app 包文件上传到组织加载项目录。 （高信任 SharePoint 加载项无法通过 Office 应用商店分发。）有关详细信息，请参阅将加载项添加到加载项目录。

2. 在包含加载项目录的相同父 SharePoint Web 应用程序内的任意网站上安装加载项。 有关上传和安装 SharePoint 加载项的详细信息，请参阅将 SharePoint 加载项添加到 SharePoint 网站。

另请参阅

• 使用 Visual Studio 发布 SharePoint 加载项
• 注册 SharePoint 加载项
• 创建使用高信任授权的 SharePoint 加载项
• SharePoint 加载项的授权和身份验证