注册 SharePoint 加载项

使用 Visual Studio、卖家面板或 AppRegNew.aspx 页在 Azure ACS 中注册 SharePoint 加载项，然后检索注册信息。

重要

作为 Azure Active Directory (Azure AD) 的一项服务，Azure 访问控制 (ACS) 将于 2018 年 11 月 7 日停用。 此停用不会影响使用 https://accounts.accesscontrol.windows.net 主机名（不受此停用影响）的 SharePoint 加载项模型。 有关详细信息，请参阅停用 Azure 访问控制对 SharePoint 加载项的影响。

要使提供程序托管的 SharePoint 加载项的远程组件可以使用 OAuth 与 SharePoint 交互，加载项必须首先注册 Azure ACS 基于云的服务和租户或场的 SharePoint 应用程序管理服务。 （称为“应用程序管理服务”是因为 SharePoint 加载项最初称为“SharePoint 相关应用程序”。）

注意

SharePoint 托管的加载项则无此要求。

要使用 Azure ACS 注册加载项，需要指定以下信息：

• 外接程序的 GUID，称为客户端 ID。
• 外接程序的密码，称为客户端密码。
• 当用户收到信任此外接程序的提示时，在同意页面上使用的外接程序的显示名称。
• 托管远程外接程序的域的 URL。
• 重定向 URL。

在注册加载项后，它将具有加载项标识，并且是一个称为加载项主体的安全主体。 安装加载项后，SharePoint 管理员将能够检索有关该特定加载项主体的信息。

当用户首次向加载项授予访问 SharePoint 资源的权限时（可能在加载项安装或运行时授予，具体取决于应用程序的设计），SharePoint 将从 Azure ACS 获取有关加载项的信息。 然后，SharePoint 将此信息存储在 SharePoint 租赁或场的应用程序管理服务数据库中。 客户端密码仅存储在 Azure ACS 中。 SharePoint 永远不知道加载项的密码。 内容数据库服务和其他组件（例如 User Profile Service）可以直接从应用程序管理共享服务获取加载项的显示名称和其他基本信息。 有关详细信息，请参阅本文中的检索加载项注册和加载项主体信息。

注意

本文假定你熟悉 OAuth 2.0 Framework 的基本概念和原理。 有关详细信息，请参阅 OAuth.net 和 Web 授权协议 (oauth)。

在 Azure ACS 中注册 SharePoint 加载项

您可以使用以下三种方法中的一种来注册外接程序，具体取决于您处于外接程序开发生命周期的什么阶段、您外接程序的体系结构以及您计划如何推广它。

注册方法	详细信息
使用 Visual Studio 和 Microsoft Visual Studio 的 Office 开发人员工具创建临时加载项标识。	Visual Studio 的 Office 开发人员工具向导使用 SharePoint 测试网站的 ACS 和应用程序管理服务为加载项创建临时注册。 从 Visual Studio 运行加载项时（按 F5），使用此标识。 这些工具还会在 web.config 和 AppManifest.xml 文件中插入客户端 ID 和密码。 当你准备好发布加载项时，可以使用 Visual Studio 发布向导转到卖家面板进行注册。 如果不是营销 Office 应用商店中的 SharePoint 加载项，则使用 AppRegNew.aspx 进行注册。 （在下一节中介绍了具体步骤。） 注意：如果你的外接程序请求在运行时动态访问 SharePoint 资源的权限，而不是在加载项安装时，你无法使用 Visual Studio 创建外接程序标识。
通过卖家面板注册外接程序。	如果要在多个 SharePoint 租户或场中使用加载项，请使用卖家面板来注册加载项，而无需考虑你是在 Office 应用商店中推广加载项，还是通过加载项目录进行发布。 在卖家面板中注册时，可为加载项设计多租户体系结构，而无需租户或场的管理员单独进行注册。 此外，如果计划在 Office 应用商店中发布加载项，必须使用卖家面板来注册加载项。 不需要使用应用商店来发布在卖家面板中注册的加载项。 有关详细信息，请参阅在卖家面板中创建或更新客户端 ID 和密码。
使用 AppRegNew.aspx 页。	如果仅在一个租户或场中使用此加载项，请使用 AppRegNew 表单注册 SharePoint 加载项。 例如，如果为单个组织创建加载项并且将要使用组织加载项目录分发加载项，可以在租户或场中使用任何网站的 AppRegNew.aspx 页来注册此加载项。 您无法将在 AppRegNew.aspx 中注册的外接程序以发布到 Office 商店。 对于发布到 Office 商店的外接程序，您必须从卖家面板中获取标识。

