IBM. Tivoli. Federated Identity Manager Version 6.2.2.7: … · 2016-05-14 · About two-legged OAuth .....371 Security Token Service interface for two-legged OAuth flow .....372

IBM® Tivoli® Federated Identity ManagerVersion 6.2.2.7

Configuration Guide

GC27-2719-02

��

NoteBefore using this information and the product it supports, read the information in “Notices” on page 785.

Edition notice

Note: This edition applies to version 6, release 2, modification 2.7 of IBM Tivoli Federated Identity Manager(product number 5724-L73) and to all subsequent releases and modifications until otherwise indicated in neweditions.

© Copyright IBM Corporation 2006, 2013.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . xiii

About this publication . . . . . . . xviiIntended audience . . . . . . . . . . . xviiAccess to publications and terminology . . . . xviiAccessibility . . . . . . . . . . . . . xviiiTivoli technical training . . . . . . . . . xviiiSupport information. . . . . . . . . . . xviiiStatement of Good Security Practices . . . . . xixConventions used in this book . . . . . . . . xix

Typeface conventions . . . . . . . . . . xixOperating system-dependent variables and paths xx

Part 1. Federation First Steps toolsetup and use . . . . . . . . . . . 1

Chapter 1. Customizing federationtemplates . . . . . . . . . . . . . . 3Customizing a federation template . . . . . . . 3

Modifying the federation template in thefedfirststeps directory . . . . . . . . . . 3Modifying the federation template in a differentdirectory. . . . . . . . . . . . . . . 3

Using the customized federation template . . . . 4

Chapter 2. Federation First Steps tool . . 5Launching the Federation First Steps tool . . . . . 5Identity provider side configuration . . . . . . 5

Creating a generic SAML 2.0 federation with anew or existing domain. . . . . . . . . . 6Configuring risk-based access with the FederationFirst Steps tool. . . . . . . . . . . . . 6Adding a service provider with the FederationFirst Steps tool. . . . . . . . . . . . . 8

Service provider side configuration . . . . . . . 9First Steps plug-in for Google Apps . . . . . 9First Steps plug-in for Microsoft Office 365 . . . 11First Steps plug-in for Salesforce . . . . . . 17First Steps plug-in for Workday . . . . . . 18

Part 2. Configuration of a domain 21

Chapter 3. Domain configuration . . . 23Worksheet for domain configuration . . . . . . 26Creating and deploying a new domain . . . . . 26Mapping the runtime to a Web server . . . . . 29Enabling replication in a WebSphere cluster . . . 30

Part 3. Configuration of a singlesign-on federation . . . . . . . . . 33

Chapter 4. Overview of configurationtasks for federated single sign-on . . . 35

Chapter 5. Identity provider and serviceprovider roles. . . . . . . . . . . . 37

Chapter 6. Using keys and certificatesto secure communications . . . . . . 39Message-level security . . . . . . . . . . . 39Transport-level security . . . . . . . . . . 40Storage and management of keys and certificates . . 43Creation of keystores, keys, and certificates . . . . 44Key selection criteria . . . . . . . . . . . 45

Chapter 7. Configuring LTPA and itskeys . . . . . . . . . . . . . . . . 47

Chapter 8. Setting up message security 49Preparing the keystores . . . . . . . . . . 49

Changing a keystore password . . . . . . . 50Creating a keystore . . . . . . . . . . . 50Importing a keystore . . . . . . . . . . 51

Planning message-level security . . . . . . . 52Obtaining your keys and certificates . . . . . . 55

Using the default key as your signing anddecryption key . . . . . . . . . . . . 55Creating self-signed certificates . . . . . . . 56Requesting CA-signed certificates . . . . . . 56

Adding your certificates to your keystore . . . . 58Importing a certificate . . . . . . . . . . 58Receiving a signed certificate from a CA. . . . 59

Obtaining a certificate from your partner . . . . 60Importing certificates from your partner'smetadata file . . . . . . . . . . . . . 61Importing a certificate from your partner . . . 61

Providing certificates to your partner . . . . . . 63Exporting certificates to a metadata file . . . . 63Exporting a certificate . . . . . . . . . . 64

Updating the cryptography policy . . . . . . . 65Removing default keystores . . . . . . . . . 65Enabling certificate revocation checking . . . . . 66

Enabling WebSphere for certificate revocationchecking . . . . . . . . . . . . . . 66Enabling the IbmPKIX trust manager for SSLconnection. . . . . . . . . . . . . . 68

Chapter 9. Setting up transport security 71Enabling SSL on the WebSphere Application Server 71

Creating a certificate request. . . . . . . . 72Receiving a signed certificate issued by acertificate authority . . . . . . . . . . . 73Associating a certificate with your SSLconfiguration . . . . . . . . . . . . . 74

© Copyright IBM Corp. 2006, 2013 iii

Deleting the default certificate . . . . . . . 75Extracting a certificate to share with your partner 75

Configuring client authentication requirements . . 76Configuring access with no authentication . . . 76Configuring basic authentication access . . . . 77Configuring access with client certificateauthentication . . . . . . . . . . . . 78

Configuring your client certificates . . . . . . 80Retrieving the server certificate from yourpartner . . . . . . . . . . . . . . . 80Obtaining your client certificate . . . . . . 81

Chapter 10. Selecting a point of contactserver . . . . . . . . . . . . . . . 83

Chapter 11. Configuring WebSphere aspoint of contact server . . . . . . . . 87Using IBM HTTP Server with WebSphere as point ofcontact . . . . . . . . . . . . . . . . 87Confirming WebSphere Application Server securityproperties . . . . . . . . . . . . . . . 88Enabling multiple language encoding on WebSphereApplication Server . . . . . . . . . . . . 89Mapping application roles to users . . . . . . 90Configuring IHS for client worksheet . . . . . . 91Setting up an outbound HTTP proxy server . . . 91WebSphere as point of contact for identity providers 93

Configuring form-based authentication . . . . 95Configuring SPNEGO authentication . . . . . 99

WebSphere point of contact server for a serviceprovider . . . . . . . . . . . . . . . 108

Configuring a WebSphere Application Serverpoint of contact server (service provider) . . . 111

Chapter 12. Configuring a Web serverplug-in . . . . . . . . . . . . . . 117Configuring service provider components . . . . 119Configuring your Web server . . . . . . . . 119

Selecting and installing a user registry . . . . 120Configuring the user registry for the targetapplication . . . . . . . . . . . . . 120Configuring an SSL connection to the userregistry . . . . . . . . . . . . . . 121Configuring a separate WebSphere ApplicationServer to host applications . . . . . . . . 121Configuring an IIS, IHS, or Apache server tohost the application . . . . . . . . . . 124

Configuring the target application . . . . . . 128Configuring the login for your application . . 128Instructing users to enable cookies . . . . . 129

Chapter 13. Setting up the aliasservice database . . . . . . . . . . 131Configuring a JDBC alias service database. . . . 132

Modifying alias service settings . . . . . . 134Configuring an LDAP alias service database . . . 134

Using tfimcfg to configure LDAP for the aliasservice. . . . . . . . . . . . . . . 135Creating an LDAP suffix . . . . . . . . 138

Planning configuration of the alias serviceproperties . . . . . . . . . . . . . 139Modifying alias service settings for LDAP . . . 141

Configuring Oracle alias service database . . . . 142

Chapter 14. Planning the mapping ofuser identities . . . . . . . . . . . 143Identity mapping overview. . . . . . . . . 144Use of XSL language for creating mapping rulesfiles . . . . . . . . . . . . . . . . 149Tivoli Directory Integrator identity mappingmodule . . . . . . . . . . . . . . . 151

Configuring the Tivoli Directory Integrator trustmodule . . . . . . . . . . . . . . 151Configuring the Tivoli Directory IntegratorServer . . . . . . . . . . . . . . . 153Configuring SSL for Tivoli Directory Integratortrust module . . . . . . . . . . . . 155

Creating a custom mapping module . . . . . . 162Adding a custom mapping module . . . . . 163Adding an instance of a custom mappingmodule . . . . . . . . . . . . . . 163

Chapter 15. SAML federationsoverview . . . . . . . . . . . . . 165SAML 1.x . . . . . . . . . . . . . . 165SAML 2.0. . . . . . . . . . . . . . . 167

Chapter 16. SAML endpoints andURLs . . . . . . . . . . . . . . . 173SAML 1.x endpoints and URLs . . . . . . . 174SAML 2.0 endpoints and URLs . . . . . . . 177

Chapter 17. Sample identity mappingrules for SAML federations . . . . . 183Mapping a local user identity to a SAML 1.x token 183Mapping a SAML 1.x token to a local user identity 184Mapping a local identity to a SAML 2.0 tokenusing an alias . . . . . . . . . . . . . 185Mapping a SAML 2.0 token to a local identity . . 186

Chapter 18. SAML 2.0 Attribute query 189Configuring attribute query . . . . . . . . 191Creating a federation as an attribute authority . . 192

Using the administration console to create afederation as an attribute authority . . . . . 192Using the command line interface to create afederation as an attribute authority . . . . . 193

Creating an identity provider partner or serviceprovider partner for an attribute authorityfederation . . . . . . . . . . . . . . 194

Using the administration console to create aservice provider or identity provider partner . . 194Using a command-line interface to create aservice provider or identity provider partner . . 196

Creating an attribute query request partner . . . 196SAML 2.0 attribute query federation response fileparameters . . . . . . . . . . . . . . 197

iv IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

SAML 2.0 attribute query partner response fileparameters . . . . . . . . . . . . . . 198

