Use the Office 365 Content Delivery Network (CDN) with SharePoint Online

• 02/19/2020
• 41 minutes to read

In this article

You can use the built-in Office 365 Content Delivery Network (CDN) to host static assets to provide better performance for your SharePoint Online pages. The Office 365 CDN improves performance by caching static assets closer to the browsers requesting them, which helps to speed up downloads and reduce latency. Also, the Office 365 CDN uses the HTTP/2 protocol for improved compression and HTTP pipelining. The Office 365 CDN service is included as part of your SharePoint Online subscription.

The Office 365 CDN is composed of multiple CDNs that allow you to host static assets in multiple locations, or origins, and serve them from global high-speed networks. Depending on the kind of content you want to host in the Office 365 CDN, you can add public origins, private origins or both. See Choose whether each origin should be public or private for more information on the difference between public and private origins.

If you are already familiar with the way that CDNs work, you only need to complete a few steps to enable the Office 365 CDN for your tenant. This topic describes how. Read on for information about how to get started hosting your static assets.

Head back to Network planning and performance tuning for Office 365.

Overview of working with the Office 365 CDN in SharePoint Online

To set up the Office 365 CDN for your organization, you follow these basic steps:

Once you're done with setup, you can Manage the Office 365 CDN over time by:

• Adding, updating, and removing assets
• Adding and removing origins
• Configuring CDN policies
• If necessary, disabling the CDN

Finally, see Using your CDN assets to learn about accessing your CDN assets from both public and private origins.

See Troubleshooting the Office 365 CDN for guidance on resolving common issues.

Plan for deployment of the Office 365 CDN

Before you deploy the Office 365 CDN for your Office 365 tenant, you should consider the following factors as part of your planning process.

Determine which static assets you want to host on the CDN

In general, CDNs are most effective for hosting static assets, or assets that don't change very often. A good rule of thumb is to identify files that meet some or all of these conditions:

• Static files embedded in a page (like scripts and images) that may have a significant incremental impact on page load times
• Large files like executables and installation files
• Resource libraries that support client-side code

For example, small files that are repeatedly requested like site images and scripts can significantly improve site rendering performance and incrementally reduce the load on your SharePoint Online sites when you add them to a CDN origin. Larger files such as installation executables can be downloaded from the CDN, delivering a positive performance impact and subsequent reduction of the load on your SharePoint Online site, even if they are not accessed as often.

Performance improvement on a per-file basis is dependent on many factors, including the client's proximity to the nearest CDN endpoint, transient conditions on the local network, and so forth. Many static files are quite small, and can be downloaded from Office 365 in less than a second. However, a web page may contain many embedded files with a cumulative download time of several seconds. Serving these files from the CDN can significantly reduce the overall page load time. See What performance gains does a CDN provide? for an example.

Determine where you want to store your assets

The CDN fetches your assets from a location called an origin. An origin can be a SharePoint site, document library or folder that is accessible by a URL. You have great flexibility when you specify origins for your organization. For example, you can specify multiple origins or a single origin where you want to put all your CDN assets. You can choose to have both public or private origins for your organization. Most organizations will choose to implement a combination of the two.

You can create new container for your origins such as folders or document libraries, and add files you want to make available from the CDN. This is a good approach if you have a specific set of assets you want to be available from the CDN, and want to restrict the set of CDN assets to only those files in the container.

You can also configure an existing site collection, site, library or folder as an origin, which will make all eligible assets in the container available from the CDN. Before you add an existing container as an origin, it's important to make sure you are aware of its contents and permissions so you do not inadvertently expose assets to anonymous access or unauthorized users.

You can define CDN policies to exclude content in your origins from the CDN. CDN policies exclude assets in public or private origins by attributes such as file type and site classification, and are applied to all origins of the CdnType (private or public) you specify in the policy. For example, if you add a private origin consisting of a site that contains multiple subsites, you can define a policy to exclude sites marked as Confidential so content from sites with that classification applied will not be served from the CDN. The policy will apply to content from all private origins you have added to the CDN.

Keep in mind that the greater the number of origins, the greater the impact on the time it takes the CDN service to process requests. We recommend that you limit the number of origins as much as possible.

Choose whether each origin should be public or private

