Microsoft KB Archive/912492

= Windows SharePoint Services and SharePoint Portal Server 2003 Support boundaries for Active Directory Federation Services =

Article ID: 912492

Article Last Modified on 1/30/2007

-

APPLIES TO


 * Microsoft Office SharePoint Portal Server 2003
 * Microsoft Windows SharePoint Services
 * Microsoft Windows Server 2003 R2 Standard Edition (32-bit x86)
 * Microsoft Windows Server 2003 R2 Enterprise Edition (32-Bit x86)
 * Microsoft Windows Server 2003 R2 Datacenter Edition (32-Bit x86)
 * Microsoft Windows Server 2003 R2 Standard x64 Edition
 * Microsoft Windows Server 2003 R2 Enterprise x64 Edition
 * Microsoft Windows Server 2003 R2 Datacenter x64 Edition

-



SUMMARY
''Active Directory Federation Services (ADFS) enables web single sign-on, federated identity and access management by securely sharing digital identity and entitlement rights across security and enterprise boundaries. The ADFS functionality becomes available in Windows Server 2003 R2.''



INTRODUCTION
The purpose of this article is to describe supported configurations, known limitations, and recommendations for improving the user experience when you deploy Microsoft Windows SharePoint Services and Microsoft Office SharePoint Portal Server 2003 with ADFS.



MORE INFORMATION
SharePoint and ADFS integration is dependent on the ADFS ability to seamlessly convert the ADFS authentication token to a Windows authentication token on the server. SharePoint server side functionality is mostly compatible with ADFS authentication. Limitations on the supported features for SharePoint and ADFS integration are driven by client side incompatibilities.

ADFS is a web-based authentication mechanism which relies on a system of client-side redirects in order to authenticate the end-user. This works well when the client is a Web browser such as Microsoft Internet Explorer. However, not all client programs support redirects.

When the user is authenticated, client-side redirects are used to obtain an ADFS authentication token, which is saved in a session cookie to authenticate subsequent requests using the same client program. Since session cookies are not shared between programs running in separate processes, Microsoft Office or other programs cannot access the cookie issued for a browser. This requires re-authenticating the user, for which the necessary redirects are not guaranteed to work in non-browser programs. Even if initial authentication succeeds, the resultant authentication cookie has an associated timeout. Thus periodic re-authentication is required, which is not guaranteed to work for all programs.

Several significant ADFS and SharePoint integration problems come from attempting to use client programs that do not work with redirects. For example, the use of SharePoint with Microsoft Office Outlook 2003, Microsoft Office FrontPage 2003, Microsoft Office Word 2003, or the Windows shell commands are either outright broken or have a sub-par experience.

The remainder of this article addresses what is supported and not supported, and how to best mitigate end-user problems that result from the known issues in this configuration.

Supported features
Any feature which operates exclusively in the Web browser will work and is fully supported. This includes the following:
 * Site navigation
 * List and document viewing
 * List item editing (including list editing by using the Edit in datasheet control)
 * Search (supported for large farm deployments, but it is not functional for single server evaluation installation)
 * File download
 * File upload

This support is dependent on the ADFS ability to seamlessly convert the ADFS authentication token to a Windows authentication token on the SharePoint server.

For more information about integrating SharePoint with ADFS, consult the ADFS Step-by-Step Guide available from the following Microsoft Web site:

http://go.microsoft.com/fwlink/?linkid=49531

Unsupported features
The following features are not supported when SharePoint is integrated with ADFS:  Using Office 2003 (or comparable) clients to open and save documents on a SharePoint server is not a supported scenario, when SharePoint is running under ADFS authentication. Even if the file is opened successfully, problems may occur if the ADFS cookie times out. If the user attempts to save the document after the cookie has expired, errors during the redirects required to re-authenticate the user may make it impossible to save the document back to the server. In this case, the user could save the document locally, and then upload it back to the server using a browser. To avoid problems, we suggest that you turn off the Office 2003 open features in SharePoint, and revert to file download and file upload by using the Web browser. The SharePoint Office integration features which rely on SOAP Web services running outside of the browser will not work with ADFS and are not supported. These features include Outlook synchronization such as Linking to Outlook from a Contacts list or an Events list, Export to Spreadsheet, creating a new list by Importing Spreadsheet, Export to Access, and Editing in FrontPage. Windows shell commands to map a drive to a site or document library or perform other operations is not supported. Web Folders (such as by using Network Places) which rely on the DAV redirector, will no longer work as expected. Web folders are typically created in order to have a file explorer view of a site or document library to easily copy and move files. Using this feature when SharePoint is working with ADFS is not supported. Independently federating the SharePoint content site and SharePoint Central Admin sites. SharePoint Web Parts that utilize the SharePoint Portal Server single sign on (SSO) feature to access program data is unsupported. Due to limitations in how ADFS handles SOAP requests, programmatic access to SharePoint data and functionality via Web Services through ADFS is not supported except when the request comes from within the content of a browser session such as from an ActiveX control.</li> SharePoint Portal Services Alternate Access Mappings are not supported with ADFS Web SSO. Alternate Access Mappings allow multiple URLs that correspond to the same Internet Information Services (IIS) virtual server, or Web site.

