Quick Start: Enabling Federation in a SharePoint Application with AD FS 2.0 as the STS

This quick start assumes that you have:

• Active Directory® Federation Services (AD FS) 2.0 already installed in the same domain as the SharePoint server.

  1. Install Active Directory® Federation Services (AD FS) 2.0. For more information, see the AD FS 2.0 Server Deployment Guide. Note that you can use any other STS that supports the WS-Federation protocol.

     Note

     If your STS does not have federation metadata documents, you must create them manually. To see what a federation metadata document looks like, you can use WIF to create an STS project and then view the federationmetadata.xml file for that project. For more information, see ASP.NET Security Token Service Web Site.

• A SharePoint server (WSS 3.0 SP2 or MOSS 2007 SP2).

To configure the SharePoint server with WIF follow these instructions:

1. First gather the following information:

   1. Identify the SharePoint Web application that you want to configure. Note the path to its web.config file (WebAppConfigPath).

   2. Note down the SharePoint zone of the Web application to be configured (default, intranet, internet, extranet, or custom).

   3. Note the path to the web.config file (AdminWebConfigPath) of the “SharePoint Central 3.0 Administration” Web site. If you don’t know the path, you can find it by opening Internet Information Services (IIS) Manager, selecting the “SharePoint Central Administration v3” site, right-clicking and selecting “Explore”.

      Note

      If you are deploying in a SharePoint Farm environment and you do not have the administration site's configuration file on the same system, you can choose the application's default zone web.config file.

      For more information on configuring this package for a Farm environment refer to the section, Farm Environment Configuration.

   4. Note the address of the federation metadata location of the STS (StsFedMetadataAddress). If the STS is AD FS 2.0, then it is sufficient to note the hostname of the system where AD FS 2.0 is installed.

2. Run the SharePoint Federation Utility. The tool is located at Start -> All Programs -> Microsoft Federation Extensions for SharePoint 3.0 -> Federation Utility for SharePoint 3.0. This program will request elevated administrator privileges. The following list describes the screens presented by the utility and the selections you should make.

   1. Administration configuration and zoning information. The first screen gathers administration configuration information. In this screen, provide the web.config path for the administration Web application (AdminWebConfigPath from step 1c).

   2. Application information. The second screen gathers information specific to the SharePoint application. In this screen, provide the web.config path for the SharePoint Web application that you want to configure (WebAppConfigPath from step 1a) and the full URL of the application (for example, https://docs.contoso.com). Also, select the SharePoint security zone for the application (from step 1b). Finally, decide whether to enable sliding cookie expiration. This means that when the client sends a request to the application and provides a session cookie, the expiration of the cookie is extended.

      Note

      The AD FS 2.0 STS requires the application to use HTTPS because the security token issued by the STS must be securely transmitted from the STS to the application.

      Click Next.

   3. STS information. The third screen gathers information specific to the STS. In this screen, provide the location of the STS federation metadata document (StsFedMetadataAddress from step 1d). For example, the URL is http://<your STS host name>/FederationMetadata/2007-06/FederationMetadata.xml. If the STS is AD FS 2.0, then it is sufficient to note the hostname of the system where AD FS 2.0 is installed. Click Next.

      The STS information screen also includes a checkbox labeled “Schedule a task to perform daily WS-Federation metadata updates”. If you check this checkbox, FedUtil schedules a task to run at 12:00 AM every day. If you want to run the task more than once a day, you can update the task in the Task Scheduler. You can find the Task Scheduler in the Control Panel under Administrative Tools. If you have configured multiple applications with FedUtil, you might see multiple tasks.

      The task retrieves the STS’s federation metadata and updates the application’s configuration with any changes it detects in the metadata document, such as changes to the STS signing certificate.

   4. Chain validation of STS signing certificate. The next screen lets you select whether to validate the STS’s token signing certificate using chain validation. After making your selection, click Next.

   5. Token encryption. The next screen lets you choose whether or not to encrypt the token issued by the STS. If the SharePoint Web application is SSL enabled, you can choose “No encryption” for better performance. If you select “Enable encryption”, you’ll need to select a certificate from your local certificate store. Click Next.

      Note

      See the Prerequisites section for instructions on which store to add the STS signing certificate.

   6. Claims offered by STS. The next screen shows the list of claims offered by the STS. Note that although the STS may offer many claims, by default, the SharePoint Web application only requires the role and name claims. Click Next.

   7. Summary. This is the final screen and it shows the list of operations that the utility will perform.

      1. Optionally, you can enable automatic federation metadata updates so that the SharePoint Web application always has the latest certificate reference for the STS. This is useful when the STS certificate rolls over and has a different thumbprint.

         Note

         On Windows Server 2003, when you choose to enable automatic federation metadata updates, there is an additional prompt that requests the password for the account to run this task under.

      2. Click Next to begin the configuration process.

      3. On success, you see a message stating that the SharePoint site was configured successfully. The federation metadata for the SharePoint Web application is available at https://<url>:<port>/layouts/images/<port>/Federationmetadata/2007-06/FederationMetadata.xml.

      Note

      If you uninstall the Microsoft Federation Extensions for SharePoint 3.0 Package, any Web applications that were federated using this process no longer work, because the web.config file refers to HTTP modules that are no longer available. It is recommended that you:

      1. Delete the federated Web applications using the SharePoint administration console.
         
         
      2. Remove the federated Web applications from the list of relying parties on the AD FS 2.0 server.
         
         
      3. If you enabled automatic federation metadata updates for the federated Web applications, delete the scheduled task(s) that performs these updates.
         
         
      4. Remove the reference to the SharePointClaimsProvider and SharePointClaimsMembershipProvider from the administration web site's web.config file.
         
         

3. Next, we configure the STS to issue tokens to the SharePoint Web application.

   1. On the STS, add the SharePoint Web application as a relying party. In the AD FS 2.0 management console, you can simply use the federation metadata link (https://contoso.com:<port>/_layouts/images/<port>/FederationMetadata/2007-06/FederationMetadata.xml) to automatically configure a SharePoint application as a relying party. Refer to the AD FS 2.0 product documentation to see how to create a Relying Party Trust.

   2. On the STS, configure the claims issuance policy for the SharePoint application to receive name and role claims. If you are using AD FS 2.0, refer to the Review the Role of Claims and Claim Rules in the Identity Provider Organization topic in the AD FS 2.0 Design Guide.