Describe problems and solutions involving CSP headers

docs/source/public_server.rst

@@ -358,6 +358,42 @@ For example, in Firefox, go to the Preferences panel, Advanced section,
 Network tab, click 'Settings...', and add the address of the notebook server
 to the 'No proxy for' field.
 
+Content-Security-Policy (CSP)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Certain `security guidelines
+<https://infosec.mozilla.org/guidelines/web_security.html#content-security-policy>`_
+recommend that servers use a Content-Security-Policy (CSP) header to prevent
+cross-site scripting vulnerabilities, specifically limiting to ``default-src:
+https:`` when possible.  This directive causes two problems with Jupyter.
+First, it disables execution of inline javascript code, which is used
+extensively by Jupyter.  Second, it limits communication to the https scheme,
+and prevents WebSockets from working because they communicate via the wss
+scheme (or ws for insecure communication).  Jupyter uses WebSockets for
+interacting with kernels, so when you visit a server with such a CSP, your
+browser will block attempts to use wss, which will cause you to see
+"Connection failed" messages from jupyter notebooks, or simply no response
+from jupyter terminals.  By looking in your browser's javascript console, you
+can see any error messages that will explain what is failing.
+
+To avoid these problem, you need to add ``'unsafe-inline'`` and ``connect-src
+https: wss:`` to your CSP header, at least for pages served by jupyter.  (That
+is, you can leave your CSP unchanged for other parts of your website.)  Note
+that multiple CSP headers are allowed, but successive CSP headers can only
+restrict the policy; they cannot loosen it.  For example, if your server sends
+both of these headers
+
+    Content-Security-Policy "default-src https: 'unsafe-inline'"
+    Content-Security-Policy "connect-src https: wss:"
+
+the first policy will already eliminate wss connections, so the second has no
+effect.  Therefore, you can't simply add the second header; you have to
+actually modify your CSP header to look more like this:
+
+    Content-Security-Policy "default-src https: 'unsafe-inline'; connect-src https: wss:"
+
+
+
 Docker CMD
 ~~~~~~~~~~