使用 AppRegNew.aspx 进行注册

1. 使用 Web 浏览器转到 <site collection url>/_layouts/15/AppRegNew.aspx。

   AppRegNew 页面表单

   

2. 输入以下表单域的值：

   • 加载项 ID。 也称为客户端 ID，它是可以生成的 GUID（选择“生成”时）或者可粘贴到 AppRegNew.aspx 中的 GUID。 该值必须对每个加载项具有唯一性，且必须为小写形式。

   • 加载项密码。 也称为客户端密码，是不透明的字符串。 使用“生成”按钮在 AppRegNew.aspx 页上生成该密码。 下面是加载项密码的一个示例：xvVpG0AgVIJfch6ldu4dLUlcZyysmGqBRbpFDu6AfJw=。

     重要

     加载项密码过期。 如果在卖家面板上注册加载项，可以将过期时间设置为长达 3 年。 在仪表板中，也可以在旧的密码接近过期日期时添加新的密码。 新密码将在加载项的所有实例中启用。 如果使用 AppRegNew.aspx 注册加载项，密码将在 1 年后过期。 有关详细信息，请参阅替换 SharePoint 加载项中即将过期的客户端密码。

   • 标题。 用户友好标题，例如，Contoso 照片打印加载项。 用户将收到提示，对加载项授予或拒绝其请求的权限。 在出现此许可提示时，此标题显示为加载项的名称。

   • 加载项域。 SharePoint 加载项远程组件的主机名称。 如果远程应用程序没有使用端口 443，则加载项域还必须包含端口号。 加载项域必须与你用于 Web 应用程序的 URL 绑定匹配。 不要在该值中包含协议（“https:”）或“/”字符。 如果你的 Web 应用程序主机正在使用 DNS CNAME 别名，请使用该别名。 例如：

     • www.contoso.com:3333
     • www.fabrikam.com

   • 重定向 URI：。 ACS 向其发送身份验证代码的远程应用程序或服务中的终结点。 严格地说，SharePoint 加载项不使用此值。 对于在 SharePoint 外部启动并使用身份验证代码流获取 SharePoint 数据的访问授权的 Web 应用程序来说，需要重定向 URI。

     但对于（从 SharePoint 启动并使用上下文令牌流的）真正 SharePoint 加载项来说，则会忽略重定向 URI。

     重定向 URI 通常同一页面、控制器方法或是从 ACS 中请求身份验证代码的 Web 服务方法，但也可能是不同的终结点。 终结点的逻辑必须从由 ACS 发送的 HTTP 响应中获取授权代码，然后使用该代码请求访问令牌和刷新令牌。 有关详细信息，请参阅 SharePoint 加载项的授权代码 OAuth 流。

     即使对于真正的 SharePoint 加载项，表单也要求你输入一个有效值（尽管并不使用它）。 该值必须为包含协议（必须为 HTTPS）的完整终结点 URL。 例如：

     • https://www.contoso.com/Default.aspx
     • https://www.fabrikam.com/RedirectAccept.aspx
     • https://www.northwindtraders.com/home/index
     • https://adventureworks.com/

3. 选择表单上的“创建”。 页面重新加载，并显示一条你所输入的值的确认消息。 请使用一种易于复制和粘贴的形式在表单中记录这些值。 将需要在 web.config 和 AppManifest.xml 文件中或指 Visual Studio 发布向导中输入这些值。

不论如何注册 SharePoint 加载项，当你准备好将加载项部署到暂存或生产环境时，都必须 将注册值输入到 web.config 和 AppManifest.xml 文件中。 如果使用 Visual Studio，则 Microsoft Visual Studio 的 Office 开发人员工具将为你执行此配置。

在 web.config 和 AppManifest.xml 文件中输入注册值

