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

Transcription

1 AD FS 2.0 Step-by-Step Guide: Federation with Ping Identity PingFederate Ping Identity Corporation and Microsoft Corporation Published: November 2010 Version: 1.0 Author: Dave Martinez, Principal, Martinez & Associates LLC Editor: Jim Becker Technical reviewers: Ping Identity: Pam Dingle, Paul Madsen, David Skyberg, Peter Motykowski; Microsoft: Mike Jones Abstract Through its support for the WS-Federation and Security Assertion Markup Language (SAML) 2.0 protocols, Microsoft Active Directory Federation Services 2.0 (AD FS 2.0) provides claimsbased, cross-domain, Web single sign-on (SSO) interoperability with non-microsoft federation solutions. Ping Identity PingFederate, through its support for WS-Federation and SAML 2.0, enables cross-domain, federated SSO between environments that are running Microsoft and Ping Identity federation infrastructures. Building on existing documentation, this step-by-step guide walks you through the setup of a basic lab deployment of AD FS 2.0 and PingFederate that performs cross-product, browserbased identity federation. Both products perform both identity federation roles: claims provider/identity provider and relying party/service provider. This document is intended for developers and system architects who are interested in understanding the basic modes of interoperability between AD FS 2.0 and PingFederate.

2 This document is provided as-is. Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. This document does not provide you with any legal rights to any intellectual property in any Microsoft or Ping Identity product. You may copy and use this document for your internal, reference purposes. You may modify this document for your internal, reference purposes Microsoft Corporation. All rights reserved. Microsoft, Active Directory, Internet Explorer, SQL Server, Windows, Windows PowerShell, and Windows Server are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners.

3 Contents AD FS 2.0 Step-by-Step Guide: Federation with Ping Identity PingFederate... 5 About This Guide... 5 Terminology Used in This Guide... 5 About the Author... 5 Prerequisites and Requirements... 6 PingFederate... 6 Windows... 6 PingFederate... 6 AD FS Preconfiguration Tasks... 7 Make Quick-Start Deployment Network-Ready... 7 Ensure IP Connectivity... 8 Configure Name Resolution... 8 Verify Clock Synchronization... 9 Enable SSL Server Authentication... 9 Update the AD FS 2.0 Sample User Account... 9 Configure AD FS 2.0 as the Claims Provider and PingFederate as the Relying Party Configure PingFederate Add a New IdP Connection Using Metadata Export Service Provider Metadata to a File Configure AD FS Add a Relying Party Using Metadata Edit Claim Rules for Relying Party Trust Create Link for Initiating Federated Access Test AD FS 2.0 as the Claims Provider and PingFederate as the Relying Party Configure PingFederate as the Claims Provider and AD FS 2.0 as the Relying Party Configure PingFederate Add a New SP Connection Using Metadata Export Identity Provider Metadata to a File Configure AD FS Add a Claims Provider Using Metadata Edit Claim Rules for Claims Provider Trust Edit Claim Rules for the WIF Sample Application Change AD FS 2.0 Signature Algorithm Create Link for Initiating Federated Access (optional) Test PingFederate as the Claims Provider and AD FS 2.0 as the Relying Party

4 Appendix Additional Protocol Support Certification Authority-Issued Signing/Encryption Certificates Other Signing and Encryption Digital Signing Encryption AD FS 2.0 Encryption Strength Federated SLO SAML 2.0 Artifact Profile Alternative Authentication Methods (PingFederate as IdP) SAML 2.0 IdP Discovery Override Parameters When Initiating SSO Persistent and Transient Name IDs Name ID Name Qualifiers

5 AD FS 2.0 Step-by-Step Guide: Federation with Ping Identity PingFederate 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 ( 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. 5

6 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 ( 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 lab uses version 1.0 of the stand-alone Quick-Start applications distribution, which was released in August 2010, the same time as version 6.3 of PingFederate. Prior versions of PingFederate include a bundled version of the Quick-Start applications that was not tested, and they may not be compatible with the instructions in this guide. 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: Quick-Start application URLs: For simplicity, PingFederate s integrated application server is used to host the Quick- Start applications. Therefore, the application URLs include the same port (9031) as the server. IdP Application URL: SP Application URL: 6

7 For more information about installation and deployment, see the PingFederate documentation library ( AD FS 2.0 The test deployment that was created in the AD FS 2.0 Federation with a WIF Application Stepby-Step Guide ( 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. All of the actions in this section were performed while logged in to Windows with administrative privileges. 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 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 in the Quick-Start configuration to an external web address. For this lab, we will use the address 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. This single PingFederate instance can perform both the IdP and SP roles when it interacts with AD FS 2.0. A second PingFederate server is not required. Therefore, you can disregard steps 1 and 2 under Initial Setup, which anticipate the creation of a second PingFederate server. 7

8 As a result of the changes that you make in this section, your deployment should now use the following URLs: PingFederate Base URL: Quick-Start application URLs: IdP Application URL: SP Application URL: 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 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 pad to open the file. 3) Add an entry for fsweb.contoso.com, for example: 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: 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 pad. 7) Add an entry for ping.example.com, for example: ping.example.com 8) Save and close the file. 8

9 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. For information about how to synchronize a Windows Server 2008 R2 domain controller to an Internet time server, see article in the Microsoft Knowledge Base ( 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 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. 9

10 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 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 2) At the security warning, click the link to continue to the website. 10

11 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 SPinitiated 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 address member status Source Assertion Assertion Value name Assertion 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. 11

12 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. 12

13 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 Display-Name Outgoing Claim Type Name 13

14 -Addresses 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 pad. 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=" for SP-initiated SSO via direct application access & IdP selection</a> 14

15 <p> <a href=" = s://ping.example.com:9031/quickstart-app-sp/go">link for SPinitiated SSO via PingFederate server access</a> <p> <a href=" Rp=PF-DEMO "> Link for IdP-initiated SSO via AD FS 2.0 server access</a> 3) In pad, 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. For the best results, clear all the cookies in Internet Explorer on the AD FS 2.0 computer (fsweb.contoso.com). To clear the cookies, click Tools, click Internet Options, click Delete under Browsing History, and then select cookies for deletion. 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 3) Click the links to test SSO to PingFederate from AD FS 2.0. When you use the first link (direct application access), select the IdP Partner that is listed as Contoso-ADFS2 on the IdP selection page. AD FS 2.0 does not support the declaration of a Target or RelayState parameter 15