Chapter 19. Establishing a SAMLfederation . . . . . . . . . . . . . 199Gathering your federation configurationinformation . . . . . . . . . . . . . . 199

SAML 1.x service provider worksheet . . . . 199SAML 1.x identity provider worksheet . . . . 201SAML 2.0 service provider worksheet . . . . 203SAML 2.0 identity provider worksheet . . . . 208

Creating your role in the federation . . . . . . 214Configuring a WebSEAL point of contact server forthe SAML federation . . . . . . . . . . . 214Configuring WebSphere as a point of contact server 216Providing guidance to your partner . . . . . . 216Obtaining federation configuration data from yourpartner . . . . . . . . . . . . . . . 218

SAML 1.x service provider partner worksheet 219SAML 1.x identity provider partner worksheet 224SAML 2.0 service provider partner worksheet 230SAML 2.0 identity provider partner worksheet 237

Adding your partner . . . . . . . . . . . 245Providing federation properties to your partner 247

Exporting federation properties . . . . . . 247Viewing federation properties . . . . . . . 248

Synchronizing system clocks in the federation . . 248

Chapter 20. Configuring a SAMLfederation using CLI . . . . . . . . 249Configuring a SAML 1.x Identity Providerfederation using CLI . . . . . . . . . . . 249Configuring a SAML 1.x Service Providerfederation using CLI . . . . . . . . . . . 252Importing a SAML 1.x Service Provider into theSAML identity provider federation . . . . . . 255Importing a SAML 1.x Identity Provider into theSAML Service Provider federation . . . . . . 257Configuring a SAML 2.0 Identity Providerfederation using CLI . . . . . . . . . . . 260Configuring a SAML 2.0 service providerfederation using CLI . . . . . . . . . . . 264Importing a SAML 2.0 Service Provider into theSAML Identity Provider federation . . . . . . 266Importing a SAML 2.0 Identity Provider into theSAML service provider federation . . . . . . 268

Chapter 21. Planning an InformationCard federation . . . . . . . . . . 271Overview of the Information Card identityprovider . . . . . . . . . . . . . . . 272

Issuing of managed cards . . . . . . . . 272Identity provider federations . . . . . . . 275Information Card claims. . . . . . . . . 276Information Card error pages . . . . . . . 277

Overview of the Information Card relying party 278User access to a relying party . . . . . . . 278Relying party federations . . . . . . . . 280

Website enablement for Information Card . . . . 281Configuration requirements for Information Card 285

Requirement for WebSphere Version 6.1 . . . 286Updating the cryptography policy forInformation Card . . . . . . . . . . . 286Information Card requirement for alias service 287Decryption key from point of contact server . . 287Information Card time synchronizationrequirements . . . . . . . . . . . . 287

Identity mapping for Information Card. . . . . 288Identity provider configuration worksheet . . . . 289Relying party configuration worksheet . . . . . 291Managed partner worksheet . . . . . . . . 293

Chapter 22. Configuring anInformation Card federation . . . . . 297Verifying Information Card dependencies . . . . 297Configuring an Infocard federation . . . . . . 297Configuring WebSEAL as a point of contact serverfor an Information Card federation . . . . . . 298Configuring WebSphere as a point of contact server 299Specifying a persona index . . . . . . . . . 299

Chapter 23. Information Cardreference . . . . . . . . . . . . . 301Replacement macros in the infocard_template XMLfile . . . . . . . . . . . . . . . . . 301Information Card claims. . . . . . . . . . 302Federation properties for identity providers . . . 304Federation properties for relying party . . . . . 307Properties for identity provider partners for relyingparty federations . . . . . . . . . . . . 309Properties for relying party partners for identityprovider federations . . . . . . . . . . . 310

Chapter 24. OpenID planning overview 313OpenID ID URLs . . . . . . . . . . . . 313Identity provider federations . . . . . . . . 318Identity provider trust chains . . . . . . . . 320Relying Party Discovery . . . . . . . . . . 322Authentication modes . . . . . . . . . . 322Consumer federations . . . . . . . . . . 323OpenID login . . . . . . . . . . . . . 325Consumer trust chains . . . . . . . . . . 327User agent policy . . . . . . . . . . . . 331OpenID Extensions . . . . . . . . . . . 334

OpenID Simple Registration Extension . . . . 334OpenID Attribute Exchange Extension . . . . 334OpenID Provider Authentication PolicyExtension. . . . . . . . . . . . . . 337

Identity provider configuration worksheet . . . . 338Consumer configuration worksheet . . . . . . 344

Chapter 25. Configuring OpenID . . . 349Verifying OpenID dependencies . . . . . . . 349Configuring an OpenID federation . . . . . . 349Configuring performance improvement for OpenID 350Configuring a WebSEAL point of contact server foran Open ID federation . . . . . . . . . . 351Configuring WebSphere as a point of contact server 352Configuring login pages . . . . . . . . . . 352

Contents v

Chapter 26. OpenID reference . . . . 353Supported algorithms and transports . . . . . 353Template page for advertising an OpenID server 353Template page for consent to authenticate . . . . 354Template HTML page for trusted site management 359Template page for OpenID error . . . . . . . 362Template page for OpenID 2.0 indirect post . . . 363Template page returned for checkid_immediate . . 364Template page returned for server error . . . . 365

Chapter 27. OAuth planning overview 367OAuth Concepts . . . . . . . . . . . . 367OAuth endpoints . . . . . . . . . . . . 368OAuth 1.0 workflow . . . . . . . . . . . 370

About two-legged OAuth . . . . . . . . 371Security Token Service interface for two-leggedOAuth flow . . . . . . . . . . . . . 372

OAuth 2.0 workflow . . . . . . . . . . . 373Client authentication considerations at theOAuth 2.0 token endpoint . . . . . . . . 377Configuring the SOAP endpoint authenticationsettings . . . . . . . . . . . . . . 379

Client registration . . . . . . . . . . . . 380State management . . . . . . . . . . . . 380Trusted clients management . . . . . . . . 385OAuth EAS overview . . . . . . . . . . 385

OAuth data . . . . . . . . . . . . . 386Error responses. . . . . . . . . . . . 387

Federation and partner configuration information 387OAuth 1.0 service provider worksheet . . . . 388OAuth 1.0 service provider partner worksheet 391OAuth 2.0 service provider worksheet . . . . 392OAuth 2.0 service provider partner worksheet 396

Chapter 28. Configuring an OAuthfederation . . . . . . . . . . . . . 399Configuring an OAuth service provider federation 399Enabling two-legged OAuth validation . . . . . 400Configuring a WebSEAL point of contact server forthe OAuth federation. . . . . . . . . . . 400Configuring WebSphere as a point of contact server 402Adding a partner to an OAuth federation . . . . 402Configuring the WebSphere OAuth TrustAssociation Interceptor . . . . . . . . . . 403Configuring the WebSphere OAuth Servlet Filter 404WebSEAL OAuth EAS configuration. . . . . . 406

Configuring the WebSEAL OAuth EASmanually . . . . . . . . . . . . . . 407Configuring the WebSEAL OAuth EAS with thetfimcfg tool . . . . . . . . . . . . . 409

Chapter 29. OAuth reference . . . . . 411OAuth STS Interface for AuthorizationEnforcement Points . . . . . . . . . . . 411OAuth Trust Association Interceptor and ServletFilter custom properties . . . . . . . . . . 422OAuth EAS stanza reference . . . . . . . . 424

[aznapi-external-authzn-services] stanza . . . 425[azn-decision-info] stanza . . . . . . . . 426[aznapi-configuration] stanza . . . . . . . 427

[oauth-eas] stanza . . . . . . . . . . . 428OAuth 1.0 and OAuth 2.0 template pages fortrusted clients management . . . . . . . . 436OAuth 1.0 template page for consent to authorize 437OAuth 1.0 template page for response . . . . . 441OAuth 1.0 template page for denied consent . . . 441OAuth 1.0 template page for errors . . . . . . 442OAuth 2.0 template page for consent to authorize 442OAuth 2.0 template page for response . . . . . 446OAuth 2.0 template page for errors . . . . . . 446

Chapter 30. Planning a Libertyfederation . . . . . . . . . . . . . 449Identity provider and service provider roles . . . 449Liberty single sign-on profiles . . . . . . . . 450Liberty register name identifier . . . . . . . 451Liberty federation termination notification. . . . 451Liberty single logout . . . . . . . . . . . 452Liberty identity provider introduction . . . . . 453Liberty message security . . . . . . . . . 454Liberty communication properties . . . . . . 454Liberty token modules . . . . . . . . . . 455Liberty identity mapping . . . . . . . . . 456

Mapping a Tivoli Access Manager credential toa Liberty or SAML 2 token . . . . . . . . 456Mapping a Liberty or SAML 2 token to a TivoliAccess Manager credential . . . . . . . . 459

Liberty alias service . . . . . . . . . . . 461

Chapter 31. Configuring a Libertyfederation . . . . . . . . . . . . . 463Creating a Liberty identity provider . . . . . . 463Creating a Liberty service provider . . . . . . 465Configuring a WebSEAL point of contact server forthe Liberty federation . . . . . . . . . . 467Configuring WebSphere as a point of contact server 469Exporting Liberty federation properties. . . . . 469Exporting SOAP endpoint authenticationinformation to a Liberty federation partner . . . 469Obtaining metadata from a Liberty federationpartner . . . . . . . . . . . . . . . 470Importing SOAP endpoint authenticationinformation from a Liberty federation partner . . 471Adding a partner to a Liberty federation . . . . 473Configuring the alias service for Liberty . . . . 476

