From 9c66c229876614d1f0a5426126a5536f7c3c9e0f Mon Sep 17 00:00:00 2001
From: Michael Kelly <mkelly@mozilla.com>
Date: Thu, 7 Jun 2012 13:48:56 -0400
Subject: [PATCH] Fix #64: Add docs for CSP issues.

---
 docs/details/troubleshooting.rst | 22 ++++++++++++++++++++++
 docs/index.rst                   |  1 +
 docs/setup.rst                   | 11 +++++++++++
 3 files changed, 34 insertions(+)
 create mode 100644 docs/details/troubleshooting.rst

diff --git a/docs/details/troubleshooting.rst b/docs/details/troubleshooting.rst
new file mode 100644
index 0000000..0a58be1
--- /dev/null
+++ b/docs/details/troubleshooting.rst
@@ -0,0 +1,22 @@
+Troubleshooting
+===============
+
+CSP WARN: Directive "..." violated by https://browserid.org/include.js
+----------------------------------------------------------------------
+
+This warning appears in the Error Console when your site uses 
+`Content Security Policy`_ without making an exception for the browserid.org
+external JavaScript include.
+
+To fix this, include https://browserid.org in your script-src directive. If 
+you're using the `django-csp`_ library, the following settings will work::
+
+    CSP_SCRIPT_SRC = ("'self'", 'https://browserid.org',)
+    CSP_FRAME_SRC = ("'self'", 'https://browserid.org',)
+
+.. note:: The example above also includes the frame-src directive. There is an
+   iframe used during BrowserID login, but some people report that login will
+   work without the directive. In general, you should probably include it.
+
+.. _Content Security Policy: https://developer.mozilla.org/en/Security/CSP
+.. _django-csp: https://github.com/mozilla/django-csp
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 6a0a9ce..a679648 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,3 +22,4 @@ to fork_ and contribute!
    setup
    details/customization
    details/settings
+   details/troubleshooting
diff --git a/docs/setup.rst b/docs/setup.rst
index 2e6e3a4..e8a1cdd 100644
--- a/docs/setup.rst
+++ b/docs/setup.rst
@@ -97,5 +97,16 @@ This JavaScript file requires jQuery.
       <script src="https://browserid.org/include.js"></script>
       <!-- Include JS for browserid_form here. -->
 
+.. note:: If your site uses `Content Security Policy`_, you will have to add
+   directives to allow the external browserid.org JavaScript, as well as an
+   iframe used as part of the login process.
+
+   If you're using `django-csp`_, the following settings will work::
+
+      CSP_SCRIPT_SRC = ("'self'", 'https://browserid.org',)
+      CSP_FRAME_SRC = ("'self'", 'https://browserid.org',)
+
 .. _Form Media: https://docs.djangoproject.com/en/1.3/topics/forms/media/
 .. _Managing static files: https://docs.djangoproject.com/en/1.3/howto/static-files/
+.. _Content Security Policy: https://developer.mozilla.org/en/Security/CSP
+.. _django-csp: https://github.com/mozilla/django-csp
\ No newline at end of file