通过

创建使用低信任授权的 SharePoint 加载项

  • 项目

SharePoint 加载项（或外部应用程序）中的远程组件可以通过使用每个 HTTP 请求将访问令牌传递到 SharePoint，获取对 SharePoint 资源的授权。 远程组件从与客户的 Office 365 租赁关联的 Microsoft Azure 访问控制服务 (ACS) 帐户获取访问令牌。 Azure ACS 在 OAuth 2.0 事务中充当授权服务器（称为流），其中 SharePoint 充当资源服务器，且远程组件充当客户端。 若要了解相关协议规范，请参阅 Web 授权协议 (OAuth)。

重要

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

使用低信任授权系统的提供程序托管的 SharePoint 加载项可以在 Office 应用商店中出售，并安装在 Microsoft SharePoint Online 或本地 SharePoint 场中，该服务器场已配置为使用客户的 Office 365 租户与 Azure ACS 建立信任。 客户必须具有 Office 365 租赁才能安装使用低信任系统的 SharePoint 加载项。 但是，客户无需使用租赁用于任何其他目的。 有关将本地场链接到 Office 365 租赁的说明，请参阅使用 Office 365 SharePoint 网站在本地 SharePoint 网站上对提供程序托管的加载项进行授权。

在 Azure ACS 中注册

要使用低信任系统，必须先将 SharePoint 加载项注册到 Azure ACS 以及 SharePoint 场或 SharePoint Online 租赁的应用程序管理服务。 （称为“应用程序管理服务”是因为 SharePoint 加载项最初称为“SharePoint 相关应用程序”。）

对于通过 Office 应用商店出售的加载项，注册到 ACS 的操作在卖家面板中执行，注册服务的操作在安装加载项时执行。

对于在组织外接程序目录中分发的外接程序，将在要安装外接程序的任何 SharePoint 租户或场的 _Layouts\15\AppRegNew.aspx 页上执行 ACS 和服务注册。 访问 SharePoint 的外部非 SharePoint 应用程序也需要进行注册。 该目录包括 Office 加载项、Windows 应用商店应用、Web 应用程序以及智能手机应用等设备应用。

注意

注册要求应用程序具有 Internet 域。 任何现有域均可用于此目的，但无法完全确定你未拥有的任何域将始终存在，因此 Web 应用程序需为本机设备应用程序的一部分，即使 Web 应用程序组件除启用注册外不扮演任何其他角色也是如此。 有关使用这种方法设计的高级代码示例，请参阅使用加载项模型分批预配网站。

有关注册的详细信息，请参阅注册 SharePoint 加载项。

加载项密码到期

加载项密码必须每 12 个月替换一次。 有关详细信息，请参阅替换 SharePoint 加载项中即将过期的客户端密码。

授权策略

可将 SharePoint 加载项设计为使用三种授权策略中的一种：

  • 仅用户策略。 在使用仅用户策略时，SharePoint 仅检查用户的权限。 当用户直接访问资源而不使用加载项时（例如，当用户第一次打开 SharePoint 网站的主页或从 PowerShell 访问 SharePoint API 时），SharePoint 将使用该策略。

  • 仅加载项策略。 使用此策略的加载项可以执行它具有权限执行的任何操作，即使用户没有该操作的权限也是如此。 开发人员必须请求将该策略用于加载项的加载项清单中。 该请求必须经过安装加载项的用户批准。 仅提供程序托管的 SharePoint 加载项允许使用此策略。

  • 用户 + 加载项策略。 使用此策略的加载项只能执行加载项和用户均有权限执行的操作。 默认使用此策略，除非开发人员执行特定的步骤以使用其他策略。

有关授权策略的详细信息，请参阅 SharePoint 中的加载项授权策略类型。

两个 OAuth 运行时流

每当访问 SharePoint 的云托管 SharePoint 加载项或外部应用程序运行时，将发生流，即加载项、SharePoint、ACS 和（有时）最终用户之间的一系列互动。 流的最终结果是，SharePoint 接收包含在应用程序向 SharePoint 发出的每个创建、读取、更新和删除 (CRUD) 请求中的访问令牌。

