Skip to content

Commit fe478ea

Browse files
committed
Update CSP instructions in README.
1 parent 25c4137 commit fe478ea

1 file changed

Lines changed: 14 additions & 5 deletions

File tree

README.md

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -74,13 +74,22 @@ Together, HTTPS and HSTS offer a strong, necessary level of transport security a
7474

7575
#### Content Security Policy
7676

77-
A Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks to your website, including Cross-Site Scripting (XSS) and data injection attacks. In order to incorporate the DAP JS into your site which includes a Content Security Policy, add the DAP domain and necessary Google domains to your allowed script sources. Also add the Google Analytics domain to your allowed connect sources. Example follows:
77+
A Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks to your website, including Cross-Site Scripting (XSS) and data injection attacks. If your site has a CSP, you will need to relax it slightly to allow the DAP code to load and function properly.
7878

79-
```
80-
Content-Security-Policy: script-src https://dap.digitalgov.gov https://www.google-analytics.com https://www.googletagmanager.com; connect-src https://www.google-analytics.com;
81-
```
79+
If you are loading the centrally-hosted DAP script with the default configuration, you will need to add the following directives to your CSP:
80+
81+
|Directive|Content| Justification |
82+
|-|-|----------------------------------------------------------------------------------------------------------------------|
83+
|`script-src`|`https://dap.digitalgov.gov https://www.googletagmanager.com`| The DAP script is served from `dap.digitalgov.gov` and it loads the GA4 tag library from `www.googletagmanager.com`. |
84+
|`connect-src`|`https://www.google-analytics.com`| The GA4 tag connects to `www.google-analytics.com` to send analytics data from your site to Google Analytics. |
85+
86+
If you are self-hosting the DAP code, then you can leave off the `dap.digitalgov.gov` domain from the `script-src` directive. Note that the DAP code attempts to load an additional third-party script from our https://dap.digitalgov.gov server and
87+
it will fail to load if you don't include our server in your CSP. This additional, optional script is for tracking [Core Web Vitals](https://web.dev/articles/vitals#core_web_vitals) and DAP will work fine without it.
88+
89+
If you have configured YouTube tracking (with the `yt` query parameter set to `true`), you will also need to add `https://www.youtube.com` to your `script-src` directive, because DAP uses the [YouTube Iframe API](https://www.youtube.com/iframe_api) to track interaction with YouTube videos.
8290

83-
This whitelists the DAP domain and necessary Google domains as trusted sources for JavaScript downloads to your site. In order to make your CSP as restrictive and secure as possible, use `script-src` rather than `default-src` to only permit JavaScript to be included from these domains and no other file types. The `connect-src` directive allows the DAP JavaScript code to connect to the Google Analytics domain in order to send analytics data from your site to Google Analytics.
91+
Note that Google [documentation](https://developers.google.com/tag-platform/security/guides/csp#google_analytics_4_google_analytics) claims that additional directives are needed for the GA4 tag, but the DAP team has not found that to be the case. This is the CSP that we use on https://analytics.usa.gov/, as an example.
92+
If your team encounters any situation where the additional directives seem to be necessary, we'd love to hear about it at [dap@gsa.gov](mailto:dap@gsa.gov).
8493

8594
#### Data integrity
8695

0 commit comments

Comments
 (0)