SharePoint 加载项的上下文标记 OAuth 流Context Token OAuth flow for SharePoint Add-ins

在 SharePoint 中,针对提供程序托管的低信任加载项的 OAuth 身份验证和授权流包含加载项、SharePoint、授权服务器和浏览器之间在运行时的一系列交互。In SharePoint, the OAuth authentication and authorization flow for a provider-hosted, low-trust, add-in involves a series of interactions among your add-in, SharePoint, the authorization server, and the browser at runtime. 此方案中的授权服务器是 Microsoft Azure 访问控制服务 (ACS)。The authorization server in this scenario is Microsoft Azure Access Control Service (ACS).

重要

作为 Azure Active Directory (Azure AD) 的一项服务,Azure 访问控制 (ACS) 将于 2018 年 11 月 7 日停用。Azure Access Control (ACS), a service of Azure Active Directory (Azure AD), will be retired on November 7, 2018. 此停用不会影响使用 https://accounts.accesscontrol.windows.net 主机名(不受此停用影响)的 SharePoint 加载项模型。This retirement does not impact the SharePoint Add-in model, which uses the https://accounts.accesscontrol.windows.net hostname (which is not impacted by this retirement). 有关详细信息,请参阅停用 Azure 访问控制对 SharePoint 加载项的影响For more information, see Impact of Azure Access Control retirement for SharePoint Add-ins.

在提供程序托管的加载项中,你具有一个与 SharePoint 分开,而不属于 SharePoint 场或 SharePoint Online 租赁的远程 Web 应用程序或服务。With a provider-hosted add-in, you have a remote web application or service that is separate from SharePoint, and not part of the SharePoint farm or SharePoint Online tenancy. 它可以托管在云中或本地服务器上。It can be hosted in the cloud or on an on-premises server. 在本文中,远程组件称为 Contoso.com。In this article, the remote component is called Contoso.com.

备注

远程组件也可以托管对 SharePoint 项目所发生的事件(如列表或列表项)做出响应的事件接收器。The remote component can also host event receivers that respond to events that occur to SharePoint items, such as lists or list items. Contoso.com 可能会响应的远程事件示例包括列表事件,如添加或删除列表项;或 Web 事件,如添加或删除网站。Examples of remote events that Contoso.com might want to respond to are list events, such as adding or removing a list item; or web events, such as adding or deleting a site. 有关如何创建远程事件接收器的详细信息,请参阅在 SharePoint 加载项中创建远程事件接收器For more information about how to create remote event receivers, see Create a remote event receiver in SharePoint Add-ins.

Contoso.com 使用 SharePoint 客户端对象模型 (CSOM) 或 SharePoint REST API 调用 SharePoint。Contoso.com uses the SharePoint client object model (CSOM) or the SharePoint REST APIs to make calls to SharePoint. Contoso.com 应用程序使用 OAuth 令牌传递流对 SharePoint 进行身份验证。The Contoso.com application uses an OAuth token-passing flow to authenticate with SharePoint. SharePoint 和 Contoso.com 相互不信任,但都信任 ACS,并会接受 ACS 颁发的令牌。SharePoint and Contoso.com do not trust each other; but both trust ACS and accept tokens issued by ACS.

涉及三种令牌:SharePoint 让 ACS 创建上下文令牌,SharePoint 将其转发到 Constoso.com。There are three tokens involved: SharePoint has ACS create a context token that SharePoint forwards to Constoso.com. Contoso.com 验证上下文令牌由 ACS 办法并信任它。Contoso.com validates that the context token was issued by ACS so it trusts it. 然后,Contoso.com 从上下文令牌提取刷新令牌并用它从 ACS 中直接获取访问令牌Contoso.com then extracts a refresh token from the context token and uses it to get an access token directly from ACS. 它将访问令牌包含在对 SharePoint 的所有请求中。It includes the access token in all its requests to SharePoint. SharePoint 确认访问令牌由 ACS 颁发,从而对从 Contoso.com 发出的请求做出响应。SharePoint validates that the access token was issued by ACS, so it responds to the requests from Contoso.com.

你在远程组件中提供令牌处理代码(但是,如果你的远程组件托管在 .NET 上,Microsoft Visual Studio 的 Office 开发人员工具将提供示例代码,为你执行大部分工作。)You provide the token-handling code in the remote component (but if your remote component is hosted on .NET, the Microsoft Office Developer Tools for Visual Studio provide sample code that does most of the work for you). 有关令牌处理代码的详细信息,请参阅在提供程序托管的低信任 SharePoint 加载项中处理安全令牌For more information about token-handling code, see Handle security tokens in provider-hosted low-trust SharePoint Add-ins.