Creating an LDAP suffix for the alias service 476Configuring LDAP server settings . . . . . 477

Chapter 32. Planning a WS-Federationsingle sign-on federation . . . . . . 479Identity provider and service provider roles . . . 479WS-Federation single sign-on profiles . . . . . 480WS-Federation single sign-on properties . . . . 480WS-Federation token properties . . . . . . . 481WS-Federation identity mapping . . . . . . . 481

Mapping a Tivoli Access Manager credential toa SAML 1 token . . . . . . . . . . . 481Mapping a SAML 1 token to a Tivoli AccessManager credential . . . . . . . . . . 484

vi IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

Chapter 33. Configuring aWS-Federation single sign-onfederation . . . . . . . . . . . . . 487Creating a WS-Federation single sign-on federation 487Configuring WebSEAL as the point of contactserver . . . . . . . . . . . . . . . . 488Configuring WebSphere as a point of contact server 489Exporting WS-Federation properties . . . . . . 490Obtaining configuration information from aWS-Federation partner . . . . . . . . . . 490WS-Federation properties to exchange with yourpartner . . . . . . . . . . . . . . . 491Adding a partner to your WS-Federation singlesign-on federation . . . . . . . . . . . . 492

Part 4. Web services securitymanagement configuration . . . . 495

Chapter 34. Web services securitymanagement configuration . . . . . 497

Part 5. Configuring security tokenservice. . . . . . . . . . . . . . 499

Chapter 35. Kerberos constraineddelegation overview . . . . . . . . 501Overview of Kerberos constrained delegation withWebSEAL junctions . . . . . . . . . . . 502Deployment overview . . . . . . . . . . 503

Chapter 36. Enabling integratedWindows authentication . . . . . . . 505

Chapter 37. Configuring ActiveDirectory and WebSphere forconstrained delegation . . . . . . . 507

Chapter 38. Tivoli Federated IdentityManager configuration for a Kerberosjunction scenario. . . . . . . . . . 513Planning configuration of the trust chain . . . . 513Worksheet for trust chain configuration . . . . 517Creating a Kerberos constrained delegation moduleinstance . . . . . . . . . . . . . . . 519Creating a trust chain for Kerberos constraineddelegation . . . . . . . . . . . . . . 519Tivoli Federated Identity Manager configurationnotes . . . . . . . . . . . . . . . . 521

Chapter 39. WebSEAL configuration 523Verifying a WebSEAL installation . . . . . . . 523Planning WebSEAL Kerberos junction configuration 524Kerberos junction configuration worksheet . . . 528Configuring a WebSEAL Kerberos junction . . . 529WebSEAL configuration notes . . . . . . . . 530

Chapter 40. SSL configuration task fora Kerberos junctions deployment. . . 533

Part 6. Configuring User Self Care 535

Chapter 41. Understanding User SelfCare . . . . . . . . . . . . . . . 537Effectively customizing User Self Care . . . . . 539Understanding User Self Care operations . . . . 539

User ID existence check operation . . . . . 541Enrollment operation . . . . . . . . . . 541Password management operations . . . . . 542Profile management operations . . . . . . 543Forgotten user ID operation . . . . . . . 544Forgotten Password operation . . . . . . . 544Account deletion operation . . . . . . . . 545Captcha operation . . . . . . . . . . . 545Registry attributes operations . . . . . . . 545Secret question operation . . . . . . . . 546

User Self Care URLs . . . . . . . . . . . 547User Self Care HTTP requests . . . . . . . 547User Self Care HTTP responses . . . . . . 549

Captcha demonstration . . . . . . . . . . 550

Chapter 42. Deploying User Self Care 553Configuring a Tivoli Federated Identity Managerdomain . . . . . . . . . . . . . . . 553Domain configuration . . . . . . . . . . 554Configuring a user registry . . . . . . . . . 557

Configuring a Tivoli Directory Server . . . . 557Configuring a Tivoli Access Manager adapterfor WebSphere Federated Repository . . . . 558Configuring an Active Directory server . . . . 563

Configuring a response file . . . . . . . . . 564Configuring User Self Care . . . . . . . . . 566

Showing trust chains . . . . . . . . . . 566Configuring the Captcha demonstration . . . 567Using a response file to configure User Self Care 568Configuring a point of contact server . . . . 568Modifying checks on user ID and password . . 570Enabling multiple secret question. . . . . . 577Custom attribute definition . . . . . . . . 594Creating an attribute for a new custom field inUser Self Care . . . . . . . . . . . . 597User Self Care session information storage . . 598Customizing the User Self Care HTML pages 601

Integrating User Self Care with WebSEAL . . . . 609Permitting unauthenticated access to the UserSelf Care change password form . . . . . . 611Modifying the user self care WebSEAL changepassword form . . . . . . . . . . . . 612Modifying a WebSEAL expired password form 613Supporting redirection back to WebSEAL . . . 614

Modifying a User Self Care federation . . . . . 614Unconfiguring User Self Care . . . . . . . . 614

Chapter 43. Tuning User Self Care 617Account create cache . . . . . . . . . . . 618Forgotten password cache . . . . . . . . . 618

Contents vii

Secret question failure cache . . . . . . . . 619Notes about tuning caches . . . . . . . . . 619

Chapter 44. Response file parameters 621

Part 7. Configuring one-timepassword . . . . . . . . . . . . 629

Chapter 45. One-time password . . . 631One-time password overview . . . . . . . . 631One-time password configuration overview . . . 632

Chapter 46. One-time passworddeployment . . . . . . . . . . . . 635Configuring a one-time password federation . . . 635Activating the one-time password point of contact 636Configuring the one-time password in a federatedsingle sign-on flow . . . . . . . . . . . 636Verifying the one-time password federated singlesign-on configuration. . . . . . . . . . . 637Configuring one-time password extendedauthentication with WebSEAL as point of contact . 637Verifying the one-time password extendedauthentication configuration . . . . . . . . 641Creating your own one-time password point ofcontact . . . . . . . . . . . . . . . 642

HTTP request claims for authentication policycallback . . . . . . . . . . . . . . 644

One-time password resend support . . . . . . 649Configuring an unauthenticated one-time passwordflow . . . . . . . . . . . . . . . . 649Migrating one-time password files into an existingenvironment. . . . . . . . . . . . . . 650Customizing one-time password . . . . . . . 651

Customizing one-time password mapping rules 651Customizing one-time password template pages 656Authentication policy mapping rulecustomization . . . . . . . . . . . . 663Creating user-defined macros . . . . . . . 664manageItfimOneTimePassword . . . . . . 665One-time password response file . . . . . . 669manageItfimPointOfContact . . . . . . . 677Point of contact response file . . . . . . . 681One-time password provider plug-in reference 685One-time password delivery plug-in reference 690One-time password user information providerplug-in reference . . . . . . . . . . . 694

Chapter 47. Tuning the one-timepassword . . . . . . . . . . . . . 699

Part 8. Customization . . . . . . . 701

Chapter 48. Customizing runtimeproperties . . . . . . . . . . . . . 703Creating a custom property . . . . . . . . 703Deleting a custom property. . . . . . . . . 703Custom properties reference . . . . . . . . 704

General properties. . . . . . . . . . . 704Custom properties for single sign-on protocolservice. . . . . . . . . . . . . . . 705Custom properties for the trust service . . . . 707Custom properties for OAuth 2.0 . . . . . . 709Custom properties for SAML 1.0 . . . . . . 709Custom properties for SAML 1.1 . . . . . . 709Custom properties for the key service . . . . 710Custom properties for a SOAP client . . . . 711Custom properties for SAML 2.0 . . . . . . 712Custom properties for the console . . . . . 714Custom property for OpenID . . . . . . . 715Custom property for transport security protocol 715Custom properties for LTPA tokens . . . . . 716

Chapter 49. Customizing anauthentication login form for singlesign-on . . . . . . . . . . . . . . 717Supported macros for customizing anauthentication login form . . . . . . . . . 717Configuring a point of contact server to supportcustomization of login pages . . . . . . . . 720Pass SAML request element to the point of contactserver . . . . . . . . . . . . . . . . 721

Chapter 50. Customizing singlesign-on event pages . . . . . . . . 723Generation of event pages . . . . . . . . . 723Page identifiers and template files . . . . . . 724Template page for the WAYF page . . . . . . 732Modifying or creating the template files . . . . 734Publishing updates . . . . . . . . . . . 735Creating a page locale . . . . . . . . . . 736Deleting a page locale . . . . . . . . . . 736Customizing multiple-use physical page templates 737Customizing the Consent to Federate Page forSAML 2.0. . . . . . . . . . . . . . . 737

Chapter 51. Developing a custompoint of contact server . . . . . . . 741Publishing callback plug-ins . . . . . . . . 742Creating a new point of contact server . . . . . 742Creating a point of contact server like an existingserver . . . . . . . . . . . . . . . . 744Activating a point of contact server . . . . . . 746

Chapter 52. Customizing signatureX.509 certificate settings . . . . . . 747

Chapter 53. Running WebSphereApplication Server with Java 2 . . . . 749

Part 9. Appendixes . . . . . . . . 751

Appendix A. tfimcfg reference . . . . 753Configuring WebSEAL or Web Gateway Applianceas point of contact with the tfimcfg tool . . . . 754

Running the tfimcfg tool . . . . . . . . 756

viii IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

Configuring the SOAP traffic with the tfimcfgtool. . . . . . . . . . . . . . . . 758Setting up a soapusers group and certificate . . 760

