SharePoint Online's Support for Content Security Policy

As a SharePoint developer working with the SharePoint Framework (SPFx), I’ve been keeping a close eye on a new feature coming to SharePoint Online. Microsoft is currently rolling out Content Security Policy (CSP) support and enforcement in SharePoint Online.

If you’re building custom SPFx solutions, understanding what CSP is and how it works in SharePoint Online is essential. Let me walk you through the basics. In addition, I have a few asks to improve this new feature that I’ll share at the end of the article.

What is Content Security Policy?

In web development, Content Security Policy is a security feature that helps websites protect against various attack vectors, including cross-site scripting (XSS), clickjacking, and other code injection attacks. Think of CSP as a set of instructions that tell the browser what resources a page is allowed to load. It is a series of instructions the server sends to the browser, and all modern browsers respect it.

The source of a page contains references to multiple resources, including images, stylesheets, and JavaScript files. For the scripts, the browser checks these CSP instructions before loading any scripts.

How CSP Works in SharePoint Online

When a browser requests a script and CSP is enabled on the site, the browser checks the script location against the CSP rules. If the CSP restrictions allow the location of the script to be loaded, the browser proceeds with the request. However, if CSP rules don’t allow the location, the browser won’t load the script and logs an error in the browser’s console.

How CSP Affects SPFx Solutions

By default, SharePoint Online is configured to allow the browser to load scripts used to implement SharePoint Online, including scripts from custom SPFx solutions that include scripts in the SharePoint package (*.sppkg) deployment packages (the default setting for all SPFx projects since one of the very first releases).

When developers create new SPFx solutions, the default setting includes the JavaScript bundles that implement SPFx components in the package. When an SPFx app is installed, the assets included in the package are deployed to the site’s ClientSideAssets folder, which works seamlessly with the default CSP settings. Why? Because scripts served from SharePoint Online, among other locations, are part of the default CSP policy.

Microsoft is adding a new feature to SPO when administrators upload SharePoint solutions (*.sppkg) to app catalogs. Administrators will now see a list of external endpoints where the solution will load scripts.

Once the solution is enabled, the URL to the script is added to SPO’s new Trusted Script Sources list:

There’s a catch, though… unfortunately, this addresses only one way scripts can be loaded by a SPFx solution. In my opinion, this is something that should be addressed and improved with this new feature. I’ll address that, and more suggestions, at the end of the article in my section on how I think this should be improved.

There are several options for how scripts can be loaded in SPFx solutions, and some of these require special CSP considerations:

Option 1: Deploy SPFx Scripts to an External CDN

Developers can configure SPFx solutions to not include the JavaScript bundles in the package and instead deploy these scripts to their locations. For instance, vendors might elect to deploy scripts to their own managed Content Delivery Network (CDN).

To implement this scenario, developers configure the SharePoint package to load scripts from a remote domain by setting the cdnBasePath property in the ./config/write-manifests.json file. They must then deploy the scripts to that location in addition to deploying the SharePoint package (*.sppkg) to the SharePoint Online App Catalog.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/write-manifests.schema.json",
  "cdnBasePath": "https://cdn.voitanos.io/mastering-spfx-ch18deployment"
}

The good news is that SharePoint Online handles this automatically. When an SPFx solution using this approach is installed, SharePoint Online detects it and notifies the administrator where the scripts are loaded from, as shown in the following image:

In addition, SharePoint Online will automatically add the value set in the project’s cdnBasePath to the list of allowed domains where scripts can be loaded in the SharePoint Online Admin Center (SPAC).

Option 2: Pull Script Dependencies from a CDN

Another common scenario occurs when an SPFx solution takes a dependency on a popular library. Instead of including it in the SPFx component’s JavaScript bundle, developers can configure the solution to exclude it from the bundle and instruct the SPFx runtime to pull the library from a remote CDN prior to loading the bundle.

This is done by adding the external script reference to the externals property in the ./config/config.json file.