先决条件Prerequisites

SharePoint 加载项使用上下文令牌流之前,必须先完成以下准备步骤。The following preliminary steps must be completed before a SharePoint Add-in can use the Context Token flow:

  • 如果 SharePoint 加载项将安装在本地 SharePoint 场上,有些设置要求将不适用于仅安装到 SharePoint Online 的情况:If the SharePoint Add-in is to be installed to an on-premises SharePoint farm, these setup requirements don't apply if it is only installed to SharePoint Online:

  • 不论加载项是安装到 SharePoint Online 还是本地 SharePoint 场,SharePoint 加载项必须在 ACS 中注册Regardless of whether the add-in is installed to SharePoint Online or to an on-premises SharePoint farm, the SharePoint Add-in must be registered with ACS. 有关如何执行此操作的详细信息,请参阅注册 SharePoint 加载项。此外,作为注册的一部分,加载项还为 ACS 提供其客户端 ID 和客户端密码。For details about how this can be done, see Register SharePoint Add-ins. Among other things, the add-in provides ACS with its client ID and client secret as part of the registration.

上下文令牌流步骤Context Token flow steps

下图中显示了 SharePoint 提供程序托管的加载项的 OAuth 身份验证和授权流。The OAuth authentication and authorization flow for a SharePoint provider-hosted add-in is shown in the following figure.

OAuth 上下文令牌流OAuth Context Token flow

OAuth 身份验证流程

下列步骤与图中的数字对应:These are the steps that correspond to the numbers in the figure:

  1. 用户从 SharePoint 启动 SharePoint 加载项。加载项的设计决定完成此步骤的方式。A user launches the SharePoint Add-in from SharePoint. The design of the add-in determines how this is done:
  • 如果加载项设计为在加载项部件(本质上是关于 IFRAME 的包装程序)中显示远程 Web 应用程序(中 Contoso.com 上),那么启动加载项就是表示导航到包含加载项部件的 SharePoint 页面。If the add-in is designed to surface the remote web application (at Contoso.com) in an add-in part (which is essentially a wrapper around an IFRAME), launching the add-in simply means navigating to a SharePoint page that contains the add-in part. (如果用户尚未登录,SharePoint 将提示用户登录。)SharePoint 处理页面并检测到页面上有一个 Contoso.com 应用程序中的组件。(If the user is not already signed in, SharePoint prompts the user to sign in.) SharePoint processes the page and detects that there is a component from the Contoso.com application on the page. (有关加载项部件的详细信息,请参阅创建加载项部件以安装 SharePoint 加载项。)(For more information about add-in parts, see Create add-in parts to install with your SharePoint Add-in.)

  • 如果加载项设计为在浏览器使用完整页面,用户可通过在 SharePoint 网站的“网站内容”**** 页面上选择加载项磁贴来启动它。If the add-in is designed to use as a full page in the browser, the user launches it by selecting its add-in tile on the SharePoint website's Site Contents page. (一种变体是加载项包含启动远程组件的自定义菜单或功能区项目时的情况。)(A variation of this is when the add-in includes a custom menu or ribbon item that launches the remote component.)

  1. 不论加载项如何启动,SharePoint 必须获取可以发送到 Contoso.com 应用程序的上下文令牌,因此它要求 ACS 创建包含 SharePoint 上下文相关信息的上下文令牌,其中包括当前用户、远程应用程序 URL 和其他信息。Regardless of how the add-in is launched, SharePoint must get a context token that it can send to the Contoso.com application, so it asks ACS to create a context token that contains information about the SharePoint context, including the current user, the remote application URL, and other information. 上下文令牌还包含加密刷新令牌。The context token also contains an encrypted refresh token.

  2. ACS 借助使用 Contoso.com 加载项密码的算法签署上下文令牌,并将其返回到 SharePoint。ACS signs the context token by using an algorithm that uses the Contoso.com add-in secret, and returns it to SharePoint. 只有 ACS 和 Contoso.com 加载项知道密码。Only ACS and the Contoso.com add-in know the secret.

  3. 如果在加载项部件中显示 Contoso.com 应用程序,SharePoint 会呈现托管加载项部件的页面,并将上下文令牌添加到 URL 中,加载项部件中的 IFRAME 会调用该 URL 来获取其内容。If the Contoso.com application is surfaced in an add-in part, SharePoint renders the page that hosts the add-in part and adds the context token to the URL that the IFRAME in the add-in part calls to get its contents. 如果 Contoso.com 应用程序是完整页面,SharePoint 会将浏览器重定向到 Contoso.com,并包括上下文令牌作为重定向响应的一部分。If the Contoso.com application is full page, SharePoint redirects the browser to Contoso.com and includes the context token as a part of the redirect response.

  4. 上下文令牌包含在发送给 Contoso.com 服务器的浏览器请求中。The context token is included in the browser request that is sent to the Contoso.com server.

  5. Contoso.com 服务器获取上下文令牌并验证签名,它之所以可以这样操作,是因为它知道客户端密码。The Contoso.com server gets the context token and validates the signature, which it can do because it knows the client secret. 这可向 Contoso.com 保证令牌由 ACS 颁发,而不是冒充 SharePoint 的骗子。This assures Contoso.com that the token was issued by ACS and not an imposter pretending to be SharePoint. Contoso.com 从上下文令牌中提取刷新令牌,并通过请求将允许其访问 SharePoint 的访问令牌的形式,将其与其他信息(包括客户端 ID 和客户端机密)一起发送到 ACS。Contoso.com extracts the refresh token from the context token and sends it, along with other information, including its client ID and client secret, to ACS in a request for an access token that allows it to access SharePoint.

  6. ACS 验证刷新令牌,确保令牌由 ACS 颁发,然后将访问令牌返回到 Contoso.com。ACS validates the refresh token so that it is assured that it issued the token, and then it returns an access token to Contoso.com. Contoso.com 可以选择缓存此访问令牌,因此不会在每次访问 SharePoint 时都要求 ACS 提供访问令牌。Optionally, Contoso.com can cache this access token so it doesn't have to ask ACS for an access token every time that it accesses SharePoint. 默认情况下,访问令牌一次适合缓存几小时。By default, access tokens are good for a few hours at a time. (截至本文撰写时,ACS 颁发的 SharePoint 访问令牌的默认过期时间为 12 小时,但这可能会更改。)(When this article was written, the default expiration for ACS-issued access tokens to SharePoint was 12 hours, but that could change.)