tfimcfg limitation with Sun Java 1.4.2.4 . . . . . 761tfimcfg LDAP properties reference . . . . . . 761Default ldapconfig.properties file . . . . . . . 764Sample output from tfimcfg configuration of LDAP 765

Appendix B. URLs for initiating SAMLsingle sign-on actions . . . . . . . 767SAML 1.x initial URL. . . . . . . . . . . 767SAML 2.0 profile initial URLs . . . . . . . . 769

Assertion consumer service initial URL (serviceprovider) . . . . . . . . . . . . . . 769Single sign-on service initial URL (identityprovider) . . . . . . . . . . . . . . 772Single logout service initial URL . . . . . . 774

Name identifier management service initial URL 775

Appendix C. Using the command-lineinterface to configure Tivoli FederatedIdentity Manager SHA256 support . . 777

Appendix D. Disabling logging toenhance performance . . . . . . . . 783

Notices . . . . . . . . . . . . . . 785

Glossary . . . . . . . . . . . . . 789

Index . . . . . . . . . . . . . . . 793

Contents ix

x IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

Figures

1. Example of WebSphere Application Serverwith form-based authentication . . . . . . 94

2. Example of WebSphere Application Serverwith SPNEGO TAI authentication . . . . . 95

3. Example of the ktpass command . . . . . 1014. tai.properties.template file . . . . . . . 1065. Example of Tivoli Federated Identity Manager

and a Web application server . . . . . . 1096. Example of LTPA attribute to HTTP header

mapping . . . . . . . . . . . . . 1187. Example of identity mapping . . . . . . 1458. STS Universal User document schema 1479. Token processing . . . . . . . . . . 148

10. XSL code sample showing mapping of a localuser identity into a Principal name for aSAML token . . . . . . . . . . . . 184

11. XSL code sample showing assignment ofauthentication method as an Attribute for aSAML token . . . . . . . . . . . . 184

12. XSL code sample showing assignment of avalue for the Principal name for a SAMLtoken. . . . . . . . . . . . . . . 185

13. XSL code sample showing verification of avalue for the AuthenticationMethod . . . . 185

14. XSL code sample showing mapping of a localuser identity into a SAML token, using analias . . . . . . . . . . . . . . 186

15. XSL code sample showing assignment of avalue for the Principal name for a SAML 2.0token. . . . . . . . . . . . . . . 187

16. XSL code sample showing AttributeList for aSAML 2.0 token. . . . . . . . . . . 187

17. Example claims from a Information Cardidentity agent . . . . . . . . . . . 277

18. Example login format for use by RelyingParty . . . . . . . . . . . . . . 279

19. OBJECT syntax example . . . . . . . . 28220. Example of InfoCard XHTML syntax 28321. Example WebSEAL login page with OBJECT

tags . . . . . . . . . . . . . . . 28522. Example code for returning a pointer to your

OpenID server from your identity URL usingHTML discovery . . . . . . . . . . 314

23. Example claims during the identity providerinvocation of the trust service . . . . . . 321

24. Simple OpenID login form . . . . . . . 32525. OpenID login form with registry extension

parameters . . . . . . . . . . . . 32626. OpenID claims during a Consumer WS-Trust

call . . . . . . . . . . . . . . . 32927. Example STSUU during trust service request

at the OpenID Consumer . . . . . . . 33028. Default-deny hostname regular expressions 33229. Default-deny IP address netmasks . . . . 33230. Sample Simple Registration Extension 33431. Sample Attribute Exchange Extension 335

32. Template file openid_server.html . . . . . 35433. Handling consent of individual optional

attributes . . . . . . . . . . . . . 35634. Template HTML file sitemanager.html 36135. Template HTML file error.html. . . . . . 36336. Template file indirect_post.html . . . . . 36437. Template page immediate.html. . . . . . 36538. Template file server_error.html . . . . . . 36639. OAuth 1.0 XSL sample code with state

management . . . . . . . . . . . . 38240. OAuth 2.0 XSL sample code with state

management . . . . . . . . . . . . 38441. Sample JavaScript code for OAuth 1.0 40542. Sample JavaScript code for OAuth 2.0 40643. OAuth STS trust chain workflow . . . . . 41244. OAuth authorization enforcement point

workflow . . . . . . . . . . . . . 42245. Template for clients_manager.html . . . . 43746. Template for user_consent.html . . . . . 44047. Template for user_response.html . . . . . 44148. Template for user_consent_denied.html 44249. Template for user_error.html . . . . . . 44250. Template for user_consent.html . . . . . 44551. Template for user_response.html . . . . . 44652. HTML template for user_error . . . . . . 44753. XSL code sample showing mapping of a

value from a Tivoli Access Managercredential into a Principal name for a Libertytoken . . . . . . . . . . . . . . 458

54. XSL code sample showing assignment ofauthentication method as an Attribute for aLiberty token. . . . . . . . . . . . 458

55. XSL code sample showing assignment ofoptional attributes for a Liberty token . . . 459

56. XSL code sample showing optionalassignment of GroupList value to an attributefor a Liberty token . . . . . . . . . . 459

57. XSL code sample showing assignment of avalue for the Principal name for a Libertytoken. . . . . . . . . . . . . . . 460

58. XSL code sample showing optionalassignment of attributes for a Liberty token. . 461

59. XSL code sample showing mapping of avalue from a Tivoli Access Managercredential into a Principal name for a SAMLtoken . . . . . . . . . . . . . . 483

60. XSL code sample showing assignment ofauthentication method as an Attribute for aSAML token . . . . . . . . . . . . 483

61. XSL code sample showing assignment ofoptional attributes for a SAML token . . . 484

62. XSL code sample showing optionalassignment of GroupList value to an attributefor a SAML token . . . . . . . . . . 484

© Copyright IBM Corp. 2006, 2013 xi

63. XSL code sample showing assignment of avalue for the Principal name for a SAMLtoken. . . . . . . . . . . . . . . 485

64. XSL code sample showing optionalassignment of attributes for a SAML token. . 486

65. Kerberos constrained delegation with aWebSEAL junction . . . . . . . . . . 502

66. User Self Care solution . . . . . . . . 53867. Captcha example . . . . . . . . . . 55168. Sample wimconfig.xml settings . . . . . 56369. Profile management attributes in the response

file . . . . . . . . . . . . . . . 62570. Template for allerror.html . . . . . . . 658

71. Template for error_generating_otp.html 65872. Template for

error_get_delivery_options.html . . . . 65973. Template for error_otp_delivery.html 66074. Template for error_sts_invoke_failed.html 66175. Template for

error_could_not_validate_otp.html . . . . 66276. Template page for sms_message.xml . . . . 66377. Template for email_message.xml . . . . . 66378. Template page wayf-html.html . . . . . . 73479. Default values for ldapconfig.properties 76580. Sample output from tfimcfg.jar. . . . . . 766

xii IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

Tables

1. Domain configuration properties . . . . . 262. Tivoli Access Manager environment properties 263. SSL server authentication certificate

requirements . . . . . . . . . . . . 414. SSL client authentication certificate

requirements . . . . . . . . . . . . 425. Your keys . . . . . . . . . . . . . 536. Keys you need from your partner . . . . . 537. Keys you must provide to your partner 548. A list of all the possible name and values for

an outbound HTTP proxy server . . . . . 929. Parameters to use with the Microsoft

Windows ktpass command . . . . . . . 10010. Signer certificate details in SPNEGO

environment . . . . . . . . . . . . 10311. Parameters for the LDAP directory in

SPNEGO environment . . . . . . . . 10412. Macros used in the tai.properties.template file 10713. LDAP properties to modify for tfimcfg 13814. LDAP Search property . . . . . . . . 13915. LDAP environment properties . . . . . . 14016. LDAP server properties . . . . . . . . 14017. Example mapping rules . . . . . . . . 14918. Sample mapping rules files for the

demonstration application . . . . . . . 15119. Tivoli Directory Integrator Module

configuration properties worksheet . . . . 15320. STSUUSER entries used to generate a SAML

token . . . . . . . . . . . . . . 18321. SAML token information that is converted

into a STS universal user document . . . . 18422. STSUUSER entries used to generate a SAML

token, using an alias . . . . . . . . . 18623. SAML token information that is converted

into an STS universal user document . . . 18724. Attribute query parameters for federation

response file . . . . . . . . . . . . 19725. Attribute query parameters for partner

response file . . . . . . . . . . . . 19826. General information for service provider in

SAML 1.x federation . . . . . . . . . 19927. Contact information for service provider in

SAML 1.x federation . . . . . . . . . 19928. Federation protocol for service provider in

SAML 1.x federation . . . . . . . . . 20029. Point of contact server information for service

provider in SAML 1.x federation . . . . . 20030. Signature information for service provider in

SAML 1.x federation . . . . . . . . . 20031. Identity mapping information for service

provider in SAML 1.x federation . . . . . 20132. General information for identity provider in

SAML 1.x federation . . . . . . . . . 20133. Contact information for identity provider in

SAML 1.x federation . . . . . . . . . 201

34. Federation protocol information for identityprovider in SAML 1.x federation . . . . . 201

35. Point of contact server for identity providerin SAML 1.x federation . . . . . . . . 202

36. Signing information for identity provider inSAML 1.x federation . . . . . . . . . 202

37. SAML Message Settings information foridentity provider in SAML 1.x federation . . 202

38. Token Settings information for identityprovider in SAML 1.x federation . . . . . 203

39. Identity mapping information for identityprovider in SAML 1.x federation . . . . . 203

