ADFS 2.0 Step-by-Step Guide: Federation with IBM Tivoli Federated Identity Manager

  • Article

Updated: March 24, 2011

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 IBM Tivoli Federated Identity Manager (TFIM) by using the Security Assertion Markup Language (SAML) 2.0 (https://go.microsoft.com/fwlink/?LinkId=193996) protocol, specifically its Web Browser SSO Profile and 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 AD FS 2.0 and SAML documentation. The following table assists in drawing parallels between the two concepts.

AD FS 2.0 name SAML name Concept

Security Token

Assertion

A package of security information, describing a user, created and consumed during a federated access request

Claims Provider

Identity Provider (IdP)

Partner in a federation that creates security tokens for users

Relying Party

Service Provider (SP)

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:

  • Configure AD FS 2.0 as the Claims Provider and TFIM as the Relying Party

  • TFIM 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 AD FS 2.0, and the other to host TFIM. This document presumes the pre-existence of deployments of AD FS 2.0 and TFIM, as described below.

AD FS 2.0

The test deployment 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.

TFIM

The TFIM environment in this lab is hosted by a fictitious company called Example.com, and was configured as described below. Installation and deployment guides for TFIM are available at the IBM Tivoli Federated Identity Manager Information Center (https://go.microsoft.com/fwlink/?LinkId=213791) Web site.

Windows Environment

  • Host operating system: Windows Server 2003 SP2

  • Host name: tfim.example.com

TFIM Environment

  • Product version: IBM Tivoli Federated Identity Manager version 6.2.0.2

  • Other IBM software features installed to support TFIM:

    • IBM Tivoli Directory Server version 6.0 Fixpack 7 (6.0.0.52) as the user repository

    • IBM Tivoli Access Manager for e-business version 6.0.0.22

Note

Tivoli Access Manager (TAM) is a web access management product that provides policy-based web access control. TFIM versions 6.2.0 and above can be used without TAM. However, it is included here because of its ability to provide rich user attribute data for use in TFIM security tokens. 

  - IBM Tivoli Access Manager WebSEAL version 6.0.0.22, as TFIM point of contact server and proxy for IVT sample application  
      
      - HTTPS enabled on port 443 (instructions provided below)  
          
  - IBM WebSphere Application Server (WAS) Network Deployment 6.0.2.33, to host:  
      
      - TFIM runtime and management service  
          
      - TAM Web Portal Manager version 6.0.0.22  
          
      - TFIM IVT sample application  
          
  - IBM WebSphere Application Server Embedded version 6.1.0.15, to host:  
      
      - TFIM management console  
          
  - IBM Global Security Kit (GSKit) version 7.0.4.20

This document presumes that WAS Network Deployment (ND) 6.0 is installed before WAS Embedded 6.1, and that all applications except the TFIM management console run on WAS ND 6.0. As a result, the relevant port values used in this document are:

  • WAS ND 6.0 Application Server: Port 9080

  • WAS ND 6.0 Administration: Port 9060

  • WAS Embedded 6.1 (TFIM) Administration: Port 9061

Preconfiguration Tasks

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

Note

All of the actions in this section were performed while logged into Windows with administrative privileges.

Ensure IP Connectivity

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

Configure Name Resolution

In this lab, we will use the hosts file on the AD FS 2.0 computer (fsweb.contoso.com) to configure name resolution of the partner federation servers and sample applications.

Note

Production deployments should use Domain Name System (DNS) instead.

To configure name resolution

  1. Locate the hosts file on the AD FS 2.0 computer (fsweb.contoso.com), and open with Notepad. The default location is C:\windows\system32\drivers\etc\hosts.

  2. Add an entry for tfim.example.com, for example:192.168.1.3tfim.example.com

  3. Save and close the file.

Verify Clock Synchronization

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

Note

For information on how to synchronize a Windows Server domain controller to an Internet time server, Microsoft Knowledge Base article 816042 (https://go.microsoft.com/fwlink/?LinkId=60402).

Enable SSL Server Authentication

Federation relies heavily on public key infrastructure (PKI), including Secure Sockets Layer (SSL) encryption, for trustworthy transactions. To properly use SSL security in this lab, first create a new self-signed certificate for the WebSEAL server at tfim.example.com. Then add the self-signed certificate being used by WebSEAL 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.

Create a New Self-signed SSL Certificate for WebSEAL

To generate a new self-signed SSL certificate for WebSEAL

  1. On the TFIM computer (tfim.example.com), launch the IBM Key Management (ikeyman) utility, installed by default at C:\Program Files\IBM\gsk7\bin\gsk7ikm.exe.

  2. In the Key Database File menu, select Open.

  3. In the Open dialog box, in the Key database type drop-down list select CMS.

  4. Click Browse and navigate to the location of the key database file holding the WebSEAL deployment certificates, default location C:\Program Files\Tivoli\PDWeb\www-default\certs\pdsrv.kdb.

  5. Select pdsrv.kdb and click Open, and then click OK.

  6. In the Password Prompt dialog box, type the key store password (default pdsrv) and click OK.

  7. In the Key Database Content section, click the New Self-Signed button.

  8. In the Create New Self-Signed Certificate dialog box, type the following values and click OK:

    Name Value

    Key Label

    adfsinterop

    Common Name

    tfim.example.com

  9. In the Confirm dialog box, click Yes to make the new key the default key in the database.

Apply New SSL Certificate in WebSEAL

To apply a new self-signed SSL certificate in WebSEAL

  1. On the TFIM computer (tfim.example.com), navigate to the configuration file for the WebSEAL instance hosting the TFIM runtime and IVT sample application, default location C:\Program Files\Tivoli\PDWeb\etc\webseald-default.conf.

  2. Right-click the configuration file and select Open with Notepad.

  3. Scroll down to the SSL section and change the value of webseal-cert-keyfile-label to adfsinterop.

  4. Click Save.

  5. Click Start > Settings > Control Panel > Administrative Tools > Services.

  6. Right-click the WebSEAL server instance (default Access Manager WebSEAL-default) and select Restart.

Install WebSEAL SSL Certificate on AD FS 2.0 Computer

Install the new WebSEAL SSL certificate into the Trusted Roots store on fsweb.contoso.com. This allows the Contoso user’s Internet Explorer to trust the TFIM web server during the federation process, and avoids security warning messages in the browser.

To install WebSEAL SSL certificate into fsweb.contoso.com

  1. From the AD FS 2.0 computer (fsweb.contoso.com), use Internet Explorer to visit https://tfim.example.com.

  2. At the security warning, click the link to continue to the web site. 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, 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 the radio button to 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 click OK.

  9. Click Next > Finish > OK > OK.

  10. Close and reopen Internet Explorer, and revisit https://tfim.example.com. This time the address bar should remain white, signifying a working SSL channel.

Create/Modify Sample Users and Groups

Follow the instructions below to add users with detailed identity attributes to each product’s respective user directory, in order to demonstrate transmission of rich claims between partners.

Update AD FS 2.0 Sample User Account

First, add data to the Contoso Administrator user account that will appear in security tokens generated by AD FS 2.0 for TFIM.

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-most pane, right-click Administrator and select 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

Create TFIM Sample Users

TFIM provides a command-line tool named tfimcfg.jar that configures TFIM integration with WebSEAL. The same tool also populates a local user directory with sample users for federation testing. Here, you will add sample users to the WebSEAL IBM Tivoli Directory Server instance.

To create TFIM sample users in IBM Tivoli Directory Server using tfimcfg.jar

  1. To open a command prompt on the TFIM computer (tfim.example.com), click Start, click Run, type cmd, and then click OK.

  2. Change the DOS prompt directory to C:\Program Files\IBM\FIM\tools\tamcfg.

  3. At the command prompt, type Notepad ldapconfig.properties.

  4. In ldapconfig.properties, ensure that the following values are correct: ldap.hostname, ldap.port, ldap.admin.dn, ldap.admin.password. Also make sure that ldap.ivt.sp.configuration and ldap.ivt.ip.configuration are both set to “true”.

  5. Save and close ldapconfig.properties.

  6. At the command prompt, type the following command, and then press ENTER:java -jar tfimcfg.jar -action ldapconfig -rspfile ldapconfig.properties

Create Local User in TAM for AD FS 2.0 User

When TFIM acts as a service provider and uses TAM for access control, it typically maps incoming security tokens to a local account in its user directory before creating a session. Here we will create an account for Contoso’s Joe Admin in the Example.com IBM Tivoli Directory Server instance through the TAM web interface.

To add Joe Admin into IBM Tivoli Directory Server and TAM

  1. On the TFIM computer (tfim.example.com), login to the Tivoli Access Manager Web Portal Manager application at https://localhost:9080/pdadmin.

  2. In the left navigation bar, expand User, and then click Create User.

  3. In the Create User window, type the following values and click Create.

    Name Value

    User Id

    admin@contoso.com

    Common Name

    Joe

    Surname

    Admin

    Password

    <insert password>

    Registry UID

    uid=admin,o=serviceprovider,dc=com

  4. Click Create, and then click Done.

Deploy TFIM Sample Application

TFIM provides a sample application, which is known as the Install Verification Test, or IVT application. Follow the instructions provided in the Single Sign-On Demonstration Application section the IBM Tivoli Federated Identity Manager Version 6.1.1. Single Sign-on Guide (https://go.microsoft.com/fwlink/?LinkId=213792) to deploy the sample application into the WebSphere Application Server ND instance on the TFIM server.

To view the sample application, use Internet Explorer on the TFIM computer (tfim.example.com) to visit https://localhost:9080/fimivt/federations.jsp.

Note

External HTTPS access to the IVT application will be provided through WebSEAL, which will be configured later.

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

In this step, you configure the scenario in which Contoso’s Joe Admin uses federation (through AD FS 2.0) to access the Example.com sample application protected by TFIM. This web browser scenario uses the SAML 2.0 HTTP POST binding.

Configure TFIM

Create an Identity Mapping Rule File

All TFIM federations include an identity mapping rule that instructs TFIM how to translate identity data being passed to or from partner environments. The identity mapping rule can be written in XML Extensible Stylesheet Language (XSL) or in Java, or built using IBM Tivoli Directory Integrator. Here we will write the identity mapping rule in XSL (using a sample rule shipped with TFIM as a starting point), and save the new rule to a file for later use.

For more information on identity mapping rules, see the Planning the mapping of user identities section of the IBM Tivoli Federated Identity Manager Configuration Guide (https://go.microsoft.com/fwlink/?LinkId=213793).

The identity mapping rule file created below instructs TFIM to:

  • Map incoming AD FS 2.0 Name ID claims to the local user with the same value in the TAM UserId field;

  • Map incoming AD FS 2.0 E-Mail and Name claims to equivalent WebSEAL tag/value attributes.

To create the Example.com service provider identity mapping rule

  1. Browse to the \examples\demo\demo_rules folder in the location where TFIM was installed, for example C:\Program Files\IBM\FIM\examples\demo\demo_rules.

  2. In the demo_rules folder, right-click sp_saml_20.xsl and then click Open With NotePad.

  3. In Notepad, on the Edit menu, click Find. In the Find what field, type tagvalue_name attribute, and then click Find Next.

  4. Scroll down to find the following segment of XML, then replace ‘commonName’ with the formal URI-based name for the SAML ‘Name” claim (in bold below):

    Section before editing

    <stsuuser:Value><xsl:value-of select="//stsuuser:AttributeList/stsuuser:Attribute[@name='commonName'][@type='https://example.com/federation/v1/commonName']/stsuuser:Value" /></stsuuser:Value>

    Section after editing

    <stsuuser:Value><xsl:value-of select="//stsuuser:AttributeList/stsuuser:Attribute[@name='https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name']/stsuuser:Value" /></stsuuser:Value>

  5. In Notepad, on the Edit menu, click Find. In the Find what field, type tagvalue_email attribute, and then click Find Next.

  6. Scroll down to find the following segment of XML, then replace ‘email’ with the formal URI-based name for the SAML ‘E-Mail Address’ claim (in bold below):

    Section before editing

    <stsuuser:Value><xsl:value-of select="//stsuuser:AttributeList/stsuuser:Attribute[@name='email'][@type='https://example.com/federation/v1/email']/stsuuser:Value" /></stsuuser:Value>

    Section after editing

    <stsuuser:Value><xsl:value-of select="//stsuuser:AttributeList/stsuuser:Attribute[@name='https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress']/stsuuser:Value" /></stsuuser:Value>

  7. In Notepad, on the File menu, click Save As.

  8. In the Save As dialog box, in the File name field, type sp_saml_20_adfs.xsl. In the Save as type drop-down list select All Files, and then click Save.

Add a Service Provider Federation

In this procedure, you will add a federation through the TFIM console application that will enable Example.com to act as a Service Provider/Relying Party.

To add a TFIM service provider federation

  1. Open the WebSphere Application Server 6.1 console application at https://tfim.example.com:9061/admin.

  2. In the left navigation area, click Tivoli Federated Identity Manager, and then click Configure Federated Single Sign-on, and then click Federations.

  3. In the Federations window, click Create to start the Federation Wizard.

  4. In the General Information window, in the Federation Name field, type TFIMasSP.

  5. Under Identify your role, click Service Provider, and then click Next.

  6. In the Contact Information window, in the Company Name field, type Example.com, and then click Next.

  7. In the Federation Protocol window, click SAML 2.0, and then click Next.

  8. In the Point of Contact Server window, in the Point of Contact field, type https://tfim.example.com/FIM1, and then click Next.

Note

This value is case sensitive.

  1. In the Profile Selection window, select Manual: Select individual profiles and bindings and click Next.

  2. In the Profile Details window, clear the box next to HTTP Artifact, check the box next to HTTP Post, and click Next.

  3. In the Signature Options window, in the Select Signing Key section, ensure the DefaultKeyStore is selected, then in the Keystore Password text box type testonly and click List Keys.

  4. Click the radio button next to the key with the alias testkey and click Next.

  5. In the Encryption Options window, ensure the DefaultKeyStore is selected, then in the Keystore Password text box type testonly and click List Keys.

  6. Click the radio button next to the key with the alias testkey and click Next.

  7. In the SAML Message Settings window, leave the defaults and click Next.

  8. In the Identity Mapping Options window, ensure that Use XSL transformation for identity mapping is selected, and then click Next.

  9. In the Identity Mapping window, click Browse.

  10. In the Choose File dialog box, navigate to the location where you saved the identity mapping rule file named sp_saml_20_adfs.xsl, for example C:\Program Files\IBM\FIM\examples\demo\demo_rules\sp_saml_20_adfs.xsl.

  11. Select sp_saml_20_adfs.xsl, and then click Open.

  12. In the Identity Mapping window, click Next.

  13. In the Summary window, review your entries, and then click Finish.

  14. In the Create Federation Complete window, click Done.

Note

You can dismiss the notification in the Current Domain window that appears after you add this federation. You can load the new configuration objects to the TFIM runtime later, after other changes.

Prepare AD FS 2.0 Metadata File

Adding partners into TFIM begins with importing partner metadata. The AD FS 2.0 metadata file includes information pertaining to how AD FS 2.0 performs both the identity provider and service provider roles, including certificates to validate and encrypt security token data.

Note

The AD FS 2.0 metadata XML file uses extension points in the SAML 2.0 metadata standard (https://go.microsoft.com/fwlink/?LinkId=194835) that are not supported by TFIM 6.2.0. In this lab, we will edit the AD FS 2.0 metadata file to remove the unsupported elements. TFIM versions 6.2.1.0 and above can read the AD FS 2.0 metadata document without modification.

To prepare the AD FS 2.0 metadata document

  1. On the AD FS 2.0 computer (fsweb.contoso.com), use Internet Explorer to view https://fsweb.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml.

  2. Click Page, and then click Save As. Save the file with the name ADFSFederationMetadata.xml to a location that can be accessed by the TFIM computer. Make sure to change the Save as type drop-down box to All Files (*.*).

  3. On the TFIM computer (tfim.example.com), right-click ADFSFederationMetadata.xml and select Open with Notepad.

  4. In Notepad, on the Edit menu, click Find. In the Find what field, type signature, and then click Find Next.

  5. Delete the metadata document signature section of the file (bold text below). Since we are editing the document, this signature is invalid.

    Section before editing

    <EntityDescriptor ID="abc123" entityID="https://FSWEB.contoso.com/adfs/services/trust" xmlns="urn:oasis:names:tc:SAML:2.0:metadata"><ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#"> SIGNATURE DATA</ds:Signature><RoleDescriptor xsi:type=…>

    Section after editing

    <EntityDescriptor ID="abc123" entityID="https://FSWEB.contoso.com/adfs/services/trust" xmlns="urn:oasis:names:tc:SAML:2.0:metadata"><RoleDescriptor xsi:type=…>

  6. In Notepad, on the Edit menu, click Find. In the Find what field, type attribute, and then click Find Next.

  7. Delete all of the attribute elements in the <IDPSSODescriptor> section of the file (bold text below).

    Section before editing

    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://fsweb.contoso.com/adfs/ls/" /> <Attribute Name="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="E-Mail Address" xmlns="urn:oasis:names:tc:SAML:2.0:assertion" /> - MORE ATTRIBUTES -<Attribute Name="https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Windows account name" xmlns="urn:oasis:names:tc:SAML:2.0:assertion" /> </IDPSSODescriptor>

    Section after editing

    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://fsweb.contoso.com/adfs/ls/" /> </IDPSSODescriptor>

  8. In Notepad, click Page, and then click Save As. Save the file with the name edited_ADFSFederationMetadata.xml to a location that can be accessed by the TFIM computer. Make sure to change the Save as type dropdown box to All Files (*.*).

  9. Close edited_ADFSFederationMetadata.xml.

Create an IdP Partner using Metadata

Each TFIM federation can include one or more partners. Follow these instructions to add Contoso as an identity provider partner to the TFIMasSP federation.

To add a new IdP partner in TFIM

  1. Open the WebSphere Application Server 6.1 console application at https://tfim.example.com:9061/admin.

  2. In the left navigation area, click Tivoli Federated Identity Manager, and then click Configure Federated Single Sign-on, and then click Partners.

  3. In the Partners window, click Create to start the Federation Partner Wizard.

  4. In the Select Federation window, click TFIMasSP, and then click Next.

  5. In the Import Metadata window, click Browse, and then navigate to the location where you saved edited_ADFSFederationMetadata.xml.

  6. In the Choose File dialog box, click edited_ADFSFederationMetadata.xml, and then click Open.

  7. In the Import Metadata window, click Next.

  8. In the Signature Validation window, click the radio button next to DefaultKeyStore, then in the Keystore Password text box type testonly and click Next.

  9. In the Encryption Options window, click the radio button next to DefaultKeyStore, then in the Keystore Password text box type testonly and click Next.

  10. In the SSL Server Authentication for Artifact Resolution window, ensure the DefaultKeyStore is selected, then in the Keystore Password text box type testonly and click List Keys.

  11. Click the radio button next to the key with the alias testkey and click Next.

Note

This key is not the AD FS 2.0 SSL certificate. However, since we have not enabled the HTTP Artifact binding for this federation, the key selected here will have no impact on our testing.

  1. In the SSL Client Authentication for Artifact Resolution window, clear the box next to Partner Requires Client Certificate Authentication and click Next.

  2. In the Partner Settings window, in the Default Post-Authentication Target URL text box type https://tfim.example.com/FIM1/fimivt/federations.jsp, and then click Next.

  3. In the SAML Assertion Settings window, in the Username to be used for anonymous users text box type anonymous and click Next.

Note

This user is not in the TAM LDAP directory. However, for our testing, the user selected here is not relevant.

  1. In the Identity Mapping Options window, ensure Use XSL Transformation for Identity Mapping is selected, and then click Next.

  2. In the Identity Mapping window, leave the XSLT File Containing Identity Mapping Rule field empty, and then click Next.

  3. In the Summary window, review your entries, and then click Finish.

  4. In the Add Partner Complete window, click Enable Partner.

  5. To enable all recent configuration changes, in the Current Domain window, click Load Configuration Objects to Tivoli Federation Manager runtime.

Configure WebSEAL for Federation and Sample Application

Here we will use the command-line tool tfimcfg.jar to configure WebSEAL to integrate with TFIM. In addition, we will also configure WebSEAL to provide access control for the IVT demo application, which you installed earlier.

To configure WebSEAL federation and demo app using tfimcfg.jar

  1. To open a command prompt on the TFIM computer (tfim.example.com), click Start, click Run, type cmd, and then click OK.

  2. Change the DOS prompt directory to C:\Program Files\IBM\FIM\tools\tamcfg.

  3. Identify the location where WebSEAL is installed, and then find the WebSEAL configuration file named webseald-<instance_name>.conf. The default location and file name are C:\Program Files\Tivoli\PDWeb\etc\webseald-default.conf.

  4. At the command prompt, type the following command to begin the WebSEAL configuration tool:
    java -jar tfimcfg.jar -cfgfile <full_path_to_webseal_config_file>
    For example, here we typed:
    java –jar tfimcfg.jar –cfgfile “C:\Program Files\Tivoli\PDWeb\etc\webseald-default.conf”

  5. At the TAM administrator user-id prompt, type the administrator ID that was created during TAM installation (default sec_master), and then press ENTER.

  6. At the TAM administrator password prompt, type the administrator password that was created during TAM installation, press ENTER, type 1, and then press ENTER to proceed to the next step.

  7. At the WebSEAL hostname prompt, type tfim.example.com, press ENTER, type 1, and then press ENTER to proceed to the next step.

  8. At the ITFIM hostname prompt, type tfim.example.com, and then press ENTER.

  9. At the ITFIM HTTP port prompt, type 9080, and then press ENTER.

  10. At the Optional TFIM administrator user-id prompt, leave empty and press ENTER.

  11. At the Optional TFIM administrator password prompt, leave empty and press ENTER.

  12. At the Use SSL connection to ITFIM server prompt, type n, press ENTER, type 1, and then press ENTER to proceed to the next step.

  13. At Federation to configure prompt, type the number corresponding to TFIMasSP, and then press ENTER.

  14. After the federation endpoints are displayed, type 1, and then press ENTER to proceed to the next step.

  15. After the ACLs being placed on the federation endpoints are displayed, type 1, and then press ENTER to proceed to the next step.

  16. At the Perform configuration for demo application prompt, type y, and then press ENTER.

  17. To display a list of configuration actions that will be taken, type 1, and then press ENTER.

  18. To perform configuration, type 1, and then press ENTER.

  19. To verify successful configuration, type the following URL into a browser:
    https://tfim.example.com/FIM1/fimivt/protected/ivtlanding.jsp

  20. To verify proper TAM configuration, login to the application using the user name me-chris and the password abcd1234.

Note

The TFIM Configuration Tool performs many actions when configuring the IVT application that would typically be performed manually. A list of these actions is provided in the Appendix.

Change TFIM Default Name ID Format

When acting as the service provider, TFIM defaults to requesting the Persistent name identifier format (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) in outbound SAML authentication requests. This format requires special configuration in AD FS 2.0. For the sake of simplicity, we will change the default name identifier format TFIM requests from AD FS 2.0 to the emailAddress name identifier format.

To change the TFIM default requested Name ID format

  1. On the TFIM computer (tfim.example.com), navigate to the TFIM federation configuration file (feds.xml), default location C:\<WAS profile root>\config\itfim\<tfim domain>\etc\feds.xml. For example, in this lab the file was at C:\Program Files\IBM\WebSphere\AppServer\profiles\default\config\itfim\tfim-server1\etc\feds.xml.

  2. Right-click feds.xml, and then select Open with Notepad.

  3. In Notepad, on the Edit menu, click Find. In the Find what field, type TFIMasSP, and then click Find Next.

  4. Scroll down to find the following segment of XML, then add the emailAddress name identifier format value (in bold below):

    Section before editing

    <fc:EntityProperty name="SAML2.DefaultNameIDFormat"> <fim:Value></fim:Value> </fc:EntityProperty>

    Section after editing

    <fc:EntityProperty name="SAML2.DefaultNameIDFormat"><fim:Value>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</fim:Value> </fc:EntityProperty>

  5. Save and close feds.xml.

  6. In the TFIM administrative console, in the left navigation area, click Tivoli Federated Identity Manager, and then click Domain Management, and then click Runtime Node Management.

  7. In the Runtime Management section, click the Reload Configuration button.

Export TFIM Service Provider Metadata to a File

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

To export TFIM SP metadata to a file

  1. In the TFIM administrative console, in the left navigation area click Configure Federated Single Sign-on, and then click Federations.

  2. In the Federations window, select the TFIMasSP federation, and then click the Export button.

  3. Click Save, and save the file with the name TFIMasSP_Example.com_metadata.xml to a location that can be accessed by the AD FS 2.0 computer.

Configure AD FS 2.0

Add a Relying Party Using Metadata

Adding a partner into AD FS 2.0 can be done either manually or through metadata import. In this lab, we will use metadata import.

To add an AD FS 2.0 relying party using metadata

  1. On the AD FS 2.0 computer (fsweb.contoso.com), click Start > Administrative Tools > AD FS 2.0 Management to open the AD FS 2.0 Management console.

  2. In the left navigation area, expand the Trust Relationships folder, then right-click the Relying Party Trusts folder and select Add Relying Party Trust to start the Add Relying Party Trust Wizard.

  3. Click Start.

  4. In the Select Data Source page, select Import data about the relying party from a file.

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

  6. Navigate to the location where you saved TFIMasSP_Example.com_metadata.xml earlier and click Open, and then click Next.

  7. In the Specify Display Name page, type TFIM SP Example and click Next.

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

  9. 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 rules in this section describes how data from Active Directory is inserted into the security token created for TFIM.

The primary claim needed by TFIM is the name identifier, or Name ID, which is the assertion attribute used to map incoming federated users to TFIM’s local user store.

To edit AD FS 2.0 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 Management center pane, under Relying Party Trusts, right-click TFIM SP Example, and then click Edit Claim Rules.

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

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

  4. In 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

    E-Mail-Addresses

    E-Mail Address

    Display-Name

    Name

  7. Click Finish.

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

  9. In the Select Rule Template page, select Transform an Incoming Claim, and click Next.

  10. In the Configure Claim Rule page, type the following values.

    Name Value

    Claim rule name

    Name ID Transform

    Incoming claim type

    E-Mail Address

    Outgoing claim type

    Name ID

    Outgoing Name ID format

    Email

  11. Leave the Pass through all claim values radio button selected and click Finish.

  12. Click OK to close the Edit Claim Rules window.

Note

Although Name ID was available as a possible outgoing claim type in step 6, choosing Name ID directly there would have resulted in AD FS 2.0 sending the Name ID with no Name ID format applied. This would not work, since TFIM expects a specified Name ID format, in this case E-Mail Address.

Disable AD FS 2.0 Encryption

AD FS 2.0 automatically configures itself to encrypt token data whenever it receives an encryption certificate from a partner, as it did here, since TFIM’s federation metadata document included an encryption key.

When performing encryption, AD FS 2.0 defaults to using 256-bit Advanced Encryption Standard (AES) keys, or AES-256. In contrast, a default WebSphere/TFIM deployment supports a lower strength encryption algorithm (AES-128). For the sake of simplicity, to eliminate decryption issues we will turn off encryption in AD FS 2.0 tokens destined for Example.com.

Warning

An alternative way to address this issue is to upgrade TFIM’s encryption capability. Visit the Unrestricted JCE Policy Files (https://go.microsoft.com/fwlink/?LinkId=213795) page of the IBM web site to download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction policy files.

To disable encryption

  1. On the AD FS 2.0 computer, click Start > Administrative Tools > Windows PowerShell Modules.

  2. At the PowerShell command prompt, type:
    set-ADFSRelyingPartyTrust -TargetName “TFIM SP Example” -EncryptClaims $False

  3. Hit Enter.

Note

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 (https://go.microsoft.com/fwlink/?LinkId=194005) and the AD FS 2.0 Cmdlets Reference (https://go.microsoft.com/fwlink/?LinkId=177389).

Change AD FS 2.0 Signature Algorithm

When acting as an identity provider, AD FS 2.0 defaults to using the Secure Hash Algorithm 256 (SHA-256) to digitally sign assertions sent to relying parties. In addition, in cases where relying parties sign authentication requests, AD FS 2.0 defaults to expecting those requests to be signed using SHA-256.

In contrast, TFIM uses the SHA-1 algorithm to sign authentication requests and validate assertions. Follow the steps below to change the algorithm AD FS 2.0 uses with TFIM to the SHA-1 algorithm.

Note

TFIM versions 6.2.1.2 and above supports the SHA-256 signing algorithm. Contact IBM Support for more information.

To change the AD FS 2.0 signature algorithm

  1. In the AD FS 2.0 Management console, in the center pane under Relying Party Trusts, right-click TFIM SP Example, and then click Properties.

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

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

In this scenario, Joe Admin from Contoso accesses the federated sample application at Example.com.

Note

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, under Browsing History click Delete, and then check cookies for deletion and click Delete.

To access the Example.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://tfim.example.com/FIM1/fimivt/federations.jsp.

  3. Scroll to the rows representing the TFIMasSP federation, and find the row for partner https://fsweb.contoso.com/adfs/services/trust.

  4. In the Endpoint information section, click the signon hyperlink under SAML2.SingleSignOnService[0] with the binding listed as urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST. This will begin the SP-initiated federated single sign-on process.

At this point, you should see the TFIM sample application. Note the presence of the email and name claims in the Request Headers section of the page. These were additional assertion attributes sent by AD FS 2.0.

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

Configure TFIM

In this step, you configure a scenario in which an Example.com’s Chris Calley uses federation (through TFIM) to access the WIF sample application protected by AD FS 2.0. As before, this web browser scenario uses the SAML 2.0 HTTP POST binding.

Add an Identity Provider Federation

In this procedure, you will add a federation through the TFIM console application that will enable Example.com to act as an Identity Provider/Claims Provider. Unlike the prior “TFIM as SP” scenario, here we do not have to first create an identity mapping rule file, because TFIM provides a sample rule that will work unmodified in our demonstration.

To add a TFIM identity provider federation

  1. Open the WebSphere Application Server 6.1 console application at https://tfim.example.com:9061/admin.

  2. In the left navigation area, click Tivoli Federated Identity Manager, and then click Configure Federated Single Sign-on, and then click Federations.

  3. In the Federations window, click Create to start the Federation Wizard.

  4. In the General Information window, in the Federation Name field, type TFIMasIDP.

  5. Under Identify your role, click Identity Provider, and then click Next.

  6. In the Contact Information window, in the Company Name field, type Example.com, and then click Next.

  7. In the Federation Protocol window, click SAML 2.0, and then click Next.

  8. In the Point of Contact Server window, in the Point of Contact field, type https://tfim.example.com/FIM2, and then click Next.

Note

This value is case sensitive.

Note

Typically, TFIM can use the same TAM junction (FIM2 in the URL above) for multiple federations. However, due to peculiarities in this environment with the IVT application and its WebSEAL configuration scripts, we used a different junction than the one used for the TFIMasSP federation created earlier.

  1. In the Profile Selection window, select Manual: Select individual profiles and bindings and click Next.

  2. In the Profile Details window, clear the box next to HTTP Artifact, check the box next to HTTP Post, and click Next.

  3. In the Signature Options window, in the Select Signing Key section, ensure the DefaultKeyStore is selected, then in the Keystore Password text box type testonly and click List Keys.

  4. Click the radio button next to the key with the alias testkey and click Next.

  5. In the Encryption Options window, ensure the DefaultKeyStore is selected, then in the Keystore Password text box type testonly and click List Keys.

  6. Click the radio button next to the key with the alias testkey and click Next.

  7. In the SAML Message Settings window, leave the defaults and click Next.

  8. In the SAML Assertion Settings window, leave the defaults and click Next.

  9. In the Identity Mapping Options window, ensure that Use XSL transformation for identity mapping is selected, and then click Next.

  10. In the Identity Mapping window, click Browse.

  11. In the Choose File dialog box, navigate to the \examples\mapping_rules folder in the location where TFIM was installed, for example C:\Program Files\IBM\FIM\examples\mapping_rules.

  12. Select ip_saml_20_email_nameid.xsl, and then click Open.

  13. In the Identity Mapping window, click Next.

  14. In the Summary window, review your entries, and then click Finish.

  15. In the Create Federation Complete window, click Done.

Note

You can dismiss the notification in the Current Domain window that appears after you add this federation. You can load the new configuration objects to the TFIM runtime later, after other changes.

Create an SP Partner Using Metadata

Follow these instructions to add Contoso as a service provider partner to the TFIMasIDP federation.

To add a new SP partner in TFIM

  1. Open the WebSphere Application Server 6.1 console application at https://tfim.example.com:9061/admin.

  2. In the left navigation area, click Tivoli Federated Identity Manager, and then click Configure Federated Single Sign-on, and then click Partners.

  3. In the Partners window, click Create to start the Federation Partner Wizard.

  4. In the Select Federation window, click TFIMasIDP, and then click Next.

  5. In the Import Metadata window, click Browse, and then navigate to the location where you saved ADFSFederationMetadata.xml earlier.

Note

You can alternatively use the edited_ADFSFederationMetadata.xml file you created in the previous scenario here, but it is not required. The attributes removed from the <IDPSSO> element earlier do not impact TFIM’s ability to read the <SPSSO> element used in this procedure.

  1. In the Choose File dialog box, click ADFSFederationMetadata.xml, and then click Open.

  2. In the Import Metadata window, click Next.

  3. In the Signature Validation window, click the radio button next to DefaultKeyStore, then in the Keystore Password text box type testonly and click Next.

  4. In the Encryption Options window, click the radio button next to DefaultKeyStore, then in the Keystore Password text box type testonly and click Next.

  5. In the SSL Client Authentication for Artifact Resolution window, ensure the box next to Partner Requires Client Certificate Authentication is cleared, and then click Next.

  6. In the Partner Settings window, leave the defaults and click Next.

  7. In the SAML Assertion Settings window, leave the defaults and click Next.

  8. In the Identity Mapping Options window, ensure Use XSL Transformation for Identity Mapping is selected, and then click Next.

  9. In the Identity Mapping window, leave the XSLT File Containing Identity Mapping Rule field empty, and then click Next.

  10. In the Summary window, review your entries, and then click Finish.

  11. In the Add Partner Complete window, click Enable Partner.

  12. To enable all recent configuration changes, in the Current Domain window, click Load Configuration Objects to Tivoli Federation Manager runtime.

Configure WebSEAL for Federation and Sample Users

Here we will use the command-line tool tfimcfg.jar to configure WebSEAL to integrate with TFIM. In addition, we will also import the sample users we previously added to our LDAP instance into TAM.

To configure WebSEAL federation and sample users using tfimcfg.jar

  1. To open a command prompt on the TFIM computer (tfim.example.com), click Start, click Run, type cmd, and then click OK.

  2. Change the DOS prompt directory to C:\Program Files\IBM\FIM\tools\tamcfg.

  3. Identify the location where WebSEAL is installed, and then find the WebSEAL configuration file named webseald-<instance_name>.conf. The default location and file name are C:\Program Files\Tivoli\PDWeb\etc\webseald-default.conf.

  4. At the command prompt, type the following command to begin the WebSEAL configuration tool:
    java -jar tfimcfg.jar -cfgfile <full_path_to_webseal_config_file>
    For example, here we typed:
    java –jar tfimcfg.jar –cfgfile “C:\Program Files\Tivoli\PDWeb\etc\webseald-default.conf”.

  5. At the TAM administrator user-id prompt, type the administrator ID that was created during TAM installation (default sec_master), and then press ENTER.

  6. At the TAM administrator password prompt, type the administrator password that was created during TAM installation, press ENTER, type 1, and then press ENTER to proceed to the next step.

  7. At the WebSEAL hostname prompt, type tfim.example.com, press ENTER, type 1, and then press ENTER to proceed to the next step.

  8. At the ITFIM hostname prompt, type tfim.example.com, and then press ENTER.

  9. At the ITFIM HTTP port prompt, type 9080, and then press ENTER.

  10. At the Optional TFIM administrator user-id prompt, leave empty and hit ENTER.

  11. At the Optional TFIM administrator password prompt, leave empty and hit ENTER.

  12. At the Use SSL connection to ITFIM server prompt, type n, press ENTER, type 1, and then press ENTER to proceed to the next step.

  13. At Federation to configure prompt, type the number corresponding to TFIMasIDP, and then press ENTER.

  14. After the federation endpoints are displayed, type 1, and then press ENTER to proceed to the next step

  15. After the ACLs being placed on the federation endpoints are displayed, type 1, and then press ENTER to proceed to the next step.

  16. At the Perform configuration for demo application prompt, type y, and then press ENTER.

  17. To display a list of configuration actions that will be taken, type 1, and then press ENTER.

  18. To perform configuration, type 1, and then press ENTER.

Note

The TFIM Configuration Tool performs many actions when configuring the IVT application that would typically be performed manually. A list of these actions is provided in the Appendix.

Export TFIM Identity Provider Metadata to a File

Export the TFIMasIDP metadata file AD FS 2.0 will need to automate setup of the TFIM identity provider instance in the next section.

To export TFIM IdP metadata to a file

  1. In the TFIM administrative console, in the left navigation area click Configure Federated Single Sign-on, and then click Federations.

  2. In the Federations window, select the TFIMasIDP federation, and then click the Export button.

  3. Click Save, and save the file with the name TFIMasIDP_Example.com_metadata.xml to a location that can be accessed by the AD FS 2.0 computer.

Configure AD FS 2.0

Add UserName Claim Description

The inbound security token from TFIM will include a “UserName” claim containing the user’s TAM UserId. Follow the procedure below to configure AD FS 2.0 to properly receive this claim.

To add a new claim description

  1. On the AD FS 2.0 computer (fsweb.contoso.com), click Start > Administrative Tools > AD FS 2.0 Management to open the AD FS 2.0 Management console.

  2. In the left navigation area, expand the Service folder, then right-click the Claim Descriptions folder and select Add Claim Description.

  3. In the Add a Claim Description window, type the following values:

    Name Value

    Display name

    UserName

    Claim identifier

    UserName

  4. Click OK.

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.

To add an AD FS 2.0 claims provider using metadata

  1. In the AD FS 2.0 Management console, in the left navigation area, expand the Trust Relationships folder, then right-click the Claims Provider Trusts folder and select Add Claims Provider Trust to start the Add Claims Provider Trust Wizard.

  2. Click Start.

  3. In 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 TFIMasIDP_Example.com_metadata.xml earlier and click Open, and then click Next.

  6. In the Specify Display Name page, type TFIM IdP Example and click Next.

  7. Click Next, and then click Close.

Edit Claim Rules for Claims Provider Trust

Claim rules describe how AD FS 2.0 determines what data should reside inside the federation security tokens it generates. The following claim rules describes how inbound data from TFIM is prepared for use with the relying parties registered in AD FS 2.0. For example, here we will transform the UserName claim sent by TFIM into the Name claim used by all Contoso relying party applications.

To edit AD FS 2.0 claim rules for a claims provider trust

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

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

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

  4. In 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

    Email

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

  6. Click Add Rule again.

  7. In the Select Rule Template page, select the Transform an Incoming Claim box, and then click Next.

  8. In the Configure Claim Rule page, use the following values.

    Name Value

    Claim rule name

    Name Transform Rule

    Incoming claim type

    UserName

    Outgoing 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 add claim rules for the sample application that takes into account the new claims from the TFIM claims provider.

To edit the claim rules for the WIF sample application

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

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

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

  4. In 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

    Email

  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. In the Select Rule Template page, select Pass Through or Filter an Incoming Claim, and then click Next.

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

    Name Value

    Claim rule name

    Pass Name Rule

    Incoming claim type

    Name

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

  10. Click OK.

Note

If you configured the optional Step 6: Change Authorization Rules when 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, alternatively, add a new Permit or Deny Users Based on an Incoming Claim rule allowing incoming Name ID = ccalley@identityprovider.example.com to access the application.

Change AD FS 2.0 Default Name ID Format

When acting as a service provider, AD FS 2.0 defaults to requesting the Unspecified name identifier format (urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified) in outbound SAML authentication requests. This format requires special configuration in TFIM. For the sake of simplicity, we will change the default name identifier format AD FS 2.0 requests from TFIM to the emailAddress name identifier format.

To change the AD FS 2.0 default requested name identifier format

  1. On the AD FS 2.0 computer, click Start > Administrative Tools > Windows PowerShell Modules.

  2. At the PowerShell command prompt, type:
    set-ADFSClaimsProviderTrust -TargetName “TFIM IdP Example” -RequiredNameIdFormat urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

  3. Hit Enter.

Note

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 (https://go.microsoft.com/fwlink/?LinkId=194005) and the AD FS 2.0 Cmdlets Reference (https://go.microsoft.com/fwlink/?LinkId=177389).

Change AD FS 2.0 Signature Algorithm

When acting as relying party, AD FS 2.0 default configuration expects identity providers to use the Secure Hash Algorithm 256 (SHA-256) for signing operations. In addition, in cases where identity providers request signed authentication requests, AD FS 2.0 signs those requests using SHA-256.

In contrast, TFIM uses the SHA-1 algorithm to validate authentication requests and sign assertions. Follow the steps below to change the algorithm AD FS 2.0 uses with TFIM to the SHA-1 algorithm.

Warning

TFIM versions 6.2.1.2 and above supports the SHA-256 signing algorithm. Contact IBM Support for more information.

To change the AD FS 2.0 signature algorithm

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

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

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

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

Note

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, under Browsing History click Delete, and then check cookies for deletion and click Delete.

To access the WIF sample 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://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/default.aspx.

  3. The first page prompts you to select your organization from a list. Select TFIM IdP Example from the list, and then click Continue to Sign In.

Note

This page did not appear in the previous example when you were redirected to AD FS 2.0. That is because at that point there was only one claims provider registered in AD FS 2.0. When only one claims provider is available, AD FS 2.0 defaults to forwarding all security token requests to it.

  1. The Access Manager for e-business forms logon page appears. Type the user name chris and the password abcd1234, 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 proper suffix.

Appendix

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

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). TFIM likewise supports WS-Federation.

Also, both AD FS 2.0 and TFIM support use of the WS-Trust protocol for services-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 optionally allow encryption of security token contents. This lab uses self-signed private key certificates, generated from inside the AD FS 2.0 and TFIM products, for signing security tokens.

Alternatively, organizations could choose to use a private key certificate issued by a certification authority (CA) for signing/encryption. The primary benefit of using certificates issued from a CA is the ability to check for possible certificate revocation against the certificate revocation list (CRL) from the issuing CA.

In TFIM, CRL checking is not enabled by default. An administrator can add CRL checking through modifications in the TFIM and WebSphere Application Server administrative consoles. In AD FS 2.0, CRL checking is enabled by default for all claims provider trusts. This has implications in federation deployments between TFIM (acting as an IDP) and AD FS 2.0 (acting as an SP):

  • If the signing private key that TFIM uses includes a CRL Distribution Point (CDP) extension, that location must be accessible by the AD FS 2.0 Federation Server, or CRL checking fails, resulting in a failed access attempt. 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 private key does not include a CDP extension, no CRL checking is performed by AD FS 2.0.

  • 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 TFIM claims provider signing certificate, click Start > Administrative Tools > Windows PowerShell Modules on the AD FS 2.0 computer. Then at the PowerShell command prompt type:

    set-ADFSClaimsProviderTrust –TargetName “TFIM IdP 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 supported in TFIM and/or AD FS 2.0 include:

Digital Signing

  • 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 TFIM and AD FS 2.0 support), or elements of an assertion like the Subject (TFIM only)

  • Name ID in a federated single logout (SLO) request

Federated Single Logout (SLO)

Both AD FS 2.0 and TFIM include support for federated single logout. Federated single logout makes it possible for a user 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 TFIM support the SAML 2.0 HTTP Artifact binding as part of their support for the SAML 2.0 protocol. The artifact binding differs in approach from the HTTP POST binding and may be preferred in some situations.

Alternative Authentication Methods (TFIM as IdP)

When TFIM acts as the IDP, the user needing a security token must authenticate to TFIM through a point of contact server. TFIM supports these points of contact options:

  • Integration with IBM Tivoli Access Manager WebSEAL, leveraging all the authentication methods available in WebSEAL, including forms, client-side certificates, and SPNEGO/Kerberos for Windows desktop SSO.

  • Integration with IBM WebSphere Application Server, using either forms authentication or SPNEGO using Trust Association Interceptor (TAI) authentication for environments using Microsoft Active Directory as the user registry.

  • Generic/Custom point of contact server, which enables integration with other access management solutions.

SAML 2.0 IdP Discovery

Both TFIM and AD FS 2.0 support the SAML IdP Discovery Profile (https://go.microsoft.com/fwlink/?LinkId=210334) which provides 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 default approach used in both products, where users self-select their IdP from a home realm discovery (AD FS 2.0) or “Where Are You From” (TFIM) web page.

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 TFIM, select Identity Provider Discover form the SAML 2.0 Profile Details page in the Federation Wizard.

Note

When using the web-based IdP-selection interface in AD FS 2.0 or TFIM, 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 on) are typically included in a partner’s XML metadata document. In this lab, we use XML metadata documents to create trusts/connections within AD FS 2.0 and TFIM.

However, scenarios exist where 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 sent to federation servers to initiate SSO. These parameters typically impact the authnRequest an SP generates during SP-initiated SSO, or the assertion an IdP generates during IdP-initiated SSO.

In TFIM, administrators can add invoke many features by adding parameters to the URLs used to initiate SSO directly at the TFIM server.

Note

For more information on building initial URLs directed at TFIM, please see the SAML 2.0 Profile Initial URLs section of the TFIM Configuration Guide (https://go.microsoft.com/fwlink/?LinkId=213796).

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

  • RequiredNameIdFormat

  • SamlAuthenticationRequestParameters

  • SamlAuthenticationRequestIndex

  • SamlAuthenticationRequestProtocolBinding

Note

A workaround for accessing an AD FS 2.0 -protected application using an SP-initiating URL is to use WS-Federation syntax. AD FS 2.0 will perform an in-process protocol transition (from WS-Federation to SAML 2.0) during the transaction. An example URL for this lab would be: 

https://fsweb.contoso.com/adfs/ls/?wa=wsignin1.0&wtrealm=https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/default.aspx&whr= https://tfim.example.com/FIM2/sps/TFIMasIDP/saml20

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 utilize 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 dropdown 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 TFIM 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). TFIM provides this capability through its alias service. AD FS 2.0 supports creation opaque identifiers through custom claim rules.

A persistent Name ID would use the same alphanumeric value in each request from a given user, while a transient Name ID would change 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 where 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 is a summary of the capabilities in this area.

  AD FS as IDP / TFIM as SP TFIM as IDP / AD FS as RP

Persistent Name ID / account linking

WORKS

AD FS does not support account linking scenario

Transient Name ID / pseudo-anonymous access

WORKS

WORKS

Name ID Name Qualifiers

Both AD FS 2.0 and TFIM support the use 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.

Note

An spNameQualifier can represent a consortiums of SPs that share a user’s opaque identifier between them.

In TFIM, name qualifier support is automated. For example, TFIM 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 can be accomplished 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 TFIM 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"] = "https://tfim.example.com/FIM1/sps/TFIMasSP/saml20");

Modifications by the TFIM Configuration Tool (tfimcfg.jar)

The TFIM Configuration Tool (tfimfcg.jar) exists as an aid for TFIM administrators for the following purposes, one primary and one secondary:

  • Primary
    To properly configure WebSEAL to operate with the newly-established federations

  • Secondary
    To configure the sample users, groups and application that make up the Install Verification Tool (IVT) Demo Application

Because this test lab leverages the sample users, groups and application that comprise the IVT Application, this guide instructs users to use tfimfcg.jar for demo-configuration purposes. Doing so, however, automates a set of tasks that would typically have to be performed manually to accomplish the same level of functionality. These manual tasks include the following:

  • Creating sample users and groups in LDAP directory (using the ldapconfig action).

  • Importing sample users and groups into TAM.

  • Enabling forms authentication on WebSEAL, and disabling basic authentication.

  • Setting access control policies, such as itfim_TFIMasSP_anyauth, on the realms that include the pages of the demo application, such as /WebSEAL/tfim.example.com-default/FIM1/fimivt/protected/.

  • When TFIM is the Account Partner, adding e-mail address as an attribute in the TAM credential, which makes the attribute available upon user login to TFIM for use in security tokens.

  • Creating a Tag/Value configuration that passes data about the user as HTTP header values across WebSEAL junctions.

For more information about the TFIM Configuration Tool, including a complete list of actions that the tool automates, see the IBM document Using tfimcfg to Configure WebSEAL for Federations (https://go.microsoft.com/fwlink/?LinkId=213797).