16 when it acts as the IdP during IdP-initiated SSO. Therefore, successful use of the third link (IdP-initiated SSO) which does not state the target application explicitly requires the SP to use the Default URL feature in PingFederate (which is already configured in this lab). The setting is available on the Main Menu under My SP Configuration\Application Integration Settings\Default URLs. 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 SPinitiated SSO, and then click Next. 10) On the Assertion Lifetime page, leave the default validity times, and then click Next. 16

17 11) On the Assertion Creation page, click Configure Assertion Creation. 12) On the Identity Mapping page, leave Standard selected and click Next. 13) On the Attribute Contract page, in the Extend the Contract box type 14) Click Add, and then click Next. 15) On the IdP Adapter Mapping page, click on Map New Adapter Instance. 16) On the Adapter Instance page, in the Adapter Instance dropdown list select IdP Adapter and click Next. 17) On the Assertion Mapping page, leave Use only the attributes available in the SSO assertion selected and click Next. 18) On the Attribute Contract Fulfillment page, fill in the following values and click Next. Attribute Contract Source Value SAML_SUBJECT Adapter 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. 17

18 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 18

19 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 Claim rule name Incoming claim type Value Name ID Rule Name ID Incoming name ID format Unspecified 5. Select the Pass through only claim values that match a specific suffix value option. In 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 Claim rule name Value Name Rule 19

20 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 Claim rule name Value 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 Claim rule name Incoming claim type Value Pass Name ID Rule Name ID Incoming Name ID format Unspecified 9) Leave the Pass through all claim values option selected, and then click Finish 20

21 10) Click OK. If you configured the optional Step 6: Change Authorization Rules when you were testing the original AD FS 2.0 with WIF Step-by-Step Guide deployment, ensure that you add back the Permit All Users issuance authorization rules for the WIF sample application before testing this scenario. Or, as an alternative, add a new Permit or Deny Users Based on an Incoming Claim rule allowing incoming Name ID = john@example.com to access the application. 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. Although not configured in this lab, this same procedure is recommended for AD FS 2.0 relying party trusts that use PingFederate. If the PingFederate SP signs authnrequests, artifact resolution requests, or logout requests, AD FS 2.0 errors will occur unless this signature algorithm setting is changed. 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. When acting as the SP, AD FS 2.0 does not support SAML 2.0-based SP-initiated SSO using a hyperlink, nor does it support SAML 2.0-based IDP-initiated SSO to a WIF relying party application. The link offered here uses WS-Federation parameters and syntax, with AD FS 2.0 performing an in-process protocol transition (from WS-Federation to SAML 2.0) during the transaction. 21

22 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 pad 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=" tps://fsweb.contoso.com/claimsawarewebappwithmanagedsts/default.a spx&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. Clear all the cookies in Internet Explorer on the AD FS 2.0 computer (fsweb.contoso.com). To clear the cookies, click Tools, click Internet Options, click Delete under Browsing History, and then select cookies for deletion. To access the WIF sample application 1) On the AD FS 2.0 computer, open a browser window, and then navigate to 2) The first page prompts you to select your organization from a list. Select Ping Example, and then click Continue to Sign In. This page did not appear in the previous example when you were redirected to AD FS 2.0. This is because at that point there was only one identity provider registered in AD FS 2.0. When only one IdP is available, AD FS 2.0 defaults to forwarding requests to that IdP. 3) The PingFederate Quick-Start forms logon page appears. Select the user name john, type the password test, and then click Login. 22

23 At this point, you should see the WIF sample application. 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. 23

24 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 applicationbased federation and SSO (sometimes called active client SSO). Active clients can support moreadvanced 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 selfsigned 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. 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 24

25 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 You can make many configuration changes to AD FS 2.0 using the Windows PowerShell command-line and scripting environment. For more information, see the AD FS 2.0 Windows PowerShell Administration section of the AD FS 2.0 Operations Guide ( and the AD FS 2.0 Cmdlets Reference ( 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: 25

26 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 ( 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 ( which provides a standards-based cookie 26

27 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 ( When they use the web-based IdP-selection interface in AD FS 2.0 and PingFederate, both products have the ability to write proprietary cookies to user web browsers to provide a silent IdP-selection in future access requests. 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 SPinitiated 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. For more information about building preformatted hyperlinks that are directed at PingFederate, see Appendix C: Application Endpoints in the PingFederate Administrator s Manual ( 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 27

28 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 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. Persistent Name ID / account linking Transient Name ID / pseudoanonymous access AD FS as IdP / Ping as SP WORKS WORKS Ping as IdP / AD FS as RP AD FS does not support the account linking scenario WORKS 28