When you identify an origin, you specify whether it should be made public or private. Access to CDN assets in public origins is anonymous, and CDN content in private origins is secured by dynamically generated tokens for greater security. Regardless of which option you choose, Microsoft does all the heavy lifting for you when it comes to administration of the CDN itself. Also, you can change your mind later, after you've set up the CDN and identified your origins.

Both public and private options provide similar performance gains, but each has unique attributes and advantages.

Public origins within the Office 365 CDN are accessible anonymously, and hosted assets can be accessed by anyone who has the URL to the asset. Because access to content in public origins is anonymous, you should only use them to cache non-sensitive generic content such as JavaScript files, scripts, icons and images.

Private origins within the Office 365 CDN provide private access to user content such as SharePoint Online document libraries, sites and proprietary images. Access to content in private origins is secured by dynamically generated tokens so it can only be accessed by users with permissions to the original document library or storage location. Private origins in the Office 365 CDN can only be used for SharePoint Online content, and you can only access assets in private origins through redirection from your SharePoint Online tenant.

You can read more about how CDN access to assets in a private origin works in Using assets in private origins.

Attributes and advantages of hosting assets in public origins

• Assets exposed in a public origin are accessible by everyone anonymously.

  Important

  You should never place resources that contain user information or are considered sensitive to your organization in a public origin.

• If you remove an asset from a public origin, the asset may continue to be available for up to 30 days from the cache; however, we will invalidate links to the asset in the CDN within 15 minutes.

• When you host style sheets (CSS files) in a public origin, you can use relative paths and URIs within the code. This means that you can reference the location of background images and other objects relative to the location of the asset that's calling it.

• While you can construct a public origin's URL, you should proceed with caution and ensure you utilize the page context property and follow the guidance for doing so. The reason for this is that if access to the CDN becomes unavailable, the URL will not automatically resolve to your organization in SharePoint Online and might result in broken links and other errors. The URL is also subject to change which is why it should not just be hard coded to its current value.

• The default file types that are included for public origins are .css, .eot, .gif, .ico, .jpeg, .jpg, .js, .map, .png, .svg, .ttf, .woff and .woff2. You can specify additional file types.

• You can configure a policy to exclude assets that have been identified by site classifications that you specify. For example, you can choose to exclude all assets that are marked as "confidential" or "restricted" even if they are an allowed file type and are located in a public origin.

Attributes and advantages of hosting assets in private origins

• Private origins can only be used for SharePoint Online assets.

• Users can only access the assets from a private origin if they have permissions to access the container. Anonymous access to these assets is prevented.

• Assets in private origins must be referred from the SharePoint Online tenant. Direct access to private CDN assets does not work.

• If you remove an asset from the private origin, the asset may continue to be available for up to an hour from the cache; however, we will invalidate links to the asset in the CDN within 15 minutes of the asset's removal.

• The default file types that are included for private origins are .gif, .ico, .jpeg, .jpg, .js, and .png. You can specify additional file types.

• Just like with public origins, you can configure a policy to exclude assets that have been identified by site classifications that you specify even if you use wildcards to include all assets within a folder or document library.

For more information about why to use the Office 365 CDN, general CDN concepts, and other Microsoft CDNs you can use with your Office 365 tenant, see Content Delivery Networks.

Default CDN origins

Unless you specify otherwise, Office 365 sets up some default origins for you when you enable the Office 365 CDN. If you initially opt not to provision them, you can add these origins after you complete setup. Unless you understand the consequences of skipping the setup of default origins and have a specific reason for doing so, you should allow them to be created when you enable the CDN.

Default private CDN origins:

• */userphoto.aspx
• */siteassets

Default public CDN origins:

• */masterpage
• */style library
• */clientsideassets

Set up and configure the Office 365 CDN by using the SharePoint Online Management Shell

The procedures in this section require you to use the SharePoint Online Management Shell to connect to SharePoint Online. For instructions, see Connect to SharePoint Online PowerShell.

Complete these steps to set up and configure the CDN to host your assets in SharePoint Online using the SharePoint Online Management Shell.

Click to expand

Set up and configure the Office 365 CDN by using PnP PowerShell

The procedures in this section require you to use PnP PowerShell to connect to SharePoint Online. For instructions, see Getting started with PnP PowerShell.

Complete these steps to set up and configure the CDN to host your assets in SharePoint Online using PnP PowerShell.

Click to expand

Set up and configure the Office 365 CDN using the Office 365 CLI

