Step-by-Step Guide to Identity Delegation December 2009 · Step-by-Step Guide to Identity Delegation Version 1.0 ... domain controller (use contosodc.contoso.com as the name for the

Step-by-Step Guide to Identity Delegation

Version 1.0 December 2009

This guide walks you through the experience of developing a composite application that uses the identity delegation feature of Windows® Identity Foundation (WIF) and Active Directory® Federation Services (AD FS) version 2.0.

Featuring: AD FS 2.0 WIF

Microsoft Corporation

Author: Jan Alexander

Editor: Tonda Kiffin

1

This document supports a preliminary release of a software product that may be changed substantially

prior to final commercial release. This document is provided for informational purposes only and

Microsoft makes no warranties, either express or implied, in this document. Information in this

document, including URL and other Internet Web site references, is subject to change without notice.

The entire risk of the use or the results from the use of this document remains with the user. Unless

otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos,

people, places, and events depicted in examples herein are fictitious. No association with any real

company, organization, product, domain name, e-mail address, logo, person, place, or event is intended

or should be inferred. Complying with all applicable copyright laws is the responsibility of the user.

Without limiting the rights under copyright, no part of this document may be reproduced, stored in or

introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical,

photocopying, recording, or otherwise), or for any purpose, without the express written permission of

Microsoft Corporation.

© 2009 Microsoft Corporation. All rights reserved.

Microsoft, Active Directory, Internet Explorer, SharePoint, Visual C#, Visual Studio, Windows, and

Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the

United States and/or other countries.

All other trademarks are property of their respective owners.

2

Contents Introduction .................................................................................................................................................. 3

Setting Up IIS Bindings at CONTOSOSRV1 and CONTOSOSRV2 .................................................................... 7

Configuring Application Pool Settings at CONTOSOSRV1 ............................................................................. 9

Setting up Local Intranet Sites on CONTOSOSRV1 and CONTOSOC1 ......................................................... 10

Creating WFE Claims-Aware Web Application on CONTOSOSRV1 ............................................................. 13

Registering the WFE Application with AD FS 2.0 STS at CONTOSODC ........................................................ 18

Completing the Relying Party Registration at CONTOSODC ....................................................................... 26

Enabling the Application Pool Account to Access the SSL Certificate at CONTOSOSRV2 ........................... 38

Creating WCF Backend Service at CONTOSOSRV2 ...................................................................................... 39

Registering Backend Service with AD FS 2.0 STS at CONTOSODC .............................................................. 44

Completing the Relying Party Registration at the CONTOSODC ................................................................. 54

Enabling Identity Delegation and Fixing Claims Issuance Rules at CONTOSODC ....................................... 66

Finishing Up the WFE Application at CONTOSOSRV1 ................................................................................. 77

Testing the Final Application ....................................................................................................................... 87

3

Introduction The goal of this step-by-step guide is to guide you through the whole end-to-end experience of

developing a composite application that uses the identity delegation feature of Windows® Identity

Foundation (WIF) and Active Directory® Federation Services (AD FS) version 2.0. The application consists

of two service tiers and a browser-based client. The middle tier is implemented as an ASP.NET Web

application, and the back end is implemented as a Windows Communication Foundation (WCF) service.

Both tiers are implemented as claims-aware applications, using both WIF and AD FS 2.0 for their

authentication needs. The goal is to allow the middle tier to call the back-end service, acting as the caller

that is accessing the middle tier, and to accomplish that more securely without modifying the

application contracts between the middle tier and back end or between the middle tier and the end

user. The following diagram shows the overall application layout with the authentication data flow. Also

note that the claim requirements for middle tier are different than for the back-end service. The Web

front-end application requires Name and User Principal Name (UPN) claims, and the back-end service

requires Name, UPN, and Group claims. This guide demonstrates how to set up the claims

transformation rules at the AD FS 2.0 security token service (STS) to implement such scenarios.

Web Front-End

Bob

Browser Backend Service

ADFS 2.0 STS

Get Token for

Web Front-End

Token Representing Bob

Get Token for

Backend

Service

Acting As BobToken Representing

Web Front-End Acting

As Bob

ASP.NET Web

Application

WCF Service

Hosted in IIS

Required claims: Name,

UPNRequired claims: Name,

UPN, Group

For the purposes of this guide, you will use only a single domain environment, and you will need four

computers for the scenario. The following picture shows the network topology.

4

ContosoC1

(Win7)

10.0.0.4

ContosoDC

(Win2k8 R2)

10.0.0.1

ContosoSrv1

(Win2k8 R2)

10.0.0.2

ContosoSrv2

(Win2k8 R2)

10.0.0.3

AD PDC (Contoso.com)

ADFS v2 IdP/FP

ADCS

DNS (contoso.com)

Secondary DNS (fabrikam.com)

Web Front End App

Visual Studio 2008 SP1

IIS

WCF

WIF

WCF Backend service

Visual Studio 2008 SP1

IIS

WCF

WIF

Contoso\Administrator – Domain Admin

Contoso\Fred – Application developer

Admin on ContosoSrv1 and ContosoSrv2

Contoso\Bob – User running on the client

To set up the virtual machines (VMs), follow the steps in the prerequisites guide (below) for the

CONTOSO domain. You must set up one domain controller with Active Directory Domain Services

(AD DS), Active Directory Certificate Services (AD CS), and Domain Name System (DNS) roles enabled;

two servers with the Web server and Application server roles enabled, and Microsoft® Visual Studio®

2008 Professional (or Team Foundation) installed; and one client or server that will be used to access

the Web front-end application using Windows Internet Explorer®. Install the AD FS 2.0 STS on the