However, unlike Option 1, this requires manually adding an entry in the SPAC’s Trusted Script Sources list as it’s not automatically picked up by SPO.

Option 3: Dynamically Load a Script with the SPComponent Loader

Another option developers can implement is to conditionally load a script through code using the SPComponentLoader:

async SPComponentLoader.loadScript('https://some-external-site/script.js');

Like option 2 above, this option requires manually adding an entry in the SPAC’s Trusted Script Sources list as it’s not automatically picked up by SPO.

Managing CSP Rules in SharePoint Online

SharePoint administrators can manage CSP rules through the SharePoint Online Admin Center by navigating to to the Trusted Script Sources page: SPAC > Advanced > Script Sources:

Administrators can add new entries by selecting Add source or edit existing entries.

• Source: expression must be a valid CSP expression
• Status: indicates how each entry was added to the list - entries automatically added from SPFx packages show as “Imported from app catalog” while manually added or edited entries show as “Added from script sources”

Monitoring CSP Violations

When the browser requests a script that violates the SPO CSP settings, it displays a message in the browser’s console and logs it to Microsoft Purview.

Viewing Violations in the Browser Console

The browser logs CSP violations in SPO to the console, displaying error messages that indicate which script violated the policy and what the current CSP directive allows.

I went back and deleted the entry in the Trusted Script Sources page, then added the web part to a page in my tenant. Notice the CSP policy now treats this as a violation by logging it to the browser’s console:

The list in the screenshot is a little hard to read, so I’ve added line breaks and shared it below. Notice the first line says our custom script is not allowed by the SPO CSP policy:

[Report Only]
Refused to load the script
'https://cdn.voitanos.io/mastering-spfx-ch18deployment/VtnsAzureCdnWebPart[..].js'
because it violates the following Content Security Policy directive:
"script-src 'unsafe-eval' 'self'
https://contentstorage.osi.office.net
https://swx.cdn.skype.com
https://res.delve.office.com
https://lpcres.delve.office.com
https://widget.uservoice.com
https://by2.uservoice.com
https://www.bing.com/api/maps
https://www.bing.com/rms
https://fabriciss.azureedge.net
https://ajax.aspnetcdn.com
https://js.monitor.azure.com
https://r4.res.office365.com
https://public-cdn.sharepointonline.com
https://teams.microsoft.com
*.cdn.office.net
*.fluidpreview.office.net
*.onecdn.static.microsoft
https://webshell.suite.office.com
https://amcdn.msftauth.net
https://res-1.cdn.office.net
https://webshell.suite.officeppe.com
https://res-2.public.onecdn.static.microsoft
https://df.loki.delve.office.com
https://c5-excel-15.cdn.office.net
https://c5-onenote-15.cdn.office.net
https://c5-powerpoint-15.cdn.office.net
https://c5-visio-15.cdn.office.net
https://c5-word-view-15.cdn.office.net
https://res-2.df.onecdn.static.microsoft
https://res-1.df.onecdn.static.microsoft
https://res-3-sdf.cdn.office.net
https://shell.cdn.office.net
'nonce-1315956a-d00e-4886-a4a9-6e23fc383e95'".
Note that 'script-src-elem' was not explicitly set, so 'script-src' is used as a fallback.

Viewing Violations in Microsoft Purview

SharePoint Online logs CSP violations to Microsoft Purview. Administrators can navigate to the Audit solution in Microsoft Purview from the Microsoft 365 Admin Center and search for the Activity with the friendly name Violated Content Security Policy or operation name ViolatedContentSecurityPolicy:

When selecting a search result, the side panel shows audit details including:

• DocumentUrl: The page in the SharePoint Online site where the CSP violation occurred
• BlockedUrl: The URL of the script that violated the CSP configuration

Remember, don’t start freaking out that all your custom solutions are going to start breaking.