The procedures in this section require that you have installed the Office 365 CLI. Next, connect to your Office 365 tenant using the login command.

Complete these steps to set up and configure the CDN to host your assets in SharePoint Online using the Office 365 CLI.

Click to expand

spo cdn set --type Public --enabled true

spo cdn set --type Private --enabled true

spo cdn get --type Public

spo cdn origin list --type Public

spo cdn origin add --type [Public | Private] --origin <path>

spo cdn origin add --type Public --origin */masterpage

spo cdn origin add --type Private --origin sites/site1/siteassets

spo cdn origin remove --type Public --origin */masterpage

spo cdn policy set --type Public --policy IncludeFileExtensions --value "CSS,EOT,GIF,ICO,JPEG,JPG,JS,MAP,PNG,SVG,TTF,WOFF,JSON"

spo cdn policy set --type Public --policy ExcludeRestrictedSiteClassifications --value "HBI"

spo cdn set --type Public --enabled false

Using your CDN assets

Now that you have enabled the CDN and configured origins and policies, you can begin using your CDN assets.

This section will help you understand how to use CDN URLs in your SharePoint pages and content so that SharePoint redirects requests for assets in both public and private origins to the CDN.

For information on how to use the CDN for hosting client-side web parts, see the topic Host your client-side web part from Office 365 CDN (Hello World part 4).

Updating links to CDN assets

To use assets that you have added to an origin, you simply update links to the original file with the path to the file in the origin.

• Edit the page or content that contains links to assets you have added to an origin. You can also use one of several methods to globally search and replace links across an enter site or site collection if you want to update the link to a given asset everywhere it appears.
• For each link to an asset in an origin, replace the path with the path to the file in the CDN origin. You can use relative paths.
• Save the page or content.

For example, consider the image /site/SiteAssets/images/image.png, which you have copied to the document library folder /site/CDN_origins/public/. To use the CDN asset, replace the original path to the image file location with the path to the origin to make the new URL /site/CDN_origins/public/image.png.

If you want to use the full URL to the asset instead of a relative path, construct the link like so:

https://<TenantHostName>.sharepoint.com/sites/site/CDN_origins/public/image.png

To learn about how to verify that assets are being served from the CDN, see How do I confirm that assets are being served by the CDN? in Troubleshooting the Office 365 CDN.

Using assets in public origins

The Publishing feature in SharePoint Online automatically rewrites URLs of assets stored in public origins to their CDN equivalents so that assets are served from the CDN service instead of SharePoint.

If your origin is in a site with the Publishing feature enabled, and the assets you want to offload to the CDN are in one of the following categories, SharePoint will automatically rewrite URLs for assets in the origin, provided that the asset has not been excluded by a CDN policy.

The following is an overview of which links are automatically rewritten by the SharePoint Publishing feature:

• IMG/LINK/CSS URLs in classic publishing page HTML responses
  • This includes images added by authors within the HTML content of a page
• Picture Library SlideShow webpart image URLs
• Image fields in SPList REST API (RenderListDataAsStream) results
  • Use the new property ImageFieldsToTryRewriteToCdnUrls to provide a comma separated list of fields
  • Supports hyperlink fields and PublishingImage fields
• SharePoint image renditions

The following diagram illustrates the workflow when SharePoint receives a request for a page containing assets from a public origin.

Constructing CDN URLs for public assets

If the Publishing feature is not enabled for a public origin, or the asset is not one of the link types supported by the auto-rewrite feature of the CDN service, you can manually construct URLs to the CDN location of the assets and use these URLs in your content.

For public CDN assets, the URL format will look like the following:

https://publiccdn.sharepointonline.com/<TenantHostName>/sites/site/library/asset.png

Replace TenantHostName with your tenant name. Example:

https://publiccdn.sharepointonline.com/contoso.sharepoint.com/sites/site/library/asset.png

Using assets in private origins

No additional configuration is required to use assets in private origins. SharePoint Online automatically rewrites URLs for assets in private origins so requests for those assets will always be served from the CDN. You cannot manually build URLs to CDN assets in private origins because these URLs contain tokens that must be auto-generated by SharePoint Online at the time the asset is requested.

Access to assets in private origins is protected by dynamically generated tokens based on user permissions to the origin, with the caveats described in the following sections. Users must have at least read access to the origins for the CDN to render content.

The following diagram illustrates the workflow when SharePoint receives a request for a page containing assets from a private origin.