40. General information for service provider inSAML 2.0 federation . . . . . . . . . 204

41. Contact information for service provider inSAML 2.0 federation . . . . . . . . . 204

42. Federation protocol for service provider inSAML 2.0 federation . . . . . . . . . 204

43. Point of contact server information for serviceprovider in SAML 2.0 federation . . . . . 204

44. Profile selection and configurationinformation for service provider in SAML 2.0federation. . . . . . . . . . . . . 204

45. Signature information for service provider inSAML 2.0 federation . . . . . . . . . 205

46. Encryption information for service providerin SAML 2.0 federation . . . . . . . . 206

47. SAML message settings for service providerin SAML 2.0 federation . . . . . . . . 206

48. Attribute query information for serviceprovider . . . . . . . . . . . . . 207

49. Attribute query mapping information forservice provider in SAML 2.0 federation . . 208

50. Identity mapping information for serviceprovider in SAML 2.0 federation . . . . . 208

51. General information for identity provider inSAML 2.0 federation . . . . . . . . . 209

52. Contact information for identity provider inSAML 2.0 federation . . . . . . . . . 209

53. Federation protocol for identity provider inSAML 2.0 federation . . . . . . . . . 209

54. Point of contact server information foridentity provider in SAML 2.0 federation . . 209

55. Profile selection and configurationinformation for identity provider in SAML 2.0federation. . . . . . . . . . . . . 209

56. Signature information for identity provider inSAML 2.0 federation . . . . . . . . . 210

57. Encryption information for identity providerin SAML 2.0 federation . . . . . . . . 211

58. SAML message settings for identity providerin SAML 2.0 federation . . . . . . . . 211

59. Token Settings information for identityprovider in SAML 2.0 federation . . . . . 212

60. Attribute query information for identityprovider . . . . . . . . . . . . . 212

© Copyright IBM Corp. 2006, 2013 xiii

61. Attribute query mapping information foridentity provider . . . . . . . . . . 213

62. Identity mapping information for identityprovider in SAML 2.0 federation . . . . . 213

63. Metadata options for adding service providerpartner in SAML 1.x federation . . . . . 219

64. Contact information for service providerpartner in SAML 1.x federation . . . . . 219

65. SAML message settings for service providerpartner in SAML 1.x federation . . . . . 219

66. Signature validation information for serviceprovider partner in SAML 1.x federation . . 220

67. Security token settings information for serviceprovider partner in SAML 1.x federation . . 221

68. Identity mapping information for serviceprovider partner in SAML 1.x federation . . 224

69. Metadata options for adding identityprovider partner in SAML 1.x federation . . 225

70. Contact information for identity providerpartner in SAML 1.x federation . . . . . 225

71. SAML message settings for identity providerpartner in SAML 1.x federation . . . . . 225

72. Signature validation information for identityprovider partner in SAML 1.x federation . . 226

73. Server certificate validation for your identityprovider partner in a SAML 1.x federation . . 227

74. Client authentication for SOAP for youridentity provider partner in a SAML 1.xfederation. . . . . . . . . . . . . 228

75. Security token settings information foridentity provider partner in SAML 1.xfederation. . . . . . . . . . . . . 228

76. Identity mapping information for identityprovider partner in SAML 1.x federation . . 230

77. Federation to which you are adding a serviceprovider partner in a SAML 2.0 federation . . 230

78. Metadata file from your service providerpartner in a SAML 2.0 federation . . . . . 231

79. Signature validation for your service providerpartner in a SAML 2.0 federation . . . . . 231

80. Keystore for storing the encryption key fromyour service provider partner in a SAML 2.0federation. . . . . . . . . . . . . 231

81. Server certificate validation for your serviceprovider partner in a SAML 2.0 federation . . 232

82. Client authentication for your serviceprovider partner in a SAML 2.0 federation . . 232

83. Partner settings for your service providerpartner in a SAML 2.0 federation . . . . . 232

84. SAML Assertion settings for your serviceprovider partner in a SAML 2.0 federation . . 235

85. Attribute query mapping information foryour service provider partner . . . . . . 236

86. Identity Mapping options for your serviceprovider partner in a SAML 2.0 federation . . 237

87. Federation to which you are adding anidentity provider partner in a SAML 2.0federation. . . . . . . . . . . . . 237

88. Metadata file from your identity providerpartner in a SAML 2.0 federation . . . . . 238

89. Signature validation for your identityprovider partner in a SAML 2.0 federation . . 238

90. Keystore for storing the encryption key fromyour identity provider partner in a SAML 2.0federation. . . . . . . . . . . . . 238

91. Server certificate validation for your identityprovider partner in a SAML 2.0 federation . . 239

92. Client authentication for your identityprovider partner in a SAML 2.0 federation . . 239

93. Partner settings for your identity providerpartner in a SAML 2.0 federation . . . . . 239

94. SAML Assertion settings for your identityprovider partner in a SAML 2.0 federation . . 242

95. Attribute query information for identityprovider partner . . . . . . . . . . 243

96. Attribute query mapping information foridentity provider partner. . . . . . . . 244

97. Identity Mapping options for your identityprovider partner in a SAML 2.0 federation . . 245

98. Response file settings for identity provider inSAML 1.x federation . . . . . . . . . 250

99. Response file settings for service provider inSAML federation . . . . . . . . . . 253

100. Response file settings for service providerpartner in SAML 1.x federation . . . . . 255

101. Response file settings for Identity Providerpartner in SAML 1.x federation . . . . . 258

102. Response file settings for Identity Provider inSAML 2.0 federation . . . . . . . . . 260

103. Response file settings for service provider inSAML 2.0 federation . . . . . . . . . 264

104. Response file settings for Service Providerpartner in SAML 2.0 federation . . . . . 267

105. Response file settings for Identity Providerpartner in SAML 2.0 federation . . . . . 269

106. Worksheet for identity provider federationproperties . . . . . . . . . . . . . 291

107. Worksheet for relying party federationproperties . . . . . . . . . . . . . 293

108. Worksheet for managed partner configurationproperties . . . . . . . . . . . . . 294

109. Worksheet for federation identificationproperties . . . . . . . . . . . . . 343

110. Configuration properties for OpenIDconsumer . . . . . . . . . . . . . 347

111. OAuth 1.0 endpoint definitions and URLs 369112. OAuth 2.0 endpoint definitions and URLs 370113. Configurations supported . . . . . . . 378114. Worksheet for OAuth 1.0 federation

configuration properties . . . . . . . . 388115. Worksheet for OAuth 1.0 partner

configuration properties . . . . . . . . 391116. Worksheet for OAuth 2.0 federation

configuration properties . . . . . . . . 393117. Worksheet for OAuth 2.0 partner

configuration properties . . . . . . . . 396118. Trust association interceptor and servlet filter

properties . . . . . . . . . . . . . 423119. Out-STSUUSER entries used to generate a

Liberty or SAML 2 token. . . . . . . . 457

xiv IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

120. Token information that is converted into aSTS universal user document . . . . . . 460

121. LDAP Search property . . . . . . . . 477122. LDAP environment properties . . . . . . 477123. LDAP server properties . . . . . . . . 478124. In-STSUUSER entries generated from a Tivoli

Access Manager credential . . . . . . . 482125. Out-STSUUSER entries used to generate a

SAML token . . . . . . . . . . . . 482126. SAML token information that is converted

into a STS universal user document . . . . 485127. WS-Federation properties . . . . . . . 491128. WS-Federation data . . . . . . . . . 491129. SAML token module properties . . . . . 492130. Example server hostnames used in this

documentation . . . . . . . . . . . 504131. Module identification panels properties 517132. Kerberos Delegation Module Configuration

panel property . . . . . . . . . . . 517133. Chain mapping identification properties 517134. Chain Mapping Lookup properties . . . . 517135. Chain identification panel . . . . . . . 518136. Chain assembly panel. . . . . . . . . 518137. Access Manager Credential Module

Configuration property . . . . . . . . 518138. Kerberos delegation module (Issue mode)

Configuration property . . . . . . . . 518139. tfimsso and tfim-cluster stanza properties 528140. HTTP Requests . . . . . . . . . . . 547141. HTTP Responses . . . . . . . . . . 549142. Using the com.tivoli.pd.rgy.util.RgyConfig

utility . . . . . . . . . . . . . . 560143. User Self Care response file parameters 565144. Conditions found in the HTML validation

function . . . . . . . . . . . . . 571145. HTML pages . . . . . . . . . . . . 581146. HTML pages . . . . . . . . . . . . 583

147. HTML files . . . . . . . . . . . . 594148. List of attributes that are stored during a user

enrollment flow . . . . . . . . . . . 599149. List of attributes that are stored during a

forgotten password flow . . . . . . . . 600150. List of attributes that are stored during a

forgotten user ID flow . . . . . . . . 600151. Account create cache parameters . . . . . 618152. Forgotten password cache parameters 618153. Secret question failure cache parameters 619154. Values for the -operation parameter 666155. Values for the manageItfimPointOfContact

-operation parameter. . . . . . . . . 677156. Parameters used in point of contact response

files . . . . . . . . . . . . . . . 682157. Supported Protocol independent macros 718158. Supported SAML protocol macros . . . . 718159. Supported OpenID protocol macros . . . . 719160. Supported OAuth protocol macros . . . . 720161. General page identifiers and their template

files . . . . . . . . . . . . . . . 724162. SAML 1.x page identifiers and their template

files . . . . . . . . . . . . . . . 725163. SAML 2.0 page identifiers and their template

