AD FS 2.0 Federation with a WIF Application Step-by-Step Guide

Applies To: Active Directory Federation Services (AD FS) 2.0

About This Guide

This guide provides instructions for setting up a small test lab with Active Directory® Federation Services (AD FS) 2.0 and Windows Identity Foundation (WIF) on a server running the Windows Server® 2008 or Windows Server 2008 R2 operating system. It explains how to install and configure the software that is required for setting up a stand-alone federation server (running AD FS 2.0 software) and a Web server (running WIF software).

The federation server will issue the claims that are required so that users can access the sample application. The Web server will host a sample WIF application that will trust the users who present the claims that the federation server issues. For the purposes of reducing the time needed to set up this test lab, both the federation server role and the Web server role will be installed on the same computer.

The overall goal of this guide is to provide a good understanding of the base configuration requirements necessary for evaluating how the AD FS 2.0 and WIF technologies interoperate. You should be able to complete the steps in this guide within one hour or less.

What this guide does not provide

This guide assumes that you have a working test lab network environment. Therefore, this guide does not provide instructions for setting up and configuring the following:

1. An Active Directory domain

2. A federation server proxy

3. AD FS 2.0 in a production environment

Requirements

To complete all the steps in this guide, your lab must have a single computer or virtual machine (VM) that meets the minimum requirements that are specified in the following table.

To maximize the chances of completing the objectives of this guide successfully, complete the steps in this guide in the order in which they are presented.

Step 1: Download, Install, and Configure Prerequisite Software

This step guides you through the process of downloading, installing, and configuring prerequisite software, which AD FS 2.0 and WIF require, on your computer. The following table provides details about the required software, which actions to take with the software, the reasons why the software is required, and links to downloads for the software.

Administrative credentials

To perform all the tasks in this guide, always log on using the local Administrator account for the computer.

Step 2: Install and Configure AD FS 2.0

Before you can evaluate the single-sign-on (SSO) scenario, you must first install and configure AD FS 2.0 on the FSWEB computer. When you complete this step, this computer will be set up in the federation server role.

Install AD FS 2.0

Use the following procedure to install the AD FS 2.0 software on FSWEB. The AdfsSetup.exe installation package will install AD FS 2.0 and all the prerequisite software components that it requires.

To install AD FS 2.0

1. Locate the AdfsSetup.exe installation package that you downloaded, and then double-click it.

2. On the Welcome to the AD FS 2.0 Setup Wizard page, click Next.

3. On the End-User License Agreement page, read the license terms. If you agree to the terms, select the I accept the terms in the License Agreement check box, and then click Next.

4. On the Server Role page, click Federation server, and then click Next.

5. On the Completed the Microsoft AD FS 2.0 Setup Wizard page, click Close. This automatically starts the AD FS 2.0 Management console.

Create and configure a server authentication certificate in IIS

Use the following procedure to create a self-signed Secure Sockets Layer (SSL) certificate and bind it to the Default Web Site using the IIS Manager console. The AD FS 2.0 Setup Wizard should have automatically installed the Web Server (IIS) server role on the FSWEB computer.

To create and configure a server authentication certificate in IIS

1. Open the Internet Information Services (IIS) Manager console.

2. On the Start menu, click All Programs, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

3. In the console tree, click the root node that contains the name of the computer, and then, in the details pane, double-click the icon named Server Certificates in the IIS grouping.

4. In the Actions pane, click Create Self-Signed Certificate.

5. On the Specify Friendly Name page, type fsweb.contoso.com, and then click OK.

6. In the console tree, click Default Web Site.

7. In the Actions pane, click Bindings.

8. In the Site Bindings dialog box, click Add.

9. In the Add Site Binding dialog box, select https in the Type drop-down list, select the fsweb.contoso.com certificate in the SSL certificate drop-down list, click OK, and then click Close.

10. Close the Internet Information Services (IIS) Manager console.

Configure the computer as a stand-alone federation server

Use the following procedure to configure FSWEB for the stand-alone federation server role.

