在运行时使用 OAuth 授权提供程序托管的外接程序用户

项目
04/08/2023

运行时在提供程序承载的外接程序中使用 OAuth 提供对 SharePoint 资源的授权访问。

适用于：SharePoint 2013 | SharePoint 加载项 | SharePoint Online

用户可以通过打开 SharePoint 网站，选择“ 网站内容”，然后选择加载项来访问 SharePoint 加载项。 SharePoint 会将用户重定向到你的提供程序托管的外接程序运行所在的远程 Web。由于用户是从 SharePoint 访问外接程序，用户需得到 SharePoint 授权，然后才能访问外接程序。

或者，如果用户直接转到提供程序托管的外接程序的 URL，该外接程序必须在运行时使用 OAuth 对他们进行授权。在这种情况下，提供程序托管的外接程序必须处理授权，因为您的用户未首先获得 SharePoint 的授权。 Core.DynamicPermissions 示例演示如何使用 OAuth 从网站动态请求权限。使用此解决方案可以执行以下操作：

授权用户直接导航到你的提供程序托管的外接程序，而非从 SharePoint 访问你的外接程序。例如，你可能不希望用户使用 SharePoint UI。相反，你的用户可能使用提供程序托管的外接程序，其中显示了从 SharePoint 检索的相关数据。
构建可以使用 OAuth 对用户进行身份验证，且可以通过 Office 应用商店销售的提供程序托管的外接程序。

开始之前

若要开始，请从 GitHub 上的 Office 365 开发人员模式和做法项目下载 Core.DynamicPermissions 示例加载项。

运行此代码示例之前：

