Table of Contents

• Introduction
• Overview
• What are the options for Browser File Handling and what do they mean?
• Where do I manage Browser File Handling in SharePoint 2010 and 2013?
• Object Model References related to Browser File Handling for Developers
• 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)?
• What file (MIME) types are trusted out of the box?
• How to - PowerShell Examples:
  • Download Browser File Handling Management functions for SharePoint 2010 and 2013
  • Get the trusted (allowed) MIME types for a specific Web Application
  • Add a new MIME type to the trusted (allowed) list for a specific SharePoint 2010 or 2013 Web Application 
  • Add a new MIME type to the trusted (allowed) list for all content Web Applications within SharePoint 2010 or 2013 (excludes Central Administration) 
  • Remove an existing MIME type from the trusted (allowed) list for a specific Web Application within SharePoint 2010 or 2013
  • Remove an existing MIME type from the trusted (allowed) list for all SharePoint 2010 or 2013 content Web Applications (excluding Central Administration) 
• Security Guidance and Overall Recommendation

---

Note: The out of the box Wiki Table of Contents didn't pick up all sections so I created it manually

---

Important update note - Please read:

• This article was originally written for SharePoint 2010 however the same applies to SharePoint 2013. When reading this article, if I say "SharePoint" without qualifying a version I am referring to all versions of SharePoint 2010 and SharePoint 2013.
• Download "Manage SharePoint 2010 or 2013 Web Application Browser File Handling MIME Types". I have posted Get, Add and Remove functions on the TechNet Gallery to make managing Browser File Handling MIME Types easy for everyone.

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.

What are the options for Browser File Handling and what do they mean?

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

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

“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

Where do I manage Browser File Handling in SharePoint 2010 and 2013?

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 

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.

Object Model References related to Browser File Handling for Developers

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

• SPWebApplication.AllowedInlineDownloadedMimeTypes Property:
  Microsoft.SharePoint.SPWebApplication.AllowedInlineDownloadedMimeTypes
  Property value is a Generic ICollection of type string
  
  
• SPBrowserFileHandling Enumeration:
  Microsoft.SharePoint.SPBrowserFileHandling  
  
  
• SPWebApplication.BrowserFileHandling Property:
  Microsoft.SharePoint.SPWebApplication.BrowserFileHandling 
  Property value is of type Microsoft.SharePoint.SPBrowserFileHandling 
  
  
• SPList.BrowserFileHandling Property:
  Microsoft.SharePoint.SPList.BrowserFileHandling 
  Property value is of type Microsoft.SharePoint.SPBrowserFileHandling 
  
  
• SPDocumentLibrary.BrowserFileHandling Property:
  Microsoft.SharePoint.SPDocumentLibrary.BrowserFileHandling 
  Inherits from SPList. Property value is of type Microsoft.SharePoint.SPBrowserFileHandling

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.

What file (MIME) types are trusted out of the box?

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.

How To - 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 (allowed) list for a specific SharePoint 2010 or 2013 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 AllowedInlineDownlodedMimeTypes list, you can execute the following PowerShell snippet:

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

Add a new MIME type to the trusted (allowed) list for all content Web Applications within SharePoint 2010 or 2013 (excludes Central Administration)

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 (allowed) list for a specific Web Application within SharePoint 2010 or 2013

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 (allowed) list for all SharePoint 2010 or 2013 content Web Applications (excluding Central Administration)

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.