CSP and Trusted URLs
Salesforce sets a Content Security Policy header on Lightning pages. The framework
default is restrictive — script-src 'self', and font-src, img-src,
media-src, frame-src, style-src, and connect-src likewise scoped to the
org's own origin. Any external resource a component needs is blocked until an
administrator adds a Trusted URL (called a CSP Trusted Site in API 58.0 and
earlier) that grants that specific origin, that specific directive, in that
specific context.
Setup path, verbatim from Salesforce Help: From Setup, in the Quick Find box,
enter Trusted URLs, and then select Trusted URLs.
The metadata type is CspTrustedSite, stored in cspTrustedSites/ with the
.cspTrustedSite extension, available in API 39.0 and later.
Before Starting
Read the actual console message. It names the directive that blocked the
request, and that directive is the only checkbox you need. Configuring from a
guess is how allow-lists rot.
Establish which surfaces the component runs on. Lightning Experience,
Experience Builder site, and Visualforce are separate contexts, and a URL
trusted in one is not trusted in another.
Enumerate every origin the feature touches, not just the one in the first
error. A third-party SDK typically needs a loader host, an API host, a frame
host for challenge flows, an asset CDN, and a telemetry beacon.
Decide whether this is a browser problem at all. If the request originates
in Apex, you need a Remote Site Setting or a Named Credential, and no Trusted
URL will help.
Core Concepts
The six directives you can grant
CspTrustedSite exposes exactly six directive fields. There is no script-src
field — Lightning fixes script-src at 'self'.
| Field |
Grants |
Typical console phrase |
isApplicableToConnectSrc |
fetch, XMLHttpRequest, WebSockets |
Refused to connect to |
isApplicableToFrameSrc |
<iframe> sources |
Refused to frame |
isApplicableToImgSrc |
images |
Refused to load the image |
isApplicableToFontSrc |
fonts |
Refused to load the font |
isApplicableToStyleSrc |
stylesheets |
Refused to load the stylesheet |
isApplicableToMediaSrc |
audio and video resources |
Refused to load media |
Context scopes the whole record
context |
Applies to |
All |
All supported context types |
LEX |
Lightning Experience pages only |
Communities |
Experience Builder sites only |
VisualForce |
Custom Visualforce pages only, and only if the page's cspHeader attribute is true (API 55.0+) |
FieldServiceMobileExtension |
Field Service Mobile Extensions only (API 47.0+) |
LightningOut |
"Reserved for future use" (API 64.0+) |
The endpointUrl grammar
Must include a domain name; may include a port. Wildcards are supported
(*.example.com). Third-party APIs must begin with https://; WebSockets must
begin with wss://. The value is a literal — build any templated URL before you
write it into the metadata.
Malformed values (malformed^url.example.com, https://{subdomain}.example.com)
could be saved before February 2025 and are "excluded from generated CSP HTTP
headers" — an entry that looks Active and correct but has never been in the header.
The default for unset directives is version-dependent
| API version of the deployment |
If every isApplicable* is false |
| ≤ 49.0 |
All of them default to true — an open grant |
| 50.0–58.0 |
isApplicableToImgSrc is set to true |
| ≥ 59.0 |
At least one isApplicable* or canAccess* must be true, or the deploy is rejected |
Write every field explicitly, true and false alike.
Camera and microphone are Permissions-Policy, not CSP
canAccessCamera and canAccessMicrophone (API 59.0+) are inert unless the org has
enablePermissionsPolicy = true and grantCameraAccess / grantMicrophoneAccess
= TrustedUrls in SecuritySettings.
Trusted URL is not Remote Site Setting
|
Trusted URL |
Remote Site Setting / Named Credential |
| Enforced by |
The user's browser, via the CSP header |
The Salesforce application server |
| Governs |
LWC/Aura fetch, <img>, <iframe>, fonts, CSS, WebSockets |
Apex Http.send(), Visualforce |
| Error text |
Refused to ... violates the following Content Security Policy directive |
Unauthorized endpoint, please check Setup->Security->Remote site settings |
Common Patterns
Pattern A — one origin, one directive, one context
The default and the correct shape for most cases. Read the console error, create
one record with one directive ticked and every other field explicitly false, and
put the depending component's name in description. Example 1 in
references/examples.md.
Pattern B — vendor the library into a static resource
For third-party JavaScript, this is the answer rather than a Trusted URL, because
there is no script-src field to grant. Upload the library as a static resource
and load it with loadScript from lightning/platformResourceLoader; it is then
served from the org's own origin. This also pins the version.
Pattern C — one record per origin for a multi-host SDK
A payment or analytics SDK needs several entries — loader, API, challenge iframe,
asset CDN. Enumerate them from the vendor's own CSP documentation in one pass, then
test the failure and challenge paths, because a 3-D Secure iframe or an error
beacon fires only there.
Pattern D — Apex proxy instead of a browser call
When the call carries a credential, or the endpoint is internal and not
HTTPS-reachable from a browser, route it through Apex with a Named Credential. No
Trusted URL, no CORS, credentials never reach the browser.
Decision Guidance
| Situation |
Approach |
LWC needs to fetch an external JSON API |
Trusted URL, connect-src, correct context |
| Component needs a third-party JS library |
Static resource + loadScript — not a Trusted URL |
| Vendor mandates loading their script live |
Vendor conversation and a documented risk acceptance; there is no per-URL script-src grant |
| Third-party widget in an iframe |
Trusted URL, frame-src, plus connect-src for whatever the widget calls |
| Widget needs camera or microphone |
canAccess* on the URL and SecuritySettings set to TrustedUrls |
| Apex callout is blocked |
Remote Site Setting or Named Credential — not a Trusted URL |
| Internal service is HTTP-only |
Apex proxy; CSP requires HTTPS and there is no exemption |
| Vendor hostnames genuinely rotate |
Wildcard, with the reason recorded in description |
| Deadline pressure, widget still blocked |
Escalate the enumeration, never Relaxed CSP |
Recommended Workflow
- Reproduce and read the violation. Capture the full console message: it names
both the blocked URL and the directive. One message per blocked origin.
- Classify the caller. Browser-originated → Trusted URL. Apex-originated →
Remote Site Setting or Named Credential. A feature doing both needs both.
- Enumerate every origin the feature needs from the vendor's CSP
documentation, and note which directive each one requires. Do not configure
incrementally, one incident at a time.
- Decide the context from the surfaces the component runs on, and emit one
record per context rather than defaulting to
All.
- Author
CspTrustedSite metadata with every directive field written
explicitly, an exact host unless rotation genuinely requires a wildcard, and a
description naming the depending feature.
- Verify the whole flow, including the failure and challenge paths, and
confirm no residual console violations.
- Add the entry to the quarterly review list so it is removed when the feature
is retired — the allow-list must shrink as well as grow.
Review Checklist
Salesforce-Specific Gotchas
Full detail with quotes in references/gotchas.md.
- Context is not a label — a URL trusted in LEX is not trusted in Experience
Cloud, and the record still shows as Active.
- There is no
script-src checkbox. Use a static resource.
- Inline handlers are blocked and no configuration unblocks them.
- A malformed URL saves, shows Active, and is silently excluded from the CSP
header — the cause of "it's allow-listed and still blocked."
- The default for unset directives changed at API 50.0 and again at 59.0.
- Camera and microphone need an org-level switch too.
- A third-party script almost never talks to only its own origin.
- The generated CSP header has a practical size ceiling — keep it under 12 KB;
problems are reported approaching 16 KB.
- Relaxed CSP is site-wide and effectively permanent.
- HTTPS is mandatory, including for resources inside your own org.
- Trusted URLs and Remote Site Settings solve different problems.
Output Artifacts
| Artifact |
Description |
| Origin inventory |
Every host the feature touches, the directive each needs, and the vendor documentation it came from |
CspTrustedSite metadata |
One file per origin per context, every directive field explicit, description naming the dependent feature |
SecuritySettings change |
Only when camera or microphone access is required, deployed separately as an org-wide change |
| Verification note |
Which flows were exercised, including failure and challenge paths, and confirmation of a clean console |
| Review entry |
The record's name and owning feature added to the quarterly Trusted URL review |
Related Skills
lwc/static-resources-in-lwc — the loadScript / loadStyle path that replaces
a script-src grant, and how to package a vendored library
security/network-security-and-trusted-ips — the network-layer controls that
Trusted URLs are frequently confused with
integration/named-credentials-setup — the server-side alternative when the call
carries a credential or the endpoint cannot be browser-reachable
1---2name: csp-and-trusted-urls3description: "Configure Content Security Policy via Trusted URLs and CSP Trusted Sites so Lightning, LWR, and LWC can call third-party scripts, APIs, and frame sources. NOT for clickjack configuration — use lwc/static-resources-in-lwc."4category: security5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Security8triggers:9 - "script refused to load salesforce csp"10 - "add trusted url for external api"11 - "lwc fetch third party blocked"12 - "csp trusted sites lightning"13tags:14 - csp15 - trusted-urls16 - lightning17inputs:18 - "External URLs the UI must reach"19 - "context (Lightning vs LWR vs Experience)"20outputs:21 - "Trusted URL records with correct context scopes"22dependencies: []23version: 1.0.124author: Pranav Nagrecha25updated: 2026-08-1426metadata:27 source: https://skillmd.com/skills/pranavnagrecha/csp-and-trusted-urls28---2930# CSP and Trusted URLs3132Salesforce sets a Content Security Policy header on Lightning pages. The framework33default is restrictive — `script-src 'self'`, and `font-src`, `img-src`,34`media-src`, `frame-src`, `style-src`, and `connect-src` likewise scoped to the35org's own origin. Any external resource a component needs is blocked until an36administrator adds a **Trusted URL** (called a CSP Trusted Site in API 58.0 and37earlier) that grants that specific origin, that specific directive, in that38specific context.3940Setup path, verbatim from Salesforce Help: *From Setup, in the Quick Find box,41enter `Trusted URLs`, and then select **Trusted URLs**.*4243The metadata type is `CspTrustedSite`, stored in `cspTrustedSites/` with the44`.cspTrustedSite` extension, available in API 39.0 and later.4546---4748## Before Starting49501. **Read the actual console message.** It names the directive that blocked the51 request, and that directive is the only checkbox you need. Configuring from a52 guess is how allow-lists rot.53542. **Establish which surfaces the component runs on.** Lightning Experience,55 Experience Builder site, and Visualforce are separate contexts, and a URL56 trusted in one is not trusted in another.57583. **Enumerate every origin the feature touches**, not just the one in the first59 error. A third-party SDK typically needs a loader host, an API host, a frame60 host for challenge flows, an asset CDN, and a telemetry beacon.61624. **Decide whether this is a browser problem at all.** If the request originates63 in Apex, you need a Remote Site Setting or a Named Credential, and no Trusted64 URL will help.6566---6768## Core Concepts6970### The six directives you can grant7172`CspTrustedSite` exposes exactly six directive fields. There is **no `script-src`73field** — Lightning fixes `script-src` at `'self'`.7475| Field | Grants | Typical console phrase |76|---|---|---|77| `isApplicableToConnectSrc` | `fetch`, `XMLHttpRequest`, WebSockets | `Refused to connect to` |78| `isApplicableToFrameSrc` | `<iframe>` sources | `Refused to frame` |79| `isApplicableToImgSrc` | images | `Refused to load the image` |80| `isApplicableToFontSrc` | fonts | `Refused to load the font` |81| `isApplicableToStyleSrc` | stylesheets | `Refused to load the stylesheet` |82| `isApplicableToMediaSrc` | audio and video resources | `Refused to load media` |8384### Context scopes the whole record8586| `context` | Applies to |87|---|---|88| `All` | All supported context types |89| `LEX` | Lightning Experience pages only |90| `Communities` | Experience Builder sites only |91| `VisualForce` | Custom Visualforce pages only, **and only if the page's `cspHeader` attribute is `true`** (API 55.0+) |92| `FieldServiceMobileExtension` | Field Service Mobile Extensions only (API 47.0+) |93| `LightningOut` | "Reserved for future use" (API 64.0+) |9495### The `endpointUrl` grammar9697Must include a domain name; may include a port. Wildcards are supported98(`*.example.com`). Third-party APIs must begin with `https://`; WebSockets must99begin with `wss://`. The value is a literal — build any templated URL before you100write it into the metadata.101102Malformed values (`malformed^url.example.com`, `https://{subdomain}.example.com`)103could be saved before February 2025 and are "excluded from generated CSP HTTP104headers" — an entry that looks Active and correct but has never been in the header.105106### The default for unset directives is version-dependent107108| API version of the deployment | If every `isApplicable*` is `false` |109|---|---|110| ≤ 49.0 | All of them default to `true` — an **open** grant |111| 50.0–58.0 | `isApplicableToImgSrc` is set to `true` |112| ≥ 59.0 | At least one `isApplicable*` or `canAccess*` must be `true`, or the deploy is rejected |113114Write every field explicitly, `true` and `false` alike.115116### Camera and microphone are `Permissions-Policy`, not CSP117118`canAccessCamera` and `canAccessMicrophone` (API 59.0+) are inert unless the org has119`enablePermissionsPolicy = true` and `grantCameraAccess` / `grantMicrophoneAccess`120= `TrustedUrls` in `SecuritySettings`.121122### Trusted URL is not Remote Site Setting123124| | Trusted URL | Remote Site Setting / Named Credential |125|---|---|---|126| Enforced by | The user's **browser**, via the CSP header | The Salesforce **application server** |127| Governs | LWC/Aura `fetch`, `<img>`, `<iframe>`, fonts, CSS, WebSockets | Apex `Http.send()`, Visualforce |128| Error text | `Refused to ... violates the following Content Security Policy directive` | `Unauthorized endpoint, please check Setup->Security->Remote site settings` |129130---131132## Common Patterns133134### Pattern A — one origin, one directive, one context135136The default and the correct shape for most cases. Read the console error, create137one record with one directive ticked and every other field explicitly `false`, and138put the depending component's name in `description`. Example 1 in139[`references/examples.md`](references/examples.md).140141### Pattern B — vendor the library into a static resource142143For third-party JavaScript, this is the answer rather than a Trusted URL, because144there is no `script-src` field to grant. Upload the library as a static resource145and load it with `loadScript` from `lightning/platformResourceLoader`; it is then146served from the org's own origin. This also pins the version.147148### Pattern C — one record per origin for a multi-host SDK149150A payment or analytics SDK needs several entries — loader, API, challenge iframe,151asset CDN. Enumerate them from the vendor's own CSP documentation in one pass, then152test the *failure and challenge* paths, because a 3-D Secure iframe or an error153beacon fires only there.154155### Pattern D — Apex proxy instead of a browser call156157When the call carries a credential, or the endpoint is internal and not158HTTPS-reachable from a browser, route it through Apex with a Named Credential. No159Trusted URL, no CORS, credentials never reach the browser.160161---162163## Decision Guidance164165| Situation | Approach |166|---|---|167| LWC needs to `fetch` an external JSON API | Trusted URL, `connect-src`, correct context |168| Component needs a third-party JS library | Static resource + `loadScript` — not a Trusted URL |169| Vendor mandates loading their script live | Vendor conversation and a documented risk acceptance; there is no per-URL `script-src` grant |170| Third-party widget in an iframe | Trusted URL, `frame-src`, plus `connect-src` for whatever the widget calls |171| Widget needs camera or microphone | `canAccess*` on the URL **and** `SecuritySettings` set to `TrustedUrls` |172| Apex callout is blocked | Remote Site Setting or Named Credential — not a Trusted URL |173| Internal service is HTTP-only | Apex proxy; CSP requires HTTPS and there is no exemption |174| Vendor hostnames genuinely rotate | Wildcard, with the reason recorded in `description` |175| Deadline pressure, widget still blocked | Escalate the enumeration, never Relaxed CSP |176177---178179## Recommended Workflow1801811. **Reproduce and read the violation.** Capture the full console message: it names182 both the blocked URL and the directive. One message per blocked origin.1832. **Classify the caller.** Browser-originated → Trusted URL. Apex-originated →184 Remote Site Setting or Named Credential. A feature doing both needs both.1853. **Enumerate every origin the feature needs** from the vendor's CSP186 documentation, and note which directive each one requires. Do not configure187 incrementally, one incident at a time.1884. **Decide the context** from the surfaces the component runs on, and emit one189 record per context rather than defaulting to `All`.1905. **Author `CspTrustedSite` metadata** with every directive field written191 explicitly, an exact host unless rotation genuinely requires a wildcard, and a192 `description` naming the depending feature.1936. **Verify the whole flow**, including the failure and challenge paths, and194 confirm no residual console violations.1957. **Add the entry to the quarterly review list** so it is removed when the feature196 is retired — the allow-list must shrink as well as grow.197198---199200## Review Checklist201202- [ ] The directive granted matches the directive named in the console error203- [ ] Every `isApplicableTo*` field is written explicitly, `true` or `false`204- [ ] `context` is set deliberately, not defaulted205- [ ] `endpointUrl` is an exact host unless a wildcard is justified in `description`206- [ ] `endpointUrl` has no template placeholders and no malformed characters207- [ ] `description` names the component or feature that depends on this entry208- [ ] Every origin the feature touches has an entry — loader, API, frame, CDN, beacon209- [ ] Third-party JavaScript is a static resource, not a live CDN load210- [ ] Camera/microphone grants are paired with the `SecuritySettings` change211- [ ] No Relaxed CSP anywhere in the solution212- [ ] Failure and challenge paths exercised, not just the happy path213- [ ] Entry recorded for quarterly review214215---216217## Salesforce-Specific Gotchas218219Full detail with quotes in [`references/gotchas.md`](references/gotchas.md).2202211. **Context is not a label** — a URL trusted in LEX is not trusted in Experience222 Cloud, and the record still shows as Active.2232. **There is no `script-src` checkbox.** Use a static resource.2243. **Inline handlers are blocked** and no configuration unblocks them.2254. **A malformed URL saves, shows Active, and is silently excluded** from the CSP226 header — the cause of "it's allow-listed and still blocked."2275. **The default for unset directives changed at API 50.0 and again at 59.0.**2286. **Camera and microphone need an org-level switch too.**2297. **A third-party script almost never talks to only its own origin.**2308. **The generated CSP header has a practical size ceiling** — keep it under 12 KB;231 problems are reported approaching 16 KB.2329. **Relaxed CSP is site-wide and effectively permanent.**23310. **HTTPS is mandatory**, including for resources inside your own org.23411. **Trusted URLs and Remote Site Settings solve different problems.**235236---237238## Output Artifacts239240| Artifact | Description |241|---|---|242| Origin inventory | Every host the feature touches, the directive each needs, and the vendor documentation it came from |243| `CspTrustedSite` metadata | One file per origin per context, every directive field explicit, `description` naming the dependent feature |244| `SecuritySettings` change | Only when camera or microphone access is required, deployed separately as an org-wide change |245| Verification note | Which flows were exercised, including failure and challenge paths, and confirmation of a clean console |246| Review entry | The record's name and owning feature added to the quarterly Trusted URL review |247248---249250## Related Skills251252- `lwc/static-resources-in-lwc` — the `loadScript` / `loadStyle` path that replaces253 a `script-src` grant, and how to package a vendored library254- `security/network-security-and-trusted-ips` — the network-layer controls that255 Trusted URLs are frequently confused with256- `integration/named-credentials-setup` — the server-side alternative when the call257 carries a credential or the endpoint cannot be browser-reachable