domain controller (use contosodc.contoso.com as the name for the STS instead of sts1.contoso.com, as

the guide suggests). Install WIF SDK on both CONTOSOSRV1 and CONTOSOSRV2. In addition, make sure

5

that you follow the installation guide and provision the Secure Sockets Layer (SSL) certificates on

CONTOSODC (before you install AD FS 2.0 STS) and both CONTOSOSRV1 and CONTOSOSRV2 by using the

domain certificate services through the Internet Information Services (IIS) Management console.

The IIS SSL certificates for CONTOSOSRV1 and CONTOSOSRV2 must have the common name (CN) part

set to their host names (contososrv1.contoso.com and contososrv2.contoso.com, respectively). For the

CONTOSODC, request a certificate with a CN set to contosodc.contoso.com and not *.contoso.com, as

the guide suggests.

Important:

This guide does not use the sts1.contoso.com name for the AD FS 2.0 STS name; it uses

contosodc.contoso.com instead. Because the service principal name (SPN) host/contosodc.contoso.com

is already registered on the machine account for the CONTOSODC computer, the AD FS 2.0 configuration

wizard will indicate that it was not able to register the SPN for the AD FS 2.0 service account

(CONTOSO/adfssrvc). Because of this, you must register the SPN for CONTOSO\adfssrvc manually by

using the following command:

setspn -S http/contosodc.contoso.com adfssrvc

You must execute this command with administrative credentials at a command prompt after the

AD FS 2.0 configuration is finished. If it is successful, the output of the setspn utility should look like this:

After the installation, make sure that you create the user accounts based on the image above, and make

CONTOSO\Fred the administrator on the CONTOSOSRV1 and CONTOSOSRV2 computers. Use the same

password as for the other accounts in the guide (p@ssw0rd).

Note: Make sure that you skip the SharePoint installation steps in the installation guide. You will not use

Microsoft SharePoint® Products and Technologies in this guide; installing it modifies the default Web

site inside IIS, making it unusable for the purposes of this guide.

Download and extract VMs For the purposes of this step by step guide, if you did not create your own set of VMs, download the

following files from here:

ContosoDC.zip

ContosoSrv1.zip

ContosoSrv2.zip

ContosoC1.zip

WS2008R2Fullx64Ent.zip

6

After the download is complete, extract the contents of the .zip files to a folder where the VMs will

reside, for example, extract the folder, ContosoDC, located in the ContosoDC.zip file to c:\VM\.

Repeat the step for ContosoSrv1, ContosoSrv2, and ContosoC1.

WS2008R2Fullx64Ent.zip file contains the base VHD that needs to be copied to the virtual hard disks

folder of each one of the virtual machine. For example for ContosoDC, copy the extracted

WS2008R2Fullx64Ent.vhd from WS2008R2Fullx64Ent.zip to c:\VM\ContosoDC\Virtual Hard Disks\

folder. Repeat the same step for ContosoSrv1, ContosoSrv2 and ContosoC1.

Create a new virtual network All the VM images (for server computers as well as client computers) are preconfigured to use a virtual

private network interface. The following procedure explains how to re-create this network in Hyper-V to

support the use of the VM images in your own test lab environment.

To create the virtual network for the AD FS 2.0 VM lab environment

1. On the host computer, open Hyper-V Manager.

To open Hyper-V Manger, on the Start menu, point to Administrative Tools, and then click Hyper-V Manager.

2. In Hyper-V Manager, on the Action menu, click Virtual Network Manager.

3. In Virtual Network Manager, click Internal for the type of virtual network that you want

to create, and then click Add.

4. In New Virtual Network, for Name type Internal-Network, verify that for Type the

Internal only option is selected, and then click OK.

Note that the network name is case sensitive and should be entered exactly as provided

above. All four VMs will need to use this network, which will be a "local only" interface.

All four VM images should already be IP-configured, as described in the following

section.

Import and start virtual machines Us the following procedure to import the four VMs with Hyper-V. You can import the VMs only on

Windows Server 2008 R2.

To import the AD FS 2.0 lab VMs

1. In Hyper-V Manager, on the Action menu, click Import Virtual Machine.

2. In the Import Virtual Machine dialog box, click Browse.

3. In the Select Folder dialog box, browse to and locate the named folder for the VM that

you want to import.

For example, to import the CONTOSODC VM, navigate to c:\VM and select ContosoDC folder, and then click Select Folder.

7

4. For the Settings, keep the Move or restore the virtual machine setting selected.

5. Click Import to begin importing the VM.

.

Repeat steps 1 through 4 for all VMs.

Setting Up IIS Bindings at CONTOSOSRV1 and CONTOSOSRV2 Follow these steps on both the CONTOSOSRV1 and CONTOSOSRV2 computers. Click Start, point to Administrative Tools, and then click IIS Manager. Select the Default Web Site node.

On the right side, click Bindings.

8

If HTTPS binding is present, select it, and then click Edit. If HTTPS binding is not present, click Add.

In the SSL certificate list, select the certificate for contososrv1.contoso.com (for the CONTOSOSRV2 computer, select contososrv2.contoso.com). Click OK.

9

Configuring Application Pool Settings at CONTOSOSRV1 This step is required for IIS 7.5 only (Windows 7 or Windows Server® 2008 R2) on the CONTOSOSRV1 computer. In IIS Manager, select the Application Pools node, and then select the DefaultAppPool.

On the right side, click Advanced Settings.

10

Set the Load User profile property to True, and then click OK.

Setting up Local Intranet Sites on CONTOSOSRV1 and CONTOSOC1 Do this step on CONTOSOSRV1 and CONTOSOC1 (and any other computers that you are using for testing the Web front-end (WFE) application).