To configure the computer as a stand-alone federation server

1. While the AD FS 2.0 Management console is open, click AD FS 2.0, and then, in the details pane, click the AD FS 2.0 Federation Server Configuration Wizard link to start the wizard.

2. On the Welcome page, click Create a new Federation Service, and then click Next.

3. On the Select Stand-Alone or Farm Deployment page, click Stand-alone federation server, and then click Next.

4. On the Specify the Federation Service Name page, verify that the fsweb.contoso.com certificate is selected, and then click Next.

5. On the Ready to Apply Settings page, review the settings, and then click Next.

6. On the Configuration Results page, click Close.

7. Leave the AD FS 2.0 Management console open, and then proceed to the next step.

Step 3: Install and Configure WIF and the Sample Application

This step installs and configures WIF and a sample application (provided by the WIF SDK) to trust the claims that are issued by the federation server role that you created in the previous step. After this step is complete, the FSWEB computer is set up in both the federation server role and the claims-aware Web server role.

Install the WIF SDK

Use the following procedure to install the WIF SDK software on the FSWEB computer. This installation package contains claims-aware sample Web applications that trust claims from the federation server.

To install and configure WIF SDK

1. Locate the WindowsIdentityFoundation-SDK.msi installable package that you downloaded, and then double-click it.

2. On the Welcome to the Windows Identity Foundation SDK Setup Wizard page, click Next.

3. On the End-User License Agreement page, read the license terms. If you agree to the terms, select the I accept the terms in the License Agreement check box, and then click Next.

4. On the Destination Folder page, specify the desired installation folder, and then click Next.

5. On the Ready to install Windows Identity Foundation SDK page, click Install.

6. On the Completed the Windows Identity Foundation SDK Setup Wizard page, clear the Open Readme check box, and then click Finish.

Create the WIF sample application

Use the following procedure to create the WIF sample application on the FSWEB computer. This procedure creates the necessary virtual directories in IIS that this application requires to function properly.

To create the WIF sample application

1. Open Windows Explorer, and navigate to C:\Program Files\Windows Identity Foundation SDK\v3.5\Samples\Quick Start\Using Managed STS. If you are using a 64-bit version of Windows, change Program Files in this path to Program Files (x86).

2. Right-click setup.bat, and then click Run as administrator.

3. After the command-line script stops running, close the Command Prompt window.

Create and configure the WifSamples application pool

The WIF sample application is configured to use a specific application pool called WifSamples. Use the following procedure to create and configure the WifSamples application pool.

To create and configure the WifSamples application pool

1. Open the Internet Information Services (IIS) Manager console.

2. In the console tree, in the root node that contains the name of the computer, right-click Application Pools, and then click Add Application Pool.

3. In the Add Application Pool dialog box, in Name type WifSamples, and then click OK.

4. In IIS Manager, in the center pane, right-click the newly created WifSamples application pool, and then click Advanced Settings.

5. In the Advanced Settings dialog box, in the Process Model section, change the value for Load User Profile to True, and then click OK.

6. Close the IIS Manager console.

Configure the WIF sample application to trust incoming claims

Use the following procedure to configure the WIF sample application to trust incoming claims from the federation server role that you created previously. In this procedure, you use Visual Studio 2008 and the Federation Utility Wizard.

To configure the WIF sample application to trust incoming claims

1. Click Start, click All Programs, click Microsoft Visual Studio 2008, right-click Microsoft Visual Studio 2008, and then click Run as administrator.

2. In Visual Studio 2008, on the File menu, click Open File.

3. In the Open File dialog box, navigate to C:\Program Files\Windows Identity Foundation SDK\v3.5\Samples\Quick Start\Using Managed STS, click the RPForManagedSTS-VS2008 solution file, and then click Open.

4. In the Solution Explorer, right-click the project, and then click Add STS reference to start the Federation Utility Wizard.

5. On the Welcome to the Federation Utility Wizard page, in Application URI, type https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/ to indicate the path to the sample application that will trust the incoming claims from the federation server. Click Next.

