From 408bd861b41144fa7f977a97c4bfff1527724eaa Mon Sep 17 00:00:00 2001
From: Francesc Guasch <frankie@etsetb.upc.edu>
Date: Fri, 20 Oct 2023 16:31:14 +0200
Subject: [PATCH] doc: frontend security policies

issue #1920
---
 docs/docs/chatwoot.rst                 | 22 +++++++++-
 docs/docs/custom_login.rst             |  5 ++-
 docs/docs/frontend_security_policy.rst | 57 ++++++++++++++++++++++++++
 3 files changed, 81 insertions(+), 3 deletions(-)
 create mode 100644 docs/docs/frontend_security_policy.rst

diff --git a/docs/docs/chatwoot.rst b/docs/docs/chatwoot.rst
index 3388f4838..4ae7781a0 100644
--- a/docs/docs/chatwoot.rst
+++ b/docs/docs/chatwoot.rst
@@ -26,7 +26,7 @@ Do not copy the *\<script\>* tags, only the javascript code.
   :linenos:
 
 	(function(d,t) {
-	  var BASE_URL = "https://chatwoot_server";
+	  var BASE_URL = "https://chatwoot.server.example.org";
 	        var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
 	        g.src= BASE_URL + "/packs/js/sdk.js";
 	        s.parentNode.insertBefore(g,s);
@@ -48,7 +48,25 @@ Do not copy the *\<script\>* tags, only the javascript code.
 
 .. image:: images/chat_inside.png
 
-And restart rvd_front service:
+
+Security Policy
+~~~~~~~~~~~~~~~
+
+You need to allow third party content inside HTML, edit the /etc/rvd_front.conf
+config file and add this line.
+
+::
+
+      ,security_policy => 'foo.bar.com'
+
+This will allow the server *foo.bar.com* to all the content, see this
+`guide <http://ravada.readthedocs.io/en/latest/docs/frontend_security_policy.html>`_
+if you want to add different security policies.
+
+Apply
+~~~~~
+
+Restart rvd_front service to apply changes:
 
 .. prompt:: bash #
 
diff --git a/docs/docs/custom_login.rst b/docs/docs/custom_login.rst
index 6c82a6471..ab7b0f23b 100644
--- a/docs/docs/custom_login.rst
+++ b/docs/docs/custom_login.rst
@@ -34,8 +34,11 @@ Add your template in ``/etc/rvd_front.conf``
 Path for CSS, js and images
 ---------------------------
 
+The custom files must be placed in  ``/usr/share/ravada/templates/main/custom``
+
 If CSS, js or images are needed save in: ``public/css/custom``,
-``public/js/custom`` or ``public/img/custom`` respectively.
+``public/js/custom`` or ``public/img/custom`` respectively. These files must be
+located inside ``/usr/share/ravada/templates/public``.
 
 .. note ::
     Make sure your CSS, JS or images in custom template refers to those paths.
diff --git a/docs/docs/frontend_security_policy.rst b/docs/docs/frontend_security_policy.rst
new file mode 100644
index 000000000..096b6840b
--- /dev/null
+++ b/docs/docs/frontend_security_policy.rst
@@ -0,0 +1,57 @@
+Frontend Security Policy
+========================
+
+If you want to add custom third party HTML inside Ravada you may want
+to change the security policy headers. That may be necessary when you
+are using custom widgets, footers or login pages.
+
+Default Security Policy
+-----------------------
+
+Default Security Policy only allows content from the Ravada frontend server
+or its CDN libraries, such as bootstrap, fonts and others we are using.
+
+Custom Security Policy
+----------------------
+
+Single Entry
+~~~~~~~~~~~~
+
+The easiest way to allow third party content attached to the frontend is
+adding this single configuration in /etc/rvd_front.conf
+
+::
+
+      ,security_policy => 'foo.bar.com'
+
+This will allow any kind of content from this domain inside the Ravada web
+pages.
+
+Multiple source policies
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to be more specific about what content you are allowed, or you
+want to have different sources, you can do it this way:
+
+::
+
+      ,security_policy => {
+        default_src => 'foodefault.bar.com'
+        ,frame_src => 'fooframe.bar.com'
+        ,script_src => 'fooscript.bar.com'
+      }
+
+These three entries were enough to allow extra content in our tests, but
+there are many sources policies you can change.
+
+This is a list of all of the security policies you can enable in this config:
+
+* connect_src
+* default_src
+* frame_src
+* font_src
+* media_src
+* object_src
+* style_src
+* script_src
+