As I said above, while this feature is rolling out in SharePoint Online now, it’s not being enforced… yet. At this time, scripts that violate the CSP configuration are just being reported in the browser’s console and logged as findings in the Microsoft Purview Audit solution. This will give you visibility into solutions that you’ll need to address before the enforcement of the CSP settings in your tenant takes effect.

When will CSP in SPO be Enforced?

It’s my understanding that Microsoft plans to start enforcing CSP support in SharePoint Online in Q4 of 2025.

While this may change, you have plenty of time to watch your tenant using the tools provided to make the appropriate changes to your solutions and your tenant.

But, I’d keep an eye on the Microsoft 365 Message Center for updates on the enforcement timeline

How to Address CSP Violations

What happens when you see entries of CSP violations in your Microsoft Purview Audit solution or in your browser’s console?

You have two options:

1. Add the script’s domain to the Trusted Script Sources list in the SharePoint Online Admin Center. This is a great solution when you trust the source where the script is being loaded from.
2. Update the SPFx solution to either deploy the script to the ClientSideAssets library by including it in the package.

There’s no other solution. Ultimately, the scripts your solution needs to load must be at a URL that the SPO CSP settings trust. If that’s not one of the default URLs, you must add it to the Trusted Script Sources.

Areas For Improvement with SPO’s Support for CSP

Now you know what CSP, how SharePoint Online is implementing the support for it, how it will impact your solutions, and how to address violations, I have some suggestions & asks of Microsoft for this feature that I think will improve it for SharePoint Online tenant administrators and SPFx developers alike.

My motivation for all three of these proposals is to:

1. make it clear for tenant administrators to easily see & manage what external scripts are loaded from outside the tenant
2. make it easier for developers to communicate what a solution needs & uses to the tenant administrators

My three (3) suggestions are as follows:

Suggestion #1: Rename Trusted Script Sources

Names matter. Call it what it is.

An administrator has been made aware of a script that should be allowed, but is being blocked by the CSP configuration in their SPO tenant. So the go to the SPAC to address this, only they can’t find anything in the navigation or settings that talk about CSP, a content policy, a security policy, or anything close to it.

The name that was chosen (Trusted Script Sources) for the page where you manage CSP and the associated menu item (Script Sources) doesn’t make sense.

The Microsoft 365 naming department is at it again, thinking they have to get cute & unique. Why make it hard?

💡✅ This should be renamed to CSP Config or CSP Settings in the menu & call the page Content Security Policy Settings.

At least Purview got it right…

Suggestion #2: Automatically Detect Remote [External] URLs

SPO is currently detecting the remote location where a SharePoint solution’s bundles are stored when uploading a page, but it should do the same for the URLs the developer has defined for scripts listed as dependencies. This is a common and good practice by developers to exclude third-party-libraries out of the generated bundle.

This scenario is MUCH more common than loading the bundle from outside of SharePoint Online.

For example, the following excerpt from a SPFx project’s ./config/config.json file lists two libraries loaded from remote CDNs:

• https://code.jquery.com/jquery-1.12.4.js
• https://cdn.datatables.net/1.10.12/js/jquery.dataTables.min.js

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/config.2.0.schema.json",
  "version": "2.0",
  "bundles": {
    "j-query-data-tables-web-part": {
      "components": [ .. ]
    }
  },
  "externals": {
    "jquery": {
      "path": "https://code.jquery.com/jquery-1.12.4.js",
      "globalName": "jQuery"
    },
    "datatables": {
      "path": "https://cdn.datatables.net/1.10.12/js/jquery.dataTables.min.js",
      "globalName": "jQuery",
      "globalDependencies": [ "jquery" ]
    }
  },
  "localizedResources": {
    "JQueryDataTablesWebPartStrings": "lib/webparts/jQueryDataTables/loc/{locale}.js"
  }
}

💡✅  The process of deploying the SharePoint solution (*.sppkg) should automatically detect these scripts as well, located in the generated component manifest, just like it does when you don’t include the bundle in the package. These should be shown to the administrator and added to the list of allowed scripts.