6. On the Security Token Service page, click Use an existing STS, type fsweb.contoso.com, and then click Next.

7. On the STS signing certificate chain validation error page, click Disable certificate chain validation, and then click Next.

8. On the Security token encryption page, click No encryption, and then click Next.

9. On the Offered claims page, review the claims that will be offered by the federation server, and then click Next.

10. On the Summary page, review the changes that will be made to the sample application by the Federation Utility Wizard, and then click Finish.

11. On the File menu, click Save to save the changes to the project.

12. Close Visual Studio.

Step 4: Configure AD FS 2.0 to Send Claims to the Application

This step configures AD FS 2.0 to send claims to an application.

Add the sample application as a relying party

Use the following procedure to add a relying party trust to the Contoso Federation Service.

To add the sample application as a relying party

1. In the AD FS 2.0 Management console, click AD FS 2.0, and then, in the details pane, click Required: Add a trusted relying party to start the Add Relying Party Wizard.

2. On the Welcome page, click Start.

3. On the Select Data Source page, click Import data about the relying party published online or on a local network, type https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/, and then click Next. This action prompts the wizard to check for the metadata of the application that the Web server role hosts.

4. On the Specify Display Name page, in Display name type WIF Sample App, and then click Next.

5. On the Choose Issuance Authorization Rules page, click Permit all users to access this Relying Party, and then click Next.

6. On the Ready to Add Trust page, review the relying party trust settings, and then click Next to save the configuration.

7. On the Finish page, click Close to exit the wizard. This also opens the Edit Claim Rules for WIF Sample App properties page. Leave this dialog box open, and then go to the next procedure.

Configure the claim rule for the sample application

Use the following procedure to configure the claim rule that will enable the federation server to send outgoing claims to the trusted WIF sample application.

To configure the claim rule for the sample application

1. On the Edit Claim Rules for WIF Sample App properties page, on the Issuance Transform Rules tab, click Add Rule to start the Add Transform Claim Rule Wizard.

2. On the Select Rule Template page, under Claim rule template, click Pass Through or Filter an Incoming Claim on the menu, and then click Next. This action passes an incoming claim through to the user by means of Windows Integrated Authentication.

3. On the Configure Rule page, in Claim rule name type Pass Through Windows Account Name Rule. In the Incoming claim type drop-down list, click Windows account name, and then click Finish.

4. Click OK to close the property page and save the changes to the relying party trust.

Step 5: Access the Sample Application

This step demonstrates the user experience with the application.

Configure browser settings to trust the federation server role

Use the following procedure to manually configure Internet Explorer settings so that the browser settings trust FSWEB.

To configure browser settings to trust the federation server role

1. Start Internet Explorer.

2. On the Tools menu, click Internet Options.

3. On the Security tab, click Local intranet, and then click Sites.

4. Click Advanced.

5. In Add this Web site to the zone, type https://fsweb.contso.com, and then click Add.

6. Click Close, and then click OK two times.

Test access to the sample application

Use the following procedure to verify that a user in the Contoso domain can now access the sample application.

To test access to the sample application

1. Log on to the computer using the contoso\administrator account.

2. Open a browser window, and then go to https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/default.aspx.

3. This action automatically redirects the request to the federation server role and then back to the sample application with claims. Notice that the claims that AD FS 2.0 issues appear in the page.

(Optional) Step 6: – Change Authorization Rules

This optional step demonstrates how to change the authorization rules for token issuance that are configured on the AD FS 2.0 relying party trust. The issuance authorization rules provide a rich mechanism for detailed, claims-based access control. In the first procedure of step 4, you chose to permit access to all users. In this step, you will change the rules to only permit access to the CONTOSO\administrator account.

Configure the authorization claim rules for the sample application

Use the following procedure to add an additional rule to deny access to a windows account.

To configure the claim rule for the sample application