You may want to deploy a SharePoint Portal Sever site that is accessible both internally (inside the intranet) and externally (from outside the corporate firewall), but not expose the same URL to clients in the different DNS &quot;zones&quot;. The Internal URL is similar to https://myteam, but the external URL is similar to http://partners.extranet.company.com/myteam. ADFS does NOT support this feature; for security reasons it enforces a unique Return URL for a given site or program for added security.

For more information about ADFS and the Return URL, visit the following Microsoft Web site:

http://technet2.microsoft.com/WindowsServer/en/Library/bf0cf512-7468-4bfa-bc89-5e2da40e232f1033.mspx

</li></ul>

Removing feature functionality that is not supported
To reduce end-user confusion, you can remove some feature functionality that is not supported. Removing the feature from the user interface will help prevent end-users from using a feature that will either be broken or have a sub par experience.

Disabling the Edit in Office Application and New Document controls
To turn off the Edit in Office Application control and the New Document control, you have to edit the Docicon.xml file on each front-end Web server. The Docicon.xml file is located in the following folder:



To edit the Docicon.xml file, open it in notepad and then locate the following section </ByProgID> <ByExtension> <Mapping Key=&quot;doc&quot; Value=&quot;icdoc.gif&quot; EditText=&quot;Microsoft Office Word&quot; OpenControl=&quot;SharePoint.OpenDocuments&quot;/> To change this file so that it is not possible to use the Context Menu to Edit the document in Word, you have to modify the parameter as seen below. For example, after modifying the entry for Word documents, it would appear as follows: </ByProgID> <ByExtension> <Mapping Key=&quot;doc&quot; Value=&quot;icdoc.gif&quot;/> The result of this change is that the Edit in Microsoft Office Word control will no longer appear on the context menu drop-down for the document. You will need to repeat this procedure for each Office file extension mapping.

After this change, if the user clicks New Document, the user will receive the following message:

‘New Document’ requires a Windows SharePoint Services-compatible application and Microsoft Internet Explorer 5.0 or greater. To add a document to this document library, click the ‘Upload Document’ button.

More information about editing Docicon.xml is available in the Windows SharePoint Services SDK at the following Microsoft Web site:

http://msdn2.microsoft.com/en-us/library/ms463701.aspx

Client computers that have Office applications installed may receive error messages. These messages may be received when the client computers open a document that is stored in a document library that is located on a Shared Services SharePoint site. To remove these error messages, open the Htmltransinfo.xml file on the Web server computer, and then remove the ProgId mapping. To do this, follow these steps: <ol> In Microsoft Windows Explorer, find the Htmltransinfo.xml file. This file is located in the following folder on the Web server:

 :\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\Template\Xml

</li> Right-click Htmltransinfo.xml, and then click Edit.</li> Change the file to set ProgId to empty. For example, ProgId = &quot;&quot;.</li></ol>

The following code is an example of how the Htmltransinfo.xml file looks before you set ProgID to empty.

Note The following lines may have been wrapped for easier readability on the Web. <HtmlTrInfo> <Mapping Extension=&quot;xls&quot; AcceptHeader=&quot;application/vnd.ms-excel&quot; HandlerUrl=&quot;HtmlTranslate.aspx&quot; ProgId=&quot;SharePoint.OpenDocuments.2&quot;/> <Mapping Extension=&quot;doc&quot; AcceptHeader=&quot;application/msword&quot; HandlerUrl=&quot;HtmlTranslate.aspx&quot; ProgId=&quot;&quot;/> <Mapping Extension=&quot;ppt&quot; AcceptHeader=&quot;application/vnd.ms-powerpoint&quot; HandlerUrl=&quot;HtmlTranslate.aspx&quot; ProgId=&quot;SharePoint.OpenDocuments.2&quot;/> <Mapping Extension=&quot;pps&quot; AcceptHeader=&quot;application/vnd.ms-powerpoint&quot; HandlerUrl=&quot;HtmlTranslate.aspx&quot; ProgId=&quot;&quot;/> <Mapping Extension=&quot;one&quot; AcceptHeader=&quot;&quot; HandlerUrl=&quot;&quot; ProgId=&quot;SharePoint.OpenDocuments.2&quot;/> </HtmlTrInfo> The following is an example of how the Htmltransinfo.xml file looks after you set ProgId to empty.

Note The following lines may have been wrapped for easier readability on the Web. <HtmlTrInfo> <Mapping Extension=&quot;xls&quot; AcceptHeader=&quot;application/vnd.ms-excel&quot; HandlerUrl=&quot;HtmlTranslate.aspx&quot; ProgId=&quot;&quot;/> <Mapping Extension=&quot;doc&quot; AcceptHeader=&quot;application/msword&quot; HandlerUrl=&quot;HtmlTranslate.aspx&quot; ProgId=&quot;&quot;/> <Mapping Extension=&quot;ppt&quot; AcceptHeader=&quot;application/vnd.ms-powerpoint&quot; HandlerUrl=&quot;HtmlTranslate.aspx&quot; ProgId=&quot;&quot;/> <Mapping Extension=&quot;pps&quot; AcceptHeader=&quot;application/vnd.ms-powerpoint&quot; HandlerUrl=&quot;HtmlTranslate.aspx&quot; ProgId=&quot;&quot;/> <Mapping Extension=&quot;one&quot; AcceptHeader=&quot;&quot; HandlerUrl=&quot;&quot; ProgId=&quot;&quot;/> </HtmlTrInfo>

