独立 Web 部件

  • 项目

使用此功能，你可以构建可与由 Azure AD 保护的 API 进行安全通信的 Web 部件，而无需将访问令牌公开给页面上的其他组件甚至租户中的脚本。

为什么选择独立 Web 部件

若要允许 SharePoint 框架解决方案安全地访问由 Azure AD 保护的 API，可以使用 API 管理来指定租户中的脚本可以访问哪些 API 以及使用哪些权限。 接下来，使用 SharePoint 框架，你可以轻松检索特定 API 的访问令牌。 虽然它极大地简化了与由 Azure AD 保护的 API 的通信，但它允许所有脚本（而不仅仅是特定的 SharePoint 框架解决方案）获得任何批准的 API 的访问令牌。 如果在租户中使用的某个脚本被攻击，那么它可以代表当前用户访问任何已批准的 API。

独立 Web 部件引入了一种新的方法来隔离对由 Azure AD 保护的 API 的访问，并确保只允许特定 SharePoint 框架 Web 部件获得特定 API 的访问令牌。

独立 Web 部件的工作原理

重要

独立 Web 部件功能仅在 SharePoint 框架 v1.8 以及更高版本中可用。 仅新式页面支持独立 Web 部件。 虽然你可能能够将独立 Web 部件添加到经典页面，但发布时，Web 部件将不会呈现并生成错误。 独立 Web 部件只能安装到租户应用目录中。 它们不适用于网站集应用目录。

体系结构概述说明了独立 Web 部件的工作原理

使用独立 Web 部件功能的解决方案在 *.sppkg 文件中的项目元数据中设置了特定标志。 在将这些解决方案部署到应用程序目录时，所有 API 权限请求都被指定为独立。

在批准了一个独立 API 权限请求后，SharePoint 将在链接到 Microsoft 365 租户的 Azure AD 中创建一个单独的 Azure AD 应用程序。 此 Azure AD 应用程序特定于 SharePoint 框架解决方案，该解决方案请求 API 权限，并将根据该解决方案的请求设置 OAuth 权限。 由 OAuth 隐式流使用的 Azure AD 应用程序，其返回 URL 将设置为与特定 SharePoint 框架应用程序绑定的唯一域。

使用独立权限的解决方案的所有 Web 部件，将在添加到页面时，使用指向与特定 SharePoint 框架解决方案绑定的唯一域的 iframe 进行显示。 这样，SharePoint Framework 就可以强制实施唯一 API 权限，并确保租户中任何其他解决方案或脚本无法获取这些 API 的访问令牌。

搭建一个使用独立权限的项目

为面向 SharePoint Online 的新 SharePoint 框架项目搭建基架时，SharePoint 框架 Yeoman 生成器将显示以下提示：

解决方案中的组件是否需要访问唯一且不与租户中其他组件共享的 Web API 的权限？：

如果回答是，生成器将通过将 isDomainIsolated 属性设置为 true，向 config/package-solution.json 文件中的项目配置添加一个标志。 因为独立 Web 部件功能只适用于 Web 部件，所以生成器只允许在项目中创建 Web 部件。

重要

理论上，可以在使用独立权限的项目中手动创建 SharePoint 框架扩展。 然而，这并不是一个好主意，建议不要这样做，而且它不受支持。

如果添加的扩展与由 Azure AD 保护的 API 通信，那么它将无法以独立的方式检索访问令牌，并会在运行时失败。

与 API 进行通信

尽管 Web 部件使用独立权限，但对于如何在代码中获得由 Azure AD 保护的 API 的访问令牌并没有特别之处。 此外，即使在运行时独立 Web 部件将加载到指向一个唯一域的 iframe 中，你也可以与 SharePoint REST API 进行通信，就像在非独立 Web 部件中一样。

使用独立 Web 部件部署解决方案

带有独立 Web 部件的解决方案的部署方式与常规的 SharePoint 框架解决方案相同。 唯一区别是，API 权限请求是作为独立请求部署的。 在 API 管理页面上可以清楚地看到这一点，其中 API 权限请求按照应用它们的解决方案分组。

在租户级别上授予的 API 权限可由任何 SharePoint 框架解决方案或租户上的一段脚本使用。 另一方面，独立权限只能由请求的解决方案使用。

使用独立 Web 部件

当添加到页面时，使用 iframe 显示独立 Web 部件。 此 iframe 指向分配给 Web 部件所在的 SharePoint 框架解决方案的唯一域。 此域也在创建的 Azure AD 应用程序的返回 URL 中引用，该应用程序用于托管特定 SharePoint 框架解决方案的独立权限。 使用唯一域可确保，只有来自特定 SharePoint 框架解决方案的 Web 部件才能获得独立权限集的访问令牌。

独立 Web 部件的属性窗格

独立 Web 部件的属性窗格将呈现为具有相同 Web 部件的其他实例的单独 iframe。 它带来了开发人员应注意的一些细节：

  • 独立 Web 部件的生命周期事件（例如 render）将调用两次：一次用于 Web 部件本身，一次用于属性窗格。
  • 属性窗格的 iframe 大小受限于面板尺寸。 如果计划在属性窗格中使用模式或任何宽控件，请考虑这一点。

独立 Web 部件的处置

从 DOM 中删除 iframe 将自动清理与 iframe 文档关联的所有资源（包括套接字连接），可能不会调用独立 Web 部件的 onDispose 方法。

升级现有项目以使用独立权限

如果正在将现有 SharePoint 框架项目升级到 v1.8.0，并希望使用独立权限功能，可以通过在 config/package-solution.json 文件中将 isDomainIsolated 属性设置为 true 来实现。 应确保项目只包含 Web 部件。

将项目更改为使用独立权限后，应重新部署项目。 这将发出独立于解决方案的新 API 权限请求，这些请求需要得到租户管理员的批准。

使用独立权限删除解决方案

在批准独立 API 权限时，SharePoint 将创建专用 Azure AD 应用程序，这些应用特定于请求权限的 SharePoint 框架解决方案。 当从应用程序目录删除 SharePoint 框架解决方案时，不会删除 API 权限以及 Azure AD 应用程序。