SharePoint: Browser File Handling Deep Dive

  • Article

Applies To

  • SharePoint 2010
  • SharePoint 2013

Note: This article was originally written for SharePoint 2010, but the content also applies to SharePoint 2013. When reading this article, if the version is not qualified, then the content applies to both versions.

Introduction

In this article, I take a deep dive into understanding all aspects of the Browser File Handling security feature in SharePoint. I attempt to explain the complete story about this security feature and inform you of everything you need to know to make an educated judgment call on what options you have available and more importantly, what you should be doing.

Please note that all PowerShell examples apply to SharePoint Foundation 2010, SharePoint Server 2010, SharePoint Foundation 2013 and SharePoint Server 2013 and should be executed within the SharePoint 2010 Management Shell or the SharePoint 2013 Management Shell.

Overview

Browser File Handling was introduced into SharePoint 2010 as a security feature and the same applies to SharePoint 2013. When a user requests a file within SharePoint, the web server (IIS) will respond including the “X-Download-Options: noopen” HTTP Response Header if Browser File Handling is set to Strict and the file (MIME) type accessed is not on the Web Applications trusted file (MIME) type list. This header works in conjunction with Internet Explorer (version 8 or higher) to prevent potential security risks when accessing files online and will stop files from being directly opened.

A paragraph from the IE Blog on X-Download-Options:

“For web applications that need to serve untrusted HTML files, we have introduced a mechanism to help prevent the untrusted content from compromising your site’s security. When the new X-Download-Options header is present with the value noopen, the user is prevented from opening a file download directly; instead, they must first save the file locally. When the locally saved file is later opened, it no longer executes in the security context of your site, helping to prevent script injection.”

I consider the post on the IE Blog titled “IE 8 Part V: Comprehensive Protection” essential reading. The security changes outlined are carried forward into IE9, IE10 and likely will be present in all future versions of IE.

Browser File Handling Options and Meanings

There are two options for Browser File Handling – “Strict” and “Permissive”.

  1. “Strict” specifies the MIME types which are not listed in a Web Application’s AllowedInlineDownloadedMimeTypes property (more on this in a bit) are forced to be downloaded.
  2. “Permissive” specifies that the HTML and other content types which might contain script are allowed to be displayed directly in the browser. In other words, no matter what the type of content, if it lives within SharePoint, the file will open in your browser.

View the source of the included definitions

Managing Browser File Handling

It is important to note that a Browser File Handling property (BrowserFileHandling) exists in the following locations:

  • Each Web Application has a Browser File Handling Property 
  • Each List has a Browser File Handling Property 
  • Each Document Library has a Browser File Handling Property 
  • Each IIS Server has a Browser File Handling Property that applies when Blob Cache is used on that server

The only one you can manage through the web interface is the Web Application level Browser File Handling property. To do so, here is the click by click:

Go to Central Administration > Manage Web Applications > [Highlight a web application] > click General Settings in the Ribbon > Scroll down in the General Settings window to see Browser File Handling. Set as desired. Save settings.

The List and Document Library level properties are only accessible through code.

Browser File Handling Object Model References

 For the developers in the crowd, here are reference links to the SharePoint Object Model related to Browser File Handling:

The "X-Download-Options: noopen" HTTP Response header

How does SharePoint determine whether to send the "X-Download-Options: noopen" HTTP Response header (i.e. whether to present a Save or Open option to a user)?