11

Start Internet Explorer, select Tools, and then select Internet Options.

12

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

Click Advanced.

13

Under Websites, add https://contosodc.contoso.com and https://contososrv1.contoso.com to

the list of sites. You can also add http://contosodc.contoso.com, but it is not required for this guide.

Click Close. Click OK, and then click OK again.

Creating WFE Claims-Aware Web Application on CONTOSOSRV1 On the CONTOSOSRV1 computer, log on as CONTOSO\Fred. Make sure that you start Visual Studio 2008 as Administrator (to do this, right-click the Visual Studio 2008 icon, and then click Run as Administrator.

14

In Visual Studio 2008, on the File menu, point to New, and then select Web Site.

15

In the Language list, select Visual C#. In the Visual Studio installed templates list, select Claims-aware ASP.NET Web Site. Set the Location to HTTP, and then click Browse.

16

Click Local IIS, and expand Default Web Site. In the upper-right corner, click the Create New Web Application button, and then type WFE as a name for the new Web application. Select the Use Secure Sockets Layer check box at the bottom, and then click Open.

17

Change the Location from https://localhost/WFE to https://contososrv1.contoso.com/WFE, and then click OK.

Solution Explorer should appear as follows:

Make sure that you save the project and the solution. You can then press F5 and test the application. You can leave the password field blank in the logon page.

18

In the next step, you register the new Web application with the AD FS 2.0 STS.

Registering the WFE Application with AD FS 2.0 STS at CONTOSODC On the CONTOSOSRV1 computer, log on as Fred, and start Visual Studio 2008 with administrative credentials (right-click the Visual Studio 2008 icon, and select Run as Administrator). In Solution Explorer, right-click the WFE project, and select Add STS reference.

19

Verify that the values for Application configuration location and Application URI (uniform resource identifier) are set correctly, and then click Next.

20

Select Use an existing STS, and set the STS federation metadata location URL to

https://contosodc.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml. To verify the URL, click Test location. Internet Explorer opens the WS-Federation metadata document published by the AD FS v2 STS. If the document does not appear, verify that you typed the URL correctly as listed previously. After you verify that the URL works, click Next.

21

The AD FS 2.0 STS in this guide is configured with an automatically managed self-signed certificate that cannot be chained to any certification authority that the computer trusts. To allow the WFE service to consume tokens issued by this STS, you must disable chain-trust verification. Make sure that Disable certificate chain validation is selected, and then click Next.

22

Select No encryption, and then click Next.

23

Click Next again.

24

You can preview the actions that the Federation Utility will perform in this window. In this guide you will not schedule an automated task to update the application configuration based on the STS federation metadata document. Click Finish.

25

After the Federation Utility finishes, the application configuration is updated, and a federation document that describes the application authentication requirements is created. You can verify this by looking in Solution Explorer.

The two main changes made in the Web.config file are adding the WSFederationAuthenticationModule and SessionAuthenticationModule into the ASP.NET pipeline, and configuring the WIF runtime using the microsoft.identityModel section.

26

Make sure that you save both the project and solution for the WFE application.

Completing the Relying Party Registration at CONTOSODC Next, you must register the application with AD FS 2.0 STS that is running at CONTOSODC. Switch to the CONTOSODC computer, log on as CONTOSO\Administrator, and start AD FS 2.0 Management console.

27

Select the Relying Party Trusts node.

In the Actions list on the right side, click Add Relying Party Trust.

28

When the Add Relying Party Trust Wizard appears, click Start.

29

Select Import data about the relying party published online or on a local network. In the Federation

metadata address box, type https://contososrv1.contoso.com/WFE/FederationMetadata/2007-

06/FederationMetadata.xml. This is the location of the federation metadata document that was created by the Federation Utility in the previous section. Click Next.

30

Change the display name to signal that this entry represents the WFE application at contososrv1.contoso.com. You can also add some notes that are associated with this relying party trust. Click Next.

31

Verify that Permit all users to access this relying party is selected, and then click Next.

32

On the next page, you can preview the information about the relying party. Then click Next.

33

Make sure that the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes check box is selected, and then click Close.

34

The Edit Claim Rules dialog box appears. On the Issuance Transform Rules tab, click Add Rule.

35

In the Claim rule template list, select Send LDAP Attributes as Claims, and then click Next.

36

In the Claim rule name box, type Issue UPN and Name. In the Attribute store list, select Active Directory. Configure the rule to issue User-Principal-Name LDAP Attribute as UPN claim type, and the Display-Name LDAP Attribute as Name claim type. Click Finish.

37

The Issuance Transform Rules should now contain one rule that you just created. Click OK.

After you close the Edit Claim Rules dialog box, a new relying party trust appears in the AD FS 2.0 Management console under the Relying Party Trusts node.

38

You have now completed the registration procedure for the WFE application at the AD FS 2.0 STS. To verify that everything is set up correctly, go to the CONTOSOSRV1 computer and press F5 in Visual Studio. Internet Explorer should start, and after the authentication finishes, you should see UPN and Name claims that belong to the CONTOSO\Fred account along with authentication instant and authentication method claims. You can also switch to the CONTOSOC1 computer and test the application using the CONTOSO\Bob account by going to https://contososrv1.contoso.com/WFE.

Enabling the Application Pool Account to Access the SSL Certificate at

CONTOSOSRV2 Because the Federation Utility requires the WCF service to use an X.509 certificate to decrypt incoming security tokens issued by the STS, you will use the SSL certificate that is already provisioned on the CONTOSOSRV2 computer for this purpose. To do this, you must enable the processes that are running under the IIS application pool account to access the private key of this certificate. First, create a script with all the necessary steps, and then run this script with administrative credentials. At CONTOSOSRV2, start Notepad, and copy and paste the following text. @echo off setlocal set WIFSDKSCRIPTS=C:\Program Files (x86)\Windows Identity Foundation SDK\v3.5\Samples\Utilities\Scripts\

39

set CERTHASH= set KEYCONTAINER= set IIS7UTIL=IIS7Util.exe set CERTSUBJECTNAME="contososrv2.contoso.com, OU=IT, O=Contoso, L=Redmond, S=WA, C=US" pushd "%WIFSDKSCRIPTS%" for /f %%a in ('%IIS7UTIL% GetCertThumbprint my %CERTSUBJECTNAME%') do (set CERTHASH=%%a) for /f %%a in ('%IIS7UTIL% GetCertKeyContainer my %CERTHASH%') do (set KEYCONTAINER=%%a) popd pushd "%ALLUSERSPROFILE%\Microsoft\Crypto\RSA\MachineKeys" icacls %KEYCONTAINER% /grant *S-1-5-20:R icacls %KEYCONTAINER% /grant "IIS APPPOOL\DefaultAppPool":R

popd Make sure that the argument that is passed to the SetCertHashFromSubjectName.bat script matches the whole subject name of the contososrv2.contoso.com certificate, without the initial “CN=” prefix. Next, save the content of the Notepad file and name it configure_cert_key.bat. Next, start a new Command Prompt window with administrative credentials (on the Start menu, right-click the Command Prompt shortcut, and select Run as Administrator). Go to the directory where you saved the configure_cert_key.bat file, and run it. If everything goes correctly, the script will print two messages about setting ACLs on the private key file that corresponds to the SSL X.509 certificate. These messages come from the icacls utility that the script file uses.

Creating WCF Backend Service at CONTOSOSRV2 Switch over to the CONTOSOSRV2 computer, and log on as CONTOSO\Fred. Make sure that HTTPS binding is added to the default Web site in IIS Manager on CONTOSOSRV2, and that the contososrv2.contoso.com certificate is selected as the server's SSL certificate for this HTTPS binding. Start Visual Studio 2008 with administrative credentials (right-click the Visual Studio 2008 icon and select Run as Administrator).

40

First, you must create a new claims-aware WCF service. On the File menu, point to New, and then select Web Site.

In the New Web Site dialog box, in the Language list, select Visual C#. In the Templates list, select Claims-aware WCF Service. In the Location list, select HTTP, and then click Browse.

41

Select Local IIS, and under the Local Web Servers node, click the Default Web Site. In the upper-right corner, click the New Web application button. Type BackendService as the name of the new Web application. Select the Use Secure Sockets Layer, check box, and then click Open.

42

Change the location value to https://contososrv2.contoso.com/BackendService, and then click OK.

In Solution Explorer, open the IService.cs and Service.cs files from the App_Code node. You must change the default implementation of the service to return the information that you need. Change the IService.cs file as follows: using System.ServiceModel; namespace BackendService { [ServiceContract] public interface IService { [OperationContract] string GetData(string value); } }

Change the Service.cs file as follows: using System.Text; using System.Threading; using Microsoft.IdentityModel.Claims; namespace BackendService

43

{ public class Service : IService { public string GetData(string value) { IClaimsPrincipal principal = (IClaimsPrincipal)Thread.CurrentPrincipal; IClaimsIdentity identity = (IClaimsIdentity)principal.Identity; StringBuilder sb = new StringBuilder(); // Compute the result based on the input value. sb.AppendFormat("<div><p>You entered: <b>{0}</b></p>\n", value); // Print details about the caller's identity. sb.AppendFormat("<p>Caller's identity name: {0}</p>\n", identity.Name != null ? identity.Name : "Identity does not have a name"); sb.Append("Caller's claims:<br>\n"); PrintClaimsTable(sb, identity); // Print all the actors associated with the caller's identity. identity = identity.Actor; while (identity != null) { sb.AppendFormat("<p>Calling via identity: {0}</p>\n", identity.Name != null ? identity.Name : "Identity does not have a name"); sb.Append("With claims:<br>\n"); PrintClaimsTable(sb, identity); identity = identity.Actor; } sb.Append("</div>"); return sb.ToString(); } private static void PrintClaimsTable(StringBuilder sb, IClaimsIdentity identity) { sb.Append("<table style='width:100%;'><tr><th>Claim Type</th>" + "<th>Claim Value</th><th>Claim Issuer</th></tr>\n"); foreach (Claim claim in identity.Claims) { sb.AppendFormat("<tr><td>{0}</td><td>{1}</td><td>{2}</td></tr>\n", claim.ClaimType, claim.Value, claim.Issuer); } sb.Append("</table>\n"); } } }

Make sure that everything is typed correctly by building the solution (click Build, and then click Build Solution).

44

Registering Backend Service with AD FS 2.0 STS at CONTOSODC In Solution Explorer, right-click the BackendService project, and select Add STS reference.

45

Verify that the value for Application configuration location is correct, and change the Application URI to

https://contososrv2.contoso.com/BackendService/Service.svc (the value offered by the Federation Utility uses an http: URL scheme).

46

In the Service name list, make sure that BackendService.Service is selected, and in the Endpoint contract name list, make sure that BackendService.IService is selected. Click Next.

47

Select Use an existing STS, and in the STS federation metadata location box, type

https://contosodc.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml. You can click Test location to verify that you entered the correct URL. After you make sure that the URL is correct, click Next.

48

The AD FS 2.0 STS in this guide is configured with an automatically managed self-signed certificate that cannot be chained to any certification authority that the computer trusts. To allow the back-end service to consume tokens that are issued by this STS, you must disable chain-trust verification. Make sure that Disable certificate chain validation is selected, and then click Next.

The Federation Utility requires that the WCF services use the token encryption feature. Therefore, you must select a certificate that the back-end service will use to decrypt the incoming tokens. You will use the SSL certificate that was already provisioned on the CONTOSOSRV2 computer.

49

Select Enable encryption. Under Encryption Certificate, click Select an existing certificate from store, and then click Select Certificate.

Select the contososrv2.contoso.com certificate in the list, click OK, and then click Next in the Federation Utility window.

50

The next window shows the supported claim types that are provided by the AD FS 2.0 STS instance at CONTOSODC. Click Next.

51

The next window summarizes the changes that the Federation Utility will perform after you click Finish. Make sure that the Schedule a task to perform daily federation metadata updates check box is cleared, and then click Finish.

52

The Federation Utility modified the Web.config file. In particular, it updated the BackendService.Service binding to use wsFederation2007HttpBinding, and it configured the WIF runtime using the microsoft.identityModel section.

53

Next, you must add the STS endpoint that you want the BackendService clients to use when they request tokens for the BackendService. Because you know that you control all BackendService clients, you can determine an STS endpoint that will work for all of them. Note: In general, when the clients can come from various locations and use different identity provider STSs, the selection of the STS endpoint must be done at the client before initiating communication to the service. Applications can use the CardSpace component of the Windows operating system to externalize the endpoint selection from the application logic. To select the STS endpoint for the clients, you must modify the Web.config file in the BackendService project. Locate the message XML element in system.serviceModel/bindings/ws2007FederationHttpBinding/binding/security element. Change the mode attribute value from Message to TransportWithMessageCredential and add the following element, for example, after the issuerMetadata element (the order of elements in the message element is not important). <issuer address="https://contosodc.contoso.com/adfs/services/trust/13/kerberosmixed" />

This causes the BackendService to expose a WSDL document that instructs all its clients to go to the above endpoint when they request tokens for the BackendService. After you make the change, the whole ws2007FederationHttpBinding element should look like the following: <ws2007FederationHttpBinding> <binding name="BackendService.IService_ws2007FederationHttpBinding"> <security mode="TransportWithMessageCredential"> <message> <issuerMetadata address="https://contosodc.contoso.com/adfs/services/trust/mex" /> <issuer address="https://contosodc.contoso.com/adfs/services/trust/13/kerberosmixed"/> </issuer> <claimTypeRequirements> <!--Following are the claims offered by STS 'http://contosodc.contoso.com/adfs/services/trust'. Add or uncomment claims that you require by your application and then update the federation metadata of this application.--> <add claimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" isOptional="true" /> <add claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" isOptional="true" /> <!--<add claimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" isOptional="true" />--> <!--<add claimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" isOptional="true" />--> <!--<add claimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" isOptional="true" />--> <!--<add claimType="http://schemas.xmlsoap.org/claims/CommonName" isOptional="true" />-->

54

<!--<add claimType="http://schemas.xmlsoap.org/claims/EmailAddress" isOptional="true" />--> <!--<add claimType="http://schemas.xmlsoap.org/claims/Group" isOptional="true" />--> <!--<add claimType="http://schemas.xmlsoap.org/claims/UPN" isOptional="true" />--> <!--<add claimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" isOptional="true" />--> <!--<add claimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier" isOptional="true" />--> <!--<add claimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" isOptional="true" />--> <!--<add claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod" isOptional="true" />--> <!--<add claimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/denyonlysid" isOptional="true" />--> <!--<add claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarysid" isOptional="true" />--> <!--<add claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarygroupsid" isOptional="true" />--> <!--<add claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid" isOptional="true" />--> <!--<add claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid" isOptional="true" />--> <!--<add claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid" isOptional="true" />--> <!--<add claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname" isOptional="true" />--> </claimTypeRequirements> </message> </security> </binding> </ws2007FederationHttpBinding>

Completing the Relying Party Registration at the CONTOSODC Next, you must register the application with AD FS 2.0 STS running at CONTOSODC. Switch to the CONTOSODC computer, log on as CONTOSO\Administrator, and start AD FS 2.0 management console.

55

Select the Relying Party Trusts node.

In the Actions list on the right side, click Add Relying Party Trust.

The Add Relying Party Trust Wizard appears.

56

Click Start.

57

Select the Import data about the relying party published online or on a local network option, and in the Federation metadata address box, type

https://contososrv2.contoso.com/BackendService/FederationMetadata/2007-

06/FederationMetadata.xml. This is the location of the federation metadata document that was created by the Federation Utility in the previous section. Click Next.

58

Change the Display name to signal that this entry represents a back-end service application at contososrv2.contoso.com. You can also add some notes that are associated with this relying party trust. Click Next.

59

Verify that Permit all users to access this relying party is selected, and then click Next.

60

On the next page, you can preview the information about the relying party. Then, click Next.

61

Make sure that the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes check box is selected, and then click Close.

62

The Edit Claim Rules dialog box appears. On the Issuance Transform Rules tab, click Add Rule.

63

In the Claim rule template list, select Send LDAP Attributes as Claims, and then click Next.

64

Name the rule as Issue Group, UPN and Name claims. In the Attribute store list, select Active Directory, and configure the rule to issue Token-Groups - Qualified by Long domain name LDAP attribute as Group, and the User-Principal-Name LDAP attribute as UPN claim type, and the Display-Name LDAP attribute as Name claim type. Click Finish.

65

Click OK.

There should now be two relying party trusts listed in the AD FS 2.0 Management console.

66

Enabling Identity Delegation and Fixing Claims Issuance Rules at

CONTOSODC The claims issuance rule that you created in the previous step would work well if the user accessed the back-end service directly. However, in this case the back-end service will be accessed by the WFE ASP.NET application acting as the user. What will occur is that the WFE Web application will send a token request to the AD FS 2.0 STS at CONTOSODC, authenticating as the application pool account (CONTOSO\CONTOSOSRV1$ in this case), and sending along the security token that it received from its caller (the user who is accessing the WFE application through the browser). The WFE Web application will ask AD FS 2.0 STS to get a token for the back-end service, acting as the user, who is represented by the security token that is included in the request. The AD FS 2.0 STS now has two identities—the identity of the token requestor, CONTOSO\CONTOSOSRV1$, and the identity of the original caller, CONTOSO\Bob or CONTOSO\Fred—and it must issue claims for both and combine them correctly to issue the resulting token. To transform the identities, it will use the claim issuance rules that are associated with the BackendService relying party for both identities. Therefore, you must, make sure that the issuance rules that you associated with the BackendService will work for the application pool account and also the identities that represent the callers of the WFE application. But first, you must allow the WFE application to request a token acting as something else when communicating with the back-end service. For that, you must go back to the BackendService relying party trust. In AD FS 2.0 Management console, go to the Relying Party Trusts node, select the BackendService trust, and on the right side, click Edit Claims Rules.

67

Select the Delegation Authorization Rules tab, and then click Add Rule.

68

In the Claim rule template list, select Permit or Deny Users Based on an Incoming Claim, and then click Next.

69

In the Claim rule name box, type Allow WFE on contososrv1 to use ActAs feature. In the Incoming claim type list, select Windows account name. In the Incoming claim value box, type CONTOSO\CONTOSOSRV1$ (all uppercase letters). Make sure that Permit access to users with this incoming claim is selected, and then click Finish.

Next, you must update the Issuance Transform rules for the BackendService.

70

Select the Issuance Transform Rules tab. Currently you have only one rule in this section to issue Group, UPN, and Name claims from the Active Directory attribute store. If you click Edit Rule, and then click View Rule Language at the bottom of the dialog box, you see that this rule uses the WindowsAccountName claim issued by the AD AUTHORITY to select the Group, UPN, and Name claims. This works when the user directly authenticates to the STS; however, in this case, the user will be represented by a token that was issued by the AD FS 2.0 STS to the WFE application. Claims that are extracted from this token will not have the issuer set to AD AUTHORITY because they are not coming from the Windows Local Security Authority (LSA) process. Instead, the issuer will be set to SELF AUTHORITY because the claims are coming from a security token that is issued by the STS itself (in this case to the WFE application). To make the scenario work end to end, you must add another Issuance Transform Rule here that will issue Group, UPN, and Name claims based on a claim that comes from the security token with the SELF AUTHORITY issuer. To do this, you must create a custom claims transform rule. First, click Add Rule.

71

In the Claim rule template list, select Send Claims Using a Custom Rule, and then click Next.

Copy the following code, and paste it in the Custom rule text box. c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "SELF AUTHORITY"] => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/claims/Group", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"), query = ";tokenGroups(longDomainQualifiedName),userPrincipalName,displayName;{0}", param = c.Value);

72

Name the rule as Issue UPN, Name and Group claims using WindowsAccountName from an incoming token, and then click Finish.

73

The Claims Transform Rules section now has two rules in it. Click OK.

To make the rule that you created in the previous step work, you must make sure that the WindowsAccountName claim is issued for tokens targeted at the WFE application so that, when the WFE applications sends those tokens to the STS inside the ActAs element, the claims transformation rule that you just created will work. Select the WFE application relying party trust in the AD FS 2.0 Management Console, and then click Edit Claim Rules on the right side.

74

Click Add Rule to add a new rule that will issue the WindowsAccountName claim.

75

In the Claim rule template list, select Pass Through or Filter an Incoming Claim, and then click Next.

76

Name the rule Issued WindowsAccountName. In the Incoming claim type list, select Windows account name. Make sure that Pass through all claim values is selected, and then click Finish.

77

The Issuance Transform Rules section should now have two rules in it. Click OK.

At this point, you are finished with the configuration of the AD FS 2.0 STS with regards to identity delegation. In the next step, you finish the WFE application at CONTOSOSRV1 and test the solution end to end.

Finishing Up the WFE Application at CONTOSOSRV1 Switch to the CONTOSOSRV1 computer, and log on as CONTOSO\Fred. Start Visual Studio 2008 with administrative credentials (right-click the Visual Studio 2008 shortcut and select Run as Administrator). Open the WFE project.

78

First, you must add a reference to the BackendService to the WFE project. Right-click the WFE project, and select Add Service Reference.

79

In the Add Service Reference dialog box, in the Address box, type

https://contososrv2.contoso.com/BackendService/Service.svc, and then click Go. Select the IService contract under the Service node, and in the Namespace box below, type BackendServiceReference. Click OK.

In Solution Explorer, verify that the service reference was added to the project. The BackendServiceReference appears under the App_WebReferences node.

Next, you modify the Web.config file to make sure that the correct STS identity is configured for the Kerberos authentication that the WFE application will use to request tokens for the BackendService. Open the Web.config file, and locate the system.serviceModel/bindings/ws2007FederationHttpBinding/binding/security/message/issuer. Add the following as a child element of the issuer element: <identity> <servicePrincipalName value="http/contosodc.contoso.com"/> </identity>

80

After you make the changes, the ws2007FederationHttpBinding will look like the following example: <ws2007FederationHttpBinding> <binding name="WS2007FederationHttpBinding_IService" closeTimeout="00:01:00" openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00" bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard" maxBufferPoolSize="524288" maxReceivedMessageSize="65536" messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true"> <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384" maxBytesPerRead="4096" maxNameTableCharCount="16384" /> <reliableSession ordered="true" inactivityTimeout="00:10:00" enabled="false" /> <security mode="TransportWithMessageCredential"> <message algorithmSuite="Default" issuedKeyType="SymmetricKey" negotiateServiceCredential="true"> <issuer address="https://contosodc.contoso.com/adfs/services/trust/13/kerberosmixed" binding="customBinding" bindingConfiguration="https://contosodc.contoso.com/adfs/services/trust/13/kerberosmixed" > <identity> <servicePrincipalName value="http/contosodc.contoso.com"/> </identity> </issuer> <issuerMetadata address="https://contosodc.contoso.com/adfs/services/trust/mex" /> <tokenRequestParameters> <trust:SecondaryParameters xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <trust:KeyType xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey</trust:KeyType> <trust:KeySize xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">256</trust:KeySize> <trust:Claims Dialect="http://schemas.xmlsoap.org/ws/2005/05/identity" xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <wsid:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" Optional="true" xmlns:wsid="http://schemas.xmlsoap.org/ws/2005/05/identity" /> <wsid:ClaimType Uri="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" Optional="true" xmlns:wsid="http://schemas.xmlsoap.org/ws/2005/05/identity" /> </trust:Claims> <trust:KeyWrapAlgorithm xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p</trust:KeyWrapAlgorithm> <trust:EncryptWith xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">http://www.w3.org/2001/04/xmlenc#aes256-cbc</trust:EncryptWith> <trust:SignWith xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">http://www.w3.org/2000/09/xmldsig#hmac-sha1</trust:SignWith>

81

<trust:CanonicalizationAlgorithm xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">http://www.w3.org/2001/10/xml-exc-c14n#</trust:CanonicalizationAlgorithm> <trust:EncryptionAlgorithm xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">http://www.w3.org/2001/04/xmlenc#aes256-cbc</trust:EncryptionAlgorithm> </trust:SecondaryParameters> </tokenRequestParameters> </message> </security> </binding> </ws2007FederationHttpBinding>

While you are editing the Web.config file, you must make another change. Locate the microsoft.identityModel/service element, and change it by adding the following attribute to it. saveBootstrapTokens="true"

The changed element should look like this: <microsoft.identityModel> <service saveBootstrapTokens="true"> <audienceUris>

This change instructs WIF to store the security token that the caller used to authenticate to the application inside the session state so that the application does not have to do it. WIF will make this security token available to the application as long as the session between the user and the Web application exists. You will use this cached security token to request tokens for the BackendService acting as the original caller. Next, you modify the WFE application business logic to integrate it with the BackendService. First, you add the Global.asax file and use it to create and cache an instance of the WCF ChannelFactory object. This instance is then used by the Default.aspx page to make calls to the BackendService. Note: Creating ChannelFactory instances is a process that can take a lot of computing resources. Because the ChannelFactory can be used to create multiple channels, running under different credentials, we recommend that the middle-tier application avoid creating a ChannelFactory instance every time that a new channel is needed. In Solution Explorer, right-click the WFE project, and select Add New Item.

82

In the Templates list, select the Global Application Class, and then click Add.

Modify the Global.asax file to look like the following code example: <%@ Application Language="C#" %> <%@ Import Namespace="System.ServiceModel" %> <%@ Import Namespace="BackendServiceReference" %> <%@ Import Namespace="Microsoft.IdentityModel.Protocols.WSTrust" %> <script runat="server"> void Application_Start(object sender, EventArgs e) { // Code that runs on application startup. ChannelFactory<BackendServiceReference.IServiceChannel> service2CF = new ChannelFactory<BackendServiceReference.IServiceChannel>("WS2007FederationHttpBinding_IService"); service2CF.ConfigureChannelFactory(); Application["WFE_CachedChannelFactory"] = service2CF; } void Application_End(object sender, EventArgs e) {

83

// Code that runs on application shutdown. } void Application_Error(object sender, EventArgs e) { // Code that runs when an unhandled error occurs. } void Session_Start(object sender, EventArgs e) { // Code that runs when a new session is started. } void Session_End(object sender, EventArgs e) { // Code that runs when a session ends. // Note: The Session_End event is raised only when the sessionstate mode // is set to InProc in the Web.config file. If session mode is set to // StateServer or SQLServer, the event is not raised. } </script>

As you can see, you have implemented the Application_Start method. You create a new instance of the ChannelFactory<BackendServiceReference.IServiceChannel>, use the WIF ConfigureChannelFactory extension method (coming from the Microsoft.IdentityModel.Protocols.WSTrust namespace), and finally, store the prepared channel factory in the application state collection. Next, you modify the Default.aspx and Default.aspx.cs files to use the cached channel factory and expose the identity delegation feature to the WFE application users. First, open the Default.aspx file, and modify its source code to look like the following code example: <%@ Page Language="C#" AutoEventWireup="true" CodeFile="Default.aspx.cs" Inherits="_Default" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head id="Head1" runat="server"> <title>Claims-aware ASP.NET Web Site</title> <style type="text/css"> .style1 { font-size: large; font-weight: bold; } div { font-family: Verdana; font-size: small;

84

} p { font-size: small; } table { font-size: 9px; color: Gray; } </style> </head> <body> <p class="style1"> Windows Identity Foundation - Claims-aware ASP.NET Web Site</p> <div> <asp:Table ID="CallerClaims" runat="server"/> </div> <form id="form1" runat="server" method="post" defaultbutton="Button1" defaultfocus="TextBox1" > <div> Input value: <asp:TextBox ID="TextBox1" runat="server"></asp:TextBox> <br /> <asp:Button ID="Button1" runat="server" onclick="Button1_Click" Text="Call Backend Service" /> </div> </form> <asp:PlaceHolder ID="BackendServiceOutput" runat="server" /> </body> </html>

Next, open the Default.aspx.cs file, and modify its content as follows: using System; using System.Web.UI; using System.Web.UI.WebControls; using Microsoft.IdentityModel.Claims; using Microsoft.IdentityModel.Protocols.WSTrust; using System.Threading; using System.IdentityModel.Tokens; using System.ServiceModel; using BackendServiceReference; using System.Text; public partial class _Default : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { IClaimsPrincipal claimsPrincipal = Page.User as IClaimsPrincipal; IClaimsIdentity claimsIdentity = (IClaimsIdentity)claimsPrincipal.Identity; // The code below shows claims found in the IClaimsIdentity. // TODO: Change code below to do your processing using claims. TableRow headerRow = new TableRow();

85

TableCell claimTypeCell = new TableCell(); claimTypeCell.Text = "Claim Type"; claimTypeCell.BorderStyle = BorderStyle.Solid; TableCell claimValueCell = new TableCell(); claimValueCell.Text = "Claim Value"; claimValueCell.BorderStyle = BorderStyle.Solid; headerRow.Cells.Add(claimTypeCell); headerRow.Cells.Add(claimValueCell); CallerClaims.Rows.Add(headerRow); TableRow newRow; TableCell newClaimTypeCell, newClaimValueCell; foreach (Claim claim in claimsIdentity.Claims) { newRow = new TableRow(); newClaimTypeCell = new TableCell(); newClaimTypeCell.Text = claim.ClaimType; newClaimValueCell = new TableCell(); newClaimValueCell.Text = claim.Value; newRow.Cells.Add(newClaimTypeCell); newRow.Cells.Add(newClaimValueCell); CallerClaims.Rows.Add(newRow); } } protected void Button1_Click(object sender, EventArgs e) { SecurityToken callerToken = null; IClaimsPrincipal claimsPrincipal = Thread.CurrentPrincipal as IClaimsPrincipal; string value = TextBox1.Text; if (String.IsNullOrEmpty(value)) { value = "Default Input"; } // Get the Bootstrap Token. // We expect only one identity, which will contain the bootstrap token. if (claimsPrincipal != null && claimsPrincipal.Identities.Count == 1) { callerToken = claimsPrincipal.Identities[0].BootstrapToken; } if (callerToken == null) { BackendServiceOutput.Controls.Add(new LiteralControl( "<b>saveBootstrapTokens must be set to 'true' on the microsoft.identityModel/service element</b>")); return; } // Get the channel factory to the back-end service

86

// from the application state. ChannelFactory<BackendServiceReference.IServiceChannel> factory = (ChannelFactory<BackendServiceReference.IServiceChannel>)Application["WFE_CachedChannelFactory"]; // Create and set up channel to talk to the back-end service. BackendServiceReference.IServiceChannel channel; // Set up the ActAs to point to the caller's token so that we perform a // delegated call to the back-end service // on behalf of the original caller. // // Note: A new channel must be created for each call. channel = factory.CreateChannelActingAs(callerToken); string retval = null; // Call the back-end service and handle the possible exceptions. try { retval = channel.GetData(value); channel.Close(); } catch (CommunicationException exception) { StringBuilder sb = new StringBuilder(); sb.AppendLine("<pre>"); sb.AppendLine(exception.Message); sb.AppendLine(exception.StackTrace); Exception ex = exception.InnerException; while (ex != null) { sb.AppendLine("==========================="); sb.AppendLine(ex.Message); sb.AppendLine(ex.StackTrace); ex = ex.InnerException; } sb.AppendLine("</pre>"); channel.Abort(); retval = sb.ToString(); } catch (TimeoutException) { channel.Abort(); retval = "<p>Timed out...</p>"; } catch (Exception exception) { StringBuilder sb = new StringBuilder(); sb.AppendLine("<pre>"); sb.AppendLine("An unexpected exception occured."); sb.AppendLine(exception.StackTrace); sb.AppendLine("</pre>"); channel.Abort(); retval = sb.ToString(); }

87

BackendServiceOutput.Controls.Add(new LiteralControl(retval)); } }

This change added an input box and button to the default page and registered an OnClick handler with the button. The event handler will use the cached channel factory instance to construct a new channel, acting as the original caller. To get a representation of the original caller, the event handler uses the BootstrapToken extension property in the IClaimsIdentity class. callerToken = claimsPrincipal.Identities[0].BootstrapToken;

The event handler then uses the callerToken to construct the channel using the CreateChannelActingAs extension method: channel = factory.CreateChannelActingAs(callerToken);

Next, it invokes the service, using the value that is provided in the input box, correctly handing any exceptions that this call might cause. retval = channel.GetData(value); channel.Close();

Finally, it displays the result using the BackendServiceOutput placeholder control. BackendServiceOutput.Controls.Add(new LiteralControl(retval));

Make sure that you save all the modified files and project.

Testing the Final Application Next, switch to the CONTOSOC1 computer (you can also perform this step from the CONTOSOSRV1 computer), and log on as CONTOSO\Bob. Start Internet Explorer, and in the address bar, enter

https://contososrv1.contoso.com/WFE, and press ENTER. After the authentication, you should see the default page that displays Bob's name, UPN, and WindowsAccountName claims along with authentication method and authentication instant claims. Next, type a value in the input box, and click Call Backend Service. The result of the call appears below the button, as shown in the following image.

88