So, for the above example, I’d expect to see the following when I deploy the SharePoint solution in an app catalog:

Upon deployment, by selecting the Enable app button, I would expect these script URLs would be added to the Trusted Script Sources list without manual interaction.

Suggestion #3: Act Like Permission Requests: Let Developers Set Their Own URLs

I can see some scenarios where the last suggestion of automatically detecting URLs from the externals object in the config is not ideal… maybe you don’t want to list every single script URL in the Trusted Script Sources page and rather you just want to include a full domain such as the popular CDN URLs cdn.jsdelivr.com or esm.run from jsDelivr that hosts popular JavaScript bundles.

Or maybe you want to list remote URLs you generate in your code programmatically or using the SPComponentLoader API.

💡✅ Developers should have an option, similar to how you can include permission requests in the SharePoint solution package with the webApiPermissionRequests. This proposal could be in addition to, or instead of, my previous recommendation. Ideally, it’s in addition to the previous proposal.

In addition, follow the same pattern SPO already follows with permission requests. When present, SPO will add a permission request that must be approved by an administrator. Shouldn’t loading scripts from locations that aren’t in the default list of allowed domains in the default CSP configuration require an extra step, as they can be just as dangerous as granting permissions?

Here’s what I’d like to see:

• Add an array property cspUrlRequests, for CSP URL requests to the package-solution.json file:

  {
    "solution": {
      "name": "vtns-azure-cdn-client-side-solution",
      "id": "0183e69e-a4a3-4688-9a78-713c5da96a4c",
      "version": "1.0.0.0",
      "includeClientSideAssets": false,
      "skipFeatureDeployment": true,
      "isDomainIsolated": false,
      "cspUrlRequests": [
        "https://cdn2.voitanos.io",
        "https://cdn3.voitanos.io"
      ],
      // ..
    },
    "paths": {
      "zippedPackage": "solution/vtns-azure-cdn.sppkg"
    }
  }
  

• When deployed, SPO would union all the CSP URLs & create permission requests for them. This list would be generated from the following locations:

  • The current CSP support implementation which is automatically detects the change to the cdnBasePath property in the write-manifests.json file.
  • From my previous suggestion, those URLs automatically detecting remote scripts listed as dependencies are listed in the externals property of the config.json file.
  • URLs defined in my proposed cspUrlRequests property in the package-solution.json file

This pattern follows the same pattern Microsoft is already using for permission requests, highlighted in the blue box above.

Conclusion & What This Means for My Development Workflow

As CSP continues rolling out in SharePoint Online, I’m doing the following with my solutions & recommending my students do the same:

1. Test existing SPFx solutions to identify any CSP violations
2. Review any external script dependencies and ensure they’re properly configured in the SPAC Trusted Script Sources page
3. Monitor Microsoft Purview for CSP violations (and use the browser console for debugging)

The key takeaway is that if I include resources in my SharePoint package (the default configuration), CSP settings won’t impact my solution. But if I’m loading scripts from external sources, I need to ensure those sources are properly configured in the Trusted Script Sources.

This rollout gives us developers a valuable opportunity to prepare our solutions before enforcement begins, ensuring our custom SharePoint solutions continue to work seamlessly while benefiting from enhanced security protections.

What do you think about my suggestions?

Do you have any ideas around this new feature?

Let me know by leaving a comment below! 👇

author

Andrew Connell

Microsoft MVP, Full-Stack Developer & Chief Course Artisan - Voitanos LLC.

Andrew Connell is a full stack developer who focuses on Microsoft Azure & Microsoft 365. He’s a 20+ year recipient of Microsoft’s MVP award and has helped thousands of developers through the various courses he’s authored & taught. Whether it’s an introduction to the entire ecosystem, or a deep dive into a specific software, his resources, tools, and support help web developers become experts in the Microsoft 365 ecosystem, so they can become irreplaceable in their organization.

Feedback & Questions