How to use Django’s Content Security Policy

Basic config

To enable Content Security Policy (CSP) in your Django project:

1. Add the CSP middleware to your MIDDLEWARE setting:

   MIDDLEWARE = [
       # ...
       "django.middleware.csp.ContentSecurityPolicyMiddleware",
       # ...
   ]
   

2. Configure the CSP policies in your settings.py using either SECURE_CSP or SECURE_CSP_REPORT_ONLY (or both). The CSP Settings docs provide more details about the differences between these two:

   from django.utils.csp import CSP
   
   # To enforce a CSP policy:
   SECURE_CSP = {
       "default-src": [CSP.SELF],
       # Add more directives to be enforced.
   }
   
   # Or for report-only mode:
   SECURE_CSP_REPORT_ONLY = {
       "default-src": [CSP.SELF],
       # Add more directives as needed.
       "report-uri": "/path/to/reports-endpoint/",
   }
   

Nonce config

To use nonces in your CSP policy, beside the basic config, you need to:

1. Include the NONCE placeholder value in the CSP settings. This only applies to script-src or style-src directives:

   from django.utils.csp import CSP
   
   SECURE_CSP = {
       "default-src": [CSP.SELF],
       # Allow self-hosted scripts and script tags with matching `nonce` attr.
       "script-src": [CSP.SELF, CSP.NONCE],
       # Example of the less secure 'unsafe-inline' option.
       "style-src": [CSP.SELF, CSP.UNSAFE_INLINE],
   }
   

2. Add the csp() context processor to your TEMPLATES setting. This makes the generated nonce value available in the Django templates as the csp_nonce context variable:

   TEMPLATES = [
       {
           "BACKEND": "django.template.backends.django.DjangoTemplates",
           "OPTIONS": {
               "context_processors": [
                   # ...
                   "django.template.context_processors.csp",
               ],
           },
       },
   ]
   

3. In your templates, add the nonce attribute to the relevant inline <style> or <script> tags, using the csp_nonce context variable:

   <style nonce="{{ csp_nonce }}">
     /* These inline styles will be allowed. */
   </style>
   
   <script nonce="{{ csp_nonce }}">
     // This inline JavaScript will be allowed.
   </script>
   

Caching and Nonce Reuse

The ContentSecurityPolicyMiddleware automatically handles generating a unique nonce and inserting the appropriate nonce-<value> source expression into the Content-Security-Policy (or Content-Security-Policy-Report-Only) header when the nonce is used in a template.

To ensure correct behavior, make sure both the HTML and the header are generated within the same request and not served from cache. See the reference documentation on Nonce usage for implementation details and important caching considerations.