The following notes outline the various scenarios through which SharePoint makes the determination to send the “X-Download-Options: noopen” HTTP Response header.
When serving a file, SharePoint 2010 and 2013 use the following logic (from a high level):

  • Check the Web Application’s Browser File Handling Property 

    • If it is “Strict” then all untrusted files within the Web Application will always include the include the “X-Download-Options: noopen” header in the HTTP response. 
    • If it is “Permissive” then SharePoint will check the Browser File Handling Property of the list or document library within which the file resides. This is an override of the Web Application Browser File Handling setting: 
      • If the List/Document Library Browser File Handling Property is set to “Strict” and the MIME type being requested is not on the trusted MIME type list (i.e. the Web Application's AllowedInlineDownloadedMimeTypes), then the HTTP Response will include the “X-Download-Options: noopen” header. 
      • If the Document Library Browser File Handling Property is set to “Permissive” then the HTTP Response will omit the “X-Download-Options” header. 

Some important additional notes:

  • You cannot override the Browser File Handling Property at the List/Document Library level to be more accommodating than at the Web Application level. For example, if your Web Application’s Browser File Handling property is set to “Strict” and then List/Document Library within the Web Application is set to “Permissive”, the HTTP Response will include the “X-Download-Options: noopen” header unless the MIME type being served is on the trusted file list. 
  • You can override the Browser File Handling Property at the List/Document Library level to be more restrictive. For example, if your Web Application is set to “Permissive” and then set a Document Library to “Strict”, the HTTP Response will include the “X-Download-Options: noopen” header unless the MIME type being served is on the trusted file list. 
  • For the “X-Download-Options: noopen” header to be omitted completely one of the two scenarios must be true: 
    • The MIME type being served is on the Web Applications trusted file list, or 
    • The MIME type being served is not on the Web Applications trusted file list and the Browser File Handling Property for both the Web Application and the List/Document Library within which the file resides is set to “Permissive”. 
  • It is important to stress that the trusted file list is unique to a Web Application. The number of trusted file lists (i.e. AllowedInlineDownloadedMimeTypes lists) you have is equal to the number of Web Applications you have in IIS serving SharePoint sites. This is important to understand as if you wish to add “application/pdf” to all trusted file lists within your SharePoint environment, you’ll need to add it to the trusted file list for each Web Application that serves SharePoint sites. 

I encourage all Administrators and Developers to download Fiddler2 and test some different scenarios related to the Browser File Handling Property. Fiddler will show you the HTTP Response Headers so you can prove that the cases presented above are indeed correct.

Default Trusted file (MIME) types

Each Web Application in SharePoint 2010 and 2013 has an AllowedInlineDownloadedMimeTypes property within which a list of trusted file (MIME) types exists. Firstly, there is no “untrusted” list, only a “trusted” list. It is safe to assume that if a MIME type is not included in this list, it is untrusted by default and is subject to the “X-Download-Options: noopen” HTTP Response header. The most common example of this is PDF documents, MIME type “application/pdf”.

In the SharePoint 2010 Management Shell, you can easily find out which types are trusted out of the box by executing the following PowerShell snippet:

Get-SPWebApplication "http://yourwebapplicationurl" | Foreach-Object {$_.AllowedInlineDownloadedMimeTypes}

You could also use the following snippet to achieve the same output:

$webApplication = Get-SPWebApplication "http://yourwebapplicationurl"            
$webApplication.AllowedInlineDownloadedMimeTypes

Again, it is important to note that each web application has its own AllowedInlineDownloadedMimeTypes property.

PowerShell Examples

Download Browser File Handling Management Functions for SharePoint 2010 and 2013

On the TechNet Gallery, I have posted functions for download titled. "Manage SharePoint 2010 or 2013 Web Application Browser File Handling MIME Types". These are re-usable functions with Get, Add and Remove functionality. Using these functions would be the easiest way for you to manage your Browser File Handling MIME Types in SharePoint 2010 and 2013. All three functions work with PowerShell 2.0 and 3.0.

** **

Get the trusted (allowed) MIME Types for a specific Web Application

  Get-SPWebApplication "http://yourwebapplicationurl" |  Foreach-Object {$_.AllowedInlineDownloadedMimeTypes}

Add a new MIME Type to the Trusted List for a specific Web Application

To add a new MIME type, for example “application/pdf”, to a Web Application’s AllowedInlineDownloadedMimeTypes list, using "application/pdf" as an example and assuming it exists within the AllowedInlineDownloadedMimeTypes list, you can execute the following PowerShell snippet:

$webApplication = Get-SPWebApplication "http:/yourwebapplicationurl"             
$webApplication.AllowedInlineDownloadedMimeTypes.Add("application/pdf")             
$webApplication.Update()

Add a new MIME Type to the Trusted (allowed) List for all Content Web Applications

You may wish to add a new MIME type to all of your content web applications. To do this, using "application/pdf" as an example, execute the following PowerShell snippet. Note that this example takes care of checking whether or not the MIME type is on the list before attempting to add it.  

$mimeType = "application/pdf"             
Get-SPWebApplication |             
foreach-object             
{             
    # If the MIME Type is not already on the allowed list for the Web Application             
    if(!$_.AllowedInlineDownloadedMimeTypes.Contains($mimeType))             
    {             
        # Add the MIME type to the allowed list and update the Web Application             
        $_.AllowedInlineDownloadedMimeTypes.Add($mimeType)             
        $_.Update()             
        Write-Host Added $mimeType to the allowed list for Web Application $_.Name             
    }             
    else             
    {             
        # The MIME type was already allowed - can't add. Inform user             
        Write-Host Skipped Web Application $_.Name - $mimeType was already allowed             
    }             
}

 

Remove an existing MIME Type from the Trusted List for a specific Web Application

To remove an existing MIME type from the allowed list, using "application/pdf" as an example and assuming it exists within the AllowedInlineDownlodedMimeTypes list, you can execute the following PowerShell snippet:

$webApplication = Get-SPWebApplication "http:/yourwebapplicationurl"             
$webApplication.AllowedInlineDownloadedMimeTypes.Remove("application/pdf")             
$webApplication.Update()

Remove an existing MIME type from the Trusted List for all Content Web Applications

You may wish to add a new MIME type to all of your content web applications. To do this, using "application/pdf" as an example, execute the following PowerShell snippet. Note that this example takes care of checking whether or not the MIME type is on the list before attempting to remove it. 

$mimeType = "application/pdf"             
Get-SPWebApplication |             
foreach-object             
{             
    # If the MIME Type is not already on the allowed list for the Web Application             
    if($_.AllowedInlineDownloadedMimeTypes.Contains($mimeType))             
    {             
        # Remove the MIME type from the allowed list and update the Web Application             
        $_.AllowedInlineDownloadedMimeTypes.Remove($mimeType) | Out-Null             
        $_.Update()             
        Write-Host Removed $mimeType from the allowed list of Web Application $_.Name             
    }             
    else             
    {             
        # The MIME type was not on the list - can't remove. Inform user             
        Write-Host Skipped Web Application $_.Name - $mimeType was not on the allowed list             
    }             
}

 

Security Guidance and Overall Recommendation

It is recommended that for all Web Applications, you keep the default Browser File Handling setting – Strict. This promotes the best security practice and if you require MIME type exceptions, then add the specific MIME type to your Web Application’s AllowedInlineDownloadedTypes property list.

While many request how to make SharePoint 2010 or 2013 work like previous versions of SharePoint (i.e. SharePoint 2007) with regards to Browser File Handling (i.e. set it to Permissive), I hope at this stage you understand exactly what you are asking.

What setting do I use within the environments for which I am responsible? Strict – always.

Any and all feedback is appreciated.