Token-based authorization in private origins

Access to assets in private origins in the Office 365 CDN is granted by tokens generated by SharePoint Online. Users who already have permission to access to the folder or library designated by the origin are automatically granted tokens that permit the user to access the file based on their permission level. These access tokens are valid for 30 to 90 minutes after they are generated to help prevent token replay attacks.

Once the access token is generated, SharePoint Online returns a custom URI to the client containing two authorization parameters eat (edge authorization token) and oat (origin authorization token). The structure of each token is <'expiration time in Epoch time format'>__<'secure signature'>. For example:

https://privatecdn.sharepointonline.com/contoso.sharepoint.com/sites/site1/library1/folder1/image1.jpg?eat=1486154359_cc59042c5c55c90b26a2775323c7c8112718431228fe84d568a3795a63912840&oat=1486154359_7d73c2e3ba4b7b1f97242332900616db0d4ffb04312

Item-level permissions are not supported for assets in private origins

It is important to note that SharePoint Online does not support item-level permissions for assets in private origins. For example, for a file located at https://contoso.sharepoint.com/sites/site1/library1/folder1/image1.jpg, users have effective access to the file given the following conditions:

Troubleshooting the Office 365 CDN

How do I confirm that assets are being served by the CDN?

Once you have added links to CDN assets to a page, you can confirm that the asset is being served from the CDN by browsing to the page, right clicking on the image once it has rendered and reviewing the image URL.

You can also use your browser's developer tools to view the URL for each asset on a page, or use a third party network trace tool.

You cannot test CDN URLs directly in a web browser because you must have a referer coming from SharePoint Online. However, if you add the CDN asset URL to a SharePoint page and then open the page in a browser, you will see the CDN asset rendered on the page.

For more information on using the developer tools in the Microsoft Edge browser, see Microsoft Edge Developer Tools.

To watch a short video hosted in the SharePoint Developer Patterns and Practices YouTube channel demonstrating how to verify that your CDN is working, please see Verifying your CDN usage and ensuring optimal network connectivity.

Why are assets from a new origin unavailable?

Assets in new origins will not immediately be available for use, as it takes time for the registration to propagate through the CDN and for the assets to be uploaded from the origin to CDN storage. The time required for assets to be available in the CDN depends on how many assets and the files sizes.

My client-side web part or SharePoint Framework solution isn't working

When you enable the Office 365 CDN for public origins, the CDN service automatically creates these default origins:

• */MASTERPAGE
• */STYLE LIBRARY
• */CLIENTSIDEASSETS

If the */clientsideassets origin is missing, SharePoint Framework solutions will fail, and no warning or error messages are generated. This origin may be missing either because the CDN was enabled with the -NoDefaultOrigins parameter set to $true, or because the origin was manually deleted.

You can check to see which origins are present with the following PowerShell command:

Get-SPOTenantCdnOrigins -CdnType Public

Or you can check with the Office 365 CLI:

spo cdn origin list

To add the origin in PowerShell:

Add-SPOTenantCdnOrigin -CdnType Public -OriginUrl */CLIENTSIDEASSETS

To add the origin in the Office 365 CLI:

spo cdn origin add --origin */CLIENTSIDEASSETS

What PowerShell modules and CLI shells do I need to work with the Office 365 CDN?

You can choose to work with the Office 365 CDN using either the SharePoint Online Management Shell PowerShell module or the Office 365 CLI.

See also

Content Delivery Networks

Network planning and performance tuning for Office 365

SharePoint Performance Series - Office 365 CDN video series

Recommended content

• Office 365 Content Delivery Network (CDN) Quickstart - Microsoft 365 Enterprise

  Office 365 Content Delivery Network (CDN) Quickstart

• Distribute business apps using the App Catalog - SharePoint - SharePoint in Microsoft 365

  Learn how SharePoint admins can use the SharePoint App Catalog site to upload and install (deploy) custom business apps and third-party apps.

• Use the Page Diagnostics tool for SharePoint Online - Microsoft 365 Enterprise

  Use the Page Diagnostics for SharePoint tool to analyze SharePoint Online modern portal and classic publishing pages against a pre-defined set of performance criteria.

• Tune SharePoint Online performance - Microsoft 365 Enterprise

  Contains links to other articles that tell you how to improve performance of page download times for SharePoint Online.