1. In the Edit Issuance Transform Rules for WIF Sample App properties page, while on the Issuance Authorization Rules tab, select the rule named Permit Access to All Users, and click Remove Rule. Click Yes to confirm. With no rules, no users are permitted access.

2. On the Issuance Authorization Rules tab, click the Add Rule button to start the Add Issuance Authorization Claim Rule Wizard.

3. On the Select Rule Template page, under Claim rule template, select Permit or Deny Users Based on an Incoming Claim from the menu, and then click Next.

4. On the Configure Rule page, in Claim rule name type Permit CONTOSO\Administrator Rule, in the Incoming claim type drop-down list, select Windows account name. In Incoming claim value, type CONTOSO\administrator, select the option to Permit access to users with this incoming claim, and then click Finish.

5. Click OK to close the property page and save the changes to the relying party trust.

Test access to the sample application

Use the following procedure to verify that a user in the Contoso domain can now access the sample application.

To test access to the sample application

1. Log on to the computer using the contoso\administrator account.

2. Open a browser window, and then go to https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/default.aspx. This will automatically redirect the request to the federation server role and back to the sample application with claims.

3. Notice that the administrator has access as seen in Step 5.

4. Log off, and log on to the computer using any other account.

5. Open a browser window, and then go to https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/default.aspx. This will automatically redirect the request to the federation server.

6. Notice that the user is denied access.

Appendix A: Install and Configure AD FS 2.0 for High Availability

Use the following procedure to install the AD FS 2.0 software on both FSWEB1 and FSWEB2, which are representing fsweb.contoso.com. The AdfsSetup.exe installation package will install AD FS 2.0 and all the prerequisite software components that it requires.

Before federation servers can be grouped as a farm, they must first be clustered so that requests that arrive at a single fully qualified domain name (FQDN) are routed to the various federation servers in the server farm. You can create the server cluster by deploying Network Load Balancing (NLB) inside the corporate network. This guide assumes that NLB has been configured appropriately to cluster each of the federation servers in the farm.

