2019年4月23日,星期二

SPFx隔离的Web部件–连接到后端API的正确方法

It’由于最近发布了SPFx 1.8,SharePoint / Office 365开发人员现在可以创建“隔离的” Web部件。如果您的Web部件需要与后端API或Graph对话的权限,则应强烈考虑使Web部件隔离。仅通过AAD身份验证保护Azure函数或其他API就是没有’足够。在这篇文章中,我’将详细介绍可以在Office 365环境中执行特权操作的SPFx Web部件的一些细节(在这种情况下,通过模板创建Microsoft Team)–因此,我们应该采取步骤来确保安全。具体来说,我们要保护在后台使用的访问令牌,并确保没有其他Web部件可以“piggy-back”到我们正在使用的权限上。没有隔离的Web部件:

  • 页面上的其他任何代码(可能从3 rd 一方的供应商)可以嗅探访问令牌,并可能恶意地使用它,具体取决于它拥有的权限
  • 任何标准SPFx Web部件都可以使用其他任何权限– meaning it’s a “最高公分母”这种情况下,环境中的所有标准SPFx Web部件都具有相同的权限,即有史以来授予的最高权限
这些可能是非常有效的安全问题– you’d要非常确定已向SPFx授予了哪些权限级别,以及您的环境中确切拥有的代码。隔离的Web部件通常可以作为确保Office 365环境不会不安全的答案的一部分。

怎么样 隔离的Web部件到底有什么帮助?

孤立的Web部件解释器

来自隔离的SPFx程序包的Web部件在iFrame内托管的唯一域上运行-授予的权限适用 只要 在该域上托管的代码。由于常规SPFx Web部件在* .sharepoint.com域上运行,因此授予的权限不适用于该域。而且由于其他任何SPFx隔离的Web部件都可以在 不同 唯一域,它们也不适用于此。本质上, 共享 SPFx的应用程序主体是 用过的–而是专用于AAD应用注册 这个 SPFx解决方案已创建并用于身份验证。请注意,此范围不是’t单个Web部件,但包含解决方案包。但是,这很好-如果您有不受信任的源代码为同一解决方案/代码库提供代码,那么坦率地说,您可能面临更大的安全性和治理挑战。

因此,当将隔离的Web部件添加到页面时,’会看到包含的iFrame– 不 ice the source:

源是一个动态创建的域,用于表示此解决方案包–类似于怎么老“SharePoint托管的应用”该模型用于为记住这些的人提供一个单独的代码托管域。在AD门户中,您’还将看到您为该SPFx解决方案包创建的应用程序注册:


它具有一堆自动配置的重定向URI,以支持从iFramed Web部件代码将使用的域进行SPFx调用:

独特的domain / iFrame和专用的AAD应用程序注册的组合解决了SPFx和AAD集成所带来的先前的权衡,其中存在对给定安全范围的权限请求(例如Group.ReadWrite.All)。–这将允许创建新的Office 365组或Microsoft团队或更新现有的Office 365组或Microsoft团队,以及进行其他一系列操作) 适用于租户中的所有* SPFx Web部件和扩展,而不仅仅是需要它的人。

因此,您可以看到执行高度特权操作的任何Web部件(例如,以我为例,创建一个团队,以继续该示例)确实应该被隔离– especially if there’您的租户可以托管来自不同团队或提供商的Web部件。通过这种方式。我保证,唯一可以调用我的API的东西就是要使用的Web部件-Office 365租户中没有其他代码可以。

当然,如果没有隔离的Web部件附带的iFrame,则auth令牌就在页面中,该页面上的其他任何内容都会被嗅探到:

因此,隔离的Web部件是一件好事。

在我们讨论在哪里需要什么配置之前,让’我们考虑一下一些用户界面。

具有隔离Web部件的UI注意事项

假设您要在隔离的Web部件中使用某些Office UI Fabric(OUIF)组件。那’很好,但您需要考虑以下事实:您的内容显示在具有特定尺寸的iFrame中–和某些UI组件不’不能很好地玩。让’s说我们要使用OUIF React中的对话框。在下面的示例中,我有一个按钮可以弹出对话框,为便于说明,我’ve还在我的Web部件上添加了黑色边框,因此您可以看到它在页面中的大小:


当按下按钮时,我们得到以下信息:


哇– doesn’看起来不对。那当然’,因为对话框仅出现在iFrame中。如果我扩展Web部件的尺寸,则对话框可以完全显示–实际上,我几乎需要“reserve”页面上所有最初不可见的元素的空间:


而且’Fabric React Panel也是如此。用一个小的Web部件,它’s 不 clear what’s going on 在 all:


