.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. index:: Content Security Policy

.. _content_security_policy:

Content Security Policy (CSP)
=============================

A **Content Security Policies** (CSP) is a mechanism that a web application uses to protect against cross-site scripting (XSS) attacks. Web browsers check all web content against the application's policy, and block content that violates the policy. This makes it harder for an attacker to inject malicious content into the application.

.. note:: For more information regarding how this policy is implemented and enforced 
    visit, https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy.


.. _Default CSP:

TopBraid EDG default content security policy
--------------------------------------------

By default, TopBraid EDG uses a strict content security policy.

::

    script-src 'strict-dynamic' 'nonce-{{nonce}}' 'unsafe-inline' https: http:; base-uri 'self'; object-src 'none'; frame-ancestors 'self'

.. tip:: The ``{{nonce}}`` placeholder is replaced with a unique value per request, and the ``'unsafe-inline' https: http:`` part is a fallback for legacy browsers.

The policy restricts JavaScript execution and the ability to load the application in frames.


Impact on JavaScript customizations
-----------------------------------

Some JavaScript features are disabled or restricted under a strict policy. EDG customizations that use JavaScript can be impacted by this. Most notably:

* The HMTL ``<script>`` element requires a ``nonce`` attribute with the per-request nonce. This attribute can only be generated on the server side. In SWP, this can be generated with:

  .. code-block:: HTML

     <script nonce="{= tbl:nonce() }">...</script>

  In HTML template files (e.g., when :ref:`customizing the login form <ext_login>`):

  .. code-block:: HTML

     <script nonce="${csp-nonce}">...</script>

* The event handler HTML attributes (``onclick``, etc.) are disabled. Instead, use JavaScript to attach the event handler to the element, for example

  .. code-block:: javascript

     element.addEventHandler('click', function() { ... })

  In SWP, this can be achieved by nesting this inside the HTML element:

  .. code-block:: javascript

     <ui:handle ui:event="click" ui:script="..."/>

* ``javascript:...`` URLs are disabled. The common idiom for a link that triggers JavaScript code does not work:

  .. code-block:: HTML

     <a href="javascript:void(0)" onclick="...">

  Instead, a button styled as a link can be used:

  .. code-block:: HTML

     <button class="btn btn-link">

* JavaScript's ``eval`` function is disabled.

* JavaScript's ``document.write`` function cannot be used to create ``<script>`` elements. Use `document.createElement` instead.


.. _Lax CSP:

Using a lax policy
------------------

When a customization cannot be made to work under the strict policy, then a lax policy can be configured.

The setting is under *Server Administration* > *System Configuration Parameters* > *Advanced Parameters*.

A baseline lax policy that does not block JavaScript is:

::

    script-src: 'self' 'unsafe-inline'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'

The ``script-src`` section may need tailoring, for example by whitelisting any external domains that scripts might be loaded from.

.. warning:: This configuration is potentially less secure, since it removes one (but not the only) line of defense against XSS attacks.


Testing customizations
----------------------

* **Under a strict policy**

  One way to test a customization is to simply use it with the default (strict) policy, with the browser's developer console open. Content security policy violations will be reported in the browser console. Since the offending JavaScript code is prevented from running, the customization may not work correctly.

* **Under a lax policy**

  Alternatively, the :ref:`strict policy<Default CSP>` can be set as the value of *Content Security Policy (report only)*, and a :ref:`lax policy<Lax CSP>` as the value of *Content Security Policy (enforced)*. In this setup, violations of the strict policy are only reported in the JavaScript console, but not enforced. In other words, the customization will work correctly even if it violates the strict CSP, but such violations can be detected by the developer.