files . . . . . . . . . . . . . . . 726164. Liberty page identifiers . . . . . . . . 727165. WS-Federation page identifiers. . . . . . 728166. Independent page identifiers . . . . . . 729167. Macros used in the template files . . . . . 730168. Supported consent values for SAML 2.0

response . . . . . . . . . . . . . 738169. SAML 2.0 SHA256 Parameter Configuration

Matrix . . . . . . . . . . . . . . 777170. Identity Provider and Service Provider

SHA256 Federation and Partner Response FileParameters . . . . . . . . . . . . 779

Tables xv

xvi IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

About this publication

IBM® Tivoli® Federated Identity Manager Version 6.2.2 implements solutions forfederated single sign-on, Web services security management, and provisioning thatare based on open standards. IBM Tivoli Federated Identity Manager extends theauthentication and authorization solutions provided by IBM Tivoli Access Managerto simplify the integration of multiple existing Web solutions.

This guide describes how to configure IBM Tivoli Federated Identity Manager.

Intended audienceThe target audience for this book includes network security architects, systemadministrators, network administrators, and system integrators. Readers of thisbook should have working knowledge of networking security issues, encryptiontechnology, keys, and certificates. Readers should also be familiar with theimplementation of authentication and authorization policies in a distributedenvironment.

This book describes an implementation of a Web services solution that supportsmultiple Web services standards. Readers should have knowledge of specific Webservices standards, as obtained from the documentation produced by the standardsbody for each respective standard.

Readers should be familiar with the development and deployment of applicationsfor use in a Web services environment. This includes experience with deployingapplications into an IBM WebSphere® Application Server environment.

Access to publications and terminologyThis section provides:v A list of publications in the IBM Tivoli Federated Identity Manager library.v Links to “Online publications” on page xviii.v A link to the “IBM Terminology website” on page xviii.

IBM Tivoli Federated Identity Manager library

The following documents are available in the IBM Tivoli Federated IdentityManager library:v IBM Tivoli Federated Identity Manager Quick Start Guidev IBM Tivoli Federated Identity Manager Installation Guide, GC27-2718-01v IBM Tivoli Federated Identity Manager Configuration Guide, GC27-2719-02v IBM Tivoli Federated Identity Manager Installing, configuring, and administering

risk-based access, SC27-4445-02v IBM Tivoli Federated Identity Manager Configuring web services security,

GC32-0169-04v IBM Tivoli Federated Identity Manager Administration Guide, SC23-6191-02v IBM Tivoli Federated Identity Manager Auditing Guide, GC32-2287-05v IBM Tivoli Federated Identity Manager Troubleshooting Guide, GC27-2715-01v IBM Tivoli Federated Identity Manager Error Message Reference, GC32-2289-04

© Copyright IBM Corp. 2006, 2013 xvii

Online publications

IBM posts product publications when the product is released and when thepublications are updated at the following locations:

IBM Tivoli Federated Identity Manager Information CenterThe http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.tspm.doc_7.1/welcome.html site displays the information centerwelcome page for this product.

IBM Security Systems Documentation Central and Welcome pageIBM Security Systems Documentation Central provides an alphabetical listof all IBM Security Systems product documentation and links to theproduct information center for specific versions of each product.

Welcome to IBM Security Systems Information Centers provides andintroduction to, links to, and general information about IBM SecuritySystems information centers.

IBM Publications CenterThe http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss site offers customized search functions to help you find all the IBMpublications you need.

IBM Terminology website

The IBM Terminology website consolidates terminology for product libraries in onelocation. You can access the Terminology website at http://www.ibm.com/software/globalization/terminology.

AccessibilityAccessibility features help a user who has a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You also canuse the keyboard instead of the mouse to operate all features of the graphical userinterface.

For additional information, see the "Accessibility" topic in the information center athttp://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.tivoli.fim.doc_6.2.2/ic/ic-homepage.html.

Tivoli technical trainingFor Tivoli technical training information, refer to the following IBM TivoliEducation Web site at http://www.ibm.com/software/tivoli/education.

Support informationIf you have a problem with your IBM software, you want to resolve it quickly. IBMprovides the following ways for you to obtain the support you need:

OnlineGo to the IBM Software Support site at http://www.ibm.com/software/support/probsub.html and follow the instructions.

IBM Support AssistantThe IBM Support Assistant (ISA) is a free local software serviceabilityworkbench that helps you resolve questions and problems with IBM

xviii IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.tivoli.fim.doc_6226/ic/ic-homepage.htmlhttp://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.tivoli.fim.doc_6226/ic/ic-homepage.htmlhttps://www.ibm.com/developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/IBM%20Security%20Systems%20Documentation%20Central/page/Welcomehttp://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/index.jsphttp://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wsshttp://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wsshttp://www.ibm.com/software/globalization/terminologyhttp://www.ibm.com/software/globalization/terminologyhttp://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.tivoli.fim.doc_6.2.2/ic/ic-homepage.htmlhttp://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.tivoli.fim.doc_6.2.2/ic/ic-homepage.htmlhttp://www.ibm.com/software/tivoli/educationhttp://www.ibm.com/software/support/probsub.htmlhttp://www.ibm.com/software/support/probsub.html

software products. The ISA provides quick access to support-relatedinformation and serviceability tools for problem determination. To installthe ISA software, see the IBM Tivoli Federated Identity Manager InstallationGuide. Also see: http://www.ibm.com/software/support/isa.

Troubleshooting GuideFor more information about resolving problems, see the IBM TivoliFederated Identity Manager Troubleshooting Guide.

Statement of Good Security PracticesIT system security involves protecting systems and information throughprevention, detection and response to improper access from within and outsideyour enterprise. Improper access can result in information being altered, destroyed,misappropriated or misused or can result in damage to or misuse of your systems,including for use in attacks on others. No IT system or product should beconsidered completely secure and no single product, service or security measurecan be completely effective in preventing improper use or access. IBM systems,products and services are designed to be part of a comprehensive securityapproach, which will necessarily involve additional operational procedures, andmay require other systems, products or services to be most effective. IBM DOESNOT WARRANT THAT ANY SYSTEMS, PRODUCTS OR SERVICES AREIMMUNE FROM, OR WILL MAKE YOUR ENTERPRISE IMMUNE FROM, THEMALICIOUS OR ILLEGAL CONDUCT OF ANY PARTY.

Conventions used in this bookThis reference uses several conventions for special terms and actions and foroperating system-dependent commands and paths.

Typeface conventionsThis publication uses the following typeface conventions:

Bold

v Lowercase commands and mixed case commands that are otherwisedifficult to distinguish from surrounding text

v Interface controls (check boxes, push buttons, radio buttons, spinbuttons, fields, folders, icons, list boxes, items inside list boxes,multicolumn lists, containers, menu choices, menu names, tabs, propertysheets), labels (such as Tip:, and Operating system considerations:)

v Keywords and parameters in textItalic

