Use the Office 365 content delivery network with SharePoint Online

You can host static assets in the Office 365 content delivery network (CDN) to provide better performance for your SharePoint Online pages. Static assets are files that don't change very often, like images, video and audio, style sheets, fonts, and JavaScript files. The CDN works as a geographically distributed caching proxy, by caching static assets closer to the browsers requesting them.

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

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

Office 365 CDN  basics

The Office 365 CDN is included as part of your SharePoint Online subscription. You don't have to pay extra for it. Office 365 provides support for both private and public access and allows you to host static assets in multiple locations, or origins. The Office 365 CDN is not the same as the Azure CDN. If you need more information about why to use a CDN or about general CDN concepts, see Content delivery networks.

How the CDN grants access to end users

Private access to static assets 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 will automatically be granted tokens. SharePoint Online does not support item-level permissions for the CDN.

For example, for a file located at https://contoso.sharepoint.com/sites/site1/library1/folder1/image1.jpg, given the following:

  • User 1 has access to folder1 and to image1.jpg

  • User 2 does not have access to folder1

  • User 3 does not have access to folder1 but is granted explicit permission to access image1.jpg through SharePoint Online

  • User 4 has access to folder1 but has been explicitly denied access to image1.jpg

Then the following are true:

  • User 1 and User 4 will be able to access image1.jpg through the CDN.

  • User 2 and User 3 will not be able to access image1.jpg through the CDN.

    However, User 3 can still access the asset image1.jpg directly through SharePoint Online while User 4 cannot access the asset through SharePoint Online.

Overview of working with the Office 365 CDN

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

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

  • Adding, updating, and removing assets

  • Adding and removing origins

  • Configuring CDN policies

  • If necessary, disabling the Office 365 CDN

Determine where you want to store your assets

The CDN fetches your assets from a location called an origin. For Office 365, an origin is a SharePoint 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.

If you define hundreds of origins, it will likely have a negative impact on the time it takes to process requests. We recommend that if you have more than about 100 origins you might want to rethink your architecture.

Choose whether each origin should be public or private

When you identify an origin, you specify whether it should be made public or private. 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 performance improvements, but each has unique attributes and advantages.

Attributes and advantages of hosting assets in a public origin   

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

    Important: If you identify a public origin in your CDN, you should never place resources that are considered sensitive to your organization in a public origin or SharePoint Online library.

  • 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 hard code a public origin's URL, doing so is not recommended. 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 default file types that are included for public origins are .css, .eot, .gif, .ico, .jpeg, .jpg, .js, .map, .png, .svg, .ttf, and .woff. You can specify additional file types.

  • If you want, 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 a private origin   

  • Users can only access the assets from a private origin if they are authorized to do so. Anonymous access to these assets is prevented.

  • 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.

  • 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 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 Site Library.

Default Office 365 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 exclude them, you can add these origins after you complete setup.

Default private origins:

  • */userphoto.aspx

  • */siteassets

Default public origins:

  • */masterpage

  • */style library

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

The procedures in this topic 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 Office 365 CDN to host your static assets in SharePoint Online.

To enable your organization to use the Office 365 CDN

Use the Set-SPOTenantCdnEnabled cmdlet to enable your organization to use the Office 365 CDN. You can enable your organization to use either public origins, private origins, or both with the CDN. You can also configure the Office 365 CDN to skip the setup of default origins when you enable it. You can always add these origins later as described in this topic.

In Windows Powershell for SharePoint Online:

Set-SPOTenantCdnEnabled -CdnType <Public | Private | Both> -Enable $true

For example, to enable your organization to use both public and private origins with the CDN, type the following command:

Set-SPOTenantCdnEnabled -CdnType Both -Enable $true

To enable your organization to use both public and private origins with the CDN but skip setting up the default origins, type the following command:

Set-SPOTenantCdnEnabled -CdnType Both -Enable $true -NoDefaultOrigins

To enable your organization to use public origins with the CDN, type the following command:

Set-SPOTenantCdnEnabled -CdnType Public -Enable $true

To enable your organization to use private origins with the CDN, type the following command:

Set-SPOTenantCdnEnabled -CdnType Private -Enable $true

For more information about this cmdlet, see Set-SPOTenantCdnEnabled.

(Optional) To change the list of file types to include in the Office 365 CDN

Tip: When you define file types by using the Set-SPOTenantCdnPolicy cmdlet, you overwrite the currently defined list. If you want to add additional file types to the list, use the cmdlet first to find out what file types are already allowed and include them in the list along with your new ones.

Use the Set-SPOTenantCdnPolicy cmdlet to define static file types that can be hosted by public and private origins in the CDN. By default, common asset types are allowed, for example .css, .gif, .jpg, and .js.

In Windows PowerShell for SharePoint Online:

Set-SPOTenantCdnPolicy -CdnType <Public | Private> -PolicyType IncludeFileExtensions -PolicyValue "<Comma-separated list of file types>"

To see what file types are currently allowed by the CDN, use the Get-SPOTenantCdnPolicies cmdlet:

Get-SPOTenantCdnPolicies -CdnType <Public | Private>

For more information about these cmdlets, see Set-SPOTenantCdnPolicy and Get-SPOTenantCdnPolicies.

(Optional) To change the list of site classifications you want to exclude from the Office 365 CDN

Tip: When you exclude site classifications by using the Set-SPOTenantCdnPolicy cmdlet, you overwrite the currently defined list. If you want to exclude additional site classifications, use the cmdlet first to find out what classifications are already excluded and then add them along with your new ones.

Use the Set-SPOTenantCdnPolicy cmdlet to exclude site classifications that you do not want to make available over the CDN. By default, no site classifications are excluded.

In Windows PowerShell for SharePoint Online:

Set-SPOTenantCdnPolicy -CdnType <Public | Private> -PolicyType ExcludeRestrictedSiteClassifications  -PolicyValue "<Comma-separated list of site classifications>"

To see what site classifications are currently restricted, use the Get-SPOTenantCdnPolicies cmdlet:

Get-SPOTenantCdnPolicies -CdnType <Public | Private>

For more information about these cmdlets, see Set-SPOTenantCdnPolicy and Get-SPOTenantCdnPolicies.

To add an origin for your assets

Use the Add-SPOTenantCdnOrigin cmdlet to define an origin. You can define multiple origins. The origin is a URL that points to a SharePoint library or folder that contains the assets that you want to be hosted by the CDN.

Important: If you identify a public origin in your CDN, you should never place resources that are considered sensitive to your organization in the public origin or SharePoint Online library.

Add-SPOTenantCdnOrigin -CdnType <Public | Private> -OriginUrl <path>

Where path is the path to the folder that contains the assets. You can use wildcards in addition to relative paths. For example, to include all of the assets in the masterpages folder for all of your sites as a public origin within the CDN, type the following command:

Add-SPOTenantCdnOrigin -CdnType Public -OriginUrl */masterpage

For more information about this command and its syntax, see Add-SPOTenantCdnOrigin.

Once you've run the command, the system synchronizes the configuration across the datacenter. This takes 15 minutes.

Example: Configure a public origin for your master pages and for your style library for SharePoint Online

Normally, these origins are set up for you by default when you enable public origins for the Office 365 CDN. However, if you want to enable them manually, follow these steps.

  • Use the Add-SPOTenantCdnOrigin cmdlet to define the style library as a public origin within the Office 365 CDN.

    Add-SPOTenantCdnOrigin -CdnType Public -OriginUrl */style%20library
  • Use the Add-SPOTenantCdnOrigin cmdlet to define the master pages as a public origin within the Office 365 CDN.

    Add-SPOTenantCdnOrigin -CdnType Public -OriginUrl */masterpage
  • For more information about this command and its syntax, see Add-SPOTenantCdnOrigin.

    Once you've run the command, the system synchronizes the configuration across the datacenter. This takes 15 minutes.

Example: Configure a private origin for your site assets, site pages, and publishing images for SharePoint Online

  • Use the Add-SPOTenantCdnOrigin cmdlet to define the site assets folder as a private origin within the Office 365 CDN.

    Add-SPOTenantCdnOrigin -CdnType Private -OriginUrl */siteassets
  • Use the Add-SPOTenantCdnOrigin cmdlet to define the site pages folder as a private origin within the Office 365 CDN.

    Add-SPOTenantCdnOrigin -CdnType Private -OriginUrl */sitepages
  • Use the Add-SPOTenantCdnOrigin cmdlet to define the publishing images folder as a private origin within the Office 365 CDN.

    Add-SPOTenantCdnOrigin -CdnType Private -OriginUrl */publishingimages

    For more information about this command and its syntax, see Add-SPOTenantCdnOrigin.

    Once you've run the command, the system synchronizes the configuration across the datacenter. This takes 15 minutes.

Example: Configure a private origin for a site collection for SharePoint Online

Use the Add-SPOTenantCdnOrigin cmdlet to define a site collection as a private origin within the Office 365 CDN. For example,

Add-SPOTenantCdnOrigin -CdnType Private -OriginUrl sites/site1/siteassets

For more information about this command and its syntax, see Add-SPOTenantCdnOrigin.

Once you've run the command, the system synchronizes the configuration across the datacenter. This takes 15 minutes.

Manage the Office 365 CDN

Once you've set up the CDN, you can make changes to your configuration as you update content or as your needs change, as described in this section.

To add, update, or remove assets from the Office 365 CDN

Once you've completed the setup steps, you can add new assets, and update or remove existing assets whenever you want. Just make your changes to the assets in the folder or SharePoint library that you identified as an origin. If you add a new asset, it is available through the CDN immediately. However, if you update the asset, it will take up to 15 minutes for the new copy to propagate and become available in the CDN.

If you need to retrieve the location of the origin, you can use the Get-SPOTenantCdnOrigins cmdlet. For information on how to use this cmdlet, see Get-SPOTenantCdnOrigins.

To remove an origin from the Office 365 CDN

If you need to, you can remove access to a folder or SharePoint library that you identified as an origin. To do this, use the Remove-SPOTenantCdnOrigin cmdlet. For information on how to use this cmdlet, see Remove-SPOTenantCdnOrigin.

To modify an origin in the Office 365 CDN

You can't modify an origin you've created. Instead, remove the origin and then add a new one. For more information, see To remove an origin from the Office 365 CDN and To add an origin for your assets.

To disable the Office 365 CDN

Use the Set-SPOTenantCdnEnabled cmdlet to disable the CDN for your organization. If you have both the public and private origins enabled for the CDN, you need to run the cmdlet twice as shown in the following examples.

To disable use of public origins in the CDN, in Windows Powershell for SharePoint Online, enter the following command:

Set-SPOTenantCdnEnabled -CdnType Public -Enable $false

To disable use of the private origins in the CDN, enter the following command:

Set-SPOTenantCdnEnabled -CdnType Private -Enable $false

For more information about this cmdlet, see Set-SPOTenantCdnEnabled.

Troubleshooting your Office 365 CDN configuration

The endpoint will not immediately be available for use, as it takes time for the registration to propagate through the CDN. Configuration takes 15 minutes.

Expand your skills
Explore training
Get new features first
Join Office Insiders

Was this information helpful?

Thank you for your feedback!

Thank you for your feedback! It sounds like it might be helpful to connect you to one of our Office support agents.

×