但是在这种情况下,即使使用更高的Web部件也不会’t really help –您可以看到更多的面板,但是由于面板使用了屏幕的整个高度,因此您仍然看不到全部内容:


因此,当内容位于页面中时,也许隔离的Web部件可以更好地工作,而不是使用任何其他元素。 出现在用户互动中。您’我们需要相应地设计隔离Web部件的UI。

创建一个隔离的Web部件

通过指定来创建隔离的Web部件“isDomainIsolated”在您的SPFx项目的package-solution.json文件中为true。这告诉SPFx,此软件包中的所有Web部件都应与其他Web部件隔离(但不能彼此隔离)– you’d为此需要单独的项目):


您可以随时指定此选项,但是Yeoman Generator通过在您询问时询问此问题来帮助您’重新创建一个新的SPFx项目。一种“yes”以下问题将导致上面的配置:


关键要素

起初我对某些配置值中需要的值感到有些困惑。知道在AAD中为我创建了一个新的AAD应用程序注册后,是否需要在代码中使用该客户端ID?还是我的Azure函数使用的AAD应用程序注册的客户端ID 内部地 实际针对Graph进行调用(因为我的模式是SPFx Web部件-> Azure Function -> Graph calls)?

该文档从本质上说,“一切正常”,但我仍然有些困惑。

这里’总结您需要做什么:
  • 创建您的Azure Function应用并通过AAD身份验证确保安全
  • 创建您的SPFx项目并回答“yes”有关隔离的Web部件的问题(或添加“isDomainIsolated”:在您现有的package-solution.json文件中为true)
  • 添加适当的“webApiPemissionRequests”您的package-solution.json文件中的部分(下一个更多内容)
  • 使用AadHttpClientFactory在SPFx Web部件中编写代码以对API执行身份验证
  • 将包部署到应用程序目录(即使仅在此阶段调试)
  • 在租户管理中的API管理页面上批准权限请求
让’s更详细一些:
在package-solution.json中
将条目添加到“webApiPemissionRequests” section 与您的服务器端API /功能相对应, 范围“user_impersonation”. IMPORTANT:
  • 要列出的AAD应用程序reg / API是 一个适合您的功能应用程序 ,而不是:
    • 为隔离的Web部件动态创建的AAD应用(例如“cob-teamcreatorwp” in my case)
    • 您可能在功能中使用了其他一些AAD应用,但与从Web部件到API的通信没有任何关系(例如“COB Graph Access” in my case)
因此,您的package-solution.json应该看起来像这样:

在您的SPFx代码中
在您的代码中,您’会有这样的事情–请注意,再次传递给AadHttpClientFactory的客户端ID是Function应用的ID:

批准权限:
然后,需要将解决方案包部署到您的租户,并获得同意。
  • 将软件包添加到应用目录–请注意“权限管理”页面上的消息,表明需要采取进一步的措施,并带有有关批准的特定权限的说明:

  • 如果您随后转到该页面,’会看到批准的权限:  

  • 如果您点击批准按钮’对授予的权限感到满意。在这种情况下,权限将仅限于此SPFx程序包中的Web部件–租户中的其他Web部件将无法使用它。
从使用隔离的Web部件还原
在最初将Web部件定义为隔离的Web部件之后,有时您可能需要将Web部件还原为标准Web部件-我发现自己在撰写本文后必须执行一次此操作。请注意,除了将package-solution.json中的“ isDomainIsolated”更改为“ false”并重新打包外,您还需要从App Catalog中完全*删除* SPFx解决方案,然后上传新版本-简单的版本升级是不足以切换。希望能对某人有所帮助!

概要

您可以通过很多方法来确保自定义代码在Office 365 / SharePoint Online环境中可以执行的操作,但是隔离的Web部件确实有助于最大程度地降低利用漏洞的可能性。没有它们,也许其他东西可能会在您没有意识到的情况下调用您的后端API。值得注意的是,Microsoft在降低某些操作所需的代码权限方面仍有一些工作要做(例如,在Teams通道中发布消息需要Group.ReadWrite.All,并且某些Planner操作是相似的),但希望很快会实现。

It’同样值得考虑的是在什么地方需要什么权限。如果您通过后端API调用Graph,则SPFx可能只需要调用*您的API的权限,而后端使用的单独的AAD应用程序注册才具有采取实际操作的权限。显然,可以大大减少表面积。

无论哪种方式,隔离的Web部件都可以在平衡安全性与Office 365中的功能方面发挥重要作用。我将在以后的文章中发布Teams Creator Web部件和Azure Function API的完整源代码。

进一步阅读:
//docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/isolated-web-parts