有两个供 SharePoint 使用的主要 OAuth 流。 一个用于云承载的 SharePoint 外接程序，另一个称为"临时"流，用于访问 SharePoint 数据的其他平台上的应用程序。

  • 上下文令牌流。 SharePoint 加载项的远程组件使用 SharePoint 客户端对象模型 (CSOM) 或 REST 终结点向 SharePoint 发出调用。 SharePoint 从可以发送至远程服务器的 ACS 中请求上下文令牌。 远程服务器使用上下文令牌从 ACS 中请求访问令牌。 然后，远程服务器使用访问令牌重新与 SharePoint 通信。

    有关此流的详细信息，请参阅 SharePoint 加载项的上下文令牌 OAuth 流。

  • 身份验证代码流。 SharePoint 加载项在安装时被授予访问 SharePoint 资源所需的权限。 但是未安装在 SharePoint 上的应用程序必须请求"临时"权限，即每次运行时请求的权限。 此流中没有 SharePoint 上下文令牌。 相反，当加载项运行并尝试访问 SharePoint 时，SharePoint 将提示用户授予对所请求应用程序的权限。 当用户授予权限后，SharePoint 从传递到应用程序的 ACS 中获取授权代码。 应用程序使用代码从 ACS 获取访问代码，然后它可以与 SharePoint 通信。

    有关此流的详细信息，请参阅 SharePoint 加载项的授权代码 OAuth 流。

低信任 SharePoint 加载项疑难解答

针对有关某些使用低信任授权系统的 SharePoint 加载项的特定问题，本文提供了一般疑难解答指南和信息。

使用 Fiddler 工具

免费的 Fiddler 工具可用于捕获你的加载项的远程组件发送到 SharePoint 的 HTTP 请求。 工具的免费扩展可自动解码请求中的访问令牌。

开发期间仅用 OAuth 的 HTTPS 要求

OAuth 要求 SharePoint 运行 HTTPS（并不只是服务，还包括 SharePoint）。 在开发加载项时，这可能会产生阻碍。 例如，如果在调试加载项时尝试对 SharePoint 发起调用，可能会收到 403（禁止）消息，这是因为加载项运行所在的"localhost"中不支持 SSL。

可以使用以下 Windows PowerShell cmdlet 在开发过程中禁用 HTTPS 要求。

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

若要稍后重新启用 HTTPS 要求，请使用以下 Windows PowerShell cmdlet。

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

配置文件和注册表单中的域名不匹配可能导致无法授权。 下面四个值必须完全相同：

  • 加载项域，当 SharePoint 加载项在 AppRegNew.aspx 或卖家面板上注册时指定。

  • 在其中注册远程 Web 应用程序的安全证书的域。

  • AppManifest.xml 文件中 StartPage 值的域部分。

  • 在 AppManifest.xml 中指定的任何事件接收器的 URL 的域部分。

关于这一点，请注意以下事项：

  • 如果 SharePoint 加载项的远程组件使用除 443 以外的任何端口，必须明确包含端口作为所有四个位置的域的一部分；例如，contoso.com:3333。 （必须使用默认端口为 443 的 HTTPS 协议。）

  • 如果您为远程 Web 应用程序创建 DNS CNAME 别名，请为所有位置的域值使用 CNAME 别名。 例如，如果您的应用程序托管在 contoso.cloudapp.net 上，且您为其创建 contososoftware.com 的一个 CNAME，请使用 contososoftware.com 作为域。

  • 需要在 AppManifest.xml 文件的 StartPage 值（以及任何事件接收器 URL）中对域进行硬编码，然后才能将加载项打包。 如果使用 Visual Studio 中的“发布”向导打包加载项，系统将提示你提供域，Visual Studio 的 Office 开发人员工具会为你将域插入到 StartPage 值中（代替在调试过程中使用的 ~remoteWebUrl 令牌）。 但是，如果不使用“发布”向导，或者即使使用“发布”向导，但你的远程 Web 应用程序被部署到 Azure，则必须手动将令牌替换为域（和协议）；例如 https://contososoftware.com 或 https://MyCloudVM:3333。

错误：“基础连接已关闭：无法为 SSL/TLS 安全通道建立信任关系”。

此错误是 SSL 握手问题，不是 OAuth 问题。 确保 SharePoint 信任您正在使用的证书，并且该证书与端点名称匹配。

使用 HTTP DAV 方法从 SharePoint 读取文件出错

HTTP DAV 与 OAuth 不兼容。 如果您正在使用 SharePoint 客户端对象模型 (CSOM)，请使用以下代码读取文件。

File f = clientContext.Web.GetFileByServerRelativeUrl( url);
ClientResult<Stream> r = f.OpenBinaryStream();
clientContext.ExecuteQuery();

另请参阅