在打包 SharePoint 外接程序并部署其远程组件之前，请在 AppManifest.xml 和 web.config 文件中输入一些注册值。

提示

如果使用 Visual Studio 发布向导发布 SharePoint 加载项，Visual Studio 将在发布过程中提示你输入客户端 ID 和客户端密码，并且会为你将信息放在正确的位置。

1. 在 Visual Studio 项目的 Web.config 文件中，输入外接程序 ID 值作为 ClientId 值（替换工具输入的临时值）。

   重要

   客户端 ID GUID 中的所有字母都必须是小写形式。

   示例如下。

   <appSettings>
     <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
     .  .  .
   </appSettings>
   

2. 输入外接程序密码值作为 ClientSecret 值（替换工具输入的临时值）。

   下面的示例演示如何在 Web 应用程序的 Web.config 文件中使用这些值。

   <appSettings>
     <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
     <add key="ClientSecret" value="l0z/8TzWN0yQBzMBSEZtYts2Vt3Eo/oE3rfCdPaogKQ= " />
   </appSettings>
   

3. 在 Visual Studio 项目的 AppManifest.xml 文件中，输入加载项 ID 值作为 ClientId 值（小写形式）。

   注意

   加载项清单不适用于实时请求访问 SharePoint 资源的权限的 Web 应用程序。 没有真正意义上的“SharePoint 加载项”。 它们未安装在 SharePoint 上，没有加载项清单。 有关详细信息，请参阅 SharePoint 加载项的授权代码 OAuth 流。

   下面的示例显示如何在 AppManifest.xml 文件中使用 ClientId 值。

   <AppPrincipal>
     <RemoteWebApplication ClientId="a044e184-7de2-4d05-aacf-52118008c44e"/>
   </AppPrincipal>
   

4. Visual Studio 的 Office 开发人员工具使用 StartPage 元素中的令牌 ~remoteAppUrl。 （例如，<StartPage>~remoteAppUrl/Pages/Default.aspx?{StandardTokens}</StartPage>。）如果使用 Visual Studio 中的“发布”向导，此令牌将解析到远程组件的 URL。 如果不使用向导（或者，如果你使用向导，但将远程组件发布到 Azure），则必须将令牌手动替换为注册加载项时所使用的加载项域值。 它必须是完全相同的值，包括端口号（如果有），除非还包含了 HTTPS 协议。 示例如下。

   <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
   

5. 对于 AppManifest.xml 文件中的 Title 元素，考虑使用与 AppRegNew.aspx 中的“标题”字段相同的值。 Title 元素值是用户在加载项安装后看到的加载项名称。 如果同意对话框中的加载项名称与 SharePoint UI 中的加载项名称不同，用户可能会产生混淆。

   下面的示例在外接程序清单中显示这些值。

   <Properties>
     <Title>Contoso photo printing app</Title>
     <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
   </Properties>
   

使用实时请求权限的加载项中的重定向 URL

如果你的 Web 应用程序是从 SharePoint 外部启动的（因此，它不是真正的 SharePoint 加载项），则必须将它设计为在运行时从 SharePoint 请求权限。 它需要具有使用重定向 URI 的代码以及其他信息，以从 ACS 中获取访问令牌。 找到设置此 URI 的位置，并在 AppRegNew.aspx 或卖家面板中使用用于重定向 URI 字段的确切值。 该值可能位于代码文件或配置文件中。

检索加载项注册信息和加载项主体信息

可以检索你在 SharePoint 上安装或注册的加载项的加载项注册信息和加载项主体信息。

要查找已注册的加载项的注册信息，请转到 http://<SharePointWebsite>/_layouts/15/AppInv.aspx。

若要执行查找，您必须记得用于注册您的外接程序的客户端 ID（又称为外接程序 ID）。 查找会返回特定客户端 ID 的以下信息：

• 标题
• 加载项域
• 重定向 URL（这与重定向 URI 相同）

此查找不返回加载项密码值。

要查看已注册的加载项主体的列表，请转到：http://<SharePointWebsite>/_layouts/15/AppPrincipals.aspx。

另请参阅

• SharePoint 外接程序的三种授权系统
• 开始创建提供程序托管的 SharePoint 外接程序
• SharePoint 外接程序的授权和身份验证