AD FS 2.0 Step-by-Step Guide: Federation with Ping Identity PingFederate

Updated: November 24, 2010

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

About This Guide

This guide provides step-by-step instructions for configuring a basic identity federation deployment between Microsoft® Active Directory® Federation Services 2.0 (AD FS 2.0) and Ping Identity® PingFederate® by using the Security Assertion Markup Language (SAML) 2.0 protocol (https://go.microsoft.com/fwlink/?LinkId=193996) with the SAML2.0 HTTP POST binding.

Terminology Used in This Guide

Throughout this document, there are numerous references to federation concepts that are called by different names in the Microsoft and PingFederate products. The following table assists in drawing parallels between the two vendors’ technologies.

AD FS 2.0 name	PingFederate name	Concept
Security Token	Assertion	A collection of XML-formatted security information, describing a user, that is created and consumed during a federated access request
Claims Provider	Identity Provider (IdP)	The partner in a federation that creates security tokens for users
Relying Party	Service Provider (SP)	The partner in a federation that consumes security tokens for providing access to applications
Claims	Assertion attributes	Data about users that is sent inside security tokens

In this deployment, you have the option of configuring either (or both) of two scenarios:

• AD FS 2.0 as claims/identity provider and PingFederate as relying party/service provider

• PingFederate as claims/identity provider and AD FS 2.0 as relying party/service provider

About the Author

Dave Martinez (dave@davemartinez.net) is Principal of Martinez & Associates, a technology consultancy based in Redmond, Washington.

Prerequisites and Requirements

This lab requires two computers—one to host PingFederate, and the other to host AD FS 2.0. This document presumes the pre-existence of functioning deployments of PingFederate and AD FS 2.0, as described below.

PingFederate

A test deployment created with the PingFederate Quick-Start Applications (https://go.microsoft.com/fwlink/?LinkId=206361) is used as a starting point for this lab. The Quick-Start setup process configures a single PingFederate instance to perform both the identity provider (IdP) and service provider (SP) roles, and it deploys sample applications.

This guide assumes that the PingFederate computer is configured as follows.

Windows

• Host operating system: Windows Server® 2008 R2

• Web server role (Internet Information Services (IIS)) installed to host the preformatted hyperlinks that initiate federated access:

  • Default website ports: HTTP (80) and HTTPS (443)

• Windows Firewall with Advanced Security turned off, to easily allow for HTTPS communications on nonstandard ports (see below)

PingFederate

• Product version: PingFederate 6.3.

• Ports used: Use default port 9999 for the administrative console and default port 9031 for HTTPS-protected federation traffic.

• PingFederate Base URL: https://localhost:9031

• Quick-Start application URLs:

  - IdP Application URL: https://localhost:9031/quickstart-app-idp/go  
      
  - SP Application URL: https://localhost:9031/quickstart-app-sp/go  
      

For more information about installation and deployment, see the PingFederate documentation library (https://go.microsoft.com/fwlink/?LinkId=206362).

AD FS 2.0

The test deployment that was created in the AD FS 2.0 Federation with a WIF Application Step-by-Step Guide (https://go.microsoft.com/fwlink/?LinkId=193997) is used as starting point for this lab. That lab uses a single Windows Server 2008 R2 instance (fsweb.contoso.com) to host both the AD FS 2.0 federation server and a Windows® Identity Foundation (WIF) sample application. It presumes the availability of a “Contoso.com” domain, in which fsweb.contoso.com is a member server. The same computer can act as the domain controller and federation server in test deployments.

Preconfiguration Tasks

Perform the following prerequisite configuration steps to prepare the environment for federation testing.

Make Quick-Start Deployment Network-Ready

The PingFederate Quick-Start setup process configures a single PingFederate instance to perform both the IdP and SP roles, performing a loopback that sends messages to and from itself at the web address https://localhost. For this lab to work, you must modify the Quick-Start deployment to send and receive messages in a network environment so that your PingFederate server responds to messages from your AD FS 2.0 computer (fsweb.contoso.com).

The modifications change the address https://localhost in the Quick-Start configuration to an external web address. For this lab, we will use the address https://ping.example.com.

For detailed instructions, see the “Configuring Other Deployments: Using Separate Servers” section of “Chapter 4: Modifying the Configuration” of the PingFederate Quick-Start Guide in the Quick-Start distribution.

As a result of the changes that you make in this section, your deployment should now use the following URLs:

• PingFederate Base URL: https://ping.example.com:9031

• Quick-Start application URLs:

  • IdP Application URL: https://ping.example.com:9031/quickstart-app-idp/go

  • SP Application URL: https://ping.example.com:9031/quickstart-app-sp/go

After performing the Ensure IP Connectivity and Configure Name Resolution steps below, test the Quick-Start deployment for network-readiness by visiting either the Quick-Start IdP or SP application at https://ping.example.com:9031 from the AD FS 2.0 computer (fsweb.contoso.com) and performing federated SSO, using the same testing process described in the PingFederate Quick-Start Guide.

Ensure IP Connectivity

Make sure that the PingFederate (ping.example.com) and AD FS 2.0 (fsweb.contoso.com) computers have IP connectivity between them. The Contoso.com domain controller, if it is running on a separate computer, does not require IP connectivity to the PingFederate system.

Configure Name Resolution

In this lab, we will use the hosts file on both computers to configure name resolution of the partner federation servers and sample applications.

To configure name resolution

1. Locate the hosts file on the PingFederate computer (ping.example.com). The default location is C:\windows\system32\drivers\etc\hosts.

2. Right-click the file, and then click Open. Select Notepad to open the file.

3. Add an entry for fsweb.contoso.com, for example:
   192.168.1.2    fsweb.contoso.com

4. If ping.example.com is not a Windows domain controller, add a second entry that points to itself in the hosts file, for example:
   192.168.1.3    ping.example.com

5. Save and close the file.

6. Locate the hosts file on the AD FS 2.0 computer (fsweb.contoso.com), and open it with Notepad.

7. Add an entry for ping.example.com, for example:
   192.168.1.3    ping.example.com

8. Save and close the file.

Verify Clock Synchronization

Federation events typically have a short Time to Live (TTL). To avoid errors based on time-outs, ensure that both computers have their clocks synchronized.

Enable SSL Server Authentication

Federation relies heavily on public key infrastructure (PKI), including Secure Sockets Layer (SSL) encryption, for trustworthy transactions. Earlier, when you made the PingFederate Quick-Start deployment network-ready, you created a new self-signed SSL certificate for the PingFederate server. Now, add this SSL certificate into the Trusted Roots store of the AD FS 2.0 computer (fsweb.contoso.com). This allows Internet Explorer to trust the web server during HTTPS communications.

To install the PingFederate SSL certificate on fsweb.contoso.com

1. From fsweb.contoso.com, use Internet Explorer to go to https://ping.example.com:9031/pf/heartbeat.ping. This is a PingFederate system status endpoint, which should return an “OK” message if PingFederate is running.

2. At the security warning, click the link to continue to the website. The Address Bar will turn red to signify that the page is protected by an SSL certificate that is not trusted.

3. Click the Certificate Error message next to the Internet Explorer address bar, and then click View certificates.

4. In the Certificate window, on the General tab click Install Certificate to start the Certificate Import Wizard.

5. Click Next.

6. In the Certificate Store window, click Place all certificates in the following store.

7. Click Browse, and then click Show physical stores.

8. Select Local Computer in the Trusted Root Certificate Authorities folder, and then click OK.

9. Click Next, click Finish, click OK, and then click OK.

10. Close and reopen Internet Explorer, and then go back to the web address. The address bar should remain white, signifying a working SSL channel.

Update the AD FS 2.0 Sample User Account

The PingFederate Quick-Start application expects multiple inbound assertion attributes that are not present by default in the Administrator account used by AD FS 2.0 in its step-by-step guide. To demonstrate federation more comprehensively, we will add data to the Administrator account that will manifest itself in security tokens that AD FS 2.0 generates for PingFederate.

To add data to the Administrator account in the Contoso Active Directory

1. Log in to the Contoso domain controller computer as CONTOSO\administrator.

2. Click Start, click Administrative Tools, and then click Active Directory Users and Computers.

3. In the console tree, under Contoso.com, click the Users folder.

4. In the right pane, right-click Administrator, and then click Properties.

5. On the General tab, add the following values, and then click OK.

   Name	Value
   Display name	Joe Admin
   E-mail	admin@contoso.com

Configure AD FS 2.0 as the Claims Provider and PingFederate as the Relying Party

In this step, you configure the scenario in which the Contoso domain administrator (through AD FS 2.0) receives federated access to the Example.com sample application (using PingFederate). The scenario uses the SAML 2.0 POST profile.

Configure PingFederate

Add a New IdP Connection Using Metadata

You can add an IdP partner using AD FS 2.0 into PingFederate either manually or through metadata import. In this lab, we will use metadata import. The AD FS 2.0 metadata file includes information about performing both the identity provider and service provider roles, including the public key that is used to validate security tokens that AD FS 2.0 signs in the identity provider role.

To add a new IdP Connection using metadata

1. From the PingFederate computer (ping.example.com), use Internet Explorer to go to the AD FS 2.0 metadata XML file at https://fsweb.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml.

2. At the security warning, click the link to continue to the website.

3. Click Page, and then click Save As to save FederationMetadata.xml to the desktop.

4. In the PingFederate administrative console, on the Main Menu page under My SP Configuration, click Create New under IdP Connections.

5. On the Connection Type page, leave Browser SSO Profiles selected, and then click Next.

6. On the Connection Options page, leave Browser SSO selected, and then click Next.

7. On the Import Metadata page, click Browse, select the FederationMetadata.xml file that you saved to the desktop earlier, click Open, and then click Next.

8. On the Metadata Summary page, and then click Next.

9. On the General Info page, in the Connection Name field, replace the existing contents with Contoso-ADFS2, and then click Next.

10. On the Browser SSO page, click Configure Browser SSO.

11. On the SAML Profiles page, select the check boxes next to IdP-Initiated SSO and SP-initiated SSO, and then click Next.

12. On the User-Session Creation page, click Configure User-Session Creation.

13. On the Identity Mapping page, leave Account Mapping selected, and then click Next.

14. On the Attribute Contract page, click Next.

15. On the Adapter Mapping & User Lookup page, click Map New Adapter Instance.

16. On the Adapter Instance page, in the Adapter Instance drop-down list, select SP Adapter, and then click Next.

17. On the Adapter Data Store page, leave Use only the attributes available in the SSO assertion selected, and then click Next.

18. On the Adapter Contract Fulfillment page, fill in the following values, and click Next.

    Adapter contract	Source	Value
    email address	Assertion	https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    member status	Assertion	https://schemas.microsoft.com/ws/2008/06/identity/claims/role
    name	Assertion	https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    userid	Assertion	SAML_SUBJECT

19. On the Adapter Mapping Summary page, click Done.

20. On the Adapter Mapping & User Lookup page, click Next.

21. On the User-Session Creation Summary page, click Done.

22. On the User-Session Creation page, click Next.

23. On the Protocol Settings page, click Configure Protocol Settings.

24. On the SSO Service URLs page, leave the Redirect and POST endpoints as /adfs/ls/, and then click Next.

25. On the Allowable SAML bindings page, clear the check boxes next to Artifact, Redirect, and SOAP (leaving only POST selected), and then click Next.

26. On the Signature Policy page, leave Use SAML-standard signature requirements selected, and then click Next.

27. On the Encryption policy page, leave None selected and click Next.

28. On the Protocol Settings summary page, click Done.

29. On the Protocol Settings page, click Next.

30. On the Browser SSO summary page, click Done.

31. On the Browser SSO page, click Next.

32. On the Credentials page, click Next.

33. On the Activation & Summary page, change Connection Status to Active, and then click Save.

34. On the Manage IdP Connections page, click Save.

Export Service Provider Metadata to a File

Export the metadata file that AD FS 2.0 will use to automate setup of the PingFederate relying party instance in the next section.

To export SP metadata to a file

1. In the PingFederate administrative console, on the Main Menu page under My SP Configuration, click Manage all IdP under IdP Connections.

2. On the Manage Connections page, click Export Metadata next to the connection named Contoso-ADFS2.

3. On the Metadata Signing page, in the drop-down list, select the certificate with cn=demo dsig.

4. Select Include this certificate’s public key certificate in the element check box, and then click Next.

5. On the Export & Summary page, click Export.

6. Click Save, change the file name to ping_sp_metadata.xml, and then save the file to a location where the AD FS 2.0 computer (fsweb.contoso.com) can access it.

7. Click Close.

8. Click Done.

Configure AD FS 2.0

Add a Relying Party Using Metadata

You can add a relying party partner using PingFederate into AD FS 2.0 either manually or through metadata import. In this lab, you use metadata import.

To add a relying party using metadata

1. In AD FS 2.0, in the console tree, right-click the Relying Party Trusts folder, and then click Add Relying Party Trust to start the Add Relying Party Trust Wizard.

2. Click Start.

3. On the Select Data Source page, click Import data about the relying party from a file.

4. In Federation metadata file location, click Browse.

5. Navigate to the location where you saved ping_sp_metadata.xml earlier, click Open, and then click Next.

6. On the Specify Display Name page, type Ping Example, and then click Next.

7. On the Choose Issuance Authorization Rules page, leave the default Permit all users to access the relying party selected, and then click Next.

8. Click Next, and then click Close.

Edit Claim Rules for Relying Party Trust

Claim rules describe how AD FS 2.0 determines what data should reside inside the federation security tokens it generates. The claim rule in this section describes how data from Active Directory is inserted in the security token that created for PingFederate.

To edit the claim rules for a relying party trust

1. The Edit Claim Rules dialog box should already be open. If not, In the AD FS 2.0 center pane, under Relying Party Trusts, right-click Ping Example, and then click Edit Claim Rules.

2. On the Issuance Transform Rules tab, click Add Rule.

3. On the Select Rule Template page, leave Send LDAP Attributes as Claims selected, and then click Next.

4. On the Configure Claim Rule page, in the Claim rule name box, type Get attributes.

5. In the Attribute Store list, select Active Directory.

6. In the Mapping of LDAP attributes section, create the following mappings.

   LDAP attribute	Outgoing claim type
   Display-Name	Name
   E-Mail-Addresses	E-Mail Address
   SAM-Account-Name	Name ID

7. Click Finish.

8. On the Issuance Transform Rules tab, click Add Rule.

9. On the Select Rule Template page, select Send Group Membership as a Claim, and then click Next.

10. On the Configure Claim Rule page, in the Claim rule name box, type Member status.

11. In User’s group, click Browse, type Domain Users, and then click OK.

12. In Outgoing claim type, select Role.

13. In Outgoing claim value, type Gold, and then click Finish.

14. Click OK.

Create Link for Initiating Federated Access

Initiating federated access to a PingFederate-protected application can be done either by accessing the secured application directly or by using a preformatted hyperlink. Accessing the application directly results in a redirect to a PingFederate-hosted page for IdP selection, similar in purpose to the AD FS 2.0 HomeRealmDiscovery.aspx page. This page can be replaced with a custom selection page.

Initiating federation with a preformatted hyperlink automatically directs a user to an IdP federation server to get a security token. This link can be located either at the account side (for example, on a Contoso employee portal page) or at the resource side (for example, on an unprotected Example.com site page providing authentication options).

Regardless of its physical location, the link can direct users to the PingFederate server or the AD FS 2.0 server. Because they are separate products, the syntax of the link changes depending on which approach is chosen.

In this lab, we will host links on a web page on the PingFederate computer (ping.example.com), which is served by IIS. We will include links that demonstrate all three ways to initiate access.

To create a link for initiating federated access

1. On the PingFederate computer (ping.example.com), open Notepad.

2. Add the following to a new document:

   <p>Welcome to Example.com!</p>
   <p>Test Links - From AD FS 2.0 (IdP) to PingFederate (SP)</p>
   <a href="https://ping.example.com:9031/quickstart-app-sp/go">Link for SP-initiated SSO via direct application access & IdP selection</a>
   <p>
   <a href="https://ping.example.com:9031/sp/startSSO.ping?PartnerIdpId=https://fsweb.contoso.com/adfs/services/trust&TargetResource=https://ping.example.com:9031/quickstart-app-sp/go">Link for SP-initiated SSO via PingFederate server access</a>
   <p>
   <a href=" https://fsweb.contoso.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=PF-DEMO "> Link for IdP-initiated SSO via AD FS 2.0 server access</a>
   

3. In Notepad, on the File menu, click Save.

4. In the Save As window, navigate to the C:\inetpub\wwwroot folder.

5. In Save as type, select All Files (*.*), and in File name, type index.htm.

6. Click Save, and then close index.htm.

Test AD FS 2.0 as the Claims Provider and PingFederate as the Relying Party

In this scenario, the Contoso domain administrator accesses the federated sample application at Example.com.

To access the adatum.com application

1. Log in to the console of the fsweb.contoso.com server using the CONTOSO\administrator account.

2. Open a browser window and navigate to https://ping.example.com.

3. Click the links to test SSO to PingFederate from AD FS 2.0.

At this point, you should see the PingFederate sample application. Review the log files for AD FS 2.0 in Event Viewer and for PingFederate at c:\pingfederate\log (server.txt) to see the security token information that is passed between environments.

Configure PingFederate as the Claims Provider and AD FS 2.0 as the Relying Party

In this step, you configure a scenario in which an Example.com user (using PingFederate) gets federated access to the WIF sample application through AD FS 2.0. As before, this scenario uses the SAML 2.0 POST profile.

Configure PingFederate

Add a New SP Connection Using Metadata

As before, we will use metadata import to add an SP partner using AD FS 2.0 into PingFederate.

To add a new SP Connection using metadata

1. In the PingFederate administrative console, on the Main Menu page under My IdP Configuration, click Create New under SP Connections.

2. On the Connection Template page, leave Do not use a template for this connection selected, and then click Next.

3. On the Connection Type page, leave Browser SSO Profiles selected, and then click Next.

4. On the Connection Options page, leave Browser SSO selected, and then click Next.

5. On the Import Metadata page, click Browse, select the FederationMetadata.xml file that you saved to the desktop earlier, click Open, and then click Next.

6. On the Metadata Summary page, click Next.

7. On the General Info page, in Connection Name, replace the existing contents with Contoso-ADFS2, and then click Next.

8. On the Browser SSO page, click Configure Browser SSO.

9. On the SAML Profiles page, select the check boxes next to IdP-Initiated SSO and SP-initiated SSO, and then click Next.

10. On the Assertion Lifetime page, leave the default validity times, and then click Next.

11. On the Assertion Creation page, click Configure Assertion Creation.

12. On the Identity Mapping page, leave Standard selected, and then click Next.

13. On the Attribute Contract page, in the Extend the Contract box, type https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.

14. Click Add, and then click Next.

15. On the IdP Adapter Mapping page, click Map New Adapter Instance.

16. On the Adapter Instance page, in the Adapter Instance drop-down list, select IdP Adapter, and then click Next.

17. On the Assertion Mapping page, leave Use only the attributes available in the SSO assertion selected, and then click Next.

18. On the Attribute Contract Fulfillment page, fill in the following values, and then click Next.

    Attribute contract	Source	Value
    SAML_SUBJECT	Adapter	email
    https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	Text	${fname} ${lname}

19. On the IdP Adapter Mapping Summary page, click Done.

20. On the IdP Adapter Mapping page, click Next.

21. On the Assertion Creation Summary page, click Done.

22. On the Assertion Creation page, click Next.

23. On the Protocol Settings page, click Configure Protocol Settings.

24. On the Assertion Consumer Service URLs page, click delete under Action for the Artifact endpoint listing. When the remaining settings are listed as follows, click Next.

    Default	Index	Binding	Endpoint URL
    default	0	POST	/adfs/ls/
    	2	Redirect	/adfs/ls/

25. On the Allowable SAML bindings page, clear the check boxes next to the Artifact and SOAP (leaving only POST and Redirect selected), and then click Next.

26. On the Signature Policy page, leave Always sign the SAML assertion selected, and then click Next.

27. On the Encryption policy page, leave None selected, and then click Next.

28. On the Protocol Settings summary page, click Done.

29. On the Protocol Settings page, click Next.

30. On the Browser SSO summary page, click Done.

31. On the Browser SSO page, click Next.

32. On the Credentials page, click Configure Credentials.

33. On the Digital Signature Settings page, in the drop-down list, choose the certificate with cn=demo dsig, and then click Next.

34. On the Credentials Summary page, click Done.

35. On the Credentials page, click Next.

36. On the Activation & Summary page, change Connection Status to Active, and then click Save.

37. On the Manage SP Connections page, click Save.

Export Identity Provider Metadata to a File

Export the metadata file AD FS 2.0 that will use to automate setup of the PingFederate claims provider instance in the next section.

To export IdP metadata to a file

1. In the PingFederate administrative console, on the Main Menu page under My IdP Configuration, click Manage all SP under SP Connections.

2. On the Manage Connections page, click Export Metadata next to the connection named Contoso-ADFS2.

3. On the Metadata Signing page, in the drop-down list, choose the certificate with cn=demo dsig.

4. Select the Include this certificate’s public key certificate in the element check box, and then click Next.

5. On the Export & Summary page, click Export.

6. Click Save, change the file name to ping_idp_metadata.xml, and then save the file to a location where the AD FS 2.0 computer (fsweb.contoso.com) can access it.

7. Click Close.

8. Click Done.

Configure AD FS 2.0

Add a Claims Provider Using Metadata

Once again, you use the metadata import capabilities of AD FS 2.0 to create the Example.com claims provider. The metadata includes the public key that is used to validate security tokens that are signed by PingFederate.

To add a relying party using metadata

1. In AD FS 2.0, in the console tree, right-click the Claims Provider Trusts folder, and then click Add Claims Provider Trust to start the Add Claims Provider Trust Wizard.

2. Click Start.

3. On the Select Data Source page, select Import data about the claims provider from a file.

4. In the Federation metadata file location field, click Browse.

5. Navigate to the location where you saved ping_idp_metadata.xml earlier, click Open, and then click Next.

6. On the Specify Display Name page, type Ping Example, and then click Next.

7. Click Next, and then click Close.

Edit Claim Rules for Claims Provider Trust

The following claim rule describes how data from PingFederate is used in the security token that is sent to the WIF sample application.

To edit the claim rule for a claims provider trust

1. The Edit Claim Rules window should be open. If not, in the AD FS 2.0 center pane, under Claims Provider Trusts, right-click Ping Example, and then click Edit Claim Rules.

2. On the Acceptance Transform Rules tab, click Add Rule.

3. On the Select Rule Template page, select the Pass Through or Filter an Incoming Claim check box, and then click Next.

4. On the Configure Claim Rule page, use the following values.

   Name	Value
   Claim rule name	Name ID Rule
   Incoming claim type	Name ID
   Incoming name ID format	Unspecified

5. Select the Pass through only claim values that match a specific email suffix value option. In Email suffix value, type example.com, and then click Finish.

6. Click Add Rule again.

7. On the Select Rule Template page, select the Pass Through or Filter an Incoming Claim check box, and then click Next.

8. On the Configure Claim Rule page, in Claim rule name, use the following values.

   Name	Value
   Claim rule name	Name Rule
   Incoming claim type	Name

9. Leave the Pass through all claim values option selected, and then click Finish.

10. To acknowledge the security warning, click Yes.

11. Click OK.

Edit Claim Rules for the WIF Sample Application

At this point, incoming claims have been received at AD FS 2.0, but rules that describe what to send to the WIF sample application have not yet been created. You now edit the existing claim rules for the sample application to take into account the new PingFederate external claims provider.

To edit the claim rules for the WIF sample application

1. In AD FS 2.0, in the left navigation area, click Relying Party Trusts. In the center pane, right-click WIF Sample App, and then click Edit Claim Rules.

2. On the Issuance Transform Rules tab, click Add Rule.

3. On the Select Rule Template page, click Pass Through or Filter an Incoming Claim, and then click Next.

4. On the Configure Claim Rule page, type the following values.

   Name	Value
   Claim rule name	Pass Name Rule
   Incoming claim type	Name

5. Leave the Pass through all claim values option selected, and then click Finish.

6. On the Issuance Transform Rules tab, click Add Rule.

7. On the Select Rule Template page, click Pass Through or Filter an Incoming Claim, and then click Next.

8. On the Configure Claim Rule page, type the following values.

   Name	Value
   Claim rule name	Pass Name ID Rule
   Incoming claim type	Name ID
   Incoming Name ID format	Unspecified

9. Leave the Pass through all claim values option selected, and then click Finish.

10. Click OK.

Change AD FS 2.0 Signature Algorithm

When it signs assertions, PingFederate defaults to using the Secure Hash Algorithm 1 (SHA-1) for signing operations, while by default AD FS 2.0 expects partners to use SHA-256. Follow the steps below to set AD FS 2.0 to expect SHA-1 for interoperability with PingFederate.

To change the AD FS 2.0 signature algorithm

1. In AD FS 2.0, in the left navigation area, click Claims Provider Trusts. In the center pane, right-click Ping Example, and then click Properties.

2. On the Advanced tab, in the Secure hash algorithm list, select SHA-1, and then click OK.

Create Link for Initiating Federated Access (optional)

Initiating federated access to an AD FS 2.0-protected application can use a preformatted hyperlink, or a user can visit the application directly and leverage AD FS 2.0 home realm discovery, which provides an interface to allow a user to select their IdP from a list.

In this lab, we will access the application directly and use home realm discovery. However, as an option, we will also host an SP-initiated SSO (from AD FS 2.0) link on our IIS page.

To create a link for initiating federated access

1. On the PingFederate computer (ping.example.com), navigate to c:\inetpub\wwwroot\ index.htm

2. Right-click index.htm, and then click Open With. Select Notepad to open the file.

3. Add the following to the end of the document:

   <p>Test Links – From PingFederate (IdP) to AD FS 2.0 (SP)</p>
   <a href="https://fsweb.contoso.com/adfs/ls/?wa=wsignin1.0&wtrealm=https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/default.aspx&whr=PF-DEMO"> Link for SP-initiated SSO via AD FS 2.0 server access</a>
   

4. Save and close the file.

Test PingFederate as the Claims Provider and AD FS 2.0 as the Relying Party

In this scenario, John from Example.com accesses the Contoso WIF sample application.

To access the WIF sample application

1. On the AD FS 2.0 computer, open a browser window, and then navigate to https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/default.aspx.

2. The first page prompts you to select your organization from a list. Select Ping Example, and then click Continue to Sign In.

3. PingFederate Quick-Start forms logon page appears. Select the user name john, type the password test, and then click Login.

At this point, you should see the WIF sample application. Note the presence of the name claim, which was an additional assertion attribute. Also note the nameidentifier claim, which successfully passed the rule limitation of using only addresses with the example.com suffix.

Review the log files for AD FS 2.0 in Event Viewer and for PingFederate at c:\pingfederate\log (server.txt) to see the security token information that was passed between environments.

Appendix

The purpose of this section is to highlight other possibilities that are outside the scope of this document but available to architects when they deploy federation between AD FS 2.0 and PingFederate.

Additional Protocol Support

In addition to SAML 2.0, AD FS 2.0 also supports use of the WS-Federation protocol for web browser-based federation and SSO (sometimes called passive client SSO). PingFederate likewise supports WS-Federation.

Also, both AD FS 2.0 and PingFederate support use of the WS-Trust protocol for application-based federation and SSO (sometimes called active client SSO). Active clients can support more-advanced federation scenarios.

Certification Authority-Issued Signing/Encryption Certificates

For security reasons, production federation deployments require the use of digitally signed security tokens, and as an option allow encryption of security token contents. This lab uses self-signed private key certificates, which are generated from inside the AD FS 2.0 and PingFederate products, for signing security tokens.

As an alternative, organizations can use a private key certificate that is issued by a certification authority (CA) for signing and encryption. The primary benefit of using certificates that a CA issues is the ability to check for possible certificate revocation against the certificate revocation list (CRL) from the issuing CA.

Both in AD FS 2.0 and in PingFederate, CRL checking is enabled by default for all partner connections, if the certificate being used by the partner includes a CRL Distribution Point (CDP) extension. This has implications in federation deployments between PingFederate and AD FS 2.0:

• If a signing/encryption certificate provided by one side of a federation includes a CDP extension, that location must be accessible by the other side’s federation server. Otherwise, CRL checking fails, resulting in a failed access attempt. Note that CDP extensions are added by default to certificates that are issued by Active Directory Certificate Services (AD CS) in Windows Server 2008 R2.

• If the signing/encryption certificate does not include a CDP extension, no CRL checking is performed by AD FS 2.0 or PingFederate.

• You can turn off CRL checking on a server-wide basis in PingFederate under the Security section of My Server in the PingFederate administration console.

• In AD FS 2.0, you can turn off CRL checking for a specific partner by using the Windows PowerShell™ command-line and scripting environment. For example, to turn off CRL checking of this lab’s PingFederate claims provider signing certificate, click Start, click Administrative Tools, and then click Windows PowerShell Modules on the AD FS 2.0 computer. Then, at the PowerShell command prompt type the following:

  set-ADFSClaimsProviderTrust –TargetName “Ping Example” 
  –SigningCertificateRevocationCheck None
  

Other Signing and Encryption

The SAML 2.0 protocol enables advanced use of PKI for federation security that is outside the scope of this document. Some of the capabilities that are supported in PingFederate or AD FS 2.0 include the following.

Digital Signing

• Authentication requests (authnRequest) from SP to IdP

• Federated single logout (SLO) requests and responses (See more on SLO below.)

• Artifact resolution requests and responses when using the HTTP-Artifact binding (See more on the Artifact binding below.)

• SSO responses (a superset of signed assertions)

Encryption

• Entire SAML assertions (both PingFederate and AD FS 2.0 support) or elements of an assertion such as the Subject or specific attributes (PingFederate only)

• Name ID in an SLO request

AD FS 2.0 Encryption Strength

In AD FS 2.0, encryption of outbound assertions is turned on by default. Assertion encryption occurs for any relying party/service provider for which AS FS 2.0 possesses an encryption certificate.

When it performs encryption, AD FS 2.0 uses 256-bit Advanced Encryption Standard (AES) keys, or AES-256. In contrast, by default PingFederate supports a weaker algorithm (AES-128). Failing to reconcile these conflicting defaults can result in failed SSO attempts.Alternatives for addressing this issue include the following:

• Disabling encryption in AD FS 2.0. To disable encryption, on the AD FS 2.0 computer, click Start, click Administrative Tools, and then click Windows PowerShell Modules. Then, at the Windows PowerShell command prompt, type the following:

  set-ADFSRelyingPartyTrust –TargetName “Ping Example” 
  –EncryptClaims $False
  

• Upgrade PingFederate’s encryption capability. Because of import control restrictions, the standard Java Runtime Environment (JRE) distribution supports strong but not unlimited encryption. For this reason, the strongest cipher suites are commented out of the two configuration files com.pingidentity.crypto.SunJCEManager.xml and com.pingidentity.crypto.LunaJCEManager.xml, which are located in the folder <pf_install>/server/default/data/config-store. To use the strongest encryption, remove the comments from the AES 256 cipher suites, and then download and install the appropriate version of Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from the Java SE Downloads (https://go.microsoft.com/fwlink/?LinkId=206383).

Federated SLO

Both AD FS 2.0 and PingFederate include support for federated single logout. Federated single logout makes it possible for users to log out completely from their IdP federation server, as well as any replying party applications that are federated through a particular browser session. Federated logout seeks to improve security by leaving no sessions open for misuse, hijacking, or other malicious actions.

SAML 2.0 Artifact Profile

Both AD FS 2.0 and PingFederate support the SAML 2.0 HTTP artifact binding as part of their support for the SAML 2.0 protocol. The artifact profile differs in approach from the HTTP POST profile, and it may be preferred in some situations.

Alternative Authentication Methods (PingFederate as IdP)

In this lab, when PingFederate acts as the IdP, the user that needs a security token authenticates to PingFederate through forms authentication by using the bundled LDAP Authentication Service. Beyond the LDAP adapter, PingFederate supports other methods of authentication to the federation server, including following:

• X.509 client certificate authentication.

• Integration with Identity Management (IdM) Systems. PingFederate provides silent authentication through integration with popular IdM systems, including CA SiteMinder, Oracle Access Manager and IBM Tivoli Access Manager.

• Integration with Windows. PingFederate provides silent authentication through integration with a Windows security context (either NTLM or Integrated Windows Authentication (IWA).

SAML 2.0 IdP Discovery

Both PingFederate and AD FS 2.0 support the SAML IdP Discovery Profile (https://go.microsoft.com/fwlink/?LinkID=205506) which provides a standards-based cookie mechanism to determine a user’s IdP during SP-initiated SSO, when no IdP is otherwise explicitly stated. This contrasts with the approach used in this lab, where both AD FS 2.0 and PingFederate are configured to present a web interface from which a user self-selects their IdP from a list.

Use of the IdP Discovery Profile requires the use of a common domain. IdP partners use this domain to write common domain cookies (CDC) using a CDC-writing service, while SP partners read those cookies using a CDC reading service.

AD FS 2.0 provides CDC writer and reader applications a folder called CDC.Web in the AD FS 2.0 application installation folder. To configure SAML IdP discovery in PingFederate, see the “Configuring IdP Discovery” section of “Chapter 3: System Settings” in the PingFederate Administrator’s Manual (https://go.microsoft.com/fwlink/?LinkId=206384).

Override Parameters When Initiating SSO

Most of the parameters that define the behavior of a federation trust (what protocols to use, what endpoints to send messages to, and so forth) are typically included in a partner’s XML metadata document. In this lab, we use XML metadata documents to create trusts and connections within AD FS 2.0 and PingFederate.

However, scenarios exist in which a federation partner may want to modify or extend the default behavior of a federation as defined in metadata. For that purpose, the SAML 2.0 protocol allows for the use of added parameters in the messages that are sent to federation servers to initiate SSO. These parameters typically affect the authnRequest that an SP generates during SP-initiated SSO or the assertion that an IdP generates during IdP-initiated SSO.

In PingFederate, administrators can invoke many features by adding parameters to the preformatted hyperlinks that are used to initiate SSO directly at the PingFederate server.

AD FS 2.0 does not support SAML-based SP-initiated SSO, and therefore it does not support the supplying of parameters in preformatted hyperlinks. However, the Windows PowerShell set-ADFSClaimsProviderTrust cmdlet provides some configuration options that modify the contents of authnRequests that are generated by AD FS 2.0 as an SP:

• RequiredNameIdFormat

• SamlAuthenticationRequestParameters

• SamlAuthenticationRequestIndex

• SamlAuthenticationRequestProtocolBinding

During SAML-based IdP-initiated SSO, AD FS 2.0 supports the use of only the single parameter loginToRp, which identifies the relying party to which the assertion should be sent. However, administrators can modify the AD FS 2.0 passive federation web application (default location C:\intepub\adfs\ls) to use the following SignOnRequestParameters that change default behavior.

• Consent

• IsPassive

• ForcedAuthentication

• RequestedAuthenticationContext

Modify the IdpInitiatedSignOn.aspx and IdpInitiatedSignOn.aspx.cs files to enable these parameters. The Consent parameter is already enabled by default. To display the user consent drop-down list during SSO, uncomment the Consent section in the AD FS 2.0 web application’s web.config file.

Persistent and Transient Name IDs

Both AD FS 2.0 and PingFederate support the use of persistent and transient Name IDs in SAML 2.0 security tokens. Both types of Name ID use an opaque alphanumeric string to represent a user, instead of a readable and understandable value (such as an e-mail address or a Windows SAM-Account-Name).

A persistent Name ID uses the same alphanumeric value in each request from a given user, while a transient Name ID changes in each browser session. Persistent Name IDs are useful in account-linking scenarios, because they can be appended to an application-side user account and then used like any other attribute for user disambiguation. Transient Name IDs are useful in cases in which a user identity is not needed at the application—only confidence that the user successfully authenticated at a trusted relying party—but an ID that tracks back to a specific user is needed for repudiation purposes and similar things.

The following table is a summary of the capabilities in this area.

	AD FS as IdP / Ping as SP	Ping as IdP / AD FS as RP
Persistent Name ID / account linking	WORKS	AD FS does not support the account linking scenario
Transient Name ID / pseudo-anonymous access	WORKS	WORKS

Name ID Name Qualifiers

Both AD FS 2.0 and PingFederate support the use optional name qualifier attributes (nameQualifier, spNameQualifier) of the NameID element in SAML assertions. When federations use persistent or transient Name IDs, the possibility exists for an SP to receive the same opaque IDs for different users, which compromises the system’s ability to disambiguate the user. Name qualifiers improve the probability of uniqueness by limiting the scope of an opaque identifier to one IdP-SP relationship. Typically, organizations define the nameQualifier attribute as the unique identifier (entityID) of the IdP and the spNameQualifer attribute as the entityID of the SP.

In PingFederate, name qualifier support is automated. For example, PingFederate automatically adds nameQualifer and spNameQualifier attributes to the Name ID attribute of any assertions that include an opaque identifier.

In AD FS 2.0, name qualifier support is not automated, but it can be accomplished by using custom-developed claim rules. For example, the two custom claim rules below generate and send a persistent Name ID from this lab’s AD FS 2.0 IdP to the PingFederate SP, with nameQualifier and spNameQualifier attributes included

Rule 1: Create Persistent Name ID

c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
 => add(store = "_OpaqueIdStore", types = ("https://mycompany/internal/persistentId"), query = "{0};{1};{2}", param = "ppid", param = c.Value, param = c.OriginalIssuer);

Rule 2: Send Name ID with NameQualifiers

c:[Type == "https://mycompany/internal/persistentId"]
 => issue(Type = "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["https://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", Properties["https://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "https://fsweb.contoso.com/adfs/services/trust", Properties["https://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "PF-DEMO");