Removing other Client-Integration Functionality
To remove or hide the client-integration functionality, you can follow the steps below.

Note These steps are intended to be implemented before deploying portal or Windows SharePoint Services sites, and should be performed on custom site definitions whenever possible.

For more information, click the following article number to view the article in the Microsoft Knowledge Base:

898631 Supported and unsupported scenarios for working with custom site definitions and custom area definitions in Windows SharePoint Services and in SharePoint Portal Server 2003

Note Attempting to implement these same changes on site definitions that have already been deployed will pose additional, and in some cases, unsupported challenges that are outside of the scope of this article. <ol> Implement a custom .js file. Refer to the Customizing the Shortcut Menu for List Items topic in the SharePoint Products and Technologies SDK as a guide:

http://msdn2.microsoft.com/en-us/library/ms868274.aspx

Create a new .js file named Custom_ows.js as the article indicates, and reference it in the corresponding Onet.xml file for the site definition files that you will be customizing. It is not necessary to implement the custom Check Out & Save command that is described in the article.</li>  Edit the custom .js file to remove or modify client-integration functionality. The following code snippet, which represents the entirety of the custom .js code needed for this step, can be added to the newly-created Custom_ows.js file, as-is: //begin code to modify client-integration //disables &quot;Export to Spreadsheet&quot; functionality and returns friendly error to user function ExportList(using) {   var L_ExportListSpreadsheet_Text = &quot;This feature has been disabled on your server.&quot;; alert(L_ExportListSpreadsheet_Text); } //removes &quot;Link to Outlook&quot; link function GetStssyncAppName(strDefault) {   return false; }

//end code to modify client-integration After steps 1 and 2 have been completed, the &quot;Export to Spreadsheet&quot; and the &quot;Link to Outlook&quot; functionality will be modified or removed from any newly-created sites based on the site definition that references the custom .js file. </li>  Optionally, remove &quot;Import Contacts&quot; links from the &quot;Contacts&quot; list definitions.

Note The &quot;Import Contacts&quot; link cannot be removed or disabled by editing the custom .js file, and requires manual editing of every contacts-based list definition (where Type=105, or custom list definitions based on the same) on the server to remove the link. Additionally, the supportability guidelines that are outlined in KB article 898631 for editing site and list definitions require that changes to Schema.xml files only be made within custom site definitions. Because of this, and because this is a fairly intensive task, administrators are advised to consider educating users about the status of this functionality rather than implementing a system-wide change to every contacts-based list definition.

To remove the &quot;Import Contacts&quot; link, open the corresponding Schema.xml file for editing. The Schema.xml file is located in the list definition folder within the respective site definition's Lists folder, such as

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\Template\1033\Custom_sts\Lists\Contacts

Within the Schema.xml file, find the section of code that is relative to the &quot;Import Contacts&quot; link, by searching for the string ImportFromAddressBook within the file. Remove the contents of the &quot;CDATA&quot; block that contains the &quot;Import Contacts&quot; link. For example, in the default contacts list definition, the following example code represents the state of the list definition before removing the contents of the CDATA section </SCRIPT>]]></HTML><HTML><![CDATA[ <TD class=ms-separator>|</TD> <TD class=&quot;ms-toolbar&quot;>  </TD> ]]></HTML> After removing the relevant code, the same code would look like the following example code: </SCRIPT>]]></HTML><HTML><![CDATA[ ]]></HTML> Again, this change would need to be made for every contacts-based list definition system-wide. </li></ol>

In your deployment, you may find other unexpected issues when using ADFS with SharePoint. To determine if the problem is an Office or SharePoint specific issue, you will need to test on a separate server using the standard Windows Integrated Authentication. If it reproduces with standard Windows Authentication without ADFS integration, then the problem is a core Office or SharePoint problem and can be reported to Office or SharePoint product support services for assistance working around the issue or requesting a hotfix.

If the problem is unique to ADFS authentication, it is possible the problem could exist in the configuration of ADFS, an Internet Explorer issue with redirects, or possibly a non-supported scenario. Product Support Services ADFS support team can help investigate these issues. However, if the problem is a limitation in Office or SharePoint compatibility with ADFS style authentication, the Office or SharePoint product teams are not able to provide fixes to improve the ADFS integration experience. If there is a work around or other specific guidance that can be provided, this article will be amended to include the additional information.

Additional query words: sharepointportalserver2003 sharepointportalserver2k3 sps2003 sps2k3 windows2003 windows2k3 win2003 win2k3

Keywords: kbconfiguration kbtshoot kbexpertiseinter kbinfo KB912492

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.