每个访问令牌仅供在初始授权请求中指定的用户帐户使用,仅授予对该请求中指定的服务(本示例中为 SharePoint)的访问权限。Each access token is specific to the user account that is specified in the original request for authorization, and grants access only to the service (in this case, SharePoint) that is specified in that request. 刷新令牌的有效期更长(截至本文撰写时为六个月),并且也可以缓存。Refresh tokens are longer lived (six months when this article was written) and can also be cached. 因此,同一个刷新令牌可以从 ACS 兑换新的访问令牌,直到刷新令牌本身过期。So, the same refresh token can be redeemed for a new access token from ACS until the refresh token itself expires. (有关缓存令牌的详细信息,请参阅在提供程序托管的低信任 SharePoint 加载项中处理安全令牌。)(For more information about caching tokens, see Handle security tokens in provider-hosted low-trust SharePoint Add-ins.)

刷新令牌过期后,Contoso.com 可以通过获取新的上下文令牌来获取新的刷新令牌。When the refresh token expires, Contoso.com can get a new one by obtaining a new context token. 有关详细信息,请参阅获取新的上下文令牌For more information, see Get a new context token.

  1. Contoso.com 使用访问令牌发出 SharePoint REST API 调用或对 spnv 的 CSOM 请求。Contoso.com uses the access token to make a SharePoint REST API call or CSOM request to spnv. 它通过在 HTTP Authorization 标头中传递 OAuth 访问令牌来执行此操作。It does this by passing the OAuth access token in the HTTP Authorization header. (如果远程组件托管在 .NET 平台上,则创建标头的示例代码在 Visual Studio 的 Office 开发人员工具中提供。)(Sample code for creating the header is provided in the Office Developer Tools for Visual Studio if your remote component is hosted on a .NET platform.)

  2. SharePoint 验证访问令牌,确保其由 ACS 颁发,然后它将 Contoso.com 请求的数据的发送到 Contoso.com,或执行 Contoso.com 请求的创建、读取、更新或删除 (CRUD) 操作,SharePoint validates the access token so that it is assured the token was issued by ACS. It then sends the data that Contoso.com requested to Contoso.com or performs the create, read, update, or delete (CRUD) operation that Contoso.com requested.

  3. Contoso.com 应用程序页面在浏览器(或加载项部件的 IFRAME)中显示。The Contoso.com application page renders in the browser (or in the IFRAME of the add-in part).

另请参阅See also