Skip to content

Commit ace6b07

Browse files
ethanpalmethanpalm
authored
CSP configuration and whitelist domains (#1090)
* add CSP config page to docs.json * Create csp-configuration.mdx * update description * add CSP header definitions * update conceptual info * combine testing/verification * update troubleshooting * use accordions for troubleshooting * : isntead of - * update whitelist table * 💅 * style and concision * simplify troubleshooting * remove protocol * remove protocol * add `'unsafe-eval'` * add blob in img-src * make it more clear this is an edge case * style * update Cloudflare steps * remove deprecated widget
1 parent 36a4de6 commit ace6b07

File tree

2 files changed

+124
-1
lines changed

2 files changed

+124
-1
lines changed

‎docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,8 @@
151151
"pages": [
152152
"advanced/subpath/cloudflare",
153153
"advanced/subpath/route53-cloudfront",
154-
"advanced/subpath/vercel"
154+
"advanced/subpath/vercel",
155+
"guides/csp-configuration"
155156
]
156157
},
157158
{

‎guides/csp-configuration.mdx‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: "Content Security Policy (CSP) configuration"
3+
sidebarTitle: "CSP configuration"
4+
description: "Domain whitelist and header configurations for reverse proxies, firewalls, and networks that enforce strict security policies"
5+
---
6+
7+
Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. Mintlify serves a default CSP that protects most sites. If you host your documentation behind a reverse proxy or firewall, that overwrites the default CSP, you may need to configure CSP headers for features to function properly.
8+
9+
## CSP directives
10+
11+
The following CSP directives are used to control which resources can be loaded:
12+
13+
- `script-src`: Controls which scripts can be executed
14+
- `style-src`: Controls which stylesheets can be loaded
15+
- `font-src`: Controls which fonts can be loaded
16+
- `img-src`: Controls which images, icons, and logos can be loaded
17+
- `connect-src`: Controls which URLs can be connected to for API calls and WebSocket connections
18+
- `frame-src`: Controls which URLs can be embedded in frames or iframes
19+
- `default-src`: Fallback for other directives when not explicitly set
20+
21+
## Domain whitelist
22+
23+
| Domain | Purpose | CSP directive | Required |
24+
|:-------|:--------|:--------------|:-------|
25+
| `d4tuoctqmanu0.cloudfront.net` | KaTeX CSS, fonts | `style-src`, `font-src` | Required |
26+
| `*.mintlify.dev` | Documentation content | `connect-src` | Required |
27+
| `d3gk2c5xim1je2.cloudfront.net` | Icons, images, logos | `img-src` | Required |
28+
| `www.googletagmanager.com` | Google Analytics/GTM | `script-src`, `connect-src` | Optional |
29+
| `cdn.segment.com` | Segment analytics | `script-src`, `connect-src` | Optional |
30+
| `plausible.io` | Plausible analytics | `script-src`, `connect-src` | Optional |
31+
| `tag.clearbitscripts.com` | Clearbit tracking | `script-src` | Optional |
32+
| `cdn.heapanalytics.com` | Heap analytics | `script-src` | Optional |
33+
| `chat.cdn-plain.com` | Plain chat widget | `script-src` | Optional |
34+
| `chat-assets.frontapp.com` | Front chat widget | `script-src` | Optional |
35+
36+
## Example CSP configuration
37+
38+
<Note>
39+
Only include domains for services that you use. Remove any analytics domains that you have not configured for your documentation.
40+
</Note>
41+
42+
```text wrap
43+
Content-Security-Policy:
44+
default-src 'self';
45+
script-src 'self' 'unsafe-inline' 'unsafe-eval' www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com
46+
chat.cdn-plain.com chat-assets.frontapp.com;
47+
style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net;
48+
font-src 'self' d4tuoctqmanu0.cloudfront.net;
49+
img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net;
50+
connect-src 'self' *.mintlify.dev www.googletagmanager.com cdn.segment.com plausible.io;
51+
frame-src 'self' *.mintlify.dev;
52+
```
53+
54+
## Common configurations by proxy type
55+
56+
Most reverse proxies support adding custom headers.
57+
58+
### Cloudflare configuration
59+
60+
Create a Response Header Transform Rule:
61+
62+
1. In your Cloudflare dashboard, go to **Rules > Overview**.
63+
2. Select **Create rule > Response Header Transform Rule**.
64+
3. Configure the rule:
65+
- **Modify response header**: Set static
66+
- **Header name**: `Content-Security-Policy`
67+
- **Header value**:
68+
```text wrap
69+
default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;
70+
```
71+
4. Deploy your rule.
72+
73+
### AWS CloudFront configuration
74+
75+
Add a response headers policy in CloudFront:
76+
77+
```json
78+
{
79+
"ResponseHeadersPolicy": {
80+
"Name": "MintlifyCSP",
81+
"Config": {
82+
"SecurityHeadersConfig": {
83+
"ContentSecurityPolicy": {
84+
"ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;",
85+
"Override": true
86+
}
87+
}
88+
}
89+
}
90+
}
91+
```
92+
93+
### Vercel configuration
94+
95+
Add to your `vercel.json`:
96+
97+
```json
98+
{
99+
"headers": [
100+
{
101+
"source": "/(.*)",
102+
"headers": [
103+
{
104+
"key": "Content-Security-Policy",
105+
"value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;"
106+
}
107+
]
108+
}
109+
]
110+
}
111+
```
112+
113+
## Troubleshooting
114+
115+
Identify CSP violations in your browser console:
116+
117+
1. Open your browser's Developer Tools.
118+
2. Go to the **Console** tab.
119+
3. Look for errors starting with:
120+
- `Content Security Policy: The page's settings blocked the loading of a resource`
121+
- `Refused to load the script/stylesheet because it violates the following Content Security Policy directive`
122+
- `Refused to connect to because it violates the following Content Security Policy directive`

0 commit comments

Comments
 (0)