确保您在网站上具有“管理”权限。有关更多信息，请参阅了解权限级别(#了解权限级别)。
使用 AppRegNew.aspx 在 SharePoint 网站上注册外接程序：
1. 导航到 SharePoint 网站上的 appregnew.aspx。例如，如果你希望在 contoso.sharepoint.com 网站上使用你的外接程序，请导航到 http://contoso.sharepoint.com/_layouts/15/appregnew.aspx。
2. 选择“生成”以生成一个新的“客户端 ID”。
3. 选择“生成”以生成一个新的“客户端密钥”。
4. 在标题中输入加载项的标题。
5. 在 “外接程序域”中，输入提供程序托管的外接程序的 URL。例如，输入 localhost。
6. 在 “重定向 URI”中，输入提供程序托管的外接程序的 URL。在获得授权和同意之后，SharePoint 会将你的外接程序重定向到此 URL。例如，输入 https://localhost:44363/Home/Callback. 可以从 Visual Studio 中 Core.DynamicPermissionsWeb 项目的 SSL URL 属性获取域名和端口号。
7. 选择"创建"。
将客户端 ID 和客户端密钥复制到 Core.DynamicPermissionsWeb\web.config 中的 appSettings 元素。

使用 Core.DynamicPermissions 加载项

运行此代码示例时：

在“连接到Office 365”中，输入你注册加载项的 SharePoint 网站的 URL，然后选择“连接”。例如，输入 https://contoso.sharepoint.com。
登录到你的 Office 365 网站。
如果系统要求你授予加载项请求的权限的同意，请选择“ 信任它”。请注意，你将被重定向到 /_layouts/15/OAuthAuthorize.aspx 页面。

注意

用户必须具有 “管理” 权限才能授予对外接程序请求的权限的同意。有关详细信息，可以参阅 SharePoint 加载项的授权代码 OAuth 流。
在“已成功连接到 Contoso”中，输入要创建的新列表的名称，然后选择“创建列表”。
确认显示属于 Contoso 网站的所有列表的“Contoso 列表”中显示您的新列表。

在连接到Office 365上选择“连接”时，将调用 Controllers\HomeController.cs 中的“连接”，然后调用 TokenRepository.Connect 。用户在“连接到 Office 365”上输入的 URL 将作为 hostUrl 传递到 TokenRepository.Connect。

注意

本文中的代码按原样提供，不提供任何明示或暗示的担保，包括对特定用途适用性、适销性或不侵权的默示担保。

 public ActionResult Connect(string hostUrl)
        {
            TokenRepository repository = new TokenRepository(Request, Response);
            repository.Connect(hostUrl);
            return View();            
        }

TokenRepository.Connect 调用 TokenHelper.GetAuthorizationUrl。 TokenHelper.GetAuthorizationUrl 使用 hostUrl 以及对 SharePoint 资源的所需权限将重定向 URL 返回到 OAuthAuthorize.aspx。 OAuthAuthorize.aspx 用于使用 OAuth 对用户授权。重定向到 OAuthAuthorize.aspx 时，用户必须登录到 Office 365，然后同意外接程序请求的权限，或信任加载项。对 SharePoint 资源的所需权限是 Web.Manage。用户授权后，代码示例将在 SharePoint 网站上创建列表。若要在 SharePoint 网站上创建列表，用户必须拥有 Web.Manage 权限。

注意

TokenHelper.GetAuthorizationUrl 返回格式为&client_id=<Client ID>&scope=Web.Manage&response_type=code 的 URLhttps://contoso.sharepoint.com/_layouts/15/OAuthAuthorize.aspx?IsDlg=1，其中<客户端 ID> 是加载项的客户端 ID。如果加载项是通过卖家面板进行注册，那么任何 Office 365 网站都可以安装此加载项。如果加载项未通过卖家面板注册，则必须使用 appregnew.aspx 来注册加载项，然后更新 Core.DynamicPermissionsWeb\web.config。若要了解详细信息，请参阅注册 SharePoint 2013 加载项。

 public void Connect(string hostUrl)
        {
            if (!IsConnectedToO365)
            {
                HttpCookie spHostUrlCookie = new HttpCookie("SPHostUrl");
                spHostUrlCookie.Value = hostUrl;
                spHostUrlCookie.Expires = DateTime.Now.AddYears(5);
                _response.Cookies.Add(spHostUrlCookie);
                _response.Redirect(TokenHelper.GetAuthorizationUrl(hostUrl, "Web.Manage"));
            }
        }

授权后，外接程序将重定向到 Controllers\HomeController.cs 中的 Callback ，这是在 appregnew.aspx 上指定的重定向 URI。 TokenHelper 将授权代码 code 传递到 Callback。要授予本文稍后所述的访问令牌，必须将授权代码 code 返回到 Callback。然后 Callback 将调用 TokenRepository.Callback。

 public ActionResult Callback(string code)
        {
            TokenRepository repository = new TokenRepository(Request, Response);
            repository.Callback(code);
            return RedirectToAction("Index");
        }

TokenRepository.Callback 调用 TokenCache.UpdateCacheWithCode，后者使用 TokenHelper.GetAccessToken 以便基于授权代码 code 获取 OAuth 访问令牌。

public void Callback(string code)
        {
            HttpCookie spHostUrlCookie = _request.Cookies["SPHostUrl"];
            if (null != spHostUrlCookie)
            {
                Uri sharePointSiteUrl = new Uri(spHostUrlCookie.Value);
                TokenCache.UpdateCacheWithCode(_request, _response, sharePointSiteUrl);
            }
        }

 public static void UpdateCacheWithCode(HttpRequestBase request, HttpResponseBase response, Uri targetUri)
        {
            string refreshToken = TokenHelper.GetAccessToken(request.QueryString["code"], "00000003-0000-0ff1-ce00-000000000000", targetUri.Authority, TokenHelper.GetRealmFromTargetUrl(targetUri), new Uri(request.Url.GetLeftPart(UriPartial.Path))).RefreshToken;
            SetRefreshTokenCookie(response.Cookies, refreshToken);
            SetRefreshTokenCookie(request.Cookies, refreshToken);
        }

现在，加载项拥有此用户的访问令牌，可以继续在 SharePoint 网站上创建列表。

另请参阅

Office 365 开发模式和做法解决方案指南。

通过

在运行时使用 OAuth 授权提供程序托管的外接程序用户

开始之前

使用 Core.DynamicPermissions 加载项

另请参阅

其他资源