Outdated documentation

You are looking at the documentation for an older release. For the latest information, please see current release documentation.

包含自定义脚本

外部人员界面应用程序的构建采用了安全第一的思想。它包含几个机制，以确保前端的所有代码都由OTRS框架直接提供。

In addition, a security standard called Content Security Policy headers is now leveraged by the built-in web server. It serves as a last line of defense and in case some unexpected code still makes it to the client, it will make sure that the user’s browser simply refuses to run it.

但是，仍然存在这样的用例，即使是现代的 WEB 应用程序也可能需要运行一些额外的代码，前提是由管理员审查和包含这些代码。例子可以是外部集成的聊天解决方案，也可以是用于外部 WEB 分析的内联代码片段。

参见

包含自定义脚本在 系统配置 中通过以下设置完成：

  • ExternalFrontend::ExternalScripts
  • ExternalFrontend::InlineScripts
  • WebApp::Server::AdditionalOrigins

WEB 分析的例子

在本例中，我们概述了在外部人员界面应用程序中包含 WEB 分析提供者使用的自定义脚本的步骤。它们将在每次使用应用程序时运行，以便跟踪和报告用户的行为，供以后分析。

我们从下面来自第三方供应商的代码片段开始。

<script async src="https://www.example.com/track/js?id=UA-XXXXXX-Y"></script>
<script>
   window.dataLayer = window.dataLayer || [];
   function track(){dataLayer.push(arguments);}
   track('js', new Date());

   track('config', 'UA-XXXXXX-Y');
</script>

代码片段的第一行引用一个 外部 资源，该资源会由 script 标签加载。

在下面的脚本块中，我们有一些 内联 代码，在加载页面后立即运行。

添加外部脚本资源

首先，我们需要在适当的配置中包含外部脚本的位置:

  1. 转到 系统配置 屏幕。
  2. 搜索设置 ExternalFrontend::ExternalScripts。
  3. 点击该设置以编辑它。
  4. 如果已经存在值，则单击加号按钮。否则，继续下面的步骤。
  5. 在文本字段中输入 外部 资源的完整位置。例如： https://www.example.com/track/js?id=UA-XXXXXX-Y。
  6. 点击复选标记以保存修改后的设置。
  7. 部署修改后的系统配置。

添加内联代码片段

接下来，我们还必须包含原始代码段的内联部分：

  1. 转到 系统配置 屏幕。

  2. 搜索设置 ExternalFrontend::InlineScripts。

  3. 点击该设置以编辑它。

  4. 如果已经存在值，则单击加号按钮。否则，继续下面的步骤。

  5. 在文本区域中输入完整的代码片段，去掉任何 script 标签。例如:

    window.dataLayer = window.dataLayer || [];
function track(){dataLayer.push(arguments);}
track('js', new Date());

track('config', 'UA-XXXXXX-Y');

  6. 点击复选标记以保存修改后的设置。

  7. 部署修改后的系统配置。

重新构建外部人员界面应用程序

为了应用更改，我们还需要重新构建外部人员界面应用程序。下拉到 shell，执行以下命令:

bin/otrs.WebServer.pl --deploy-assets

将安全标头中的其它源列入白名单

如果您现在尝试访问外部人员界面应用程序，则可以验证脚本是否包含在代码中。 但是，您的浏览器可能会阻止访问所有 内联 和 外部 资源，因此代码可能会因某些错误而失败。

这种情况是设计使然，因为只有在 内容安全策略 标头中明确列入白名单时才能加载外部资源。

若要检查阻塞代码，请使用适当的 WEB 浏览器检查工具。在我们的示例中，我们将使用 Mozilla Firefox 及其 WEB 控制台，该控制台可通过 工具→Web 开发者→web 控制台 菜单项或 F12 快捷键获得。

对于示例代码片段，在访问应用程序时，可能会在控制台收到以下错误:

Browser Console Errors and Warnings

浏览器控制台错误和警告

从控制台错误我们可以看到外部脚本资源不能被加载(1和3行)。除此之外,两个评估调用也被封锁(2和5行)。所有错误都引用了一个名为 script-src 的 内容安全策略 规则，该规则表示脚本资源。

我们需要将外部资源和评估调用添加到 内容安全策略 标头的其它源列表中：

  1. 转到 系统配置 屏幕。
  2. 搜索设置 WebApp::Server::AdditionalOrigins。
  3. 点击该设置以编辑它。
  4. 如果 script-src 已经存在值，请单击旁边的加号按钮。 否则，继续下面的步骤。
  5. 在文本字段中只输入被阻塞资源的域部分。例如: https://www.example.com。这允许加载外部资源。
  6. 点击字段旁边的加号按钮，这样就添加了另一个值。
  7. 在新字段中输入以下指令，包括引号: 'unsafe-eval'。这允许执行评估调用。
  8. 点击复选标记以保存修改后的设置。
  9. 部署修改后的系统配置。

此时不需要重新构建外部人员界面应用程序，因为其它源配置立即生效。

如果重新加载外部人员界面应用程序，可能会得到一些额外的错误。在我们的例子中，可能是这样的:

Additional Browser Console Errors and Warnings

其它的浏览器控制台错误和警告

此错误表示还阻止了另一个资源，即特定位置的图像（第1行）。 我们可以通过引用图像资源的 内容安全策略 规则 img-src 的名称推断出这一点。 要将其添加到白名单，请尝试以下操作：

  1. 转到 系统配置 屏幕。
  2. 搜索设置 WebApp::Server::AdditionalOrigins。
  3. 点击该设置以编辑它。
  4. 如果已经存在 img-src 的值，请单击旁边的加号按钮。 否则，继续下面的步骤。
  5. 在文本字段中只输入被阻塞资源的域部分。例如: https://www.example.com。这允许加载外部图片资源。
  6. 点击复选标记以保存修改后的设置。
  7. 部署修改后的系统配置。

再次尝试重新加载外部人员界面应用程序并检查是否有更多错误。 如果没有，您的脚本现在可能正常工作。

不幸的是，无法预测脚本可能需要哪种资源。 但是，不用担心，您可以将其中的大多数列入白名单，只需确保遵循浏览器控制台日志中显示的提示跟踪。 在配置中查找相应的标头规则并相应地进行更新。

注解

某些资源可能仅由其他人请求，因此可能需要多次迭代才能正确配置所有内容。

警告

外部资源白名单会在您的 OTRS 应用程序中面临潜在的安全风险！只允许那些您确信没有恶意且来自可靠来源的资源。。 请记住，如果某些资源今天是安全的，那并不意味着它在明天仍然安全。 注意安全！