v Citations (examples: titles of publications, diskettes, and CDsv Words defined in text (example: a nonswitched line is called a

point-to-point line)v Emphasis of words and letters (words as words example: "Use the word

that to introduce a restrictive clause."; letters as letters example: "TheLUN address must start with the letter L.")

v New terms in text (except in a definition list): a view is a frame in aworkspace that contains data.

v Variables and values you must provide: ... where myname represents....Monospace

v Examples and code examples

About this publication xix

http://www.ibm.com/software/support/isa

v File names, programming keywords, and other elements that are difficultto distinguish from surrounding text

v Message text and prompts addressed to the userv Text that the user must typev Values for arguments or command options

Operating system-dependent variables and pathsThis publication uses the UNIX convention for specifying environment variablesand for directory notation.

When using the Windows command line, replace $variable with % variable% forenvironment variables and replace each forward slash (/) with a backslash (\) indirectory paths. The names of environment variables are not always the same inthe Windows and UNIX environments. For example, %TEMP% in Windowsenvironments is equivalent to $TMPDIR in UNIX environments.

Note: If you are using the bash shell on a Windows system, you can use the UNIXconventions.

xx IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

Part 1. Federation First Steps tool setup and use

The topics in the Configuration section provide a step-by-step guide to configuringthe Federation First Steps feature. The management console provides wizards toguide you through many of the configuration tasks.

You can use the Federation First Steps tool to create a SAML 2.0 federation basedon a template and your preferred role.

Start with the topic Chapter 1, “Customizing federation templates,” on page 3.

© Copyright IBM Corp. 2006, 2013 1

2 IBM® Tivoli® Federated Identity Manager Version 6.2.2.7: Configuration Guide

Chapter 1. Customizing federation templates

The Federation First Steps tool contains federation templates which you can use tocreate SAML 2.0 federations. The federation templates are response files thatcontain macros which are expanded during runtime. You can edit the federationtemplates to customize some properties.

About this task

Before you use the Federation First Steps tool to create a federation, you cancustomize the federations templates. The following sections guide you through theprocess.v Customizing the federation templatev Using the customized federation template

Customizing a federation templateAbout this task

You can customize a federation template in two ways:v Modifying the federation template in the fedfirststeps directoryv Modifying the federation template in a different directory

Modifying the federation template in the fedfirststeps directoryProcedure1. Go to /firststeps/fedfirststeps/templates and locate

the template that you must customize.2. Use a text editor to edit the template that you must customize.3. Edit the variables that you must change. You can specify your preferred value

for the company name, mapping rule, and so on.4. Click Save.

Modifying the federation template in a different directoryProcedure1. Go to /firststeps/fedfirststeps/templates and locate

the template that you must customize.2. If you must put the templates folder in another location, copy the templates

folder from /firststeps/fedfirststeps/templates. Moveit in another directory, and rename it.

3. Use a text editor application to customize the template.4. Edit the variables that you must change. You can specify your preferred value

for the company name, mapping rule, and so on.5. Click Save.


Using the customized federation templateAbout this task

There are two ways to use the customized federation template in the FederationFirst Steps tool: by modifying the fedfirststep.ini file, or by using thecommand-line interface. If, for example, your custom templates are inc:\custom_tfim_fed_templates\, follow these procedures:

Procedurev Modify the fedfirststep.ini file, then run the Federation First Steps tool.

1. Go to FIM_Install/tools/fedfirststeps/fedfirststeps.ini and open thefedfirststep.ini file in a text editor.

2. Add -custom-template-dir.3. Click Save.4. Launch the Federation First Steps tool.

v Use the command-line interface1. Open the command-line interface.2. In the command-line interface, enter:

– fedfirststeps.exe -custom-template-dir– c:\custom_tfim_fed_templates


Chapter 2. Federation First Steps tool

Use the Federation First Steps tool to create a generic SAML federation, configurerisk-based access, or add service providers as a partner.

The Federation First Steps tool has the following limitations:v The Federation First Steps tool User Interface does not support wrapping of the

check box label. The text does not display in the next line and gets truncatedbecause of a known Standard Widget Toolkit issue.

v The use of Federation First Steps tool in cluster environments is not supported.

Launching the Federation First Steps toolLaunch the Federation First Steps tool to create federations.

Before you beginv For Linux and Solaris users, ensure that you are running GIMP Toolkit (GTK)

version 2.12.0 or later.v For AIX® users, ensure that you have the latest version of motif installed.

Procedure

Choose any of the following options to launch the Federation First Steps tool.v In the installation wizard, the Launch the First steps console option check box

is selected by default. Click Finish.

Note: This option is only available on a new installation of Tivoli FederatedIdentity Manager.

v In the fedfirststeps directory, launch fedfirststeps.exe or fedfirststeps.v Run the following commands in the command-line interface:

– Microsoft Windows$FIM_INSTALL_DIR\firststeps\fedfirststeps\fedfirststeps.exe

– UNIX$FIM_INSTALL_DIR/firststeps/fedfirststeps/fedfirststeps

Note: If you are using a 64-bit operating system and the Federation FirstSteps tool does not launch, ensure that the contents of the$FIM_INSTALL_DIR/firststeps/fedfirststeps.ini file is-vm$FIM_INSTALL_DIR/_uninst/_jvm/bin-nlen_US

Identity provider side configurationConfigure the identity provider federation settings using the Federation First Stepstool.


Creating a generic SAML 2.0 federation with a new or existingdomain

The Federation First Steps wizard creates a generic federation so that TivoliFederated Identity Manager users can access the applications of the serviceprovider.

Before you begin

You must know the following information to complete the wizard:v The signing key option. See Storage and management of keys and certificates.v The domain name. See Domain configuration.v The point of contact server. See Managing point of contact servers.

Procedure1. Launch the Federation First Steps tool.2. Select SAML 2.0 Wizard.3. Click Start. The tool scans your existing configuration settings.4. Provide the information that is requested by the wizard.5. Click Finish to start the task processing. Click Back if you want to change

anything.6. Optional: Activate the local domain.

a. Log on to the Integrated Solutions Console.b. Click Tivoli Federated Identity Manager > Domains. A prompt for the

detected local domain is displayed.c. Click OK to activate the local domain.

7. Optional: Check the details of the federation that you created.a. Log on to the Integrated Solutions Console.b. Click Tivoli Federated Identity Manager > Configure Federated Single

Sign-on > Federations.c. The Federations panel shows a list of configured federations. Select the new

federation that you created.d. Click Properties.e. Select the properties to modify. Federation properties are described in the

online help.f. Click OK to close the Federation Properties panel.

Configuring risk-based access with the Federation First Stepstool

Use the IBM Tivoli Federated Identity Manager Federation First Steps tool toconfigure and enable risk-based access. Risk-based access is a component for IBMTivoli Federated Identity Manager. Risk-based access provides access decision andenforcement that is based on a dynamic risk assessment or confidence level of atransaction.

Before you begin

Before you start the Federation First Steps tool, complete the following steps:


http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.tivoli.fim.doc_6.2/installconfig/concept/managementofcertsSAML.htmlhttp://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.tivoli.fim.doc_6.2/installconfig/concept/PlanningDomainConfiguration.htmlhttp://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.tivoli.fim.doc_6.2.1/task/config/console/managingcustomPOC.html

1. If you have a WebSphere Application Server clustered environment, you mustcreate and configure a JNDI context named jdbc/rba in WebSphere ApplicationServer and create the database schema for risk-based access. See Manuallyconfiguring the database.

2. Install risk-based access. See Installing risk-based access.3. Configure the WebSEAL point of contact server for IBM Tivoli Federated

Identity Manager. See Configuring WebSEAL point of contact server for SAMLfederation.

You must know the following information to complete the wizard:v URL of the Point of Contact Server for IBM Tivoli Federated Identity Managerv URI of the IBM Tivoli Access Manager secure resource that you want to protect

with risk-based accessv WebSEAL instance name

Procedure1. Launch the Federation First Steps tool.2. Select Risk-based Access Configuration Wizard.3. Click Start. The tool scans your existing configuration settings.4. Provide the information that is requested by the wizard.5. Optional: On the General Configuration Settings page, select Configure Tivoli

Access Manager, if you want to set up IBM Tivoli Access Managerenvironment so that it delegates authorization decisions to risk-based access foryour secure resources.

Note: If you select this option, you must ensure that IBM Tivoli AccessManager is installed and configured locally on the same system as IBM TivoliFederated Identity Manager.

6. Specify the URL of the Point of Contact Server for IBM Tivoli FederatedIdentity Manager, which is used for collecting attributes.http://host_name/webseal-junction-name

For example:http://mywebsealhost.company.com/FIM

After the configuration process is completed, the Risk-based AccessConfiguration Summary page describes whether the configuration failed or wassuccessful.v If the configuration completes successfully, the next steps to complete the

setup for risk-based access are displayed on the Risk-based AccessConfiguration Summary page. Follow the instructions in the summary pageto complete the IBM Tivoli Access Manager and external authorizationservice (EAS) setup for your environment.

v If the configuration fails, the log and failure messages are displayed on theRisk-based Access Configuration Summary page. Use the details that areprovided in the log and failure messages to check where the configurationprocess failed and the probable causes of failure. Resolve the configurationissues and run the Federation First Steps tool again to configure risk-basedaccess.

7. Click Finish.

Chapter 2. Federation First Steps tool 7

http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.rba.doc/rbaConfiguringDB.htmlhttp://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.rba.doc/rbaConfiguringDB.htmlhttp://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.rba.doc/rbaInstallingRisk-basedAccess.htmlhttp://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/index.jsp?topic=%2Fcom.ibm.tivoli.fim.doc_6.2.1%2Ftask%2FConfiguringSAML2POC.htmlhttp://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/index.jsp?topic=%2Fcom.ibm.tivoli.fim.doc_6.2.1%2Ftask%2FConfiguringSAML2POC.html

What to do next

After you complete all of the next steps that are specified on the summary page,verify that risk-based access is configured correctly on your system. See Verifyingthe configuration.

Adding a service provider with the Federation First Steps toolThe Federation First Steps wizard adds a service provider as a partner so thatTivoli Federated Identity Manager users can access the applications of the serviceprovider. Supported service providers include Salesforce, Google Apps, MicrosoftOffice 365, and Workday.

Before you begin

You must know the following information to complete the wizard:v Partner and domain names of the service provider that you want to add as a

partner.v Federation namev Federated user namesv If you have multiple domain names in Google Apps, the issuer in the SAML

request must be set as google.com/a/example.com instead of google.com. Thisoption must match the single sign-on option in Google Apps.

v Signing key optionv Point of contact server

About this task

The Federation First Steps wizard adds a service provider as a partner in thefollowing scenarios:v To an existing domain and an existing federationv To an existing domain and a new federationv To a new domain and a new federation

Procedure1. Launch the Federation First Steps tool.2. Select the service provider-specific plug-in that you want to use.3. Click Start. The tool scans your existing configuration settings.4. Provide the information that is requested by the wizard.5. Click Finish if you want to start the task processing. Click Back if you want to

change anything.6. Optional: Check the details of the federation that you created.

a. Log on to the Integrated Solutions Console.b. Click Tivoli Federated Identity Manager > Configure Federated Single

Sign-on > Federations.c. The Federations panel shows a list of configured federations. Select the new

federation that you created.d. Click Properties.e. Select the properties to modify. Federation properties are described in the

online help.f. Click OK to close the Federation Properties panel.


http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.rba.doc/rbaConfigVerifying.htmlhttp://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.rba.doc/rbaConfigVerifying.html

7. Optional: Check the details of the partner that was created.a. Log on to the Integrated Solutions Console.b. Click Tivoli Federated Identity Manager > Configure Federated Single

Sign-on > Partners.c. The Partners panel shows a list of configured partners. Select the new

partner that you created.d. Click Properties.e. Select the properties to modify. Partner properties are described in the

online help.f. Click OK to close the Partner Properties panel.

8. Optional: Activate the local domain.a. Log on to the Integrated Solutions Console.b. Click Tivoli Federated Identity Manager > Domains. A prompt for the

detected local domain is displayed.c. Click OK to activate the local domain.

Related concepts:“Overview on the UPN and immutableID strategy for Microsoft Office 365” onpage 11You must choose a strategy for ImmutableID before configuring single sign-onsettings for Microsoft Office 365. Microsoft Office 365 users are identified by theUser Principal Name or UPN and ImmutableID.

Service provider side configurationConfigure the service provider federation settings using the Federation First Stepstool.

Note: The configuration instructions for these service providers may change. Seethe service provider-specific documentation for updates.

First Steps plug-in for Google AppsUse the first steps plug-in to create a federation with Google Apps.1. Select the appropriate configuration for your identity provider. For more

information, see “Identity provider side configuration” on page 5.2. “Configuring Google Apps single sign-on settings”3. “Provisioning users to Google Apps” on page 104. “Testing the single sign-on to Google Apps” on page 10

Configuring Google Apps single sign-on settingsConfigure the Google Apps single-sign on settings to enable user authentication.

Before you begin

The configuration requires you to provide a certificate that is used to sign theSAML message in your Federated Identity Manager. Export your FederatedIdentity Manager certificate into a Privacy-Enhanced Message (PEM) format. See"Exporting a certificate" in the IBM Tivoli Federated Identity Manager ConfigurationGuide.


Procedure1. Navigate to the website of your service provider.

a. Open a web browser.b. Enter the URL provided by Google to access your account. For example,

https://www.google.com/a/example.com.2. Log in with your credentials.3. Navigate to the single sign-on configuration page.

a. Click Advanced Tools.b. Select Set up single sign-on (SSO).

4. Select the Enable Single Sign-on setting.5. Configure the single sign-on settings by providing the following information:

Sign-in page URLEnter the Federated Identity Manager Login Endpoint URL. Forexample, https://idp.example.com/FIM/sps//saml20/login

Sign-out page URLEnter the URL to redirect users when they log out.

Change password URLProvide the URL to let users change their password in your system.

6. Upload the verification certificate that you exported at the beginning of thistask in this field. This certificate must contain the public key from the key-pairthat is used for signing SAML messages in your Federated Identity Manager.

7. Save your settings.

What to do next

Test the single sign-on on Google Apps.

Provisioning users to Google AppsProvision users to Google Apps so they can be authenticated through singlesign-on.

Procedure1. Log in to Google Apps.2. Click Organization & users.3. Click Create a new user.4. Specify the required information about your user.5. Follow the on-screen instructions to complete the steps for adding a user.

Results

Users are added in Google Apps.

Testing the single sign-on to Google AppsTest the single sign-on authentication to Google Apps after completing all thefederation and domain configuration steps.

Before you begin

Ensure that you have added users in Google Apps and Federated IdentityManager. For more information on how to add users in Google Apps, see


“Provisioning users to Google Apps” on page 10. For more information about howto add single sign-on users in Federated Identity Manager, see the IBM TivoliFederated Identity Manager Configuration Guide.

About this task

The steps provide instructions on how you can test the single sign-on.

Procedure

Initiate the single sign-on.v To initiate single sign-on from the Identity Provider side:

1. Navigate to the login-initial endpoint of the Identity Provider.2. Indicate google.com as the PartnerId.3. Set the target to any string. For example, https://idp.example.com/sps/

/saml20/logininitial?PartnerId=google.com&Target=. You are redirected to the Identity Provider login page.

Note: If you do not specify a value for Target or set it to an empty string,Google displays an error message stating that the required responseparameter RelayState is missing.

4. Login with the user ID and password of the user that you are testing.v To initiate single sign-on from Google:

1. Access the protected resource URL. For example, https://drive.google.com/a/example.com. You are redirected to the Identity Provider login page.

2. Login with the user ID and password of the user that you are testing.

Results

The user can access the protected resource in Google Apps.

First Steps plug-in for Microsoft Office 365Use the first steps plug-in to create a federation with Microsoft Office 365. Theusage of Windows PowerShell for single sign-on to provision users is notsupported by IBM®.1. “Overview on the UPN and immutableID strategy for Microsoft Office 365”

a. “Populating the Federated Identity Manager alias service” on page 13b. “Sending a request to the Tivoli Federated Identity Manager Security Token

Service” on page 142. Select the appropriate configuration for your identity provider. For more

information, see “Identity provider side configuration” on page 5.3. “Configuring Microsoft Office 365 single sign-on settings” on page 154. “Provisioning users to Microsoft Office 365” on page 165. “Testing the single sign-on to Microsoft Office 365” on page 16

Overview on the UPN and immutableID strategy for MicrosoftOffice 365You must choose a strategy for ImmutableID before configuring single sign-onsettings for Microsoft Office 365. Microsoft Office 365 users are identified by theUser Principal Name or UPN and ImmutableID.

UPN The UPN is the local account user name that is appended with


@domainname for a registered domain you own. The Federation First Stepstool automatically generates the mapping rule that maps the local accountuser name to the UPN format.

ImmutableIDThis identifier is a non-recycled unique identifier for the account. It mustbe passed as an attribute in the SAML assertion during single sign-on toMicrosoft Office 365.

You must determine the ImmutableID value and where it is stored.

Using the Tivoli Access Manager principal UUID as the ImmutableIDThis technique applies only if you use Tivoli Access Manager WebSEAL asyour point of contact for Federated Identity Manager. It applies duringstandard user authentication from the Tivoli Access Manager registry.

Tivoli Access Manager assigns a principal UUID to each user account. ThisUUID is used during user provisioning and during single sign-on withWS-Federation in Federated Identity Manager.

The advantage of using this technique is that during single sign-on at runtime, the UUID is already in the Tivoli Access Manager credential. There isno need to write a Federated Identity Manager mapping rule to retrieve itand insert it into the SAML assertion.

The disadvantage of this technique is that there is no way of determiningwhether a user is provisioned to Microsoft Office 365 before you attemptsingle sign-on.

User provisioning must be done before a user attempts single sign-on.Otherwise, single sign-on fails. See “Provisioning users to Microsoft Office365” on page 16 for more details.

The following scenario shows a ldapsearch for a Tivoli Access Managerprincipal UUID. For example, secUUID. The Tivoli Access Manager domainis default. The user is jane. Type the command on one line./opt/IBM/ldap/V6.1/bin/idsldapsearch -L -h localhost -p 389 -Dcn=root -w -b "cn=users,secauthority=default"-s one "(&(objectclass=secUser)(principalName=jane))"

The following code is a sample result:....secDN: principalName=jane,cn=Users,secAuthority=DefaultsecUUID: a1a2a3a4-b1b2-c1c2-1111-000000000000....

Using the Federated Identity Manager alias service to manage ImmutableID

This technique requires a configured alias service for Federated IdentityManager. See IBM Tivoli Federated Identity Manager Information Centerfor more details about alias service.

If Tivoli Access Manager is not your point of contact or if you do not wantto use the Tivoli Access Manager principal UUID as the Microsoft Office365 ImmutableID, store and manage a different UUID.

Federated Identity Manager provides a generic alias service. It is used inSAML 2.0 federations with persistent name identifiers.The supportedprogrammatic interface to the Federated Identity Manager alias service isthrough the APIs in the IDMappingExtUtils class. The class can be calledfrom the Javascript and Java™ mapping rules in the Federated IdentityManager Security Token Service.


http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/index.jsp?topic=%2Fcom.ibm.tivoli.fim.doc_6.2.2%2Fic%2Fic-homepage.html

To populate the alias service, you must create an STS trust chain and callthose APIs. See “Populating the Federated Identity Manager alias service.”

Using the Base64 encoded value of UPNWith this technique, the ImmutableID that is sent to Microsoft Office 365 isthe base64-encoded value of the UPN.

Note: Use this method only in a test environment and not in a productionenvironment.

Populating the Federated Identity Manager alias service:

To use the Federated Identity Manager alias service to manage ImmutableID,populate the Federated Identity Manager alias service first.

Procedure

1. Create an STS chain with the following structure:v Default STSUU (validate)v Default Map (map)v Default STSUU (issue)

2. Set the following addresses:v AppliesTo Address http://appliesto/aliasv Issuer Address http://issuer/alias

3. Use the following JavaScript mapping rule for the default map module.// BEGIN Javascript mapping rule// mapping rule for performing simple store and fetch alias operationsimportPackage(Packages.com.tivoli.am.fim.trustserver.sts);importPackage(Packages.com.tivoli.am.fim.trustserver.sts.utilities);importPackage(Packages.com.tivoli.am.fim.trustserver.sts.uuser);

// Figure out the "operation" being performedvar operation = stsuu.getAttributeValueByName("operation");

// store operationif (operation != null && operation == "store") {// get username, federation ID, and alias value to storevar username = stsuu.getPrincipalName();var federationid = stsuu.getAttributeValueByName("federationID");var alias = stsuu.getAttributeValueByName("alias");

if (username != null && federationid != null && alias != null) {// store it, first removing any existing valuesvar existingAliasValues =

IDMappingExtUtils.lookupAliasesForUserAsStringArray(federationid, username);

if (existingAliasValues != null) {for (var i = 0; i < existingAliasValues.length; i++) {IDMappingExtUtils.removeAliasForUser(

federationid, username, existingAliasValues[i]);}}IDMappingExtUtils.addAliasForUser(federationid, username, alias);}}

// fetch operationif (operation != null && operation == "fetch") {// get username, federation IDvar username = stsuu.getPrincipalName();


Documents

IBM. Tivoli. Federated Identity Manager Version 6.2.2.7: … · 2016-05-14 · About two-legged OAuth .....371 Security Token Service interface for two-legged OAuth flow .....372