For more information about how to configure a cluster FQDN using Microsoft NLB technology, see Specifying the Cluster Parameters (https://go.microsoft.com/fwlink/?LinkID=74651).

Create a dedicated service account

1. Create a dedicated user/service account in the Active Directory forest that is located in the identity provider organization. This account is necessary for the Kerberos authentication protocol to work in a farm scenario and to allow pass-through authentication on each of the federation servers. Use this account only for the purposes of the federation server farm.

2. Edit the user account properties, and select the Password never expires check box. This action ensures that this service account's function is not interrupted as a result of domain password change requirements.

To set the SPN of the service account

• Because the application pool identity for the AD FS 2.0 AppPool is running as a domain user/service account, you must configure the Service Principal Name (SPN) for that account in the domain with the Setspn.exe command-line tool. Setspn.exe is installed by default on computers running Windows Server 2008. Run the following command on a computer that is joined to the same domain where the user/service account resides:

  setspn -a host/<server name> <service account>

  For example, in a scenario in which all federation servers are clustered under the Domain Name System (DNS) host name https://fsweb.contoso.com and the service account name that is assigned to the AD FS 2.0 AppPool is named adfs2farm, type the command as follows, and then press ENTER:

  setspn -a HOST/fsweb.contoso.com adfs2farm

  It is necessary to complete this task only once for this account.

Install AD FS 2.0 on both FSWEB1 and FSWEB2

You must install AD FS 2.0 on both FSWEB1 and FSWEB2.

To install AD FS 2.0

1. Locate the AdfsSetup.exe installable package that you downloaded and then double-click it.

2. On the Welcome to the AD FS 2.0 Setup Wizard page, click Next.

3. On the End-User License Agreement page, read the license terms. If you agree to them, select the I accept the terms in the License Agreement check box, and then click Next.

4. On the Server Role page, choose Federation server, and then click Next.

5. On the Completed the Microsoft AD FS 2.0 Setup Wizard page, click Close. This will automatically start the AD FS 2.0 Management console.

Configure FSWEB1 as the first federation server in a federation server farm

Use the following procedure to configure FSWEB1 as the first federation server in a federation server farm.

To configure FSWEB1 as the first federation server in a federation server farm

1. While the AD FS 2.0 Management console is open, click AD FS 2.0, and then, in the details pane, click the AD FS 2.0 Federation Server Configuration Wizard link to start the wizard.

2. On the Welcome page, select Create a new Federation Service, and then click Next.

3. On the Select Stand-Alone or Farm Deployment page, select New federation server farm, and then click Next.

4. On the Specify the Federation Service Name page, verify that the fsweb.contoso.com certificate is selected, and then click Next.

5. On the Specify a Service Account page, click Browse, and select the service account created previously in this step. In Password, type the password of the service account, and then click Next.

6. On the Ready to Apply Settings page, review the settings, and then click Next.

7. On the Configuration Results page, click Close.

8. Leave the AD FS 2.0 Management console open, and then proceed to the next step.

Add FSWEB2 to the federation server farm

Use the following procedure to configure FSWEB for the stand-alone federation server role.

To add FSWEB2 to the federation server farm

1. While the AD FS 2.0 Management console is open, click AD FS 2.0, and then, in the details pane, click the AD FS 2.0 Federation Server Configuration Wizard link to start the wizard.

2. On the Welcome page, select Add a federation server to an existing Federation Service, and then click Next.

3. On the Specify the Primary Federation Server and Service Account page, in Primary federation server name, type FSWEB1. Click Browse, and select the service account created previously in this step. In Password, type the password of the service account, and then click Next.

4. On the Ready to Apply Settings page, review the settings, and then click Next.

5. On the Configuration Results page, click Close.

Appendix B: Install and Configure a Federation Server Proxy

Use the following procedure to install the AD FS 2.0 software on a new computer named FSWEBPROXY that will be configured in the federation server proxy role. The AdfsSetup.exe installation package will install AD FS 2.0 and all the prerequisite software components that it requires.

To install AD FS 2.0

1. Locate the AdfsSetup.exe installable package that you downloaded and then double-click it.

2. On the Welcome to the AD FS 2.0 Setup Wizard page, click Next.

3. On the End-User License Agreement page, read the license terms. If you agree to them, select the I accept the terms in the License Agreement check box, and then click Next.

4. On the Server Role page, choose Federation server proxy, and then click Next.

5. On the Completed the Microsoft AD FS 2.0 Setup Wizard page, click Close. This will automatically start the AD FS 2.0 Federation Server Proxy Configuration Wizard.

Configure the federation server proxy

Use the following procedure to configure FSWEBPROXY for the federation server proxy role.

To configure the federation server proxy

1. On the Welcome page of the AD FS 2.0 Federation Server Proxy Configuration Wizard, click Next.

2. On the Specify the Federation Service Name page, type fsweb.contoso.com, and then click Next.

3. When you are prompted for the user name and password, specify the username and password of the service account you created in the beginning of Appendix A.

4. On the Ready to Apply Settings page, review the settings, and then click Next.

5. On the Configuration Results page, click Close.

Test access to the sample application

Use the following procedure to verify that an external user in the Contoso domain can now access the sample application. This simulates an external user by changing the hosts file to point to the proxy when contacting fsweb.contoso.com. Use the following procedure to configure the Federation Service to trust the federation server proxy.

To add the IP address of the federation server proxy to the client hosts file

1. Navigate to the %systemroot%\Winnt\System32\Drivers directory folder and locate the hosts file.

2. Start Notepad, and then open the hosts file.

3. Add the IP address and the host name of a federation server in the account partner to the hosts file, as shown in the following example:

   <IP Address for Federation Service> fsweb.contoso.com

4. Save and close the file.

To test access to the sample application

1. Log on to the computer using the contoso\administrator account.

2. Open a browser window, and then go to https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/default.aspx. This will automatically redirect the request to the federation server role and back to the sample application with claims.

3. Notice that the claims that AD FS 2.0 issued appear in the page.