Identity and Access Management Solutions Using WebSphere Portal V5.1, Tivoli Identity Manager V4.5.1, and Tivoli Access Manager V5.1 Sg246692

Front cover
Identity and Access Management Solutions

Using WebSphere Portal V5.1, Tivoli Identity Manager V4.5.1, and Tivoli Access Manager V5.1
Explore identity and access management concepts, architecture and technology options Provision users to multiple systems and develop a custom portal interface Deploy and manage an identity and access management solution
John Ganci Subbu Cherukuwada Bob McGoogan Leonardo Olivera Jacob Thorwart Wes Wardell
ibm.com/redbooks
International Technical Support Organization Identity and Access Management Solutions Using WebSphere Portal V5.1, Tivoli Identity Manager V4.5.1 and Tivoli Access Manager V5.1 August 2005
SG24-6692-00
Note: Before using this information and the product it supports, read the information in Notices on page xiii.
First Edition (August 2005) This edition applies to IBM Tivoli Identity Manager V4.5.1, IBM Tivoli Access Manager V5.1 for e-business, IBM Tivoli Directory Server V5.2, IBM Tivoli Directory Integrator V6.0, IBM WebSphere Portal V5.1, IBM DB2 Content Manager V8.3, Enterprise Edition, and IBM Rational Application Developer V6.0.0.1 on the Microsoft Windows platform.
Copyright International Business Machines Corporation 2005. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Part 1. Introduction to identity and access management . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Introduction to identity and access management . . . . . . . . . . . . . . . . . . . . 4 1.1.1 Key concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.2 High level solution architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2 Solution software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.2.1 Runtime environment solution software . . . . . . . . . . . . . . . . . . . . . . . 9 1.2.2 Development environment solution software . . . . . . . . . . . . . . . . . . 10 1.3 Target audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.3.1 Roles and skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.3.2 Matching redbook topics to roles and skills. . . . . . . . . . . . . . . . . . . . 12 Chapter 2. Architecture and design guidelines . . . . . . . . . . . . . . . . . . . . . 15 2.1 Operational modeling guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.1.1 Operational model overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.1.2 Topology zones. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.1.3 Application architecture components . . . . . . . . . . . . . . . . . . . . . . . . 22 2.1.4 Product mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 2.1.5 Runtime environment topology selection . . . . . . . . . . . . . . . . . . . . . 24 2.1.6 Development environment topology selection . . . . . . . . . . . . . . . . . 30 2.2 Design principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 2.2.1 Centralized authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 2.2.2 Access decision evaluated on demand . . . . . . . . . . . . . . . . . . . . . . . 38 2.2.3 Capture authentication events and logs . . . . . . . . . . . . . . . . . . . . . . 38 2.3 User provisioning guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 2.3.1 Identity management overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 2.3.2 Common LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 2.3.3 Tivoli Identity Manager services, workflows, and policies . . . . . . . . . 41 2.3.4 Tivoli Directory Integrator assembly lines . . . . . . . . . . . . . . . . . . . . . 47 2.3.5 Tivoli Directory Integrator connectors . . . . . . . . . . . . . . . . . . . . . . . . 47
Copyright IBM Corp. 2005. All rights reserved.
iii
2.4 Single sign-on authentication guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . 48 2.4.1 WebSphere Portal authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 2.4.2 DB2 Content Manager authentication . . . . . . . . . . . . . . . . . . . . . . . . 49 2.4.3 Single sign-on for WebSphere Portal and Content Manager . . . . . . 52 2.4.4 Single sign-on authentication using Tivoli Access Manager . . . . . . . 55 2.5 Authorization guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 2.5.1 WebSphere Portal authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 2.5.2 DB2 Content Manager authorization . . . . . . . . . . . . . . . . . . . . . . . . . 64 2.5.3 Tivoli Access Manager authorization . . . . . . . . . . . . . . . . . . . . . . . . 66 2.5.4 WebSphere Portal vs. Tivoli Access Manager authorization . . . . . . 67 2.6 Product-specific integration guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 2.6.1 WebSEAL junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 2.6.2 Junction considerations for use with TAI. . . . . . . . . . . . . . . . . . . . . . 70 2.6.3 Handling of back-end application cookies . . . . . . . . . . . . . . . . . . . . . 71 2.6.4 Junction Mapping Table (JMT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 2.6.5 WebSEAL URL-based access control . . . . . . . . . . . . . . . . . . . . . . . 73 2.6.6 Access control of WebSphere Portal resources . . . . . . . . . . . . . . . . 74 2.6.7 Access control of resources within portlet applications . . . . . . . . . . . 74 2.6.8 WebSEAL and WebSphere Portal session considerations . . . . . . . . 74 2.7 Sequence diagrams for common access patterns . . . . . . . . . . . . . . . . . . 76 2.7.1 UCT1: Access unprotected portal page . . . . . . . . . . . . . . . . . . . . . . 77 2.7.2 UCT2: Access protected portal page, provide valid credentials . . . . 78 2.7.3 UCT3: Access protected portal page with existing valid session . . . 79 2.7.4 UCT4: Access protected portal page with invalid credentials . . . . . . 80 2.7.5 UCT5: WebSEAL session times out before portal session . . . . . . . . 82 2.7.6 UCT6: Portal session times out before WebSEAL session. . . . . . . . 84 2.7.7 UCT7: Both WebSEAL and WebSphere Portal sessions time out . . 87 2.7.8 UCT8: WebSphere Portal logout after WebSEAL session timeout . . 91 Part 2. ITSO identity and access management working example . . . . . . . . . . . . . . . . . . . 95 Chapter 3. Requirements analysis and solution design . . . . . . . . . . . . . . 97 3.1 Business scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 3.1.1 Initial context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 3.1.2 Business challenges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 3.2 Business requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 3.2.1 Functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 3.2.2 Non-functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 3.3 Use case model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 3.3.1 Use case overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 3.3.2 Use case details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 3.4 Solution architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 3.4.1 Architecture overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
iv
3.4.2 3.4.3 3.4.4 3.4.5
Architectural decisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Solution architecture details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Runtime topology and product mapping . . . . . . . . . . . . . . . . . . . . . 127 Development environment topology and product mapping . . . . . . . 128
Chapter 4. Runtime environment installation . . . . . . . . . . . . . . . . . . . . . . 129 4.1 Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 4.1.1 Hardware and software prerequisites . . . . . . . . . . . . . . . . . . . . . . . 131 4.1.2 Hardware used within the ITSO runtime environment . . . . . . . . . . 131 4.1.3 Software used within the ITSO runtime environment . . . . . . . . . . . 132 4.2 Directory node installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 4.2.1 Windows 2000 Server installation . . . . . . . . . . . . . . . . . . . . . . . . . . 135 4.2.2 DB2 Universal Database V8.2 installation . . . . . . . . . . . . . . . . . . . 137 4.2.3 IBM GSKit installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 4.2.4 WebSphere Application Server V5.0.2 installation . . . . . . . . . . . . . 143 4.2.5 Tivoli Directory Server V5.2 installation . . . . . . . . . . . . . . . . . . . . . 147 4.2.6 Tivoli Directory Server configuration . . . . . . . . . . . . . . . . . . . . . . . . 150 4.2.7 Tivoli Web Administration Tool configuration . . . . . . . . . . . . . . . . . 152 4.2.8 Tivoli Directory Integrator installation . . . . . . . . . . . . . . . . . . . . . . . 155 4.2.9 DB2 Information Integrator for Content installation . . . . . . . . . . . . . 157 4.3 Access Manager node installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 4.3.1 Windows 2000 Server installation . . . . . . . . . . . . . . . . . . . . . . . . . . 158 4.3.2 IBM Java Runtime Environment (JRE) V1.3.1 installation . . . . . . . 158 4.3.3 IBM GSKit installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 4.3.4 Tivoli Directory Client SDK 5.2 installation . . . . . . . . . . . . . . . . . . . 159 4.3.5 WebSphere Application Server V5.0.2 installation . . . . . . . . . . . . . 160 4.3.6 Configure Directory Server for Tivoli Access Manager . . . . . . . . . . 160 4.3.7 Tivoli Access Manager installation . . . . . . . . . . . . . . . . . . . . . . . . . 161 4.3.8 Tivoli Access Manager configuration . . . . . . . . . . . . . . . . . . . . . . . 162 4.3.9 Tivoli Access Manager Web Portal Manager installation . . . . . . . . 167 4.3.10 Tivoli Access Manager V5.1 Base Fixpack 9 installation . . . . . . . 168 4.3.11 Configure Web Portal Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . 170 4.3.12 Verify the Web Portal Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 4.3.13 Tivoli Identity Manager Agent for TAM installation . . . . . . . . . . . . 171 4.3.14 Tivoli Identity Manager Agent for TAM configuration . . . . . . . . . . 172 4.4 Reverse Proxy node installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 4.4.1 Windows 2000 Server installation . . . . . . . . . . . . . . . . . . . . . . . . . . 176 4.4.2 Java Runtime Environment (JRE) V1.3.1 installation . . . . . . . . . . . 176 4.4.3 IBM GSKit installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 4.4.4 Tivoli Directory Client installation . . . . . . . . . . . . . . . . . . . . . . . . . . 177 4.4.5 Tivoli Access Manager: WebSEAL installation . . . . . . . . . . . . . . . . 177 4.4.6 Tivoli Access Manager: WebSEAL configuration . . . . . . . . . . . . . . 179 4.4.7 Tivoli Access Manager V5.1 Base Fixpack 9 installation . . . . . . . . 182
Contents
4.4.8 Tivoli Access Manager V5.1 WebSEAL Fixpack 9 installation . . . . 182 4.5 Identity Management node installation . . . . . . . . . . . . . . . . . . . . . . . . . . 183 4.5.1 Windows 2000 Server installation . . . . . . . . . . . . . . . . . . . . . . . . . . 184 4.5.2 DB2 Universal Database V8.2 installation . . . . . . . . . . . . . . . . . . . 184 4.5.3 IBM GSKit V7.0.3.8 installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 4.5.4 Tivoli Directory Server V5.2 installation . . . . . . . . . . . . . . . . . . . . . 184 4.5.5 Tivoli Directory Server configuration . . . . . . . . . . . . . . . . . . . . . . . . 184 4.5.6 WebSphere Application Server V5.1. . . . . . . . . . . . . . . . . . . . . . . . 185 4.5.7 Tivoli Identity Manager V4.5.1 Fixpack 16 (full install) . . . . . . . . . . 185 4.5.8 Install Tivoli Identity Manager V4.5.1 FP42. . . . . . . . . . . . . . . . . . . 196 4.5.9 Tivoli Identity Manager Agent for TAM profile configuration . . . . . . 199 4.6 Content Management node installation. . . . . . . . . . . . . . . . . . . . . . . . . . 200 4.6.1 Windows 2000 Server installation . . . . . . . . . . . . . . . . . . . . . . . . . . 201 4.6.2 Tivoli Directory Client SDK installation . . . . . . . . . . . . . . . . . . . . . . 201 4.6.3 WebSphere Application Server V5.1.1 installation . . . . . . . . . . . . . 201 4.6.4 DB2 Universal Database V8.2 installation . . . . . . . . . . . . . . . . . . . 203 4.6.5 Create user IDs with privileges for Content Manager . . . . . . . . . . . 204 4.6.6 DB2 Content Manager V8.3 installation . . . . . . . . . . . . . . . . . . . . . 206 4.6.7 DB2 Content Manager V8.3 Client for Windows installation . . . . . . 208 4.7 Portal Server node installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 4.7.1 Windows 2000 Server installation . . . . . . . . . . . . . . . . . . . . . . . . . . 210 4.7.2 WebSphere Portal V5.1 installation . . . . . . . . . . . . . . . . . . . . . . . . 210 4.7.3 IBM HTTP Server and WebSphere plug-in installation . . . . . . . . . . 220 4.7.4 Java Runtime Environment (JRE) V1.3.1 installation . . . . . . . . . . . 222 4.7.5 Tivoli Access Manager Java Runtime Environment installation . . . 222 4.7.6 DB2 UDB V8.2 ESE installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 4.7.7 DB2 UDB Client configuration to Content Manager . . . . . . . . . . . . 224 4.7.8 Information Integrator for Content V8.3 installation. . . . . . . . . . . . . 224 4.7.9 Tivoli Identity Manager V4.5.1 API installation . . . . . . . . . . . . . . . . 231 Chapter 5. Runtime environment configuration . . . . . . . . . . . . . . . . . . . . 235 5.1 Configure WebSphere Portal for DB2 UDB. . . . . . . . . . . . . . . . . . . . . . . 236 5.1.1 Create a DB2 user for WebSphere Portal . . . . . . . . . . . . . . . . . . . . 236 5.1.2 Create DB2 UDB databases for WebSphere Portal . . . . . . . . . . . . 236 5.1.3 Migrate the data from Cloudscape to DB2 UDB . . . . . . . . . . . . . . . 240 5.2 Configure WebSphere Portal with IBM HTTP Server . . . . . . . . . . . . . . . 248 5.2.1 IBM HTTP Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 5.2.2 Configure WebSphere Portal for the external IBM HTTP Server . . 253 5.3 Configure WebSphere Portal with LDAP. . . . . . . . . . . . . . . . . . . . . . . . . 255 5.3.1 Create a suffix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 5.3.2 Create LDIF file containing users and groups . . . . . . . . . . . . . . . . . 256 5.3.3 Import the LDIF file (wp-itso.ldif) to create users and groups . . . . . 257 5.3.4 Enable LDAP security for WebSphere Portal . . . . . . . . . . . . . . . . . 258
vi
5.3.5 Verify the LDAP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 5.4 Configure DB2 Content Manager with LDAP . . . . . . . . . . . . . . . . . . . . . 265 5.4.1 Back up the DB2 Content Manager databases . . . . . . . . . . . . . . . . 266 5.4.2 Generate the cmbcmenv.properties file . . . . . . . . . . . . . . . . . . . . . 266 5.4.3 Copy the cmbcmenv.properties file . . . . . . . . . . . . . . . . . . . . . . . . . 269 5.4.4 Copy the icmxlslg.dll (user exit) . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 5.4.5 Enable trusted logons for Library Server. . . . . . . . . . . . . . . . . . . . . 270 5.4.6 Create the ClientUserEditSSO privilege sets . . . . . . . . . . . . . . . . . 272 5.4.7 Test the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 5.4.8 Configure LTPA for WebSphere Application Server . . . . . . . . . . . . 275 5.4.9 Enable SSL for LDAP server communication . . . . . . . . . . . . . . . . . 276 5.5 Enable mutual SSL between WebSEAL and Portal . . . . . . . . . . . . . . . . 276 5.5.1 IBM HTTP Server SSL configuration . . . . . . . . . . . . . . . . . . . . . . . 277 5.5.2 Configure WebSphere Portal for SSL . . . . . . . . . . . . . . . . . . . . . . . 277 5.5.3 Export IBM HTTP Server CA certificate . . . . . . . . . . . . . . . . . . . . . 278 5.5.4 Import IBM HTTP Server certificate into WebSEAL keystore . . . . . 279 5.5.5 Export WebSEAL certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 5.5.6 Import WebSEAL certificate into IBM HTTP Server keystore . . . . . 282 5.5.7 Enable mutual SSL for IBM HTTP Server . . . . . . . . . . . . . . . . . . . . 283 5.6 Configure Portal authentication with TAM using TAI . . . . . . . . . . . . . . . . 284 5.6.1 Apply Tivoli Access Manager ACLs to new LDAP suffixes . . . . . . . 285 5.6.2 Define additional MIME types for WebSphere Application Server . 294 5.6.3 Create a WebSEAL junction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 5.6.4 Enable forms authentication on WebSEAL . . . . . . . . . . . . . . . . . . . 298 5.6.5 Configure WebSEAL to modify URLs to back-end systems . . . . . . 299 5.6.6 Configure additional WebSEAL parameters . . . . . . . . . . . . . . . . . . 301 5.6.7 Import WebSphere Portal users and groups into TAM . . . . . . . . . . 301 5.6.8 Define access controls for WebSphere Portal URIs . . . . . . . . . . . . 302 5.6.9 Configure the junction mapping table (JMT) . . . . . . . . . . . . . . . . . . 305 5.6.10 Configure SSO for WebSEAL and WebSphere via TAI . . . . . . . . 308 5.6.11 Configure Portal login/logout for use with WebSEAL . . . . . . . . . . 311 5.7 Configure WebSphere Portal authorization with TAM . . . . . . . . . . . . . . . 321 5.7.1 Configure SSL between WebSphere and TAM. . . . . . . . . . . . . . . . 322 5.7.2 Configure WebSphere Portal authorization for TAM . . . . . . . . . . . . 324 5.7.3 Verify entries in TAM for Portal external authorization . . . . . . . . . . 327 5.8 Configure reverse password synchronization . . . . . . . . . . . . . . . . . . . . . 328 5.8.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 5.8.2 Enable password synchronization in Tivoli Identity Manager . . . . . 330 5.8.3 Reverse Password Synchronization Agent installation . . . . . . . . . . 330 5.8.4 Configure the Agent with Tivoli Identity Manager . . . . . . . . . . . . . . 331 5.9 Additional configuration and security hardening . . . . . . . . . . . . . . . . . . . 335 5.9.1 Configure WebSEAL and WebSphere Portal session timeouts . . . 335 5.9.2 Configure WebSEAL to handle favicon.ico . . . . . . . . . . . . . . . . . . . 337
Contents
vii
5.9.3 Security hardening . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Chapter 6. Development environment installation . . . . . . . . . . . . . . . . . . 339 6.1 Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 6.1.1 Architecture overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 6.1.2 Hardware used within the ITSO development environment . . . . . . 341 6.1.3 Software used within the ITSO development environment . . . . . . . 342 6.1.4 VMWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 6.2 Identity Manager node installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 6.3 Content Management node installation. . . . . . . . . . . . . . . . . . . . . . . . . . 344 6.4 Development node installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 6.4.1 IBM Rational Application Developer V6.0 installation . . . . . . . . . . . 345 6.4.2 WebSphere Portal V5.1 Test Environment installation . . . . . . . . . . 349 6.4.3 IBM Rational Application Developer V6.0.0.1 fixpack . . . . . . . . . . . 352 6.4.4 DB2 Universal Database installation . . . . . . . . . . . . . . . . . . . . . . . . 355 6.4.5 IBM DB2 Information Integrator for Content V8.3 installation . . . . . 355 6.4.6 Tivoli Identity Manager V4.5.1 API installation . . . . . . . . . . . . . . . . 356 6.5 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 6.5.1 Configure WebSphere Portal with LDAP . . . . . . . . . . . . . . . . . . . . 356 6.5.2 Configure DB2 Content Manager with LDAP . . . . . . . . . . . . . . . . . 357 6.5.3 WebSphere Portal V5.1 Test Environment configuration . . . . . . . . 358 6.5.4 Create a WebSphere Portal V5.1 Test Environment server . . . . . . 359 6.5.5 Tivoli Identity Manager customization . . . . . . . . . . . . . . . . . . . . . . . 361 Chapter 7. TDI connector for Content Manager development . . . . . . . . 363 7.1 Tivoli Directory Integrator connector overview . . . . . . . . . . . . . . . . . . . . 364 7.2 Create the connector class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 7.3 Create the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 7.4 Compile the connector class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 7.4.1 Import the code into Rational Application Developer . . . . . . . . . . . 368 7.4.2 Prepare project to build connector . . . . . . . . . . . . . . . . . . . . . . . . . 369 7.5 Package the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Chapter 8. TDI Assembly Line development. . . . . . . . . . . . . . . . . . . . . . . 373 8.1 Develop the DB2 Content Manager Config . . . . . . . . . . . . . . . . . . . . . . . 374 8.1.1 Create the DB2 Content Manager Config . . . . . . . . . . . . . . . . . . . . 374 8.1.2 Add the cmAdd assembly line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 8.1.3 Add the ListenForCMUpdates event handler . . . . . . . . . . . . . . . . . 382 8.1.4 Add the cmUpdate assembly line . . . . . . . . . . . . . . . . . . . . . . . . . . 383 8.1.5 Add the cmDelete assembly line . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 8.2 Develop the database Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 8.2.1 Create the database Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 8.2.2 Add the dbUpdate assembly line . . . . . . . . . . . . . . . . . . . . . . . . . . 386 8.2.3 Add the ListenForDBUpdates event handler. . . . . . . . . . . . . . . . . . 391
viii
8.2.4 Assembly line for deleting entries . . . . . . . . . . . . . . . . . . . . . . . . . . 392 8.3 Develop the LDAP Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 8.3.1 Create the LDAP Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 8.3.2 Add the ldapUpdate assembly line . . . . . . . . . . . . . . . . . . . . . . . . . 393 8.3.3 Add the ldapGroupUpdate assembly line . . . . . . . . . . . . . . . . . . . . 401 8.3.4 Update groups from within the ldapUpdate assembly line . . . . . . . 406 8.3.5 Add the ListenForLDAPUpdates event handler . . . . . . . . . . . . . . . 408 8.3.6 Assembly line for deleting entries . . . . . . . . . . . . . . . . . . . . . . . . . . 408 8.4 Testing the Configs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 Chapter 9. Tivoli Identity Manager customization . . . . . . . . . . . . . . . . . . 411 9.1 Create Identity Manager Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 9.1.1 Add Service Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 9.1.2 Create Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 9.1.3 Modify Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 9.2 Create Organizational Units and Persons . . . . . . . . . . . . . . . . . . . . . . . . 415 9.2.1 Create Organizational Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 9.2.2 Create Person . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 9.2.3 Create the organization structure . . . . . . . . . . . . . . . . . . . . . . . . . . 417 9.3 Create and Grant Organizational Roles . . . . . . . . . . . . . . . . . . . . . . . . . 419 9.3.1 Create Organizational Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 9.3.2 Grant Organizational Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 9.4 Modify the user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 9.4.1 Add attributes to user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 9.4.2 Update the Person entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 9.5 Create the Password Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 9.6 Create Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 9.6.1 Modify selfRegister workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 9.6.2 Modify transfer workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 9.7 Create Identity Manager Provisioning Policies . . . . . . . . . . . . . . . . . . . . 434 9.7.1 Modify the Default provisioning policy for ITIM . . . . . . . . . . . . . . . . 434 9.7.2 Create the DB2 Universal Database Provisioning Policy . . . . . . . . 436 9.7.3 Create the Tivoli Directory Server Provisioning Policy . . . . . . . . . . 440 9.7.4 Create the DB2 Content Manager Provisioning Policy . . . . . . . . . . 444 9.7.5 Create the Tivoli Access Manager Provisioning Policy . . . . . . . . . . 448 Chapter 10. Provisioning portlet application development. . . . . . . . . . . 451 10.1 Portlet application design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 10.2 Using the Tivoli Identity Manager APIs . . . . . . . . . . . . . . . . . . . . . . . . . 452 10.3 Prepare for the sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 10.3.1 Import the project interchange file . . . . . . . . . . . . . . . . . . . . . . . . . 453 10.3.2 Add the user library to the project build path. . . . . . . . . . . . . . . . . 453 10.3.3 Add the HR Application to the project build path. . . . . . . . . . . . . . 454
Contents
ix
10.3.4 Configure the WebSphere Portal V5.1 Test Environment. . . . . . . 454 10.4 Develop a portlet service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 10.4.1 Portlet service interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 10.4.2 Portlet service implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 10.4.3 Using the Tivoli Identity Manager APIs . . . . . . . . . . . . . . . . . . . . . 456 10.4.4 Deploy the portlet service for testing . . . . . . . . . . . . . . . . . . . . . . . 458 10.5 Develop portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 10.5.1 Develop the Self-register portlet . . . . . . . . . . . . . . . . . . . . . . . . . . 461 10.5.2 Develop the Entitlement Request portlet. . . . . . . . . . . . . . . . . . . . 463 10.5.3 Develop the ResetPassword portlet . . . . . . . . . . . . . . . . . . . . . . . 464 10.5.4 Develop the Password portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 10.5.5 Develop the Update My Info portlet. . . . . . . . . . . . . . . . . . . . . . . . 467 10.5.6 Develop the Update Roles portlet . . . . . . . . . . . . . . . . . . . . . . . . . 468 10.5.7 Develop the Update Employee Info portlet . . . . . . . . . . . . . . . . . . 468 Chapter 11. Application deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 11.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 11.1.1 Install and configure software for runtime environment . . . . . . . . 470 11.1.2 ITSO sample code download and unpack . . . . . . . . . . . . . . . . . . 470 11.1.3 Deploy HR application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 11.1.4 Deploy document management application . . . . . . . . . . . . . . . . . 470 11.2 Deploy the TDI connector for Content Manager . . . . . . . . . . . . . . . . . . 471 11.3 Deploy the TDI configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 11.3.1 Deploy the TDI config files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 11.3.2 Start the Tivoli Directory Integrator servers. . . . . . . . . . . . . . . . . . 474 11.3.3 Stop the Tivoli Directory Integrator servers . . . . . . . . . . . . . . . . . . 475 11.4 Tivoli Identity Manager customization . . . . . . . . . . . . . . . . . . . . . . . . . . 475 11.5 Deploy provisioning portlet application . . . . . . . . . . . . . . . . . . . . . . . . . 476 11.5.1 Deploy the TIM Portlet Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 11.5.2 Define the TIM Portlet Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 11.5.3 Enable sessions for anonymous users . . . . . . . . . . . . . . . . . . . . . 477 11.5.4 Create TIM administrator user in Directory node . . . . . . . . . . . . . 478 11.5.5 Create a Credential Vault Slot. . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 11.5.6 Install the User Provisioning portlets . . . . . . . . . . . . . . . . . . . . . . . 480 11.5.7 Create Portal pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 11.5.8 Add portlets to pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484 11.5.9 Assign resource permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 11.5.10 Externalize resources to Tivoli Access Manager . . . . . . . . . . . . 491 Chapter 12. Application walkthrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 12.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 12.2 Add new employee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 12.3 Employee self-registration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
12.4 HR manager employee approval and assign roles . . . . . . . . . . . . . . . . 499 12.5 Employee password reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 12.6 Employee password change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 12.7 Employee self-care . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 12.8 Employee assigns document management report . . . . . . . . . . . . . . . . 506 12.9 Employee role changed by manager. . . . . . . . . . . . . . . . . . . . . . . . . . . 508 12.10 Employee department change by manager . . . . . . . . . . . . . . . . . . . . 510 Chapter 13. Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 13.1 Generate and view a security audit report. . . . . . . . . . . . . . . . . . . . . . . 516 13.2 Log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 13.3 Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 13.3.1 Tivoli Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 13.3.2 Tivoli Identity Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 13.3.3 Tivoli Identity Manager Agent for TAM account create fails . . . . . 521 13.3.4 WebSphere Portal V5.1 Test Environment . . . . . . . . . . . . . . . . . . 522 13.3.5 Page configuration reset when Portal Test Environment restarted 522 Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 Appendix A. HR application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 Introduction to the HR application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Deploy the HR application to runtime environment . . . . . . . . . . . . . . . . . . . . 527 Requirements to deploy and run the HR application. . . . . . . . . . . . . . . . . 527 ITSO sample code download and unpack . . . . . . . . . . . . . . . . . . . . . . . . 528 Import users and groups into LDAP directory via ldif file . . . . . . . . . . . . . 528 Create the HR application database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 Deploy the HR application EAR file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 Install the HR application shared libraries . . . . . . . . . . . . . . . . . . . . . . . . . 532 Deploy the HR application WAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 Modify the PortletServiceRegistryService.properties file . . . . . . . . . . . . . 533 Create the portal pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Add portlets to pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 Assign resource permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Additional configuration when deployed with Tivoli Access Manager . . . . 541 Run the HR application in the runtime environment. . . . . . . . . . . . . . . . . . . . 543 Set up HR application in Rational Application Developer. . . . . . . . . . . . . . . . 544 Requirements to customize the HR application . . . . . . . . . . . . . . . . . . . . 545 Create the database and import the data,. . . . . . . . . . . . . . . . . . . . . . . . . 545 Import the Project Interchange File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Configure the HR application data source . . . . . . . . . . . . . . . . . . . . . . . . 545 Define the HR Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Configure the WebSphere Portal V5.1 Test Environment. . . . . . . . . . . . . 546 Configure Java build path and test environment to deploy . . . . . . . . . . . . 546
Contents
xi
Appendix B. Document management application . . . . . . . . . . . . . . . . . . 549 Introduction to the document management application . . . . . . . . . . . . . . . . . 550 User roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 Document management application detailed scenario . . . . . . . . . . . . . . . 552 Use case diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 Deploy document management application . . . . . . . . . . . . . . . . . . . . . . . . . . 553 Prerequisites for application deployment . . . . . . . . . . . . . . . . . . . . . . . . . 553 Start the servers on runtime nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 ITSO sample code download and unpack . . . . . . . . . . . . . . . . . . . . . . . . 555 DB2 Content Management application deployment . . . . . . . . . . . . . . . . . 555 WebSphere Portal application deployment . . . . . . . . . . . . . . . . . . . . . . . . 562 Additional configuration when deployed with Tivoli Access Manager . . . . 573 Run and verify the document management application . . . . . . . . . . . . . . . . . 575 Add ITSO provided theme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 Supervisor assigns report to researcher group . . . . . . . . . . . . . . . . . . . . . 577 Researcher accepts and enters report content . . . . . . . . . . . . . . . . . . . . . 578 Researcher submits report for peer review . . . . . . . . . . . . . . . . . . . . . . . . 581 Researcher adds comments for review complete . . . . . . . . . . . . . . . . . . . 581 Supervisor approves and submits to legal . . . . . . . . . . . . . . . . . . . . . . . . 583 Legal approves and submits for publishing . . . . . . . . . . . . . . . . . . . . . . . . 583 Publisher approves and publishes the report . . . . . . . . . . . . . . . . . . . . . . 584 Set up DM application in Rational Application Developer . . . . . . . . . . . . . . . 586 Prerequisites for importing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Importing a project interchange file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 Fixing build path problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 Appendix C. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 System requirements for downloading the Web material . . . . . . . . . . . . . 592 Download and unpack the Web material . . . . . . . . . . . . . . . . . . . . . . . . . 592 Description of Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
xii
Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.
xiii
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: Eserver Redbooks (logo) eServer xSeries BladeCenter ClearCase Cloudscape Domino DB2 Universal Database DB2 IBM Lotus Rational Redbooks Tivoli WebSphere Workplace Workplace Web Content Management
The following terms are trademarks of other companies: EJB, Java, Javadoc, JavaScript, JDBC, JSP, JVM, J2EE, J2SE, Sun, Sun Java, SunOS, Ultra, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. ActiveX, Microsoft Internet Explorer, Microsoft, Windows NT, Windows, Win32, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Intel, Pentium, Xeon, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others.
xiv
Preface
The identity and access management solutions described in this IBM Redbook include the following key areas: User provisioning: Develop a portlet interface for self-care (user and account management), and approval of user provisioning requests by utilizing the Tivoli Identity Manager (TIM) APIs, services, workflow, and policies. Tivoli Directory Integrator Assembly Lines and connectors are used to provision users to an LDAP directory, DB2 UDB database, and DB2 Content Manager. Authentication: Provide an integrated single sign-on (SSO) authentication solution using Tivoli Access Manager, and related technologies such as trusted association interceptor (TAI), Credential Vault, and LtpaToken. Authorization: Manage user access control through TIM provisioning policies and role mapping with products that have access models such as Tivoli Access Manager, WebSphere Portal, and DB2 Content Manager. Part 1 of the redbook describes the key concepts, solution software, architecture and design guidelines for an identity and access management solution. Part 2 contains the ITSO identity and access management working example. The example includes business requirements, architecture, details for implementing the runtime and development environments, creation of the Identity Manager workflow and policies, TDI assembly lines and connectors, provisioning portlet development, deployment, and administration. Part 3 provides procedures to deploy and run the HR and document management applications used in the working example.
The team that wrote this redbook

This redbook was produced by a team of specialists from around the world working at the International Technical Support Organization, Raleigh Center. John Ganci is a Consulting IT Specialist at the IBM ITSO, Raleigh Center, USA. John has 15 years of experience in application design, development, testing and consulting. His areas of expertise include e-business integration, WebSphere Application Server, WebSphere Portal, e-commerce, pervasive computing, technical team leadership, Linux and J2EE programming.
xv
Subbu Cherukuwada is an Advisory Security Analyst with IBM Global Services, Australia. He has ten years of experience in the fields of customer support, UNIX system administration and UNIX security auditing. He holds a Masters Degree in Information Security from RMIT University, Australia. His areas of expertise include design and implementation of IBM Tivoli Access Manager for e-business and Operating Systems, as well as security administration of HP-UX and SunOS operating systems. Bob McGoogan is an IBM Certified IT Specialist in the USA. He has been with IBM for 20 years and has spent the last seven years working with customers on Proof of Concept engagements on a number of IBM Software products. Most recently Bob has been working with customers to help them understand how WebSphere Portal can work in their environments to meet their business goals. Leonardo Olivera is an IT Specialist at IBM Global Services, Uruguay. He has ten years of experience in application development and systems integration. He holds a degree in Computer Science Engineering from Catholic University, Uruguay. His areas of expertise include J2EE application development and WebSphere Application Server, acting as technical advisor for several J2EE related projects. He also teaches courses on Object Oriented Programming, Java and J2EE. Jacob Thorwart is a Co-op IT Specialist at the IBM ITSO Center in Raleigh, North Carolina. He is currently pursuing a Bachelor of Science degree in Information Sciences and Technology at Pennsylvania State University. His interests include systems integration and Web applications. Wes Wardell is a Staff Software Developer for IBM Software Group in Toronto, Canada. He has nine years of experience in application development and testing. He holds a degree in Computing and Computer Electronics from Wilfrid Laurier University, Canada. His areas of expertise include Web application development and solution integration, recently working with such products as WebSphere Application Server, Tivoli Directory Integrator, WebSphere Portal, and Tivoli Identity Manager. Thanks to the following people for their contributions to this project: Fred Lu, IBM Canada Kai Schwidder, IBM Switzerland Oleg Bascurov, IBM Germany Normunds Saumanis, IBM Latvia Zoran Radenkovic, IBM Australia Brian Matthiesen, IBM USA Yvonne Lyon, ITSO editor, IBM USA
xvi
Become a published author

Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability. Find out more about the residency program, browse the residency index, and apply online at:
ibm.com/redbooks/residencies.html
Comments welcome
Your comments are important to us! We want our Redbooks to be as helpful as possible. Send us your comments about this or other Redbooks in one of the following ways: Use the online Contact us review redbook form found at:
ibm.com/redbooks
Send your comments in an email to:

redbook@us.ibm.com
Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HZ8 Building 662 P.O. Box 12195 Research Triangle Park, NC 27709-2195
Preface
xvii
xviii
Part 1
Part
Introduction to identity and access management
Chapter 1.
Introduction
Nearly every e-business needs a secure infrastructure for hosting Web-based applications such as portals. There are several common challenges that businesses face when implementing applications with integration to back-end systems. First, the site needs to provide a method of provisioning users across the enterprise. Second, the site needs the capability to permit or deny access to resources based on the policies and users/groups who access the resources (authorization). Third, the site needs to provide a means of determining who is accessing the site (authentication) and only require a single sign-on (SSO) to access resources to which they have been granted access. Finally, there needs to be an audit trail to ensure proper use of the system. In some cases, businesses have tried to pioneer these solutions on their own. This can be a very costly and risky approach to Web-based security. As the complexity of Web sites increases to meet e-business needs, there is a growing expectation for IT shops to deploy solutions in a very timely fashion. To solve these infrastructure and security needs, many companies look to leverage middleware software technologies that provide an integrated solution for user provisioning, authentication, authorization and auditing. When companies invest in Web security solutions from IBM, they get a proven production-ready solution that can dramatically accelerate their time to market. The focus of this chapter is to introduce the key concepts of an identity and access management system and define the target audience of the redbook.
1.1 Introduction to identity and access management

The identity and access management solutions found in this redbook leverage the functionality provided by several IBM software products, including Tivoli Identity Manager, Tivoli Access Manager, Tivoli Directory Integrator, Tivoli Directory Server, and WebSphere Portal. When integrated together, the IBM middleware products provide solutions for user provisioning, single sign-on authentication, authorization, and security audit reporting.
1.1.1 Key concepts

This section highlights key identity and access management concepts.
Identity management
Identity management entails the tasks required to manage a users identity within an organizational structure such as a directory. This includes the ability to create or provision a user, manage a user, and delete a user. The identity of a user is used for authentication and authorization to resources the user is granted access.
User provisioning
Within the context of this redbook, user provisioning provides a method of creating and managing users from a central system to external systems. It is common for enterprise applications to share a common LDAP user registry. In some cases, legacy systems require that users are provisioned to the legacy system. The objective is to provision and manage users from a central system.
Authentication
Authentication is a process where the client identity is validated. The client can be an end user, a machine, or an application. The identity of the user, authenticated or unauthenticated, is used to acquire the users credentials to determine if the user has permissions for the requested resource (authorization).
Authorization
The authorization process provides the capability to permit or deny access to resources based on the policies and users that access the resources. If the resource is protected, the user will first be authenticated to determine their identity, and then the privileges defined for the desired resource will be checked.
Shared LDAP user registry

The user registry is stored under a root LDAP suffix (for example, dc=itso, dc=ibm, dc=com) in the LDAP repository. For example, in an identity and access management solution, Tivoli Access Manager, WebSphere Portal, and WebSphere Application Server reference the same user registry, since they are configured to connect to and use the same Tivoli Directory Server LDAP repository.
Single sign-on
Single sign-on provides users with the ability to log on once (authenticate) and be able to access resources or applications within the enterprise the user has been granted permissions.
Credential Vault
WebSphere Portal includes the Credential Vault, which provide a mechanism for storing external credentials, retrieving those credentials from an application, and passing the user credentials to a back-end application. The Credential Vault is a portal service that helps portlets and portal users manage multiple identities. When using Tivoli Access Manager with WebSphere Portal, the credential storage for the Credential Vault can be moved to the Tivoli Access Manager Global Sign-on (GSO) lockbox.
Audit trail
An audit trail is used to record transactions of a system to ensure its integrity. Within an identity management system, the audit trail can be used to validate that the provisioning of users was performed as intended by the security of the system, as well as to validate proper access to resources and authentication.
1.1.2 High level solution architecture

Figure 1-1 on page 7 depicts the key components of the Identity and Access Management solution discussed in this redbook. The primary focus of this redbook is on the user provisioning solution, however both single sign-on authentication and authorization are also implemented in detail. To provide a better understanding of the high level solution architecture, we describe a simplified walkthrough of each of the key architecture elements.
User provisioning
The primary IBM software products applied in the user provisioning solution in this redbook are Tivoli Identity Manager (TIM), Tivoli Directory Integrator (TDI), and Tivoli Directory Server (TDS). In the ITSO working example, we created a front-end portlet application that used Tivoli Identity Manager APIs to interact with TIM to provision users.
Chapter 1. Introduction
Users are provisioned as follows: 1. User provisioning request pending approval within Tivoli Identity Manager. There are several ways that a Tivoli Identity Manager request would be entered and require approval. The provisioning entry requiring approval could be entered via the Tivoli Identity Manager Console, or a front-end application such as the portlet application we developed in the ITSO working example. 2. The approval of the provisioning request will create an account in Tivoli Identity Manager (TIM). 3. Based on the roles assigned to the user being provisioned, TIM policies will be executed, which in turn call Tivoli Directory Integrator Assembly Lines. 4. Tivoli Directory Integrator (TDI) Assembly Lines are used to define tasks to be executed based on the TIM policies executed. For example, a TIM policy to provision a user to an LDAP directory would invoke a TDI Assembly Line for LDAP. The TDI Assembly Line can make use of TDI connectors to perform the actual task of provisioning the user in another system, such as LDAP. TDI includes many connectors that can be used out-of-the-box. In addition, custom TDI connectors can be built using the APIs of TDI and the target system. In our working example, we demonstrate how to develop a custom TDI connector for DB2 Content Manager to provision a user. In some cases, Tivoli Identity Manager Agents exist with the necessary function to provision a user without the need for a TDI connector. For example, the Tivoli Identity Manager Agent for Tivoli Access Manager can be used to provision a user to Tivoli Access Manager.
Access Manager TAM Authorization TAM Policy TIM Agent for TAM TIM Policies 3 Database policy LDAP policy Backend policy TAM policy Identity Manager Tivoli Identity Manager
Authorization
Database AL
TDI Assembly Lines 1
Backend AL
LDAP AL
Authentication
Portal Server TAI Portlet and J2EE applications
User Provisioning
TDI connector
TDI connector
Client Web Browser
Reverse Proxy TAM WebSEAL
Directory Tivoli Directory Integrator Tivoli Directory Server
TAI, or LtpaToken
Backend
Figure 1-1 High level Identity and Access Management solution architecture
Single sign-on (SSO) authentication

Within an enterprise environment where users interact with multiple Web applications, it is highly desirable to enable single sign-on authentication. For this redbook, single sign-on is achieved by using Tivoli Access Manager and Tivoli Directory Server, as well the use of Trusted Association Interceptors (TAI) and LtpaTokens to pass credentials. The SSO authentication of a user within the identity and access management solution depicted in Figure 1-1, is achieved as follows: 1. The user enters a URL in the Web browser to access a resource that is protected by the WebSEAL.
2. The Tivoli Access Manager WebSEAL determines if the user has attempted to access a protected resource and will prompt the user with a logon page. 3. The user enters their username and password in the logon form and then submits the credentials to the WebSEAL. 4. The WebSEAL then interacts with the Tivoli Access Manager Policy Server and Tivoli Directory Server to validate the identity of the user in the Tivoli Access Manager user registry. 5. The WebSEAL uses the validated identity to obtain a credential for that user. 6. If the request is to access a back-end resource or application, the credentials are passed using either a Trusted Association Interceptor (TAI) or an LtpaToken depending on the target system. SSO can also be achieved from WebSphere Portal to a back-end system using the Credential Vault provided by WebSphere Portal.
Authorization
Managing access to resources in an enterprise environment can be very tedious when many systems and applications employ their own access control security models. Tivoli Access Manager provides a means of centralizing access controls to resources and applications. In the identity and access management solution depicted in Figure 1-1 on page 7, Tivoli Access Manager can be used for authorization to resources and applications. In the ITSO working example, we provide procedures for implementing native access control models within WebSphere Portal and DB2 Content Manager, as well as using Tivoli Access Manager. Authorization using Tivoli Access Manager within the identity and access management solution depicted in Figure 1-1 on page 7, works as follows: 1. The WebSEAL interacts with the Tivoli Access Manager authorization services with the user credentials to permit or deny access to protected objects after evaluating the access control list (ACL) permissions and protected object policy (POP). 2. WebSEAL forwards the request to WebSphere Portal. 3. The portlet then interacts with the back-end application. 4. The WebSEAL sends the response to the Web browser client to display the contents of the portal page.
1.2 Solution software

This section highlights the software we used in the ITSO working example identity and access management system for both the runtime and development environments.
1.2.1 Runtime environment solution software

When implementing the ITSO working example identity and access management solution, we used the most current fixpack levels of the software at the time of writing, in some cases to address problems and validate the functionality when integrated. We used Microsoft Windows 2000 Server with Service Pack 4 as the operating system platform. There are many possible runtime topologies, depending on the customers requirements. In 2.1.5, Runtime environment topology selection on page 24, we define four topologies (entry, enterprise, extended enterprise, high availability extended enterprise). We provide guidance on selecting the appropriate runtime topology, as well as define by node the software products and levels. The ITSO runtime environment includes the following software: IBM Tivoli Identity Manager V4.5.1 + Fixpack 42 IBM Tivoli Identity Manager Agent V4.5.9 for Tivoli Access Manager IBM Tivoli Access Manager V5.1 for e-business + Fixpack 9 IBM Tivoli Directory Integrator V6.0 + Fixpack 1 IBM Tivoli Directory Server V5.2 + Fixpack 2 IBM WebSphere Application Server V5.1 + Fixpack 1 IBM WebSphere Application Server V5.0 + Fixpack 2 IBM WebSphere Portal V5.1 Extend for Multiplatforms IBM DB2 Universal Database V8.2, Enterprise Server Edition + Fixpack 8 IBM DB2 Content Manager V8.3, Enterprise Edition IBM DB2 Information Integrator for Content V8.3
1.2.2 Development environment solution software

Like the runtime environment, there are several possible configurations for implementing a development environment. The development environment topologies, software products, and levels are described in detail in 2.1.6, Development environment topology selection on page 30. The ITSO development environment includes the following software: IBM Rational Application Developer V6.0 + Fixpack V6.0.0.1 Integrated Development Environment Portal Tools WebSphere Portal V5.1 Test Environment IBM DB2 Information Integrator for Content V8.3 - Content Manager connector jars for APIs IBM Tivoli Identity Manager V4.5.1 - jars for APIs IBM Tivoli Directory Integrator V6.0 - jars for APIs For development and test purposes, we used all of the software listed in 1.2.1, Runtime environment solution software on page 9, within the development environment.
1.3 Target audience

This redbook includes architecture, design, development, integration, deployment and administration topics. The target audience for this redbook can be best matched by role to the topic of interest within the publication. The identity and access management solution found in this redbook is largely targeted at enterprise customers.
10
1.3.1 Roles and skills

This section includes a brief description of the roles needed for a team to execute an identity and access management project during the development life-cycle, with the objective of mapping the redbook topics to roles and skills.
IT architect
The IT architect looks after the overall project technical architecture/design, quality assurance of the solution, knowledge transfer to customer, and mentoring to the project technical team members. The architect should have product knowledge for WebSphere Portal, Tivoli Identity Manager, Tivoli Access Manager, Tivoli Directory Integrator.
Security architect
The role of a security architect is to eliminate or greatly reduce the possibility of an intruder attack. When developing a strategy for providing an identity and access management solution, it is critical that the security architect understand the areas of risk and ensure that the solution architecture addresses the known risk categories.
IT specialist
The role of IT specialist represents a wide range of technical specialists, including systems administrator, database administrator, pre-sales support, technical support, and tester.
Portal developer
The portal developer is responsible for developing the portlets for the identity and access management solution. In small projects, a developer may perform several roles, including J2EE application developer, portal developer, and Web designer.
J2EE developer
The J2EE developer is responsible for developing such application code as EJBs and servlets for back-end applications.
Java developer
The Java developer is responsible for developing such application code as Java connectors such as a custom Tivoli Directory Integrator connector for DB2 Content Manager.
11
Project manager
The project manager is responsible for managing and leading the project team along all phases of the project and also acts as a contact point to interact with the customer.
Security administrator
The security administrator is responsible for implementing the access control list (ACL) policies and protected object policies (POP) for protected resources. In addition, the security administrator is responsible for managing the identity of users within the system.
Portal administrator
The portal administrator role is responsible for deploying portlets and managing the portal server, including security-related tasks and troubleshooting.
Content Manager administrator

The DB2 Content Manager administrator is responsible for manage the DB2 Content Manager system. This includes provisioning users and groups, configuring the item type and attributes, access controls, and workflows.
1.3.2 Matching redbook topics to roles and skills

Table 1-1 provides a summary of the redbook topics by part and chapter/appendix for the defined roles and skills.
Table 1-1 Matching redbook topics to roles and skills Chapter/appendix Part 1, Introduction to identity and access management Chapter 1, Introduction on page 3 Chapter 2, Architecture and design guidelines on page 15 All user roles IT architect All user roles Primary Secondary
Part 2, ITSO identity and access management working example
12
Chapter/appendix Chapter 3, Requirements analysis and solution design on page 97 Chapter 4, Runtime environment installation on page 129 Chapter 5, Runtime environment configuration on page 235 Chapter 6, Development environment installation on page 339 Chapter 7, TDI connector for Content Manager development on page 363 Chapter 8, TDI Assembly Line development on page 373 Chapter 9, Tivoli Identity Manager customization on page 411 Chapter 10, Provisioning portlet application development on page 451 Chapter 11, Application deployment on page 469
Primary IT architect Security architect Project manager IT specialist IT specialist Security administrator Portal administrator Portal developer J2EE developer Java developer Security administrator IT specialist Security administrator IT specialist Portal developer J2EE developer IT specialist Portal administrator Security administrator Portal developer J2EE developer IT specialist Portal administrator Security administrator
Secondary All user roles
IT architect IT architect Security architect IT architect IT specialist IT architect IT specialist IT architect IT architect IT architect Portal developer J2EE developer IT architect IT architect Portal administrator Security administrator IT specialist IT architect
Chapter 12, Application walkthrough on page 493
Chapter 13, Administration on page 515 Part 3, Appendixes on page 523 Appendix A, HR application on page 525
IT specialist Portal developer J2EE developer Content Manager administrator IT specialist Portal developer J2EE developer
IT architect
Appendix B, Document management application on page 549
IT architect
13
14
Chapter 2.
Architecture and design guidelines

This chapter is intended to provide a technical foundation for understanding how to design and build an identity and access management system. First we explore the operational model by examining the solution architecture components, common runtime and development topologies, and product mappings. Next we examine the key architecture components and interactions for authentication, authorization, and user provisioning. Finally, we review guidelines for product-specific integration, and sequence diagrams for common access patterns. This chapter is organized into the following sections: Operational modeling guidelines Design principles User provisioning guidelines Single sign-on authentication guidelines Authorization guidelines Product-specific integration guidelines Sequence diagrams for common access patterns
15
2.1 Operational modeling guidelines

This section includes guidelines for operational modeling, which are used to define the network, systems, middleware, and applications for the solution architecture. This section includes the following topics: Operational model overview Topology zones Runtime environment topology selection Development environment topology selection
2.1.1 Operational model overview

In todays e-business environment, most companies regardless of size know that access to the Internet and intranet is essential in order to compete in the global marketplace. While the benefits of being connected are significant, so are the risks. Connecting a private network to the Internet gives employees and business partners access to information, but also supplies a pathway for external users to access a companys private information. Frequent stories in the media regarding intruders gaining access to information via the Internet illustrate the need to implement network and application security. The operational model represents a network of computer systems, their associated peripherals, and the systems software, middleware, and application software that they run. In general, the operational model includes the following: One or more diagrams that show the topology and geographic distribution of the system, the node definitions, and network connections, as well as how users and external systems interact. A description of each node. A mapping matrix of deployment units to nodes. Each deployment unit is a convenient grouping of components from the software architecture. A description of the system management strategy. A description of middleware services and products and the key middleware choices. Descriptions of walkthroughs, which describe the flow of a business activity from a user all the way through the system and back to the user.
16
Depending on the stage of analysis and design, the nodes and connections may be conceptual, specified, or actual physical computer systems:
Conceptual corresponds to an early stage of design. Conceptual nodes

ignore many technological limitations and focus on application software components, deferring treatment of middleware and other software.
Specified refers to a detailed specification of a computer platform or network. Technological limitations are fully taken into account, but the detailed choice of technology is not made. Physical refers to the specific types of computers, networks, and software
that make up the system. Generally an operational model develops from conceptual, and specified to physical. Depending on the complexity of the problem and the starting point, it may not be necessary to go through all three stages. At any one time, different parts of the description may be at different levels. The operational model is the main description of the systems architecture. Without an operational model, or something very similar, it is hard to see how a systems architecture of any complexity can be designed and developed. The most obvious consequence is that some non-functional requirements will not be met, and this will not be realized until late in the project.
2.1.2 Topology zones

A good starting point is to construct a set of guiding principles to help develop the necessary infrastructure. In the past, networks evolved, meaning that as the need for a service or access to an application became necessary, the network grew to accommodate the requests. There was no unique beginning or endpoint. Network architectures now require the input of security specialists, application developers, and network professionals. All of these individuals affect the process of the flow of data and clients on the network. Each individual brings the necessary information for assembling building blocks where the logical and physical design needs and expectations are, giving a clearer representation of the enterprise. Building an architectural model that represents key components and the connections or interfaces between components allows for a visual picture of the business needs. Looking at the enterprise in this manner gives you the opportunity to visualize the relationships among your basic systems. It should also enable you to drill down into each component for the visualization of additional relationships.
Chapter 2. Architecture and design guidelines
17
A global vision suggests that the enterprise is more than its physical boundaries. But localizing that perspective reduces the complexity of trying to install, implement, and manage a security solution. To achieve this, you can base the solution on an integrated, standards-based architecture. An open and adaptable architecture helps minimize unseen flaws that can compromise the entire infrastructure and reduce the availability of applications and information.
Add security design objectives to architecture

Adding security design objectives into your architecture creates a framework to organize and validate the business environment and security risks. The immediate benefit is saved time and lower costs to reach the outcome. However, using a tried methodology gives a better-quality result with a quantitative tracking method. Security design objectives should outline how to achieve the following: Deploy and manage trusted credentials. Control access to stored information consistent with roles, responsibilities, and privacy policies. Control access and use of systems and processes consistent with roles and responsibilities. Protect stored or in transit information consistent with its classification, control, and flow policies. Assure the correct and reliable operation of components and services. Defend against attacks. Defend against fraud. The IBM Method for Architecting Secure Solutions (MASS) provides design objectives or, more simply put, a starting point. MASS includes the Common Criteria, which is compliant with international standards that are comprehensive and well accepted. MASS provides a set of security domains to help define the threats to an enterprise (including actors/users, flow control, authorization, physical security, and so on). It enables you to assign information assets to your security domains that become crucial in the high-level design of the architecture.
Domain zone categories

The client utilizes the network to access applications and data. This client can be from either within your enterprise or outside of it. Using the concept of security domains seen in Figure 2-1, you can translate into something more targeted.
18
Outside Zone
Demilitarized Zone
Production Zone
Internal Network
Restricted Protocol Firewall Domain Firewall Domain Firewall
Uncontrolled
Controlled
Domain Firewall
Controlled
Secured
Management Zone
Figure 2-1 Domain zone categories
Let us briefly explain what these domain categories stand for: Uncontrolled: Refers to anything outside the control of an organization. Access from the uncontrolled environment to systems in the controlled zone could be via a wide number of channels. Controlled: Restricts access between uncontrolled and restricted (a traditional DMZ). Restricted: Access is restricted and controlled. Only authorized individuals gain entrance and there is no direct communication with external sources (Internet). Secured: Access is available only to a small group of highly trusted users. Access to one secured area does not necessarily give access to another. External Controlled: An external zone in which data is stored by business partners external to the systems where there is limited trust in the protection of data (for example, credit reporting agencies, banks, and government agencies). Constructing your environment in this manner enables internal users to see out, but external users can not see in. The benefits of constructing security domains this way are: They are clear and efficient. They are easy to explain.
19
They provide a complete design and implementation view, enabling you to avoid errors. Fewer errors mean a lower risk of exposure and loss. There is a consistent use of recognized standards (common criteria, IBM Architecture Description Standard). MASS uses the common criteria definition of risk management as a framework, identifying four key steps in risk management: Identification of vulnerabilities Identification of threats or threat agents Determination of the risk imposed Identification of available counter measures Security risk management plays a big part in designing a secure solution, but so does security assurance. If we define the risks to the system, we must also assure that we counter measure those risks providing assurance for the correctness and effectiveness of the security solution. You will see these domain designs throughout the book.
Network zones
We have to consider four types of network zones and their transport classifications in our discussion: Internet (uncontrolled zone) Internet DMZ (controlled zone) Production zone (restricted zone) Intranet (controlled zone)
Internet (uncontrolled zone)

The Internet is a global network (a network of networks) connecting millions of computers. It cannot be controlled and should not have any components in it.
Internet DMZ (controlled zone)

The Internet DMZ is generally a controlled zone that contains components with which clients may directly communicate. It provides a buffer between the uncontrolled Internet and internal networks. Because this DMZ is typically bounded by two firewalls, there is an opportunity to control traffic at multiple levels: Incoming traffic from the Internet to hosts in the DMZ Outgoing traffic from hosts in the DMZ to the Internet Incoming traffic from internal networks to hosts in the DMZ Outgoing traffic from hosts in the DMZ to internal networks
20
The transport between a controlled and an uncontrolled zone is classified as public. The transport between a controlled and another controlled or a restricted zone is classified as managed.
Production zone (restricted zone)

One or more network zones may be designated as restricted, that is, they support functions to which access must be strictly controlled and, of course, direct access from an uncontrolled network should not be permitted. As with an Internet DMZ, a restricted network is typically bounded by one or more firewalls, and incoming/outgoing traffic may be filtered as appropriate. The transport between a restricted and a controlled zone is classified as
managed. The transport between a restricted and a secured zone is classified as trusted. Intranet (controlled zone)
Like the Internet DMZ, the corporate intranet is generally a controlled zone that contains components with which clients may directly communicate. It provides a buffer to the internal networks.
Management zone (secured zone)

One or more network zones may be designated as a secured zone. Access is only available to a small group of authorized staff. Access into one area does not necessarily give you access to another secured area. The transport into a secured zone is classified as trusted.
Other networks
Keep in mind that the network examples we use do not necessarily include all possible situations. There are organizations that extensively segment functions into various networks. However, in general, the principles discussed here may be translated easily into appropriate architectures for such environments. Placement of various data components within network zones is both a reflection of the security requirements in play and a choice based on an existing or planned network infrastructure and levels of trust among the computing components within the organization. Requirement issues often may be complex, especially with regard to the specific behavior of certain applications. With a bit of knowledge about the organizations network environment and its security policies, reasonable component placements are usually easy to identify.
21
e-business security requirement and MASS

The IBM e-business methodology fits nicely with MASS domain concepts. MASS is built on open and accepted standards. e-business patterns originate in IBM product divisions and are provided as operational models that are also based on open standards and technologies. Notice that the principles of the Six As of e-business factor nicely into the overall plan as well: Authorization: Allow only users who are approved to access systems, data, application, and networks (public and private). Asset protection: Keep data confidential by ensuring that privacy rules are enforced. Accountability: Identify who did what, when. Assurance: Have the ability to confirm and validate the enforcement of security. Availability: Keep systems, data, networks, and applications reachable. Administration: Define, maintain, monitor, and modify policy information consistently. In order for your network security solution to work, it must be based on consistent, corporate-wide policies. A successful deployment requires that an effective link be forged from the management definition of policy to the operational implementation of that policy. Tip: Plan your security polices around your business model, not the other way around.
2.1.3 Application architecture components

The application architecture components, or layers, involved in the operating model are illustrated in Figure 2-2.
22
Client Tier
Browser Edge of Network Authentication proxy Load balancer
Network Tier
Application Server
Portal Tier
Portal server Presentation Services Connectivity Services Personalization Services
Directory and Security Services
Web server
Security Tier
Portal Services Tier
Document Management
Data Tier
Content
Portal Data
User Directory
Figure 2-2 Architecture logical components
The layers shown in Figure 2-2 are described as follows: Client layer: Internet Web browsers translate client requests. Network layer: The edge of network consists of the load balancing, caching and security processing that takes place in a demilitarized zone (DMZ) between a protocol firewall (separating the uncontrolled Internet from the DMZ) and a domain firewall (separating the DMZ from the trusted internal network (intranet). Portal layer: Contains the application server(s) hosting the portal application. Security layer: Enforces authentication, authorization, security policies, and identity management. Portal services layer: Content and services consumed by the portal application. Data layer: Data storage accessed by the portal and portal services applications.
23
2.1.4 Product mapping

For this redbook, the identity and access management system will use the following product mapping in each architectural layer: Client layer: Browser: Microsoft Internet Explorer V6 Network layer: Load balancer: IBM WebSphere Application Server Network Deployment V5.1 Load Balancer Edge component Reverse proxy: IBM Tivoli Access Manager V5.1 for e-business (WebSEAL component) Portal layer: Web server: IBM HTTP Server V1.3.28 Application server: IBM WebSphere Application Server V5.1 Cluster manager: IBM WebSphere Application Server Network Deployment V5.1 Portal server: IBM WebSphere Portal V5.1 Security layer: User repository: IBM Tivoli Directory Server V5.2 Policy Manager: IBM Tivoli Access Manager V5.1 for e-business Identity Manager: IBM Tivoli Identity Manager V4.5.1 Directory Integrator: IBM Tivoli Directory Integrator V6.0
Portal services layer: IBM DB2 Content Manager V8.3, Enterprise Edition IBM DB2 Information Integrator for Content V8.3 Data layer: Database server: IBM DB2 Universal Database, V8.2 Enterprise Server
2.1.5 Runtime environment topology selection

In this section we examine the following runtime topologies for an identity and access management system using Tivoli Identity Manager, Tivoli Access Manager, Tivoli Directory Integrator, Tivoli Directory Server, and WebSphere Portal: Entry runtime topology Enterprise runtime topology Extended enterprise runtime topology Extended enterprise high availability runtime topology
24
Note: We have included DB2 Content Manager as a back-end system for two reasons. First, the placement and interaction of DB2 Content Manager within the identity and access management system is representative of other back-end systems. Second, Part 2, ITSO identity and access management working example on page 95, includes DB2 Content Manager. We considered the following architecture issues for each of the runtime topologies: Complexity Security Scalability High availability Placement of nodes within network zones
Entry runtime topology

Figure 2-3 depicts an entry runtime topology. This type of topology is appropriate for test purposes, prototypes, and in some instances an SMB type customer environment. Within the IBM software portfolio, many of the products include an Express Edition, which is targeted at SMB customers. Typically, the licensing for the Express Edition products state that the software can only allow the software components to be installed on a standalone node. For the ITSO identity and access management system working example, we chose the entry runtime topology. We selected this topology because it allows us to demonstrate how to address the key configuration issues with components installed on separate nodes, without having too many nodes required for the topology.
25
Outside zone
Demilitarized zone
Production zone
WebSphere Portal 5.1
WebSphere Application Server 5.1.1 IBM HTTP Server 1.3.28 DB2 UDB 8.2 + FP8 DB2 Information Integrator for Content 8.3 (CM connectors) Tivoli Identity Manager 4.5.1 + FP42 (API jars) Windows 2000 Server + SP4
Client
I N T E R N E T
Tivoli Access Manager 5.1 + FP9 (Runtime, PDJRTE, Web Security, WebSEAL) Tivoli Directory Client 5.2 + FP2 IBM GSKit 7.0.3.8 IBM JRE 1.3.1 Windows 2000 Server + SP4
Content Management
DB2 Content Manager 8.3 (Library Server, Resource Manager, System Admin Client) DB2 Content Manager Client for Windows 8.3 WebSphere Application Server 5.1.1 IBM HTTP Server 1.3.28 DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Figure 2-3 ITSO runtime environment and product mapping
The premises for the entry runtime topology and potential benefits are as follows: Installation: Closely matches default install process. Single node implementations are the automated default installations for Tivoli Identity Manager, Tivoli Directory Server, Tivoli Access Manager, Tivoli Directory Integrator, WebSphere Portal, and DB2 Content Manager. Maintenance: Default configuration easier to administer. Cost: Reduced hardware requirements Non-mission critical: Primarily for development or test environments (can be used as an SMB environment). Security: Isolation and centralized security. There is an explicit layer of isolation between the outside zone and the WebSphere Portal node by using the Tivoli Access Manager WebSEAL in the DMZ on the Reverse Proxy node. In addition, this topology includes a centralized model using Tivoli Access Manager for authentication and authorization, Tivoli Identity Manager for identity management, and Tivoli Directory Server for a common LDAP user directory.
Protocol Firewall
Domain Firewall
Reverse Proxy
Portal Server
Directory
Tivoli Directory Server 5.2 + FP2 (Server, Client, Web Admin) Tivoli Directory Integrator 6.0 + FP1 IBM HTTP Server 1.3.26.2 WebSphere Application Server 5.0.2 IBM GSKit 7.0.3.8 DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Access Manager
Tivoli Access Manager 5.1 + FP9 (Runtime, PDJRTE, Policy, Auth, Web Portal Mgr) Tivoli Identity Manager Agent 4.5.9 for TAM IBM HTTP Server 1.3.26.2 IBM WebSphere Application Server 5.0.2 IBM GSKit 7.0.3.8 IBM JRE 1.3.1 Windows 2000 Server + SP4
Identity Manager
Tivoli Identity Manager 4.5.1 + FP42 Tivoli Directory Server 5.2 + FP2 (Server, Client) DB2 UDB 8.2 ESE + FP8 IBM HTTP Server 1.3.28 IBM WebSphere Application Server 5.0.2 IBM GSKit 7.0.3.8 Windows 2000 Server + SP4
26
Considerations and potential impacts for this topology include: Performance: Resource competition on each node. Scalability: Not provided. Addition of Portal Server nodes or Content Manager nodes require implementation rework for WebSphere Portal and Content Manager respectively. Availability: Single points of failure. Many of the nodes represent single points of failure in the delivery of the system.
Enterprise runtime topology

Figure 2-4 depicts the enterprise runtime topology. This type of topology is appropriate for an enterprise or SMB production environment seeking greater performance than what is provided by the entry runtime topology.
Outside zone
Demilitarized zone
Production zone
DB2 Content Manager 8.3 (Library

Server, System Admin Client) Windows 2000 Server + SP4
Protocol Firewall
Domain Firewall
Client
I N T E R N E T
Library Server
Resource Manager
DB2 Content Manager 8.3
(Resource Manager) DB2 Content Manager Client 8.3 WebSphere Application Server 5.1.1 IBM HTTP Server 1.3.28 DB2 UDB V8.2 ESE + FP8 Windows 2000 Svr + SP4
Database Server Portal Server

DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Reverse Proxy
Directory
Access Manager
Identity Manager
Directory
Tivoli Identity Manager 4.5.1 + FP42 DB2 UDB 8.2 ESE + FP8 IBM HTTP Server 1.3.28 IBM WebSphere Application Server 5.0.2 IBM GSKit 7.0.3.8 Windows 2000 Server + SP4
Figure 2-4 Enterprise runtime topology
27
The enterprise runtime topology contains the following additional nodes when compared to the entry runtime topology: Directory node for the Identity Manager node. Separate Database Server node shared by applications and middleware. Separation of the Content Manager components into a Library Server and Resource Manager nodes. Premises for and potential benefits of the enterprise runtime topology include: Performance: Separate nodes for DB2 Content Manager Library Server and Resource manager, with the potential for multiple Resource Manager nodes, provides better performance. In addition, this topology includes a separate Database Server for applications and a separate Directory node for Tivoli Identity Manager to improve performance. Considerations and potential impacts for this topology include: Availability: Single points of failure. No failover provided for Library Server node or Directory node shared by applications. Complexity: More nodes to configure. The configuration increases implementation and maintenance effort. Cost: Additional hardware. Additional nodes incur additional hardware, software, configuration and support costs.
Extended enterprise runtime topology

Figure 2-5 depicts the extended enterprise runtime topology. This type of topology is appropriate for an enterprise production environment seeking greater scalability and performance than what is provided by the enterprise runtime topology.
28
Outside zone
Demilitarized zone
Production zone

Server, System Admin Client) Windows 2000 Server + SP4
Protocol Firewall
Domain Firewall
Client
Library Server
Resource Manager
DB2 Content Manager 8.3
(Resource Manager) DB2 Content Manager Client 8.3 WebSphere Application Server 5.1.1 IBM HTTP Server 1.3.28 DB2 UDB V8.2 ESE + FP8 Windows 2000 Svr + SP4
I N T E R N E T
Reverse Proxy Load Balancer
Database Server Portal Server

DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Directory
Reverse Proxy
IBM WebSphere Application Server 5.1 Network Deployment (Edge Components) Windows 2000 Server + SP4
Access Manager
Identity Manager
Directory
Tivoli Identity Manager 4.5.1 + FP42 DB2 UDB 8.2 ESE + FP8 IBM HTTP Server 1.3.28 IBM WebSphere Application Server 5.0.2 IBM GSKit 7.0.3.8 Windows 2000 Server + SP4
Figure 2-5 Extended enterprise runtime topology
The extended enterprise runtime topology contains the following additional nodes when compared to the enterprise runtime topology: Load Balancer node Clustered Reverse Proxy nodes Clustered Portal Server nodes Premises for and potential benefits of the enterprise runtime topology include: Security: Isolation of applications. Load Balancer node and Reverse Proxy nodes provide security separation (for example, DMZ, firewalls) from the Production zone applications. Performance: Load balancing of Reverse Proxy and Portal Server nodes improves performance.
29
Scalability: Caters for multiple application nodes. The Reverse Proxy nodes are load balanced to achieve great scalability. The Portal Server nodes are part of a cluster for increased scalability and performance. Considerations and potential impacts for this topology include: Availability: Single points of failure. No failover provided for Load Balancer node, Library Server node, or Directory Server node. Complexity: Clustering. WebSphere Portal clustering and Load Balancer configuration substantially increases implementation and maintenance effort. Cost: Additional hardware. Additional nodes incur additional hardware, software, configuration and support costs.
Extended enterprise high availability runtime topology

The extended enterprise high availability runtime topology adds the following nodes when compared to the extended enterprise runtime topology: Load Balancer node failover Directory Server node failover OS clustering for Library Server node and Resource Manager nodes Premises for and potential benefits of this topology include: Availability: Delivery channel redundancy. Failover provided for Load Balancer node and Directory Server node. OS Clustering for Library Server node and Resource Manager nodes. Application clustering for Portal Server node and multiple Web Server Redirector nodes. Considerations and potential impacts for this topology include: Complexity: Clustering and failover. High availability configuration substantially increases implementation and maintenance effort. Cost: Additional hardware. Redundant nodes incur additional hardware, software, configuration, and support costs without increasing service performance.
2.1.6 Development environment topology selection

Depending on the size of the project development team, the development functions may be split across several different roles. This section outlines four types of applications to be developed and run within an identity and access management system. In addition, we highlight the development topologies required to develop the applications defined.
30
Application considerations
For illustration purposes, consider a scenario in which the following four types of applications need to be developed: User provisioning portlet application. The provisioning portlet application has a portlet based front-end and uses Tivoli Identity Manager APIs to interact with Tivoli Identity Manager. Through the use of Tivoli Identity Manager workflows and policies, and Tivoli Directory Integrator Assembly Lines and connectors, users are then provisioned to multiple system types. This includes systems such as Tivoli Directory Server and DB2 Content Manager. The applications share LDAP user registry. HR application (portlet front-end, EJB back-end). The HR application has a portlet based front-end and EJB back-end. The application uses an LDAP user registry. Document management application. The document management application has a custom portlet front-end and uses DB2 Information Integrator for Content to access DB2 Content Manager for the back-end repository. The back-end DB2 Content Manager application includes a custom item type, attributes, and workflow used for approvals by users of the system (researcher, supervisor, legal, etc.). The application uses an LDAP user registry. Identity Manager policies/workflow and TDI Assembly Lines/connectors. Once users are created using the provisioning portlets, the Identity Manager workflow and policies can be used to provision the users. This requires that Tivoli Identity Manager be set up. Once the provisioning request is approved within Tivoli Identity Manager, policies are used to invoke Tivoli Directory Integrator Assembly Lines via event handlers. To develop TDI Assembly Lines and custom connectors, you will need to have a node with Tivoli Directory Integrator set up. In addition to the types of applications, there are some product specific development considerations: WebSphere Portal V5.1 Test Environment local versus remote. The WebSphere Portal V5.1 Test Environment can be installed either locally as an integrated Rational Application Developer test environment, or as a standalone installation of WebSphere Portal on a separate node (or same node not integrated with Rational Application Developer). This is determined at the time that WebSphere Portal V5.1 is installed. When installing the Portal Test Environment locally, the advantage is that the portlets can be developed, tested, and debugged within Rational Application Developer without the need to package and deploy a WAR file. The
31
disadvantage of using the local integrated test environment is that the environment does not behave exactly as a full installation for WebSphere Portal. For example, the page and portlet settings configured in the WebSphere Portal Administration portlets, are reset after restarting the server within Rational Application Developer. The advantage of using the full WebSphere Portal on a separate node is that the application will be deployed and run the same way on a production system (it is a production-like configuration). The disadvantage is that you have to package and deploy WAR files, which makes developing the application more time consuming. Tivoli Directory Integrator. When developing Tivoli Directory Integrator assembly lines and using existing or developing custom connectors, you will likely need a full test environment in order to fully test the functionality of the provisioning. The following sections present several development environment topologies that can be used to develop and test the applications, depending on your development team structure (segmented by application type or jack of all trades).
Development topology 1: User provisioning portlet

Development topology 1 provides the capability to develop and test the provisioning portlet application. Figure 2-6 depicts a two node topology where the Identity Manager node is separate from the Development node. In this example, we used the WebSphere Portal V5.1 Test Environment within Rational Application Developer. We recommend using separate nodes for several reasons. First, using two nodes allows for distributed load and better performance during development. For example, our Identity Manager node had 1 GB of RAM and the Development node had 2 GB of RAM. Second, the Identity Manager node includes a WebSphere Application Server V5.0.2 used by the Tivoli Directory Server Administration Tool, which may have conflicting ports with the WebSphere Application Server V5.1.1 that the WebSphere Portal V5.1 Test Environment of Rational Application Developer uses. Third, it is also possible that the Identity Management node could be more easily shared with other developers. This type of development environment will allow you to develop and test the portlets ability to create users within Tivoli Identity Manager.
32
Note: Once the provisioning portlet has created the user in Tivoli Identity Manager using the APIs, user provisioning to multiple systems can be invoked using the Tivoli Identity Manager workflow and policies. If you desire to test the user provisioning to multiple systems, you will need a full test environment as described in Development topology 6: Develop and test end-to-end on page 37. If your development system has plenty of memory, you might consider using the VMWare Workstation image for the Identity Manager node.
Development
Identity Manager
Rational Application Developer V6.0.0.1 (IDE, Portal Tools, Portal 5.1 Test Env) Tivoli Identity Manager V4.5.1 + FP42 (connector jar - APIs) HR application WAR (portlets) and EAR (servlets, EJBs) deployed and running Windows XP + SP1
Tivoli Identity Manager 4.5.1 + FP42 Tivoli Directory Server 5.2 + FP2 (Server, Client) IBM GSKit 7.0.3.8 DB2 UDB 8.2 ESE + FP8 IBM HTTP Server 1.3.28 IBM WebSphere Application Server 5.1 Windows 2000 Server + SP4
Figure 2-6 Development topology 1: Provisioning portlet
Note: For the ITSO working example, the HR application WAR (portlets) and EAR (servlets, EJBs) need to be deployed and running so that the user provisioning portlets can access a portlet service which uses HR application EJBs to access the HR database.
33
Development topology 2: HR application

Development topology 2 provides the capability to develop and test the HR application. Figure 2-7 depicts a two node topology where the Directory Server (optional) is separate from the Development node. Both the portal front-end and EJBs can be developed and tested in the Portal V5.1 Test Environment, since it includes IBM WebSphere Application Server V5.1. Development topology 1: User provisioning portlet on page 32 can be used to develop the HR application, since it includes a superset of the software needed. Note: The HR application is used primarily to demonstrate the ability to provision users to multiple systems. This redbook does not describe how the application was developed; however, Figure 2-7 does highlight the necessary development environment required to develop this type of application. For more information on the HR application, refer Appendix A, HR application on page 525.
Development
Directory
Rational Application Developer V6.0.0.1 (IDE, Portal Tools, Portal 5.1 Test Env) DB2 UDB V8.2 ESE + FP8 Windows XP + SP1
Tivoli Directory Server V5.2 + FP2 (Server, Client SDK, Web Admin) WebSphere Application Server V5.0.2 IBM HTTP Server V1.3.26 DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Figure 2-7 Development topology 2: HR application
34
Development topology 3: Document management

Development topology 3 provides the capability to develop and test a custom document management application. Figure 2-8 depicts a two node topology with a Development node and Content Management node. Note: The ITSO custom document management application is used primarily to demonstrate the ability to provision users to multiple systems. This redbook does not describe how the application was developed; however, Figure 2-8 on page 35 highlights the necessary development environment required to develop this type of application. For more information on the custom document management application, refer to Appendix B, Document management application on page 549.
Development
Content Management
Rational Application Developer V6.0.0.1 (IDE, Portal Tools, Portal 5.1 Test Env) DB2 Information Integrator for Content V8.3 (CM connector) DB2 UDB V8.3 Client + FP8 Windows XP + SP1
DB2 Content Manager V8.3 (Library Server, Resource Manager, Sys Admin) WebSphere Application Server V5.1.1 IBM HTTP Server 1.3.28 Tivoli Directory Server V6.0 (Server, Client SDK) DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Figure 2-8 Development topology 3: Document management application
35
Development topology 4: Develop all Web applications

Development topology 4 provides the capability to develop and test the provisioning portlets, HR and custom document management applications. Figure 2-9 depicts a three node topology with a Development node, Identity Management node, and Content Management node.
Tivoli Identity Manager 4.5.1 + FP42 Tivoli Directory Server 5.2 + FP2 (Server, Client) DB2 UDB 8.2 ESE + FP8 IBM HTTP Server 1.3.28 IBM WebSphere Application Server 5.1 IBM GSKit 7.0.3.8 HR application WAR (portlets) and EAR (servlets, EJBs) deployed and running Windows 2000 Server + SP4
Identity Manager
Development
Content Management
Rational Application Developer V6.0.0.1 (IDE, Portal Tools, Portal 5.1 Test Env) DB2 Information Integrator for Content V8.3 (CM connector) Tivoli Identity Manager V4.5.1 + FP42 (connector jars - API)I DB2 UDB V8.2 ESE + FP8 HR application WAR (portlets) and EAR (servlets, EJBs) deployed and running Windows 2000 Professional + SP4
DB2 Content Manager 8.3 (Library Server, Resource Manager, System Admin Client) WebSphere Application Server 5.1.1 IBM HTTP Server 1.3.28 DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Figure 2-9 Development topology 4: Develop all Web applications
There are a few key points to make regarding Development topology 4 as depicted in Figure 2-9. First, although the full runtime environment does provide for integration of the Identity Management node DB2 Content Manager via Tivoli Directory Integrator, this capability does not exist in this development environment. Second, if you do desire full integration testing, you will need to implement a runtime topology such as the Entry runtime topology on page 25.
36
Development topology 5: Develop TDI ALs and connectors

In order to develop and test the TDI Assembly Lines and custom connectors for the ITSO scenario, you will need an environment that includes the Directory node, Identity Manager node, Content Management node, and HR database deployed on a node where DB2 Universal Database is installed. Figure 2-10 depicts development topology 5.
Identity Manager
Content Management
Server, Resource Manager, System Admin Client) WebSphere Application Server 5.1.1 IBM HTTP Server 1.3.28 DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Tivoli Identity Manager 4.5.1 + FP42 Tivoli Directory Server 5.2 + FP2 (Server, Client) DB2 UDB 8.2 ESE + FP8 IBM HTTP Server 1.3.28 IBM WebSphere Application Server 5.1 IBM GSKit 7.0.3.8 HR application database Windows 2000 Server + SP4
Directory
Figure 2-10 Development topology 5: Develop TDI ALs and custom connectors
Development topology 6: Develop and test end-to-end

Development topology 6 provides the capability to develop and test the provisioning portlets, HR, and custom document management applications as seen in Development topology 4: Develop all Web applications on page 36, with the additional capability to test the Tivoli Identity Manager policies and workflows, as well as end-to-end integration testing.
2.2 Design principles

The design of any architecture must be based on clearly defined and articulated principles that form a foundation for the design process, that is, the principles describe the objectives of the solution. Whenever in doubt about a design decision, the principles should be used to map a path forward and to justify the overall design. The following principles apply to an identity and access management system: Centralized authority Access decision evaluated on demand Capture authentication events and logs
37
2.2.1 Centralized authority

The security solution should have a central point of authority for security-related information, and must support both centralized and distributed management. Motivation: This principle drives the need for one source of authoritative, security-related policy within an organization. It enables a consistent policy to be applied across applications, systems, and throughout the organization while providing a flexible administration framework that fits into and enhances an organizations operation capabilities for example, centralized authentication using Tivoli Access Manager and centralized user provisioning using Tivoli Identity Manager. Implications: This principle implies a high degree of integration, broad coverage, and flexibility required from the products that are chosen to support it. Integration is one of the greatest challenges.
2.2.2 Access decision evaluated on demand

Access decisions must be evaluated where and when they are required, not at the beginning of a transaction. Gated controls should be employed throughout the solution. Putting all controls at the front door puts too much emphasis on the concept of trust (that is, I have let you into my house and now you can do whatever you like), creating an inherently less secure system. Motivation: The drivers for this principle are increased security and performance: Increased security through more checks of a users or transactions authority to perform a function. Increased performance as decisions get made when a user requires something, meaning that unnecessary decisions about a users potential activity will not be made up front. Implications: Requires good integration capability to enable a common security service to permeate an environment. The majority of applications must be able to use the security services.
2.2.3 Capture authentication events and logs

Sufficient logging and/or audit trail is required to capture all authentication, access control decisions, and user provisioning events. The level of logging should be based on business and security requirements, hence the security solution should provide comprehensive and flexible logging coverage, allowing it to be customized.
38
Motivation: Because no security solution is foolproof, it is essential to keep good records of the transactions performed by the security system. An easily manageable method of dealing with these records is essential. Implications: Strong integration is required to provide logging across multiple systems. Mechanisms must be in place to collect, filter, analyze, and report on audit data. These principles are not intended to be comprehensive, but to highlight some core objectives of the identity and access management system.
2.3 User provisioning guidelines

Within the context of this redbook, user provisioning provides a method of creating and managing users from a central system to external systems. It is common for enterprise applications to share a common LDAP user registry. In some cases, older existing systems may require that users are provisioned to the those systems. The objective is to provision and manage users from a central system. Tivoli Identity Manager, Tivoli Directory Server, and Tivoli Directory Integrator are the primary software products used to provide the user with the provisioning solution found in this redbook. This section includes the following topics: Identity management overview Common LDAP directory Tivoli Identity Manager services, workflows, and policies Tivoli Directory Integrator assembly lines Tivoli Directory Integrator connectors Note: The ITSO identity and access management system working example includes a detailed solution for user provisioning to external systems. For more information, refer to User provisioning on page 122.
2.3.1 Identity management overview

Identity management is a comprehensive, process-oriented, and policy-driven security approach that helps organizations consolidate identity data and automate the deployment across the enterprise. In order to effectively compete in todays business environment, companies are increasing the number of users (customers, employees, partners, and suppliers) who are allowed to access information. As IT is challenged to do more with fewer
39
resources, managing user identities and their access to resources throughout the identity life cycle is even more difficult. Typical IT environments have many local administrators using manual processes to implement user changes across multiple systems and applications. As identity management grows more costly, it can inhibit the development and deployment of new business initiatives. An integrated identity management solution can help get users, systems, and applications online and productive fast, and maintain dynamic compliance to increase the resiliency and security of the IT environment, while helping to reduce costs and maximize return on investment. An identity management solution has four key areas: Identity lifecycle management (user self-care, enrollment, and provisioning) Identity control (access and privacy control, single sign-on, and auditing) Identity federation (sharing user authentication and attribute information among trusted Web services applications) Identity foundation (directory, directory integration, and workflow) As the world of e-business gains global acceptance, the traditional processes of corporate user administration are no longer able to cope with the demands of increased scale and scope expected from them. Identity management is a superset of older user provisioning systems that allows for the management of identity and credential information for customers, partners, suppliers, automated processes, corporate users, and others. As organizations come to depend on their IT assets more, these assets attract the attention of accounting and reporting standards. IT data and system assets will increasingly become balance sheet line items, and therefore be subject to different audit and compliance rules. Organizations must be able to demonstrate due care, due diligence, improved security, and compliance with other financial rules. We should realize that any entity using the IT systems run by an organization must be included in the scope of identity management if we are to have any chance of achieving these goals. For more information on identity management, refer to the following redbooks: Identity Management Design Guide with Tivoli Access Manager, SG24-6996 Enterprise Security Architecture Using IBM Tivoli Security Solutions, SG24-6014
40
2.3.2 Common LDAP directory

In a perfect world, all applications and systems can share a common LDAP directory. When using a common directory, the administration of user accounts can be centralized using a common LDAP directory. Within a typical enterprise environment, legacy systems often require that users are managed within the system or application. In some cases, users need to be created in both the legacy system and an LDAP directory. For this reason, there is a need for a centralized system that users can be provisioned to multiple systems. For example, when integrating WebSphere Portal and DB2 Content Manager, both products can be configured to use a common LDAP directory.
2.3.3 Tivoli Identity Manager services, workflows, and policies

Within the IBM middleware software portfolio, Tivoli Identity Manager is the primary software used to centrally manage the identity of users across systems. When using Tivoli Identity Manager, users are first created in Tivoli Identity Manager, and then provisioned to external systems. There are a couple of scenarios in which Tivoli Identity Manager is used. In this redbook we cover the following methods Tivoli Identity Manager can used to provision users: Tivoli Identity Manager Agents: Tivoli Identity Manager provides many agents that can be used out-of-the-box to provision users. For example, the Tivoli Identity Manager Agent for Tivoli Access Manager can be used to provision users from Tivoli Identity Manager to Tivoli Access Manager. Tivoli Identity Manager + TDI assembly lines and connectors: Tivoli Identity Manager can be customized to create services, organizational units and roles, create policies and workflows. In addition, Tivoli Directory Integrator assembly lines and connectors are used to provision users to the external systems. In some cases Tivoli Directory Integrator connectors exist out of the box, and in other cases the connector will need to be customized or created using the TDI and external application APIs. The ITSO identity and access management system working example includes both scenarios. The following sections describe common Tivoli Identity Manager components and configuration tasks: Tivoli Identity Manager service Tivoli Identity Manager Organizational Units and Persons
41
Organizational Roles Modify user interface Password policy Create workflows Provisioning policies
Tivoli Identity Manager service

A Tivoli Identity Manager service is the interface used to communicate with a managed resource, such as an LDAP server. A service profile consists of a set of files that describe the Tivoli Identity Manager service and the accounts managed by that service. Note: For details, refer to 9.1, Create Identity Manager Services on page 412. The configuration of a Tivoli Identity Manager service can be achieved by completing the following tasks: Add the service to be available in Tivoli Identity Manager. For each target system that will require a custom created service within Tivoli Identity Manager, you need to add the service to Tivoli Identity Manager so that it can be accessed and customized from the Tivoli Identity Manager Web interface. This task is performed by copying the sample services files to a directory on the node where Tivoli Identity Manager is installed, and executing the config_remote_services command from the command line to add the service to be available from the Tivoli Identity Manager. In the ITSO working example, we added services to Tivoli Identity Manager for LDAP (dsml2ldapservice), DB2 UDB (dsml2db2service), and DB2 Content Manager (dsml2CMservice). Create the service profile in the Tivoli Identity Manager Web interface. The service defines what parameters are required when creating the service profile. Tivoli Identity Manager contains the necessary details to communicate with the Tivoli Identity Manager agent or external system using a custom configuration. The service profiles are created from the Tivoli Identity Manager Web interface based on the services that have been installed. Modify the service. In some cases it may be necessary to modify the configuration of a service profile. For example, after creating the CM, DB2 and LDAP Services for the ITSO working example, we needed to modify the Policy Enforcement by selecting Correct Noncompliance and then submitted the update.
42
For detailed information on creating Tivoli Identity Manager Services, refer to 9.1, Create Identity Manager Services on page 412.
Tivoli Identity Manager Organizational Units and Persons

Defining the Organizational Unit, Persons, and organizational structure are key elements of the Tivoli Identity Manager configuration. This type of configuration will be unique for the requirements of the customer. Each of the following configuration tasks can be performed from the Tivoli Identity Manager Web interface under My organization: Create Organizational Units Create Persons Create organizational structure When complete, the organization structure should look like Figure 2-11, where DEV01 and HRD01 are Organizational Units.
Figure 2-11 ITSO organization structure
For detailed information on creating an Organizational Unit, Person, and organizational structure, refer to 9.2, Create Organizational Units and Persons on page 415.
43
Organizational Roles
Organizational Roles often represent each group created within the LDAP directory or other system. Once the Organizational Roles are created within Tivoli Identity Manager, the Persons are granted these roles. It is common for the Organizational Roles defined in Tivoli Identity Manager to be later mapped to roles in other systems such as WebSphere Portal or DB2 Content Manager. For detailed information on defining Organization Roles, refer to 9.3, Create and Grant Organizational Roles on page 419.
Modify user interface

Tivoli Identity Manager administrators can customize the user interface to add and remove fields from forms displayed. For example, the ITSO working example describes how to modify the Tivoli Identity Manager user interface to add additional fields to the Person form. For detailed information on modifying the Tivoli Identity Manager user interface, refer to 9.4, Modify the user interface on page 421.
Password policy
The password policy in Tivoli Identity Manager contains the rules to enforce strong password construction. A new password policy can be defined from the Tivoli Identity Manager Web interface. For example, Figure 2-12 displays rules that can be defined for a password policy. For detailed information on defining a password policy, refer to 9.5, Create the Password Policy on page 425.
44
Figure 2-12 Password Policy
Create workflows
Within Tivoli Identity Manager, it is possible to customize the default operational workflows for a specific set of scenarios by modifying the JavaScript used by the workflow. For example, for the ITSO working example we modified the selfRegister workflow. Figure 2-13 displays the modified selfRegistration workflow.
45
Figure 2-13 Design of selfRegistration Workflow
For detailed information on creating workflows, refer to 9.6, Create Workflows on page 426.
Provisioning policies
Provisioning policies are used within Tivoli Identity Manager to manage user accounts. The provisioning policies can in turn be configured to initiate the creation and management of user accounts in external systems. When configuring policies, services and workflows are defined. In addition, JavaScript is used to defined the policy, and attributes are mapped from the Tivoli Identity Manager interface to the target system the user will be provisioned. For the ITSO working example, we discuss three provisioning policy types: Default provisioning policy: In this case, we modify the JavaScript for the Default provisioning policy for ITIM. Provisioning policies which interact with Tivoli Identity Manager Agents: In this example, we define the provisioning policy to interact with the Tivoli Identity Manager Agent for Tivoli Access Manager to create, delete and update users in Tivoli Access Manager. Provisioning policies that interact with Tivoli Directory Integrator assembly lines and connectors to create, delete, and update users in the target system: In this case, we create a provisioning policy for LDAP, DB2 UDB, and DB2 Content Manager to interact with Tivoli Directory Integrator assembly lines and connectors to create and manager users in the external systems.
46
For detailed information on creating provisioning policies, refer to 9.7, Create Identity Manager Provisioning Policies on page 434.
2.3.4 Tivoli Directory Integrator assembly lines

A Tivoli Directory Integrator Config describes a set of components that are linked together to form an integration solution. With the use of a Config, entities such as user accounts can form the basis of integration across systems by mapping the entity attributes that each system understands. For example, in the ITSO identity and access management system, users will be provisioned from Tivoli Identity Manager through Tivoli Directory Integrator to the HR DB2 UDB database, employee LDAP directory, and DB2 Content Manager user repository. The assembly lines are created by using the Tivoli Directory Integrator Configuration Editor. When provisioning a user, three common operations are needed, including add, update, and delete users. From the Config Editor, the following configuration tasks are performed to develop an assembly line: Create a new Config: This task creates a new XML configuration file used to store the settings of the assembly line. Add the assembly lines: In this task, the assembly line name is defined, attributes are mapped from what is passed in to that of the target system, and a component is added to define the connector to take action. For example, the cmAdd assembly line is defined for DB2 Content Manager, the attributes are mapped from what are passed in from Tivoli Identity Manager to that of the target DB2 Content Manager item type attributes, and the com.ibm.itso.connector.CMConnector component is defined to carry out the programmatic task of provisioning the user. For detailed information on creating assembly lines, refer to Chapter 8, TDI Assembly Line development on page 373.
2.3.5 Tivoli Directory Integrator connectors

In some cases, Tivoli Directory Integrator provides connectors out-of-the-box to provision users to the target system. In other cases, Tivoli Directory Integrator and target system APIs.
47
In the ITSO working example, we used the out-of-the-box Tivoli Directory Integrator connectors for LDAP and DB2 UDB. In the case of DB2 Content Manager, a connector did not exist, so we created a custom connector using the Tivoli Directory Integrator and DB2 Information Integrator for Content APIs to provision a user to DB2 Content Manager. For detailed information on creating a custom Tivoli Directory Integrator connector, refer to Chapter 7, TDI connector for Content Manager development on page 363.
2.4 Single sign-on authentication guidelines

Authentication is the process whereby a clients identity is validated. The client may be an end user, another server, or an application, but must provide credentials acceptable to the requested resource prior to being granted access. In this section we briefly describe authentication mechanisms that are included with WebSphere Portal, Tivoli Access Manager, and DB2 Content Manager. In addition, we discuss integration alternatives for a shared user repository and single sign-on. Note: The ITSO identity and access management system working example includes an SSO authentication solution. For more information, refer to Authentication and authorization on page 120.
2.4.1 WebSphere Portal authentication

By default WebSphere Portal uses the Custom Form-based Authentication mechanism of WebSphere Application Server to prompt users for their identity. During authentication, a user is validated against a configured user registry. WebSphere Application Server and WebSphere Portal support three types of user registries: Lightweight Directory Access Protocol (LDAP) accessible directories. Custom User Registry interface, used to access non-LDAP user registries that are plugged in to WebSphere Application Server authentication. Third-party authentication using Trust Association Interceptors (TAIs). The third-party authentication provider determines the challenge mechanism and authentication method.
48
When using LDAP and custom registry configurations, WebSphere Portal shares the same authentication registry as the WebSphere Application Server. WebSphere Portal supports standard LDAP protocols to access: IBM Tivoli Directory Server Lotus Domino Directory Notes Address Book (NAB) Microsoft Active Directory Sun One Novell eDirectory Alternately, the system can be configured for third-party authentication (for example, through an external security manager such as Tivoli Access Manager) or Secure Sockets Layer (SSL) Client Authentication.
2.4.2 DB2 Content Manager authentication

By default, DB2 Content Manager authenticates users against its own custom user registry, which cannot be externalized or shared with other applications. Once DB2 Content Manager is configured to use and LDAP directory, users can either be provisioned (created) or imported from an external LDAP compliant directory, and then utilize this directory for authentication purposes. DB2 Content Manager also supports authentication by means of trusted credentials (for example, LTPA tokens) supplied by another application (or external security managers) using the Content Manager API for Java. When accessing Content Manager, there are two levels of authentication: one at the database level and another at the Library Server level. Administrators have two classifications when the administrative domains feature is enabled: superadministrators and subadministrators. In general, only superadministrators have access to the System Administration Client. Superadministrators: Superadministrators must have DB2 privileges of an administrator (for example, db2admin). That is, full administrative privileges to DB2 are required. This user ID has to be defined in the operating system with the DB2 administrator privilege. The password for this operating system ID is used to connect to DB2 and to log on to the Library Server. The password defined for the Library Server is not used. This user ID is defined in the Library Server with full Content Manager administration privileges (AllPrivs) to perform all administration activities. Subadministrators do not require DB2 privileges.
49
Subadministrators: Subadministrators manage only certain sections of the Library Server, therefore, subadministrators log on to the System Administration Client in one of two ways: If the user ID is an operating system user ID, then the password in the operating system is used to connect to DB2 and to log on to the Library Server. If the user ID is not an operating system user ID, then the user ID and password pair encrypted in the cmbicmenv.ini file is used to connect to DB2 and the user ID and password provided in the Logon window is used to log on to the Library Server. Content Manager regular users: Standard Content Manager users who use Content Manager Windows Client or eClient dont have to be defined as users of the Library Servers operating system. A user ID and password pair encrypted in the cmbicmenv.ini file is used to connect to DB2 and the user ID and password provided in the Logon window is used to log on to the Library Server. If the user is defined at the operating system level, the user ID and password is used to login to DB2 and (if DB2 Login was successful) to Content Manager Library Server. Figure 2-14 outlines the steps of the login process. Content Manager supports standard LDAP protocols to access user registry from one of the following supported directory servers: IBM Tivoli Directory Server Lotus Domino Directory Notes Address Book (NAB) Microsoft Active Directory It is possible to import user list form LDAP type directories and later use external LDAP directories for authentication purposes. For details on configuring Content Manager for LDAP, refer to 5.4, Configure DB2 Content Manager with LDAP on page 265.
50
Start of Login Process
User ID: <userid> Password: <password>
Is User Defined at the OS Level? Yes DB2 Login Attempt User ID: <userid> Password: <password>
No
DB2 Login Attempt User ID: <ICMConct> Password: <ICMpassword>
No
DB2 Login Successful?
Yes Library Server Login Attempt User ID: <userid> Password: <password>
No
Library Server Login Successful?
Yes Login Process Failed Login Process Successful
Figure 2-14 IBM DB2 Content Manager V8.3, Enterprise Edition login process
51
2.4.3 Single sign-on for WebSphere Portal and Content Manager

Single sign-on represents an authentication process where a user (or client) is validated once (for example, submits a single username and password), and is subsequently identified to all resources and applications within the SSO domain. SSO can often be made transparent to the user (reduced sign-on) even when there is not a true single sign-on mechanism implemented. This usually involves tactical authentication between applications to avoid prompting a user to enter a username / password. By default, DB2 Content Manager and WebSphere Portal maintain separate user registries and utilize separate authentication services. To create a solution where a user has a single identity and to assist in establishing SSO, these user registries should have their user entries synchronized via a common directory.
Common user registry

A common user registry for Content Manager and WebSphere Portal can be based on an LDAP compliant directory (for example, Tivoli Directory Server, Lotus Domino Directory Notes Address Book) or Microsoft Active Directory. Content Manager will still maintain a separate user registry, but the entries are created by provisioning or importing existing entries from the external directory (LDAP). Users entries imported from external directory can also be authenticated against this directory, so that the password stored by Content Manager Library Server is not used. Users are imported from an external LDAP compliant directory (selectively via user query strings) using the LDAP User Import Scheduler utility. During logon, the Library Server automatically connects to the LDAP server to authenticate the user. If the LDAP server is not able to verify the users password for any reason, the authentication will fail. Alternatively, users can be provisioned to Content Manager using the Tivoli Identity Manager workflows and policies, Tivoli Directory Integrator assembly lines, and a custom connector for DB2 Content Manager. Figure 2-15 depicts a possible scenario of coexistence of WebSphere Portal, Content Manager, and a common LDAP server.
52
Web Browser
1 User ID Password
WebSphere Portal Server
C User ID Password
Portlet
IBM Content Manager Library Server
D Authentication B User Credentials A Get User Credentials 3 Authentication response 2 Authentication request
LDAP IBM Directory Server
Figure 2-15 .Common user registry scenario
In this scenario, when a user accesses Content Manager resources via WebSphere Portal, authentication is performed separately by both systems (although they use the same credential source).
WebSphere Portal authentication when using LDAP

When WebSphere Portal is configured to use an LDAP compliant directory, the authentication request is processed as follows: 1. The user submits their credentials to WebSphere Portal. 2. WebSphere Portal performs user authentication against LDAP service. 3. When authentication is successful, the user is identified to WebSphere Portal resources.
Content Manager authentication when using LDAP

When Content Manager is configured to use an LDAP directory, the authentication request is processed as follows: 1. The user submits a Content Manager access request, and the portlet accesses the LDAP service to get the users credentials. 2. The user credentials are programmatically submitted to the Library Server. 3. The Library Server authenticates the users credentials against the external LDAP service. 4. When authentication is successful, user is identified to Content Manager resources.
53
Common LDAP user registry and LTPA tokens

WebSphere Application Server automatically generates LTPA tokens when security is enabled. As WebSphere Portal re-uses the WebSphere Application Server security services, the LTPA tokens are present in the users session and can be retrieved programmatically. The credential can then be passed to Content Manager via the DB2 Information Integrator for Content Java APIs, and therefore the user identity is passed between the two applications without requiring any other form of authentication. Content Manager must be configured to receive trusted connections (for example, LTPA tokens), and individual users must have the appropriate privileges to utilize this authentication mechanism. Note: This is uni-directional SSO, with the authentication domain only covering WebSphere Portal and the portlet application access via the Java API for Content Manager. A user authenticating with the Content Manager eClient will still need to authenticate when accessing WebSphere Portal.
Credential Vault
The WebSphere Portal Credential Service and Credential Vault provide a mechanism for storing external application credentials. Typically, authentication with stored credentials to external applications is conducted as the credentials (username or password) differ from the users WebSphere Portal credentials. The Credential Vault is essentially a way of storing usernames and passwords, which can be programmatically retrieved and used in tactical authentications. The WebSphere Portal Credential Service and Credential Vault also provide a mechanism that assists a portlet in retrieving one of several representations of a user's authenticated identity, which can then be passed to a back-end system such as the Content Manager Library Server for authentication purposes. Note: The implementation of this approach is clumsy when using a shared user registry. In this instance a user has only one username and password, but is required to manually enter those details in a credential vault slot. The details in this slot are then used to authenticate the user during the Java API based requests to Content Manager from WebSphere Portal.
54
2.4.4 Single sign-on authentication using Tivoli Access Manager

There are several levels of integration that can be implemented between Tivoli Access Manager and WebSphere Portal. Figure 2-16 illustrates the multiple realms of single sign-on in an enterprise Web application environment. In the ITSO working example runtime environment, the integration of WebSphere Portal and Tivoli Access Manager is focused on Client-Web application single sign-on issues. The example also illustrates how to use Tivoli Access Manager Global Sign-On (GSO) Lockbox for WebSphere Portal Credential Vault credential storage. Credential Vault is used to store user credentials for Portal-Backend SSO. To implement cross-domain SSO, IBM Tivoli Access Manager WebSEAL supports the ability to forward an authenticated identity from a user in one security domain to a WebSEAL server in another security domain.
Cross-Domain SSO
Client-Web App SSO Web Application
Portal-Backend SSO
Client
Client Authentication Proxy Other Domain Authentication Proxy WebSphere Portal
Portlet
Back-end Application
Portlet Web Application
Back-end Application
Figure 2-16 Realms of single sign-on
Figure 2-17 illustrates the general request processing steps for WebSEAL authentication and authorization when WebSEAL is configured to use forms-based login and cookie based session IDs. Note that the diagram does not include other processing that WebSEAL may perform, such as content filtering, cookie handling, etc. These steps are common for both TAI- or LTPA-enabled junctions. The internal details of the two highlighted steps differ between TAI and LTPA junctions. They are illustrated in Figure 2-18 on page 60 and Figure 2-19 on page 61, respectively.
55
User requests a URL from a web browser
WebSEAL session exists? Yes
No
Is URL accessible to unauthenticated users? Yes
No
Is URL accessible to this user? Yes
Create a session by setting PD-SSESSION-ID cookie in HTTP response
No Send HTTP 302 response redirecting the web browser to the WebSEAL login page
Create a new session by setting PD-SSESSION-ID cookie in HTTP response
Build HTTP request to the junctioned server
User enters username and password and submits the form
Send HTTP 302 response redirecting the web browser to the original URL
Issue the HTTP request and get the response from the junctioned server
Validate user credentials in LDAP user registry
Build HTTP response for the user No User credentials valid? Yes
Web browser automatically requests the URL. PD-S-SESSION-ID session cookie is sent to WebSEAL
Send the response to the user
Send an error page
Display the WebSEAL response
Figure 2-17 WebSEAL to Web application authentication flow
56
This section describes the following single sign-on capabilities when integrating WebSphere Portal and Tivoli Access Manager: Credential Vault integration with GSO Trust Association Interceptor (TAI) LTPA token support Selecting a single sign-on solution
Credential Vault integration with GSO

WebSphere Portal provides an implementation of Vault Adapter (com.ibm.wps.sso.vaultservice.AccessManager41VaultAdapter) that uses the GSO Lockbox to store the user credentials. It allows you to consolidate the sensitive user data into a single GSO repository.
Trust Association Interceptor (TAI)

When using Tivoli Access Manager for a secure portal solution, the WebSEAL is used as Reverse Proxy and entry point to all service requests. The intent of this implementation is to have WebSEAL as the only exposed entry point. As such, it authenticates all requests that come in and provides course-granularity junction point authorization. When the WebSphere Application Server is used as a back-end server it further exploits its fine-grained access control. The WebSEAL can pass HTTP requests that include credentials of the authenticated used to the WebSphere Application Server. The WebSphere Application Server then uses these credentials to authorize the request. WebSphere Application Server includes the Trust Association Interceptor Mode within its security framework, which is capable of interfacing with third-party objects that intercept requests issued by trusted proxy servers, such as WebSEAL. These objects are collectively known as Trust Association Interceptors (TAI) or simply interceptors. WebSphere Application Server includes a TAI plug-in for the WebSEAL. TAI implies that the WebSphere Application Server security application recognizes and processes HTTP requests received from WebSEAL. WebSphere and WebSEAL engage in a contract in which the former gives its full trust to the latter, which means that WebSEAL applies its authentication policies on every Web request that is dispatched to the WebSphere Application Server. This trust is validated by the interceptors that reside in the WebSphere Application Server environment for every request received. The method of validation is agreed on by WebSEAL and the interceptor. Setting values for parameters defined in the webseal.properties file that resides on the WebSphere Application Server server determine the method of validation for the interceptors.
57
The TAI version that ships with Tivoli Access Manager V5.1 can be configured in one of the following methods: Trust association with -b supply option Trust association with -B option Trust association using mutually authenticated SSL
Summary of how TAI works

The following example illustrates how trust association works when using WebSphere Application Server Administration applications: 1. The browser requests a URI that WebSEAL recognizes to be a protected resource. 2. WebSEAL prompts the user to provide a user ID and password (this can be either via a Basic Authentication challenge or via a Custom Form). 3. WebSEAL authenticates the user. 4. After properly authenticating, WebSEAL forwards a modified HTTP request to the back-end WebSphere server. 5. Depending on the configuration: Trust association with -b supply option: If the WebSEAL junction has been defined with -b supply, the modified HTTP request contains the Basic Authentication header field with the original client user ID and the dummy WebSEAL password. When WebSphere Application Server TAI validates the request, it verifies in LDAP that the password supplied in the BA header is valid for the user ID specified in the com.ibm.websphere.security.WebSEAL.username property for TAI. The actual client user ID encoded in the BA header is not used by the TAI request validation. Note: For junctions defined with the -b supply option, WebSEAL builds the BA header using the actual client user ID. This means that unauthenticated users can never access resources over these junctions because WebSEAL cannot build the BA header without the actual user ID.
58
Trust association with -B option for SSL junctions: If the WebSEAL junction has been defined with the -B option, the modified HTTP request contains a Basic Authentication header with the user ID that was specified with the -U option and the password that was specified with the -W option during junction creation. When WebSphere Application Server TAI validates the request, it verifies in LDAP that the password supplied in the BA header is valid for the user ID specified in the com.ibm.websphere.security.WebSEAL.username property for TAI. The dummy user ID encoded in the BA header is not used by the TAI request validation. In this case WebSEAL does not need an actual client user ID to build the BA header, so unauthenticated user access is possible over this type of junction. Note: WebSEAL only supports the -B option for SSL junctions. Trust association using mutually authenticated SSL: Alternatively, if the junction between WebSEAL and WebSphere is a mutually authenticated SSL junction and the property value of com.ibm.websphere.security.WebSEAL.mutualSSL is yes, WebSphere trusts the session and does not perform additional validation of BA headers. No trust association: If a junction is created without one of the above mentioned -b supply, -B or mutual SSL options, WebSphere Application Server TAI will not be able to authenticate WebSEAL with either HTTP Basic Authentication or mutual SSL. In this case TAI will not attempt to extract any user credentials from the request headers and the request will be processed as if coming from an unauthenticated user. 6. After authenticating WebSEAL, TAI extracts the value of the iv-user http header and returns this as the authenticated user that should be used by WebSphere authorization. This is done in the getAuthenticatedUsername() method. Figure 2-18 illustrates the WebSEAL request building and WebSphere Application Server request processing steps in more detail for TAI-based single sign-on using a junction created with the -b supply option.
59
Start building the request to the junctioned server
TAI validates in LDAP the WebSEAL user id specified in TAI username property with the extracted password
Create BA header using actual client id and dummy password
User/password combination valid?
No
Yes -c junction option specified? No
Extract client username from iv_user header Yes
Insert iv_user, iv_groups, iv_creds headers as specified by -c option
iv_user extracted successfully?
No
Yes Send request to WebSphere Application Server Use the extracted value as authenticated user id for WebSphere authorization
WebSphere authorization assumes unauthenticated user
TAI extracts the password from BA header
Process the request in WebSphere Application Server
Send response back to WebSEAL
Figure 2-18 WebSEAL request processing for TAI junction with -b supply option
60
LTPA token support

The WebSphere Application Server can be configured to use a Lightweight Third Party Authentication (LTPA) token (that is, cookie) to provide single sign-on across multiple servers. After the user has been authenticated by WebSphere, an LTPA cookie is created and sent to the browser. The browser will return this cookie on subsequent requests, enabling the origin WebSphere Application Server (or other WebSphere Application Server within the same TCP domain) to recognize the user. The LTPA cookie is protected by a 3DES key, which also proves that it was created by a trusted source. The Tivoli Access Manager WebSEAL can generate an LTPA token that will be accepted by the WebSphere Application Server. WebSphere Application Server trusts this LTPA token because it is encrypted with the correct shared key. Figure 2-19 shows a WebSEAL junction that is configured to use LTPA. An LTPA key is generated on the WebSphere machine and then exported to a keyfile (protected by a password). This keyfile must then be manually copied to the WebSEAL machine. When the junction to the WebSphere server is configured, it is specified as an LTPA junction, and the keyfile and password are given as parameters.
Key File
Internet John
WebSEAL
HTTP Request 4 John
WebSphere Application Server John 6
Application
2 Bind Directory Username=? Password=?
Figure 2-19 WebSEAL creates LTPA cookies for authenticated users
When a user authenticates to WebSEAL and requests a resource on this junction, WebSEAL creates an LTPA cookie using the key from the keyfile. This encrypted cookie contains the users Access Manager user ID and is included in the HTTP request sent to the WebSphere server. When WebSphere receives the HTTP request, it extracts the user ID from the LTPA cookie and uses it to build a WebSphere credential for the user. It would be usual for WebSEAL and WebSphere to share a registry to avoid synchronization problems. WebSphere then applies its own authorization decision to the request.
61
Figure 2-20 illustrates the WebSEAL request building and WebSphere Application Server request processing steps in more detail for LTPA-based single sign-on.
Start building the request to the junctioned server
Create LTPA token with the current user id
LTPA token valid?
No
Yes Encrypt the LTPA token with the imported LTPA encryption key
Use the extracted value as authenticated user id for WebSphere authorization
Send request to WebSphere Application Server
Use the extracted value as authenticated user id for WebSphere authorization
WebSphere authorization assumes unauthenticated user
WAS decrypts the LTPA token with its LTPA encryption key Process the request in WebSphere Application Server
Send response back to WebSEAL
Figure 2-20 WebSEAL request processing for LTPA junction
Selecting a single sign-on solution

This section provides guidelines on selecting an appropriate single sign-on solution for a secure portal solution. If you assume that Tivoli Access Manager and WebSphere Portal (WebSphere Application Server) share a common user registry, then GSO would be the last choice for SSO. Instead, using either the Trust Association Interceptor (TAI) or the LTPA support would be the preferred solution. GSO is the only option for the following scenarios: When WebSEAL and WebSphere rely on different user registries, you may need to supply a different user ID and password combination for the user to WebSphere that is meaningful to the WebSphere user registry.
62
There might be situations, even in the case of a shared user registry, where -b GSO might be useful. For example, if internal users should be able to connect to WebSphere directly using basic authentication and then have indirect access through WebSEAL with WebSEAL being configured to provide forms-based logon. There are cases when LTPA is needed or desired: Use of LTPA would allow having a non-ssl junction without the restrictions of TAI discussed in 2.6.2, Junction considerations for use with TAI on page 70. On the other hand, the restrictions are really security features of TAI. The inflexibility with TAI is really caused by WebSEAL junction restrictions. LTPA can only be used if all the back-end servers (and possibly WebSEAL as well) reside in the same domain (for example, DB2 Content Manager) This is because the LTPA token is really a domain cookie and will not be sent to servers in different domains. This is a real drawback for LTPA. Otherwise, we recommend the TAI option, because it is easy to configure and maintain. There is no key distribution or periodic update required. TAI is also the method used when WebSphere supports integration with third-party Reverse Proxy security servers in general.
2.5 Authorization guidelines

Authorization is the process of determining whether a user has access to resources based on the access policies applied. If the resource is protected, the user will first be authenticated to determine their identity, then check the privileges defined for the requested resource. In this section we will describe authorization mechanisms provided by WebSphere Portal, Tivoli Access Manager, and DB2 Content Manager. In addition, we will explore integration options when used together and with external products such as Tivoli Access Manager. Note: The ITSO identity and access management system working example includes an SSO authentication solution. For more information, refer to Authentication and authorization on page 120.
2.5.1 WebSphere Portal authorization

WebSphere Portal administrators configure access to portal resources (for example, pages, portlets) by assigning users or groups to access roles. The application supports fine-grained access control over resources, and users can
63
interact with (view, edit, manage, etc.) only those resources for which they have appropriate access rights (for example, role based content and services). When rendering a resource, WebSphere Portal verifies that the user has appropriate rights to use the requested resource. Access rights are administered through the User Group Permissions and Resource Permissions portlets and stored in the WebSphere Portal database by default (application specific). Other than the requirement for a successful authentication, authorization is independent of WebSphere Application Server or any custom authentication proxy. WebSphere Application Server protects servlets and enterprise beans, but WebSphere Portal protects its own internal resources, such as pages and portlets. In WebSphere Portal V5.0, access control is based on roles. A role combines a set of permissions with a specific WebSphere Portal resource. This set of permissions is called a role type. You can assign roles on virtual resources and on resource instances. Resource instances are specific resources, such as a single portlet or page. Virtual resources are a unique resource type that have two functions: They protect sensitive operations that affect the entire portal or specific concepts in the portal. For example, the XML configuration interface virtual resource protects the ability to execute scripts through that XML configuration interface. They are parent resources for all resource instances. Role assignments on the Web Modules virtual resource permit access to all Web modules in the portal. Note: Additional information can be found on WebSphere Portal InfoCenter which is also available on the following Web page:
http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html
2.5.2 DB2 Content Manager authorization

In DB2 Content Manager, each user is granted a set of privileges that define the maximum possible authorizations (application specific operations) a user can perform. The users effective access rights will never exceed the user defined privileges. Access control is applied to the object or controlled entity that represents a unit of data. The controlled entity can be at the Library Server level, item type level or on the item (object) itself. For example, you can bind an Access Control List (ACL) to an item type to enforce access control at the item type level. The ACL contains
64
the control rules for access to the stored objects. Every controlled entity or object in Content Manager must be bound to an ACL. When a user initiates an action on an item, the system checks the users privilege level and compares it to the ACL bound to the item or object to determine if the user has the right to carry out the action. Note: Although the ACL may grant the user type additional rights beyond their defined privileges, the user will only be able to perform actions for which there are matches between the user privileges and the ACL rights. Next we briefly explain the following terms and how they are used in conjunction with one another: Privileges Privilege groups Privilege sets Access control lists
Privileges
A privilege is the right to access a specific object in a specific way. Privileges include rights to log on to a system, create a user as well as reading, writing, or deleting an item, a worklist, or an annotation.
Privilege groups
A privilege group is simply a convenience grouping of similar privileges for the purpose of helping you create a privilege set.
Privilege sets
A privilege set is a collection of privileges for working with system components and functions; for example, a privilege set gives authority to create users or to log on a system. It represents a user role, such as editor or reviewer.
Access control lists

An access control list associates one or more user IDs (which includes its own privilege set) or user groups with privilege sets. User IDs might be associated with different privilege sets for different item types, so that there might be an editor for one item type and a reviewer for another item type. Access control lists can be used for multiple item types. Figure 2-21 describes relationships between objects on which IBM DB2 Content Manager for Multiplatforms V8.2 authorization mechanism is based.
65
Privilege
You can use existing privileges to create...
Privilege Group
You can use existing privilege groups to create...
Privilege Set
You can associate users and user groups with privilege sets to create... Users and/or User Groups
Access Control List
You can use existing access control lists to define...
Authorization to use resource
Controlled Entities (Item, Item Type, Library Server)
Figure 2-21 Relationships between objects which are used for authorization purposes
IBM DB2 Content Manager for Multiplatforms V8.2 stores definitions of objects which are used for authorization procedures in its database (ICMNLSDB). Note: For more information on authorization, refer to the product guide: System Administration Guide, IBM DB2 Content Manager V8.3 Enterprise Edition, SC27-1335-06
2.5.3 Tivoli Access Manager authorization

IBM DB2 Content Manager V8.3, Enterprise Edition keeps all ACLs, privileges, and groups definitions in database in ICMSTCompiledACL table. There is no simple way to move authentication functionality out of the Library Server.
66
WebSphere Portal supports Tivoli Access Manager as an external authorization engine. It is potentially possible (with a good deal of effort) to recreate Content Manager authorization model within Tivoli Access Manager and develop a replication mechanism to synchronize data between Content Manager Library Server tables and the Tivoli Access Manager database tables. The user registry would be also shared, as per the common LDAP authentication scenario described previously, via IBM Tivoli Directory Server V5.2. Another possibility for centralized authorization management is to use DB2 Information Integrator for Content Java API to create, modify, and delete ACL objects within Content Manager Library Server database. Both scenarios are hypothetical and were not considered nor implemented for this redbook. The solution described would essentially provide administrators with a centralized authorization management tool, but not used in runtime conditions to check user authorizations.
2.5.4 WebSphere Portal vs. Tivoli Access Manager authorization

Both WebSphere Portal and Tivoli Access Manager provide authorization solutions. One key difference is that WebSphere Portal can only be used to manage authorization for portal pages, portlets, and other portal resources, whereas Tivoli Access Manager can manage authorization for many resource types including portals, J2EE applications, legacy applications, printers, etc. One of the greatest advantages of externalizing the WPS-role-to-user/group mapping in Tivoli Access Manager V5.1 is that it is possible to use not only ACLs that statically define Role membership, but also POPs, and most of all the new Tivoli Access Manager V5.1 Authorization Rules. When using POP, for instance, you can define in which days of the weeks or in which hours of the day a user is a privileged user for portlet A. When using the Authorization Rule you can define a rule stating User is an Administrator for Portlet A if he has received approval from administrative board. In Tivoli Access Manager you are able to dynamically add rules for role definition. When using WPS you can only statically define users/groups that are in a particular role definition. Other key considerations are the customer requirements and existing environment. For example, if authorization is only an issue for portal applications
67
and the application is self-contained, then using WebSphere Portal to manage authorization may be appropriate. On the other hand, if you have many application types (portal, J2EE, older systems, etc.) on many servers, then having a centralized authorization solution using TAM may be more appropriate.
2.6 Product-specific integration guidelines

This section describes Tivoli Access Manager and WebSphere Portal product-specific architectural considerations. The following product-specific features are discussed: WebSEAL junctions Junction considerations for use with TAI Handling of back-end application cookies Junction Mapping Table (JMT) WebSEAL URL-based access control Access control of WebSphere Portal resources Access control of resources within portlet applications WebSEAL and WebSphere Portal session considerations
2.6.1 WebSEAL junctions

Tivoli Access Manager WebSEAL uses junctions to map the protected Web application servers to its own URI space. Each junction maps to a single Web server (or a cluster of identical servers). There are several options that define the junction scheme for WebSphere Portal. Number of junctions: A single junction for all WebSphere Portal access Separate junctions for unauthenticated and authenticated user access to WebSphere Portal Encryption for WebSEAL to WebSphere Portal communications: Non-encrypted junction SSL encrypted junction with server-side certificate SSL encrypted junction with client and server certificates (mutual SSL) Cookie handling: Junction created with -j option Junction created without -j option
68
Cookie handling options usually do not influence other aspects of junction functionality. Requirements on the number of junctions and encryption, however, impose certain limits on the possible junctioning schemes. There are several questions that need to be prioritized and answered before choosing a suitable junction scheme: Will the system allow unauthenticated access to some portal resources? Will the communication between client and WebSEAL be SSL encrypted? Will there be some resources accessible over non-encrypted connection, and some accessible over SSL, thus requiring switching between HTTP and HTTPS protocols? Does your planned URL scheme require the same base URL for both unauthenticated and authenticated access, or does it specify separate base URLs? What are the security requirements for the connection between Remote Proxy node and Portal Server node? What are the performance requirements for the connection between Remote Proxy node and Portal Server node? Typically the most important decision will be the number of junctions, since it is the only one that directly affects the user experience. This decision also has the biggest technical impact. If separate junctions will be implemented for authenticated and unauthenticated access, it is possible to use either encrypted or non-encrypted connections from WebSEAL to WebSphere Portal. However, two junctions can present some problems if using WebSEAL Junction Mapping Table (JMT). Usually /wps path would be mapped to the portal junction. If there are two portal junctions, /wps can only be mapped to one of them. If a user accesses a portlet through the non-mapped junction and clicks on a link with /wps base path, WebSEAL will route the request through the mapped junction. This can cause unexpected behavior for some applications. For more details on this issue, see 2.6.4, Junction Mapping Table (JMT) on page 72. The other option, a single junction, solves the problem with JMT. However, it imposes another limitation. If both authenticated and unauthenticated access need to be provided over the same junction, it must use an SSL connection to the Portal Server node. This limitation does not apply if only authenticated access needs to be provided. For more details on this issue see 2.6.2, Junction considerations for use with TAI on page 70.
69
2.6.2 Junction considerations for use with TAI

The Trust Association Interceptor plug-in provided with WebSphere Application Server provides the following methods for establishing a trust relationship between WebSEAL and WebSphere Application Server: Junction created with -b supply option Junction created without -b supply option using mutual SSL Custom TAI plug-in
Junction created with -b supply option

If the junction is created with the -b supply option, WebSEAL will send HTTP Basic Authentication credentials with each request, identifying that the request indeed comes from WebSEAL. WebSEAL will send the user ID of the currently logged in user, and a dummy password defined in the webseald-<instance>.conf file. The TAI plug-in only uses the password provided with Basic Authentication header, the user id is ignored. The password is validated for the user ID defined by the com.ibm.websphere.security.webseal.userId property for the TAI plug-in. Even though the user ID specified in the request header is not used by TAI, WebSEAL must provide it to generate the Basic Authentication header. If the junction uses an encrypted connection (created with the -t ssl option), WebSEAL can be configured to provide a dummy user ID for the Basic Authentication credentials. If the junction uses a non-encrypted connection (created with the -t tcp option), WebSEAL will always use the actual logged in user ID to generate the Basic Authentication credentials. As a result, unauthenticated access is not possible over a non-SSL junction if using TAI because there is no real user ID, and the Basic Authentication credentials cannot be generated.
Junction created without -b supply option using mutual SSL

Alternatively, the connection between WebSEAL and WebSphere Application Server can be established over a mutually authenticated SSL connection. In this case the trust is established based on cryptographic certificates. The second option is more secure and does not require the use of Basic Authentication credentials, but imposes a performance penalty. This is the only available option when providing authenticated and unauthenticated access over the same junction and using unmodified, out-of-the-box components.
Custom TAI plug-in

The third alternative is to create a custom TAI plug-in for WebSphere Application Server that accepts requests without Basic Authentication headers and without mutual SSL. If you choose this approach, be aware that after such modification, the TAI plug-in will in effect treat all requests it receives as coming from a trusted
70
source. It increases the possibility of malicious security exploits and should not be done in security conscious environments. Note: For details on creating a custom TAI plug-in, refer to the redbook, IBM WebSphere V5.0 Security, WebSphere Handbook Series, SG24-6573.
2.6.3 Handling of back-end application cookies

Depending on the junction creation options, WebSEAL will handle the cookies set by the back-end Web application in two different ways. In either case the cookie value remains unmodified. See WebSEAL Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1359, for more information on junction options (Table 2-1).
Table 2-1 Naming convention for cookie examples Description Reverse Proxy node Portal Server node WebSEAL junction for portal access Value wswin1.itso.ral.ibm.com wpwin1.itso.ral.ibm.com /portal
The cookie handling examples use the following naming convention (Table 2-1). If the junction is created without specifying the -j option, WebSEAL will send the back-end cookie to the client browser without modifying its name. It will update the cookie path to reflect the junction from which it was set. The following example illustrates cookie filtering for the /portal junction created without the -j option (Table 2-2).
Table 2-2 WebSEAL cookie handling without -j option Original cookie Cookie name Cookie path Server JSESSIONID /wps wpwin1.itso.ral.ibm.com WebSEAL filtered cookie JSESSIONID /portal/wps wswin1.itso.ral.ibm.com
Note that the filtered cookie path is now set to /portal/wps and therefore the browser will only send the JSESSIONID cookie with requests for URLs beginning with /portal/wps.
71
If the junction is created with specifying the -j option, WebSEAL will rename the cookie before sending it to the client browser. The new cookie name includes junction identification and is generated in the following form:
AMWEBJCT!<junction_name>!<original_cookie_name>
The following example illustrates cookie filtering for the /portal junction created with the -j option (Table 2-3).
Table 2-3 WebSEAL cookie handling with -j option Original cookie Cookie name Cookie path Server JSESSIONID /wps wpwin1.itso.ral.ibm.com WebSEAL filtered cookie AMWEBJCT!%2Fportal!JSESSIONID / wswin1.itso.ral.ibm.com
Note that the filtered cookie path is now set to / and therefore the browser will send the mangled JSESSIONID cookie with all requests to the Reverse Proxy node. WebSEAL will decode the junction information in the mangled cookie name and determine whether the cookie should be forwarded to the back-end application.
2.6.4 Junction Mapping Table (JMT)

When accessing WebSphere Portal through WebSEAL, the junction name is added to the base portal URL. For example, if the base portal URL is /wps, and the WebSEAL junction name is /portal, the portal URL becomes /portal/wps. Some applications, such as Resource Permissions portlet, do not work properly with the junction name inserted into the URLs because they expect the portal to be accessible at the /wps URL. The WebSEAL Junction Mapping Table can be used to allow these applications to work as expected by mapping all requests for the /wps URL to the /portal junction. There are several limitations for using the Junction Mapping Table: JMT will not work properly with junctions created without the -j option. When WebSphere Portal sets the JSESSIONID cookie, WebSEAL will filter it as illustrated in Table 2-2 on page 71. The cookie path is set to /portal/wps. If the user tries to access a URL beginning with /wps, the browser will not send the JSESSIONID cookie with this request. Even though the link can be accessed, the user session will be lost. JMT will not work properly if separate junctions are used for authenticated and unauthenticated access to WebSphere Portal because JMT can only map /wps URL to a single junction.
72
Suppose that there are two junctions created, for example /portal for unauthenticated access and /sportal for authenticated access, and /wps is mapped to /sportal. If an unauthenticated user accesses a /wps URL, WebSEAL will map it to the protected junction and access will be denied. If /wps is mapped to the unsecure /portal junction, and an authenticated user attempts to access a portal resource, WebSEAL will allow the request through, but WebSphere Portal may not allow access to protected resources over an unsecure channel, and the request will fail.
2.6.5 WebSEAL URL-based access control

WebSEAL provides coarse-grained authorization based on URLs (see Figure 2-22). This level of access control is configured using WebSEAL ACLs, POPs, and Dynamic Rules Engine (Dynamic Rules are new in Tivoli Access Manager V5.1). WebSEAL will allow access only when all conditions are met.
Request Deny
No
Deny
No
Deny
ACL Satisfied?
Yes
POP Satisfied?
Yes
Rule Decision?
Permit
Access determined by user/group permissions
Object access characteristics (for example, audit, time-of-day or day-of-week) for all users and groups
Access determined dynamically, based on current conditions
Figure 2-22 WebSEAL URL authorization
The following example illustrates WebSEAL URL authorization by using only ACLs, without defining additional POPs and Dynamic Rules. In the example runtime environment, the following four ACLs are used: WP_all_access for URLs accessible to all users WP_authenticated_access for URLs accessible to authenticated users only WP_admin_access for URLs accessible to administrators only WP_no_access for denying access to some URLs completely
73
2.6.6 Access control of WebSphere Portal resources

Tivoli Access Manager supports the J2EE security model and JAAS; however, these features are not fully leveraged in the WebSphere Portal environment. WebSphere Portal implements its own authorization mechanism for access control of its resources, such as pages and portlets. This provides finer grained authorization than Java 2 security, but has the disadvantage of having to maintain two separate security solutions (Tivoli Access Manager and WebSphere Portal). However, WebSphere Portal allows you to delegate authorization to an external authorization engine. We will use this feature to delegate WebSphere Portal resource authorization to Tivoli Access Manager.
2.6.7 Access control of resources within portlet applications

In addition to WebSphere Portal authorization, which controls access to resources such as portlets, portlet developers can use aznAPI to integrate Tivoli Access Manager authorization services within their applications. For details, refer to the product guide, Authorization Java Classes Developer Reference, IBM Tivoli Access Manager V5.1, SC32-1350.
2.6.8 WebSEAL and WebSphere Portal session considerations

Both WebSEAL and WebSphere Portal establish sessions with the client browser when initially accessed. These sessions are independent of each other, but both must be valid in order for the system to work as expected.
WebSEAL user sessions

A WebSEAL session is established between the client browser and WebSEAL after a user logs into WebSEAL. The session is maintained by either setting a PD-S-SESSION-ID cookie on the client browser or by SSL Session-ID. WebSEAL session is terminated when the user explicitly logs out by accessing the /pkmslogout URL, or when session timeout occurs. WebSEAL has two settings in the [session] stanza of the webseald-<webseal_instance>.conf file that govern the session timeout. The inactive-timeout parameter sets the timeout value for user session inactivity. By default, inactive-timeout is set to 600 seconds. The timeout parameter sets the maximum lifetime timeout value for all user sessions stored in the WebSEAL session/credentials cache. This parameter defines credential lifetime rather than session inactivity timeout. Its purpose is to enhance security by forcing the user to re-authenticate when the specified timeout limit is reached. By default, timeout is set to 3600 seconds.
74
Note: Both settings produce the same behavior the user is requested by WebSEAL to re-authenticate. All further references in this book to WebSEAL session timeouts will not distinguish between session inactivity timeout and maximum session lifetime timeout because the consequent system interactions are the same.
WebSphere Portal user sessions

A WebSphere Portal session is established between the client browser and WebSEAL when an authenticated user accesses any portal page and a session does not already exist. Pages accessed by unauthenticated users may or may not create a user session for WebSphere Portal, depending on how the portlets are coded. If the WebSphere Portal session for an authenticated user is invalidated for any reason, such as session inactivity timeout, the user may need to log in again to be able to access portal resources. The WebSphere Portal session is actually a standard J2EE Web application session and is handled by WebSphere Application Server. The session is maintained by setting a JSESSIONID cookie on the client browser. The WebSphere Portal session timeout is defined by WebSphere_Portal application server session manager settings in WebSphere Application Server. By default, the session timeout is set to 30 minutes. The test use cases in UCT5: WebSEAL session times out before portal session on page 82 through UCT8: WebSphere Portal logout after WebSEAL session timeout on page 91 illustrate several common scenarios that can occur because of WebSEAL and WebSphere Portal session issues. The behavior seen in UCT6 through UCT8 would typically be perceived by the user as defective, even though each component works exactly as designed. There are two approaches that can be used to remedy the problem illustrated in UCT6 and UCT7: One possible approach is to reconfigure WebSphere Portal to persist the user sessions when they time out, instead of invalidating them. In standalone portal setup, such behavior could lead to possible user session-based security exploits. However, when used together with Tivoli Access Manager, the user sessions are authenticated and validated by WebSEAL. Since WebSphere Portal in this setup trusts WebSEAL and does not perform its own user validation, the WebSphere Portal sessions can be persisted when expiring without compromising security. This is the approach we will use in our example environment. Enabling automatic persistence for expiring WebSphere Portal sessions has another side effect the sessions effectively are preserved in the database forever. This can be a problem for high-volume sites, and sites that create
75
WebSphere Portal sessions for unauthenticated users. The unauthenticated user sessions will be persisted at session expiration, but, being anonymous, they will never be accessed again. In this case it is necessary to perform regular cleanup of stale sessions from the database. Another approach is to set the session timeout in the WebSphere Application Server session manager settings to No timeout. The benefit of this approach is that the WebSphere Portal session database will not get polluted with persisted expired sessions. The drawback is that WebSphere Application Server will keep the sessions in memory indefinitely, resulting in continuously decreasing performance and eventual depletion of the JVM memory heap, thus requiring regular restarting of the WebSphere_Portal application server.
2.7 Sequence diagrams for common access patterns

The following use cases illustrate the typical client access patterns; interactions between client browser, WebSEAL and WebSphere Portal; and the system response. For simplicity, the sequence diagrams only show interactions between components that directly manipulate the user request/response flow in the system. Use cases UCT1 through UCT4 illustrate basic client access patterns. Use cases UCT5 through UCT8 illustrate several specific situations where each component performs as designed, but the overall system response is not as expected. Some suggestions for workarounds for these issues are given in 5.9, Additional configuration and security hardening on page 335. The use cases use the naming convention listed in Table 2-4.
Table 2-4 Naming convention for use cases Description Reverse Proxy node Portal Server node WebSEAL junction for portal access Value wswin1.itso.ral.ibm.com wpwin1.itso.ral.ibm.com /portal
76
2.7.1 UCT1: Access unprotected portal page

This section includes a use case and sequence diagram for access to an unprotected portal page (see Table 2-5 and Figure 2-23).
Table 2-5 UCT1: Access unprotected portal page Use Case ID: UCT1 Description Precondition Actors Main Scenario UCT1: Access unprotected portal page This use case is used to access an unprotected portal page. None. Customer. 1. Actor accesses unprotected portal page with an Web browser. 2. System displays the requested page contents.
Browser GET /portal/wps/portal
WebSEAL GET /wps/portal HTTP 200 OK (default unprotected page)
Portal
HTTP 200 OK (default unprotected page)
Figure 2-23 Sequence diagram - UCT1: Access unprotected portal page
These are the steps: 1. The user tries to access unprotected from a Web browser at:
http://<webseal_fully_qualified_hostname>/portal/wps/portal
2. WebSEAL performs URL authorization and determines that the requested resource is accessible to unauthenticated users. 3. WebSEAL forwards the request to the WebSphere Portal. 4. The WebSphere Portal sends a response with the requested content. 5. WebSEAL performs a response URL filtering and sends the response to the user.
77
2.7.2 UCT2: Access protected portal page, provide valid credentials

This section includes a use case and sequence diagram for access to a protected portal page with valid credentials (see Table 2-6 and Figure 2-24).
Table 2-6 UCT2: Access protected portal page, valid credentials Use Case ID: UCT2 Description UCT2: Access protected portal page, valid credentials This use case is used to access a protected portal page without an existing session. The actor provides valid credentials. The actor has to be a registered user in the system. Customer. 1. Actor accesses protected portal page with a Web browser. 2. System displays the login page. 3. Actor provides valid username and password and submits the page. 4. System displays the requested page contents.
Precondition Actors Main Scenario
Browser GET /portal/wps/myportal
WebSEAL Set PD-S-SESSION-ID cookie. Path: /
Portal
HTTP 200 OK (login.html)
POST /pkmslogin.form HTTP 302 MOVED to /portal/wps/myportal GET /portal/wps/myportal HTTP 200 OK (customized page) Set AMWEB!%2Fportal!JSESSIONID cookie. Path:/ Set PD-S-SESSION-ID cookie. Path: / GET /wps/myportal HTTP 200 OK (customized page) Set JSESSIONID cookie. Path:/wps
Figure 2-24 Sequence diagram - UCT2: Access protected portal page, valid credentials
The steps are as follows: 1. The user tries to access a customized page at:
https://<webseal_fully_qualified_hostname>/portal/wps/myportal
The browser does not send a PD-S-SESSION-ID cookie in the request.
78
2. WebSEAL performs URL authorization and determines that the requested resource is accessible only to authenticated users. 3. WebSEAL sends a login form (login.html) to the user. WebSEAL creates a user session by setting the PD-S-SESSION-ID cookie in the response headers. 4. The user enters a valid username and password and submits the login form (POST /pkmslogin.form). 5. WebSEAL verifies the user credentials and sends a HTTP 302 Moved Temporarily response to the users browser, setting the original page URI (/portal/wps/myportal) in the Location header field. It will cause the browser to immediately redirect to the specified URI. 6. The browser automatically makes a request to:
And sends the PD-S-SESSION-ID cookie in the request. 7. WebSEAL forwards the request to the WebSphere Portal. 8. The WebSphere Portal sends a response with the requested content. 9. WebSEAL performs response URL and cookie filtering and sends the response to the user.
2.7.3 UCT3: Access protected portal page with existing valid session
This section includes a use case and sequence diagram for access to a protected portal page with an existing valid session (see Table 2-7 and Figure 2-25).
Table 2-7 UCT3: Access protected portal page with existing valid session Use Case ID: UCT3 Description Precondition UCT3: Access protected portal page with existing valid session This use case is used to access a protected portal page with an existing valid session. The actor has to be a registered user in the system. The actor needs to have established a valid WebSEAL session by logging in. Customer. 1. Actor accesses protected portal page with an HTML browser. 2. System displays the requested page contents
Actors Main Scenario
79
WebSEAL GET /wps/myportal
Portal
HTTP 200 OK (customized page) Send PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies
HTTP 200 OK (customized page)
Send JSESSIONID cookie
Figure 2-25 Sequence diagram - UCT3: Access protected portal page with existing valid session
These are the steps: 1. The user tries to access a customized page at:
The browser sends the PD-S-SESSION-ID cookie in the request, identifying an existing session. At this stage, the browser may or may not send a valid JSESSIONID cookie identifying a WebSphere Portal session. 2. WebSEAL verifies that the session is valid based on the PD-S-SESSION-ID cookie. 3. WebSEAL performs URL authorization and determines that the requested resource is accessible to the currently authenticated user. 4. WebSEAL forwards the request to the WebSphere Portal. 5. The WebSphere Portal sends a response with the requested content. If the JSESSIONID cookie was not sent with the request or had expired, WebSphere Portal will create a new user session and set the JSESSIONID cookie in the response header. 6. WebSEAL performs response URL and cookie filtering and sends the response to the user.
2.7.4 UCT4: Access protected portal page with invalid credentials

This section includes a use case and sequence diagram for access to a protected portal page with invalid credentials (see Table 2-8 and Figure 2-26).
Table 2-8 UCT4: Access protected portal page, valid credentials Use Case ID: UCT4 Description UCT4: Access protected portal page, valid credentials This use case is used to access a protected portal page without an existing session. The actor provides invalid credentials.
80
Use Case ID: UCT4 Precondition Actors Main Scenario
UCT4: Access protected portal page, valid credentials None. Customer. 1. Actor accesses protected portal page with a Web browser. 2. System displays the login page. 3. Actor provides invalid username and password combination and submits the page. 4. System prohibits access to the requested resource and sends Access Denied response.
WebSEAL Set PD-S-SESSIONID cookie. Path: /
Portal
POST /pkmslogin.form HTTP 403 ACCESS DENIED
Figure 2-26 Sequence diagram - UCT4 Access protected portal page, invalid credentials
These are the steps: 1. The user tries to access a customized page at:
The browser does not send a PD-S-SESSION-ID cookie in the request or sends a cookie identifying an expired WebSEAL session. 2. WebSEAL performs URL authorization and determines that the requested resource is accessible only to authenticated users. 3. WebSEAL sends a login form (login.html) to the user. 4. The user enters an invalid username and password combination and submits the login form (POST /pkmslogin.form). 5. WebSEAL verifies that the user credentials are invalid and sends the HTTP 403 Access Denied response to the user.
81
2.7.5 UCT5: WebSEAL session times out before portal session

This section includes a use case and sequence diagram when the WebSEAL session times out before the WebSphere Portal session (see Table 2-9 and Figure 2-27).
Table 2-9 UCT5: WebSEAL session times out before WebSphere Portal session Use Case ID: UCT5 Description UCT5: WebSEAL session times out before WebSphere Portal session This use case is used to demonstrate WebSEAL session timeout handling if WebSphere Portal has not expired. The system behavior from the user point of view is as expected. The actor has to be a registered user in the system. The actor has not accessed any WebSEAL or portal pages after restarting the browser to ensure there are no established sessions. WebSEAL session timeout is set to 3 minutes. WebSphere Portal session timeout is set to 30 minutes. Customer. 1. Actor accesses protected portal page with a Web browser. 2. System displays the login page. 3. Actor provides valid username and password and submits the page. 4. System displays the requested page contents. 5. After waiting 3 minutes the actor tries to access the same page. 6. System displays the login page. 7. Actor provides valid username and password and submits the page. 8. System displays the requested page contents.
Preconditions
82
WebSEAL
Portal
Set PD-S-SESSION-ID cookie. Path: /
POST /pkmslogin.form HTTP 302 MOVED to /portal/wps/myportal GET /portal/wps/myportal HTTP 200 OK (customized page) Set AMWEB!%2Fportal!JSESSIONID cookie. Path:/ Wait more than 3 minutes for WebSEAL session timeout Send PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies GET /portal/wps/myportal HTTP 200 OK (login.html) Set PD-S-SESSION-ID cookie. Path: / GET /wps/myportal HTTP 200 OK (customized page) Set JSESSIONID cookie. Path:/wps
POST /pkmslogin.form HTTP 302 MOVED to /portal/wps/myportal GET /portal/wps/myportal HTTP 200 OK (customized page) Set PD-S-SESSION-ID cookie. Path: / Send JSESSIONID cookie GET /wps/myportal HTTP 200 OK (customized page) JSESSIONID session is still valid
Send PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies
Figure 2-27 Sequence diagram - UCT5: WebSEAL session times out before WebSphere Portal session
These are the steps: 1. The user accesses a customized portal page the same way as illustrated in UCT2: Access protected portal page, provide valid credentials on page 78.
83
2. The user waits more than 3 minutes, but less than 30 minutes, before sending the next request. At this time the WebSEAL session will be expired, but the WebSphere Portal session will still be valid. 3. The user tries to access the customized page at:
The browser sends the PD-S-SESSION-ID cookie in the request. 4. WebSEAL determines that the user session identified by the PD-S-SESSION-ID cookie has expired. 5. WebSEAL sends the login form (login.html) to the user. WebSEAL creates a new user session by setting the PD-S-SESSION-ID cookie in the response headers. 6. The user enters a valid username and password and submits the login form (POST /pkmslogin.form). 7. WebSEAL verifies the user credentials and sends the HTTP 302 Moved Temporarily response to the users browser, setting the original page URI (/portal/wps/myportal) in the Location header field. It will cause the browser to immediately redirect to the specified URI. 8. The browser automatically makes a request to:
https://<webseal_full_hostname>/portal/wps/myportal
Sending the PD-S-SESSION-ID cookie in the request. 9. WebSEAL forwards the request to WebSphere Portal. 10.WebSphere Portal sends a response with the requested content. Since the JSESSIONID cookie was with the request and the WebSphere Portal session is still valid, WebSphere Portal processes the request as if there was no delay and subsequent re-authentication at WebSEAL. 11.WebSEAL performs response URL and cookie filtering and sends the response to the user.
2.7.6 UCT6: Portal session times out before WebSEAL session

This test case illustrates a situation where the WebSphere Portal session times out before the WebSEAL session. When trying to access a portal page after session timeout, the user receives an error message instructing you to establish a new session. After clicking the Login button, the system does not ask for a username and password, and displays the personalized portal home page. Each component works as designed, but the overall system behavior is not as typically expected (see Table 2-10 and Figure 2-28).
84
Table 2-10 UCT6: WebSphere Portal session times out before WebSEAL session Use Case ID: UCT6 Description UCT6: WebSphere Portal session times out before WebSEAL session This use case is used to demonstrate WebSphere Portal session timeout handling if the WebSEAL session has not expired. The system behavior from the user point of view may not be as expected. The actor has to be a registered user in the system. The actor has not accessed any WebSEAL or portal pages after restarting the browser to ensure that there are no established sessions. WebSEAL session timeout is set to 30 minutes. WebSphere Portal session timeout is set to 3 minutes. Customer. 1. Actor accesses protected portal page with an HTML browser. 2. System displays the login page. 3. Actor provides valid username and password and submits the page. 4. System displays the requested page contents. 5. After waiting 3 minutes the actor tries to access the same page. 6. System displays error message. 7. The user clicks the Login button. 8. System displays protected home page without asking for username/password.
Preconditions
85
WebSEAL
Portal
Set PD-S-SESSION-ID cookie. Path: /
POST /pkmslogin.form HTTP 302 MOVED to /portal/wps/myportal GET /portal/wps/myportal HTTP 200 OK (customized page) Set AMWEB!%2Fportal!JSESSIONID cookie. Path:/ Wait more than 3 minutes for WebSphere Portal session inactivity timeout Send PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies GET /portal/wps/myportal HTTP 302 MOVED to /wps/portal/!ut/p/.scr/ErrorSessionTimeout GET /wps/portal/!ut/p/.scr/ErrorSessionTimeout HTTP 200 OK (session timeout message) Set AMWEB!%2Fportal!JSESSIONID cookie. Path:/ User clicks the Log in link Send PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies GET /wps/myportal/!ut/p/.scr/Home HTTP 200 OK (customized home page) Set AMWEB!%2Fportal!JSESSIONID cookie. Path:/ Send JSESSIONID cookie GET /wps/myportal/!ut/p/.scr/Home HTTP 200 OK (customized home page) Set JSESSIONID cookie. Path:/wps PD-S-SESSION-ID session is still valid Send JSESSIONID cookie GET /wps/myportal HTTP 302 MOVED to /wps/portal/!ut/p/.scr/ErrorSessionTimeout GET /wps/portal/!ut/p/.scr/ErrorSessionTimeout HTTP 200 OK (session timeout message) Set JSESSIONID cookie. Path:/wps JSESSIONID session has expired Set PD-S-SESSION-ID cookie. Path: / GET /wps/myportal HTTP 200 OK (customized page) Set JSESSIONID cookie. Path:/wps
Figure 2-28 UCT6: WebSphere Portal session times out before WebSEAL session
86
These are the steps: 1. The user accesses a customized portal page the same way as illustrated in UCT2: Access protected portal page, provide valid credentials on page 78. 2. The user waits more than 3 minutes, but less than 30 minutes. The WebSphere Portal session expires, while WebSEAL session is still valid. 3. The user tries to access the customized page at:
The browser sends the PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies in the request. 4. WebSEAL determines that the user session identified by the PD-S-SESSION-ID cookie is still valid and forwards the request to WebSphere Portal. WebSEAL examines the AMWEB!%2Fportal!JSESSIONID cookie, and reconstructs and inserts the original JSESSIONID cookie in the HTTP request header. 5. WebSphere Portal determines that the session identified by the JSESSIONID cookie has expired and displays an error message: Your portal session has timed out because of no activity. Please start a new session at your portal Home. 6. The user clicks the Log in link on the error page. 7. Since the PD-S-SESSION-ID session is valid, WebSEAL does not ask for authentication, and forwards the request to WebSphere Portal. 8. WebSphere Portal generates a new User session object, renders the home page for the logged-in user, and sets the JSESSIONID cookie in the response headers. 9. WebSEAL performs response URL and cookie filtering and sends the response to the user.
2.7.7 UCT7: Both WebSEAL and WebSphere Portal sessions time out
This use case illustrates a situation where both WebSphere Portal and WebSEAL sessions have timed out. When trying to access a portal page after session timeout, the user receives a login prompt. After entering username and password and submitting the form, the user receives an error message instructing him to establish a new session. After clicking the Login button, the system does not ask for a username and password, and displays the personalized portal home page. Each component works as designed, but the overall system behavior is not as desired (see Table 2-11 and Figure 2-29).
87
Table 2-11 UCT7: Both WebSEAL and WebSphere Portal sessions time out Use Case ID: UCT7 Description UCT7: Both WebSEAL and WebSphere Portal sessions time out This use case is used to demonstrate a situation when both WebSEAL and WebSphere Portal sessions time out. The system behavior from user point of view may not be as expected. The actor has to be a registered user in the system. The actor has not accessed any WebSEAL or portal pages after restarting the browser to ensure there are no established sessions. WebSEAL session timeout is set to 3 minutes. WebSphere Portal session timeout is set to 3 minutes. Customer. 1. Actor accesses protected portal page with an HTML browser. 2. System displays the login page. 3. Actor provides valid username and password and submits the page. 4. System displays the requested page contents. 5. After waiting 3 minutes the actor tries to access the same page. 6. System displays the login page. 7. Actor provides valid username and password and submits the page. 8. System displays a session timeout error message and instructs the user to reestablish the session. 9. The user clicks the Login button. 10. System displays protected home page without asking for username/password.
Preconditions
88
WebSEAL Set PD-S-SESSION-ID cookie. Path: /
Portal
HTTP 200 OK (login.html) POST /pkmslogin.form HTTP 302 MOVED to /portal/wps/myportal GET /portal/wps/myportal HTTP 200 OK (customized page) Set AMWEB!%2Fportal!JSESSIONID cookie. Path:/
Set PD-S-SESSION-ID cookie. Path: / GET /wps/myportal HTTP 200 OK (customized page) Set JSESSIONID cookie. Path:/wps
Wait more than 3 minutes for both WebSEAL and WebSphere Portal session inactivity timeout Send PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies GET /portal/wps/myportal HTTP 200 OK (login.html) PD-S-SESSION-ID session has expired Set PD-S-SESSION-ID cookie. Path: /
POST /pkmslogin.form HTTP 302 MOVED to /portal/wps/myportal Send PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies GET /portal/wps/myportal Set AMWEB!%2Fportal!JSESSIONID cookie. Path:/ HTTP 302 MOVED to /wps/portal/!ut/p/.scr/ErrorSessionTimeout
Set PD-S-SESSION-ID cookie. Path: / Send JSESSIONID cookie JSESSIONID session has expired
GET /wps/myportal Set JSESSIONID cookie. Path:/wps HTTP 302 MOVED to /wps/portal/!ut/p/.scr/ErrorSessionTimeout
Send PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies GET /wps/portal/!ut/p/.scr/ErrorSessionTimeout HTTP 200 OK (session timeout message) User clicks the Log in link Send PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies GET /wps/myportal/!ut/p/.scr/Home HTTP 200 OK (customized home page) Set AMWEB!%2Fportal!JSESSIONID cookie. Path:/ GET /wps/portal/!ut/p/.scr/ErrorSessionTimeout HTTP 200 OK (session timeout message)
Send JSESSIONID cookie GET /wps/myportal/!ut/p/.scr/Home HTTP 200 OK (customized home page) Set JSESSIONID cookie. Path:/wps
Figure 2-29 UCT7: Both WebSEAL and WebSphere Portal sessions time out
89
These are the steps: 1. The user accesses the customized portal page as illustrated in steps 19 in UCT5: WebSEAL session times out before portal session on page 82. 2. The user waits more than 3 minutes. Both the WebSphere Portal session and the WebSEAL session expire. 3. The user tries to access the customized page at:
The browser sends the PD-S-SESSION-ID cookie in the request. 4. WebSEAL determines that the user session identified by the PD-S-SESSION-ID cookie has expired. 5. WebSEAL sends the login form (login.html) to the user. WebSEAL creates a new user session by setting the PD-S-SESSION-ID cookie in the response headers. 6. The user enters a valid username and password and submits the login form (POST /pkmslogin.form). 7. WebSEAL verifies the user credentials and sends the HTTP 302 Moved Temporarily response to the users browser, setting the original page URI (/portal/wps/myportal) in the Location header field. It will cause the browser to immediately redirect to the specified URI. WebSEAL creates a new user session by setting the PD-S-SESSION-ID cookie in the response headers. 8. The browser automatically makes a request to:
https://<webseal_full_hostname>/portal/wps/myportal
Sending the PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies in the request. 9. WebSEAL determines that the user session identified by the PD-S-SESSION-ID cookie is still valid and forwards the request to WebSphere Portal. WebSEAL examines the AMWEB!%2Fportal!JSESSIONID cookie, and reconstructs and inserts the original JSESSIONID cookie in the HTTP request header. 10.WebSphere Portal determines that the session identified by the JSESSIONID cookie has expired and displays an error message: Your portal session has timed out because of no activity. Please start a new session at your portal Home. 11.The user clicks the Log in link on the error page. 12.Since the PD-S-SESSION-ID session is valid, WebSEAL does not ask for authentication and forwards the request to WebSphere Portal.
90
13.WebSphere Portal generates a new User session object, renders the home page for the logged-in user, and sets the JSESSIONID cookie in the response headers. 14.WebSEAL performs response URL and cookie filtering and sends the response to the user.
2.7.8 UCT8: WebSphere Portal logout after WebSEAL session timeout

This test case illustrates a situation where the user clicks the log out link on the WebSphere Portal page after the WebSEAL session has timed out. After clicking Log out, the user is requested to re-authenticate by WebSEAL by entering a username and password. Each component works as designed, but the overall system behavior is not as desired. The user should not be prompted for a password when logging out (see Table 2-12 and Figure 2-30).
Table 2-12 UCT8: WebSphere Portal logout after WebSEAL session timeout Use Case ID: UCT8 Description UCT8: WebSphere Portal logout after WebSEAL session timeout This use case is used to demonstrate a situation when the user clicks the Log out link after the WebSEAL session has timed out. The system behavior from the user point of view is not as expected. The actor has to be a registered user in the system. The actor has logged in and accessed protected portal pages. WebSEAL session has timed out. Customer. 1. Actor clicks the Log out link on the protected portal page. 2. System displays the login page. 3. Actor provides valid username and password and submits the page. 4. System performs logout and displays the home page for unauthenticated portal users.
Preconditions
91
Browser GET /portal/wps/myportal/!ut/p/.cmd/lo
WebSEAL PD-S-SESSION-ID session has expired
Portal
HTTP 200 OK (login.html) User enters the username and password POST /pkmslogin.form HTTP 302 MOVED to /portal/wps/myportal/!ut/p/.cmd/lo GET /portal/wps/myportal/!ut/p/.cmd/lo HTTP 302 MOVED to /pkmslogout?filename=wpslogout.html GET /pkmslogout?filename=wpslogout.html HTTP 200 OK (WebSEAL logout message)
Set PD-S-SESSION-ID cookie. Path: / GET /wps/myportal/!ut/p/.cmd/lo HTTP 302 MOVED to /pkmslogout?filename=wpslogout.html
Browser redirects to /portal/wps/portal URL as specified in HTML REFRESH meta-tag GET /portal/wps/portal HTTP 200 OK (default unprotected page) GET /portal/wps/portal HTTP 200 OK (default unprotected page)
Figure 2-30 Sequence diagram - UCT8: WebSphere Portal logout after WebSEAL session timeout
These are the steps: 1. A logged-in user has been inactive for some time and the WebSEAL session has timed out. A protected portal page is still displayed in the users browser and the user clicks the Log out link. 2. The browser sends a request to the /portal/wps/myportal/!ut/p/.cmd/lo URL, which should invoke the WebSphere Portal logout command. 3. WebSEAL determines that the user session identified by the PD-S-SESSION-ID cookie has expired.
92
4. WebSEAL sends the login form (login.html) to the user. WebSEAL creates a new user session by setting the PD-S-SESSION-ID cookie in the response headers. 5. The user enters a valid username and password and submits the login form (POST /pkmslogin.form). 6. WebSEAL verifies the user credentials and sends the HTTP 302 Moved Temporarily response to the users browser, setting the original page URI (/portal/wps/myportal/!ut/p/.cmd/lo) in the Location header field. It will cause the browser to immediately redirect to the specified URI. WebSEAL creates a new user session by setting the PD-S-SESSION-ID cookie in the response headers. 7. The browser automatically makes a request to:
https://<webseal_full_hostname>/portal/wps/myportal/!ut/p/.cmd/lo
Sending the PD-S-SESSION-ID and AMWEB!%2Fportal!JSESSIONID cookies in the request. 8. WebSEAL determines that the user session identified by the PD-S-SESSION-ID cookie is still valid and forwards the request to WebSphere Portal. WebSEAL examines the AMWEB!%2Fportal!JSESSIONID cookie, and reconstructs and inserts the original JSESSIONID cookie in the HTTP request header. 9. The WebSphere Portal logout command invalidates the WebSphere Portal session and sends a redirect to the WebSEAL logout URL (/pkmslogout?filename=wpslogout.html). 10.WebSEAL invalidates the user session and displays the wpslogout.html page. 11.The wpslogout.html page contains an HTML REFRESH meta-tag pointing to the default unprotected portal page at:
http://<webseal_full_hostname>/portal/wps/portal
12.The browser automatically makes a request to the unprotected page. 13.The system displays the home page for unauthenticated users.
93
94
Part 2
Part
ITSO identity and access management working example
95
96
Chapter 3.
Requirements analysis and solution design

The business scenario presented in this chapter is for the ITSO, which is a fictitious company in need of an identity and access management system. The identity and access management system needs to include solutions for user provisioning to multiple systems, authentication, authorization, and a security audit trail. The chapter presents the functional requirements for the scenario and draws on these requirements to produce use cases identifying the user interactions with the system. The requirements and use cases are fulfilled by implementing the solution architecture, runtime, and development environments, then developing the application in the remaining chapters of the redbook. This chapter is organized into the following sections: Business scenario Business requirements Use case model Solution architecture
97
3.1 Business scenario

This section describes the initial context of the ITSO identity and access management system. The integrated solution encompasses user provisioning, authentication, authorization, and security audit reporting. Note: We use the fictitious company named ITSO throughout the working example chapters.
3.1.1 Initial context

Many companies are striving to improve employee productivity by consolidating the myriad of application user interfaces that employees use into a single portal interface. Managing each employees access to these applications is essential to complying with security guidelines. During normal business operations, information about employees will need to be updated. Often this information is stored by different applications, so users and administrators must update each application individually while maintaining consistency and accuracy. And as employees join, leave, and move around within the organization, their access to applications must also be updated in a timely and coordinated manner. For the ITSO identity and access management system, the identities of employees within a human resources (HR) application and a document management application will be centrally managed. These applications share a common portal interface, so the management of identities also needs to be integrated into this interface. The ITSO has processes in place that must not be radically altered. When a new employee is hired, a number of policies must be followed: Only employees performing the role of an HR Specialist should add a newly hired employee to the HR application. This creation is often done before the employees first day of work. Only basic employee information, such as the department assignment and salary, will be entered into the system by the HR Specialist. The employees access to the ITSO identity and access management system must be approved by the employees manager. The role the employee performs within the organization is assigned by the employees manager. The user ID that the employee will use is chosen by the employee.
98
Personal details, such as home address and bank account information for direct deposit of pay, are entered by the employee.
3.1.2 Business challenges

Managing users across multiple applications is an extended security application pattern that controls user access while simplifying the maintenance of user accounts. There are a number of business challenges associated with managing users across multiple applications: For several of the ITSO applications, each of them maintains user account information within the application or middleware used by the application. Keeping the information accurate in each one of the applications is a time-consuming task, as well as being error-prone. Ensure that the right people have access to the right resources. Grant access to all the applications that employees will need, based on their role within the organization. Maintain corporate policies. Rules for user IDs and passwords are difficult to consistently enforce across all user accounts in different applications. Reduce security administration and support costs. Allow users to reset their own passwords and automate the provisioning of user accounts to the applications they need to have access. Improve employee productivity by providing a single point of access for the applications commonly used by employees, and only require them to log in once. Provide a security audit and reporting capability to ensure that security policies are being adhered to.
3.2 Business requirements

This section presents the business requirements for the ITSO identity and access management system.
3.2.1 Functional requirements

This section describes the functional requirements of the solution organized by the unique requirements of the following user roles: Employees Managers Administrators
Chapter 3. Requirements analysis and solution design
99
Employee requirements
The following requirements were identified for employees: Use a single interface for accessing the employee record information, human resources application, and document management application. Maintain personal and account information across multiple applications simultaneously. Have a single password for all accounts. Reset passwords quickly across all applications.
Manager requirements
Managers have the following requirements: New employees submit their own requests for user accounts. Use a single interface for accessing applications and processing employee changes. Assign roles to employees that automatically give them the correct access to the applications they need in a timely manner. Restrict the modification of sensitive employee record information, such as salary, to appropriate managers. Restrict the creation of new employees in the human resources application to the role of the HR Specialist.
Administrator requirements
Administrators identified the following requirements: Automate handling of password reset requests. Enforce user ID and password rules. Automate account creation across multiple systems. View a security audit report on access management activity. Have the capability to identify the employee owning each account.
3.2.2 Non-functional requirements

For the scope of this redbook, and subsequently in the associated example, we have limited our focus to the integration of the HR and document management sample applications into an identity and access management solution that uses a portal interface to integrate the entire solution for end users. The non-functional requirements for an enterprise environment delivering these applications are beyond the scope of this publication.
100
The ITSO identity and access management system is intended as a practical example to demonstrate integration approaches and is not a sufficient model to be used in an enterprise production deployment. We leave it up to the reader to extend the underlying principles for enterprise deployment.
3.3 Use case model

This section presents the use case model and individual use cases that outline how users will interact with the system. The use cases for the business applications in the system are not detailed in this section, with the exception of the Hire Employee use case, which is part of the HR application. The Hire Employee use case is included because the employee number generated during this use case is needed by the Employee Self-Registration use case.
3.3.1 Use case overview

This section describes the actors in the use cases, presents the use case diagram, and summarizes the use cases.
Actors defined
The actors are described in Table 3-1.
Table 3-1 Actors Actor HR Specialist Employee Manager Description A human resources professional who has the authority to add new employees to the HR application. All employees of the ITSO company. Employees can fill the role of other actors when assigned those roles. A manager of a set of employees within the company. A manager has access to additional employee details, such as salary. Department transfers are initiated by managers and specific requests require manager approval.
101
Use case diagram

This section presents a use case diagram to graphically summarize the user interactions with the ITSO identity and access management system, as seen in Figure 3-1.
Hire Employee HR Specialist Employee Self-registration
Approval and Role Assignment
Employee Password Change Employee Employee Self-care
Employee Password Reset
Manager
Role Change
Department Change
Figure 3-1 User provisioning use case diagram
102
Summary of use cases

Table 3-2 summarizes the goals and user actors involved in each of the use cases illustrated in Figure 3-1.
Table 3-2 Front-end use cases Use Case ID UCF01 UCF02 Use case name Hire Employee Employee Self-registration Goal in context A new employee is hired and added to the HR application A new employee requests access to the ITSO identity and access management system. The manager of a new employee approves the employees request for access to the system and assigns a role to the employee to control access to individual applications. A password is changed by an employee. Employee record information is updated by the employee. The password is reset by an employee. A manager changes the role of an employee, resulting in new levels of access to applications. An employee is transferred from one department to another within the organization. Actors HR Specialist Employee
UCF03
Approval and Role Assignment
Manager
UCF04 UCF05 UCF06 UCF07
Employee Password Change Employee Self-care Employee Password Reset Role Change
Employee Employee Employee Manager
UCF08
Department Change
Managers
3.3.2 Use case details

This section describes the details for each of the use cases where the actor accesses the main functions of the ITSO system through the portal interface (see Table 3-3 through Table 3-10).
103
Table 3-3 UCF01: Hire Employee Use Case ID: UCF01 Description UCF01: Hire Employee The HR Specialist creates the initial profile for a new employee in the human resources application. The HR Specialist enters the employee's name and department, after which the employee information is sent to the HR application to create the employee's record in the HR database and generate an employee number for the new employee. 1. The actor has the role of HR Specialist. 2. The new employees name does not already exist in the human resources application. Primary actors Secondary actors Main scenario HR Specialist None 1. HR Specialist logs into the portal interface. 2. HR Specialist navigates to the New Employee portlet. 3. HR Specialist enters the name of the new employee and assigns the employee to a department. 4. The human resources application generates and displays an employee number for the new employee. 5. The HR Specialist includes the employee number in the package of information provided to the new employee during orientation. Alternatives None
Precondition
Table 3-4 UCF02: Employee Self-registration Use Case ID: UCF02 Description UCF02: Employee Self-registration The new employee navigates to the ITSO identity and access management system to register for an account. The employee submits a request for an account using her employee number. The portlet passes the employee's completed request to the Identity Manager, which requests approval from the employee's manager. 1. UCF01 Employee None
Precondition Primary actors Secondary actors
104
Use Case ID: UCF02 Main scenario
UCF02: Employee Self-registration 1. The new employee navigates to the portal interface and the Self-Registration portlet. 2. The new employee submits a registration request with the employee number assigned, the desired user ID, and the answer to a security challenge question that will be needed later for performing password resets. 3. The Identity Manager workflow notifies the new employees manager of the request and waits for approval.
Alternatives
If the requested user ID already exists, doesnt meet organizational guidelines, or the employee number is already associated with a user ID, then the registration request is not accepted. The new employee must resubmit it with appropriate changes.
Table 3-5 UCF03: Approval and Role Assignment Use Case ID: UCF03 Description UCF03: Approval and Role Assignment The manager navigates to the ITSO identity and access management system to process outstanding requests. The manager sees the new employees request, selects a role to assign to the employee, and approves the request. Once approved, the Identity Manager creates accounts for the new employee in each application that is associated with the role assigned to the employee. A password is generated for each account and sent to the manager. 1. UCF02 Manager None 1. The manager logs in to the portal interface and navigates to the Process Requests portlet. 2. The manager processes a request by selecting a role for the employee, selecting to approve the request, and submitting the approval. 3. The Identity Manager provisions the user to the applications based on the defined provisioning policies. Each account created has a generated password. 4. The Identity Manager sends each generated password to the manager in an e-mail.
Precondition Primary actors Secondary actors Main scenario
105
Use Case ID: UCF03 Alternatives
UCF03: Approval and Role Assignment If the manager rejects the request, no user accounts are created. The manager needs to discuss with the new employee why the request was rejected.
Table 3-6 UCF04: Employee Password Change Use Case ID: UCF04 Description UCF04: Employee Password Change An employee logs in to the ITSO identity and access management system and submits a password change request. Once submitted, the new password is validated against the password policy in place. All accounts for the employee are then updated automatically with the new password. 1. The employee knows the current password. Employee None 1. The employee logs in to the portal interface and navigates to the Change Password portlet. 2. The employee enters the current password and then the new password twice, and submits the request. 3. The Identity Manager validates the password against the password policy for the organization. 4. The Identity Manager provisions the updated password to each account owned by the employee. Alternatives If the password does not pass validation, a message is displayed for the employee who may then try again.
Table 3-7 UCF05: Employee Self-care Use Case ID: UCF05 Description UCF05: Employee Self-care An employee logs in to the ITSO identity and access management system and updates information in the employee record. Once the changes are submitted, each modified attribute is provisioned to each application that stores the attribute. None Employee
Precondition Primary actors
106
Use Case ID: UCF05 Secondary actors Main scenario
UCF05: Employee Self-care None 1. The employee logs in to the portal interface and navigates to the Update My Information portlet. 2. The employee modifies one or more attributes displayed from the employee record, and submits the request. 3. The Identity Manager provisions the updated attributes to each account owned by the employee.
Alternatives
No updates are submitted by the employee.
Table 3-8 UCF06: Employee Password Reset Use Case ID: UCF06 Description UCF06: Employee Password Reset An employee is unable to login to the ITSO identity and access management system and submits a password reset request, including the answer to the challenge question. Once submitted, the challenge answer is validated. A password is generated that satisfies the password policy. The password is provisioned to all accounts for the employee and displayed to the employee. Upon completion of this use case, the employee is expected to change the password as outlined in UCF04. None Employee None 1. The employee navigates to the Reset Password portlet. 2. The employee enters the employee number, user ID, and answer to the challenge question, then submits the reset request. 3. The Identity Manager validates the answer to the challenge question. 4. The Identity Manager generates a new password that complies with the password policy. 5. The Identity Manager provisions the updated password to each account owned by the employee. 6. The generated password is displayed to the employee. Alternatives If the challenge answer does not pass validation, a message is displayed for the employee who may then try again.
107
Table 3-9 UCF07: Role Change Use Case ID: UCF07 Description UCF07: Role Change A manager changes the role assignment for an employee. The employees access to applications is automatically updated to reflect the new role. None Manager None 1. The manager logs in to the portal interface and navigates to the Role Change portlet. 2. The manager enters the employee number of an employee managed by the manager. 3. The list of roles for the department is displayed with the employees current role selected. 4. The manager updates the role assignment and submits the change. 5. The Identity Manager provisions the change to all applications affected by the change. User accounts may be created or removed as appropriate for the change in role. Alternatives If the manager does not manage the employee whose number is entered, then this message is conveyed to the manager who may then try again.
Table 3-10 UCF08: Department Change Use Case ID: UCF08 Description UCF08: Department Change A manager transfers an employee to a new department. The transfer is not complete until the employees new manager approves the change and assigns a role to the employee. None Managers None
Precondition Primary actors Secondary actors
108
Use Case ID: UCF08 Main scenario
UCF08: Department Change 1. The current manager logs in to the portal interface and navigates to the Employee Update portlet. 2. The manager enters the employee number of an employee managed by the manager. 3. Information from the employees record is displayed. 4. The manager updates the department attribute of the employee record and submits the change. 5. The Identity Manager requests approval from the manager of the selected department. 6. The new manager logs in to the portal interface and navigates to the Process Requests portlet. 7. The manager processes the request by selecting a role for the employee, selecting to approve the request, and submitting the approval. 8. The Identity Manager provisions the change to all applications affected by the change. User accounts may be created or removed as appropriate for the change in role.
Alternatives
If the current manager does not manage the employee whose number is entered, then this message is conveyed to the manager who may then try again. If the new manager rejects the transfer, then the employee remains in the original department. No provisioning is performed.
3.4 Solution architecture

This section presents the solution architecture for the ITSO identity and access management system. Analysis of the requirements and use cases have provided us with the information we need to formulate a security architecture. The solution architecture includes the following sections: Architecture overview Architectural decisions Solution architecture details Runtime topology and product mapping Development environment topology and product mapping
109
3.4.1 Architecture overview

This section provides a brief architecture overview of the high level components of the ITSO identity and access management system. Figure 3-2 is intended to graphically summarize the key components of the ITSO identity and access management system, and provide a basic level of understanding how these components interact. It is not meant to show options for scalability or high availability.
Access Manager TAM Authorization TAM Policy TIM Agent for TAM TIM Policies 3 Database policy Backend policy LDAP policy TAM policy Identity Manager Tivoli Identity Manager
Authorization
Database AL
TDI Assembly Lines 1
Backend AL
LDAP AL
Authentication
Portal Server TAI Portlet and J2EE applications
User Provisioning
TDI connector
TDI connector
Client Web Browser
Directory Tivoli Directory Integrator Tivoli Directory Server
LtpaToken Content Management DB2 Content Manager
Figure 3-2 High level architecture of the ITSO identity and access management system
Note: For further details about architecture topologies, refer to Chapter 2, Architecture and design guidelines on page 15.
110
The following descriptions highlight the components seen in Figure 3-2 by node: Reverse Proxy node: The WebSEAL is the primary software component of IBM Tivoli Access Manager V5.1 for e-business used on the Reverse Proxy node. The WebSEAL is more than a Reverse Proxy. It is actually a high performance, multi-threaded Web server that applies a defined security policy to the protected object space. All user requests will be received by the WebSEAL. The WebSEAL determines if the user has attempted to access a protected resource and will prompt the user with a logon dialog. The user will enter and submit the credentials to the WebSEAL, which will validate the identity of the user with the Tivoli Directory Server LDAP directory and Tivoli Access Manager. Portal Server node: IBM WebSphere Portal V5.1 is the primary software used on the Portal Server node. The Portal Server node in our environment uses WebSphere Portal V5.1 to host portlet applications (HR, document management, provisioning). In addition, WebSphere Application Server V5.1 is used to host EJB applications. These application types can be split across separate nodes for performance and scalability reasons. We chose to install them on the same node for simplicity of setup. Access Manager node: The Policy and Authorization Servers are the primary software components of IBM Tivoli Access Manager V5.1 for e-business used on the Access Manager node. This node provides services for both authentication and authorization. Directory node: The Directory node in our working example has two functions. First, IBM Tivoli Directory Server V5.2 is used as a common DAP user repository for the applications (HR and document management). Second, IBM Tivoli Directory Integrator V6.0 is used on this node to provision users initiated by Tivoli Identity Manager to external systems by the use of TDI assembly lines and connectors. Identity Manager node: IBM Tivoli Identity Manager V4.5.1 is the primary software used on the Identity Manager node. This node provides a centralized means of creating, deleting, and updating users within Tivoli Identity Manager and provisioning this information to external systems by the use of TDI or Tivoli Identity Manager Agents.
111
Content Management node: IBM DB2 Content Manager V8.3, Enterprise Edition is the primary software used on the Content Management node. This node provides the back-end document repository and workflow capability for the ITSO custom document management application.
3.4.2 Architectural decisions

This section documents important decisions made about aspects of the chosen architecture, including the structure of the system, software versions, and protocols that must be used. For the ITSO working example, we have identified the following architectural decisions (details are given in Table 3-11 through Table 3-18). AD01: Products used for security architecture AD02: Authentication mechanisms AD03: Authorization approach AD04: Where the user data is to be stored AD05: User provisioning AD06: Protocol for user communication with WebSEAL AD07: Protocol communication between WebSEAL and Portal AD08: Protocol communication between Portal and Content Manager
Table 3-11 AD01: Products used for security architecture Architectural decision ID Architectural Decision Problem Statement AD01 Which products should be used for the systems security architecture. The ITSO wants to provide a robust and comprehensive security architecture to secure the HR and document management application from unauthorized access and intrusion and to ensure users can only access data that they are authorized to see. In addition, the ITSO needs a centralized system to provision users to external systems. Security product must support configuration for WebSphere Portal. Tivoli Identity Manager, Tivoli Directory Integrator, Tivoli Directory Server, and Tivoli Access Manager provide a complete set of security infrastructure products to achieve single sign-on authentication, centralized authorization, and solution for user provisioning to external systems.
Assumptions Motivation
112
Architectural decision ID Alternatives
AD01 1. Use IBM Tivoli Access Manager V5.1 for e-business WebSEAL for security framework with a combination of less integrated solutions with WebSphere Portal and DB2 Content Manager. Tivoli Identity Manager and Tivoli Directory Integrator can be used to provision users to external systems. 2. Use another third-party security products. The first alternative was selected due to the well-known secure integration with WebSphere Portal.
Decision
Table 3-12 AD02: Authentication mechanisms Architectural Decision ID Decision Topic Problem statement AD02 Authentication mechanisms The ITSO identity and access management system must deliver single sign-on (SSO) authentication for both the HR and document management applications. This requires SSO for WebSphere Portal, Tivoli Access Manager, Tivoli Identity Manager, and DB2 Content Manager. Users will be provisioned from Tivoli Identity Manager using TDI to the HR DB2 database, LDAP user repository, and DB2 Content Manager. In addition, users will be provisioned to Tivoli Access Manager (TAM) using the TIM Agent for TAM. Role based access is defined in both applications. Users login to WebSEAL and require seamless sign-on to WebSphere Portal and Content Manager. Both applications share a common LDAP user repository. The credentials will be passed from the WebSEAL and WebSphere Application Server used by WebSphere Portal via TAI. The credentials will be passed from WebSphere Portal to the DB2 Content Manager Library Server via an LtpaToken. Use of a single user-name and password for each user User must only login to WebSEAL to gain access to the ITSO identity and access management system.
Assumptions
Motivation
113
Architectural Decision ID Alternatives
AD02 Authentication is handled independently by each application and a tactical authentication mechanism links WebSphere Portal (i.e. credential vault) based user requests to Content Manager authentication. Use WebSEAL / Tivoli Access Manager, Trusted
Decision
Table 3-13 AD03: Authorization approach Architectural Decision ID Decision Topic Problem statement AD03 Authorization approach The ITSO identity and access management system is a role based solution. Users require application specific access permissions defined in both WebSphere Portal and DB2 Content Manager. Roles will be defined within Tivoli Identity Manager and provisioned out to the external systems (WebSphere Portal and DB2 Content Manager). Required roles are common to both WebSphere Portal and Content Manager. Access control can obtain permissions at a group level in both applications. Application specific permissions can be applied to a common user group model. The configuration of access permissions in both applications therefore becomes part of deployment. Users can be provisioned, assigned group membership, and inherit access to the applications. 1. Authorization can be applied at the user level in both applications. 2. Authorization can be applied at group level in both applications, based on a common group hierarchy. 3. All authorization can be externalized from the systems to be centrally managed by Tivoli Access Manager. This option has the limitation in that DB2 Content Manager does not provide a means out-of-the-box to externalize access control to Tivoli Access Manager. The second alternative, a group authorization model, was selected to simplify user provisioning.
Assumptions
Motivation
Alternatives
Decision
114
Table 3-14 AD04: Where the user data is to be stored Architectural decision ID Architectural Decision Problem Statement Assumptions Motivation AD04 Where the user data for the application is to be stored. Administration of user profiles becomes difficult when multiple directories are used to store user profiles. Applications support the Lightweight Directory Access Protocol (LDAP). Using a single enterprise directory server to store all user profile data needed by all the components of the solution promotes easy maintenance of the set of user accounts. 1. Use Tivoli Directory Server V5.2 as the single enterprise directory. 2. Use other third-party directory services that support the LDAP protocol. 3. Use multiple directories to store user profile data. For example, directory used for Tivoli Identity Manager and another as a common repository for applications. The third alternative was selected due to ease of integration with both Tivoli Access Manager and WebSphere Portal.
Alternatives
Decision
Table 3-15 AD05: User provisioning Architectural Decision ID Decision topic Problem statement AD05 User provisioning The ITSO identity and access management system needs to provide the capability of user provisioning users (create, update, delete), groups and role assignments. WebSphere Portal and Content Manager support Lightweight Directory Access Protocol (LDAP) compliant directory servers (Tivoli Directory Server) The users and groups in the system are common to both WebSphere Portal and Content Manager.
Assumptions
115
Architectural Decision ID Motivation
AD05 Centralized control over users and groups will provide consistency in user profiles between WebSphere Portal and Content Manager. User provisioning can occur at the directory server level, propagating to the applications. Input methods include ldif file import, WebSphere Portal administration portlet, as well as other methods of update the Tivoli Directory Server (Web Administration Tool, JNDI API). 1. WebSphere Portal and Content Manager share a common LDAP compliant user repository, however the DB2 Content Manager Library Server requires that users exist in Content Manager for authorization purposes. Tivoli Identity Manager and Tivoli Directory Integrator will be used to provision users to the external systems. 2. WebSphere Portal and Content Manager each maintain their own user repository. The first alternative, use of a common user repository, was selected based on the ease of managing a single user store. Also, this approach provides for centralized management of users in Tivoli Identity Manager, which can be provisioned to external systems using TDI assembly lines and connectors, and by using Agents such as the TIM Agent for TAM.
Alternatives
Decision
Table 3-16 AD06: Protocol for user communication with WebSEAL Architectural decision ID Architectural Decision Problem Statement AD06 The protocol to be used for users to communicate with the WebSEAL Reverse Proxy server. The ITSO users must trust that their data will be secure when accessing the ITSO HR and document management applications. None. To stop data interception. 1. HTTPS can be used to encrypt user data for communication between the user and WebSEAL. 2. HTTP can be used to communicate between the user and WebSEAL.
Assumptions Motivation Alternatives
116
Architectural decision ID Decision
AD06 The first alternative was selected for authenticated access to prevent interception sensitive user data. The second alternative was selected for unauthenticated access to improve performance.
Table 3-17 AD07: Protocol communication between WebSEAL and Portal Architectural decision ID Architectural Decision Problem Statement AD07 The protocol to be used for communication between WebSEAL and the portal server. Using HTTPS for all communications with the portal server can lead to slow performance, especially in the case of accessing image data. If the components that are communicating are in trusted zones, then HTTP may be used to increase performance. However, the use of HTTP prevents unauthenticated access when TAI is used to establish a trust relationship between WebSEAL and WebSphere Portal. None. Allow both authenticated and unauthenticated access over the same junction. 1. HTTP can be used for communication between WebSEAL and WebSphere Portal. 2. HTTPS can be used to encrypt user data for communication between WebSEAL and WebSphere Portal. The second alternative was selected to allow both authenticated and unauthenticated access.
Assumptions Motivation Alternatives
Decision
117
Table 3-18 AD08: Protocol communication between Portal and Content Manager Architectural decision ID Architectural Decision Problem Statement AD08 The protocol to be used for communication between the portal server and DB2 Content Manager. Using HTTPS for all communications with the portal server and back-end systems can lead to slow performance. If the components that are communicating are in trusted zones, then HTTP may be used to increase performance. None. 1. HTTP can be used for communication between WebSphere Portal and DB2 Content Manager. 2. HTTPS can be used to encrypt user data for communication between WebSphere Portal and DB2 Content Manager. For this redbook, we choose option 1 for simplicity. But in a production environment with critical data stored in DB2 Content Manager, we recommend alternative 2.
Assumptions Alternatives
Decision
3.4.3 Solution architecture details

In the solution architecture presented in this section, we first describe the architecture from the initial context. Next we explore the key solution architecture elements, including single sign-on authentication, authorization, and user provisioning. Note: For more detailed information regarding security architecture for authentication and authorization when using Tivoli Access Manager and WebSphere Portal, refer to the Design and integration guidelines chapter in the IBM Redbook, Develop and Deploy a Secure Portal, Using WebSphere Portal V5 and Tivoli Access Manager V5.1, SG24-6325.
Existing solution architecture

The existing solution architecture, as seen in Figure 3-3, has several limitations that make it an ideal candidate to implement the ITSO identity and access management system. The Portal Server node and Content Management node share a common LDAP directory on the Directory node, authentication is performed by WebSphere Portal. In this case, DB2 Content Manager has been configured to use LDAP and can receive an LtpaToken from the WebSphere Application Server on the Portal Server for single sign-on.
118
Content Management
IBM HTTP Server WebSphere Application Server
icmrm CM Resource Manager icmrm ear server1
Portal Server
WebSphere_Portal Doc Mgt war (portlets) HR war (portlets) server1 HR ear (servlets, EJBs)
DB2 UDB Enterprise Server

icmnlsdb rmdb
DB2 Content Manager

Library Server System Admin Client

HR
DB2 II4C
CM connector
Directory
server1

ldapdb
Tivoli Directory Server
Figure 3-3 Existing solution architecture
The authorization for the HR and document management portlets is performed by WebSphere Portal by defining resource permissions for portal pages and portlets by roles (user and user groups). Authorization to DB2 Content Manager resources and workflow is managed within DB2 Content Manager by defining a privilege set (ClientUserEditSSO) and assigning users to the appropriate groups. In the current system, users must be created and managed manually within each of the systems (WebSphere Portal, DB2 Content Manager) with separate users interfaces. In our scenario, we only have a few applications. When many applications exist with unique user repositories, authentication and authorization models, you can quickly see why this type of environment would be very difficult to maintain.
119
Authentication and authorization

The authentication and authorization architecture for the ITSO identity and access management system is depicted in Figure 3-4. The ITSO identity and access management system does provide single sign-on authentication. We have included a basic authentication and authorization flow for an ITSO employee who was granted access to the document management application. This scenario assumes that the user has already been provisioned with the proper roles, which are used to determine the access of this user. 1. User enters credentials: The ITSO employee needs to access the ITSO custom document management system to create a new research report. The user will enter the ITSO site URL in a Web browser. The WebSEAL will determine if the URL requires the user to be authenticated. In this example, the user will need to enter their user ID and password credentials. 2. Validate user credentials with Policy Server: The WebSEAL will validate that the user credentials are valid by communicating with the Tivoli Access Manager Policy Server. 3. Successful authentication: Provided that the credentials are valid with Tivoli Access Manager, the user will be authenticated to the system. In our example, the WebSEAL and WebSphere Application Server on the Portal Server node have been configured with trusted association interceptor (TAI) to establish a trusted relationship to pass credentials. 4. Authorization: Both WebSphere Portal (internal) and Tivoli Access Manager (external) can be used to provide the access controls to portal pages and portlets. In our example, we chose to use WebSphere Portal for simplicity, however our environment will be configured to allow for externalizing the resource permissions from WebSphere Portal to allow Tivoli Access Manager to perform authorization. 5. Credentials passed via LtpaToken: DB2 Content Manager can be configured to use an LDAP directory such as Tivoli Directory Server, and enabled for single sign-on (SSO). SSO is achieved by passing the credentials of the user from WebSphere Application Server of the Portal Server to the Library Server via an LtpaToken.
120
6. Authorization to DB2 Content Manager resources: Although DB2 Content Manager is using a common LDAP directory and can receive authentication credentials from an LtpaToken, the authorization model is still managed within DB2 Content Manager. The authenticated user must have the ITSO defined privilege set ClientUserEditSSO (proper privileges to enable SSO), and be added to the proper groups within Content Manager to access specific resources and workflow.
Content Management CM Resource Manager CM Library Server 6 rmdb icmnlsdb Authorization to CM resources performed by CM Library Server
Grant access 3 after successful User enters Portal Server 1 authentication credentials Reverse Proxy (TAI configed) User provision war - portlets Client Web Doc Mgt war - portlets TAM WebSEAL Browser HR war - portlets HR ear - servlets, EJBs 2 Validate the user credentials with Policy Server and Directory Server HR 4b
4a Internal Authorization * WebSphere Portal resource permissions
Credentials passed via LtpaToken 5 Directory Tivoli Directory Server
ldapdb
Tivoli Directory Integrator
External Authorization * TAM Authorization Server
Access Manager TAM Authorization TAM Policy TIM Agent for TAM Identity Manager Tivoli Identity Manager
Figure 3-4 Authentication and authorization for the ITSO identity and access management system
121
User provisioning
The ITSO identity and access management system does more than consolidate user account ownership within Tivoli Identity Manager. It keeps common employee data stored in multiple systems synchronized and updates access to systems through synchronized membership in groups. This synchronization is done by making the employees identity within Tivoli Identity Manager, known as the Person object for the employee, contain the superset of the attributes to be updated. All updates of these attributes are then done on the Person object and Tivoli Identity Manager provisions them to the appropriate systems based on a set of provisioning policies. The policies are configured to set the user account attribute values required by the system represented by the account, to the values contained in the Person object. The policies will force an update of an account whenever any of the associated attributes in the Person object are changed. This does introduce duplication of employee information between the Tivoli Identity Manager server and the other systems. This solution may not be appropriate for large amounts of data stored on many different systems.
Employee data in multiple application repositories

Each application in the ITSO identity and access management system stores some amount of employee data in its data repository. Some unique attributes requiring extra privacy, such as salary, are updated directly through the HR application. The rest are managed by Identity Manager. The provisioning policies provision the appropriate employee attributes from Identity Manager to the application repositories as illustrated in Table 3-19.
Table 3-19 Employee attribute mapping across repositories Identity Manager uid cn mail departmentnumber sn email deptNumber lastname DB2 Universal Database shortname Tivoli Directory Server uid cn mail departmentnumber sn homepostaladdress employeenumber userpassword Content Manager name
homePostalAddress homeAddress employeenumber userpassword employeeNumber
122
Identity Manager telephoneNumber erroles manager st street title dn
DB2 Universal Database
Tivoli Directory Server telephonenumber group manager st street title dn
Content Manager
group
user dn
Note: The distinguished name used by Tivoli Identity Manager internally is different than the dn in the employee directory. For this example, the LDAP dn is generated based on a simple hard-coded mapping of the department number to a parent dn in the employee directory.
Organizational structure
Figure 3-5 depicts the LDAP organizational structure found in the Tivoli Directory Server on the Directory node shared by the user provisioning, HR, and document management applications.
123
LDAP Suffix
dc=itso,dc=ibm,dc=com
cn=users uid=admin Portal to LDAP bind user and WebSphere Application Server Administrator uid=wpsbind uid=hrmanager1 uid=hrspecialist1 uid=devmanager1 uid=legal1 uid=supervisor1 uid=publisher1
cn=groups cn=wpsadmins Members: uid=admin cn=hrmanagers Members: uid=hrmanager1 cn=hrspecialists Members: uid=hrspecialist1 cn=devmanagers Members: uid=devmanager1 cn=A_Legals Members: uid=legal1 cn=A_Supervisors Members: uid=supervisor1 cn=A_Publishers Members: uid=publisher1 cn=A_Researchers Members: uid=researcher1 uid=researcher2 HR Application User Groups Portal Administrator Group
uid=researcher1
Document Management Application User Groups
uid=researcher2 uid=itim manager
TIM Administrator
Figure 3-5 ITSO organizational structure within LDAP directory
User provisioning walkthrough

Figure 3-6 provides a walkthrough of the ITSO user provisioning scenario. We will start at the point where a new employee has self-registered and the provisioning request is pending approval in Tivoli Identity Manager by the HR manager: 1. The HR Manager assigns roles for the new employee and approves the registration request.
124
After the HR Manager has logged into the system, the HR manager will assign roles and approve the provisioning request from the Accept New Employee page of the user provisioning portlet application.
Content Management CM Resource Manager CM Library Server rmdb icmnlsdb 4c Create CM user via TDI CM custom connector Create LDAP user via TDI LDAP connector 4b Portal Server User provision war - portlets 1 Doc Mgt war - portlets TIM provisioning HR war - portlets request approved HR ear - servlets, EJBs and roles assigned 4a HR Update HR database record via TDI database connector Directory Tivoli Directory Server Tivoli Directory Integrator 4 Provision user via TDI Assembly Lines (AL) Database AL LDAP AL CM AL ldapdb
Client Web Browser
Access Manager TAM Authorization TAM Policy TIM Agent for TAM Create TAM user in TAM Policy Server via TIM Agent Identity Manager Tivoli Identity Manager 2 Create account in TIM 3 Execute policies 3d
3a Database policy TAM policy
3b 3c LDAP policy CM policy
Figure 3-6 User provisioning walkthrough
2. The approval of the provisioning request will create an account in Tivoli Identity Manager. 3. Based on the roles assigned to the user being provisioned, TIM policies will be executed: a. The TIM database policy will be run, which will send a request to the Tivoli Directory Integrator (TDI) database Assembly Line (AL).
125
b. The TIM LDAP policy will be run, which will send a request to TDI LDAP Assembly Line. c. The TIM DB2 Content Manager policy will be run, which will send a request to TDI DB2 Content Manager Assembly Line. d. The TAM policy will be run, which will initiate a request to the TIM Agent for TAM to create the user in Tivoli Access Manager. 4. Provision users via TDI Assembly Lines: a. The TDI database Assembly Line will invoke the TDI database connector to update a record with employee information in the HR database on the Portal Server node. b. The TDI LDAP Assembly Line will invoke the TDI LDAP connector to create a user in the LDAP directory on the Directory node. When the user is created, they will be added to the appropriate groups based on the role assignment. c. The TDI DB2 Content Manager Assembly Line will invoke the TDI custom DB2 Content Manager connector to create a user in DB2 Content Manager on the Content Management node with the ClientUserEditSSO privilege set. When the user is created, they will be added the to appropriate groups based on the role assignment. There are a few additional points we would like to highlight with the ITSO identity and access management system architecture: When unauthenticated new employees access the user provisioning application to self-register, the request is sent to TIM pending approval. In order to access TIM, we included a TIM user ID and password in a properties file. We were not able to use the WebSphere Portal Credential Vault since this requires an authenticated user. The use of a password in a properties file is not an ideal scenario and should be used with special care, such as encrypting the password within the file. The user provisioning portlet used to create a approve and assign roles by an HR manager for an employee requires a special administrator user ID retrieved from the WebSphere Portal Credential Vault with the proper access to Tivoli Identity Manager. Authorization to resources are managed by roles within WebSphere Portal, Tivoli Identity Manager, and Tivoli Access Manager. Within DB2 Content Manager groups are used.
126
3.4.4 Runtime topology and product mapping

Figure 3-7 depicts the Entry runtime topology used for the ITSO runtime environment and product mapping implemented for the redbook. We chose this configuration because it allow us to demonstrate the key configuration issues with components installed on separate nodes, without having too many nodes in the environment that would be beyond what someone could implement for a prototype, test environment, etc. Note: For more information, refer to 2.1.5, Runtime environment topology selection on page 24.
Outside zone
Demilitarized zone
Production zone
Client
I N T E R N E T
Content Management
(cmwin1)
DB2 Content Manager 8.3 (Library Server, Resource Manager, System Admin Client) DB2 Content Manager Client for Windows 8.3 WebSphere Application Server 5.1.1 IBM HTTP Server 1.3.28 DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Figure 3-7 ITSO runtime environment and product mapping
The implementation details are described in the following chapters: Chapter 4, Runtime environment installation on page 129 Chapter 5, Runtime environment configuration on page 235
Protocol Firewall
Domain Firewall
Reverse Proxy
(wswin1)
Portal Server
(wpwin1)
Directory
(tdiwin1)
Access Manager
(tamwin1)
Identity Manager
(timwin1)
127
3.4.5 Development environment topology and product mapping

Depending on the size of the project development team, the development functions may be split across several different roles. In our example, we needed a development environment in which we could develop the following four types of applications: User provisioning portlet application HR application (portlet front-end, EJB back-end) Document management application Identity Manager policies/workflow and TDI Assembly Lines/connectors While writing this redbook, we split the work among the various authors and used each of the development topologies described in 2.1.6, Development environment topology selection on page 30. Finally, we used the procedures in Development topology 6: Develop and test end-to-end on page 37 to verify the development and testing of all applications used for our working example. The implementation details are described in the following chapter: Chapter 6, Development environment installation on page 339
128
Chapter 4.
Runtime environment installation

This chapter describes how to install the software components for each node of the ITSO identity and access management system. Although there are some configuration tasks in this chapter, the majority of the integration configuration can be found in Chapter 5, Runtime environment configuration on page 235. The procedures documented are intended to be used in conjunction with the product installation guides. The value-add of the ITSO working example runtime implementation is three-fold. First, we provide detailed procedures to install the software by node. Second, we provide sample values to help put in context the information found in the product guides. Third, we include best practices and tips. This chapter is organized into the following sections: Planning Directory node installation Access Manager node installation Reverse Proxy node installation Identity Management node installation Content Management node installation Portal Server node installation
129
4.1 Planning
This section describes the runtime topology for the ITSO identity and access management system. In addition, this section provides information regarding the hardware and software levels we used to implement the runtime environment. The ITSO runtime environment consists of the following six nodes (see Figure 4-1 on page 130): Directory node Access Manager node Reverse Proxy node Identity Management node Content Management node Portal Server node Note: We do not include procedures for implementing the firewalls depicted in Figure 4-1.
Outside zone
Demilitarized zone
Production zone
W ebSphere Portal 5.1
Client
I N T E R N E T
Tivoli Access Manager 5.1 + FP9 (Runtime, PDJRTE, Web Security, W ebSEAL) Tivoli Directory Client 5.2 + FP2 IBM GSKit 7.0.3.8 IBM JRE 1.3.1 Windows 2000 Server + SP4
Content Management
(cmwin1)
DB2 Content Manager 8.3 (Library Server, Resource Manager, System Admin Client) DB2 Content Manager Client for Windows 8.3 W ebSphere Application Server 5.1.1 IBM HTTP Server 1.3.28 DB2 UDB V8.2 ESE + FP8 W indows 2000 Server + SP4
Figure 4-1 ITSO identity and access management runtime environment and product mapping
Protocol Firewall
Domain Firewall
Reverse Proxy
(wswin1)
Portal Server
(wpwin1)
Directory
(tdiwin1)
Access Manager
(tamwin1)
Identity Manager
(timwin1)
130
Note: In 3.4.4, Runtime topology and product mapping on page 127, we described possible runtime topologies. In our example, we chose to implement the Entry runtime topology, to reduce the number of nodes required to set up the environment. It is possible that software components can be further compacted to fewer nodes. We concluded that the Entry runtime topology we have defined allows us to demonstrate the key configuration tasks required of an IT specialist.
4.1.1 Hardware and software prerequisites

For detailed and official product information on the hardware and software requirements, we recommend that you refer to the product planning and installation guides.
4.1.2 Hardware used within the ITSO runtime environment

We used the following hardware to implement the nodes of the ITSO identity and access management system runtime environment on the Microsoft Windows 2000 Server platform: Directory node: IBM eServer xSeries 230 (8658-61Y) 1 CPU, Intel PIII 1 GHz 1 GB RAM 18 GB Ultra SCSI Hard Disk 1 Ethernet Adapter (IBM NetFinity Fault Tolerance PCI) Hostname: tdiwin1.itso.ral.ibm.com Access Manager node: IBM eServer xSeries BladeCenter HS20 1 CPU, Intel Xeon 2.4 GHz 1 GB RAM 40 GB Hard Disk 1 Ethernet Adapter (Broadcom NetXtreme Gigabit Fiber) Hostname: tamwin1.itso.ral.ibm.com Reverse Proxy node: IBM eServer xSeries 230 (8658-61Y) 1 CPU, Intel PIII 1 GHz 512 MB RAM 18 GB Ultra SCSI Hard Disk 1 Ethernet Adapter (IBM NetFinity Fault Tolerance PCI) Hostname: wswin1.itso.ral.ibm.com
Chapter 4. Runtime environment installation
131
Identity Management node: IBM eServer xSeries 225 (8647-5AX) 1 CPU, Intel Xeon 2.8 GHz 1 GB RAM 18 GB Ultra SCSI Hard Disk 1 Ethernet Adapter (Broadcom NetXtreme Gigabit Ethernet) Hostname: timwin1.itso.ral.ibm.com Content Management node: IBM eServer xSeries BladeCenter HS20 1 CPU, Intel Xeon 2.4 GHz 1 GB RAM 40 GB Hard Disk 1 Ethernet Adapter (Broadcom NetXtreme Gigabit Fiber) Hostname: cmwin1.itso.ral.ibm.com Portal Server node: IBM eServer xSeries 225 (8647-5AX) 1 CPU, Intel Xeon 2.8 GHz 1280 MB RAM 18 GB Ultra SCSI Hard Disk 1 Ethernet Adapter (Broadcom NetXtreme Gigabit Ethernet) Hostname: wpwin1.itso.ral.ibm.com
4.1.3 Software used within the ITSO runtime environment

The ITSO identity and access management system runtime was implemented using the software levels listed by node in Table 4-1 through Table 4-6.
Table 4-1 Directory node Software Microsoft Windows 2000 Server IBM GSKit IBM HTTP Server IBM WebSphere Application Server IBM DB2 UDB, Enterprise Server Edition Version 2000 + Service Pack 4 7.0.3.8 1.3.26.2 Note: WAS 5.0 + Fixpack 2 5.0.2 Note: 5.0 + Fixpack 2 8.1.8.762 Note: 8.2 + Fixpack 8
132
Software IBM Tivoli Directory Server * Server * Client SDK * Web Administration Tool IBM Tivoli Directory Integrator IBM DB2 Information Integrator for Content Table 4-2 Access Manager node Software Microsoft Windows 2000 Server IBM GSKit IBM Java Runtime Environment (JRE) Tivoli Directory Client SDK IBM HTTP Server IBM WebSphere Application Server IBM Tivoli Access Manager for e-business * Access Manager Runtime * Access Manager Policy Server * Access Manager Authorization Server * Access Manager Java Runtime Environment * Access Manager Web Portal Manager IBM Tivoli Identity Manager Agent for Tivoli Access Manager Table 4-3 Reverse Proxy node Software Microsoft Windows 2000 Server IBM GSKit IBM Java Runtime Environment (JRE) IBM Tivoli Directory Client SDK
Version 5.2 + Fixpack 2
6.0 + Fixpack 1 8.3
Version 2000 + Service Pack 4 7.0.3.8 1.3.1 5.2 + Fixpack 2 1.3.26.2 Note: WAS 5.0 + Fixpack 2 5.0.2 Note: 5.0 + Fixpack 2 5.1.0.9 Note: 5.1 + Base Fixpack 9
4.5.9
Version 2000 + Service Pack 4 7.0.3.8 1.3.1 5.2 + Fixpack 2
133
Software IBM Tivoli Access Manager for e-business * Access Manager Runtime * Access Manager Java Runtime Environment * Access Manager Web Security Environment * Access Manager WebSEAL Table 4-4 Identity Manager node Software Microsoft Windows 2000 Server IBM DB2 UDB, Enterprise Server Edition IBM GSKit IBM Tivoli Directory Server * Server * Client SDK IBM HTTP Server IBM WebSphere Application Server IBM Tivoli Identity Manager
Version 5.1.0.9 Note: 5.1 + WebSEAL Fixpack 9 + Base Fixpack 9
Version 2000 + Service Pack 4 8.1.8.762 Note: 8.2 + Fixpack 8 7.0.3.8 5.2 + Fixpack 2
1.3.28 5.1 4.5.1 + FP42 Note: 4.5.1 FP16 full install + FP42
Table 4-5 Content Management node Software Microsoft Windows 2000 Server IBM DB2 UDB, Enterprise Server Edition IBM Tivoli Directory SDK IBM HTTP Server IBM WebSphere Application Server IBM DB2 Content Manager, Enterprise Edition IBM DB2 Content Manager Client for Windows Version 2000 + Service Pack 4 8.1.8.762 Note: 8.2 + Fixpack 8 5.2 + Fixpack 2 1.3.28 5.1.1 8.3 8.3
134
Table 4-6 Portal Server node Software Microsoft Windows 2000 Server IBM WebSphere Portal IBM HTTP Server IBM WebSphere Application Server IBM Java Runtime Environment (JRE) IBM Tivoli Access Manager for e-business * Access Manager Java Runtime Environment IBM DB2 UDB, Enterprise Server Edition IBM DB2 Information Integrator for Content IBM Tivoli Identity Manager * API jars Version 2000 + Service Pack 4 5.1 1.3.28 5.1.1.1 1.3.1 5.1.0.9 Note: 5.1 + Base Fixpack 9 8.1.8.762 Note: 8.2 + Fixpack 8 8.3 4.5.1 + FP42
4.2 Directory node installation

The Directory node installation includes the following tasks: 1. 2. 3. 4. 5. 6. 7. 8. 9. Windows 2000 Server installation DB2 Universal Database V8.2 installation IBM GSKit installation WebSphere Application Server V5.0.2 installation Tivoli Directory Server V5.2 installation Tivoli Directory Server configuration Tivoli Web Administration Tool configuration Tivoli Directory Integrator installation DB2 Information Integrator for Content installation
4.2.1 Windows 2000 Server installation

This section highlights the key issues addressed when installing Microsoft Windows 2000 Server, such as using Windows 2000 Service Pack level 4.
Windows 2000 Service Pack 4

In our example, we installed Windows 2000 Service Pack 4.
135
Windows 2000 service levels

We installed the latest Windows 2000 service level critical updates on top of Service Pack 4.
Create admin user and assign user rights

To assign user rights for the administrator ID, do the following steps: 1. Log on to Windows as an administrator. 2. Create a user ID and add the user to the administrators group (for example, we created a user called admin). Alternatively, use an existing administrator user. 3. Click Start Settings Control Panel Administrative Tools Local Security Policy. 4. From the Local Security Settings window, select and expand Local Policies User Rights Assignment. 5. Ensure that the administrator user ID (for example, admin) has user right assignments for the following Windows Local Security Policies needed for DB2 and WebSphere Portal as seen in Table 4-7.
Table 4-7 Windows Local Security Policies Security Policy DB2 X X X X X WebSphere Portal X X na na na
Act as part of the operating Log on as a service Create a token object Increase quotas Replace a process-level token
6. Log on as the administrator user ID created and rights assigned (for example, admin).
Verify network configuration

Prior to installing the software components, it is important that you verify that your network is configured properly. We recommend that you use a static TCP/IP address and verify that the hostname can be resolved with the name server. For example, we did the following commands from a command window:
ping <hostname> ping <ip_address> nslookup <hostname> nslookup <ip_address>
136
Ensure that the fully qualified hostname is returned if resolved by a domain name server. Alternatively, you may be using a host file for an environment such as development (use ping instead of nslookup).
4.2.2 DB2 Universal Database V8.2 installation

There are a couple of key points to pass along with the level of DB2 Universal Database: DB2 Universal Database V8.2 internally is V8.1.7.445 (db2level). This is the equivalent to IBM DB2 Universal Database V8.1 + Fixpack 7. DB2 Universal Database V8 Fixpack V7a or higher can be applied to DB2 Universal Database V8.2. For compatibility reasons, it is recommended that the DB2 Universal Database clients and servers use the same level. The application software may require a specific level of DB2 Universal Database. Attention: For our scenario, we have standardized on IBM DB2 Universal Database V8.2, Enterprise Server Edition + Fixpack 8.
Install DB2 Universal Database V8.2

To install IBM DB2 Universal Database V8.2, Enterprise Server Edition, do the following steps: 1. To start the DB2 Universal Database installation, run setup.exe. 2. When the Welcome to DB2 dialog appears, click Install Product. 3. Select DB2 UDB Enterprise Server Edition and then click Next. Note: In IBM DB2 Universal Database V8.2, Enterprise Server Edition only the DB2 UDB Enterprise Server Edition option is available. The DB2 UDB Enterprise Server Edition does include a DB2 UDB Client. If you desire to install only the DB2 Universal Database Client Runtime, you will need to launch the Client install from a separate DB2 Universal Database Client Runtime CD. 4. When the Welcome dialog appears, click Next. 5. When the license agreement appears, review the conditions and select I accept the terms in the license agreement, and then click Next.
137
6. When Select the installation type dialog appears, select Typical (default), and then click Next. 7. When the Select the installation action dialog appears, we accept the default and clicked Next. 8. When the Select installation folder dialog appears, we entered C:\IBM\SQLLIB and click Next. 9. When the Set user information for the DB2 Administration Server dialog appears, we entered the following information and then clicked Next: Domain: left blank User name: db2admin Password: <db2admin_password> Confirm password: <db2admin_password> Check Use same user name and password for the remaining DB2 services. 10.When the Set up administration contact list dialog appears, we accepted the default (Local) and clicked Next. 11.When the Warning message, Notification SMTP server has not been specified, appeared, we clicked OK to continue. 12.When the Configure DB2 instances dialog appears, we accepted the default DB2 protocols and clicked Next. 13.When the Prepare the DB2 tools catalog dialog appeared, we selected Do not prepare the DB2 tools catalog on this computer, and then clicked Next. 14.When the Specify a contact for health monitor notification dialog appears, we selected Defer the task until after installation is complete, and then clicked Next. 15.When the Start copying files dialog appears, we reviewed the selections and then clicked Install to begin copying files. 16.When the Setup is complete dialog appeared, we clicked Finish. Note: After the installation of DB2 Universal Database is complete, you will be prompted to install updates. In our example scenario, we declined to install the DB2 updates, since we will install DB2 Universal Database V8 Fixpack 8 in the next section and wanted to have a known level of DB2 for all of our systems. 17.When the First Steps dialog appeared, we clicked Exit First Steps.
138
Install DB2 Universal Database V8 Fixpack 8

To install IBM DB2 Universal Database V8 Fixpack 8, do the following steps: Note: For more information regarding the contents of the IBM DB2 UDB V8 Fixpack 8, refer to the FixpackReadme.txt, which can be found at:
http://www.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v8fphis t.d2w/report#WIN-32
1. Stop DB2 Universal Database Windows services and the system tray. a. Although the Fixpack installer will attempt to stop the DB2 Windows services before installing, we recommend that you manually stop all DB2 services before starting the Fixpack install. b. Close the DB2 system tray before launching the fixpack installer. 2. Download the IBM DB2 UDB V8 Fixpack 8:
http://www.ibm.com/software/data/db2/udb/support/downloadv8W32fp8.html
DB2 UDB Enterprise Server: FP8_WR21348_ESE.exe or DB2 UDB Run-Time Client: FP8_WR21348_RTLC.exe 3. After unpacking the fixpack, run setup.exe to start the fixpack installer. 4. From the Setup dialog, click Install Products. 5. We accepted the default installation options. 6. When the installation is complete, you will be prompted to restart your system for the updates to take effect. Click Yes. 7. After restarting the system, the First Steps dialog will appear. Click Exit First Steps. 8. The internal DB2 level after the installation Fixpack 8 should be 8.1.8.762. In our example, we do not have any existing databases that need special attention (rebind DB2 utilities) since this is a pristine installation. After the system has restarted, open a DB2 command window (or Windows command window) and enter the following command:
db2level
It should return 8.1.8.762 after Fixpack 8 has been installed.
139
Note: Rebind DB2 utilities to existing databases. For more detailed information, refer to the DB2 Universal Database fixpack readme. If you have created databases before you installed the fixpack, you will need to rebind the DB2 utilities to the databases. This step is necessary for the fixes to become effective on an existing database. The binding procedure needs to be performed only once per database. Note that this is not required for database created after the fixpack is installed. We have summarized the rebind procedure found in the FixpackReadme.txt. To rebind existing DB2 UDB databases after installing the fixpack, enter the following commands from a DB2 command window for each database:
db2 terminate db2 CONNECT TO <dbname> db2 BIND <DB2_home>\BND\@db2ubind.lst GRANT PUBLIC db2 BIND <DB2_home>\BND\@db2cli.lst GRANT PUBLIC db2 BIND <DB2_home>\BND\db2schema.bnd BLOCKING ALL GRANT PUBLIC sqlerror continue
Where <dbname> represents the name of a database to which the utilities should be bound. Where <DB2_home> represents the directory where you have installed DB2. The db2ubind.lst and db2cli.lst contain lists of required bind files used by DB2 Universal Database.
4.2.3 IBM GSKit installation

This section describes how to obtain and install IBM GSKit V7.0.3.8. The GSKit is used to manage keystores and certificates. The GSKit includes the IBM Key Management utility and libraries accessible to applications to create and manage certificates. In addition, we describe how to configure the GSKit such that the IBM Key Management Utility can be run (requires JRE). There are several reasons that we need the new GSKit for the ITSO example runtime environment. First, the GSKit V7.0.1.9 included with the Tivoli Directory Server V5.2 includes root certificates that have expired. For this reason, users will not be able to create a new keystore using the iKeyman utility. Second, the updated IBM GSKit is a prerequisite for the Tivoli Access Manager V5.1 Base Fixpack 9. In addition, the IBM GSKit V7.0.3.8 includes many fixes.
140
Determine GSKit version installed

This section describes how to determine the version of GSKit an application is configured to use in the Windows registry. If you are following the order of installing components documented in this chapter, this section is not necessary, since we will install the new GSKit prior to installing components that use it. Note: The GSKit version can be obtained by using the gsk7ver.exe command or by retrieving the version from the Windows registry. We chose to use the Windows registry method, since we also needed the REGAPPS value in addition to the version. If you have not installed Tivoli Directory Server or other software containing the IBM GSKit, you can skip this section. To determine the level of the GSKit installed, do the following steps: 1. Start the Windows registry editor (regedit.exe) by clicking Start Run and entering regedit in the Open field, and then clicking OK. 2. Select and expand HKEY_LOCAL_MACHINE SOFTWARE IBM. 3. In our example, you will see both the GSK5 and GSK7 registry entries. 4. Select GSK7 CurrentVersion. Record the data value for the version name. 5. Select REGAPPS under the CurrentVersion. This will list the name of the application using the GSKit. Record the name of the application using this version of the GSKit (for example, LDAP).
Uninstall old GSKit

If you are following the ITSO procedure, this section is not required. Prior to installing the new IBM GSKit, if a GSKit already has been installed, you must manually uninstall the existing IBM GSKit as follows: 1. Ensure that the IBM Tivoli Directory Server V5.2 Windows service has been stopped, as well as other services that may be using the GSKit. 2. Open a command window and navigate to the c:\winnt directory. 3. Run the following command to uninstall the GSKit:
gsk7bui LDAP
Where LDAP is the name of the application using the GSKit recorded. 4. Verify that the GSK7 Windows registry has been removed. 5. Verify that the GSK7 directory has been removed (for example, C:\IBM\GSK7).
141
Note: If files still exist, such as DLLs, manually delete the C:\IBM\GSK7 directory after the services that locked the files have been stopped.
Note: If you have previously installed applications that use the old GSKit V7.0.1.9, they may have updated the system path to include the GSKit installation path. If you decided to change the default GSKit installation path, you may need to manually update the system path to include the correct GSKit installation path. For example, our procedure is now in such an order that this problem will not be an issue, but when we initially set up our environment, we had already installed the Tivoli Access Manager Policy Server and Authorization Server. These Windows services are started by the Access Manager Auto-Start Service, which looks for the GSKit in the system path. If the GSKit path is not correct, the services will not start. After updating the system path in the Windows environment, you will need to restart your system.
Install GSKit V7.0.3.8

To download and install the IBM GSKit V7.0.3.8, do the following steps: 1. To obtain the IBM GSKit V7.0.3.8, you will need to contact IBM support:
http://techsupport.services.ibm.com/guides/tivoli_contacts.html
2. Depending on the source of the IBM GSKit 7.0.3.8, you may have to first unzip the download zip. After the unzip, you should have a gsk7bas.exe file. 3. Enter the following command at the command line to extract the GSKit (gsk7bas.exe) to a temporary directory:
gsk7bas c:\temp
Where c:\temp is the directory to which to extract the GSKit installation files. 4. From the command window, navigate to the directory where you have extracted the GSKit installation files (for example, c:\temp). 5. Run the GSKit installer as follows:
setup <application_name>
Where <application_name> is the name of the application using GSKit V7.0.3.8. For example: Tivoli Directory Server application_name: LDAP Tivoli Access Manager WebSEAL application name: policydirector
142
6. When the Welcome window appears, click Next. 7. When the Choose Destination Location window appears, we entered c:\ibm\gsk7 for the destination folder from the Browse button. Click Next to proceed. 8. When the setup is complete, click Finish.
4.2.4 WebSphere Application Server V5.0.2 installation

This section describes how to install WebSphere Application Server V5.0 and Fixpack 2 (V5.0.2).
Install WebSphere Application Server V5.0

To install the WebSphere Application Server V5.0, do the following steps: 1. Insert the WebSphere Application Server CD. 2. Navigate to the <CD_Root> directory and run Install.exe to start the WebSphere Application Server installer. 3. When the Select the desired language to be used for the installation wizard appears, select the desired language (for example, English) and click OK. 4. When the Welcome page appears, click Next. 5. When the License Agreement page appears, review the terms and select I accept the terms in the license agreement, and then click Next. 6. When the Setup Type window appears, select Custom and click Next. 7. When the Features Selection window appears, we selected the features displayed in Figure 4-2 and then clicked Next.
143
Figure 4-2 WebSphere Application Server - selected features
8. When the Features Installation directories window appears, we entered the following information and then clicked Next: WebSphere Application Server: C:\WebSphere\AppServer IBM HTTP Server: C:\IBMHttpServer
144
9. When the Node name and Host name window appears, we entered the following information and then clicked Next: Node name: <node_name> For example, we entered tdiwin1 for the node name on the Directory node. Host name or IP Address: <fully_qualified_host_name> For example, we entered tdiwin1.itso.ral.ibm.com for the host name on the Directory node. 10.When the Windows Services window appears, we entered the following information and then clicked Next: Deselect Run WebSphere Application Server as a service Select Run IBM HTTP Server as a service User ID: admin Password: <password>
11.When the Installation Summary window appears, review your selections and then click Next to begin copying files. 12.When the Register window appears, take the appropriate action. 13.When the First Steps window appears, click Exit. 14.Click Finish on the Installation Wizard page.
Install WebSphere Application Server V5 Fixpack 2 (V5.0.2)

To install the IBM WebSphere Application Server V5 Fixpack 2, do the following steps: 1. Ensure that you have stopped all WebSphere Application Server, application servers and nodes. 2. Ensure that you have stopped the IBM HTTP Server and IBM HTTP Administration Windows service (WebSphere plug-in fixes). Note: The Fixpack will attempt to update the IBM HTTP Server and will not be able to update the server if it is started. 3. Download WebSphere Application Server V5 Fixpack 2 at:
http://www.ibm.com/support/docview.wss?rs=860&context=SW600&q1=fixpack+2&ui d=swg24005012&loc=en_US&cs=utf-8&lang=en+en
4. Unpack the WebSphere Application Server V5 Fixpack 2 to a temporary directory on the target system (for example, c:\temp\was5.fp2). Note that the WebSphere Update Installer Wizard needs write access.
145
5. Open a command window, and set the JAVA_HOME by running the following command provided with WebSphere Application Server:
C:\WebSphere\AppServer\bin\setupCmdLine.bat
6. From the command window, start the WebSphere Installation Update Wizard by entering updateWizard.bat found in the temporary directory (for example, c:\temp\was5.fp2). 7. When the WebSphere Update Installer language window appears, select the appropriate language for the wizard (for example, English) and then click OK. 8. When the Welcome window appears, click Next. 9. The WebSphere Update Installer should detect your current WebSphere Application Server version and installation directory (for example, C:\WebSphere\AppServer). Click Next. 10.Select Install fix packs and then click Next. 11.Enter the directory where you have copied the fixpack. For example, we entered c:\temp\was5.fp2\fixpacks in the Fix pack directory text field, and then clicked Next. 12.Select the was50_fp2_win fixpack (default) and then click Next. 13.You will be prompted for the directories for the IBM HTTP Server and the WebSphere Application Server Embedded Messaging (not installed), we entered the following information and then clicked Next: Check IBM HTTP Server IBM HTTP Server installation directory: c:\IBMHttpServer Uncheck Embedded Messaging (not installed) 14.Review the fixpack settings and then click Next to begin the fixpack installation of files. 15.When the WebSphere Application Server V5 Fixpack 2 installation is complete, click Finish.
Verify WebSphere Application Server V5.0.2

To verify the functionality of the WebSphere Application Server V5.0.2 after installation, do the following steps: 1. Verify the WebSphere Application Server installation by clicking Start Programs IBM WebSphere Application Server V5.1 First Steps. 2. From First Steps, click Verify Installation. If the server is not started, it will start the server and perform some tests. You will see console output with the status of each test run - passed.
146
Note: Alternatively, you can start the Install Verification by opening a command prompt, navigating to the <was_home>\bin directory, and running ivt.bat. 3. After completing the Verify Installation, click Exit from the First Steps page. 4. Ensure that the IBM HTTP Server (WebSphere plug-in) is started. 5. Ensure that the server1 application server is started. If not, start the server as follows:
cd \WebSphere\AppServer\bin startServer server1
Note: Review the status of the server startup in the startServer.log. You should see the following message:
Server server1 open for e-business
The server1 directory will not get created until the first time the application server is started. 6. Start the WebSphere Application Server Administration Console, by entering the following URL in a Web browser:
http://<was_hostname>:9090/admin
7. Logon to the WebSphere Administration Console (for example, admin). 8. When done verifying the WebSphere Administration Console, click Logout and close the Web browser. 9. Stop the server1 application server as follows:
cd \WebSphere\AppServer\bin stopServer.bat server1
4.2.5 Tivoli Directory Server V5.2 installation

This section describes how to install and configure the Tivoli Directory Server V5.2 and Fixpack 2. This procedure will be common for the Directory node and the Identity Manager node. The only exception is that on the Identity Manager node, we will not install the Tivoli Directory Server Web Administration Tool.
147
Important: When using Tivoli Directory Server V5.2 Configuration Tool + Fixpack 2, and DB2 Universal Database V8.2 + Fixpack 7a, we were not able to create the LDAP database. In addition, the log of the previous failure displayed instead of the configuration options and there was no way to clear the log. To work around this issue, we had to first uninstall the Tivoli Directory Server V5.2, re-install Tivoli Directory Server, install DB2 Universal Database V8.2 + Fixpack 8, and then create the Tivoli Directory Server LDAP database. If you follow the procedure documented in this section, you will not have this problem, since we install the proper component levels in an order that avoids the problem.
Create DB2 database owner

In our example, we granted the admin user the proper right assignments for a DB2 user (see Create admin user and assign user rights on page 136). No other action is needed.
Install Tivoli Directory Server

To install the Tivoli Directory Server V5.2, do the following steps: 1. Navigate to the ismp folder of the Tivoli Directory Server CD, and run Setup.exe to start the install. 2. Select the installer language (for example, English), which is separate from the Tivoli Directory Server language. Click OK. 3. When the Welcome page appears, click Next. 4. When the License Agreement page appears, review the terms and if in agreement select I accept the terms in the license agreement and then click Next. 5. A page will display existing components. In our example, we have pre-installed the IBM GSKit and IBM DB2 UDB. Click Next. 6. We installed Tivoli Directory Server in the C:\IBM\LDAP directory. 7. Select the Tivoli Directory Server language (for example, English) and click Next. 8. When the Select Features to install window appears, we selected the following options as seen in Figure 4-3, and then click Next. Check Client SDK 5.2. Check Web Administration Tool 5.2.
148
Note: In our scenario, there are two different installations of Tivoli Directory Server V5.2 with slightly different features selected. On the Directory node, we will install the Tivoli Directory Server Web Administration Tool. On the Identity Manager node, we chose not to install the Web Administration Tool to avoid WebSphere Application Server V5.0.2 and V5.1 compatibility issues (IBM Tivoli Directory Server V5.2 requires WebSphere Application Server V5.0.2, and IBM Tivoli Identity Manager V4.5.1 requires WebSphere Application Server V5.1.1). Check Server 5.2. Uncheck IBM WebSphere Application Server - Express 5.0. Note: We will use WebSphere Application Server instead of Express Edition, since it does not support WebSphere Security. Uncheck DB2 V8.1. Note: A newer level of DB2 UDB has already been installed. Uncheck GSKit. Note: A newer level of the GSKit has already been installed.
Figure 4-3 Tivoli Directory Server - select features
149
9. When the Installation Summary page appears, review the selections and click Next to begin installing files. 10.When the installation complete, review the readme files for the Client and Server and click Next. 11.When prompted, select Yes, restart my computer and click Next. Click Finish. 12.After restarting the 1st time, the Tivoli Directory Server Configuration Tool will be launched. Close the tool.
Install Tivoli Directory Server V5.2 Fixpack 2

To install the Tivoli Directory Server V5.2.0-TIV-ITDS-FP0002, do the following steps: 1. Ensure that the following Tivoli Directory Server Windows services are stopped. IBM Tivoli Directory Admin Daemon V5.2 IBM Tivoli Directory Server V5.2 2. Download the Tivoli Directory Server V5.2.0-TIV-ITDS-FP0002 at:
http://www.ibm.com/support/docview.wss?rs=767&context=SSVJJU&dc=D400&q1=fix pack&uid=swg24008502&loc=en_US&cs=utf-8&lang=en
3. Unpack the 5.2.0-TIV-ITDS-Win32-FP0002.zip. 4. Open a command window and navigate to the 5.2.0-TIV-ITDS-Win32-FP0002 folder and run install_update.bat to start the fixpack install. 5. You will be prompted to stop the Tivoli Directory Server and Admin Daemon, which we have already stopped in our procedure. Press Enter to continue. 6. When the fixpack installation is complete, you will see a message regarding how the previous version can be restored. Press Enter to complete the installation. 7. Start the IBM Tivoli Directory Admin Daemon V5.2 Windows service.
4.2.6 Tivoli Directory Server configuration

After installing the Tivoli Directory Server V5.2 and applying Fixpack 2, you will need to configure the directory server.
Start the Tivoli Directory Server Configuration Tool

During the first restart of your system after the Tivoli Directory Server installation, the Tivoli Directory Server - Configuration Tool will be launched automatically.
150
Alternatively, start the Directory Configuration tool by clicking Start Programs IBM Tivoli Directory Server V5.2 Directory Configuration.
Set the administrator DN and password

To set the administrator distinguished name (DN) and password using the Tivoli Directory Server Configuration Tool, do the following steps: 1. Select Administrator DN/password under choose a task. 2. Enter the Administrator DN and password and click OK. Administrator DN: cn=root Password: <root_password> 3. When prompted with Administrator DN and password successfully updated, click OK.
Create and configure the directory database

To create and configure the Tivoli Directory Server directory database from the Tivoli Directory Server - Configuration Tool, do the following steps: 1. Click Configure database under choose a task. 2. Select Create a new database and then click Next. 3. When the Configure database - user ID page appears, enter the User ID and password created in Create admin user and assign user rights on page 136 (for example, admin) and then click Next. 4. When the Configure database - database name page appears, enter the database name to be created (for example, ldapdb) and click Next. 5. When the Configure database - database code page selection appears, select Create a universal DB2 database (UTF-8/UCS-2) and click Next. 6. When the Configure database - database location appears, select the drive (for example C) and click Next. 7. When the Configuration Summary page appears, review selections and click Finish. 8. During the configuration the configuration status will be displayed. Notice that a DB2 instance is created with the name of the user designated as the DB2 owner (for example, admin). You should see the following messages if successful:
Configured IBM Tivoli Directory Server Database. IBM Tivoli Directory Server Configuration complete.
When complete, click Close.
151
4.2.7 Tivoli Web Administration Tool configuration

For the ITSO working example, we chose to install the Web Administration Tool on WebSphere Application Server V5.0.2, which is capable of being configured for WebSphere Application Server security.
Deploy Web Administration Tool

To deploy the Web Administration Tool on the WebSphere Application Server server1, do the following steps: 1. Ensure that the WebSphere Application Server - server1 is started. If not, start server1 as follows:
<was_home>\bin\startServer server1
2. Start WebSphere Application Server Administration Console by entering the following URL in a Web browser:
http://<hostname>:9090/admin
3. Logon to the Administration Console (for example, admin). 4. Click Applications Install New Application in the console navigation tree. 5. When the Preparing for application installation page appears, do the following and then click Next: Path: select Local path radio button Local Path: c:\ibm\ldap\idstools\IDSWebApp.war This is the full path of the Web Administration Tool application standalone IDSWebApp.war file. Note: The file can be either on the client machine (the machine that runs the Web browser) or on the server machine (the machine to which the client is connected). Context Root: /IDSWebApp 6. When the Generate bindings page appears, we accepted the default settings and clicked Next. 7. When the Step 1: Provide options to perform the installation page appears, we accepted the default settings and clicked Next: Application Name: IDSWebApp_war (default) 8. When the Step 2: Map virtual hosts for Web modules page appears, we entered the following information and then clicked Next: Virtual Host: Select default_host (default) Web Module: Check IBM Tivoli Directory Server Web Application v2.0
152
9. When the Step 3: Map modules to application servers page appears, we accepted the default and then clicked Next: 10.When the Step 4: Summary Review installation options page appears, click Finish. You should see a message like this:
Application IDSWebApp_war installed successfully.
11.When the configuration update is complete, click the Save to Master Configuration link. 12.When the Save to Master Configuration page appears, click Save. 13.Start the Tivoli Directory Server Web Administration Tool. a. From the Web Administration Tool click Applications Enterprise Applications. b. From the Enterprise Application page, check IDSWebApp_war and then click Start. 14.Logout of the WebSphere Application Server Administrative Console by clicking Logout.
Web Administration Tool configuration

This section describes how to configure the Tivoli Directory Server - Web Administration Tool.
Define the directory server node to the Web Administration Tool

To define the directory server with the Web Administration tool, do the following 1. Ensure that the WebSphere Application Server server1 is started. 2. Access the Web Administration Tool from a Web browser:
http://localhost:9080/IDSWebApp/IDSjsp/Login.jsp
3. From the Web Administration Tool, enter the following and then click Login: LDAP Hostname: select Console Admin from the drop-down list. Username: superadmin (default) Password: secret (default) 4. Modify the default Console Administration user ID and password. a. Select Console Administration Change console administration login. b. When the Change Console administrator logon appears, enter the following information and click OK:
153
Console administrator login: webadmin We created the administrator webadmin, but this could be any name you desire. Current password: <password> (default is secret)
c. Select Change console administrator password. Enter the current and new password. Click OK. 5. Add the Directory Server node. a. Click Console administration Manage console servers. b. Click Add. c. Enter the Directory Server hostname and change the port numbers if not using defaults and click OK. Directory node: or Identity Manager node: Hostname: timwin1.itso.ral.ibm.com Port: 389 Administration port: 3538 Uncheck SSL enabled (default). Hostname: tdiwin1.itso.ral.ibm.com Port: 389 Administration port: 3538 Uncheck SSL enabled (default).
You should see the new server listed after adding it.
d. Click Logout from the Web Administration Tool.
Verify administration to directory server

Now that the Web Administration Tool is configured for the directory server, we recommend that you verify if it is working properly by connecting to the directory server. 1. Ensure that the Tivoli Directory Server V5.2 Windows service is started. 2. Access the Tivoli Directory Server Web Administration Tool from a Web browser:
http://localhost:9080/IDSWebApp/IDSjsp/Login.jsp
3. From the Web Administration Tool, do the following and then click Login: Select the newly created server (for example, tdiwin1.itso.ral.ibm.com) from the drop-down list on the Login page. Username: cn=root Password: <password>
154
4. To start the Tivoli Directory Server, click Server administration Start/stop/restart server. 5. Click Start (do not Check Start / restart in configuration only mode). You should see the status message, Server started.
Change password encryption method

We recommend that you change the password encryption method from the default imask to SHA or crypt from the Web Administration Tool. The primary reason is that imask is a two way encoding format and both SHA and crypt are one way. We configured the password encryption as follows: 1. From the Web Administration Tool select Server administration Manage security properties. 2. From the Manage security properties page, click Password policy. 3. Select SHA from the Password encryption drop-down and then click OK at the bottom of the page.
4.2.8 Tivoli Directory Integrator installation

This section describes how to install the IBM Tivoli Directory Integrator V6.0 and Fixpack 1.
Install Tivoli Directory Integrator V6.0

To install Tivoli Directory Integrator V6.0, do the following steps: 1. From the IBM Tivoli Directory Integrator V6.0 CD, run setupwin32.exe to start the installer. 2. When the Welcome dialog appears, click Next. 3. When the License agreement dialog appears, select I accept the terms in the license agreement and click Next. 4. When the Install Directory dialog appears, we entered C:\IBM\DirectoryIntegrator and then clicked Next. 5. Create a directory in the ibm directory named tdiwork (for example, c:\ibm\tdiwork) prior to the next step. 6. When the Specify a working directory dialog appears, we selected Select a directory to use, we entered c:\ibm\tdiwork as the directory name as seen in Figure 4-4, and then we clicked Next.
155
Note: Manually create the c:\ibm\tdiwork directory prior to clicking Next. The installer will create an environment variable that references this directory.
Figure 4-4 Tivoli Directory Integrator working directory
7. When the Installation options summary dialog appears, review the selections and then click Next. 8. When the installation is complete, you should see a message that it was successfully installed. Click Finish.
Install Tivoli Directory Integrator V6.0 Fixpack 1

To download and install Tivoli Directory Integrator V6.0 Fixpack1, do the following steps: 1. Ensure that the Tivoli Directory Integrator Server is stopped. 2. Download the Tivoli Directory Integrator V6.0 Fixpack 1 at:
http://www.ibm.com/support/docview.wss?rs=697&context=SSCQGF&dc=D400&uid=sw g24009208&loc=en_US&cs=utf-8&lang=en
156
3. Unpack 6.0.0-TIV-ITDI-FP0001.win.zip to a temporary directory. After unpacking the fixpack zip file, you should have a setupFPwin32.exe file. 4. Open a command window and navigate to the directory of setupFPwin32.exe. 5. Enter the following command to run setupFPwin32.exe to start the fixpack installer:
setupFPwin32.exe -is:javahome C:\ibm\DirectoryIntegrator\_jvm
6. When the Welcome dialog appears, click Next. 7. When the License agreement dialog appears, select I accept the terms in the license agreement and click Next. 8. When the Install Directory dialog appears, it detects the installation directory (for example, C:\ibm\DirectoryIntegrator). Click Next. 9. When the summary dialog appears, click Next. 10.When the fixpack installation is complete, you should see a message that it was successfully installed. Click Finish.
4.2.9 DB2 Information Integrator for Content installation

In order for Tivoli Directory Integrator to create a user DB2 Content Manager, it needs the DB2 Information Integrator for Content to access DB2 Content Manager. For installation details refer to 4.7.8, Information Integrator for Content V8.3 installation on page 224. Note: In this case, the verification with DB2 Content Manager will need to be deferred until after the Content Management node is installed later in the procedure. You have now completed the installation for the components of the Directory node for the example.
4.3 Access Manager node installation

The Access Manager node installation includes the following tasks: 1. 2. 3. 4. 5. Windows 2000 Server installation IBM Java Runtime Environment (JRE) V1.3.1 installation IBM GSKit installation Tivoli Directory Client SDK 5.2 installation WebSphere Application Server V5.0.2 installation
157
6. Configure Directory Server for Tivoli Access Manager 7. Tivoli Access Manager installation 8. Tivoli Access Manager configuration 9. Tivoli Access Manager Web Portal Manager installation 10.Tivoli Access Manager V5.1 Base Fixpack 9 installation 11.Configure Web Portal Manager 12.Verify the Web Portal Manager 13.Tivoli Identity Manager Agent for TAM installation 14.Tivoli Identity Manager Agent for TAM configuration

For details, refer to 4.2.1, Windows 2000 Server installation on page 135.
4.3.2 IBM Java Runtime Environment (JRE) V1.3.1 installation

In order to use the IBM Key Management Utility (iKeyman) included with the GSKit, the Java Runtime Environment (JRE) V1.3.1 is required to be installed. To install the IBM Java Runtime Environment V1.3.1, do the following steps: 1. Insert the IBM Tivoli Access Manager V5.1 Web Administration Tool CD. 2. Navigate to the <CD_Root>\Windows\JRE directory and run Install.exe to start the JRE installer. 3. When the Choose Setup Language window appears, select the language for the installation process (for example, English) and click OK. 4. When the Welcome window appears, click Next. 5. When the License Agreement window appears, if in agreement click Yes to continue. 6. When the Choose Destination Location window appears, click Browse to change the installation directory. We entered c:\ibm\Java131 in the Path and then clicked OK. When prompted to create the directory click Yes. Click Next to continue. 7. When the Select Components window appears, check Java 2 Runtime Environment and then click Next. 8. When prompted with the message Install this Java Runtime Environment as the System JVM?, click Yes. 9. When the Start Copying Files Summary window appears, click Next to begin copying files. 10.When the Setup Complete window appears, click Finish.
158
11.To verify that the JRE is installed and available as the System JVM, do the following steps: a. Verify that the java.exe is found in the c:\winnt\system32 directory, which is copied to this directory as a result of clicking Yes in step eight. b. Open a command window and enter the following command:
java -version
It should return the following message:

java version "1.3.1" Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1) Classic VM (build 1.3.1, J2RE 1.3.1 IBM Windows 32 build cn131-20021102 (JIT enabled: jitc))

This section is optional on the Access Manager node since we do not configure SSL as part of our scenario, however this is a task that is often completed in a production environment. For details, refer to 4.2.3, IBM GSKit installation on page 140. In this case, you will need to configure the GSKit after installation. Note: The application name for this scenario is policydirector. For example:
setup policydirector
4.3.4 Tivoli Directory Client SDK 5.2 installation

As a prerequisite to the Tivoli Access Manager Runtime, the Tivoli Directory Server V5.2 Client SDK 5.2 must be installed: 1. Install the Tivoli Directory Server V5.2 - Client SDK 5.2. For details, refer to Install Tivoli Directory Server on page 148, however, only install the Client SDK 5.2. 2. Install Tivoli Directory Server V5.2 Fixpack 2 (update Client SDK). For details, refer to Install Tivoli Directory Server V5.2 Fixpack 2 on page 150.
159

On the Access Manager node, the Tivoli Access Manager Web Portal Manager requires WebSphere Application Server V5.0.2: 1. Install WebSphere Application Server V5.0. For details, refer to Install WebSphere Application Server V5.0 on page 143. 2. WebSphere Application Server V5 Fixpack 2 (V5.0.2). For details, refer to Install WebSphere Application Server V5 Fixpack 2 (V5.0.2) on page 145. 3. Verify the WebSphere Application Server V5.0.2 installation For details, refer to Verify WebSphere Application Server V5.0.2 on page 146.
4.3.6 Configure Directory Server for Tivoli Access Manager

This section describes the configuration required between the Tivoli Directory Server on the Directory node, and Tivoli Access Manager on the Access Manager node.
Prepare schema definitions

Tivoli Access Manager schema definitions are added automatically during installation of IBM Tivoli Directory Server V5.2.
Create a suffix for Tivoli Access Manager meta data

To create a suffix from the Tivoli Directory Server - Web Administration Tool for the Tivoli Access Manager meta data, do the following steps: 1. From the Tivoli Directory Server - Web Administration Tool, select Server administration Manage server properties. 2. On the Manage server properties page, click Suffixes. 3. Enter Suffix DN secAuthority=Default and click Add. 4. Click OK at the bottom of the page to save the settings. Attention: The first time we configured the runtime environment, we later discovered while troubleshooting that the suffix was not saved. On our system, the display resolution was set to 1024x768. The OK button to save the settings was not visible unless you scrolled down the page. We have added this note to click OK to save, in order to alert others to this pitfall. 5. Click Logout, and close the Tivoli Directory Server - Web Administration Tool.
160
4.3.7 Tivoli Access Manager installation

This section describes how to install and configure the Tivoli Access Manager V5.1 on the Policy Server node for the ITSO example. When installing Tivoli Access Manager V5.1, you can set up the system using one of the following installation methods: Installation wizard: This method is very useful if you are not experienced with using Tivoli Access Manager and want to quickly implement a base configuration. Installation using native installation utilities by platform: We performed the installation using the native installation utilities. First, we wanted to have greater control of how and where the components are installed. Also, we wanted to have a better understanding of what was being configured to build critical knowledge needed for debugging. To install the IBM Tivoli Access Manager V5.1, do the following steps: 1. Ensure that the Tivoli Directory Server is started. 2. Ensure that the proper GSKit is installed. The GSKit V7.0.1.9 included with the Tivoli Directory Server V5.2 contains certificates that have expired. To address this issue, we have downloaded and installed a newer GSKit V7.0.3.8 in 4.2.3, IBM GSKit installation on page 140. 3. Ensure that the Tivoli Directory Client SDK is installed. 4. Insert the Tivoli Access Manager Base for Windows NT, Windows XP, Windows 2000 and Windows 2003 CD. 5. Navigate to the <CD_Root>\windows\PolicyDirector\Disk Images\Disk1 folder and run Setup.exe to start the installer. 6. When the Choose Setup Language window appears, select the desired language (for example, English) and click OK. 7. When the Welcome window appears, click Next. 8. When the License Agreement window appears, review the terms and, if in agreement, click Yes. 9. When the Select Packages window appears, we checked the following packages and then clicked Next: Check Access Manager Runtime. Check Access Manager Policy Server. Check Access Manager Authorization Server. Check Access Manager Java Runtime Environment.
161
10.When the Choose Destination Directory window appears, we entered the following information and then clicked Next: Install destination directory: c:\ibm\tam 11.When the Summary/Start Copying Files window appears, review the selections and then click Next. 12.When the installation is complete, select Yes, I will restart my computer now and then click OK. Note: Manually stopping the server prior to system restart (optional). On occasion, if you do not stop the WebSphere Application Server from the command line by entering the following command, you may not be able to start the WebSphere Application Server after the restart:
C:\WebSphere\AppServer\bin\stopServer server1
To resolve this issue, delete the file server.pid found in the <was_home>/logs/server1 directory, and then restart the server.
4.3.8 Tivoli Access Manager configuration

This section describes how to configure these Tivoli Access Manager components, as follows: Configure Access Manager Runtime. Configure Access Manager Policy Server. Configure Access Manager Authorization Server. Update Windows registry for Access Manager services. Tivoli Access Manager Windows services startup.
Configure Access Manager Runtime

To configure the Tivoli Access Manager Runtime, do the following steps: 1. Ensure that the Tivoli Directory Server is started. 2. Start the Access Manager Configuration by clicking Start Programs IBM Tivoli Access Manager Configuration. Alternatively, open a command window and enter pdconfig, which is in the environment after the system restart. 3. From the Access Manager Configuration, select Access Manager Runtime and click Configure. 4. Select LDAP and click Next.
162
5. When the LDAP Server Information page appears, we entered the following information and then clicked Next: LDAP host name: tdiwin1.itso.ral.ibm.com LDAP port number: 389 6. When the SSL with the registry server window appears, we selected No next to enable SSL with the registry server and then clicked Next. 7. When the Logging Information page appears, we entered the following information and then clicked Next: Check Enable Tivoli Common Directory for logging. Log directory: c:\ibm\Tivoli\common 8. When the Configuration Summary page appears, review the settings and click Finish. The Access Manager Configuration tool should display configured status Yes for Access Manager Runtime. 9. Click Close to close the Access Manager Configuration.
Configure Access Manager Policy Server

To configure the Tivoli Access Manager Policy Server, do the following steps: 1. From the Access Manager Configuration, select Access Manager Policy Server and click Configure. 2. When the LDAP Administration ID page appears, we entered the following information and then clicked OK. LDAP administrator name: cn=root LDAP administrator password: <password> 3. When the Tivoli Access Manager administrator ID page appears, we entered the following information and then clicked OK: ID: sec_master (greyed out) Password: <password> Confirm password: <password> 4. When the Access Manager Policy Server SSL parameters page appears, we accepted the default at this time and then clicked OK: SSL port: 7135 SSL certificate lifecycle: 365 SSL connection timeout: 7200 5. After the configuration is complete, you should see the following message displayed. Click OK to continue.
Access Manager Policy Server configuration completed successfully. The Managers CA certificate is base64-encoded and is saved in a text file
163
C:\ibm\tam\keytab\pdcacerts.b64 You must distribute this file to each machine in your secure domain. It is needed for successful configuration.
Tip: The first time we configured our environment, we received an error dialog. We then reviewed the c:\ibm\tam\log\msg__config.log. We found the error:
Error code 0x20 was received from the LDAP server. Error text: No such object.
We later discovered that the suffix for Tivoli Access Manager meta data (secAuthority=Default) was not saved. We have included a note in the section where the suffix is added, to ensure that you scroll down the page and click OK to save the suffix. After successfully adding the suffix, we reran the Policy Server configuration successfully. The Access Manager Configuration tool should display configured status Yes for Access Manager Policy Server.
Configure Access Manager Authorization Server

To configure the Tivoli Access Manager Authorization Server, do the following steps: 1. From the Access Manager Configuration, select Access Manager Authorization Server and click Configure. 2. When the Domain Information window appears, enter Default in the Domain field and click Next. 3. When the Policy Server Information window appears, we entered the following information and then clicked Next: Policy server hostname: tamwin1.itso.ral.ibm.com Policy server port: 7135 4. When the Administrator ID for domain Default window appears, we entered sec_master, <password> and then clicked Next. 5. When the Authorization Server window appears, we entered the following information and then clicked OK: Local host name: tamwin1.itso.ral.ibm.com Administration request port: 7137 Authorization request port: 7136 The Access Manager Configuration tool should display configured status Yes for Access Manager Authorization Server. 6. Click Close to exit the Access Manager Configuration utility.
164
Configure Access Manager Java Runtime Environment

To configure the Access Manager Java Runtime Environment, do the following steps: 1. From the Access Manager Configuration, select Access Manager Authorization Server and click Configure. 2. When the Select Configuration type window appears, select Full. 3. The Specify the Full Path of JRE window appears, and it automatically detects the current directory of IBM JRE. In our case, it has displayed C:\IBM\Java131\jre. Change this to the JRE in the WebSphere installation directory. We have specified:
C:\WebSphere\AppServer\Java\jre
4. When the Specify the Existing Policy Server Information window appears, we entered the following information and then clicked Next: Policy server hostname: tamwin1.itso.ral.ibm.com Policy server port: 7135 5. When the Logging Information window appears, check the Enable Tivoli Common Directory Logging. Click Finish. 6. When the Access Manager Java Runtime Environment Configuration is complete message appears, click OK. 7. Click Close to exit the Access Manager Configuration utility.
Update Windows registry for Access Manager services

While writing this redbook, we found that the Tivoli Access Manager V5.1, Access Manager Policy Server Windows services did not start properly. We discovered that the Windows registry for the Access Manager Policy Server Windows service was not configured correctly by the Tivoli Access Manager V5.1 installation program. Note: If you install Tivoli Access Manager V5.1 to a path other than the default installation path, you will see a Windows service startup error, as shown in Figure 4-5.
Troubleshoot Windows service startup problem

To determine if you have the problem, do the following steps: 1. Stop the Access Manager Policy Server Windows service. 2. Start the Access Manager Policy Server Windows service.
165
3. If you see the error message shown in Figure 4-5, you will need to proceed to Update Windows registry on page 166.
Figure 4-5 Access Manager Policy Server Windows service startup failure
Update Windows registry

To work around this configuration issue, we did the following steps: 1. Start the Registry Editor (regedit.exe). 2. To update the Access Manager Policy Server Windows service definition in the registry, do the following steps: a. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IVMgr. b. Double-click ImagePath. c. From the Edit String window, we entered the following information and then clicked OK: Value data: c:\ibm\tam\bin\pdmgrd.exe
Note: We removed the li parameter, which we believe to be characters inserted by the Tivoli Access Manager installer that cause this problem. 3. To update the Access Manager Authorization Server Windows service definition in the registry, do the following steps: a. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IVACId. b. Double-click ImagePath. c. From the Edit String window, we entered the following information and then clicked OK: Value data: c:\ibm\tam\bin\pdacld.exe
Note: We removed the li parameter, which we believe to be garbage characters inserted by the Tivoli Access Manager installer. 4. Close the Registry Editor.
166
Tivoli Access Manager Windows services startup

The Tivoli Access Manager - Access Manager Auto-Start Service is set to automatic startup by default. The purpose of the Access Manager Auto-Start Service is to start other Tivoli Access Manager services automatically, such as the Policy Server and Authorization Server.
4.3.9 Tivoli Access Manager Web Portal Manager installation

This section describes how to install the Tivoli Access Manager V5.1 Web Portal Manager. Like the Web Administration Tool, the Web Portal Manager WAR file is first installed and then must be manually deployed to the WebSphere Application Server V5.0.2. The Tivoli Access Manager Web Portal Manager is a graphical Web-based application used to manage Tivoli Access Manager security policies in a secure domain. The Web-based Web Portal Manager is an alternative to the pdadmin command line interface. It allows administrators to remotely access and administer Tivoli Access Manager security policies. We chose the native method of installation, since we already have a WebSphere Application Server installed on the Policy Server node on which we can install the Access Manager Web Portal Manager. Also, installation using the native installation method promotes greater knowledge of the components and their placement, which may be needed later for administration and troubleshooting. To install the Tivoli Access Manager Web Portal Manager and the Access Manager Java Runtime Environment (PDJRTE), do the following steps: 1. Ensure that WebSphere Application Server V5.0.2 is installed. In our example, since we are installing the Web Portal Manager on the same node as the Tivoli Directory Server (Web Administration Tool), WebSphere Application Server V5.0.2 has already been installed. 2. Ensure that the following Windows services are started: IBM Tivoli Directory Server V5.2 Access Manager Policy Server 3. Insert the IBM Tivoli Access Manager Web Administration Interfaces for Windows 2000 CD. 4. Navigate to the <CD_Root>\windows\PolicyDirector\Disk Images\Disk1 folder and run Setup.exe to start the installation. 5. When the Choose Setup Language window appears, select the language for the installation process (for example, English) and click OK. 6. When the Welcome window appears, click Next.
167
7. When the License Agreement window appears, if in agreement, click Yes to continue. 8. When the Select Packages window appears, we checked the following package and then clicked Next: Check Access Manager Web Portal Manager. 9. When the installation is complete you should see a dialog with the message All Access Manager components have been installed. Installation completed successfully. Click OK to exit.
4.3.10 Tivoli Access Manager V5.1 Base Fixpack 9 installation

To install Tivoli Access Manager V5.1 Base Fixpack 9, do the following steps: Note: For more detailed information on installing the Tivoli Access Manager V5.1 Base Fixpack 9, refer to the readme, which can be found at:
http://www.ibm.com/support/docview.wss?rs=638&context=SSPREK&dc=D400&q1=Patc h&uid=swg24008522&loc=en_US&cs=utf-8&lang=en
1. Back up the Tivoli Access Manager V5.1 Base databases on the Policy Server node be before installing Fixpack 9 as follows: a. Create a database backup directory (for example, c:\ibm\tamdb.bak). b. Open a command window and the following command:
pdbackup -action backup -list c:\ibm\tam\etc\pdbackup.lst -path c:\ibm\tamdb.bak
2. Ensure that you have installed IBM GSKit V7.0.3.8, which is a prerequisite to Fixpack 9. Refer to 4.2.3, IBM GSKit installation on page 140 for details. 3. Ensure that the Tivoli Access Manager Windows services are stopped before installing the fixpack: Access Manager Authorization Server Access Manager Policy Server 4. Ensure that the server1 application server where Web Portal Manager has been deployed is stopped. 5. Download Tivoli Access Manager V5.1 Base Fixpack 9 from the following URL to a temporary directory (for example, c:\temp\tam51.fp9) on the Policy Server node:
http://www.ibm.com/support/docview.wss?rs=638&context=SSPREK&dc=D400&q1=Pat ch&uid=swg24008522&loc=en_US&cs=utf-8&lang=en
168
6. Navigate to the temporary directory where you downloaded the fixpack (for example, c:\temp\tam51.fp2), and run 5.1.0-TIV-TAM-FP0009-WIN.exe to start the Tivoli Access Manager V5.1 Fixpack Setup (5.1.0.9). 7. When the Welcome window appears, click Next. 8. When the License Agreement window appears, review the terms, and if in agreement click Yes. 9. When the installation is complete, click Finish. Note: Though it shows the completion window, it opens a Windows Command window prompting the user to configure Access Manager Java Runtime Environment. Keep the Command window open. 10.Start the Access Manager Policy Server Windows Service. 11.When the Windows Command window appears, asking for the Configuration Type, type full and press Enter. 12.When the Java Runtime Environment window appears, specify the path to the WebSphere Application Server JRE (for example, c:\WebSphere\AppServer\java\jre) and then press Enter. Note: In our example, the PDJRTE was already configured prior to starting the Fixpack 9 installation. It closes the Command window automatically after the configuration. The Fixpack installer on Windows launches the PDJRTE configuration automatically as part of the Fixpack installation, even though it is configured in our example. 13.To verify that the Fixpack installation was successful, enter the following command:
pdversion
This should return a list of components installed at 5.1.0.9 level (Fixpack 9). 14.Restart the Access Manager Auto-Start Service Windows service, which will restart Access Manager Authorization Server. Note: After applying Fixpack 9, we noticed that the Access Manager Configuration window displayed debug statements next to the Access Manager Java Runtime Environment and then configure status Yes. This visual problem does not appear to affect the runtime behavior of this component.
169
The installation and base configuration for the Access Manager node components is complete.
4.3.11 Configure Web Portal Manager

Note: We attempted to configure Web Portal Manager before installing the Fixpack 9, but received the following error message regarding the Access Manager Java Runtime Environment version:
The Access Manager Java Runtime installed within the WebSphere JRE is outdated. Please upgrade the Access Manager Java Runtime.
To resolve this problem, we configured the Web Portal Manager after installing the Fixpack 9. To configure the Web Portal Manager, do the following steps: 1. Start the WebSphere Application Server by running the following command from a command prompt.
c:\WebSphere\AppServer\bin\startserver server1
2. Configure the Web Portal Manager: a. Open a command window and navigate to the following directory where the Tivoli Access Manager components have been installed:
cd \ibm\tam\sbin
b. Run this command to start the Web Portal Manager configuration tool:
amwpmcfg -action config -interactive
c. When the WebSphere Application Server Information window appears, we accepted the detected path (for example, c:\WebSphere\AppServer) and clicked Next. d. When the Policy Server Information window appears, we entered the following information and clicked Next: Hostname: tamwin1.itso.ral.ibm.com Port: 7135
e. When the Administration Login window appears, we entered the following information and clicked Finish: Administration ID: sec_master Administrator password: <password> Domain: Default (greyed out)
f. You should see a dialog with the message Configuration of Access Manager Web Portal Manager completed successfully. Click OK.
170
4.3.12 Verify the Web Portal Manager

To verify the Tivoli Access Manager Web Portal Manager, do the following steps: 1. Restart the following Windows services to pick up the configuration settings for the newly deployed Web Portal Manager: IBM HTTP Server 1.3.26 IBM WebSphere Application Server V5 - server1 2. Enter the following URL in a Web browser to access the Web Portal Manager:
http://<hostname>/pdadmin
Where <hostname> is the hostname where the Web Portal Manager is deployed (for example, http://tamwin1.itso.ral.ibm.com/pdadmin). 3. When the Access Manager Login page appears, enter the following and then click Login: Secure Domain: Default User ID: sec_master Password: <password> 4. Review the configuration options. To logout, click Sign off in the lower right of the page.
4.3.13 Tivoli Identity Manager Agent for TAM installation

Note: At the time of writing this redbook, the most current version of the Tivoli Identity Manager Agent for TAM was V4.5.12. We found that when attempting to create a TAM account from Tivoli Identity Manager, the creation failed. To work around this issue, we used V4.5.9. This problem has been reported to the IBM Tivoli Identity Manager organization and is planned to be fixed in V4.5.13. To install the Tivoli Identity Manager Agent V4.5.9 for Tivoli Access Manager, do the following steps: 1. Ensure that Access Manager Policy Server Windows Service is started. 2. Run setup.exe to start the installer for the Tivoli Identity Manager Agent for Tivoli Access Manager. 3. When the Welcome to the InstallShield Wizard for Tivoli Access Manager 4.1/5.1 Agent windows appears, click Next. 4. When the Software License Agreement window appears, review the terms and if in agreement, select I accept the terms in the license agreement and then click Next.
171
5. When the Click Next to install Tivoli Access Manager 4.1/5.1 Agent dialog appears as shown in Figure 4-6 on page 172, we accepted the default installation directory (c:\Tivoli\Agents\TAM4Agent). Click Next.
Figure 4-6 Tivoli Access Manager Agent 4.1/5.1 Installation Directory 6. When the Installation Options Summary dialog appears, review the selections and then click Next to continue. 7. When the Access Manager Account Setup dialog appears, enter the following information and then click Next: Access Manager Administration Account : sec_master Access Manager AdministrationPassword : <sec_master password> 8. When the Installation Completed window appears, click Finish. 9. Ensure that Tivoli TAM4Agent Windows service is started.
4.3.14 Tivoli Identity Manager Agent for TAM configuration

This section describes how to configure the Tivoli Identity Manager Agent V4.5.9 for Tivoli Access Manager.
172
Create SSL certificate

To create the SSL certificate, do the following steps: 1. Ensure that the following prerequisites have been met (they should have already been completed if following the documented redbook procedure): IBM GSKit V7.0.3.8 is installed and configured (IBM Key Management). IBM JRE 1.3.1 is installed. 2. Create a keystore. In our example, we created a keystore named on the c:\ibm\certificates\tam_keyfile.kdb Access Manager node. For details on how to create a keystore, refer to Create a key store on page 250. 3. Generate a self-signed certificate. The self-signed Secure Socket Layer (SSL) certificate will be used by the Tivoli Identity Manager Agent. In our example, we generated the certificate using IBM GSKit. We specified the following information while generating the certificate on the Access Manager node: Key Label: tim_agent_for_tam Common Name: tamwin1.itso.ral.ibm.com Organization: ibm For details on how to generate a self-signed certificate, refer to Create a self-signed certificate on page 251. 4. Extract the certificate. a. Extract the certificate to a file by clicking Extract Certificate in the IBM Key Management window. b. Select Data type as Binary DER data from the drop-down list and specify a location to store the certificate. In our example, we specified the Certificate file name as tim_agent_ca. This file is stored with the extension der. 5. Copy extracted certificate to Identity Manager node. Copy the extracted certificate from the Access Manager node to a directory on the Identity Manager node. In our example, we copied the certificate file to c:\ibm\certificates on the Identity Manager node.
173
6. Export the keys for the certificate: a. Export the keys for the certificate by clicking Export/Import in the IBM Key Management window. b. When the Export/Import key window appears, do the following steps: Under Choose Action Type, select Export Key radio button. For Key file type, select PKCS12 from the drop-down menu. Specify the File Name and Location. In our example, we have specified the file name as tim_agent_keys. This file is stored with the extension p12 (for example, tim_agent_keys.p12). Click OK.
c. When the Password Prompt dialog appears, specify a password and click OK. 7. Copy the exported keys file. We copied the tim_agent_keys.p12 keys file to the bin directory of Tivoli Identity Manager Agent installation. In our example, we copied the tim_agent_keys.p12 to c:\Tivoli\Agents\TAM4Agent\bin directory.
Install the certificate and key

Install the certificate and key in the Tivoli Identity Manager Agent key store. 1. Open a Windows command prompt and change to the bin directory of Tivoli Identity Manager Agent installation. In our example, c:\Tivoli\Agents\TAM4Agent\bin. 2. In the command window, enter the following command:
certtool -agent TAM4Agent
3. When the Main menu - Configuring agent : TAM4Agent appears, Enter C at the Choice: prompt. 4. When it prompts Enter name of PKCS12 file:, enter the key file. In our example, we specified tim_agent_keys.p12. 5. When prompted to Enter password:, enter the password of the key file. It should display the following message and come back to the Main menu:
- Configuring agent : TAM4Agent: Certificate and private key successfully installed
6. At the Choice: prompt in the Main menu, Enter D. It should display the details of the certificate that has been installed in the previous step. In our example, it displayed the following information:
The following certificate is currently installed:
174
Subject: c=US,o=ibm,cn=tamwin1.itso.ral.ibm.com Issuer: c=US,o=ibm,cn=tamwin1.itso.ral.ibm.com Valid To: Thu May 11 15:50:34 2006
7. Enter X at the Choice: prompt to quit the Main menu.
Configure the Tivoli Identity Manager Agent for TAM

To configure the Tivoli Identity Manager Agent for Tivoli Access Manager, do the following steps: 1. Open a Windows command prompt and change to the bin directory of Tivoli Identity Manager Agent installation. In our example, c:\Tivoli\Agents\TAM4Agent\bin. 2. In the command window, enter the following command:
agentcfg -agent TAM4Agent
3. When prompted to Enter configuration key for Agent TAM4Agent:, enter agent. 4. It should display a menu TAM4AGENT Agent Main Configuration Menu: a. Type B at the Select menu option: prompt to select Protocol Configuration. b. When the Agent Protocol Configuration Menu appears, type C to select Configure Protocol. c. When the Configure Protocol Menu appears, type A to select DAML. d. When the DAML Protocol Properties menu appears, type B to select USERNAME. e. When it prompts Modify Property USERNAME:, Enter a username (in our example, admin). f. When it prompts Verification:, Enter the username again. It should come back to the DAML Protocol Properties menu. g. Type C to select PASSWORD. When it prompts for the PASSWORD, enter it. When it prompts for Verification, enter the password again. h. It should come back to DAML Protocol Properties. Type X at the Select menu option: prompt on all the menus to exit the configuration tool. Note: The default configuration key for the Tivoli Identity Manager Agent V4.5.12 for Tivoli Access Manager is agent. It is recommended to change it to a stronger key in production environments. This can be changed by selecting option D from the Agent Main Configuration Menu. 5. Restart the Tivoli TAM4Agent Windows service.
175
Note: As part of the configuration, the Tivoli Identity Manager Agent for TAM profile must be configured. This task will be performed on the Identity Manager node. The configuration requires that a JVM be installed, thus we completed this task after installing the Tivoli Identity Manager components (WebSphere Application Server JRE) in 4.5.9, Tivoli Identity Manager Agent for TAM profile configuration on page 199.
4.4 Reverse Proxy node installation

The Reverse Proxy node installation includes the following tasks: 1. 2. 3. 4. 5. 6. 7. 8. Windows 2000 Server installation Java Runtime Environment (JRE) V1.3.1 installation IBM GSKit installation Tivoli Directory Client installation Tivoli Access Manager: WebSEAL installation Tivoli Access Manager: WebSEAL configuration Tivoli Access Manager V5.1 Base Fixpack 9 installation Tivoli Access Manager V5.1 WebSEAL Fixpack 9 installation

4.4.2 Java Runtime Environment (JRE) V1.3.1 installation

For details, refer to 4.3.2, IBM Java Runtime Environment (JRE) V1.3.1 installation on page 158.

For details, refer to 4.2.3, IBM GSKit installation on page 140. Note: The application name for this scenario is policydirector. For example:
setup policydirector
176
4.4.4 Tivoli Directory Client installation

For details, refer to 4.3.4, Tivoli Directory Client SDK 5.2 installation on page 159.
4.4.5 Tivoli Access Manager: WebSEAL installation

The Tivoli Access Manager V5.1 WebSEAL can set up this system using one of the following installation methods: Installation wizard Native installation utilities For the ITSO working example, we chose to use the native installation utilities.
Install the Tivoli Access Manager WebSEAL

To install and configure a Tivoli Access Manager WebSEAL server system on Windows, do the following steps: 1. Ensure that the following prerequisites have been met: Log on as a user with administrator privileges. In our example, we logged in to Windows as the admin user we created with administrator privileges prior to the installation. Ensure that the registry server (Tivoli Directory Server) and policy server (Tivoli Access Manager Policy Server) are up and running in normal mode. Ensure that the GSKit is installed. In our example, the GSKit was installed as part of the Tivoli Directory Server installation. Ensure that the Java Runtime Environment is installed, which is required by the iKeyman utility used by GSKit to create a keystore and certificates. Ensure that the Tivoli Directory Client is installed. 2. Insert the IBM Tivoli Access Manager Web Security for Windows 2000 CD. 3. Navigate to the <CD_Root>\windows\PolicyDirector\Disk Images\Disk1 folder and run Setup.exe to start the installation program. 4. When the Choose Setup Language window appears, select the desired language (for example, English) and click OK. 5. When the Welcome window appears, click Next. 6. When the License Agreement window appears, review the terms and, if in agreement, click Yes.
177
7. When the Select Packages window appears, we checked the following packages and then clicked Next: Check Access Manager Runtime. Check Access Manager Java Runtime Environment. Check Access Manager Web Security Runtime. Check Access Manager WebSEAL.
8. Access Manager Runtime installation. When the Access Manager Runtime Choose Destination Directory window appears, we did the following steps: a. Click Browse. b. Enter the destination directory c:\ibm\tam and click OK. c. Click Next. d. When the Access Manager Runtime Installation Summary window appears, click Next to begin copying files. 9. Access Manager Web Security Runtime installation: a. When the Welcome Access Manager Web Security Runtime window appeared, click Next. b. When the License Agreement window appears, review the terms and, if in agreement, click Yes. c. When the Access Manager Java Runtime Environment Choose Destination Directory window appears, we did the following: i. Click Browse. ii. Enter the Access Manager Web Security Runtime installation directory c:\ibm\tam\PDWebRTE and then click OK. iii. Click Next. d. When the installation is complete, select Yes, I want to restart my computer now. Click Finish. Note: Even though we have selected Yes, I want to restart my computer now and clicked Finish, the installation program will continue to the Access Manager WebSEAL installer. 10.Access Manager WebSEAL installation. a. When the Welcome Access Manager WebSEAL window appears, click Next. b. When the License Agreement window appears, review the terms and, if in agreement, click Yes.
178
c. When the Access Manager WebSEAL Choose Destination Directory window appeared, we did the following steps: i. Click Browse. ii. Enter the Access Manager WebSEAL installation directory c:\ibm\tam\PDWeb and then click OK. iii. Click Next. d. When the installation is complete, select Yes, I want to restart my computer now. Click OK. This time the system will restart.
4.4.6 Tivoli Access Manager: WebSEAL configuration

After the Tivoli Access Manager V5.1 WebSEAL and Web Security runtime are installed, they must be configured. To configure the Tivoli Access Manager Runtime and WebSEAL, do the following steps: 1. Start the pdconfig configuration utility on the Reverse Proxy node by entering the following in a command window:
pdconfig
2. From the Access Manager Configuration utility, select the Access Manager Runtime package and click Configure. a. When the Access Manager Policy Server Host window appears, select Access Manager Policy Server is installed on another machine, enter the following, and then click Next: Host name: tamwin1.itso.ral.ibm.com Listening port: 7135
b. When the Registry window appears, select LDAP and click Next. c. When the Domain Information window appears, we accepted Default (default-supplied value do not change) in the Local domain name field and then clicked Next. d. When the LDAP Server Information window appears, we entered the following information and then clicked Next: LDAP host name: tdiwin1.itso.ral.ibm.com LDAP port number: 389
e. When the SSL with the registry server window appears, we selected No next to Enable SSL with the registry server and clicked Next. Note: In a later configuration section, we will configure SSL as part of security hardening for the entire secure portal runtime environment.
179
f. When the Logging Information window appears, we checked Enable Tivoli Common Directory for logging, entered log directory c:\ibm\Tivoli\common, and then clicked Next. The Access Manager Configuration tool should display configured status Yes for Access Manager Runtime. g. Click Close to close the Access Manager Configuration 3. Start the pdconfig configuration utility on the Reverse Proxy node by entering the following in a command window:
pdconfig
4. From the Access Manager Configuration utility, select the Access Manager WebSEAL package and click Configure. a. When the Access Manager WebSEAL Configuration window appears, click Configure. b. When the Instance Identification window appears, enter the following information and then click Next: WebSEAL instance name: default The value cannot exceed 20 characters. Note: Chapter 23, pdconfig options, in the Web Security Installation Guide, IBM Tivoli Access Manager V5.1, SC32-1361, documents how to use the fully qualified host name. We found that this was not possible, given the 20-character input restriction. Do not check Use a logical network interface (not used in our example).
c. When the WebSEAL Server Information page appears, enter the following and then click Next. Hostname: wswin1 Note: When the instance is created, the server name will be generated as <instance_name>-webseald-<hostname> (for example, default-webseald-wswin1). Listening port: 7234
d. When the Administrator Identification page appears, enter the following information and then click Next: Administration ID: sec_master Administration password: <password>
180
e. When the SSL communications with LDAP Server window appears, uncheck Enable SSL communication with the LDAP server and click Next (no SSL at this time). f. When the HTTP/HTTPS/Document Root Properties window appears, we accepted the following defaults and clicked Finish: HTTP Access: Check Allow HTTP Access Port: 80 Check Allow HTTPS Access Port: 443 Document root directory: c:/ibm/tam/PDWeb/www-default/docs Where default is the instance name.
HTTPS Access:
g. You should see the default instance created. When done, click Close. 5. Configure Access Manager Java Runtime Environment. a. Start the pdconfig configuration utility on the Reverse Proxy node by entering the following command in a command window: pdconfig b. Select the Access Manage Java Runtime Environment from the Access Manager Configuration window. c. Click Configure. d. When the Configuration Type window appears, select Standalone (only used by local iKeyman utility) and click Next. e. Enter the JRE path (for example, c:\ibm\Java131\jre), and then click Next. f. When the Logging Information window appears, we checked Enable Tivoli Common Directory for logging, entered log directory c:\ibm\Tivoli\common, and then clicked Finish. g. After configuration, click OK. h. When done, close the configuration utility by clicking Close.
IBM GSKit Key Management utility configuration

In order to run the IBM GSKit Key Management utility, the environment must be prepared: 1. Ensure that the following prerequisites are installed and configured, which should be the case if you have followed the documented procedure: Ensure that the Java Runtime is installed. Ensure that GSKit is installed.
181
2. Navigate to the c:\ibm\Java131\jre\lib\security directory on the Reverse Proxy node. 3. Back up the java.security file to java.security.org. 4. Modify the java.security file as follows to add the IBM JCE and IBM CMS security providers:
security.provider.3=com.ibm.crypto.provider.IBMJCE security.provider.4=com.ibm.spi.IBMCMSProvider
5. Save and close the java.security file. 6. Verify that the iKeyman utility starts properly from a command window by entering the following commands:
cd \ibm\gsk7\bin set JAVA_HOME=c:\ibm\Java131\jre gsk7ikm
7. Close the IBM Key Management utility.
4.4.7 Tivoli Access Manager V5.1 Base Fixpack 9 installation

In our example, we installed the Tivoli Access Manager Runtime Environment on the Reverse Proxy node. As part of our configuration, we need to upgrade the Tivoli Access Manager V5.1 Base to Fixpack 9 (5.1.0.9). Ensure that the Tivoli Access Manager WebSEAL Windows service is stopped prior to installing the fixpack. For details on installing Tivoli Access Manager V5.1 Base Fixpack 9, refer to 4.3.10, Tivoli Access Manager V5.1 Base Fixpack 9 installation on page 168.
4.4.8 Tivoli Access Manager V5.1 WebSEAL Fixpack 9 installation

To install Tivoli Access Manager V5.1 WebSEAL Fixpack 9, do these steps: Note: For more detailed information on installing the Tivoli Access Manager V5.1 WebSEAL Fixpack 2, refer to the readme, which can be found at:
http://www.ibm.com/support/docview.wss?rs=638&context=SSPREK&dc=D400&q1=Patc h&uid=swg24008525&loc=en_US&cs=utf-8&lang=en
1. Ensure that you are logged into the Reverse Proxy node as an administrator. 2. Ensure that you have installed IBM GSKit V7.0.3.8 which is a prerequisite to Fixpack 9. Refer to IBM GSKit installation on page 140 for details.
182
3. Ensure that the Tivoli Access Manager WebSEAL-<instance> Windows service is stopped before installing the fixpack. 4. Download Tivoli Access Manager V5.1 WebSEAL Fixpack 9 from the following URL to a temporary directory (for example, c:\temp\tam51ws.fp9) on the Reverse Proxy node:
http://www.ibm.com/support/docview.wss?rs=638&context=SSPREK&dc=D400&q1=Pat ch&uid=swg24008525&loc=en_US&cs=utf-8&lang=en
5. Navigate to the temporary directory where you downloaded the fixpack (for example, c:\temp\tam51ws.fp9) and run 5.1.0-TIV-AWS-FP0009-WIN.exe to start the Access Manager V5.1 WebSEAL Fixpack 9 Setup (5.1.0.9). 6. When the Welcome window appears, click Next. 7. When the License Agreement window appears, review the terms and, if in agreement, click Yes. 8. When the installation completes, click Finish. Note: If a configuration window appears for the PDJRTE, you can click Cancel since we have already configured the Access Manager Java Runtime Environment. 9. To verify that the Fixpack installation was successful, open a command window and enter the following command:
pdversion
This should return a list of components installed at the 5.1.0.9 level (Tivoli Access Manager Base and WebSEAL Fixpack 9). 10.Start the Access Manager Auto-Start Service Windows service. This completes the base installation and configuration of the Reverse Proxy node.
4.5 Identity Management node installation

The Identity Manager node installation includes the following tasks: 1. 2. 3. 4. 5. 6. 7. Windows 2000 Server installation DB2 Universal Database V8.2 installation IBM GSKit V7.0.3.8 installation Tivoli Directory Server V5.2 installation Tivoli Directory Server configuration WebSphere Application Server V5.1 Tivoli Identity Manager V4.5.1 Fixpack 16 (full install)
183
8. Install Tivoli Identity Manager V4.5.1 FP42 9. Tivoli Identity Manager Agent for TAM profile configuration


For details on installing IBM DB2 Universal Database V8.2, Enterprise Server Edition and DB2 Universal Database V8 Fixpack 8, refer to 4.2.2, DB2 Universal Database V8.2 installation on page 137.
4.5.3 IBM GSKit V7.0.3.8 installation

For details, refer to 4.3.3, IBM GSKit installation on page 159. When running the GSKit installation, we entered the following information for the Tivoli Directory Server:
setup LDAP
When prompted, we entered c:\ibm\gsk7 for our installation path.
4.5.4 Tivoli Directory Server V5.2 installation

We chose not to install the Tivoli Directory Server Web Administration Tool since it is dependent on WebSphere Application Server V5.0.2 and Tivoli Identity Manager V4.5.1 in our environment will be configured to use WebSphere Application Server V5.1. The Web Administration Tool will be installed on our Directory node and can be used to manage the directory server on this node. For details on installing the IBM Tivoli Directory Server V5.1 + Fixpack 2 refer to 4.2.5, Tivoli Directory Server V5.2 installation on page 147. The only difference is that on this node, we will not install the Web Administration Tool (only install the Server and Client SDK).
4.5.5 Tivoli Directory Server configuration

For details 4.2.6, Tivoli Directory Server configuration on page 150.
184
4.5.6 WebSphere Application Server V5.1

Service levels beyond the initial release of Tivoli Identity Manager V4.5.1 provide support for WebSphere Application Server V5.1. In our example, we will use Fixpack 16. Important: Due to APARIY60601 we did not install WebSphere Application Server V5.1 Fixpack 1 (V5.1.1) on the Identity Management node. If you choose to install WebSphere Application Server V5.1 Fixpack 1 (V5.1.1), you will need to contact IBM support to get the APARIY60601 patch. This patch addresses a memory leak with the MQQUEUESESSION.CREATERECEIVER() WebSphere MQ JMS (embedded messaging). For details on installing WebSphere Application Server V5.1, refer to WebSphere Application Server V5.1 installation on page 201.
4.5.7 Tivoli Identity Manager V4.5.1 Fixpack 16 (full install)

This section describes the prerequisite and installation steps to install IBM Tivoli Identity Manager V4.5.1 Fixpack 16, which is a full installation at the fixpack 16 level. Important: We found that when using IBM Tivoli Identity Manager V4.5.1 Fixpack 42, Tivoli Identity Manager did not deploy properly to WebSphere Application Server V5.1. For this reason, we first installed Tivoli Identity Manager V4.5.1 FP 16 (full install) so that Tivoli Identity Manager would deploy properly to WebSphere Application Server V5.1, and then we installed Fixpack 42 (next section) to service Tivoli Identity Manager to the current level at the time of writing. The Tivoli Identity Manager installation includes the following tasks: Create Tivoli Identity Manager database Create the enrole Windows user Create the LDAP suffix object Configure the Referential Integrity Plug-in for TIM Handle thread limitations for Tivoli Directory Server Install Tivoli Identity Manager V4.5.1 FP16 Install J2SE V1.3.1_04 (browser Java plug-in) Verify Tivoli Identity Manager
185
Note: For more detailed installation information, refer to the Server Installation Guide on Windows using WebSphere, IBM Tivoli Identity Manager V4.5.1, SC32-1148-02.
Create Tivoli Identity Manager database

To create and configure the Tivoli Identity Manager database, do the following steps: 1. Open a DB2 command window by selecting Start Programs IBM DB2 Command Line Tools Command Window. 2. Create the Tivoli Identity Manager database. a. Enter the following command to create the database using the codeset UTF-8 territory US:
db2 create db itimdb using codeset UTF-8 territory US
b. Modify the applheapsz by entering the following DB2 command:

db2 update db cfg for itimdb using applheapsz 1024
Note: The Server Installation Guide on Windows using WebSphere, IBM Tivoli Identity Manager V4.5.1, SC32-1148-02 recommends using half the available real memory for applheapsz value. c. Modify the app_ctl_heap_sz by entering the following DB2 command:
db2 update db cfg for itimdb using app_ctl_heap_sz 512
d. Connect to the itimdb as follows:

db2 connect to itimdb
e. Create the bufferpool by entering the following DB2 command:

db2 create bufferpool enrolebp size -1 pagesize 32k
3. Enable the Repeatable Read attribute with the setting DB2_RR_TO_RS=YES: a. Type the following to determine existing settings:
db2set -all
b. Examine the response to ensure that DB2_RR_TO_RS=YES is present. c. If the entry is not found, type the following to set the value to YES:
db2set DB2_RR_TO_RS=YES
d. Retype the following to verify the setting now exists:

db2set -all
186
4. Enter the following to stop and start DB2 for the changes to take effect:
db2 force applications all db2 terminate db2stop db2start
Create the enrole Windows user

Create a user named enrole as follows: 1. Select Start Settings Control Panel Administrative Tools Computer Management. 2. Select Local Users and Groups Users. Note: The enrole user does not need to be added to any group. 3. Select Action New User. 4. In the username field, type enrole. 5. In the password field, type a password for the database user. 6. Uncheck the User must change password at next login checkbox. 7. Check the Password never expires checkbox. 8. Click Create.
Create the LDAP suffix object

For the ITSO working example, the procedure to implement the Identity Management node is to share between the runtime and development environments. Depending on which environment you are working in, complete one of the following tasks to create the LDAP suffix object: Create the LDAP suffix for the runtime environment or Create the LDAP suffix for the development environment
Create the LDAP suffix for the runtime environment

To create the LDAP suffix object in the runtime environment, do the following steps: 1. Ensure that the following Tivoli Directory Server Windows services are stopped. IBM Tivoli Directory Admin Daemon V5.2 IBM Tivoli Directory Server V5.2 2. Navigate to the following directory:
C:\IBM\LDAP\etc
187
3. Open the ibmslapd.conf in a text editor. 4. Search for the following text:
ibm-slapdSuffix: cn=localhost
5. Add the following text (after search line):

ibm-slapdSuffix: dc=com
Where dc=com is a value for the suffix that you define for Tivoli Identity Manager. 6. Save and close the file. 7. Create an ldif file and modify it for your suffix as seen in Example 4-1.
Example 4-1 ITSO sample tim.ldif to create LDAP suffix object dn: dc=com dc: com objectclass: top objectclass: domain
Note: The tim.ldif file can be found in the c:\6692code\config\timwin1 folder of the sample code. 8. Enter the following command to import the tim.ldif file:
ldapadd -i tim.ldif -D cn=root -w?
By using the ? with the -w parameter, you will be prompted for the root password. 9. Verify the LDAP entries where created properly by performing an LDAP search. For example, we entered the following information from a command window on the Directory Server node:
ldapsearch -b dc=com objectclass=*
Create the LDAP suffix for the development environment

To create the suffix entries, users, and groups in the development environment, do the following steps: 1. Create the dc=itso,dc=ibm,dc=com suffix as described in 5.3.1, Create a suffix on page 255 in place of completing the steps in this section. The dc=itso,dc=ibm,dc=com suffix can be used for both Tivoli Identity Manager since it will use the dc=com part of the suffix, and work for the applications requiring shared LDAP directory.
188
2. Create the ldif file as described in 5.3.2, Create LDIF file containing users and groups on page 256. 3. Import the ldif file as described in 5.3.3, Import the LDIF file (wp-itso.ldif) to create users and groups on page 257 (for example, c:\6692code\config\wpwin1\wp-itso.ldif). 4. Verify the LDAP entries where created properly by performing an LDAP search. For example, we entered the following commands in a command window:
ldapsearch -b dc=itso,dc=ibm,dc=com objectclass=* ldapsearch -h <ldap_server_hostname> -b dc=itso,dc=ibm,dc=com -D uid=wpsbind,cn=users,dc=itso,dc=ibm,dc=com -w <password> -s sub uid=admin
Where <ldap_server_hostname> is the hostname of the system Tivoli Directory Server is installed, and <password> is your password.
Configure the Referential Integrity Plug-in for TIM

To configure the Referential Integrity Plug-in for Tivoli Identity Manager, do the following steps: 1. Copy the libdelref.dll plug-in library file from the DelRef\nt directory on Tivoli Identity Manager CD 2, to the C:\IBM\LDAP\bin directory. 2. Copy the timdelref.conf file from the DelRef directory on Tivoli Identity Manager CD 2, to the C:\IBM\LDAP\etc directory. 3. Navigate to the C:\IBM\LDAP\etc directory. 4. Modify the ibmslapd.conf file. a. Search for the following line (under the dn: cn=Directory .. stanza):
ibm-slapdPlugin: database path_to_rdbmfilename rdbm_backend_init
b. Add the following coding on one line after the above search line: Runtime environment:
ibm-slapdPlugin: preoperation "c:/ibm/ldap/bin/libdelref.dll" DeleteReferenceInit file="c:/ibm/ldap/etc/timdelref.conf" dn=dc=com
or Development environment:
ibm-slapdPlugin: preoperation "c:/ibm/ldap/bin/libdelref.dll" DeleteReferenceInit file="c:/ibm/ldap/etc/timdelref.conf" dn=dc=itso,dc=ibm,dc=com
c. Save and close the file.
189
5. Restart the following Tivoli Directory Server Windows services: IBM Tivoli Directory Admin Daemon V5.2 IBM Tivoli Directory Server V5.2 6. After restarting the Tivoli Directory Server Windows services, verify in the log that the Referential Integrity Plug-in was loaded properly. Review the C:\IBM\LDAP\var\ibmslapd.log file for a message similar to the following:
Plugin of type PREOPERATION is successfully loaded from c:/IBM/LDAP/bin/libdelref.dll
Handle thread limitations for Tivoli Directory Server

By default, the IBM Tivoli Directory Server V5.2 running on Windows only supports 64 concurrent connections. However, Tivoli Identity Manager data services uses LDAP connection pooling to establish up to 100 (default) simultaneous connections with the IBM Directory Server. To prevent problems with this connection limitation, do the following steps: 1. Ensure that the following Tivoli Directory Server Windows services are stopped. IBM Tivoli Directory Admin Daemon V5.2 IBM Tivoli Directory Server V5.2 2. Navigate to the following directory:
C:\IBM\LDAP\etc
3. Open the ibmslapd.conf in a text editor. 4. Search for the following stanza in the ibmslapd.conf file:
dn: cn=Front End, cn=Configuration
5. Add the following line to the stanza:

ibm-slapdSetenv: SLAPD_OCHANDLERS=<number-of-threads>
Where one thread supports 64 connections. For example, we entered 5 threads (5 x 64 = 320 possible connections):
ibm-slapdsetenv: SLAPD_OCHANDLERS=5
6. Restart the Tivoli Directory Server Windows services.
190
Install Tivoli Identity Manager V4.5.1 FP16

To install the IBM Tivoli Identity Manager V4.5.1 FP16 (full install), do the following steps: 1. Ensure that the Tivoli Directory Server V5.2 Windows service is started. 2. We downloaded IBM Tivoli Identity Manager V4.5.1 FP16 (full install) from the following site:
http://www.ibm.com/support/docview.wss?rs=644&context=SSTFWV&dc=D400&uid=sw g24007342&loc=en_US&cs=utf-8&lang=en
3. Unzip the downloaded file 4.5.1-TIM-WIN-WAS-FP0016.zip. After the unzip, you should have a self-extracting file named instwin_was_ITIM_5183.exe. Note: IBM Tivoli Identity Manager V4.5.1 FP416 is a self-extracting full install. This requires that you have a proper license agreement. 4. Start the install by running the instwin_was_ITIM_5183.exe. 5. Select the desired language (for example, English) and click OK. 6. When the License agreement dialog appears, review the terms and if in agreement select I accept the terms of the License Agreement and click Next. 7. When the Choose the Installation Type dialog appears, select Single Server (default), and click Next. 8. When prompted for the installation path of Tivoli Identity Manager, we entered c:\itim45 (default), and then clicked Next. 9. When the Choose the Database type dialog appears, select IBM DB2 Universal Database and click Next. 10.When the Run usejdbc2 command dialog appears (DB2 Universal Database V7.1 specific), click Continue. 11.The Confirm the Install Directory of WebSphere Application Server will appear. In our example, it detected C:\WebSphere\AppServer for our WebSphere Application Server V5.1 installation. Click Next. 12.When the WebSphere Application Server Data dialog appears, we accepted the following defaults and then clicked Next: Node name: timwin1 WebSphere Application Server Name: server1 13.When the WebSphere Security dialog appears, we accepted the default (WebSphere Security Disabled) and then clicked Next.
191
14.When the Specify the Encryption Key dialog appears, enter a key value (default key is sunshine), and then click Next. 15.When the Pre-Install Summary dialog appears as seen in Figure 4-7, notice that it displays WebSphere Application Server V5.0 even though we have pre-installed WebSphere Application Server V5.1. Click Install to proceed with copying files.
Figure 4-7 Pre-install Summary
16.When the Input database information and test connection dialog appears, enter the following information as seen in Figure 4-8, and then click Test: Database Name or Alias: itimdb Admin ID: admin Admin Password: <admin_password>
192
Figure 4-8 Input database information and test connection
17.After clicking Test, you should see the message dialog, Database connection is successful. Click OK. 18.When you return to the Input database information and test connection dialog, enter the enrole user ID password in the User Password field, and then click Continue. 19.When the RDBMS Configuration is complete dialog appears, click OK. 20.When the Input LDAP Server Information dialog appears, enter the following information as seen in Figure 4-9, and then click Test: Principal DN: cn=root Password: <root_password> Host name: timwin1 Port: 389
193
Figure 4-9 Input LDAP Server Information
21.After clicking Test, you should see the message dialog, Directory connection is successful. Click OK. 22.When you return to the Input LDAP Server information dialog, enter the following and then click Continue: Number of hash buckets: 1 Name of Your Organization: ITSO Default Org Short Name: ITSO Identity Manager DN Location: dc=com Note: When installing Tivoli Identity Manager in the development environment, enter dc=itso,dc=ibm,dc=com in the DN Location field. 23.You should see a dialog, LDAP Configuration is successful. Click OK. 24.When the System Configuration dialog appears, click through the tabs to verify the configuration information is correct. We found that we had to modify the settings on the Mail tab.
194
a. Change the Identity Manager Server URL to use a hostname in place of the IP address. b. Enter a Mail Server Name (even if bogus such as mailserver, so that you can continue). c. Click Apply. d. Click OK. 25.When the Install Completed dialog appears as seen in Figure 4-10, click Done.
Figure 4-10 Install Completed
Install J2SE V1.3.1_04 (browser Java plug-in)

The Tivoli Identity Manager Web interface - configuration menus require a Java plug-in for the Web browser to run applets. We found that the Tivoli Identity Manager Web interface was very particular in the level of the Java plug-in required for the configuration applets to work properly. The Java plug-in will need to be installed on systems where you will be using a Web browser to connect to the Tivoli Identity Manager Web interface.
195
Note: If the system with the Web browser accessing the Tivoli Identity Manager Web interface is connected to the Internet, when using the Configuration User Interface Customization menu you will be redirected to the Sun site to download the Sun Java 2 Standard Edition (J2SE) V1.3.1_04 JRE. If you are not connected to the Internet, manually download and install Sun Java 2 Standard Edition (J2SE) V1.3.1_04 JRE at:
http://java.sun.com/products/archive/j2se/1.3.1_04/
Verify Tivoli Identity Manager

After the installation, we recommend that you verify that Tivoli Identity Manager is working properly. 1. Server startup. Ensure that the Tivoli Directory Server V5.2 Windows service is started. Ensure that the IBM HTTP Server 1.3.28 Windows service is started. Ensure that the server1 application server is started. 2. Enter the following URL in a Web browser to access the Tivoli Identity Manager Console:
http://timwin1.itso.ral.ibm.com/enrole/logon
3. It should present the Login to Identity Manager form. Check the build level of the installation (text in blue bar). It should be: Tivoli Identity Manager 4.5.1 FP16 Build 5183. 4. Login using the following information: User ID: itim manager Password: secret 5. After successful login, you will be prompted to change the password for the above User ID. Change the password. 6. Logout by clicking Logout button.
4.5.8 Install Tivoli Identity Manager V4.5.1 FP42

This section describes how to install Tivoli Identity Manager V4.5.1 FP2, as well as how to verify that Tivoli Identity Manager is working properly after the fixpack installation.
196
Install Tivoli Identity Manager V4.5.1 FP2

To install Tivoli Identity Manager V4.5.1 FP42, do the following steps: Note: For more information, refer to the readme file included with the Tivoli Identity Manager V4.5.1 FP42. 1. In our example, the following servers are started before installing the fixpack: Tivoli Directory Server V5.2 Windows service IBM HTTP Server 1.3.28 Windows service The server1 application server The fixpack readme says that the servers do not need to be stopped for a Tivoli Identity Manager Single Server, prior to starting the fixpack installer. Note: In our example, the development Identity Manager node VMWare image was allocated 1024 MB RAM. With the servers needed for Tivoli Identity Manager running, there is not much RAM left over to run the FP42 install. 2. Back up the <tim_home>\data directory. Note: We recommend that you back up the C:\itim45\data directory containing the configuration files prior to installing FP42. 3. We downloaded the IBM Tivoli Identity Manager V4.5.1 FP42 from the following site:
http://www.ibm.com/support/docview.wss?rs=644&context=SSTFWV&dc=D400&uid=sw g24009190&loc=en_US&cs=UTF-8&lang=en
4. Unzip 4.5.1-TIV-TIM-WIN-WAS-FP0042.zip. After the unzip you should have a self-extracting file named instwin_was_ITIM_5190.exe. 5. Start the install by running the instwin_was_ITIM_5190.exe. 6. Select the desired language (for example, English) and click OK. 7. When the License agreement dialog appears, review the terms and if in agreement select I accept the terms of the License Agreement and click Next. 8. When the Choose the Installation Type dialog appears, select Single Server (default), and click Next. 9. When prompted for the installation path of Tivoli Identity Manager, we accepted the default (c:\itim45), and then clicked Next.
197
10.When prompted with the message dialog, You already have Tivoli Identity Manager 4.5.1 installed in this folder c:\itim45. Do you want to upgrade? click Yes. 11.The Confirm the Install Directory of WebSphere Application Server dialog will appear. In our example, it detected C:\WebSphere\AppServer for our WebSphere Application Server V5.1 installation. Click Next. 12.It displays a Pre-Install Summary dialog similar to that appeared during the Fixpack 16 Installation. Click Install. 13.When the Database schema upgrade is complete dialog appears, click OK. Note: At the time of writing, in some cases the Database schema upgrade complete dialog was not in focus in the foreground. By using the Alt Tab keys we were able to find the dialog and click OK. 14.When System Configuration dialog appears, click OK. 15.When the System Configuration dialog appears, the settings should already be defined. Click OK. 16.When the Install is complete, click Done.
Upgrade LDAP schema

Complete the following steps after the Tivoli Identity Manager V4.5.1 FP42 installation to upgrade the LDAP schema: 1. Navigate to the c:\itim45\bin directory. 2. Open the ldapUpgrade.lax file in a text editor. 3. Search for INSTALL_UPGRADE=. 4. Ensure that the value is set to INSTALL_UPGRADE=NO. 5. Save and close the file. 6. Open a command prompt and change the directory to c:\itim45\bin and execute ldapUpgrade.exe command. 7. Restart the Tivoli Directory Server V5.2 Windows service.
Verify Tivoli Identity Manager after FP42 install

Now that Tivoli Identity Manager V4.5.1 FP42 has been installed, we recommend that you verify Tivoli Identity Manager as follows: 1. Complete the steps found in Verify Tivoli Identity Manager on page 196. 2. Check the build level of the installation (text in blue bar). It should be as following displayed on the Tivoli Identity Manager logon page:
Tivoli Identity Manager 4.5.1 FP42 Build 5190
198
4.5.9 Tivoli Identity Manager Agent for TAM profile configuration

The following tasks should be performed on the Identity Manager node to configure the Tivoli Identity Manager Agent for TAM profile.
Tivoli Identity Manager Agent profile installation

To install the Tivoli Identity Manager Agent profile, do the following steps: 1. Ensure that the Java Runtime Environment V1.3.1 is installed, which is required by the tam4profile.exe installer. Note: In our scenario, we installed the Sun Java 2 Standard Edition (J2SE) V1.3.1_04 JRE in Install J2SE V1.3.1_04 (browser Java plug-in) on page 195 to address a Java plug-in issue for TIM applets. The tam4profile.exe will detect that this JRE is installed and run. 2. Login to Tivoli Identity Manager to ensure that Tivoli Identity Manager is working fine. 3. Copy the tamprofile.exe from the Tivoli Identity Manager Agent for TAM unpack location, to a temporary directory on the Identity Manager node. 4. Using Windows Explorer, navigate to that temporary directory and execute tam4profile.exe. 5. When the Welcome window appears, click Next. 6. When the Select the directory in which ITIM is installed window appears, Enter the Tivoli Identity Manager installation directory. We have specified c:\ITIM45. Click Next. 7. When the Installer window appears with the selected options, click Next. 8. When the Installer window appears with successful installation message, click Finish. 9. Restart the Tivoli Directory Server V5.2 Windows Service. 10.Restart the server1 WebSphere Application Server hosting the Tivoli Identity Manager application. We have executed the following to restart server1:
C:\WebSphere\AppServer\bin\stopserver server1 C:\WebSphere\AppServer\bin\startserver server1
Tivoli Access Manager service configuration

To establish communication between the Tivoli Identity Manager server and the the Tivoli Identity Manager Agent for Tivoli Access Manager, a service should be defined in the Tivoli Identity Manager server.
199
To configure the Tivoli Access Manager service, do the following steps: 1. Ensure that Tivoli Identity Manager Agent for Tivoli Access Manager is started on the Access Manager node. 2. Login to Tivoli Identity Manager as an administrator (for example, ITIM Manager account to login). 3. Click PROVISIONING. 4. Click Add. 5. For the Service Type, select TAM4Profile from the drop-down list and click Continue. 6. When the Add / Modify Service form appears as shown in, we have specified the following details: Service Name: Tivoli Access Manager URL: https://<tamwin1_IP_Address:45580 Note: We found that we had to use the IP address, not hostname to configuring this (test failed otherwise) User ID: admin Password : <admin_password> Note: Userid and Password are the USERNAME and Password values specified in step 10 of the Tivoli Identity Manager Agent for TAM configuration section. CA certificate store location : c:\ibm\certificates Add Account : select Import or Create user entry. Click Test. 7. It should display a Test Successful window. Click Done. 8. Click Submit on the Add | Modify Service form. 9. Logout of Tivoli Identity Manager by clicking Logout. The Identity Manager node installation is now complete.
4.6 Content Management node installation

This section describes how to install the components of the Content Management node. In our example, the DB2 Content Manager Library Server, Resource Manager and System Administration Client are installed on the same node.
200
The Content Management node installation includes the following tasks: 1. 2. 3. 4. 5. 6. 7. Windows 2000 Server installation Tivoli Directory Client SDK installation WebSphere Application Server V5.1.1 installation DB2 Universal Database V8.2 installation Create user IDs with privileges for Content Manager DB2 Content Manager V8.3 installation DB2 Content Manager V8.3 Client for Windows installation

4.6.2 Tivoli Directory Client SDK installation

Install the Tivoli Directory Client SDK V5.2 with Fixpack 2. For details, refer to 4.3.4, Tivoli Directory Client SDK 5.2 installation on page 159.

This section describes the steps necessary to install IBM WebSphere Application Server V5.1.1, which is required for IBM DB2 Content Manager V8.3.
WebSphere Application Server V5.1 installation

To install WebSphere Application Server V5.1 and IBM HTTP Server V1.3.28, do the following steps: 1. Insert the WebSphere Application Server V5.1 CD. 2. Run launchpad.bat to launch the WebSphere Application Server installer. 3. When the WebSphere Application Server installer appears, click Install the product. 4. When the Welcome dialog appears, click Next. 5. When the License Agreement dialog appears, review the terms and conditions and if in agreement select I accept the terms of the license agreement and click Next. 6. When the Setup Type dialog appears, select Custom and then click Next. 7. When the Installation Features dialog appears, select the options displayed in Figure 4-11, and then click Next.
201
Figure 4-11 WebSphere Application Server installation features
8. When the Product Features Installation Path dialog appears, accept the following default directories and click Next: IBM WebSphere Application Server V5.1: C:\WebSphere\AppServer IBM HTTP Server V1.3.28: C:\IBMHttpServer Embedded messaging Server and Client: C:\IBM\WebSphere MQ
202
9. When the Node Name dialog appears, enter the following information and then click Next: Node Name: <node_name> For example, cmwin1 for the Content Management node. Host Name or IP Address: <fully_qualified_hostname> For example, cmwin1.itso.ral.ibm.com for the Content Management node. 10.When prompted, for the User ID and Password to run WebSphere Application Server and the IBM HTTP Server as Windows services, enter the following information and click Next: Check Run WebSphere Application Server as service Check Run IBM HTTP Server as a service User ID: <admin_user> Password: <user_password> 11.When the Installation Summary dialog appears, review your selections and then click Next to begin copying files. 12.When the installation is complete, you will be prompted to register. Click Next to continue, and then click Finish. 13.When you return to the WebSphere Application Server installer dialog, we suggest you click Verify Installation.
WebSphere Application Server V5.1 Fixpack 1 installation

As a prerequisite to IBM DB2 Content Manager V8.3, you must install IBM WebSphere Application Server V5.1 Fixpack 1 (V5.1.1). For details on downloading and installing IBM WebSphere Application Server V5.1 Fixpack 1 (V5.1.1) refer to:
http://www.ibm.com/support/docview.wss?rs=180&context=SSEQTP&dc=D400&q1=5.1 .1&uid=swg24007195&loc=en_US&cs=utf-8&lang=en

IBM DB2 Content Manager V8.3, Enterprise Edition requires DB2 Universal Database. Install IBM DB2 Universal Database V8.2, Enterprise Server Edition with Fixpack 8. For installation details refer to 4.2.2, DB2 Universal Database V8.2 installation on page 137.
203
4.6.5 Create user IDs with privileges for Content Manager

In IBM DB2 Content Manager V8.3, Enterprise Edition, this step is optional since the DB2 Content Manager installer will create the icmadmin, rmadmin, and icmconct users as part of the install. This section describes how to create user IDs with the proper rights and privileges for these components, if you were to do so manually before the installation.
Create user IDs

Create Windows 2000 user IDs for the users listed in Table 4-8 that will be used by DB2 Content Manager and DB2 Information Integrator for Content (ICMADMIN, ICMCONCT, RMADMIN). Note: The user IDs for Windows, DB2, and Content Manager are not case sensitive. On UNIX/Linux the operating system user ID will be case sensitive.
Table 4-8 Create user IDs for Content Manager User ID Content Manager Library Server administration user ID For example: ICMADMIN Description * This user ID is used if installing and managing the Library Server on the Content Manager node. * This user ID must be a member of the DB2 Admin group (right assignments). * This user ID is used as a database connection ID from the client (Portal Server or Developer node) to the Content Manager node. * This user ID is a standard user with normal privileges and should not be part of the DB2 Admin group, with the following exception: Content Manager makes use of PUBLIC access to DB2 packages. If your security structure allow PUBLIC execution rights on all packages, ICMCONCT needs only to be granted CONNECT rights to the database. If you revoke PUBLIC access, ICMCONCT needs not only CONNECT rights to the databases, but also EXECUTE permission on Content Manager packages.
Content Manager database connection user ID For example: ICMCONCT
204
User ID Content Manager Resource Manager administration user ID For example: RMADMIN
Description * This user ID is used for managing the Resource Manager on the Content Manager node. * This user ID must be a member of the DB2 Admin group (right assignments).
The installation program refers to the IDs by the default names, and you should substitute the names you use if you are not using the default names. Important: The ICMCONCT user ID is a shared Content Manager that is used when a Content Manager user needs to perform a certain task. For example, when you need to define an item type on the Content Manager Server, Content Manager uses this ID to connect the Content Manager user to DB2. The user (for example, ICMCONCT) should be assigned privilege set UserDB2Connect in Content Manager. The encrypted ICMCONCT password is stored in the C:\IBM\db2cmv8\cmgmt\connectors\cmbicmenv.ini file. In our example, the ICMCONCT needs only to be granted DB2 CONNECT authority to the icmnlsdb database.
Add users to DB2 admin group

The user ID icmadmin and rmadmin both need to have DB2 Administrative privileges. One simple way to accomplish this is to add icmadmin and rmadmin to the Administrators group.
User right assignments

The user IDs icmadmin, rmadmin need to have the following Windows 2000 user right assignments: Act as part of the operating system Create a token object Increase quotas Log on as a service Replace a process level token For details on adding these user rights, refer to Create admin user and assign user rights on page 136.
205
4.6.6 DB2 Content Manager V8.3 installation

In our example, we will install the DB2 Content Manager Library Server, Resource Manager, and System Administration Client on the same node. Note: For more detailed information on installing IBM DB2 Content Manager V8.3 Enterprise Edition, refer to the following product guide: Planning and Installing Your Content Management System, IBM DB2 Content Manager V8.3 Enterprise Edition, GG27-1332-03
Prerequisite software
Ensure that the following perquisite software has been installed prior to installing DB2 Content Manager: Ensure That IBM WebSphere Application Server V5.1.1 is installed. Ensure that IBM HTTP Server V1.3.28 is installed. Ensure that IBM DB2 Universal Database V8.2 is installed.
Modify the java.security properties file

If you are installing the resource manager application on this workstation, you need to modify the WebSphere Application Server properties file before you begin the installation program. To update the java.security properties file used by WebSphere Application Server, do the following steps: 1. Navigate to the following directory:
<was_home>\AppServer\java\jre\lib\security
2. Open the java.security properties file. 3. The following two lines must be added to the properties file (java.security) and modified to obtain the correct default values for SSL configuration that takes place during installation:
security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.2=com.ibm.fips.jsse.IBMJSSEFIPSProvider
Note: Ensure that the provider.<number> for the other entries are updated accordingly (no duplicates). 4. Save the java.security file.
206
Install DB2 Content Manager

To install IBM DB2 Content Manager V8.3, Enterprise Edition, do the following steps: 1. Insert the IBM DB2 Content Manager V8.3, Enterprise Edition CD. 2. Run setup.bat to start the installer. 3. From the Launchpad, click Install. 4. When prompted to select the product, select DB2 Content Manager and then click Next. 5. When the Welcome dialog appears, click Next. 6. When the License Agreement dialog appears, review the terms and select I accept the terms of the agreement, then click Next. 7. When prompted for the installation destination, we entered C:\IBM), and then clicked Next. Note: The files will be installed to the db2cmv8 directory within the IBM directory (for example, C:\IBM\db2cmv8). 8. When prompted to select the installation type, select Typical and then click Next. 9. When the System Information dialog appears, enter the fully qualified host name (for example, cmwin1.itso.ral.ibm.com) and click Next. 10.When the Library Server Database dialog appears, enter the following information and then click Next: Library server database name: icmnlsdb (default) Library server database administration ID: icmadmin (default) Password: <your_password> Confirm password: <your_password> 11.You may see a warning dialog, The user ID icmadmin (user entered in previous step) does not exist on this system. Click Yes to create the user ID. 12.When the Library Server Database dialog appears, enter the following and then click Next: Library server connection ID: icmconct (default) Password: <your_password> Confirm password: <your_password>
207
13.You may see a warning dialog, The user ID icmconct (user entered in previous step) does not exist on this system. Click Yes to create the user ID. 14.When the Resource Manager Database dialog appears, enter the following and then click Next: Resource Manager database name: rmdb (default) Resource Manager database administration ID: rmadmin (default) Password: <your_password> Confirm password: <your_password> Resource Manager volume mount point: C:\ 15.You may see a warning dialog, The user ID rmadmin (user entered in previous step) does not exist on this system. Click Yes to create the user ID. 16.When the Resource Manager Application dialog appears, enter the application server node name (for example, cmwin1), and click Next. 17.When the Features Summary dialog appears, review the selections and click Next to begin copying files. 18.When the installation is complete, check the Launch Installation Validation Utility (default) and click Next. 19.When the Installation Validation Utility Results dialog appears, ensure that the validation tasks were completed successfully and then click Next. 20.Click Finish to complete the installation. 21.Click Exit to close the installer.
4.6.7 DB2 Content Manager V8.3 Client for Windows installation

In our example, we will install the IBM DB2 Content Manager V8.3 Client for Windows on the same system as the DB2 Content Manager. We will use the Client to verify our application deployment. Note: Alternatively, you can install the DB2 Content Manager eClient (Web based). For details on installing the eClient, refer to Planning and Installing Your Content Management System, IBM DB2 Content Manager V8.3 Enterprise Edition, GG27-1332-03.
208
To install the DB2 Content Manager V8.3 Client for Windows, do the following steps: 1. Insert the IBM DB2 Content Manager V8.3, Enterprise Edition CD. 2. Run setup.bat to start the installer. 3. From the Launchpad, click Install. 4. When prompted to select the product, select DB2 Content Manager Client for Windows and then click Next. 5. When prompted for the setup language, select the desired language (for example, English) and click OK. 6. When the Welcome dialog appears, click Next. 7. When the License Agreement dialog appears, review the terms and select I accept the terms of the agreement, then click Next. 8. You will be prompted for the installation destination. If you installed the DB2 Content Manager Client for Windows on a system that has DB2 Content Manager installed, it will use the same root directory for the install and append Client (for example, C:\IBM\db2cmv8\Client). Click Next. 9. When prompted to select the installation type, select Typical and then click Next. 10.When the DB2 Content Manager Initialization Files Location - Remote dialog appears, accept the default and click Next. 11.When the DB2 Content Manager Initialization Files Location - Local dialog appears, accept the default and click Next. 12.When the Ready to Install the Program dialog appears, click Install to begin copying files. 13.When the installation is complete, click Finish.
4.7 Portal Server node installation

The Portal Server node installation includes the following tasks: 1. 2. 3. 4. 5. 6. 7. 8. 9. Windows 2000 Server installation WebSphere Portal V5.1 installation IBM HTTP Server and WebSphere plug-in installation Java Runtime Environment (JRE) V1.3.1 installation Tivoli Access Manager Java Runtime Environment installation DB2 UDB V8.2 ESE installation DB2 UDB Client configuration to Content Manager Information Integrator for Content V8.3 installation Tivoli Identity Manager V4.5.1 API installation
209

4.7.2 WebSphere Portal V5.1 installation

This section describes how to install IBM WebSphere Portal V5.1 in the runtime environment using the Full installation type. IBM WebSphere Portal V5.1 has three installation types: Full: This install type installs everything you will need for WebSphere Portal, including WebSphere Application Server. When selecting this installation type, the WebSphere Portal installer will unpack archives of a full install image from the CD to speed up the installation. For this reason, some of the CDs you will be prompted for will differ from the Custom or Test Environment installations. Note: For the runtime environment described in this section, we will select the Full installation type. Custom: This install type is used if WebSphere Application Server is already installed. Test Environment: This install type is used to install the WebSphere Portal V5.1 Test Environment that is used to develop and test portlets within IBM Rational Application Developer V6.0. Note: In the development environment, we will select the Test Environment installation type as described in 6.4.2, WebSphere Portal V5.1 Test Environment installation on page 349.
210
Tip: Eliminate installer prompting of CDs: To speed up the WebSphere Portal installation (Full installation type), we copied the contents of CDs to the following directory structure on a network file share. By using the directory names noted, the WebSphere Portal installer will not prompt for CDs and thus complete the installation without intervention during the middle of the install: /wp51/setup /wp51/cd1-1 /wp51/cd1-2 /wp51/cd4-1 /wp51/cd5-1 /wp51/cd5-3
Table 4-9 IBM WebSphere Portal V5.1 CDs used for Full installation type IBM WebSphere Portal V5.1 CDs used for Full installation type WebSphere Portal V5.1 - Portal Install (Setup) WebSphere Portal V5.1 - WebSphere Business Integrator Server Foundation (1-1) WebSphere Portal V5.1 - WebSphere Business Integrator Server Foundation (1-2) WebSphere Portal V5.1 - WebSphere Application Server Archive Install for Windows (4-1) WebSphere Portal V5.1 - Portal Server Archive Install for Windows (5-1) WebSphere Portal V5.1 - Portal Server Archive Install for Multiplatforms (5-3) Directory setup cd1-1 cd1-2 cd4-1 cd5-1 cd5-3
Note: The following CDs are used for a Custom or Test Environment installation instead of the Archive Install CDs (5-1, 5-3). IBM WebSphere Portal V5.1 - WebSphere Business Integrator Server Foundation WebSphere Application Server V5.1 Fixpack 1 (1-15) IBM WebSphere Portal V5.1 - Portal Server (2) IBM WebSphere Portal V5.1 - Lotus Workplace Web Content Management (3) cd1-15 cd2 cd3
The WebSphere Portal V5.1 installation requires you to log on with an ID with sufficient user privileges on the system. The user account must be part of the local Administrators group and must have the following user rights assigned to it: Act as part of the operating system Log on as a service In our example, we have a user named admin with the proper right assignments.
211
You can change user privileges by going to Start Programs Administrative Tools Local Security Policy. This will then open a new window. In this window, expand Security Settings Local Policies User Rights Assignment. Note: After assigning user privileges, you should log off from Windows and log on again for the changes to become effective. For the WebSphere Portal V5.1 base installation, complete the following steps: 1. Run install.bat from the setup folder in the Setup CD. 2. Choose your preferred language and click OK. 3. Click Next and you will have the option to launch the Information Center (Figure 4-12).
Figure 4-12 Launch Information Center window
4. Click Next. 5. Read and the license agreement, and if in agreement, click Next.
212
Note: If you have firewall applications running on the server, a warning message similar to the one shown in Figure 4-13 will be presented. Disable any firewall applications before you proceed.
Figure 4-13 Warning message detecting firewall application
6. Select a Full installation, as shown in Figure 4-14, and proceed to the next window.
Figure 4-14 Select Full installation
213
7. Enter your choice for the WebSphere Application Server installation directory (Figure 4-15), for example, C:\WebSphere\AppServer, and click Next.
Figure 4-15 WebSphere Application Server installation directory
214
8. Enter or accept the Node name (for example, wpwin1) and the fully qualified host name (for example, wpwin1.itso.ral.ibm.com). See Figure 4-16. Click Next to proceed to the next window.
Figure 4-16 Confirm Node name and fully qualified hostname
215
9. Confirm your choice for the installation directory for WebSphere Portal. For our example, we entered C:\WebSphere\PortalServer. 10.Enter the System Logon User ID and Password (Figure 4-17) and accept the default values for the other fields. Click Next.
Figure 4-17 Run as Windows service
216
11.Enter your choice of Portal administrative user name and password (Figure 4-18). Do not use blanks in either the user ID or the password fields, and ensure that the password is at least five characters in length. This user ID is used to access WebSphere Portal with administrator authority after the installation. Note that this user ID is only used to log in to WebSphere Portal and is not related to any user IDs used to access the operating system itself. Click Next.
Figure 4-18 WebSphere Portal administrative user name and password
217
12.Confirm your choices and click Next on the summary information window (Figure 4-19).
Figure 4-19 Summary information for the installation
Note: The progress bar on the install will reset several times; this is normal. 13.Click Finish to complete the installation.
218
Verify the installation of WebSphere Portal

Note: Checkpoint for WebSphere Portal: At this point, WebSphere_Portal and server1 are not started. Before continuing, you will need to start them. To start them, complete the following steps: 1. 2. 3. 4. 5. Open a command prompt. Change the C:\WebSphere\AppServer\bin directory. Issue the startserver.bat server1 command. Wait for it to finish and start up. Then, issue the startserver.bat WebSphere_Portal command.
The capitalization is important in the server name. Additionally, for the My Tasks portlet to work, server1 must be running. To verify that the installation is successful, go to a browser and type in the following URL:
http://<fully_qualified_host_name>:9081/wps/portal
For example, in our scenario, the URL of the portal will be http://wpwin1.itso.ral.ibm.com:9081/wps/portal.
Note: Checkpoint for the servlet engine: To verify that the servlet engine is up and running, go to a browser and type in the following URL:
http://<fully_qualified_hostname>:9080/snoop
Where the <fully_qualified_host_name> in the example is wpwin1.itso.ral.ibm.com. The portal is now up and running.
219
After completing the checkpoint procedure for the servlet engine, click Log in and enter the WebSphere Portal administrator ID and password (for example, admin), as shown in Figure 4-20.
Figure 4-20 Logging in using the WebSphere Portal administrator ID
The base installation is now complete. Note: In our installation, we were behind a firewall, so we removed the Screaming Media portlets from the Welcome page because this can impact the login performance (5-10 minute delay timeout).
4.7.3 IBM HTTP Server and WebSphere plug-in installation

By default, WebSphere Portal V5.1 does not install or configure itself for use with the IBM HTTP Server. In this section we will install the IBM HTTP Server V1.3.28 as well as the WebSphere Application Server V5.1 plug-in. In 5.2, Configure WebSphere Portal with IBM HTTP Server on page 248, we will configure WebSphere Portal to use the external IBM HTTP Server.
220
To install the IBM HTTP Server V1.3.28 and WebSphere Application Server V5.1 plug-in, do the following steps: 1. Insert the WebSphere Application Server V5.1 CD (WebSphere Portal V5.1 CD1-1). 2. Navigate to the <CD_Root>\win\was folder. Run Install.exe to start the installer. 3. When the Welcome dialog appears, click Next. 4. When the License agreement dialog appears, review the terms and if in agreement select I accept the terms of the license agreement and then click Next. 5. The installer will detect an existing installation of WebSphere Application Server. In our example, we selected the Add features to existing copy (C:\WebSphere\AppServer), and then clicked Next. 6. When the Features Selection dialog appears, we checked the following options and then clicked Next: Check IBM HTTP Server V1.3.28 Check Web server plug-ins Check Plug-in for IBM HTTP Server V1.3 Uncheck remaining features. Note: Features that have already been installed will be checked and can not be unchecked from this dialog. Only check the options we have listed. 7. When the Installation location dialog appears, we entered the following information and then clicked Next: IBM WebSphere Application Server V5.1: C:\WebSphere\AppServer IBM HTTP Server V1.3.28: C:\IBMHttpServer 8. When Windows services to run WebSphere Application Server and IBM HTTP Server dialog appears, we entered the following information and then clicked Next: Check Run WebSphere Application Server as a service Check Run IBM HTTP Server as a service User ID: admin Password: <password> 9. When the Installation Features Summary dialog appears, review the selections and click Next to begin copying files. 10.When the installation is complete, click Finish.
221
Note: The WebSphere Application Server V5.1 plug-in configuration with the IBM HTTP Server V1.3.28 will be completed in 5.2, Configure WebSphere Portal with IBM HTTP Server on page 248.
4.7.4 Java Runtime Environment (JRE) V1.3.1 installation

For details, refer to 4.3.2, IBM Java Runtime Environment (JRE) V1.3.1 installation on page 158.
4.7.5 Tivoli Access Manager Java Runtime Environment installation

This section describes how to install and configure the following features: Install Tivoli Access Manager Java Runtime Environment Install Tivoli Access Manager V5.1 Base Fixpack 9 Configure PDJRTE for IBM JRE V1.3.1
Install Tivoli Access Manager Java Runtime Environment

To install and configure the Tivoli Access Manager Java Runtime Environment (PDJRTE) using the native installation utility, do the following on the Portal Server node: 1. Ensure that the following Windows services are started: IBM Tivoli Directory Server V5.2 (Directory node) Access Manager Policy Server (Access Manager node) 2. Insert the Tivoli Access Manager Base for Windows NT, Windows XP, Windows 2000 and Windows 2003 CD. 3. Navigate to the <CD_Root>\windows\PolicyDirector\Disk Images\Disk1 folder and run Setup.exe to start the installation. 4. When the Choose Setup Language window appears, select the language for the installation process (for example, English) and click OK. 5. When the Welcome window appears, click Next. 6. When the License Agreement window appears, if in agreement click Yes to continue. 7. When the Select Packages window appears, we checked the following package and then clicked Next: Check Access Manager Java Runtime Environment (PDJRTE). Uncheck all other packages. 8. Choose the destination folder (for example, c:\ibm\tam) and click Next. 9. Review your settings and click Next.
222
10.When the installation is complete, you should see a dialog with the message Installation completed successfully. Click OK to exit.
Install Tivoli Access Manager V5.1 Base Fixpack 9

For details, refer to 4.3.10, Tivoli Access Manager V5.1 Base Fixpack 9 installation on page 168.
Configure PDJRTE for IBM JRE V1.3.1

To configure the Tivoli Access Manager Java Runtime Environment (PDJRTE) for the IBM JRE V1.3.1, do the following on the Portal Server node: Note: We found that the Java Runtime Environment included with IBM WebSphere Application Server V5.1 is not compatible with the SvrSslCfg command (used in SSL configuration between WebSphere Application Server and Tivoli Access Manager). For this reason, we installed the Tivoli Access Manager Java Runtime Environment V1.3.1 and configured the Tivoli Access Manager Java Runtime Environment (PDJRTE) to use the IBM JRE V1.3.1 packaged with Tivoli Access Manager. 1. Open a command window and navigate to the c:\ibm\tam\sbin directory. 2. Enter the following command:
pdjrtecfg -action config -config_type full -host tamwin1.itso.ral.ibm.com -port 7135 -java_home c:\ibm\Java131\jre
You should see the following message:

Configuration of Access Manager Java Runtime Environment completed successfully.
Note: If your application uses the Tivoli Access Manager APIs, you may need to configure the PDJRTE to use the WebSphere Application Server JRE. Our application in our sample did not use the Tivoli Access Manager APIs.
4.7.6 DB2 UDB V8.2 ESE installation

We installed IBM DB2 Universal Database V8.2, Enterprise Server Edition + Fixpack 8 on the Portal Server node. For details, refer to DB2 Universal Database V8.2 installation.
223
4.7.7 DB2 UDB Client configuration to Content Manager

This section describes how to configure the DB2 UDB Client on the Portal Serve node to the DB2 UDB Server on the Content Management node. 1. Open DB2 command window. 2. Catalog the tcpip node:
db2 catalog tcpip node cmwin1 remote cmwin1 server 50000
3. Verify the tcpip connection via attach:

db2 attach to cmwin1 user <user> using <password>
4. Catalog the Library Server database:

db2 catalog db icmnlsdb at node cmwin1
4.7.8 Information Integrator for Content V8.3 installation

IBM DB2 Information Integrator for Content V8.3 is required so that the portal front-end interface of the document management application can access the back-end DB2 Content Manager document repository. Note: Information Integrator for Content requires the DB2 Run-Time Client installed. If the Information Integrator for Content connector is installed first, it will assume that the DB2 Run-Time Client is installed in c:\sqllib. On the Portal Server node, we install IBM DB2 Universal Database V8.2, Enterprise Server Edition, which includes the DB2 Client. This section describes how to install the IBM DB2 Information Integrator for Content V8.3 connector to access IBM DB2 Content Manager V8.3, Enterprise Edition.
Install Information Integrator for Content

To install the Information Integrator for Content, do the following steps: 1. Ensure that the following DB2 Content Manager servers are started on the Content Management node: DB2 Windows services IBM HTTP Server V1.3.28 Windows service ICM LS Monitor icmnlsdb Windows service (Library Server) icmrm WebSphere Application Server (Resource Manager)
224
2. Insert the Information Integrator for Content CD on the Developer node. If the install does not start automatically, navigate to the CD and run setup.bat. 3. Click Install from the launchpad welcome dialog. 4. Select DB2 Information Integrator for Content and click Next. 5. When the Welcome window appears, click Next. 6. Review the License Agreement. If you accept, select I accept the terms in the license agreement and click Next. 7. We entered C:\IBM in the Installation path field, and then clicked Next. Note: The files will be installed in the db2cmv8 directory within the installation directory entered here (for example, C:\IBM\db2cmv8). 8. After performing a product check, the Setup Type window will appear. Select the Connector type and click Next as shown in Figure 4-21. Note: For development purposes, select the Developer Workstation Client. This option includes Java samples useful for testing purposes. Then check Java for the Toolkit and Samples type. There will be a few extra installation panels than what is documented in this procedure.
225
Figure 4-21 Information Integrator for Content Setup Type selection
9. When the Server Connection Selection window appears, select DB2 Content Manager Version 8 as shown in Figure 4-22 and click Next.
226
Figure 4-22 Server Connection Selection
10.When the Working Directory window appears, we entered C:\IBM\db2cmv8 and then clicked Next. 11.When the System Configuration Files window appears, keep the default selection of Local and click Next. Note: The location for the files cannot be changed but it is displayed (for example: C:\IBM\db2cmv8\cmgmt\connectors). 12.When the DB2 Content Manager Version 8 Connector window appears, enter the values used during the installation of DB2 Content Manager in section 4.6.6, DB2 Content Manager V8.3 installation on page 206. The Content Manager server is on another machine so also select Configuration connection to remote library server database. The values and selections are shown in Figure 4-23. Then click Next.
227
Figure 4-23 DB2 Content Manager Version 8 Connector
13.In the next window, enter the user ID (for example: icmconct) for connecting to the Content Manager library server database along with the password. This must match the user ID that you used while setting up the library server database in section 4.6.6, DB2 Content Manager V8.3 installation on page 206. Then click Next. 14.The next window configures the connection to the Content Manager library server database. For example, Figure 4-24 shows the values entered for a Content Manager server named cmwin1. After entering the values for your library server database connection, click Next.
228
Figure 4-24 DB2 Content Manager Version 8 library server connection
15.When the Summary window appears, click Next to start the installation of the files. 16.When the installation is complete, select the Launch Installation Validation Utility and click Next. 17.Once validation has completed successfully, click Next. 18.On the final window, click Finish. 19.Click Exit on the launchpad window.
Configure Information Integrator for Content

This section describes how to configure the DB2 Information Integrator for Content environment by updating the variable paths in the cmbenv81.bat. 1. Open a Windows command window and navigate to the Information Integrator for Content installation bin directory (for example, C:\IBM\db2cmv8\bin).
229
2. Ensure that the following environment variable values in the cmbenv81.bat for your installation paths are correct: IBMCMROOT DB2HOME For example:
if "%IBMCMROOT%"=="" set IBMCMROOT=C:\IBM\db2cmv8 if "%DB2HOME%"=="" set DB2HOME=c:\ibm\sqllib
3. Save and close the file.
Verify Information Integrator for Content connection

After installing Information Integrator for Content, we recommend that you verify the connectivity to the Content Management node. 1. Ensure that the following DB2 Content Manager components are started on the Content Management node: DB2 Universal Database Windows services Start the ICM LS Monitor icmnlsdb (Content Manager Library Server Windows service) Start the icmrm application server
<was_home>\bin\startServer.bat icmrm
IBM HTTP Server Windows services. 2. Open a command window and navigate to the C:\IBM\db2cmv8\bin directory. 3. Run the following command to set the environment:
cmbenv81.bat xmlsdk
4. Set the Java_Home so that we can use the Java compiler (javac):
set path=%path%;c:\WebSphere\AppServer\java\bin
Note: In the development environment, enter the following path to the Java compiler provided with WebSphere Application Server:
set path=%path%;c:\Program Files\Portal51UTE\AppServer\java\bin
5. Navigate to the following directory: C:\IBM\db2cmv8\samples\java\xml 6. Compile the code with javac as follows:
javac TXMLList.java
7. Run TXMLList as follows:

java TXMLList -d icmnlsdb -u icmadmin -p <password> -a
230
You should see console output like the following message:

Listed Objects successfully!
Attention: If this test does not work, you should not continue until it is resolved.
4.7.9 Tivoli Identity Manager V4.5.1 API installation

The IBM Tivoli Identity Manager V4.5.1 API jars will allow the provisioning portlets to communicate with Tivoli Identity Manager for the provisioning of users.
Install the Tivoli Identity Manager JARs

In order to use the Tivoli Identity Manager API for implementing the portal interface, the appropriate JAR files must be installed into the WebSphere Portal server: 1. Stop the WebSphere Portal server. In the runtime environment, enter the following to stop the WebSphere Portal server:
c:\WebSphere\AppServer\bin\stopServer WebSphere_Portal
At this stage in our procedure in the development environment, the WebSphere Portal server has not yet been configured. 2. On the Identity Manager node, locate the following Tivoli Identity Manager JARs (for example, c:\itim45\lib). api_ejb.jar itim_api.jar ldapjdk.jar 3. Copy the JARs to the shared library directory on the WebSphere Portal server (for example: c:\WebSphere\PortalServer\shared\app). This will make the Tivoli Identity Manager API available to all portlets and also allow the JARs to be updated without rebuilding the user provisioning application. Note: In the development environment, the directory is as follows:
c:\Program Files\Portal51UTE\PortalServer\shared\app
4. Start the WebSphere Portal server. In the runtime environment, enter the following to stare the WebSphere Portal server:
c:\WebSphere\AppServer\bin\startServer WebSphere_Portal
231
At this stage in our procedure in the development environment, the WebSphere Portal server has not yet been configured.
Configure JAAS
In order for the Tivoli Identity Manager API to connect to the remote Tivoli Identity Manager server, a JAAS application login must be configured in WebSphere Application Server. Complete the following steps to configure JAAS in WebSphere Application Server on the Portal Server node (or Developer node in the development environment). 1. Start the server1 application server on the Portal Server node:
C:\WebSphere\AppServer\bin\startServer server1
Note: In the development environment, the server1 application server can be started as follows:
c:\Program Files\Portal51UTE\AppServer\bin\startServer server1
2. Start the WebSphere Administrative Console and logon:

http://<hostname>:9090/admin
3. Select and expand Security JAAS Configuration Application Logins. 4. Click New to create a login configuration for Tivoli Identity Manager. 5. Enter ITIM in the Alias name field, and then click Apply. 6. Under the Additional Properties heading, click JAAS Login Modules. 7. Click New to add a login module to the ITIM configuration. a. Enter com.ibm.itim.apps.jaas.spi.PlatformLoginModule in the Module Classname field. The Proxy Classname field should contain com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy. Note: A custom property named delegate will automatically be added with the value from the Module Classname field. In previous versions of WebSphere Application Server, this property had to be added manually. b. Select REQUIRED for the Authentication Strategy and click Apply. 8. Under Message(s) click Save. 9. Under Save to Master Configuration, click Save. 10.Logout and close the WebSphere Administrative Console.
232
11.Stop the server1 application server:

C:\WebSphere\AppServer\bin\stopServer server1
Note: In the development environment, the server1 application server can be started as follows:
c:\Program Files\Portal51UTE\AppServer\bin\stopServer server1
This concludes the installation and base configuration. Proceed to Chapter 5, Runtime environment configuration on page 235 to further configure the nodes for integration.
233
234
Chapter 5.
Runtime environment configuration

In Chapter 4, Runtime environment installation on page 129, we performed the installation and base configuration of the nodes in a standalone fashion. This chapter focuses on configuration tasks to integrate and secure access to the nodes. The chapter is organized into the following sections: Configure WebSphere Portal for DB2 UDB Configure WebSphere Portal with IBM HTTP Server Configure WebSphere Portal with LDAP Configure DB2 Content Manager with LDAP Enable mutual SSL between WebSEAL and Portal Configure Portal authentication with TAM using TAI Configure WebSphere Portal authorization with TAM Configure reverse password synchronization Additional configuration and security hardening
235
5.1 Configure WebSphere Portal for DB2 UDB

By default, WebSphere Portal installs and uses an IBM Cloudscape database to store information about user identities, credentials, and permissions for accessing portal resources. Cloudscape is a built-in Java database that is well-suited to basic portal environments. However, if the demands of your portal environment include database software with greater capability and scalability, you can also configure WebSphere Portal to use a more robust database, such as IBM DB2 Universal Database V8.2, Enterprise Server Edition. For example, Cloudscape does not support vertical cloning or a cluster environment, nor does it support enabling security in a database only mode. Performance gains might also be possible by moving to a more robust database. If you want to use another database, you must transfer data from the Cloudscape database to your preferred database. For the purpose of the proof of concept, we illustrate the migration of Cloudscape to a local DB2 Universal Database. The configuration of WebSphere Portal for DB2 Universal Database includes the following tasks: 1. Create a DB2 user for WebSphere Portal 2. Create DB2 UDB databases for WebSphere Portal 3. Migrate the data from Cloudscape to DB2 UDB
5.1.1 Create a DB2 user for WebSphere Portal

You first need to create a database user on the Microsoft Windows operating system. The user should be defined locally and belong to the local Administrators group. In our example, we created user named admin with the proper privileges. For details, refer to Create admin user and assign user rights on page 136. In our example, we created a user named admin with these rights.
5.1.2 Create DB2 UDB databases for WebSphere Portal

This section describes how to create the DB2 UDB databases that will be used by IBM WebSphere Portal V5.1. Database functions are listed in Figure 5-1.
236
Table 5-1 Database functions Database wpsdb fdbkdb Database function Stores information about user customizations, such as pages, and user and login information. Contains the information logged by your Web site for generating reports for analysis of site activity, including information about campaigns and personalized resources. Contains the information to be stored for DB2 Content Manager. Contains information used to analyze the user activities and make recommendations for Personalization. Contains the IBM Lotus Workplace Web Content Management data.
jcrdb lmdb wcmdb
Note: For a detailed description of each of the keywords, refer to the WebSphere Portal InfoCenter found at:
http://www.ibm.com/developerworks/websphere/zones/portal/proddoc.html#500
To create the DB2 UDB databases for WebSphere Portal, do the following steps: 1. Ensure that IBM DB2 Universal Database V8.2, Enterprise Server Edition is installed and the Windows services are started. 2. Open a command prompt and change to the <wp_home>/config directory. 3. Create a backup copy of the <wp_home>/config/wpconfig.properties file. 4. Update the wpconfig.properties file fields applicable to your environment. We updated the properties in the wpconfig.properties for each of the following section headings (match InfoCenter): Database properties section: Refer to Table 5-2. DB2 Content Manager properties section: Refer to Table 5-3. Personalization and Feedback Database properties section: Refer to Table 5-4. LikeMinds properties section: Refer to Table 5-5. Member Manager properties section: Refer to Table 5-6. Note: For database transfers, all databases must use the same database user name and password. For example, if you use db2admin for the wpsdb user name, you must also use db2admin for the fdbkdb, lmdb, and jcrdb user names.
Chapter 5. Runtime environment configuration
237
Table 5-2 Values used in Database properties section Property DbType wpsDbName DbDriver DbDriverDs JdbcProvider DbUrl DbUser DbPassword DbLibrary Value used db2 wpsdb COM.ibm.db2.jdbc.app.DB2Driver COM.ibm.db2.jdbc.DB2XADataSource wpsdbJDBC jdbc:db2:wpsdb admin <password> C:/ibm/SQLLIB/java/db2java.zip
Table 5-3 Values used in DB2 Content Manager properties section Property jcrDbName jcrDbUser jcrDbPassword jcrDbUrl Value used jcrdb admin <password> jdbc:db2:jcrdb
Table 5-4 Values used in Personalization and Feedback Database properties section Property FeedbackDbName FeedbackDbUser FeedbackDbPassword FeedbackDbUrl Value used fdbkdb admin <password> jdbc:db2:fdbkdb
Table 5-5 Values used in LikeMinds properties section Property LikemindsDbName LikemindsDbUser LikemindsDbPassword LikemindsDbUrl Value used lmdb admin <password> jdbc:db2:lmdb
238
Table 5-6 Values used in Member Manager properties section Property WmmDbName WmmDbUser WmmDbPassword WmmDbUrl Value used wpsdb admin <password> jdbc:db2:wpsdb
5. Save the file. 6. From a command prompt in the <wp_home>/config directory, enter the following command to configure WebSphere Portal for DB2 Universal Database with the settings defined in the wpconfig.properties file:
WPSconfig.bat create-local-database-db2
You should see the message, BUILD SUCCESSFUL, after successfully running the command. Note: In our environment, this task took approximately 10 minutes to complete. 7. Verify the connectivity to the DB2 databases: a. WebSphere Portal Server database (wpsdb): From a command prompt <wp_home>/config directory, enter the following command to validate the connection to the WebSphere Portal Server database (wpsdb):
WPSconfig.bat validate-database-connection-wps
You should see the message, BUILD SUCCESSFUL, after successfully running the command. b. WMM database (wpsdb): From a command prompt <wp_home>/config directory, enter the following command to validate the connection to the wmm database (wpsdb):
WPSconfig.bat validate-database-connection-wmm
You should see the message, BUILD SUCCESSFUL, after successfully running the command. c. Likeminds database (lmdb): From a command prompt <wp_home>/config directory, enter the following command to validate the connection to the Likeminds database (lmdb):
WPSconfig.bat validate-database-connection-likeminds
239
You should see the message, BUILD SUCCESSFUL, after successfully running the command. d. Feedback database (fdbkdb): From a command prompt <wp_home>/config directory, enter the following command to validate the connection to the Feedback database (fdbkdb):
WPSconfig.bat validate-database-connection-feedback
You should see the message, BUILD SUCCESSFUL, after successfully running the command. e. Jcr database (jcrdb): From a command prompt <wp_home>/config directory, enter the following command to validate the connection to the jcr database (jcrdb):
WPSconfig.bat validate-database-connection-jcr
You should see the message, BUILD SUCCESSFUL, after successfully running the command. f. IBM Lotus Workplace Web Content Management database (wcmdb): From a command prompt <wp_home>/config directory, enter the following command to validate the connection to the jcr database (wcmdb):
WPSconfig.bat validate-database-connection-wcm
You should see the message, BUILD SUCCESSFUL, after successfully running the command.
5.1.3 Migrate the data from Cloudscape to DB2 UDB

After the DB2 UDB databases have been created for WebSphere Portal, the data need to be migrated from the Cloudscape databases to the DB2 UDB databases. 1. Ensure that server1 is started and that WebSphere_Portal is stopped: a. Open a command prompt and change to the <was_home>\bin directory. b. Issue the serverstatus.bat -all command. c. If server1 is stopped, issue the startserver.bat server1 command. d. If WebSphere_Portal is running, issue the stopserver.bat WebSphere_Portal command. 2. From a command prompt, change to the <wp_home>\config\wizard directory and then execute the configwizard.bat command. 3. For the language, select English. 4. Click Next on the Welcome window.
240
5. Make sure that the Transfer data to another database option is selected, as shown in Figure 5-1. Click Next.
Figure 5-1 Transfer data to another database
241
6. Ensure that IBM DB2 Universal Database is selected, as shown in Figure 5-2. Click Next.
Figure 5-2 Select IBM DB2 Universal Database
242
7. If we had not already edited the wpconfig.properties file, we could choose one of the config helper files, but here we choose wpconfig.properties, as shown in Figure 5-3. Click Next.
Figure 5-3 Choose the wpconfig.properties file
243
8. You will be taken through several windows, such as the one shown in Figure 5-4. Verify the entries and click Next. Note: These values are pulled from the wpconfig.properties file, so verify them if you have not already updated them. It is possible that you could have chosen the helper file transfer_db2.properties from <wp_home>\config\helpers.
Figure 5-4 Verify the populated entries
244
9. After verifying all the inputs, the window shown in Figure 5-5 opens. Click Next to start the transfer process. Note: In our environment, the transfer process took approximately 30 minutes to complete.
Figure 5-5 Transfer the data
245
10.When the window shown in Figure 5-6 opens, click Finish to end the configuration wizard.
Figure 5-6 Process finished
11.We recommend that you perform a reorg check to improve performance: a. Open a DB2 command window. b. Connect to the database (wpsdb, jcrdb, lmdb, fdbkdb).
db2 connect to <database_name>
For example:
db2 connect to wpsdb
c. Run the following commands:

db2 reorgchk update statistics on table all db2 terminate
d. Enter the following commands to rebind the database:

db2rbind <database_name> -l db2rbind.out -u <db2_admin> -p <password>
You should see the message, Rebind done successfully for database <name>. e. Repeat for each database (wpsdb, jcrdb, lmdb, fdbkdb).
246
12.Start WebSphere Portal by opening a command prompt and navigating to the <was_home>\bin directory and enter the following command:
startserver.bat WebSphere_Portal
13.Verify the portal by typing in the URL of the portal:

http://<fully_qualified_hostname_name>:9081/wps/portal
You have now completed the migration of the WebSphere Portal database from Cloudscape to DB2 Universal Database. Note: Checkpoint for WebSphere Portal: Make sure that WebSphere Portal is started and verify that you can log in to Portal. Logs to check are configwizard.log, configwizardlog.txt, and configtrace.log (these can be found in <wp_home>\log). Additionally, you can check the system, and if you see the lines shown in Example 5-1, you can verify that DB2 Universal Database is being used correctly.
Example 5-1 configwizard.log example [1/4/05 13:45:09:781 EST] name : DB2/NT [1/4/05 13:45:09:797 EST] version : 08.01.0006 [1/4/05 13:45:09:797 EST] : IBM DB2 JDBC 2.0 Type 2 [1/4/05 13:45:09:797 EST] version : 08.01.0006 71d9b471 WSRdbDataSour I DSRA8203I: Database product 71d9b471 WSRdbDataSour I DSRA8204I: Database product 71d9b471 WSRdbDataSour I DSRA8205I: JDBC driver name 71d9b471 WSRdbDataSour I DSRA8206I: JDBC driver
Attention: The configuration wizard does not transfer IBM Lotus Workplace Web Content Manager (LWWCM) data. Therefore, after doing a DB2 configuration wizard DB transfer, IBM Lotus Workplace Web Content Manager still points to the Cloudscape database. For more detailed information, refer to the following documentation: IBM WebSphere Portal for Multiplatforms Version 5.1 Information Center. IBM WebSphere Portal for Multiplatforms Release Notes - Version 5.1.0, available at:
http://pvcid.raleigh.ibm.com/wpf/ic/510/ent/en/beta/wp_release_notes.html #ilwwcm
247
5.2 Configure WebSphere Portal with IBM HTTP Server

By default, the WebSphere Portal Server is configured to use the internal HTTP services of the WebSphere Application Server. This section describes how to configure an external IBM HTTP Server with WebSphere Portal V5.1. In WebSphere Portal V5.1, the IBM HTTP Server is not installed when selecting Full install type. Note: As a prerequisite to this section, you will need to have installed the IBM HTTP Server V1.3.28 and the WebSphere Application Server V5.1 plug-in for the IBM HTTP Server. For details, refer to 4.7.3, IBM HTTP Server and WebSphere plug-in installation on page 220.
5.2.1 IBM HTTP Server configuration

This section describes how to configure the IBM HTTP Server for SSL, as well as how to configure the WebSphere Application Server plug-in for use with IBM HTTP Server. Enable the httpd.conf for SSL Copy WebSphere plug-in entries Create a key store Create a self-signed certificate Verify IBM HTTP Server Configure WebSphere Application Server host alias for SSL Verify WebSphere Application Server
Enable the httpd.conf for SSL

To modify the httpd.conf to enable SSL support, do the following steps: 1. Stop the IBM HTTP Server V1.3.28 Windows service. 2. Back up the original httpd.conf. For example:
cd \<ihs_home>\conf copy httpd.conf httpd.conf.org
3. Copy the httpd.conf.sample containing the commented SSL directives to httpd.conf. For example:
copy httpd.conf.sample httpd.conf
4. Open the <ihs_home>\conf\httpd.conf file with a text editor. 5. Search for the following lines, uncomment the # symbol, and modify the settings as described: Verify the ServerName value, it should include your fully qualified hostname (for example, wpwin1.itso.ral.ibm.com):
ServerName <fully_qualified_hostname>
248
Uncomment the IBM SSL module for the given SSL encryption level (56 or 128 bit). For example:
LoadModule ibm_ssl_module/IBMModuleSSL128.dll
Note: In this example, 56 or 128 is the appropriate encryption level for your locale. For example, 128 is for 128-bit encryption in the US and Canada. Uncomment the following line to listen on port 443 for HTTPS:
Listen 443
Uncomment and update the VirtualHost with your hostname as follows:

<VirtualHost hostname.domain.com:443>
Note: Substitute your fully qualified host name in this line (for example, <VirtualHost wpwin1.itso.ral.ibm.com:443>). Uncomment:
SSLEnable
Uncomment:
</VirtualHost>
Uncomment and update the following:

Keyfile "<ihs_home>/ssl/keyfile.kdb"
Note: The keyfile path has been modified to include ssl instead of keys. For example:
Keyfile "c:\IBMHttpServer/ssl/keyfile.kdb"
Uncomment:
SSLV2Timeout 100 SSLV3Timeout 1000
6. Save the changes to the httpd.conf file.
Copy WebSphere plug-in entries

During the installation of the IBM HTTP Server and WebSphere plug-in, the httpd.conf was updated with the plug-in entries. Now that we have copied the httpd.conf.sample in the previous section to enable the SSL directives, we now also need to add the WebSphere plug-in entries to the httpd.conf. 1. Change to the directory of the IBM HTTP Server <ihs_home>\conf directory.
249
2. Modify the httpd.conf, and add the following for the WebSphere plug-in at the end of the file:
LoadModule ibm_app_server_http_module "c:\WebSphere\AppServer/bin/mod_ibm_app_server_http.dll" WebSpherePluginConfig "c:\WebSphere\AppServer/config/cells/plugin-cfg.xml"
Tip: The above text is in two separate lines. Within the httpd.conf, the lines are not wrapped. If you backed up the httpd.conf.org, you can cut and paste the plug-in entries to the SSL enabled httpd.conf.
Create a key store

To create the key store database used to store certificates, do the following steps: 1. Set the JAVA_HOME via the Windows environment for the Key Management Utility provided with the IBM HTTP Server, do the following steps: a. Right-click My Computer. b. Click the Advanced tab. c. Click Environment Variables. d. Click New under System variable.s e. Enter the following information and then click OK: Variable Name: JAVA_HOME Variable Value: c:\WebSphere\AppServer\java\jre
f. Click OK. 2. From Windows, click Start Programs IBM HTTP Server 1.3.28 Start Key Management Utility. 3. From the menu bar, click Key Database File New. 4. In the New window, enter the following information and then click OK: Key Database Type: CMS key database file File name: keyfile.kdb Location: <ihs_home>\ssl (for example, c:\IBMHttpServer\ssl) Note: This path must match the keyfile path in the httpd.conf.
250
5. In the Password Prompt window, enter this information and then click OK: Password: <your_password> (to protect the key store file). Check Set expiration time? and enter the number of days before the password will expire. If no expiration is required, do not check. Note: Although not required in a development environment, it is recommended that all key stores used in production environments set an expiration period. Check Stash the password to a file. Note: The IBM HTTP Server accesses the password-protected key store. 6. When the information window appears with the following message, click OK:
The password has been encrypted and saved in the file: c:\IBMHttpServer\ssl\keyfile.sth
Create a self-signed certificate

For development and testing purposes, we will create a new self-signed certificate as described in the following steps: 1. From the Key Management Utility menu bar, select Create New Self-Signed Certificate. If you closed the Key Management Utility, you will first need to open the key store first. 2. Fill in the information on the form and click OK. For example, we entered the following values: Key Label: wpwin1_http_ssl_key Common Name: <fully_qualified_hostname> Organization: <your_organization_name> (for example, IBM) Note: In our example, we entered upper case IBM for the organization name. It is important that you keep the case the same for the certificate and the Tivoli Access Manager WebSEAL junction found later in the procedure. For the production IBM HTTP Server, you should create a new certificate request (do not use a self-signed certificate). 3. When done, close the Key Management Utility.
251
Verify IBM HTTP Server

After the IBM HTTP Server configuration, we recommend that you complete the following verification tests: Start IBM HTTP Server Verify the IBM HTTP Server Back up the httpd.conf
Start IBM HTTP Server

The IBM HTTP Server service can be started by one of the following methods: IBM HTTP Server 1.3.28 Windows service or From the command line or batch file containing the following:
net start IBM HTTP Server 1.3.28
Verify the IBM HTTP Server

To verify IBM HTTP Server is working properly, enter the following URLs in a Web browser after the IBM HTTP Server has been started: Verify HTTP:
http://<hostname>
Verify HTTPS:
https://<hostname>
Back up the httpd.conf

After you have verified that the IBM HTTP Server is working properly with SSL enabled, we recommend that you make a backup of the <ihs_home>\conf\httpd.conf file to httpd.conf.was.ssl.
Configure WebSphere Application Server host alias for SSL

To create WebSphere Application Server host alias for SSL for the default host, do the following steps: 1. Start the WebSphere Application Server - server1 application server. 2. Login to the WebSphere Administrative Console. 3. Select Environment Virtual Hosts. 4. Click default_host. 5. Click Host Aliases. 6. Click New. 7. Enter * in the Host Name field, enter 443 in the Port field, and then click OK.
252
8. Click Save. 9. Click Save under the Save to Master Configuration window. 10.Under Environment, click Update Web Server Plugin. 11.Click OK. 12.You should see a message, Web server plug-in configuration updated successfully. Click OK. 13.Logout of the WebSphere Administrative Console. 14.Restart the IBM HTTP Server Windows service to read the newly generated WebSphere plugin-cfg.xml file.
Verify WebSphere Application Server

Now that we have added the WebSphere Application Server plug-in for the IBM HTTP Server, we recommend that you test that the plug-in is working properly. 1. Start the server1 application server. 2. Start the IBM HTTP Server. 3. Enter the following URLs (http, https) to access the Snoop application via the IBM HTTP Server with plug-in, which will redirect to WebSphere Application Server.
http://wpwin1.itso.ral.ibm.com/snoop https://wpwin1.itso.ral.ibm.com/snoop
5.2.2 Configure WebSphere Portal for the external IBM HTTP Server
This section describes how to configure IBM WebSphere Portal V5.1 to use the external IBM HTTP Server V1.3.28 in place of the WebSphere Application Server internal HTTP service. Note: This section does not apply to runtime topologies such as the development WebSphere Test Environment or a runtime environment that does not include an external Web server. 1. Ensure that the IBM HTTP Server V1.3.28 Windows service is started. 2. Ensure that the server1 application server is started. 3. Stop the WebSphere_Portal application server. 4. Navigate to the <wp_home>\config directory. 5. Back up the WebSphere Portal configuration properties found in the wpconfig.properties file by entering the following command:
wpsconfig backup-main-cfg-file
253
6. Change the wpconfig.properties values as seen in Table 5-7. Note: For a detailed description of each of the keywords, refer to the WebSphere Portal InfoCenter found at:
Table 5-7 ITSO example wpconfig.properties values for external Web server Section in wpconfig.properties file WebSphere Application Server Keyword WpsHostName WpsHostPort ITSO example value wpwin1.itso.ral.ibm.com 80
7. Save the updated wpconfig.properties file. 8. Enter the following command to configure WebSphere Portal Server for the external Web server based on the settings of the updated wpconfig.properties file:
wpsconfig httpserver-config
9. Restart the IBM HTTP Server. 10.Restart the WebSphere Portal Server for the changes to take effect. a. Open a command prompt change to the WebSphere Application Server bin directory:
cd \WebSphere\AppServer\bin
b. Confirm that the WebSphere Portal Server is stopped:

serverstatus WebSphere_Portal
If the server is started, enter the following command to stop:

stopServer WebSphere_Portal
c. Start the WebSphere_Portal application server.

startServer WebSphere_Portal
11.Verify that WebSphere Portal works properly with the external Web server. You should be able to browse your WebSphere Portal Server using the external Web server hostname:
http://wpwin1.itso.ral.ibm.com/wps/portal
254
Note: Prior to adding the external Web server, you needed to include the port number 9081 for the internal HTTP transport the WebSphere Portal Server was using in the URL. For example,
http://wpwin1.itso.ral.ibm.com:9081/wps/portal
Now that we have configured the external Web server, we do not need to specify the port (default port 80) in the URL:
5.3 Configure WebSphere Portal with LDAP

This section describes how to configure WebSphere Portal with the Tivoli Directory Server (LDAP). We will first connect WebSphere Portal to the previously installed Tivoli Directory Server. In addition, we will create users and groups for the ITSO environment. The section is organized into the following tasks: Create a suffix Create LDIF file containing users and groups Import the LDIF file (wp-itso.ldif) to create users and groups Enable LDAP security for WebSphere Portal Verify the LDAP configuration
5.3.1 Create a suffix

To create a suffix using the Tivoli Directory Server - Configuration Tool, do the following on the Directory Integrator node, where the Tivoli Directory Server is installed: 1. Stop the Tivoli Directory Server V5.2 Windows service. 2. Start the Tivoli Directory Server - Configuration Tool by clicking Start Programs IBM Tivoli Directory Server V5.2 Directory Configuration. 3. Select Manage suffixes under choose a task. Note: If the suffix dc=com exists, it must be removed before adding the dc=itso,dc=ibm,dc=com suffix in the next step. 4. On the suffix page, we entered the following for the ITSO example and then clicked Add:
255
Suffix DN: dc=itso,dc=ibm,dc=com 5. Click OK.
5.3.2 Create LDIF file containing users and groups

Users and groups can be created for the Tivoli Directory Server from the Web Administration Tool or by importing an LDIF file containing users and groups. For the ITSO working example, we created the wp-itso.ldif based on the PortalUsers.ldif file found on the WebSphere Portal Setup CD. We have included the wp-itso.ldif file in the ITSO sample code c:\6692code\config\wpwin1 directory (see Example 5-2). We changed the DN. We recommend that you change the userpassword attribute for users wpsadmin and wpsbind to a unique password.
Example 5-2 ITSO example WebSphere Portal LDIF file (wp-itso.ldif) version: 1 # ITSO example: wp-itso.ldif file dn: dc=itso,dc=ibm,dc=com objectclass: domain objectclass: top # Add lines according to this scheme that correspond to your suffix dc: itso,dc=ibm,dc=com dc: itso,dc=ibm dc: itso dn: cn=users,dc=itso,dc=ibm,dc=com objectclass: container objectclass: top cn: users dn: cn=groups,dc=itso,dc=ibm,dc=com objectclass: top objectclass: container cn: groups dn: uid=admin,cn=users,dc=itso,dc=ibm,dc=com objectclass: organizationalPerson objectclass: person objectclass: top objectclass: inetOrgPerson uid: admin userpassword: password sn: admin givenName: wps
256
cn: wps admin dn: uid=wpsbind,cn=users,dc=itso,dc=ibm,dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson uid: wpsbind userpassword: wpsbind sn: bind givenName: wps cn: wps bind dn: cn=wpsadmins,cn=groups,dc=itso,dc=ibm,dc=com objectclass: groupOfUniqueNames objectclass: top uniquemember: uid=admin,cn=users,dc=itso,dc=ibm,dc=com cn: wpsadmins
Note: If content management functions are configured, it is recommended to also create the following groups in the LDAP: wpsContentAdministrators wpsDocReviewer For details, refer to the IBM WebSphere Portal V5.1 InfoCenter.
5.3.3 Import the LDIF file (wp-itso.ldif) to create users and groups
To import the ITSO provided wp-itso.ldif file to create users and groups to the Tivoli Directory Server, do the following tasks on the node where Tivoli Directory Server is installed: 1. Stop the IBM Tivoli Directory Server V5.2 Windows service. 2. Copy the ITSO provided c:\6692code\config\wpwin1\wp-itso.ldif file to a temporary directory where Tivoli Directory Server is installed (for example, c:\temp). 3. Modify the value of the value of the userpassword keyword in the wp-itso.ldif file for your environment. 4. Start the Tivoli Directory Server Configuration Tool by clicking Start Programs IBM Tivoli Directory Server V5.2 Directory Configuration. 5. Select Import LDIF data.
257
6. When the Import LDIF Data page appears, we entered the following information and then clicked Import (bottom of page): Path and LDIF file name: c:\temp\wp-itso.ldif Select Standard import After the import has finished successfully, a message will be displayed reporting how many entries have been imported into the directory server. 7. When the import is complete, click Close. Close the Configuration Tool. 8. Restart the IBM Tivoli Directory Server V5.2 Windows service. 9. Verify the LDAP entries where created properly by performing an LDAP search. For example, we entered the following from a command window on the Directory Server node:
ldapsearch -h <ldap_server_hostname> -b dc=itso,dc=ibm,dc=com -D uid=wpsbind,cn=users,dc=itso,dc=ibm,dc=com -w <password> -s sub uid=admin
Where <ldap_server_hostname> is the hostname of the system Tivoli Directory Server is installed, and <password> is your password.
5.3.4 Enable LDAP security for WebSphere Portal

This section describes how to enable LDAP security for WebSphere Portal.
Configure WebSphere Portal for read-only LDAP access

For the ITSO example runtime environment, we have chosen to prevent WebSphere Portal from writing to the LDAP directory. We will only allow Tivoli Access Manager to write to the LDAP directory to ensure consistency and increase security. However, the default configuration for WebSphere Portal is not set up for read-only LDAP access. Therefore, we must configure WebSphere Portal for read-only LDAP access. Note: Within the ITSO development environment, we did not complete this section. To configure WebSphere Portal for read-only LDAP access, do the following steps: 1. Navigate to the c:/WebSphere/PortalServer/config/templates/wmm directory on the Portal Server node. 2. Back up the following files: wmm_LDAP.xml.<LDAPType>.<number>.wmm (for example, wmm_LDAP.xml.IBM_DIRECTORY_SERVER.1.wmm)
258
wmmLDAPAttributes_<LDAPType>.xml (for example, wmmLDAPAttributes_IBM_DIRECTORY_SERVER.xml) Note: Explanation of naming constructs for wmm xml files: <LDAPType> is the type of LDAP server that is being used, such as IBM_DIRECTORY_SERVER. <number> specifies whether a lookaside database is implemented. Use 1 if a lookaside database is not defined, or 3 if the lookaside database is defined. 3. Modify the attributes in the wmm_LDAP.xml.IBM_DIRECTORY_SERVER.1.wmm file. Search for the <ldapRepository tag section of the file, and modify the values as seen in Example 5-7. You will need to add the ingnoreReadOnlyUpdate=true entry.
Example 5-3 ITSO example wmm_LDAP.xml.IBM_DIRECTORY_SERVER.1.wmm (snippet) <ldapRepository name="wmmLDAP"  ..... wmmGenerateExtId="false" ignoreReadOnlyUpdate="true" supportGetPersonByAccountName="true" profileRepositoryForGroups="LDAP1" supportTransactions="false" adminId="@LDAPAdminUIdXml@" adminPassword="@EncryptedLDAPAdminPwd@" ldapHost="@LDAPHostName@" ldapPort="@LDAPPort@" ldapTimeOut="6000" ldapAuthentication="SIMPLE" ldapType="0" groupCacheRefreshInterval="-1"> </ldapRepository>
4. Save the file. 5. Modify the attributes in the wmmLDAPAttributes_IBM_DIRECTORY_SERVER.xml file. Search for wmmAttributeName=extId and modify the pluginAttributeName attribute as shown in Example 5-4. 6. Set the readOnly attribute to true in every attributeMap tag as shown in Example 5-4. If an attributeMap tag does not contain a readOnly attribute, you will need to add it.
259
Example 5-4 ITSO wmmLDAPAttributes_IBM_DIRECTORY_SERVER.xml (snippet) <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE repositoryAttributes SYSTEM "wmmAttributesMap.dtd"> <repositoryAttributes repositoryName="wmmLDAP">  <attributeMap wmmAttributeName="extId"  pluginAttributeName="ibm-entryUuid" dataType="String" multiValued="false" readOnly="true"/>  <attributeMap wmmAttributeName="groupMember" pluginAttributeName="@LDAPGroupMember@" applicableMemberTypes="Group" dataType="String" valueLength="1024" multiValued="true" readOnly="true"  defaultValue="uid=dummy" />  </repositoryAttributes>
7. Save the file.
Configure WebSphere Portal for security with LDAP

On the Portal Server node, there are pre-configured templates that can be customized to configure WebSphere Portal for LDAP. 1. Stop the WebSphere_Portal application server. 2. Ensure that the server1 application server is started. 3. Open a command prompt and navigate to the <wp_home>\config directory. Note: Depending on the environment, the <wp_home> path will be different: Runtime environment:
C:\WebSphere\PortalServer\config
Development environment:
C:\Program Files\Portal51UTE\PortalServer\config
260
4. Back up the WebSphere Portal configuration properties found in the wpconfig.properties file by entering the following command:
wpsconfig backup-main-cfg-file
5. Change the wpconfig.properties values as seen in Table 5-8. Tip: The helper configuration files, found in the ../config/helpers directory, can be used to automate the update of the wpconfig.properties file on multiple systems. We used the security_ibm_dir_server.properties helper file to update the wpconfig.properties file. The helper files include comments that are self-documenting.
Table 5-8 ITSO example wpconfig.properties values for LDAP security Section in wpconfig.properties file WebSphere Application Server Properties Portal Configuration Properties Keyword WasUserid WasPassword PortalAdminId PortalAdminIdShort PortalAdminPwd PortalAdminGroupId PortalAdminGroupId Short ITSO example value uid=wpsbind,cn=users,dc=itso,dc=ibm,dc=com <password> uid=admin,cn=users,dc=itso,dc=ibm,dc=com admin <password> cn=wpsadmins,cn=groups,dc=itso,dc=ibm,dc=com wpsadmins Note: If content management functions are configured, there are additional Portal Configuration properties that will need to be defined. We did not configure them for our scenario. WebSphere Portal Security LTPA and SSO Configuration LTPAPassword LTPATimeout SSODomainName <password> 120 itso.ral.ibm.com
261
Section in wpconfig.properties file LDAP Properties Configuration
Keyword Lookaside LDAPHostName
ITSO example value false tdiwin1.itso.ral.ibm.com Note: In the development environment, the value is timdev1.itso.ral.ibm.com (shared Tivoli Directory Server).
LDAPPort LDAPAdminUId
389 uid=wpsbind,cn=users,dc=itso,dc=ibm,dc=com Note: The default is cn=root. In our example, we have configured for read-only in Configure WebSphere Portal for read-only LDAP access on page 258. Note: In the development environment we set the LDAPAdminUId to cn=root.
LDAPAdminPwd LDAPServerType LDAPBindID LDAPBindPassword WmmSystemId WmmSystemIdPass word
<password> IBM_DIRECTORY_SERVER uid=wpsbind,cn=users,dc=itso,dc=ibm,dc=com <password> uid=wpsbind,cn=users,dc=itso,dc=ibm,dc=com <password>
262
Section in wpconfig.properties file Advanced LDAP Configuration
Keyword LDAPSuffix LdapUserPrefix LDAPUserSuffix LdapGroupPrefix LDAPGroupSuffix LDAPUserObjectCla ss LDAPGroupObjectCl ass LDAPGroupMember LDAPUserFilter LDAPGroupFilter LDAPsslEnabled
ITSO example value dc=itso,dc=ibm,dc=com uid cn=users cn cn=groups inetOrgPerson groupOfUniqueNames uniqueMember (&(uid=%v)(objectclass=inetOrgPerson)) (&(cn=%v)(objectclass=groupOfUniqueNames)) false
6. Save the updated wpconfig.properties file. 7. Change to the <wp_home>\config directory and enter the following command:
WPSconfig.bat validate-ldap
If an error occurs, review the values in the wpconfig.properties (typographical errors are quite often the cause of an error on this step) and the settings in the LDAP server. Also, ensure that the LDAP server is actually running. 8. If the validation was successful enable security by issuing the following command:
WPSconfig.bat enable-security-ldap
If the task completes successfully, you will see the message BUILD SUCCESSFUL. 9. Change to the <was_home>\bin directory and enter the following commands:
stopServer server1 -user wpsbind -password <password>
Where wpsbind is the WebSphere Administrator user ID and <password> is the password for the user ID.
263
Note: Once WebSphere security is enabled, you will need to specify the user wpsbind and password as parameters for the stopServer command:
stopServer server1 -user wpsbind -password <password>
On a development system, you can add the userID and password values to the soap.client.props file to eliminate keystrokes. Modify the following coding in the c:\WebSphere\AppServer\properties\soap.client.props file:
com.ibm.SOAP.loginUserid=wpsbind com.ibm.SOAP.loginPassword=password
After making this modification, you will not need to supply the userID and password.
stopServer server1
10.Start the servers by entering the following:

startServer server1 startServer WebSphere_Portal
5.3.5 Verify the LDAP configuration

To verify the WebSphere Portal and LDAP configuration, do the following steps: 1. Verify that WebSphere security is working properly by starting the WebSphere Application Server Administration Console and log in as user ID wpsbind. WebSphere security in this case provides the authentication. If security was not working, you would not be able to log in with the wpsbind user ID.
http://wpwin1.itso.ral.ibm.com:9090/admin
2. Verify that WebSphere Portal works properly with the LDAP configuration and WebSphere security. a. If everything works properly, you should be able to browse your WebSphere Portal Server at (fully qualified hostname), which is now configured to use LDAP:
Important: Using localhost or just the hostname for accessing the portal might cause problems after configuring LDAP security. Always use the fully qualified hostname for browsing. b. From the WebSphere Portal Welcome page, click Log in at the top right corner (for example, we used the admin user ID and password).
264
5.4 Configure DB2 Content Manager with LDAP

This section describes how to configure IBM Content Manager with LDAP using the Tivoli Directory Server. In addition, we have included configuration tasks for enabling trusted logon between the portal and DB2 Content Manager for single sign-on. IBM Content Manager can be configured to use an LDAP directory for user authentication. DB2 Content Manager can be enabled for LDAP during the installation of DB2 Content Manager or after the installation as described in this section. DB2 Content Manager includes support for LDAP user authentication. In addition, Content Manager includes an LDAP utility used to import and synchronize users between Content Manager and LDAP. In our example, we will later show how Tivoli Identity Manager can be used with Tivoli Directory Integrator to provision users to DB2 Content Manager. Note: For more information on enabling single sign-on (SSO) for DB2 Content Manager, refer to Chapter 42, Using DB2 Content Manager after-installation programs and procedures, in the product guide, Planning and Installing Your Content Management System, IBM DB2 Content Manager V8.3 Enterprise Edition, GG27-1332-03. The high level steps to configure Content Manager for LDAP are as follows: 1. 2. 3. 4. 5. 6. 7. 8. 9. Back up the DB2 Content Manager databases Generate the cmbcmenv.properties file Copy the cmbcmenv.properties file Copy the icmxlslg.dll (user exit) Enable trusted logons for Library Server Create the ClientUserEditSSO privilege sets Test the configuration Configure LTPA for WebSphere Application Server Enable SSL for LDAP server communication
Note: For more information on configuring Content Manager for LDAP, refer to the following product guides: Planning and Installing Your Content Management System, IBM DB2 Content Manager V8.3 Enterprise Edition, GG27-1332-03 Revised Installation Steps for Windows, IBM DB2 Content Manager V8.2 for Multiplatforms System Administration Guide, IBM DB2 Content Manager V8.3 Enterprise Edition, SC27-1335-06
265
5.4.1 Back up the DB2 Content Manager databases

Prior to running the import of users and groups from LDAP into Content Manager, we recommend that you back up the Library Server (icmnlsdb) and Resource Manager (rmdb) databases at this stage. When you start developing the data model, you may want to restore the pristine databases for further testing from a known state. To back up the DB2 Content Manager databases, do the following tasks on the Content Management node: 1. Stop the applications that are connected to the DB2 database: Stop the ICM LS Monitor icmnlsdb Windows service for the Library Server database Stop the Resource Manager icmrm application server:
c:\WebSphere\AppServer\bin\stopServer icmrm
2. Disconnect all applications connected to the database:

db2 force applications all db2 terminate
3. Create a database backup directory (for example, c:\ibm\dbbackup). 4. Open a DB2 command window. 5. Back up the databases (icmnlsdb, rmdb), by entering command:
db2 backup db icmnlsdb to c:\ibm\dbbackup db2 backup db rmdb to c:\ibm\dbbackup
Note: The backup path must be an absolute path and may not include spaces.
5.4.2 Generate the cmbcmenv.properties file

The cmbcmenv.properties file contains configuration settings shared by Content Manager and DB2 Information Integrator for Content. This section describes how to generate a cmbcmenv.properties file with LDAP for Content Manager enabled: 1. Ensure that the ICM LS Monitor (ICMNLSDB) Windows service is started. 2. Ensure that the Tivoli Directory Server V5.2 Windows service is started. 3. Start the System Administration Client by clicking Start Programs IBM DB2 Content Manager Enterprise Edition System administration client.
266
4. When prompted to log on, enter the following information and then click OK: Server Type: select Content Manager (default) Server: select ICMNLSDB (default) User ID: ICMADMIN Password: <password>
5. From the menu bar, click Tools LDAP Configuration. 6. Click the LDAP tab. 7. From the LDAP tab, check the Enable LDAP User Import and Authentication checkbox. 8. Click the Server tab. 9. From the Server tab, we entered the following information (see Figure 5-7) and then clicked OK. Server type: select LDAP. LDAP server hostname: ldap://tdiwin1.itso.ral.ibm.com The ldap:// will be inserted into the LDAP server hostname value automatically. Base DN: click Lookup from Server and select DC=ITSO,DC=IBM,DC=COM User attribute: uid Note: The default value is cn. We changed this to uid since WebSphere Portal when configured for LDAP uses the uid for user name. The Content Manager LDAP User Import Scheduler will use the value of this user attribute to create the user in Content Manager. User name: cn=root Password: <password>
267
Figure 5-7 Content Manager LDAP configuration
You should see a message like the following example:

LDAP - Configuration update successful Config file : C:\IBM\db2cmv8\cmgmt\cmbcmenv.properties
10.Click OK and close the System Administration Client.
268
5.4.3 Copy the cmbcmenv.properties file

The cmbcmenv.properties file is used by the Content Manager System Administration Client, Library Server and Resource Manager. When Content Manager is enabled for LDAP, the cmbcmenv.properties file is generated to include the LDAP configuration settings. This LDAP aware cmbcmenv.properties file needs to be available for each of the Content Manager components. If all components are installed on the same node, the following procedure is not needed. To copy the cmbcmenv.properties file to the directory where Resource Manager is deployed to WebSphere Application Server, do the following steps: 1. Stop the icmrm application server.
c:\WebSphere\AppServer\bin\stopServer icmrm
2. Copy the generated cmbcmenv.properties file to the node where the Resource Manager is installed. For example: From: C:\IBM\db2cmv8\cmgmt To: c:\WebSphere\AppServer\installedApps\cmwin1\icmrm.ear\icmrm.war\WEBINF\classes\com\ibm\mm\icmrm Where cmwin1 in our example is the node name. 3. Modify the cmbcmenv.properties file in the directory listed above to change all occurrences of the encrypted passwords to clear text passwords. Note: The first time you start the icmrm application server, the clear text will be saved as encrypted passwords in the cmbcmenv.properties file. 4. Start the icmrm application server.
c:\WebSphere\AppServer\bin\startServer icmrm
Important: The change password request in the LDAP server is not supported. You must use the LDAP servers administrative tool (for example, the Tivoli Directory Server Web Administration Tool) to change the password yourself.
269
5.4.4 Copy the icmxlslg.dll (user exit)

The Content Manager icmxlslg.dll is used for user exits needed for the LDAP configuration. 1. Open a DB2 command window. 2. Determine location the icmxlslg.dll should be copied to, for your environment, by entering the following command:
db2 connect to icmnlsdb user icmadmin using <icmadmin_password> db2 select pathicmdll from icmstsyscontrol
For our example, the following value was returned from the select statement:
C:\IBM\db2cmv8\cmgmt\ls
3. Record the location where the DB2 Content Manager icmxlslg.dll should be copied to. We will refer to this value as <PATHICMDLL>. You will need to append the database name to the <PATHICMDLL>. In our example, this will be C:\IBM\db2cmv8\cmgmt\ls\icmnlsdb. 4. Copy the icmxlslg.dll file as follows: From:
C:\IBM\db2cmv8\ldap
To:
C:\IBM\db2cmv8\cmgmt\ls\icmnlsdb
5.4.5 Enable trusted logons for Library Server

As part of the single sign-on configuration between the WebSphere Portal and DB2 Content Manager, this section describes how to enable the DB2 Content Manager Library Server for a trusted logon (receive LtpaToken). 1. Ensure that the ICM LS Monitor (ICMNLSDB) Windows service is started. 2. Ensure that the Tivoli Directory Server V5.2 Windows service is started. 3. Start the System Administration Client by clicking Start Programs IBM DB2 Content Manager Enterprise Edition System administration client. 4. When prompted to log on, enter the following information and then click OK: Server Type: select Content Manager (default) Server: select ICMNLSDB (default) User ID: ICMADMIN Password: <password>
5. From the menu bar click Library Server Parameters Configurations.
270
6. Double-click Library Server Configurations. 7. When the Library Server Configuration dialog appears, do the following steps: a. From the Definitions tab, select Allow logon without warning from the Max user action drop-down list. b. Check the Allow trusted logon checkbox. c. Click OK to save the changes. 8. When you return to the System Administration Client main window, select Tools Manage Database Connection ID Change Database Shared Connection ID. 9. When the Change Database Shared Connection ID dialog appears, enter the following information and then click OK: User ID: icmconct Password: <icmconct_password> Confirm password: <icmconct_password> Uncheck Password is required for all users 10.You will see a password changed successfully dialog appear as seen in Figure 5-8; click OK.
Figure 5-8 Enable trusted logons for Library Server
Note: When we installed IBM DB2 Content Manager V8.3, Enterprise Edition, the icmconct user was created in Windows as part of the installation.
271
5.4.6 Create the ClientUserEditSSO privilege sets

The default privilege set for DB2 Content Manager is ClientUserReadOnly. We need to assign users of the DB2 Content Manager application a higher privilege set for the access permissions to work properly for the ITSO working example application. The ClientUserEdit system defined privilege set contains the vast majority of the privileges needed for the ITSO working example portal document management application. In addition, we need to add additional privileges (AllowConnectToLogon, AllowTrustedLogon) since we are passing a token from the portlet application to the DB2 Content Manager for a trusted logon for the purposes of single sign-on. This section describes how to create the ClientUserEditSSO privilege set. 1. Ensure that the ICM LS Monitor (ICMNLSDB) Windows service is started. 2. Ensure that the Tivoli Directory Server V5.2 Windows service is started. 3. Start the System Administration Client by clicking Start Programs IBM DB2 Content Manager Enterprise Edition System administration client. 4. When prompted to log on, enter the following information and then click OK: Server Type: select Content Manager (default) Server: select ICMNLSDB (default) User ID: ICMADMIN Password: <password>
5. From the menu bar click Authorization Privilege Sets. 6. We need to add privileges to the following privilege sets for SSO: ClientUserEdit ClientUserAllPrivs 7. Select the ClientUserEdit privilege set. 8. Right-click Copy Advanced. 9. When the Copy Privilege Set window appears, do the following tasks and then click OK: Name: ClientUserEditSSO Note: Enter the original privilege set name with SSO appended. Privileges: Check AllowTrustedLogon. Note: In total, 37 privileges should be defined for the ClientUserEditSSO privilege set. The privilege added is needed for single sign-on (SSO).
272
10.Repeat the process for the ClientUserAllPrivs (ClientUserAllPrivsSSO) privilege set. Note: There are a couple methods that can be used to create users in LDAP as well as DB2 Content Manager (needed for access control to the resources). DB2 Content Manager LDAP User Import Utility. Once this utility is configured, users created in the LDAP directory will be created in DB2 Content Manager. For details on this method, refer to the following publications: Document Management, Using WebSphere Portal V5.0.2 and DB2 Content Manager V8.2, SG24-6349 (IBM Redbook) Planning and Installing Your Content Management System, IBM DB2 Content Manager V8.3 Enterprise Edition, GG27-1332-03 Create the user in the LDAP directory, and import the user into DB2 Content Manager (required for access control to resources) from the System Administration Console. We will use this scenario for test purposes, until we have the full runtime environment installed and configured, at which time we will use Tivoli Identity Manager (next option). User provisioning using Tivoli Identity Manager and Tivoli Directory Integrator. This redbook addresses this scenario. Users will be created from the provisioning portlets in Tivoli Identity Manager. Also, Tivoli Identity Manager and Tivoli Directory Integrator will be used to create users in various systems, including DB2 Content Manager.
5.4.7 Test the configuration

To import LDAP users in DB2 Content Manager from the System Administration Client, perform the following steps: 1. Ensure that the ICM LS Monitor (ICMNLSDB) Windows service is started. 2. Ensure that the Tivoli Directory Server V5.2 Windows service is started. 3. Start the System Administration Client by clicking Start Programs IBM DB2 Content Manager Enterprise Edition System administration client.
273
4. When prompted to log on, enter the following information and then click OK: Server Type: select Content Manager (default) Server: select ICMNLSDB (default) User ID: ICMADMIN Password: <password>
5. In the navigation pane, expand Authentication Users. 6. Right-click Users and select New. 7. Click LDAP on the Define Users page to import a user. 8. Enter the user ID (for example, admin) into the Find users field, and then click Find (see Figure 5-9).
Figure 5-9 System Administration Client - LDAP button
274
9. The user and its description are displayed. Select the row and click OK. 10.Set Maximum privilege set to the privileges matching the user IDs described in 5.4.6, Create the ClientUserEditSSO privilege sets on page 272. For example, select ClientUserAllPrivsSSO from the Maximum privilege set drop-down list. 11.Click the Set Defaults tab. 12.Select SuperUserACL for the Default item access control list drop-down list (required field). 13.Click OK. 14.Verify you can logon to the DB2 Content Manager Client for Windows with the newly added user (for example, admin).
5.4.8 Configure LTPA for WebSphere Application Server

The WebSphere Application Server environment allows applications to run in a trusted environment by making credentials available for authentication. LTPA requires a central shared user repository. For the ITSO identity and access management system, the credentials will originate from the Tivoli Access Manager WebSEAL and be passed from the portal application to DB2 Content Manager (LtpaToken). To configure LTPA for the WebSphere Application Server on the Portal Server node, do the following steps: 1. Ensure that the server1 application server is started. 2. Launch the WebSphere Administrative Console and logon as admin. 3. Select Security Authentication Mechanisms LTPA. 4. Click Single Sign-on (SSO) at the bottom of the LTPA window. 5. Select the Enabled checkbox, uncheck Requires SSL checkbox, and then click OK. 6. In the navigation pane, select Security Global Security. 7. In the Active Authentication Mechanism field, select LTPA (Light weight Third Party Authentication), and then click OK. 8. Click Save to open the Save to Master Configuration window. 9. Click Save to save the configuration. 10.Restart the icmrm application server. 11.Stop the server1 application server to conserve resources.
275
5.4.9 Enable SSL for LDAP server communication

By default the communication between the DB2 Content Manager Library Server and Tivoli Directory Server (LDAP) will be in clear text. This section is optional, but highly recommended for a production environment to avoid transmitting passwords in clear text. We did not implement this step for the ITSO runtime environment. Note: We recommend that you get the environment working, and then perform security hardening steps such as enabling SSL between DB2 Content Manager and Tivoli Directory Server. For details, refer to refer to Chapter 42, Using DB2 Content Manager after-installation programs and procedures, in the product guide, Planning and Installing Your Content Management System, IBM DB2 Content Manager V8.3 Enterprise Edition, GG27-1332-03.
5.5 Enable mutual SSL between WebSEAL and Portal

The ITSO example architecture uses an external IBM HTTP Server for WebSphere Portal on the Portal Server node. This section describes how to configure mutual SSL between the WebSEAL on the Reverse Proxy node and the IBM HTTP Server on the Portal Server node. In our example, we have two fundamental requirements. First, we want to provide access for some pages to unauthenticated users. Second, we do not want to create two separate junctions for authenticated and unauthenticated users. For these reasons and limitations when creating a WebSEAL junction, we needed to enable mutual SSL for the type of junction needed. The section is organized into the following tasks: 1. 2. 3. 4. 5. 6. 7. IBM HTTP Server SSL configuration. Configure WebSphere Portal for SSL. Export IBM HTTP Server CA certificate. Import IBM HTTP Server certificate into WebSEAL keystore. Export WebSEAL certificate. Import WebSEAL certificate into IBM HTTP Server keystore. Enable mutual SSL for IBM HTTP Server.
276
5.5.1 IBM HTTP Server SSL configuration

In our environment, we have already configured the IBM HTTP Server for SSL in 5.2.1, IBM HTTP Server configuration on page 248.
5.5.2 Configure WebSphere Portal for SSL

This section describes how to enable SSL for WebSphere Portal on the Portal Server node. In this example we will configure the WebSphere Application Server, where WebSphere Portal is installed, to be SSL enabled and update the WebSphere Portal configuration for SSL.
Enable SSL for the WebSphere Application Server

Configure the WebSphere Application Server plug-in for the Web server to forward WebSphere Portal traffic that is received over SSL to WebSphere Application Server (which will then forward the traffic to WebSphere Portal). Update the virtual host list for WebSphere Application Server to include the correct host name and port number, and regenerate the plug-in configuration. In our environment, we completed this configuration task in Configure WebSphere Application Server host alias for SSL on page 252. Note: In our example, the IBM HTTP Server and plugin-cfg.xml are installed on the same node as the WebSphere Application Server. The plugin-cfg.xml is reloaded with the updated settings based on the RefreshInterval set in the plugin-cfg.xml. By default, it is set to refresh after 60 seconds. If you want this to take effect immediately, restart the IBM HTTP Server.
Enable SSL in the WebSphere Portal configuration

In our example, since we are using Tivoli Access Manager WebSEAL for authentication, we will disable WebSphere Portal login pages in 5.6.11, Configure Portal login/logout for use with WebSEAL on page 311. The enablement of SSL is a prerequisite step. To enable SSL in the WebSphere Portal configuration, do the following steps: 1. Navigate to the following directory:
c:\WebSphere\AppServer\installedApps\wpwin1\wps.ear\wps.war\WEB-INF
2. Back up web.xml to web.xml.org. 3. Modify the web.xml as seen in Example 5-5. Search on SecurityConstraint_1 to find the appropriate section to modify. Inside the SecurityConstraint_1 definition change the <transport-guarantee> setting from NONE to CONFIDENTIAL.
277
Note: The CONFIDENTIAL transport_guarantee will only allow https access to the /myportal/* URLs.
Example 5-5 ITSO modified web.xml for WebSphere Portal <security-constraint id="SecurityConstraint_1"> <web-resource-collection id="WebResourceCollection_1"> <web-resource-name></web-resource-name> <url-pattern>/myportal/*</url-pattern> <http-method>DELETE</http-method> <http-method>GET</http-method> <http-method>POST</http-method> <http-method>PUT</http-method> </web-resource-collection> <auth-constraint id="AuthConstraint_1"> <description></description> <role-name>All Role</role-name> </auth-constraint> <user-data-constraint id="UserDataConstraint_4"> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint>
4. Save and close the web.xml file. 5. Restart the WebSphere_Portal application server. 6. Restart the IBM HTTP Server.
Verify WebSphere Portal SSL configuration

Once the configuration is complete, we recommend that you verify that the WebSphere Portal Server is SSL enabled by entering the following URL in a Web browser (remember https):
https://wpwin1.itso.ral.ibm.com/wps/myportal
Log in with the admin user ID and password. Verify that the Welcome page is displayed.
5.5.3 Export IBM HTTP Server CA certificate

In our example, we used a self-signed certificate for the IBM HTTP Server. This section explains how to export the Certificate Authority (CA) certificate that will be imported into the WebSEAL keystore for the purpose of setting up SSL junctions.
278
Use the following procedure for exporting the certificate: 1. Start the IBM Key Management Utility on the Portal Server node by clicking Start Programs IBM HTTP Server 1.3.28 Start Key Management Utility. 2. From the menu bar select Key Database File Open. 3. Select CMS from the Key database type drop-down list, and then select c:\IBMHttpServer\ssl\keyfile.kdb and click Open. Note: The key database file, also known as a keystore or keyring, is defined in the <ihs_home>\conf\httpd.conf file. Search for Keyfile (for example, Keyfile "c:\IBMHttpServer/ssl/keyfile.kdb"). 4. When prompted enter the password for the keystore. 5. Under Personal Certificates, select the certificate you created in Create a self-signed certificate on page 251 (for example, wpwin1_http_ssl_key). 6. Click Extract Certificate. 7. When the Extract Certificate to a File window appears, we entered the following and then clicked OK: Data Type: Select Base64-encoded ASCII data (default). Certificate file name: wpwin1_http_cert.arm Location: c:\IBMHttpServer\ssl\ 8. Close the Key Management Utility.
5.5.4 Import IBM HTTP Server certificate into WebSEAL keystore

In our example, the JRE, GSKit and WebSEAL are installed on the Reverse Proxy node. By default, the JRE (java.security) does not include the IBM JCE and IBM CMS security providers. As part of our configuration of the GSKit iKeyman utility, we added the IBM JCE and IBM CMS security providers (see IBM GSKit Key Management utility configuration on page 181). This section describes how to import the IBM HTTP Server certificate into the WebSEAL keystore on the Reverse Proxy node. 1. Ensure that you have added the IBM CMS and JCE security provider to the java.security file. For details on updating the java.security file to add the CMS and JCE provider refer to IBM GSKit Key Management utility configuration on page 181.
279
2. Determine the WebSEAL keystore file name and location. a. Navigate to the c:\ibm\tam\PDWeb\etc directory on the Reverse Proxy node. b. Open the webseald-default.conf file in a text editor. c. Search webseal-cert-keyfile and record the value (for example, c:/ibm/tam/PDWeb/www-default/certs/pdsrv.kdb). 3. Copy the IBM HTTP Server certificate (for example, wpwin1_http_cert.arm) from the Portal Server node (c:\IBMHttpServer\ssl\) to the c:\ibm\tam\PDWeb\www-default\certs directory on the Reverse Proxy node. 4. Start the iKeyman utility on the Reverse Proxy node by entering the following commands from a Windows command window:
cd \ibm\gsk7\bin set JAVA_HOME=c:\ibm\Java131\jre gsk7ikm
5. From the menu bar select Key Database File Open. 6. When the Open window appears, do the following and then click OK: Key database type: Select CMS. Filename: pdsrv.kdb Location: c:\ibm\tam\PDWeb\www-default\certs 7. When prompted, enter the password for the keystore. By default the password is pdsrv. 8. The password can be changed by selecting Key Database File Change Password (check Stash password to a file). 9. From the Key database content drop-down list, select Signer Certificates. 10.Click Add. 11.When the Add CAs Certificate from a file window appears, we entered the following and then clicked OK: Data type: Select Base64-encoded ASCII data. Certificate file name: wpwin1_http_cert.arm Location: c:\ibm\tam\PDWeb\www-default\certs 12.When prompted for the label, we entered wpwin1_http_ssl_key and then clicked OK. For consistency, we used the same name as used to create the certificate on the Portal Server node. You should see the newly imported certificate listed (for example, wpwin1_http_ssl_key) among the Signer Certificates.
280
5.5.5 Export WebSEAL certificate

This section describes how to create a self-signed certificate for the WebSEAL and how to export the certificate. Although WebSEAL does provide a test certificate, we chose not to use this certificate for our example. This test certificate is included with the distribution of Tivoli Access Manager V5.1 available to all customers and is thus not secure. For this reason, we will create a new self-signed certificate.
Create WebSEAL self-signed certificate

To create a self-signed certificate for WebSEAL, do the following steps: 1. If you have closed the Key Management utility after the previous step, you will need to start the Key Management utility and open the key database file (pdsrv.kdb). 2. Select Personal Certificates from the Key database content drop-down list. 3. From the menu bar, select Create New Self Signed Certificate. 4. When the Create New Self Signed Certificate window appears, we entered the following and then clicked OK: Key Label: WebSEAL default key Note: In this case, default is the name of the WebSEAL instance. Common Name: wswin1.itso.ral.ibm.com Organization: IBM 5. When prompted, Do you want to set the key as the default key in the database, click No. In our example, the key is defined explicitly in the webseald-default.conf.
Export WebSEAL certificate

To export the WebSEAL certificate, do the following steps: 1. If you have closed the Key Management utility after the previous step, you will need to start the Key Management utility and open the key database file (pdsrv.kdb). 2. Under Personal Certificates, select the certificate you created in Create WebSEAL self-signed certificate on page 281 (for example, WebSEAL default key). 3. Click Extract Certificate. 4. When the Extract Certificate to a File window appears, we entered the following and then clicked OK: Data Type: Select Base64-encoded ASCII data (default). Certificate file name: webseal_default_cert.arm Location: c:\ibm\tam\PDWeb\www-default\certs 5. Close the iKeyman utility.
281
Modify webseald-default.conf to use new certificate

In our example, we chose to create a new self-signed certificate. In order for the WebSEAL to use this new certificate, we need to modify the webseald-default.conf to define the new key label: 1. Navigate to the c:\ibm\tam\PDWeb\etc directory. 2. Back up the webseald-default.conf to webseald-default.conf.org. 3. Open the webseald-default.conf file with a text editor. 4. Search for webseal-cert-keyfile-label. Modify the value as follows:
webseal-cert-keyfile-label = WebSEAL default key
5. Save and close the file. 6. Restart the WebSEAL instance (Access Manager WebSEAL-default Windows service).
5.5.6 Import WebSEAL certificate into IBM HTTP Server keystore

To import the WebSEAL certificate into the IBM HTTP Server keystore, do the following steps: 1. Copy the WebSEAL certificate (for example, webseal_default_cert.arm) from the Reverse Proxy node to the c:\IBMHttpServer\ssl directory on the Portal Server node. 2. Start the IBM Key Management Utility on the Portal Server node by clicking Start Programs IBM HTTP Server 1.3.28 Start Key Management Utility. 3. From the menu bar select Key Database File Open. 4. Select CMS from the Key Database Type drop-down list, and then select the c:\IBMHttpServer\ssl\keyfile.kdb and click Open. 5. When prompted enter the password for the keystore. 6. From the Key database content drop-down list, select Signer Certificates. 7. Click Add. 8. When the Add CAs Certificate from a file window appears, we entered the following information and then clicked OK: Data type: Select Base64-encoded ASCII data. Certificate file name: webseal_default_cert.arm Location: c:\IBMHttpServer\ssl
282
9. When prompted for the label, we entered WebSEAL default key and then clicked OK. For consistency, we entered the same name as used when we created the key. You should see the newly imported certificate listed (for example, WebSEAL default key) among the Signer Certificates. 10.Close the IBM Key Management Utility.
5.5.7 Enable mutual SSL for IBM HTTP Server

To enable mutual SSL for IBM HTTP Server on the Portal Server node, do the following steps: 1. Stop the IBM HTTP Server V1.3.28 Windows service. 2. Open the c:\IBMHTTPServer\conf\httpd.conf file with a text editor. 3. Search for the keyword SSLClientAuth inside the <VirtualHost entry. 4. Add the following entry after the commented SSLClientAuth entries:
SSLClientAuth required
5. Save the changes to the httpd.conf file. 6. Restart the IBM HTTP Server. Note: Once the SSLClientAuth required keyword and value are set, we will no longer be able to directly connect to the IBM HTTP Server via HTTPS. HTTPS connections to the IBM HTTP Server will only be permitted from WebSEAL. 7. Verify that you are not able to access the IBM HTTP Server directly via HTTPS by entering the following URL in a Web browser (see Figure 5-10):
https://wpwin1.itso.ral.ibm.com
283
Figure 5-10 Client Authentication message
8. You should see a message like the one in Figure 5-10. Click Cancel. If you are then prompted with a Security Alert, click No. Note: When we create a WebSEAL junction in 5.6.3, Create a WebSEAL junction on page 295, we will enable mutual SSL for the WebSEAL junction.
5.6 Configure Portal authentication with TAM using TAI

In the ITSO example, our runtime is currently configured for users to directly log in to the WebSphere Portal on the Portal Server node. After completing this section, the authentication for WebSphere Portal will be performed by a combination of the WebSEAL on the Reverse Proxy node, and the Tivoli Access Manager Policy Server on the Policy Server node. This section includes the following tasks: 1. 2. 3. 4. 5. 6. 7. 8. 9. Apply Tivoli Access Manager ACLs to new LDAP suffixes. Define additional MIME types for WebSphere Application Server. Create a WebSEAL junction. Enable forms authentication on WebSEAL. Configure WebSEAL to modify URLs to back-end systems. Configure additional WebSEAL parameters. Import WebSphere Portal users and groups into TAM. Define access controls for WebSphere Portal URIs. Configure the junction mapping table (JMT).
284
10.Configure SSO for WebSEAL and WebSphere via TAI. 11.Configure Portal login/logout for use with WebSEAL. Note: IBM WebSphere Portal V5.1 includes new tooling and capabilities for simplifying basic configuration of Tivoli Access Manager authentication, authorization, and Credential Vault. In our scenario, we did not use the WebSphere Portal V5.1 tooling to configure authentication. Our scenario includes many additional configuration tasks beyond the capabilities of the WebSphere Portal tooling. Our procedures were derived from the Tivoli Access Manager V5.1 product documentation noted in our procedures.
5.6.1 Apply Tivoli Access Manager ACLs to new LDAP suffixes

When Tivoli Access Manager V5.1 is configured, it attempts to apply appropriate access control in the form of Access Control Lists (ACLs) to every LDAP suffix that exists at the time in the LDAP server. In our example, we created the LDAP suffix dc=itso,dc=ibm,dc=com in 5.3.1, Create a suffix on page 255, after we configured Tivoli Access Manager. For this reason, we must manually apply Tivoli Access Manager ACLs to the suffix. Note: For more information on applying Tivoli Access Manager ACLs to a new LDAP suffix, refer to Appendix D, Managing user registries (see the section Applying IBM Tivoli Access Manager ACLs to new LDAP suffixes), in the product guide, Base Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1360.
285
Note: Apply TAM ACLs to new LDAP suffix via ldif file import. This note offers an alternative solution for applying Tivoli Access Manager ACLs to a new LDAP suffix using an ldif file import in the Tivoli Directory Server. The ITSO sample code includes c:\6692code\config\tdwin\tam-acls.ldif. If you choose to import ACLs via the ldif, you can skip the rest of this section. To apply Tivoli Access Manager ACLs to a new LDAP suffix, do the following steps: 1. Copy the c:\6692code\config\tdiwin\tam-acls.ldif file to the c:\temp directory. 2. Modify the tam-acls.ldif file for your suffix. 3. From command line, execute the following command.
ldapmodify -h tamwin1.itso.ral.ibm.com -D cn=root -w <password> -i c:\temp\tam-acls.ldif
To apply Tivoli Access Manager ACLs to a new LDAP suffix, do the following steps on the Directory node: 1. Ensure that the following IBM Tivoli Directory Server 5.2 Windows service is running. 2. Start server1 via the command prompt:
3. Start the Tivoli Directory Server Web Administration Tool in a Web browser at:
http://tdiwin1.itso.ral.ibm.com:9080/IDSWebApp/IDSjsp/Login.jsp
Where tdiwin1.itso.ral.ibm.com is the host name of the application server where the IBM Directory Server Web Administration Tool has been installed. 4. From the Web Administration Tool, do the following and then click Login: Select the newly created server (for example, tdiwin1.itso.ral.ibm.com) from the drop-down list on the Login page. Username: cn=root Password: <password> 5. From the Web Administration Tool, select Directory management Manage entries.
286
6. When the Manage entries page appears, select the suffix from the list (for example, dc=itso,dc=ibm,dc=com) by clicking it in the Select column, and then click Edit ACL. 7. To add the cn=SecurityGroup,secAuthority=Default ACL to the ITSO suffix dc=itso,dc=ibm,dc=com, do the following steps: a. When the Edit ACL page appears, click Non-filtered ACLs. b. When the Edit ACL Non-filtered ACLs page appears, do the following and then click Add: Check Propagate ACLs. DN (distinguished name): cn=SecurityGroup,secAuthority=Default Type: Select group.
c. When the Add access rights page appears, do the following and then click OK at the bottom of the page (see Figure 5-11): Add child: Select grant. Delete entry: Select grant. Select grant for all security classes (normal, sensitive, critical, system, restricted) and actions (read, write, search, compare). Note: You cannot grant write permission for the system security class (menu option is disabled).
287
Figure 5-11 Add ACL for DN cn=SecurityGroup,secAuthority=Default
8. To add the cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default ACL to the ITSO suffix dc=itso,dc=ibm,dc=com, do the following steps: a. When the Edit ACL page appears, click Non-filtered ACLs. b. When the Edit ACL Non-filtered ACLs page appears, do the following steps and then click Add:
288
Check Propagate ACLs. DN: cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default Type: select group.
c. When the Add access rights page appears, do the following and then click OK at the bottom of the page (see Figure 5-12): Add child: Leave blank. Delete entry: Leave blank. Set the normal and system Security classes to grant for the read, search and compare actions. Leave the Add child, Delete entry, and all other Security classes blank (see Figure 5-12).
Figure 5-12 Add ACL for cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default
289
9. To add the cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default ACL to the ITSO suffix dc=itso,dc=ibm,dc=com, do the following steps: a. When the Edit ACL page appears, click Non-filtered ACLs. b. When the Edit ACL Non-filtered ACLs page appears, do the following and then click Add: Check Propagate ACLs. DN: cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default Type: Select group.
c. When the Add access rights page appears, do the following and then click OK at the bottom of the page (see Figure 5-13 on page 291): Add child: Leave blank. Delete entry: Leave blank. Set the normal and system Security classes to grant for the read, search and compare actions. Leave the Add child, Delete entry, and all other Security classes blank (see Figure 5-13).
290
Figure 5-13 Add ACL for cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default
291
10.To add the cn=anybody ACL to the ITSO suffix dc=itso,dc=ibm,dc=com, do the following steps: a. When the Edit ACL page appears, click Non-filtered ACLs. b. When the Edit ACL Non-filtered ACLs page appears, do the following and then click Add: Check Propagate ACLs. DN: cn=anybody Type: Select group.
c. When the Add access rights page appears, do the following and then click OK at the bottom of page (see Figure 5-14): Add child: Leave blank. Delete entry: Leave blank. Set the normal, system and restricted Security classes to grant for the read, search and compare actions. Leave the Add child, Delete entry, and all other Security classes blank (see Figure 5-14).
292
Figure 5-14 Add ACL for cn=anybody
11.When you have completed adding the ACLs, click OK. 12.When the Manage entries page appears, click Close. The LDAP server does not need to be restarted for the changes to take effect. 13.If you are finished with the IBM Directory Server Web Administration Tool, click Logout.
293
5.6.2 Define additional MIME types for WebSphere Application Server

By default, WebSphere Application Server V5.1.1 is not configured with MIME types for Java Archive files and Microsoft ActiveX Control files. These MIME types are commonly used by back-end Web applications such as Lotus components included in IBM WebSphere Portal V5.1. When using Tivoli Access Manager WebSEAL, the MIME type must be defined in response headers in order for the response to be passed through the WebSEAL. Table 5-9 lists the MIME type definitions we will add in this section. If your portlet application uses other MIME types not found by default within WebSphere Application Server, follow the same procedure to add the MIME type definitions.
Table 5-9 Additional MIME types for WebSphere Portal Description Java Archive ActiveX Control MIME type application/java-archive application/x-cabinets-Win32-x86 Extensions jar cab
To add MIME type definitions to the WebSphere Application Server where WebSphere Portal is installed, do the following steps: 1. Ensure that the server1 application server is started on the Portal Server node. 2. Open the WebSphere Application Server Administrative Console: a. Enter the following URL:
https://wpwin1.itso.ral.ibm.com:9043/admin
b. Enter the WebSphere administrator user ID and password (for example, wpsbind). 3. Select Environment Virtual Hosts. 4. On the Virtual Hosts page, click default_host. 5. Add new MIME type. a. Click MIME Types under Additional Properties. b. Click New. c. On the New MIME Type page, enter the following information for the Java archive, as seen in Table 5-9, and then click OK: MIME type: application/java-archive Extensions: jar
6. Repeat the previous step to add a new type for ActiveX controls with the values listed in Table 5-9.
294
7. Click Save. 8. On the Save to Master Configuration page, click Save. 9. Click Logout.
5.6.3 Create a WebSEAL junction

To create the WebSEAL junctions for our configuration, we will use the Tivoli Access Manager pdadmin command line interface. You can use the pdadmin command line interface in one of the following three modes: Single command mode Interactive command mode Multiple command mode For the ITSO example, we chose to create an input file. In our example, we will use multiple command mode with a command file containing the commands to create the junction. Figure 5-15 depicts the ITSO sample /portal WebSEAL junction for WebSphere Portal.
/portal junction point Web Browser Client

HTTP Port 80
WebSEAL instance (default-webseald-wswin1)
Port 443 HTTPS
HTTP Server for WebSphere Portal
Figure 5-15 ITSO junction for WebSphere Portal
Create the wp-junction.pd command file

For our example, we created a command file named wp-junction.pd found in the c:\6692code\config\tamwin1 directory. To create the wp-junction.pd file containing the commands to create a junction for WebSphere Portal, do the following steps: 1. Ensure that the Access Manager Policy Server Windows service is started. 2. Start the pdadmin command line interface on the Reverse Proxy node, by selecting Start Programs IBM Tivoli Access Manager Administration Command Prompt. 3. Log in by entering login in the pdadmin prompt. When prompted, enter the user ID sec_master and <password>. 4. To get a list of servers, enter the following command:
server list
295
The command will output a list that contains the following name:
default-webseald-wswin1
Take note of the WebSEAL server name. 5. We created the wp-junction.pd file with the commands as seen in Example 5-6. The wp-junction.pd will be used to define an SSL junction for WebSphere Portal in the WebSEAL instance we configured previously. This will enable mutual SSL for the WebSEAL junction created. Note: For details on the parameters, refer to Appendix B, WebSEAL junction reference, in the product guide, WebSEAL Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1359. The syntax of this command is as follows:
server task <webseal_servername> create -t <junction_type> -h <backend_server_hostname> -p <backend_server_port> -j -w -c all -K <key_label> -D <CN> <junction_point>
Where the parameters are as follows (see Example 5-6): <webseal_servername> is the server name returned from server list command in the previous step (for example, default-webseald-wswin1). <junction_type> is either tcp for non-ssl or ssl. <backend_server_hostname>, in our example this is Portal Server node. <backend_server_port>, in our example this is Portal Server node port 443. -j enables junction cookies for handling server relative URLs. -w is used to support the Win32 file system. This option will only allow full paths to resources (not the short name). Also, it will make the resource validation case insensitive. -c all: There are two key options (-c all or -c iv-user) for WebSphere Portal integration. When only performing authentication, -c -iv-user is sufficient. When using performing authentication and authorization, then -c all must be used. -K <key_label> is the WebSEAL key label on the Reverse Proxy node. -D <CN> in our example is CN=wpwin1.itso.ral.ibm.com,O=IBM,C=US.
Example 5-6 ITSO wp-junction sample command file server task default-webseald-wswin1 create -t ssl -h wpwin1.itso.ral.ibm.com -p 443 -j -w -c all -K "WebSEAL default key" -D "CN=wpwin1.itso.ral.ibm.com,O=IBM,C=US" /portal
296
Note: For scenarios using the internal HTTP service built-in to WebSphere Application Server (development WebSphere Test Environment or no external Web Server), update the port to 9444 for SSL instead of port 443 in the wp-junction.pd (see Example 5-6 on page 296).
Create the WebSEAL junction from wp-junction.pd

To create the WebSEAL junction from wp-junction.pd, do the following steps: 1. Copy the wp-junction.pd command file to the c:\temp directory on the Reverse Proxy node. 2. Open a Windows command window (not pdadmin). 3. From the Windows command line, change to the directory of the wp-junction.pd and enter the following command:
pdadmin -a sec_master wp-junction.pd
4. When prompted for the password, enter the sec_master password. Note: When creating the junction, WebSEAL will attempt to connect to the back-end system (for example, WebSphere Portal). If the system is not available, you will see the following message:
DPWWA1222E A third-party server is not responding. Possible causes: the server is down, there is a hung application on the server, or network problems. This is not a problem with the WebSEAL server. DPWIV1054E Could not connect
The junction will still be created. 5. Verify that the junction was created properly. a. Start pdadmin and log in as sec_master. b. Enter the following command to verify the junction:
server task default-webseald-wswin1 list
You should see a list of junctions including the new junction created, for example:
/portal
c. You can further review the junction definition by entering the following command. This will list all settings for the /portal junction.
server task default-webseald-wswin1 show /portal
297
5.6.4 Enable forms authentication on WebSEAL

By default, the WebSEAL uses HTTP basic authentication for its authentication challenge to the user. With basic authentication, the logout does not happen until the user closes the Web browser. In addition, there are other security issues with basic authentication that make forms authentication preferable. To enable forms authentication, you will need to update the webseald-<webseal_instancename>.conf on the Reverse Proxy node as follows: 1. Navigate to the c:\ibm\tam\PDWeb\etc directory. 2. Back up the webseald-default.conf. 3. We modified the webseald-default.conf, as seen in Example 5-7.
Example 5-7 ITSO example forms authentication settings in webseaId-default.conf [ba] #-------------------------# BASIC AUTHENTICATION #-------------------------#Enable authentication using basic authentication mechanism #One of <http, https, both, none> ba-auth = none
[forms] #-------------------------#Forms #-------------------------#Enable authentication using forms #One of <http, https, both, none> forms-auth = https
4. Save the webseald-default.conf file. 5. Restart the Access Manager WebSEAL-default Windows service to enable these configuration changes. 6. To verify that the forms authentication is enabled, we will access the WebSEAL with Web browser:
https://<webseal_hostname>
You should now get the WebSEAL login form page in the browser instead of the WebSEAL basic authentication pop-up. 7. Log on to the WebSEAL with the sec_master user ID and password. You should see the WebSEAL splash screen.
298
Now that forms are enabled, users will be able to log out without needing to close the Web browser.
5.6.5 Configure WebSEAL to modify URLs to back-end systems

Web pages returned to the client from back-end applications are likely to contain URL links to resources located on those application servers (for example, WebSphere Application Server or WebSphere Portal). It is important that these links are constructed to direct any requests back to the correct locations of these resources. This section describes how to configure WebSEAL to modify URLs to back-end systems for the following: Enable WebSEAL URL filtering. Enable WebSEAL processing of URLs in the request.
Enable WebSEAL URL filtering

The Tivoli Access Manager WebSEAL URL filtering performs two functions: It adds the junction name to the path of the absolute and server-relative URLs that refer to resources located on the back-end servers. The absolute URL host/port is mapped to the respective junction on WebSEAL. When adding WebSEAL in front of a back-end application such as WebSphere Application Server or WebSphere Portal, the absolute URLs of the back-end application need to be mapped to WebSEAL. Note: For more detailed information of WebSEAL URL filtering, refer to Chapter 10, WebSEAL junctions, section Filtering URLs in responses, in the product guide, WebSEAL Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1359. If the back-end application (WebSphere Portal) generates an absolute URL as seen in Table 5-10, it will need to be mapped on WebSEAL since only the Reverse Proxy node is accessible to Web browser clients. In the filtered WebSEAL URL, the junction /portal was created in 5.6.3, Create a WebSEAL junction on page 295.
Table 5-10 WebSEAL URL filter example WebSphere Portal URL http://wpwin1.itso.ral.ibm.com/wps/portal Filtered WebSEAL URL http://wswin1.itso.ral.ibm.com/portal/wps/portal
299
To enable WebSEAL URL filtering, do the following steps: 1. Navigate to the c:\ibm\tam\PDWeb\etc directory. 2. Back up the webseald-default.conf. 3. We modified the webseald-default.conf, as seen in Figure 5-8, for the ITSO example. script-filter=yes enables WebSEAL URL filtering.
Example 5-8 ITSO example URL filtering settings in webseaId-default.conf [script-filtering] script-filter=yes
4. Save the webseald-default.conf file. 5. You will need to restart the Access Manager WebSEAL-default Windows service for the changes to take effect. We will make other changes to the webseald-default.conf file, so you may defer the restart at this time.
Enable WebSEAL processing of URLs in the request

When URLs are dynamically generated by client-side applications such as applets or embedded scripts in the HTML such as JavaScript or ActiveX, the URLs will need to be mapped. In this case WebSEAL does not have the ability to apply its standard filtering rules to the dynamically generated URLs. The WebSEAL provides two methods of addressing dynamically generated URLs from client-side applications: Junction cookies are specified with a -j option when creating the junction. Junction mapping: The junction mapping uses a static junction mapping table to map specific back-end resources to junction names. Note: For more detailed information on WebSEAL URL filtering, refer to Chapter 10, WebSEAL junctions, section Processing URLs in requests, in the product guide, WebSEAL Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1359. For the ITSO example, we chose to use the junction cookies option for the base configuration. When creating the junction in 5.6.3, Create a WebSEAL junction on page 295, we used the -j option for junction cookies of processing URLs in the request.
300
5.6.6 Configure additional WebSEAL parameters

This section describes additional parameters we modified in the webseaId-default.conf file for the ITSO working example. Note: For information on configuring WebSEAL parameters, refer to Appendix A, WebSEAL configuration file reference, in the product guide, WebSEAL Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1359. To configure additional WebSEAL parameters such as timeout, do the following steps: 1. Navigate to the c:\ibm\tam\PDWeb\etc directory. 2. We modified the webseald-default.conf as seen in Example 5-9 to configure additional parameters. The webseaId-default.conf includes comments that explain each parameter. The ITSO example contains additional parameters in webseald-default.conf.
Example 5-9 Code [server] dynurl-allow-large-posts=yes [junction] http-timeout=300 https-timeout=300 [session] ssl-id-sessions=no
3. Save the webseald-default.conf file. 4. You will need to restart the Access Manager WebSEAL-default Windows service for the changes to take effect.
5.6.7 Import WebSphere Portal users and groups into TAM

Although the users and groups used by WebSphere Portal have already been created in the Tivoli Directory Server directory, the users have not been imported into the Tivoli Access Manager. The import of users into Tivoli Access Manager includes adding attributes to existing users in the LDAP directory.
301
Create the wp-tam-user-import.pd command file

In our example, we will create a command file called wp-tam-user-import.pd found in the c:\6692code\config\tamwin1 ITSO sample code directory. This command file will be used to import the WebSphere Portal users into Tivoli Access Manager using pdadmin. The ITSO-provided wp-tam-user-import.pd file is displayed in Example 5-10 on page 302. Note: Later in our configuration, we will see how Tivoli Identity Manager can be used with the Agent for Tivoli Access Manager to create users in Tivoli Access Manager as part of the user provisioning process.
Example 5-10 ITSO example wp-tam-user-import.pd file user import -gsouser admin uid=admin,cn=users,dc=itso,dc=ibm,dc=com user modify admin account-valid yes user modify admin password-valid yes group import wpsadmins cn=wpsadmins,cn=groups,dc=itso,dc=ibm,dc=com
Import WebSphere Portal users into TAM via command file

To import the WebSphere Portal users and groups into Tivoli Access Manager using a pdadmin command file, do the following steps: 1. Open a command window. 2. Copy the wp-tam-user-import.pd to a temporary directory on the Reverse Proxy node (for example, c:\temp). 3. From the temporary directory, enter the following command to import the WebSphere Portal users and groups into Tivoli Access Manager:
pdadmin -a sec_master wp-tam-user-import.pd
When prompted, enter the sec_master password. 4. To verify that the users and groups where imported properly, enter the following commands from a Windows command window:
pdadmin -a sec_master -p <password> user list * 100 pdadmin -a sec_master -p <password> group list * 100
Where <password> is the sec_master password, * is all users, and 100 is the maximum user to return.
5.6.8 Define access controls for WebSphere Portal URIs

This section describes how to define four access categories for WebSphere Portal, as defined in Table 5-11.
302
Table 5-11 Access categories for WebSphere Portal Access category WP_all_access WP_authenticated_access WP_admin_access WP_no_access Description Access for all users (authenticated and unauthenticated) Access for authenticated users only Access for administrator users only No access
Create TAM objects for WebSphere Portal URIs

To create Tivoli Access Manager objects for WebSphere Portal URIs, do the following on the Reverse Proxy node: Note: For more information on creating Tivoli Access Manager objects, refer to Chapter 12 Application integration, in the product guide, WebSEAL Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1359. 1. Create a file named dynurl.conf in the c:\ibm\tam\PDWeb\www-default\lib directory, as seen in Example 5-11. Where default is the name of the WebSEAL instance. We have included a dynurl.conf in the c:\6692code\config\tamwin1 ITSO sample code directory.
Example 5-11 ITSO example dynurl.conf /portal/wps/portal /portal/wps/myportal /portal/wps/config /portal/wps/doc /portal/wps /portal/wps/portal* /portal/wps/myportal* /portal/wps/config* /portal/wps/doc* /wps/*
Note: We have added entries for both before the mapping and after the mapping versions of URLs that will be handled by the JMT. This is necessary, as WebSEAL will perform two ACL checks, one on the URL before the JMT transformation and one after. Both must pass for access to be granted. Given that the real access control check is the second one, we have added dummy entries for the before versions and mapped them to an object that is readable by both unauthenticated and authenticated users (/portal/wps), so the first ACL check will now always pass.
303
2. To activate the definitions, do one of the following actions: Issue the following command:
pdadmin -a sec_master -p <password> server task default-webseald-wswin1 dynurl update
or Restart the Access Manager WebSEAL-default Windows service.
Define access control policy for WebSphere Portal

This section describes how to define the access control policy for WebSphere Portal and includes the following operations: Create Tivoli Access Manager ACL templates corresponding to the access categories defined for WebSphere Portal. Update the ACLs for the imported users and groups. Attach ACLs to protected objects for WebSphere Portal. To define the access control policy, do the following 1. Create a command file called wp-tam-acl.pd, as seen in Example 5-12. The file is included in the c:\6692code\config\tamwin1 ITSO sample code directory. Note: The ITSO provided wp-tam-acl.pd command file includes three sections. The first two sections in Example 5-12 do not need to be modified unless you need to create new access categories. The last section in Example 5-12 includes settings that will change based on your environment. For example, you will need to update the following: The /WebSEAL/host-instance_name represents the beginning of the Web space for a particular WebSEAL server instance (for example, /WebSEAL/wswin1-default). To retrieve your setting enter the following command on the Reverse Proxy node:
pdadmin -a sec_master -p <password> object list /WebSEAL
Record the value returned and update the command file accordingly.
Example 5-12 ITSO example wp-tam-acl.pd acl acl acl acl create create create create WP_all_access WP_authenticated_access WP_admin_access WP_no_access
304
acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl acl
modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify modify attach attach attach attach attach
WP_admin_access set user sec_master TcmdbsvaBrxl WP_admin_access set group iv-admin Tcmdbsvarxl WP_admin_access set group webseal-servers Tgmdbsrxl WP_admin_access set group wpsadmins Tr WP_admin_access set any-other T WP_admin_access set unauthenticated T WP_no_access set user sec_master TcmdbsvaBrxl WP_no_access set group iv-admin Tcmdbsvarxl WP_no_access set group webseal-servers Tgmdbsrxl WP_no_access set group wpsadmins T WP_no_access set any-other T WP_no_access set unauthenticated T WP_authenticated_access set user sec_master TcmdbsvaBrxl WP_authenticated_access set group iv-admin Tcmdbsvarxl WP_authenticated_access set group webseal-servers Tgmdbsrxl WP_authenticated_access set group wpsadmins Tr WP_authenticated_access set any-other Tr WP_authenticated_access set unauthenticated T WP_all_access set user sec_master TcmdbsvaBrxl WP_all_access set group iv-admin Tcmdbsvarxl WP_all_access set group webseal-servers Tgmdbsrxl WP_all_access set group wpsadmins Tr WP_all_access set any-other Tr WP_all_access set unauthenticated Tr /WebSEAL/wswin1-default/portal/wps/config WP_admin_access /WebSEAL/wswin1-default/portal/wps/myportal WP_authenticated_access /WebSEAL/wswin1-default/portal/wps/portal WP_all_access /WebSEAL/wswin1-default/portal/wps/doc WP_all_access /WebSEAL/wswin1-default/portal/wps WP_all_access
2. To create the Tivoli Access Manager ACLs, modify the access and attach to objects using the wp-tam-acl.pd file by entering the following from a Windows command window:
pdadmin -a sec_master -p <password> wp-tam-acl.pd
5.6.9 Configure the junction mapping table (JMT)

Several portlets, including the Resource Permissions portlet, and the productivity components editors use relative JavaScript within the portlet or component. These portlets and components will not function correctly when accessed through a WebSEAL junction. For the JavaScript to be interpreted and navigation followed correctly, WebSEAL must be configured to insert the junction point into the JavaScript. One way to accomplish this is through the use of the JMT table function in WebSEAL.
305
Modify webseald-default.conf to resolve URL length problem

The length of the generated WebSphere Portal V5.1 URLs will cause problems if your WebSEAL instance is on the Windows platform. To resolve this problem, do the following steps: 1. On the Reverse Proxy node, navigate to the c:\ibm\tam\PDWeb\etc directory. 2. Edit the webseald.conf file and change the process-root-requests property value from always to filter to avoid problems with WebSEAL processing. For example:
process-root-requests = filter
3. Save and close the file. 4. Restart the Access Manager WebSEAL-default Windows service. Attention: At the time of writing, we found that the WebSphere Portal V5.1 Administration - Resource Permission portlets did not work properly when using the jmt.conf described in this section. The Resource Permission portlets contain JavaScript with relative URLs that are not mapped properly when using the jmt.conf found in Example 5-13. The jmt.conf is designed to address this type of issue, but does not appear to be working properly in our environment when using Tivoli Access Manager V5.1 + Fixpack 9 and WebSphere Portal V5.1. To resolve this problem, do one of the following actions: Complete the steps in Modify webseald-default.conf to resolve URL length problem on page 306 (section above). This is the recommended approach. Manually insert /portal into the URL when a page does not load properly (WebSEAL error page) for WebSphere Portal Administration. For example: Incorrect:
https://wswin1.itso.ral.ibm.com/wps/myportal/......
Correct:
https://wswin1.itso.ral.ibm.com/portal/wps/myportal/......
306
Enable JMT
To enable the JMT function, define an ASCII text file called jmt.conf as follows on the Reverse Proxy node: 1. Create the jmt.conf file in the c:/ibm/tam/PDWeb/www-default/lib directory. The location of this file is specified in the [junction] stanza of the webseald-default.conf configuration file jmt-map = lib/jmt.conf. 2. The format for data entry in the table consists of the junction name, a space, and the resource location pattern. You can also use wildcard characters to express the resource location pattern. The ITSO-provided jmt.conf is displayed in Example 5-13.
Example 5-13 ITSO example jmt.conf /portal /wps/*
3. Save and close the file. 4. Reload the JMT in WebSEAL to do one of the following: Reload the JMT using the following command: i. Open a command window. ii. Enter the following command to log in to pdadmin:
pdadmin -a sec_master -p <password>
iii. Enter the following command from the pdadmin command line to reload the JMT:
server task default-webseald-wswin1 jmt load
You should see the message JMT table successfully loaded. or Restart the WebSEAL Windows service. 5. To verify that the JMT (jmt.conf) is working properly, enter the following URL in a Web browser to access WebSphere Portal via the WebSEAL (Reverse Proxy node hostname):
http://wswin1.itso.ral.ibm.com/wps/portal
You should see the default WebSphere Portal page for unauthenticated users.
307
5.6.10 Configure SSO for WebSEAL and WebSphere via TAI

When using a Reverse Proxy such as WebSEAL to authenticate users in the DMZ, it is desirable that WebSphere Application Server, as well as other back-end applications and services, trust the authentication that has been performed and the identity that is being presented by the Reverse Proxy. If this trust can be established, users then need only authenticate once to the Reverse Proxy in order to have access to all authorized services located beyond that proxy. This is commonly known as Reverse Proxy Single Sign-on (RPSS). There are two ways to establish a trust relationship between WebSphere Application Server and WebSEAL: Trust Association Interceptor (TAI): For the ITSO working example runtime environment, we chose to use TAI for the implementation procedure found in this section. or Light Weight Third Party Authentication (LTPA) Token: There are three possible methods of verifying that the request to the WebSphere Application Server came from WebSEAL: TCP junction without SSL, with basic authentication credentials supplied SSL junction with basic authentication Mutual SSL junction without basic authentication credentials Note: We used this method for the ITSO example.
Enable TAI on the Portal Server node

To enable TAI in WebSphere Application Server on the Portal Server node using the WebSphere Application Server Administrative Console, do the following steps (refer to Figure 5-16 on page 310): 1. Ensure that the WebSphere Application Server server1 is started. 2. Start the WebSphere Application Server Administrative Console: a. Enter the URL:
b. Enter WebSphere administrator credentials (for example, wpsbind). 3. Select Security Authentication Mechanisms LTPA. Note: Although LTPA is the menu option, we are configuring TAI in this example.
308
4. Click Trust Association under Additional Properties. 5. On the Trust Association page, check the Trust Association Enabled checkbox. Click Apply. 6. Click Interceptors under Additional Properties. 7. Click com.ibm.ws.security.web.WebSealTrustAssociationInterceptor. 8. Click Custom Properties under Additional Properties. 9. Click New and enter the General Properties name and value pairs specified in Table 5-12. For more information on the possible values that these properties might have, please refer to the WebSphere Portal InfoCenter.
Table 5-12 Custom properties for WebSEAL Trust Association Interceptor Name com.ibm.websphere.security.trustassociation.types com.ibm.websphere.security.webseal.id com.ibm.websphere.security.webseal.hostnames Value webseal iv-user wswin1.itso.ral.ibm.com, wswin1 Note: This is the Reverse Proxy node in our example. The host name is case sensitive. 80,443 false true Note: SSL between the WebSEAL and the IBM HTTP Server on the Portal Server node.
com.ibm.websphere.security.webseal.ports com.ibm.websphere.security.webseal.ignoreProxy com.ibm.websphere.security.webseal.mutualSSL
309
Figure 5-16 Trust association properties
After you have created all these properties, the Custom Properties should look as shown in Figure 5-16. Tip: Check and double-check the names and values of all the Custom properties before saving the configuration changes. 10.Click Save. Click Save for Save to Master Configuration. 11.Click Logout. 12.Restart the WebSphere_Portal application server.
310
Verify the TAI configuration

Now that we have enabled TAI within WebSphere Application Server on the Portal Server node, we recommend that you verify that TAI is working properly. 1. To verify that access to unauthenticated portal pages is working properly, enter the following URL in a Web browser:
http://wswin1.itso.ral.ibm.com/portal/wps/portal
In this case, there should be no authentication. 2. To verify that authenticated access is working properly, entering the following URL in a Web browser:
https://wswin1.itso.ral.ibm.com/portal/wps/myportal
WebSEAL should challenge you to authenticate. Once you log in as WebSphere Portal administrator (for example, admin), you should be directed to the users secure and personalized myportal page. Note: The Logout link will not work at this stage. In the next section we configure the WebSphere Portal login/logout for use with WebSEAL. If you are directed to the portal login screen at wps/portal/.scr/Login or the public page, there is a problem with the Trust Association Interceptor configuration.
5.6.11 Configure Portal login/logout for use with WebSEAL

In our example, we have configured WebSEAL to authenticate users for WebSphere Portal. With our current configuration, it is no longer possible to log in or log out of WebSphere Portal directly. In this section, we describe how to configure WebSphere Portal login/logout functionality for use with WebSEAL.
Modifying web.xml
To modify the WebSphere Portal login, such that login requests are directed to the personalized portal URL, do the following steps: 1. Navigate to the following directory on the Portal Server node:
c:\WebSphere\AppServer\installedApps\wpwin1\wps.ear\wps.war\WEB-INF\
2. Back up the existing web.xml. 3. Modify the web.xml contents as seen in Example 5-14 (from /redirect to /myportal).
311
Example 5-14 ITSO modified web.xml snippet <login-config id="LoginConfig_1"> <auth-method>FORM</auth-method> <realm-name>WPS</realm-name> <form-login-config id="FormLoginConfig_1"> <form-login-page>/myportal</form-login-page> <form-error-page>/error.html</form-error-page> </form-login-config> </login-config>
Create wpslogout.html
When a WebSphere Portal user log outs of WebSEAL, we would like to display the public (unauthenticated) portal page at:
http://wswin1.itso.ibm.com/portal/wps/portal
To achieve this behavior, we must create the wpslogout.html to redirect WebSEAL logout to the WebSphere Portal public page as follows: Note: The ITSO sample code c:\6692code\config\tamwin1 directory includes a sample wpslogout.html file. 1. Navigate to the following directory on the Reverse Proxy node:
c:\ibm\tam\PDWeb\www-default\lib\html\C
2. Create the wpslogout.html file as seen in Example 5-15 in the directory listed in the previous step. You will need to modify the href value to include the WebSEAL hostname (http://wswin1.itso.ral.ibm.com/portal/wps/portal, for example).
Example 5-15 ITSO example wpslogout.html <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <script language=javascript type="text/javascript"> <!-// Set this variable to a semi-colon list of the names of cookies // you do not want to delete var exception_list = ""; function delete_cookie (name, { // Set expiration date to var expiration_date = new expiration_date . setYear path) last year Date (); (expiration_date . getYear () - 1);
312
expiration_date = expiration_date . toGMTString (); // Expire the cookie var cookie_string = name + "=; expires=" + expiration_date; if (path != null) cookie_string += "; path=" + path; document . cookie = cookie_string; } function name_in_list (n, lst) { var arr = lst . split ("; "); for (var j = 0; j < arr . length; j ++) { if (arr[j] == n) return true; } return false; } function delete_all_cookies (path, exceptions) { // Get cookie list and split into an array of cookie entries var cookie_string = "" + document . cookie; var cookie_array = cookie_string . split ("; "); // Delete each cookie ... // EXCEPT those whose naems appear in the semicolon delimited list // passed in as the second parameter to this function for (var i = 0; i < cookie_array . length; ++ i) { var single_cookie = cookie_array [i] . split ("="); var name = single_cookie [0]; if (name_in_list(name, exceptions) == false) delete_cookie (name, path); } } // --> </script> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <meta http-equiv="Refresh" content="2;URL=https://wswin1.itso.ral.ibm.com/portal/wps/portal"> <title>PKMS Administration: User Log Out</title> </head> <body bgcolor="#FFFFFF" text="#000000" onLoad=delete_all_cookies("/",exception_list)>
313
<font size="+2"><b>User %USERNAME% has logged out.</b></font>
<BR><BR> <BR><BR> Redirecting to public portal page ... select <a href="https://wswin1.itso.ral.ibm.com/portal/wps/portal">here</a> if your browser does not automatically redirect after 2 seconds. </body> </html>
Modify logout.html
When users from other applications (non WebSphere Portal) accessed through WebSEAL perform logout, the logout.html page will be displayed. 1. Navigate to the following directory on the Reverse Proxy node:
C:\ibm\tam\PDWeb\www-default\lib\html\C
2. Back up the existing logout.html. 3. Replace the existing logout.html file contents as seen in Example 5-15 on page 312. Note: The ITSO sample code c:\6692code\config\tamwin1 directory includes a sample logout.html file (Example 5-16).
Example 5-16 ITSO example logout.html <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <script language=javascript type="text/javascript"> <!-// Set this variable to a semi-colon list of the names of cookies // you do not want to delete var exception_list = ""; function delete_cookie (name, path) { // Set expiration date to last year var expiration_date = new Date (); expiration_date . setYear (expiration_date . getYear () - 1); expiration_date = expiration_date . toGMTString (); // Expire the cookie
314
var cookie_string = name + "=; expires=" + expiration_date; if (path != null) cookie_string += "; path=" + path; document . cookie = cookie_string; } function name_in_list (n, lst) { var arr = lst . split ("; "); for (var j = 0; j < arr . length; j ++) { if (arr[j] == n) return true; } return false; } function delete_all_cookies (path, exceptions) { // Get cookie list and split into an array of cookie entries var cookie_string = "" + document . cookie; var cookie_array = cookie_string . split ("; "); // Delete each cookie ... // EXCEPT those whose naems appear in the semicolon delimited list // passed in as the second parameter to this function for (var i = 0; i < cookie_array . length; ++ i) { var single_cookie = cookie_array [i] . split ("="); var name = single_cookie [0]; if (name_in_list(name, exceptions) == false) delete_cookie (name, path); } } // --> </script> <html> <head> <meta http-equiv="Content-Type" content= "text/html; charset=UTF-8"> <title>PKMS Administration: User Log Out</title> </head> <body bgcolor="#FFFFFF" text="#000000" onLoad=delete_all_cookies("/",exception_list)> <font size="+2"><b>User %USERNAME% has logged out.</b></font> </body> </html>
315
Modify ConfigService.properties
To modify the WebSphere Portal logout command to point to the WebSEAL logout command, do the following steps: 1. Navigate to the following directory on the Portal Server node:
c:\WebSphere\PortalServer\shared\app\config\services
2. Back up the ConfigService.properties file. 3. Modify the ConfigService.properties with the contents seen in Example 5-17. You will need to update the redirect.logout and redirect.logout.ssl to true, and redirect.logout.url for your environment. Note: Example 5-17 only includes the values we changed, not the entire contents of the ConfigService.properties file.
Example 5-17 ITSO example ConfigService.properties snippet # Logout redirect parameters # # Default: false, false, <none> redirect.logout = true redirect.logout.ssl = true redirect.logout.url = https://wswin1.itso.ral.ibm.com/pkmslogout?filename=wpslogout.html
Modify ToolBarInclude.jsp files

This section modifies the ToolBarInclude.jsp to address the following items: The ability of end users to self-register by removing the link to the self-registration screen from the public portal page The ability of end users to edit their profiles by removing the link to the edit profiles screen from the private portal page The ability of end users to request their passwords by removing the forgot password link from the public portal page The address of the Log in link by altering the link to point to the Reverse Proxy node The procedure requires that each ToolBarInclude.jsp is updated in each theme in which the file exists.
316
Note: There is one occurrence of the ToolBarInclude.jsp in the root of the ../wps.war/themes/html directory. This ToolBarInclude.jsp is used as the default if a theme does not have its own ToolBarInclude.jsp. In addition, you will need to update the ToolBarInclude.jsp (if found) in the ../wps.ear/wps.war/themes/html/<theme_name> directory for each theme. Modify the ToolBarInclude.jsp for each occurrence of the file, as follows: 1. Navigate to the following directory on the Portal Server node: Root directory:
c:\WebSphere\AppServer\installedApps\wpwin1\wps.ear\wps.war\themes\html
Or Theme directory:
c:\WebSphere\AppServer\installedApps\wpwin1\wps.ear\wps.war\themes\html/<th eme>
Where <theme> is the theme directory of interest. We have listed the themes we updated the ToolBarInclude.jsp: Admin AdminLeftNavigation Corporate Engineering Finance Science
2. Back up the ToolBarInclude.jsp. 3. Open the file in a text editor. Comment out the forgot password, selfcare, and enroll buttons as shown Example 5-18.
Example 5-18 ITSO example ToolBarInclude.jsp snippet to be used as the default theme <%-- forgot password button --%>
<%-<wps:if loggedIn="no" notScreen="ForgotPassword"> <td class="wpsToolBar" valign="middle" nowrap> <a class="wpsToolBarLink" href='<wps:url screen="ForgotPassword" home="public"/>'><wps:text key="link.password" bundle="nls.engine"/></a> </td> </wps:if>
--%>
<%-- selfcare button --%> <%-- uncomment to allow selfcare via screen
317
<wps:if loggedIn="yes" notScreen="SelfcareUserForm,SelfcareUserConf" portletSolo="no"> <td class="wpsToolBar" valign="middle" nowrap> <a class="wpsToolBarLink" href='<wps:url command="PrepareSelfcare" reqid="no"/>'><wps:text key="link.selfcare" bundle="nls.engine"/></a> </td> </wps:if> --%> <%-- comment to allow selfcare via screen --%> <wps:if loggedIn="yes" portletSolo="no" notSelection="wps.Selfcare"> <wps-internal:adminlinkinfo name="<%=AdminUniqueNamesMappingService.SELFCARE%>"> <wps:urlGeneration contentNode="<%=wpsContentNode%>" compositionNode='<%= wpsCompositionNode %>' portletWindowState="Normal"> <wps:urlParam type="render" name="<%= SharedParamConstants.ACCESS_ORIGIN %>" value="<%= SharedParamConstants.THEME %>"/> <wps:urlParam type="render" name="<%= SharedParamConstants.ORIGIN_CONTENT_NODE %>" value="<%= wpsContentNodeID %>" /> <td class="wpsToolBar" valign="middle" nowrap> <a href="<% wpsURL.write(out); %>" class="wpsToolBarLink"><wps:text key="link.selfcare" bundle="nls.engine"/></a> </td> </wps:urlGeneration> </wps-internal:adminlinkinfo> </wps:if>
<%-- enroll button --%>
<%-<wps:if loggedIn="no" notSelection="wps.Selfcare" > <% String dt = com.ibm.wps.puma.UserManager.instance().getDirectoryType(); if (dt==null) { dt = ""; } if (!dt.equals("SSPM")) { %>
--%>
<%--uncomment this to allow registration via screen <td class="wpsToolBar" valign="middle" nowrap> <a class="wpsToolBarLink" href='<wps:url command="PrepareEnrollment" home="public" reqid="no"/>'><wps:text key="link.enrollment" bundle="nls.engine"/></a> </td> --%> <%-- comment this to allow registration via screen --%>
<%-<wps-internal:adminlinkinfo name="<%=AdminUniqueNamesMappingService.SELFCARE%>">
318
<wps:urlGeneration contentNode="<%=wpsContentNode%>" compositionNode='<%= wpsCompositionNode %>' portletWindowState="Normal" > <wps:urlParam type="render" name="<%= SharedParamConstants.ACCESS_ORIGIN %>" value="<%= SharedParamConstants.THEME %>"/> <wps:urlParam type="render" name="<%= SharedParamConstants.ORIGIN_CONTENT_NODE %>" value="<%= wpsContentNodeID %>" /> <td class="wpsToolBar" valign="middle" nowrap> <a href="<% wpsURL.write(out); %>" class="wpsToolBarLink"><wps:text key="link.enrollment" bundle="nls.engine"/></a> </td> </wps:urlGeneration> </wps-internal:adminlinkinfo> <% } %> </wps:if>
--%>
</wps-internal:ifAdminPage> </wps:navigation> <%-- help button --%> <td class="wpsToolBarIcon" valign="middle" nowrap> <a href='<%= wpsDocURL %>/help/index.html' target="PortalHelpWindow" onClick="javascript: window.open('<%= wpsDocURL %>/help/index.html','PortalHelpWindow','resizable=yes,scrollbars=yes,menubar=no,toolbar=yes,sta tus=no,width=800,height=600,screenX=10,screenY=10,top=10,left=10').focus();returnfalse;" class="wpsToolBarLink"><img border="0" align="absmiddle" width="16" height="16" src='<wps:urlFindInTheme file="help.gif"/>' alt='<wps:text key="link.help" bundle="nls.engine"/>' title='<wps:text key="link.help" bundle="nls.engine"/>' ></a> </td>
<%-- Edit login button section (uncomment and update) --%>

<%-- login button --%> <wps:if loggedIn="no" notScreen="Login"> <td class="wpsToolBar" valign="middle" nowrap> <a class="wpsToolBarLink" href='<wps:url home="protected" screen="Home" ssl="true"/>'><wps:text key="link.login" bundle="nls.engine"/></a> </td> </wps:if> <%--comment this to allow login via screen --%>
<%-<wps:if loggedIn="no" notSelection="wps.Login" >
319
<wps:urlGeneration contentNode="wps.Login" portletWindowState="Normal"> <td class="wpsToolBar" valign="middle" nowrap> <a href="<% wpsURL.write(out); %>" class="wpsToolBarLink"><wps:text key="link.login" bundle="nls.engine"/></a> </td> </wps:urlGeneration> </wps:if>
--%>
... ...
4. Edit the login button section as seen in Example 5-18 on page 317 for each theme used. 5. Save and close the file. 6. Open and save the version of Default.jsp found in the root of the html directory and corresponding theme directory (if they exist) to force recompile.
c:/WebSphere/AppServer/installedApps/wpwin1/wps.ear/wps.war/themes/html/Def ault.jsp
This is necessary to make the application server recompile the JSP pages in order to have the changes take effect (touch operation). 7. Repeat process for other themes used.
Modify WpsHostName property in wpconfig.properties

After junction configuration the property WpsHostName in wpconfg.properties should be set to the WebSEAL hostname. This will allow proper URL filtering and protocol switching by the WebSEAL. 1. Navigate to the <wp_home>\config directory. 2. Modify the wpconfig.properties file as follows: From (Portal Server node hostname):
WpsHostName=wpwin1.itso.ral.ibm.com
To (Reverse Proxy node hostname):

WpsHostName=wswin1.itso.ral.ibm.com
3. Save and close the file. 4. Execute the wpsconfig.bat command to load the configuration changes: a. Ensure that the server1 application server is started. b. Open a command window and navigate to the following directory:
c:\WebSphere\PortalServer\config
c. Execute the wpsconfig command:
320
wpsconfig httpserver-config
You should see a message, BUILD SUCCESSFUL. 5. Restart the WebSphere_Portal application server.
Verify create/login of new user

To further test the TAI, we will create a new user (any random user) as follows: 1. Enter the following commands from the pdadmin console on the Reverse Proxy node after you have logged in as sec_master: Note: The syntax of the user create command for Tivoli Access Manager is:
user create -gsouser <user_name> <user_dn> <common name> <surname> <password> user create -gsouser jane uid=jane,cn=users,dc=itso,dc=ibm,dc=com Jane Doe passw0rd user modify jane account-valid yes
Tip: The user password chosen has to conform to the Tivoli Access Manager password policy. It requires a minimum length of eight characters formed by at least four alphabetical characters and one non-alphabetical character with no more than two repeated characters. The password policy can be changed on a user base or global base. For more information refer to the product guide, Base Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1360. 2. Log in to the portal site using this newly created user:
5.7 Configure WebSphere Portal authorization with TAM

This section describes how to configure WebSphere Portal V5.1 authorization with Tivoli Access Manager V5.1.
321
Note: IBM WebSphere Portal V5.1 includes new tooling and capabilities for simplifying basic configuration of Tivoli Access Manager authentication, authorization, and Credential Vault. For more information, refer to the IBM WebSphere Portal V5.1 InfoCenter. In our scenario, we did use the WebSphere Portal V5.1 tooling to configure authorization for Tivoli Access Manager.
5.7.1 Configure SSL between WebSphere and TAM

The SrvSslCfg command is used to configure the SSL connection between the WebSphere Application Server and Tivoli Access Manager. This command creates a keyfile and a properties file, which will be used later for WebSphere Portal configuration. The SrvSslCfg command also creates the user who is specified as <was_id> and inserts this user in the following Tivoli Access Manager LDAP groups:
cn=remote-acl-users cn=SecurityGroup,secauthority=Default
To configure the SSL connection between WebSphere Application Server used by WebSphere Portal and the Tivoli Access Manager, do the following steps: 1. Open a command window on the Portal Server node. 2. In our example, we created a command file named wpwin1_svrsslcfg.bat (see Example 5-19) in the c:\6692code\config\wpwin1 directory of the ITSO sample code containing the SvrSslCfg command and parameters for the ITSO environment. In Example 5-19, <password> needs to be updated with the correct sec_master password.
Example 5-19 ITSO sample wpwin1_svrsslcfg.bat c:\ibm\Java131\jre\bin\java com.tivoli.pd.jcfg.SvrSslCfg -action config -admin_id sec_master -admin_pwd <password> -appsvr_id amwas -port 7201 -mode remote -policysvr tamwin1.itso.ral.ibm.com:7135:1 -authzsvr tamwin1.itso.ral.ibm.com:7136:1 -cfg_file "c:\WebSphere\AppServer\java\jre\PdPerm.properties" -key_file "c:\WebSphere\AppServer\java\jre\lib\security\pdperm.ks" -cfg_action replace
<admin_id> is the Tivoli administrator user ID. The default value is sec_master. <password> is the password for the Tivoli administrator user ID.
322
<was_id> is the unique WebSphere Application Server identifier to be inserted into Tivoli Access Manager. Note: The value is user defined. In our example, we entered amwas for the <was_id>. <port_number> is the TCP/IP port that WebSphere Application Server listens to for policy server notifications. This value must be filled in even though WebSphere Application Server does not currently use this port. <pdmgrd_host> is the pdmgrd host (pdmgrd is a Tivoli Access Manager process). <pdacld_host> is the pdacld host (pdacld is a Tivoli Access Manager process). <pdacld_host> is the pdmgrd port. The default port number is 7135. <pdacld_port> is the pdacld port. The default port number is 7136. <rank> is the rank of the host. If only one host is specified, this value is 1. <config_file_path> is the path to the properties file that you will create and insert into ExternalAccess ControlService.properties, for example, c:\WebSphere\AppServer\java\jre\PdPerm.properties. <keystore_path> is the path to the keystore, for example, c:\WebSphere\AppServer\java\jre\lib\security\pdperm.ks. replace is used to replace the existing configFile URL and keystoreFile URL. Note: Alternatively, you could enter the following SvrSslCfg command to configure an SSL connection between the WebSphere Application Server on the Portal Server node and Tivoli Access Manager on the Policy Server node:
c:/ibm/Java131/jre/bin/java com.tivoli.pd.jcfg.SvrSslCfg -action config -admin_id <admin_id> -admin_pwd <password> -appsvr_id <was_id> -port <port_number> -mode remote -policysvr <pdmgrd_host>:<pdmgrd_port>:<rank> -authzsvr <pdacld_host>:<pdacld_port>:<rank> -cfg_file "<config_file_path>" -key_file "<keystore_path>" -cfg_action replace
When the SvrSslcfg command completes, you should see the message:
The configuration completed successfully.
323
3. To verify that the SvrSslCfg command worked properly, do the following steps: a. Open a command window on the Policy Server node. b. Enter the following command to log in to pdadmin:
c. Enter the following command to list the servers defined in Tivoli Access Manager:
server list
You should see the newly created server amwas-wpwin1, where amwas is the appsvr_id and wpwin1 is the host name of the Portal Server node (WebSphere Application Server is installed).
5.7.2 Configure WebSphere Portal authorization for TAM

To configure WebSphere Portal V5.1 authorization for Tivoli Access Manager, do the following steps: 1. Configure and validate connection for WebSphere Portal (wpsconfig) to Tivoli Access Manager. a. Navigate to <wp_home>\config directory on the Portal Server node. b. Back up the wpconfig.properties file. c. Modify the wpconfig.properties file with the keyword values displayed in Table 5-13.
Table 5-13 ITSO wpconfig.properties file values for TAM connection Keyword PDAdminID PDAdminPW Value for ITSO sample sec_master <sec_master_password> Description This is the Tivoli Access Manager administrator user ID. This is the Tivoli Access Manager administrator user ID password. Note: If you do not wish to include the password in the wpconfig.properties file, you can pass it as an argument at the time you run the WPSconfig task. This is the path of the Tivoli Access Manager AMJRTE properties file.
PDPermPath
C:/WebSphere/AppServer/java/jre/PdPerm. properties
324
d. Save and close the file. e. Open a command window and navigate to the <was_home>\bin directory. f. Start the server1 application server.
startServer server1
g. Stop the WebSphere_Portal application server.

stopserver WebSphere_Portal -username wpsbind -password <wpsbind_password>
h. Enter the following command to run the following validate connection task:
WPSconfig.bat validate-pdadmin-connection
You should see the following message to confirm the connection was successful:
BUILD SUCCESSFUL
Note: Alternatively, if you did not include the PDAdminPW value in the wpconfig.properties file, you can add the argument as follows:
WPSconfig validate-pdadmin-connection -DPAdminPW=<password>
2. Mask passwords (optional). Use the WebSphere Application Server encoding mechanism to mask the passwords in the production version of the <wp_home>/shared/app/config/services/ExternalAccessControlService.prop erties file. Refer to the detailed instructions on Password masking in the WebSphere Portal V5.1 InfoCenter. 3. Back up the following WebSphere Portal configuration files:
<wp_home>/shared/app/config/services/AccessControlConfigService.properties <wp_home>/shared/app/config/services.properties <wp_home>/shared/app/config/services/ConfigService.properties <wp_home>/shared/app/config/services/AccessControlDataManagementService.pro perties <wp_home>/shared/app/config/services/AuthenticationService.properties <wp_home>/shared/app/config/services/ExternalAccessControlService.propertie s
4. Configure and run the enable Tivoli Access Manager task. a. Navigate to <wp_home>\config directory on the Portal Server node. b. Back up the wpconfig.properties file. c. Modify the wpconfig.properties file with the keyword values displayed in Table 5-13.
325
Table 5-14 ITSO wpconfig.properties file values for TAM connection Keyword PDAdminID PDAdminPW Value for ITSO sample sec_master <sec_master_password> Description This is the Tivoli Access Manager administrator user ID. This is the Tivoli Access Manager administrator user ID password. Note: If you do not wish to include the password in the wpconfig.properties file, you can pass it as an argument at the time you run the WPSconfig task. This is the path of the Tivoli Access Manager AMJRTE properties file. Root objectspace entry in the TAM namespace. All Portal roles will be installed under this objectspace entry. When the Tivoli Access Manager external authorization plug-in is started, it will detect and, if necessary, create a custom action in Tivoli Access Manager. The combination of the action group and the action determines the TAM permission string required to assign membership to externalized Portal roles. When the Tivoli Access Manager external authorization plug-in is started, it will detect and, if necessary, create a custom action group in Tivoli Access Manager. The combination of the action group and the action determines the TAM permission string required to assign membership to externalized Portal roles. When Portal externalizes a role, it can automatically create and attach a TAM ACL granting membership to the user doing the role. If you set this property to false, the TAM administrator will be responsible for creating TAM ACLs to allow access to Portal roles.
PDPermPath PDRoot
C:/WebSphere/AppServer/java/jre/ PdPerm.properties /WPSv5
PDAction
PDActionGroup
[WPS5]
PDCreateAcl
true
d. Save and close the file. e. Open a command window and navigate to the <was_home>\bin directory. f. Start the server1 application server.
startServer server1
326
g. Stop the WebSphere_Portal application server.

stopserver WebSphere_Portal -username wpsbind -password <wpsbind_password>
h. Enter the following command to run the following enable Tivoli Access Manager authorization task:
WPSconfig enable-tam-authorization
You should see the following message to confirm Tivoli Access Manager enablement was successful:
BUILD SUCCESSFUL
5. Start the WebSphere_Portal application server.

cd \WebSphere\AppServer\bin startserver WebSphere_Portal
Note: When WebSphere_Portal application server starts, TAMExternalAccessControlServices creates the necessary topology in Tivoli Access Manager to begin externalizing roles, as well as creating the Administrator@EXTERNAL ACCESS CONTROL role. Depending on your configuration setting for externalaccesscontrol.createAcl, it also adds the WebSphere Portal administrator user (for our example, admin) to the ACL that is attached to this role. 6. Modify the display of the externalized roles (optional). We did not do this for our example. For details, refer to the WebSphere Portal V5.1 InfoCenter.
5.7.3 Verify entries in TAM for Portal external authorization

When the WebSphere Portal starts, TAMExternalAccessControlServices creates the necessary topology in Tivoli Access Manager to begin externalizing roles, and also creates the following items: TAM ACL:
WPSv5__Administrator-Virtual_wps-EXTERNAL_ACCESS_CONTROL_1
TAM Object (WebSphere Portal role):

/WPSv5/Administrator@VIRTUAL_wps.EXTERNAL_ACCESS_CONTROL_1
To confirm this, execute the following commands in a pdadmin session on the Reverse Proxy node: 1. Open a command window and log in to pdadmin:
327
2. Verify the /WPSv5 objectspace has been created by entering the following command:
objectspace list
You should see the /WPSv5 objectspace in the list. 3. Verify the WPS action group has been created by entering the following command:
action group list
You should see the following results:

primary WPS5
4. To verify that the portal administrator has the Administrator role, view the ACL for the namespace entry representing the /WPSv5/Administrator@VIRTUAL_wps.EXTERNAL_ACCESS_CONTROL_1 object by entering the following command on the pdadmin command line:
acl show WPSv5__Administrator-VIRTUAL_wps-EXTERNAL_ACCESS_CONTROL_1

User admin [WPS]m
5. To display the link between the ACL and the object, enter the following command:
acl find WPSv5__Administrator-VIRTUAL_wps-EXTERNAL_ACCESS_CONTROL_1

/WPSv5/Administrator@VIRTUAL_wps.EXTERNAL_ACCESS_CONTROL_1
At this stage, WebSphere Portal and Tivoli Access Manager are configured for authentication and authorization. As part of Chapter 11, Application deployment on page 469, we will demonstrate how to externalize resources for the provisioning portlet application from WebSphere Portal to Tivoli Access Manager.
5.8 Configure reverse password synchronization

In our scenario, Tivoli Identity Manager is used to create and manager user IDs for several external systems. This section describes how to configure the WebSEAL and Tivoli Identity Manager, such that if a password is changed in WebSEAL it will be propagated to Tivoli Identity Manager and then external systems. This type of configuration is known as reverse password synchronization.
328
Note: For more information on configuring reverse password synchronization refer to the product guide, Installation Guide, Reverse Password Synchronization for Tivoli Access Manager WebSEAL, which is included with the IBM Tivoli Identity Manager Agent V4.5.9 for IBM Tivoli Access Manager V5.1 for e-business.
5.8.1 Prerequisites
As part of our installation procedure for the Access Manager node in 4.3, Access Manager node installation on page 157, we installed and configured the Tivoli Identity Manager Agent V4.5.9 for Tivoli Access Manager. In addition, we installed and configured a profile so that end users can manage their Tivoli Access Manager account passwords.
Verify the ACI exists

Before installing the Reverse Password Synchronization Agent, check the configuration as follows on the Identity Manager node: 1. Log in to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Select the My Organization tab. 3. Click the ITSO organization tree. 4. From the left-hand navigation bar, select Control Access. You should see that a corresponding organizational Access Control Information (ACI) has been set for the Tivoli Access Manager account. If so, you can continue to 5.8.3, Reverse Password Synchronization Agent installation on page 330. If the ACI does not exist, create the as described in the next section (see Create ACI on page 329). Note: In our scenario, we had create the ACI.
Create ACI
To create the ACI within Tivoli Identity Manager, do the following steps: 1. Click Add from the Control Access tab of the Tivoli Identity Manager Web interface. 2. Select Account from the Select a Category drop-down list, and then click Continue.
329
3. When the Access Control Information Details page appears, enter the following information: a. ACI Name: ACI for TAM Account password synchronization b. Scope: select SubTree c. Under Attributes, click Attribute Permissions. i. Select Grant under the Read and Write columns for the Password attribute. ii. Click Continue. d. When you return to the Access Control Information Details page, click Submit. The new ACI should be displayed.
5.8.2 Enable password synchronization in Tivoli Identity Manager

To enable reverse password synchronization between accounts, the Tivoli Identity Manager password synchronization feature must be configured as follows: 1. Log in to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click the Configuration tab. 3. Click Properties tab. 4. Check the Enable Password Synchronization checkbox. 5. Click Apply Changes. 6. You should see a dialog with the message, Operation succeeded. Click OK.
5.8.3 Reverse Password Synchronization Agent installation

To install the Reverse Password Synchronization Agent on the Reverse Proxy node (WebSEAL), do the following steps: 1. Ensure that the 8.3 path convention is used (C:\Progra~1). On the Windows operation system, file and directory names might contain space characters. Since WebSEAL will expect additional arguments for any passwd-strength and post-pwdchg-process configuration lines separated by a space character, you must use the 8.3 convention, otherwise you will get truncated long filenames (C:\Progra~1\Tivoli\PdWeb\etc\passwdsync.conf, for example).
330
Note: In our example, we installed the WebSEAL to the c:\ibm\tam directory, thus we did not have this problem. 2. Copy the dynamic libraries revpwdchk.dll and revpwdsyn.dll from the IBM Tivoli Identity Manager Agent for Tivoli Access Manager distribution to the c:\ibm\tam\PDWeb\bin directory on the Reverse Proxy node (WebSEAL). 3. Copy the passwdsync.conf from the IBM Tivoli Identity Manager Agent for Tivoli Access Manager distribution to the c:\ibm\tam\PDWeb\etc directory on the Reverse Proxy node (WebSEAL). 4. Modify the webseald-default.conf. a. Navigate to the c:\ibm\tam\PDWeb\etc directory. b. Back up the webseald-default.conf file. c. Open the webseald-default.conf in a text editor. d. Modify the [authentication-mechanisms] stanza as follows (entered as two single lines):
passwd-strength=C:\ibm\tam\PDWeb\bin\revpwdchk.dll&C:\ibm\tam\PDWeb\etc\ passwdsync.conf check post-pwdchg-process=C:\ibm\tam\PDWeb\bin\revpwdsyn.dll&C:\ibm\tam\PDWeb\ etc\passwdsync.conf synch
5.8.4 Configure the Agent with Tivoli Identity Manager

The Reverse Password Synchronization Agent uses the HTTPS protocol. The Agent must be configured to accept the corresponding Tivoli Identity Manager service. To configure the Reverse Password Synchronization Agent on the Reverse Proxy node (WebSEAL) with the Tivoli Identity Manager Server on the Identity Manager node, do the following steps: 1. Create a new key store using the IBM Key Management Utility on the Reverse Proxy node. In our example, we created the c:\ibm\tam\PDWeb\keytab-default\revpwdsync.kdb. a. Open a command window on the Reverse Proxy node and enter the following commands to start the IBM Key Management Utility:
cd \ibm\gsk7\bin set JAVA_HOME=c:\ibm\Java131\jre gskikm
331
b. From the menu bar, click Key Database File New. c. In the New window, enter the following information and then click OK: Key Database Type: select CMS File name: revpwdsync.kdb Location: c:\ibm\tam\PDWeb\keytab-default
d. In the Password Prompt window, enter the following information and then click OK: Password: <your_password> (to protect the key store file) Check Set expiration time? and enter the number of days before the password will expire. Note: Although not required in a development environment, it is recommended that all key stores used in production environments set and expiration period. Check Stash the password to a file
e. When the information window appears, click OK. 2. Modify the passwdsync.conf file. a. Navigate to the c:\ibm\tam\PDWeb\etc directory. b. Back up the passwdsync.conf file. c. Open the passwdsync.conf in a text editor. d. Modify passwdsync.conf file with the values displayed in Table 5-15 on page 332.
Table 5-15 ITSO sample passwdsync.conf Keyword itim-server-name Value for ITSO sample timwin1.itso.ral.ibm.com Description This is the URL that accesses the password strength and password sync servlets on the Tivoli Identity Manager server. In a WebSphere Application Server cluster environment, you need to configure SSL for IBM HTTP Server. See the section below for instructions. If you are using a WebSphere Application Server single-server environment you do not need to configure SSL for IBM HTTP Server. The port associated with the itim-server-name URL above. The default HTTPS port is 9443.
servlet-port
9443
332
Keyword principal-name
Value for ITSO sample itim manager
Description An ID which has the necessary permission(s) to request the check and synchronization operations. In our example, we used the ITIM manager. Note: For production purposes, it is a best practice to create a separate account with appropriate permissions and use this account instead of the itim manager account.
principal-password service-source-dn
<itim_mgr_password> erservicename=Tivoli Access Manager,o=ITSO,ou=ITSO,dc=c om Note: all 1 line.
The password for the Tivoli Identity Manager Principal Name. Holds the pseudo-distinguished name of the service (resource) issuing the password synchronization request. This pseudo-name consists of the attributes o, ou and dc from the Tivoli Identity Manager LDAP organization context, and the erservicename attribute of the Tivoli Access Manager service name, as defined in Tivoli Identity Manager. Note: The notebox below this table explains how to determine the pseudo-distinguished name values.
keydatabase-file keydatabase-password servlet-context
c:\ibm\tam\PDWeb\keytab-def ault\revpwdsync.kdb <password> /passwordsynch/synch
The location and name of the Key Database file. The password for the Key Database file. The password synchronization context root on the application server.
333
Note: Determine the Pseudo-Distinguished Name Values The service-source-dn entry holds the pseudo-distinguished name of the service issuing the password synchronization request. To assist in determining the correct entries, this name may be considered to contain the following components, in the order C+B+A. C is the erServiceName attribute of the service. B is the o attribute of the organization to which the service belongs. A is the ou and dc parts of the service distinguished name (DN). For example, we did the following steps to determine the proper value: 1. To determine the C (erServiceName) and A (ou and dc) value, enter the following command:
C:\ibm\gsk7\bin>ldapsearch -h timwin1 -b dc=com objectclass=*tam*service dn erServiceName
Record the value of erServiceName (C), ou and dc (A) from the following:
erglobalid=5560088801151200925,ou=services,erglobalid=0000000000000000000 0,ou=ITSO,dc=com erservicename=Tivoli Access Manager
2. To determine the B value, enter the following command:

C:\ibm\gsk7\bin>ldapsearch -h timwin1 -b dc=com erglobalid=00000000000000000000 o
Record the value of o from the following:

erglobalid=00000000000000000000,ou=ITSO,dc=com o=ITSO
3. Concatenate the values of C+B+A to create the pseudo-distinguished name:

erservicename=Tivoli Access Manager,o=ITSO,ou=ITSO,dc=com
4. Save and close the file. 5. Restart the Access Manager WebSEAL-default Windows service. In our environment, the configuration will be verified when we add users and accounts as part of our workflow configuration.
334
5.9 Additional configuration and security hardening

This section highlights additional Tivoli Access Manager configuration tasks, as well as security hardening tasks, both of which are documented in detail in the IBM Redbook, Develop and Deploy a Secure Portal, Using WebSphere Portal V5 and Tivoli Access Manager V5.1, SG24-6325.
5.9.1 Configure WebSEAL and WebSphere Portal session timeouts

Both WebSEAL and WebSphere Portal establish sessions with the client browser when initially accessed. These sessions are independent of each other, but both must be valid in order for the system to work as expected. For a detailed description of the architecture and considerations for session timeouts, refer to 2.6.8, WebSEAL and WebSphere Portal session considerations on page 74. This section includes the following tasks to configure WebSphere Portal and WebSEAL session timeouts: Modify the WebSphere Portal session timeout. Configure WebSphere Portal to resume timed out sessions. Modify the WebSEAL session timeout.
Modify the WebSphere Portal session timeout

Modify the WebSphere Portal session timeout values on the Portal Server node from the WebSphere Application Server Administrative Console, as follows: 1. Ensure that the server1 application server is started. If not, start the server as follows:
2. Start the WebSphere Application Server Administration Console by entering the following URL in a Web browser:
http://<was_hostname>:9090/admin
3. Log on to the WebSphere Administration Console (for example, wpsbind). 4. Click Servers Application Servers. 5. Click WebSphere_Portal. 6. Click Web Container. 7. Click Session Management. 8. From the Session Management Configuration page, modify the following setting and then click OK:
335
Session timeout: Select Set timeout. Minutes: 25 (default 30) Note: Session timeout value (minutes) should be set based on the business requirements for security and performance. For example, you may consider reducing this value for high volume Web sites. 9. Click Save. 10.When the Save to Master Configuration page appears, click Save. 11.Log out and close the WebSphere Administrative Console. 12.The WebSphere_Portal application server needs to be restarted for this change to take effect. If you plan on performing the steps in Configure WebSphere Portal to resume timed out sessions on page 336, the restart can be deferred until after that task is complete.
Configure WebSphere Portal to resume timed out sessions

To configure the WebSphere Portal to resume timed out sessions, do the following steps on the Portal Server node: 1. Open a command window and navigate to the following directory:
c:\WebSphere\PortalServer\shared\app\config\services
2. Modify the ConfigService.properties file as follows: a. Search the ConfigService.properties file for the persistent.session.level. Note: We chose to accept the default persistent.session.level = 0, which means that the window state will not be preserved when the session is persisted. b. Add the following entry above the persistent.session.level property:
timeout.resume.session = true
Note: By default, WebSphere Portal will invalidate sessions when they time out. The timeout.resume.session = true WebSphere Portal will persist the sessions when they time out instead of invalidating them. For more detail refer to 2.6.8, WebSEAL and WebSphere Portal session considerations on page 74. c. Save and close the ConfigService.properties file.
336
3. The WebSphere_Portal application server needs to be restarted for this change to take effect.
Modify the WebSEAL session timeout

Modify the WebSEAL session timeout values on the Reverse Proxy node, as follows: 1. Navigate to the c:\ibm\tam\PDWeb\etc directory. 2. Modify the webseald-default.conf file. a. Search for inactive-timeout. b. We recommend that you change the inactive-timeout value from the default of 600 seconds to match the WebSphere Portal session timeout. For example, we set the WebSphere Portal session timeout to 25 minutes; thus the inactive-timeout for WebSEAL is set to 1500 seconds.
inactive-timeout = 1500
Note: The inactive-timeout value should not exceed the WebSEAL timeout value (located above the inactive-timeout value in the .conf file). By default, timeout = 3600 seconds. Simply increase the timeout value to be equal to or greater than the inactive-timeout value. For more details, refer to 2.6.8, WebSEAL and WebSphere Portal session considerations on page 74; and the product guide, WebSEAL Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1359. 3. Save and close the webseald-default.conf file. 4. The WebSEAL needs to be restarted for this change to take effect.
5.9.2 Configure WebSEAL to handle favicon.ico

Some Web browsers have unexpected behavior with the default WebSEAL configuration attempting to load the favicon.ico. To configure WebSEAL to handle favicon.ico to work with all Web browsers, do the following steps on the Reverse Proxy node: 1. Open a command window and log in to pdadmin.
2. Enter the following acl attach command:

acl attach /WebSEAL/wswin1-default/favicon.ico WP_all_access
Where wswin1-default is the WebSEAL instance and WP_all_access is ACL that allows access for all users.
337
5.9.3 Security hardening

Security hardening is out of scope for this redbook. Although the versions of the products used in this redbook are newer, many of the configuration tasks found in the Security hardening chapter of the redbook, Develop and Deploy a Secure Portal, Using WebSphere Portal V5 and Tivoli Access Manager V5.1, SG24-6325, still apply.
338
Chapter 6.
Development environment installation

This chapter describes how to install and configure a development environment on the Windows platform for the ITSO working example. The development environment defined in this chapter consists of three nodes, including the Development node, Identity Management node, and Content Management node. In addition, we will describe the required steps to prepare the workbench within Rational Application Developer for application development. When implementing the test nodes in the environment, we will note the unique settings and reference the procedures found in Chapter 4, Runtime environment installation on page 129 and Chapter 5, Runtime environment configuration on page 235. This chapter is organized into the following sections: Planning Identity Manager node installation Content Management node installation Development node installation Configuration
339
6.1 Planning
This section describes the scenario for the ITSO working example development environment, and provides information regarding the hardware and software levels we used to implement the development environment.
6.1.1 Architecture overview

Figure 6-1 depicts the development environment used for the ITSO working example. For more information on this development environment topology, refer to 3.4.5, Development environment topology and product mapping on page 128.
Tivoli Identity Manager 4.5.1 + FP42 Tivoli Directory Server 5.2 + FP2 (Server, Client) DB2 UDB 8.2 ESE + FP8 IBM HTTP Server 1.3.28 IBM WebSphere Application Server 5.1 IBM GSKit 7.0.3.8 HR application WAR (portlets) and EAR (servlets, EJBs) deployed and running Windows 2000 Server + SP4
Identity Manager
(timdev1)
Development
(ganci1)
Content Management
(cmdev1)
Rational Application Developer V6.0.0.1 (IDE, Portal Tools, Portal 5.1 Test Env) DB2 Information Integrator for Content V8.3 (CM connector) Tivoli Identity Manager V4.5.1 + FP42 (connector jars - API)I DB2 UDB V8.2 ESE + FP8 HR application WAR (portlets) and EAR (servlets, EJBs) deployed and running Windows 2000 Professional + SP4

Server, Resource Manager, System Admin Client) WebSphere Application Server 5.1.1 IBM HTTP Server 1.3.28 DB2 UDB V8.2 ESE + FP8 Windows 2000 Server + SP4
Figure 6-1 ITSO development environment and product mapping
We would like to highlight a few key points regarding the ITSO development environment: Although Figure 6-1 displays three physical nodes, we used VMWare for the Identity Manager and Document Management nodes.
340
The Development node includes IBM Rational Application Developer V6.0.0.1, WebSphere Portal V5.1 Test Environment, and is the primary node for development. In this environment, we will share the Tivoli Directory Server for both the Tivoli Identity Manager directory, and as a common LDAP directory for application single sign-on (SSO) purposes (WebSphere Portal, Tivoli Access Manager, DB2 Content Manager). This is possible since Tivoli Identity Manager will use the dc=com suffix and the applications will use dc=itso,dc=ibm,dc=com.
6.1.2 Hardware used within the ITSO development environment

We used the following hardware within the ITSO working example development environment for windows: Development node: IBM ThinkCentre M50 (8189-E1U): 1 CPU, Intel Pentium 4, 2.8 GHz 4 GB main memory (2 GB used by host Windows system) 35 GB hard disk 1 IBM Ethernet Adapter Hostname: ganci1.itso.ral.ibm.com
Identity Manager node: VMWare image: 1 CPU, Intel Pentium 4, 2.8 GHz 1024 MB main memory 10 GB hard disk 1 AMD PCNET Ethernet Adapter Hostname: timdev1.itso.ral.ibm.com
Content Management node: VMWare image: 1 CPU, Intel Pentium 4, 2.8 GHz 1024 MB main memory 10 GB hard disk 1 AMD PCNET Ethernet Adapter Hostname: cmdev1.itso.ral.ibm.com
Note: The configurations described above are not necessarily the minimum requirements for the setup; only the values for memory were chosen to be as small as possible.
Chapter 6. Development environment installation
341
6.1.3 Software used within the ITSO development environment

We used the following software levels within the ITSO working example development environment on Windows (see Table 6-1 through Table 6-3).
Table 6-1 Identity Manager node Software Microsoft Windows 2000 Server IBM DB2 UDB, Enterprise Server Edition IBM GSKit IBM Tivoli Directory Server * Server * Client SDK IBM HTTP Server IBM WebSphere Application Server IBM Tivoli Identity Manager Version 2000 + Service Pack 4 8.1.8.762 Note: 8.2 + Fixpack 8 7.0.3.8 5.2 + Fixpack 2
1.3.28 5.1 4.5.1 + FP42 Note: 4.5.1 FP16 full install + FP42
Table 6-2 Content Management node Software Microsoft Windows 2000 Server IBM DB2 UDB, Enterprise Server Edition IBM Tivoli Directory SDK IBM HTTP Server IBM WebSphere Application Server IBM DB2 Content Manager, Enterprise Edition IBM DB2 Content Manager Client for Windows Version 2000 + Service Pack 4 8.1.8.762 Note: 8.2 + Fixpack 8 5.2 + Fixpack 2 1.3.28 5.1.1 8.3 8.3
342
Table 6-3 Development node Software Microsoft Windows or Microsoft Windows IBM Rational Application Developer * Integrated Development Environment * Portal Tools IBM WebSphere Portal Test Environment Note: Includes WebSphere Application Server V5.1 Test Environment IBM Information Integrator for Content Enterprise Edition IBM DB2 UDB, Enterprise Server Edition Note: Alternatively, the DB2 UDB Run-time Client can be used to attach to a remote DB2 UDB Server. IBM Tivoli Identity Manager * API jars Version XP + SP1a or 2000 Professional + SP4 6.0.0.1 Note: 6.0 + Fixpack 6.0.0.1 5.1
8.3 8.1.8.762 Note: 8.2 + Fixpack 8
4.5.1 + FP42
6.1.4 VMWare
Within the development environment, we implemented the Identity Manager and Document Management nodes in VMware images. This allowed for greater flexibility, including the capability to run the Development node (Rational Application Developer, portal tools, WebSphere Portal V5.1 Test Environment) on the same physical system with 4 GB of RAM. Once the images are created, they can be copied to other development systems and run in VMWare network host-only mode with a hosts file to resolve hostnames. This dramatically reduces the development setup time for additional developers in need of this type of environment.
6.2 Identity Manager node installation

The installation of the Identity Manager development node is identical to the installation of the Identity Manager runtime environment. In the development environment we used the hostname timdev1 for the Identity Manager node.
343
Attention: It is important to keep the following information in mind when implementing the Identity Manager node in the development environment: Details on installing the components of the Identity Manager node can be found in 4.5, Identity Management node installation on page 183. Create suffix dc=itso,dc=ibm,dc=com In the development environment, the Tivoli Directory Server on the Identity Manager development node can also be used as the server for the employee directory. This makes it possible to test authentication within the HR and document management applications without installing another directory server. When creating the suffix on the Identity Manager node in the development environment, create the dc=itso,dc=ibm,dc=com so that both Tivoli Identity Manager and the applications can share the directory. The procedure to install the Identity Management node (see 4.5, Identity Management node installation on page 183) includes instructions specific to the development environment.
6.3 Content Management node installation

Within the development environment, the Content Management node is used to develop and test the ITSO custom document management application described in Appendix B, Document management application on page 549. For a detailed procedure on installing the software components of the Content Management node in the development environment, refer to 4.6, Content Management node installation on page 200. In the development environment, we used the hostname cmdev1 for the Content Management node.
6.4 Development node installation

This section describes how to install the components of the Development node required to develop the provisioning portlets, HR and document management applications. In addition, we include references explaining how to configure the WebSphere Portal V5.1 Test Environment to use an LDAP directory within the development environment, which are necessary to develop the applications that share the common LDAP directory.
344
The Development node installation includes the following tasks: 1. 2. 3. 4. 5. 6. IBM Rational Application Developer V6.0 installation WebSphere Portal V5.1 Test Environment installation IBM Rational Application Developer V6.0.0.1 fixpack DB2 Universal Database installation IBM DB2 Information Integrator for Content V8.3 installation Tivoli Identity Manager V4.5.1 API installation
6.4.1 IBM Rational Application Developer V6.0 installation

The purpose of this section is to highlight the key installation considerations and identify components of Rational Application Developer installed while writing this redbook. Updates will be made to Rational Application Developer in 6.4.3, IBM Rational Application Developer V6.0.0.1 fixpack on page 352. Note: For detailed information on the Rational Application Developer V6.0 installation, refer to the following product guides found on CD 1: Installation Guide, IBM Rational Application Developer V6.0 (open install.html in a Web browser). Release note, IBM Rational Application Developer V6.0 (open readme.html in a Web browser). Migration Guide, IBM Rational Application Developer V6.0 (open migrate.html in a Web browser).
Installation considerations
Prior to installing Rational Application Developer V6.0, be aware of the following installation considerations: UNC network shares: Do not install Rational Application Developer from a UNC network share (for example, \\server\shareA). Instead map the network drive to a drive letter (for example, net use x: \\server\shareA) so that the Rational Application Developer installer works properly. Standardize installation path for team development: Standardize the Rational Application Developer installation path for your development team. We found that many files within the projects have absolute paths based on the installation path, thus when you import projects from a team repository such as ClearCase you will get many errors. Installer window in foreground/background: After clicking Rational Application Developer V6.0, sometimes the welcome screen does not appear in the foreground. Simply select the new window from the task list to continue.
345
Rational Application Developer installation

While writing the redbook, we installed IBM Rational Application Developer V6.0 as follows: 1. Start the Rational Application Developer Installer by running launchpad.exe from CD 1. 2. The IBM Rational Application Developer V6.0 components (see Table 6-3) have separate installations from the main Launchpad Base page, as shown in Figure 6-2.
Figure 6-2 IBM Rational Application Developer V6.0 installation components
346
Table 6-4 IBM Rational Application Developer V6.0 description of install components Component Install IBM Rational Application Developer V6.0 Description Core Rational Application Developer sub-components: Integrated Development Environment (required) IBM WebSphere Application Server V6.0 Integrated Test Environment Additional Features: Language Pack Enterprise Generation Language (EGL) Portal Tools Examples for Eclipse Plug-in Development Note: While writing the redbook, we only installed the Portal Tools from the list of Additional Features. IBM WebSphere test environment V5.x Select from the following sub-components: WebSphere Application Server V5.1 WebSphere Application Server V5.0.2 WebSphere Application Server Express V5.1 WebSphere Application Server Express V5.0.2 IBM WebSphere Portal V5.0 test environment IBM WebSphere Portal V5.0 test environment integrated with Rational Application Developer for local testing and debug. IBM Rational Agent Controller is needed for debug on WebSphere Application Server V5.x (capability built-in on V6), and profiling and testing on WebSphere Application Server V6 and V5.x. This feature is for embedded messaging for WebSphere Application Server V5.x. In WebSphere Application Server V6 messaging is built-in. Note: Due to a defect at the time of the Rational Application Developer product release, the ClearCase LT was made available as a Web download with a supporting patch. See Installing IBM Rational ClearCase LT - Technote (open TechNote-Installing_CCLT.html in a Web browser found on CD 1).
Install Agent Controller
Install the embedded messaging client & server
Install Rational ClearCase LT
Install Crystal Enterprise V10 Professional Edition Install Crystal Enterprise V10 Embedded Edition
3. When the Welcome window appears, click Next.
347
4. When the License Agreement window appears, review the terms and, if in agreement, select I accept the terms of the license agreement. Click Next. 5. When the Install Directory window appears, we accepted the default C:\Program Files\IBM\Rational\SDP\6.0 and clicked Next. Important: It is very important that you understand the implication of changing the default installation path. For example, if you plan on team development, we strongly recommend that all developers use the same installation path (such as default), otherwise you will run into problems. We found that many files within the projects have absolute paths based on the installation path, thus when you import projects from a team repository such as ClearCase you will get many errors. 6. When the Select Features window appears, select the appropriate features for your environment. For example, we selected the features displayed in Figure 6-3 for the redbook.
Figure 6-3 Install IBM Rational Application Developer V6.0 Features
348
7. When the Installation Summary window appears, review your selections and click Next to begin copying files as seen in Figure 6-4. Note: The selected features take approximately 2.5 GB of disk space.
Figure 6-4 IBM Rational Application Developer V6.0 Install Summary
The installation can take 30 minutes to 2 hours depending on the processing speed of your system and the features selected. 8. When you see the message, The Installation Wizard has successfully installed IBM Rational Application Developer V6.0, click Next. 9. Uncheck the Launch Agent Controller install checkbox, and then click Finish.
6.4.2 WebSphere Portal V5.1 Test Environment installation

The development tools are installed as part of the base Rational Application Developer installation by selecting the Portal Tools feature. There are a couple of possible scenarios for the portal test environment: IBM WebSphere Portal V5.1 (remote) This option requires IBM WebSphere Portal V5.1 (Express, Enable, Extend Editions) sold separately.
349
IBM WebSphere Portal V5.1 Test Environment (local) The WebSphere Portal V5.1 Test Environment is included with IBM Rational Application Developer V6.0 distribution, however; it is installed via a separate installer found on the WebSphere Portal V5.1 Setup CD. Tip: Eliminate installer prompting of CDs When installing the IBM WebSphere Portal V5.1 Test Environment from a directory or network drive (ensure drive is mapped), create the directory names as listed in Table 6-5 to eliminate the need for the WebSphere Portal installer to prompt for CDs. For example, we created a directory structure on a network drive like the following:
/wp51/setup /wp51/cd1-1 /wp51/cd1-2 /wp51/cd1-15 /wp51/cd2 /wp51/cd3
Table 6-5 IBM WebSphere Portal V5.1 Test Environment CDs IBM WebSphere Portal V5.1 Test Environment CDs included with RAD V6.0 IBM WebSphere Portal V5.1 - Portal Install (Setup) IBM WebSphere Portal V5.1 - WebSphere Business Integrator Server Foundation (1-1) IBM WebSphere Portal V5.1 - WebSphere Business Integrator Server Foundation (1-2) IBM WebSphere Portal V5.1 - WebSphere Business Integrator Server Foundation WebSphere Application Server V5.1 Fixpack 1 (1-15) IBM WebSphere Portal V5.1 - Portal Server (2) IBM WebSphere Portal V5.1 - Lotus Workplace Web Content Management (3) Directory setup cd1-1 cd1-2 cd1-15 cd2 cd3
To install the IBM WebSphere Portal V5.1 Test Environment, do these steps: 1. Run install.bat from the WebSphere Portal Setup CD (or setup directory). 2. When prompted, select the desired language for the install wizard (for example, English) and click OK. 3. When the Welcome page appears, review the information and click Next. 4. When the Software License Agreement appears, if in agreement, select I accept the terms in the license agreement and click Next. 5. When the Choose the setup type that best suits your needs page appears, select Test Environment as seen in Figure 6-5 and then click Next.
350
Figure 6-5 Choose the setup type - Test Environment
6. When prompted, ensure that instances of WebSphere Application Server and WebSphere Portal are not running. Click Next. 7. When prompted to enter the WebSphere Application Server installation directory used by the WebSphere Portal Test Environment, we accepted the default directory (C:\Program Files\Portal51UTE\AppServer). Click Next. Note: This requires approximately 1,650,000 KB of disk space. 8. When prompted to enter the WebSphere Portal installation directory, we accepted the default (C:\Program Files\Portal51UTE\PortalServer). Click Next. Note: This requires approximately 1,550,000 KB of disk space.
351
9. When prompted to enter the WebSphere Portal administrative user and password, we entered the following and then clicked Next: WebSphere Portal administrative user: wpsadmin WebSphere Portal administrative user password: <password> 10.When the WebSphere Portal install options Summary dialog appears, review the selections and click Next. The installation should now begin to copying files. The installation process takes several hours. 11.When the installation is complete, click Finish. Note: The WebSphere Portal installation log can be found in the following directory:
C:\Program Files\Portal51UTE\PortalServer\log\wpinstalllog.txt
6.4.3 IBM Rational Application Developer V6.0.0.1 fixpack

The Rational Product Updater tool is used to apply fixes to IBM Rational Application Developer V6.0. We strongly recommend that you install the 6.0.0.1 fixpack for IBM Rational Application Developer for WebSphere Software V6.0. The 6.0.0.1 fixpack can be installed directly over the Web using the Product Updater tool included with Rational Application Developer, or alternatively the 6.0.0.1 fixpack can be downloaded and installed locally. More detailed information on IBM Rational Application Developer V6.0 can be found at:
http://www.ibm.com/support/docview.wss?rs=2043&context=SSRTLW&dc=D400&uid=swg24 009346&loc=en_US&cs=UTF-8&lang=en
The following procedure describes how to install IBM Rational Application Developer V6.0 using the Product Updater tool: 1. Ensure Rational Application Developer test servers are stopped and Application Developer is closed. 2. Start the Rational Product Updater by clicking Start Programs IBM Rational Rational Product Updater. 3. Click Find Updates as seen in Figure 6-6.
352
Figure 6-6 Rational Product Updater
Note: The Rational Product Updater will detect that a newer version of the Product Updater is available, download it, and restart using the new version. 4. When prompted with a dialog that V6.0.0.1 has been found, click OK. Tip: If the Rational Product Updater tool requires an update, you are prompted to install it before you can continue. The Rational Product Updater installs the update, restarts, and retrieves a list of available updates.
353
5. The IBM Rational Product Updater should be populated with updated fix information. Ensure 6.0.0.1 is checked. Click Install Updates. Tip: Detailed information on the fix is displayed in the right-hand window by selecting the update as shown in Figure 6-7.
Figure 6-7 IBM Rational Application Developer V6.0.0.1 update
354
6. When the License Agreement dialog appears, if in agreement, select I accept the terms in the license agreements, and then click OK to begin the installation. Depending on the speed of your computer processor, the amount of RAM, and the speed of your Internet connection, the update might take an extended period of time to download and install. 7. After the installation is complete, click the Installed Products tab to verify the fix pack was installed successfully. 8. Close the Rational Product Updater.
6.4.4 DB2 Universal Database installation

In the ITSO development environment, the Identity Management and Content Management nodes have IBM DB2 Universal Database V8.2, Enterprise Server Edition installed. The Developer node requires a DB2 UDB Run-time Client as a prerequisite of the DB2 Information Integrator for Content to allow for connectivity to the Content Management node. In addition, the HR application and the WebSphere Portal configuration require DB2 Universal Database Server to be installed locally or on a remote system access using the DB2 Run-time Client. You can either install the IBM DB2 Universal Database V8.2, Enterprise Server Edition on the Developer node, or install the DB2 UDB Run-time Client and catalog remote databases. Our example we chose to install the DB2 UDB Enterprise Server on the Developer node.
DB2 UDB V8.2 Enterprise Server Edition installation

For details, refer to Install DB2 Universal Database V8.2 on page 137.
DB2 UDB V8 Fixpack 8 installation

For details, refer to Install DB2 Universal Database V8 Fixpack 8 on page 139.
6.4.5 IBM DB2 Information Integrator for Content V8.3 installation

IBM DB2 Information Integrator for Content V8.3 is required on the Developer node so that the portal front-end interface of the document management application can access the back-end DB2 Content Manager document repository.
355
For installation details, refer to 4.7.8, Information Integrator for Content V8.3 installation on page 224. Note: Information Integrator for Content needs the DB2 Run-Time Client installed in section 6.4.4, DB2 Universal Database installation on page 355. If the Information Integrator for Content connector is installed first, it will assume that the DB2 Run-Time Client is installed in c:\sqllib.
6.4.6 Tivoli Identity Manager V4.5.1 API installation

The IBM Tivoli Identity Manager V4.5.1 API jars will allow the provisioning portlets to communicate with Tivoli Identity Manager for the provisioning of users. To test the connection from the portlets to Tivoli Identity Manager it is necessary to configure JAAS within the WebSphere Portal v5.1 Test Environment. This is done by configuring the WebSphere Application Server that was installed as part of the WebSphere Portal v5.1 Test Environment installation prior to creating a test environment server within Rational Application Developer. The installation of the Tivoli Identity Manager JAR files and JAAS configuration details can be found in 4.7.9, Tivoli Identity Manager V4.5.1 API installation on page 231.
6.5 Configuration
This section describes the configuration tasks required to integrate the nodes in the development environment in preparation for developing the provisioning portlet application. Although not the focus of this redbook, the environment can be used to develop and test the HR and document management applications.
6.5.1 Configure WebSphere Portal with LDAP

Within the development environment, we need to configure the WebSphere Portal V5.1 Test Environment with the Tivoli Directory Server, such that we can properly develop the applications that share the common LDAP directory.
Configuration considerations
Within the development environment, there are a few steps that are slightly different than the runtime environment: In the development environment, the Identity Manager node Tivoli Directory Server is used by Tivoli Identity Manager as well as the user registry for the applications. In this case, the suffix has already been created.
356
It is not necessary to create a separate user to access the LDAP directory, thus it is not necessary to WebSphere Portal for read-only LDAP access within the development environment. When updating the property values in the wpconfig.properties file, we set LDAPAdminUId value to cn=root to simplify the configuration.
Configure WebSphere Portal with LDAP

We have summarized the steps to configure WebSphere Portal with LDAP in the development environment. For more detailed information, refer to 5.3, Configure WebSphere Portal with LDAP on page 255 with noted considerations. To configure WebSphere Portal with LDAP, do the following steps: 1. Create a suffix. In the development environment, since we are sharing the Tivoli Directory Server for Tivoli Identity Manager and the applications, this step was completed as part of 6.2, Identity Manager node installation on page 343 (dc=itso,dc=ibm,dc=com). 2. Import the LDIF file (wp-itso.ldif) to create users and groups. Modify the userpassword keyword for your environment and import the LDIF file. For details, refer to 5.3.3, Import the LDIF file (wp-itso.ldif) to create users and groups on page 257. 3. Configure WebSphere Portal for LDAP. Update the property values in the wpconfig.properties file and execute the WPSConfig task to configure WebSphere Portal for LDAP based on the settings of the wpconfig.properties file. For details, refer to Configure WebSphere Portal with LDAP on page 357. The wpconfig.properties file can be found in the following directory on Development node:
C:\Program Files\Portal51UTE\PortalServer\config
4. Verify the LDAP configuration. For details, refer to 5.3.5, Verify the LDAP configuration on page 264.
6.5.2 Configure DB2 Content Manager with LDAP

Within the development environment, we need to configure DB2 Content Manager with the Tivoli Directory Server, such that we can properly develop the applications (ITSO custom document management) that share the common LDAP directory. For details, refer to 5.4, Configure DB2 Content Manager with LDAP on page 265.
357
6.5.3 WebSphere Portal V5.1 Test Environment configuration

To configure a WebSphere Portal V5.1 Test Environment within Rational Application Developer, do the following steps: 1. From the Rational Application Developer Workbench, select Window Preferences. 2. Select Server Installed Runtimes. 3. When the Installed Server Runtime Environments dialog appears, select WebSphere Portal v5.1 stub, and then click Edit. 4. When the Edit Server Runtime dialog appears, enter the following information as seen in Figure 6-8 and then click Finish: Name: WebSphere Portal v5.1 WebSphere Portal Location: C:\Program Files\Portal51UTE\PortalServer WebSphere Application Server Location: C:\Program Files\Portal51UTE\AppServer 5. Click OK.
Figure 6-8 Configure the WebSphere Portal V5.1 Test Environment
358
6.5.4 Create a WebSphere Portal V5.1 Test Environment server

To test portlets that access Tivoli Identity Manager within Rational Application Developer, create a test environment server as described next. Important: WebSphere Portal V5.1 runs on WebSphere Application Server V5.1. When a WebSphere Portal V5.1 Test Environment is created, it creates a copy of the WebSphere Application Server V5.1 configuration XML files. We found that with Rational Application Developer V6.0, each time a configuration change was made on the WebSphere Application Server V5.1 server1, we had to create a new WebSphere Portal V5.1 Test Environment server to pick up the changes made in WebSphere Application Server. For example, we were unable to use the WebSphere Application Server Administrative Console within the WebSphere Portal v5.1 Test Environment. When a WebSphere Portal v5.1 Test Environment server is created, it will copy the server1 configuration which was set up in 6.4.6, Tivoli Identity Manager V4.5.1 API installation on page 356. For this reason, make sure that the Tivoli Identity Manager JARs are installed and the JAAS configuration is completed for server1 before creating a WebSphere Portal v5.1 Test Environment server (see 6.4.6, Tivoli Identity Manager V4.5.1 API installation on page 356). Otherwise you will need to create a new WebSphere Portal V5.1 Test Environment server after the configuration. To create a test environment server, follow these steps. 1. On the Developer node, launch the New Server wizard from within Tivoli Access Manager by selecting File New Other.... 2. Select Server Server and then click Next. 3. Select WebSphere Portal v5.1 Test Environment, and click Next. 4. The default port numbers can be used, so click Next. 5. The WebSphere Portal Administrator user ID and password are filled in based on the values used in section 6.4.2, WebSphere Portal V5.1 Test Environment installation on page 349. Re-enter the password, then click Next. Note: When we did not replace the password, we found that the login would fail when the server was started. If the password is not re-entered and a login error occurs when starting the server, the password can be updated in the Portal tab of the server configuration.
359
6. Leave the list of configured projects empty for now and click Finish. 7. Open the server configuration. From the Servers pane in Rational Application Developer, double-click the server name. 8. Navigate to the Ports tab, then to Server Settings, and locate the Orb bootstrap settings box. In the Host Name field, replace localhost with the full host name for the machine as shown in Figure 6-9. Important: The host name cannot be localhost as Tivoli Identity Manager will not be able to respond to requests from localhost.
Figure 6-9 Set ORB bootstrap host name
9. Change to the Portal tab and select Enable base portlets for portal administration and customization. This is needed in order to set up the credential vault during testing. 10.Save and close the server configuration.
360
6.5.5 Tivoli Identity Manager customization

In order to develop and test the provisioning portlets, the Tivoli Identity Manager environment must be configured. There are a few differences to point out in the development environment: The development environment does not include Tivoli Access Manager, thus the Tivoli Access Manager provisioning policy does not need to be configured. We did not configure the DB2 Content Manager, LDAP, or Database policies. Refer to Chapter 9, Tivoli Identity Manager customization on page 411 for details.
361
362
Chapter 7.
TDI connector for Content Manager development

In our working example, we have a requirement of provisioning users from Tivoli Identity Manager to external systems such as DB2 Content Manager. Tivoli Identity Manager does not have an agent to create users in DB2 Content Manager, nor does Tivoli Directory Integrator have a predefined connector to integrate with DB2 Content Manager. In this chapter we describe how to create a custom Tivoli Directory Integrator connector to integrate with DB2 Content Manager with the capability to create, update, and delete users. The chapter is organized into the following sections: Tivoli Directory Integrator connector overview Create the connector class Create the configuration file Compile the connector class Package the connector
363
7.1 Tivoli Directory Integrator connector overview

Tivoli Directory Integrator provides many connectors out-of-the-box for various technologies and systems. In addition, Tivoli Directory Integrator provides the ability to develop custom connectors. The custom connector is packaged as a JAR file containing the Java classes, interfaces, and a configuration file. Once the JAR file is properly installed, the connector can be selected from the Tivoli Directory Integrator connectors list. The configuration information needed for the custom connector is stored in a configuration file. The configuration information indicates the configuration options to be displayed on the Config tab of the connector within Tivoli Directory Integrator.
7.2 Create the connector class

The ITSO example connector uses two different APIs organized in different packages structures: com.ibm.mm.* for the Content Manager API com.ibm.di.* for the Tivoli Directory Integrator API. Any class to be used as a custom connector should implement the interface named ConnectorInterface. The ConnectorInterface defines the methods needed for all the available operations within Tivoli Directory Integrator. The abstract class Connector is also provided with a default implementation of the interface. The custom connectors can easily sub-class it and only override the methods actually needed for a particular scenario. In the ITSO example custom connector, we implemented the methods required for AddOnly, Delete, and Update modes. From the DB2 Content Manager perspective, there is an available API to interact with objects and manage users. In our example custom connector, we used this API to map the received requirements from Tivoli Directory Integrator to the corresponding actions in DB2 Content Manager. Note: For detailed information on the available methods in Tivoli Directory Integrator, refer to Appendix C, Implementing your own Components, in the following product guide, Reference Guide, IBM Tivoli Directory Integrator V6.0, SC32-1720-00.
364
We have included a brief description of the methods implemented for the ITSO example custom connector: public CMConnector() This is the constructor which defines the available modes for the connector. This is achieved by executing the setModes() method, which receives an array of Strings with the desired modes. The values for these modes are defined as constants in the ConnectorConfig interface. In our example we only allow AddOnly, Delete and Update, such that the values used for this operation are ConnectorConfig.ADDONLY_MODE, ConnectorConfig.DELETE_MODE and ConnectorConfig.UPDATE_MODE. public void initialize(Object arg0) This method is called immediately after the constructor, and should perform the initialization actions needed for the connector. In our example, we first read the initialization parameters (database, user, password, connection options), which are entered in the Config tab of the Tivoli Directory Integrator, by using the method getParam(). Next, we establish a connection to the DB2 Content Manager database by using the connect() method from the DKDatastoreICM class. This class internally uses the DB2 Universal Database JDBC drivers for the database connection. As a result, we found necessary to create a driver instance within our code before using the DKDataStoreICM class. This action ensures that the JDBC Driver Manager will have the DB2 Universal Database Type 4 JDBC Driver properly registered. If this action is not taken, the DB2 Content Manager throws an exception because no suitable driver is found. public void putEntry(Entry entry) This method is invoked when receiving an operation in AddOnly mode. The received parameter is an Entry object, which contains the information needed to perform the operation. Inside the Entry object some attributes will be found containing the information sent from the assembly line to the connector. These attributes are instances of the Attribute class, and the names should match to those defined in the Output Map tab of the connector. In our example after obtaining the attributes, we use the DKUserMgmtICM object to perform user management operations in the repository. We create a DKUserDefICM object containing user information, and using the add() method we add the user to Content Manager. It is also necessary to assign the privilege sets for the users to match the Document Management application requirements. In our example, the privilege set used is ClientUserEditSSO. For information about privilege sets, refer to 5.4.6, Create the ClientUserEditSSO privilege sets on page 272.
Chapter 7. TDI connector for Content Manager development
365
For details about using the connector within an assembly line to add users, refer to 8.1.2, Add the cmAdd assembly line on page 375. public Entry findEntry(SearchCriteria searchCriteria) This method is used to find an entry before any update or delete operation is performed. The argument received contains the information about the search criteria to be used in the operation, and it is the responsibility of the connector developer to actually locate the corresponding object using the available methods for its implementation. The SearchCriteria class gives implementations for different kinds of filters (for example, SQL filter, LDAP filter, etc.), which provide a direct translation between the search conditions and the filter format to be applied on each underlying technology. In our example, since no direct translation is provided we choose the Script filter, which allows writing a script within the assembly line to compose the search criteria to be received by the connector. For further details about the script, refer to 8.1.4, Add the cmUpdate assembly line on page 383. The return value of the method is an Entry object containing the corresponding information about the object located in the repository. If the result is not exactly one object our implementation returns null, since only one entry (or none) would be retrieved in our scenario. Some additional considerations may be taken in other scenarios if multiple results are expected. For more detailed information on managing more than one result, refer to the product guide, Reference Guide, IBM Tivoli Directory Integrator V6.0, SC32-1720-00. The returned Entry object will be received as a parameter to the subsequent invocations of the modEntry() and deleteEntry() methods. In our example, we only need the name attribute to locate a user in DB2 Content Manager. Our implementation parses the received search criteria using the format name=value. Any other format will be ignored and no data will be retrieved. To find the user information in DB2 Content Manager, we use the getUserDef() method of the DKUserDefICM class. If the user is not found, a DKNotExistException is thrown. As it is an implementation specific behavior and the exception should not be visible outside our connector, we catch the exception and simply return null. public void modEntry(Entry entry, SearchCriteria searchCriteria) This method is called when running in Update mode to update the user information in the repository. When called, this method first removes the user
366
from every group to which it could be assigned, and then adds the user to the groups received from the assembly line. To retrieve the list of groups for the user the listGroupsForUser() method of DKUserMgmtICM is used. This method returns a dkCollection object, containing references for the groups found. An auxiliary list of group names is created iterating over the collection, and for each name of the list an instance of the group is then retrieved into a dkUserGroupDef object using the method getUserGroupDef(). Please note that this way of processing the groups using an auxiliary list is required to avoid conflicts between the iterator and the groups from which the user is deleted. We found that on each deletion the iterator is modified and the results are unpredictable. The removeUser() method is applied to each group, indicating that the user should be removed from the group. The changes are then committed by executing the update() method of DKUserMgmtICM. For further details about using the connector to modify a user, refer to 8.1.4, Add the cmUpdate assembly line on page 383. public void deleteEntry(Entry entry, SearchCriteria searchCriteria) This method is called when the deletion of an entry is required. An Entry object is received containing the attributes defined in the assembly line, which is the result of the previous findEntry() operation. In our example we called the delUser() method of the DKUserMgmtICM class to delete the user in the DB2 Content Manager repository. For further details about deleting a user, refer to 8.1.5, Add the cmDelete assembly line on page 385.
7.3 Create the configuration file

A configuration file named idi.inf is required to allow the connector customization. This file provides the field names that will be present in the Config tab of Tivoli Directory Integrator. These values can be accessed from the connector using the getParam() method. Note: While writing this redbook, we found that the Users Guide, IBM Tivoli Directory Integrator V6.0, SC32-1718-00 was not updated to include information on customizing the configuration file. For this reason, we referenced another product guide: Chapter 4, Examples under the section Writing a new Raw Connector in the Users Guide, IBM Tivoli Directory Integrator V5.2, SC32-1378-00.
367
In our example we created the following sections in the idi.inf file as part of our development within Rational Application Developer: The connector section of the file indicates the class name of the connector as well as a list of default values for some input fields available in the Config tab of the connector within Tivoli Directory Integrator. The labels for these fields are shown in blue in the Tivoli Directory Integrator Config Editor, as they are inherited from the connector definition. If the original values are changed then their labels are shown in black. Note that we do not provide a default value for the password field. A description for the connector is also provided. The form section includes the title to be displayed in the Config tab, a parameter list and the definition of each parameter. The defined parameters are as follows: database: the database name used by Content Manager. user: the user name for the database connector. password: the password for the database connector. options: any additional options for the connection. In our example we do not need to configure any options; for further information about connection options please refer to the javadoc documentation of the DKDatastoreICM class.
Each parameter in the form section has the following attributes: label: the label to be displayed in the Config tab. syntax: indicates the formatting of the field, in our case string for normal fields and password for not visible fields. description: descriptive text displayed when the mouse pointer rolls over the label.
7.4 Compile the connector class

A Project Interchange File with the source for the ITSO example custom connector is provided in C:\6692code\tdi_cm_connector. To compile the source file classes for the connector, we will need to add the API jar files for both DB2 Content Manager API and Tivoli Directory Integrator API to the project containing the custom connector code.
7.4.1 Import the code into Rational Application Developer

To import the project interchange file into IBM Rational Application Developer V6.0 containing ITSO example Tivoli Directory Integrator custom connector for Content Manager source code, do the following steps:
368
1. Start Rational Application Developer. 2. Select File Import. 3. When the Import Wizard appears, select Project Interchange and click Next. 4. In the Import Projects screen, browse to the c:\6692code\tdi_cm_connector folder and select CMConnectorProjectInterchange.zip. Click Open. 5. Click Select All and then Finish. The CMConnector project will be added to your workspace.
7.4.2 Prepare project to build connector

After importing the custom connector source project, you will need to resolve some errors before compiling. This is accomplished by adding the DB2 Content Manager and Tivoli Directory Integrator API jar files to the project build path. 1. Open the Java perspective Package Explorer view. 2. Select the CM Connector Java project, right-click and select Properties Java Build Path. 3. Select the Libraries Tab. 4. For each one of the JAR entries listed in Table 7-1, select the entry and click Edit. 5. Search the files in the corresponding directories and click Open. The expected locations for the files are shown in Table 7-1. If you are using a development environment and the products are not installed in your computer, copy the jar files into a folder and modify the library entries accordingly.
Table 7-1 Library locations File Location
cmbcm81.jar cmbicm81.jar
miconfig.jar miserver.jar
<cm_home>\lib <cm_home>\lib <tdi_home>\jars <tdi_home>\jars
6. After clicking OK the compilation problems should be resolved.
369
7.5 Package the connector

Once the connector is compiled, we will export the Tivoli Directory Integrator connector class and configuration file in a JAR file. The requirement to install a new connector is that all the needed classes should be in a jar file, which should also include the idi.inf file in its root directory. The jar file should be copied into the <tdi_home>\jars\connectors directory. To export the JAR file for the ITSO example custom connector, do the following steps: 1. Right-click the CM Connector project, and then select Export. 2. Select JAR file from the list and click Next. 3. When the JAR Package Specification dialog appears, check the resources displayed in Figure 7-1, enter C:\CMConnector.jar in the JAR file field, and then click Finish.
Figure 7-1 Export ITSO example custom connector
370
Note: For details on deploying the Tivoli Directory Integrator custom connector for DB2 Content Manager, refer to 11.2, Deploy the TDI connector for Content Manager on page 471.
371
372
Chapter 8.
TDI Assembly Line development

A Tivoli Directory Integrator Config describes a set of components that are linked together to form an integration solution. With the use of a Config, entities such as user accounts can form the basis of integration across systems by mapping the entity attributes that each system understands. In the ITSO identity and access management system, users will be provisioned from Tivoli Identity Manager through Tivoli Directory Integrator to the HR database, employee LDAP directory, and DB2 Content Manager user repository. This section describes the creation of the three Configs that will map the users from Tivoli Identity Manager to these systems. The chapter is organized into the following sections: Develop the DB2 Content Manager Config Develop the database Config Develop the LDAP Config Testing the Configs
373
8.1 Develop the DB2 Content Manager Config

The DB2 Content Manager Config handles events received from Tivoli Identity Manager by transforming the user account information and updating the accounts in DB2 Content Manager. There are three actions that the Config needs to handle: Add users Delete users Update users Each of these actions includes the group assignments for the users, which control their access within DB2 Content Manager. This section describes the creation of a new Config, then adding an event handler, assembly lines, and connectors. The connector created in Chapter 7, TDI connector for Content Manager development on page 363, will be used in this configuration. Note: For more information on Tivoli Directory Integrator concepts, such as the Config, refer to the Users Guide, IBM Tivoli Directory Integrator V6.0, SC32-1718-00, which is available from the online InfoCenter:
http://publib.boulder.ibm.com/infocenter/tiv2help/index.jsp?toc=/com.ibm. IBMDI.doc/toc.xml
8.1.1 Create the DB2 Content Manager Config

To create the Config for DB2 Content Manager, do the following steps: 1. Launch the Config Editor by selecting Start Programs IBM Tivoli Directory Integrator IBM Tivoli Directory Integrator. Alternatively, run ibmditk.bat from the Tivoli Directory Integrator installation directory. 2. Select File New to create a new Config. 3. When the XML Configuration dialog appears, enter itso-cm.xml in the File field, leave the password field blank as seen in Figure 8-1, and then click OK.
374
Figure 8-1 XML Configuration file name
Important: The password field can be left blank if you want to be able to view the xml file with any editor. However, any passwords in the connector configurations will also be visible in plain text. Add a password here to encrypt the file and protect the passwords.
8.1.2 Add the cmAdd assembly line

In this section, one of the three assembly lines for provisioning to DB2 Content Manager is created. Add requests received from Tivoli Identity Manager are used as input to this assembly line, which creates users in the Content Manager user repository. The steps for creating this assembly line are as follows: 1. Select Object New AssemblyLine. 2. In the Please Input Text dialog, enter cmAdd as the name of the assembly line and click OK. The new assembly line will open in the Details Pane on the right-hand side of the Config Editor. 3. Click the Call/Return tab, and then click Initial Work Entry sub-tab. 4. The input to the assembly line will be passed in by an event handler when it launches the assembly line. These are represented by work attributes. The work attributes are added to the work object which is accessible to all connectors within the assembly line.
Chapter 8. TDI Assembly Line development
375
To define the attributes that the cmAdd assembly line expects to receive, do the following steps: a. Click Add a new attribute to the Attribute Map as shown in Figure 8-2.
Figure 8-2 Add work attributes
b. In the dialog that appears, enter $dn as the name of the attribute, then click OK. This is the distinguished name of the user in Tivoli Identity Manager. c. Add the rest of the attributes in the same manner: departmentnumber employeetype eruid
376
5. Click Perform quick discovery of schema to add the work attributes to the Schema pane. The Initial Work Entry tab should now look similar to Figure 8-3.
Figure 8-3 cmAdd initial work entry attributes
377
6. Now add connectors to the assembly line. Click Data Flow. 7. Click the Add component button as shown in Figure 8-4, then select Add new Connector.
Figure 8-4 Add connector
8. Select com.ibm.itso.connector.CMConnector from the list of connector types. This is the connector developed in Chapter 7, TDI connector for Content Manager development on page 363. This will be used to add a user to Content Manager. Here, we are assuming that you have deployed the TDI connector for Content Manager as described in 11.2, Deploy the TDI connector for Content Manager on page 471. 9. Enter addCM in the Name field. 10.Select AddOnly from the Mode drop-down list. 11.The selections are shown in Figure 8-5. Click OK.
378
Figure 8-5 addCM connector
12.Select the addCM connector. The right-hand pane of the Data Flow tab now displays the details of this connector. Select the Config tab and the Connection tab inside it. 13.Fill in the Database name, User, and Password fields with the values needed to connect to Content Manager. The default values for Database name and User can be used if the defaults were used when installing Content Manager. Refer to Figure 8-6.
Figure 8-6 Connector configuration
14.Select the Output Map tab for the addCM connector.
379
15.Add the connector attributes. These are the attributes whose values the connector will use to add a user to Content Manager. For each name in the following list, click the Add a new attribute to the Attribute Map button shown in Figure 8-7, enter the attribute name, and click OK: groups name userDN userPWD
Figure 8-7 Connector attributes
Note: We didnt implement all methods that the connector interface supports. As a result, the buttons for discovering schema attributes cannot be used. 16.The connector expects to receive a list of group names as a string delimited by the | character. This requires an advanced mapping to build the string from the role names passed into the assembly line through the employeetype attribute. Select the groups connector attribute, select the Advanced Mapping check box, and add the script shown in Example 8-1.
380
Example 8-1 Mapping role names to groups connector attribute var roleArray = work.getAttribute('employeetype'); var roleString = "NA"; if (roleArray !=null && roleArray.size()>0) { roleString = roleArray.getValue(0); for (i=1;i<roleArray.size();i++) { var role = roleArray.getValue(i); roleString = roleString + "|" + role; } } ret.value=roleString;
17.The name connector attribute maps to the eruid assembly line attribute. Select name; unselect name in the work entry attributes list; select eruid instead. 18.The userDN needs to contain the fully qualified distinguished name of the employee in the LDAP directory. This links the Content Manager user account back to the directory so that authentication can be performed based on the directory entry instead of the local user account. The userDN is constructed based on the eruid and the parent distinguished name. All users
have the same parent distinguished name, so for simplicity, it is hardcoded here. Select the userDN connector attribute, select Advanced Mapping, then
add the script in Example 8-2.

Example 8-2 Advanced mapping for user dn var deptdn='cn=users,dc=itso,dc=ibm,dc=com'; var uid = "uid="+work.getString("eruid")+","; uid+=deptdn; task.logmsg("user DN: "+uid); ret.value=uid;
19.The Content Manager API requires that the password be set when adding a user account, even if authentication will be performed based on the users LDAP directory entry. For this example, simply set the password to a dummy value since it wont be used for authentication. Select userPWD and Advanced Mapping, then add a line such as that in Example 8-3.
Example 8-3 Dummy password value for local user account ret.value="secret";
20.Save the configuration.
381
8.1.3 Add the ListenForCMUpdates event handler

An event handler running on Tivoli Directory Integrator will receive provisioning requests from Tivoli Identity Manager. The handler will launch the appropriate assembly line whenever it receives a request. In this section, the event handler for the Content Manager Config is created and configured to call the cmAdd assembly line: 1. Select Object New EventHandler. 2. Select ibmdi.DSMLv2EventHandler, enter ListenForCMUpdates as the name, then click OK. The Select EventHandler dialog is shown in Figure 8-8.
Figure 8-8 Create event handler
3. Configure the event handler. Each Config will have an event handler running at the same time, so each event handler must be configured to listen on a different port. This configuration is used during the setup of the Content Manager provisioning policy within Tivoli Identity Manager. For the ITSO identity and access management system example, authentication will not be configured between Tivoli Identity Manager and Tivoli Directory Integrator. Most of the configuration settings can be left with their default values. Set the following configuration values: a. Change the HTTP Port to 8802. b. Add a new naming context. Multiple naming contexts can be added to use different assembly lines based on the distinguished name in the request received. For this example, only one naming context will be used, since all database updates will come from a single source: Tivoli Identity Manager. Click Add/Delete, then enter dc=com and click Add in the dialog box. c. User accounts in Content Manager will be added, updated, and deleted. At this point only the assembly line for adding accounts is complete, so only the AssemblyLine for add parameter can be configured. Select /AssemblyLines/cmAdd from the drop-down list for this parameter. 4. Save the configuration.
382
8.1.4 Add the cmUpdate assembly line

In this section, the second of three assembly lines for provisioning to Content Manager is created. Refer to 8.1.2, Add the cmAdd assembly line on page 375, for more detailed information on creating an assembly line. Create the assembly line which updates users in Content Manager as follows: 1. Create a new assembly line named cmUpdate. 2. Add the following attributes to the Initial Work Entry under the Call/Return tab: employeetype eruid 3. Click Perform quick discovery of schema to add the work attributes to the Schema pane. The Call/Return tab should look like Figure 8-9.
Figure 8-9 Update assembly line initial work entry attributes
4. Add a new connector to the assembly line under the Data Flow tab. Select com.ibm.itso.connector.CMConnector as the connector type, name it updateCM, and put it in Update mode. The selections are shown in Figure 8-10 on page 383. Click OK.
Figure 8-10 Update connector
5. Configure the connection with the Database name, User, and Password values needed to connect to Content Manager. The default values for Database name and User can be used if the defaults were used when installing Content Manager.
383
6. Add connector attributes to the Output Map. These are the attributes whose values will be used by the connector to update a user in Content Manager. Add each of the attributes in the following list: groups name 7. The groups connector attribute needs to be handled the same way as it is in the addCM connector. Add the script in Example 8-1 on page 381 to the Advanced Mapping. 8. The name connector attribute maps to the eruid assembly line attribute. Change the work entry attribute selection from name to eruid. 9. For both connector attributes, uncheck the check box under the Add column as shown in Figure 8-11.
Figure 8-11 Update connector output map
10.Add link criteria to locate the user account in Content Manager that is to be updated. The Content Manager connector expects a filter in the form of name=userId. Select the Link Criteria tab, select Build criteria with custom script, then add the script in Example 8-4.
Example 8-4 Link criteria script var dn = work.getString("$dn"); var end = dn.indexOf(","); //Incoming $dn is "eruid=..." so replace "eruid" with "name" var filter = "name"+dn.substring(5,end); task.logmsg('filter: ' + filter); ret.filter = filter;
384
11.Add the assembly line to the event handler. Set the AssemblyLine for modify parameter to /AssemblyLines/cmUpdate. Note: You may need to close the event handler in the Config Editor and reopen it before the cmUpdate connector appears in the drop-down list. 12.Save the configuration.
8.1.5 Add the cmDelete assembly line

In this section, the third of three assembly lines for provisioning to Content Manager is created. Refer to 8.1.2, Add the cmAdd assembly line on page 375, for more detailed information on creating an assembly line. Create the assembly line which deletes users from Content Manager as follows: 1. Create a new assembly line named cmDelete. 2. Add the following attribute to the Initial Work Entry under the Call/Return tab: eruid 3. Click Perform quick discovery of schema to add the work attribute to the Schema pane. 4. Add a new connector to the assembly line under the Data Flow tab. Select com.ibm.itso.connector.CMConnector as the connector type, name it deleteCM, and put it in Delete mode. The selections are shown in Figure 8-10. Click OK.
Figure 8-12 Delete connector
5. Configure the connection with the Database name, User, and Password values needed to connect to Content Manager. The default values for Database name and User can be used if the defaults were used when installing Content Manager.
385
6. Add link criteria to locate the user account in Content Manager that is to be deleted. The Content Manager connector expects a filter in the form of name=userId. Select the Link Criteria tab, select Build criteria with custom script, then add the script used for the updateCM connector in Example 8-4 on page 384. 7. Add the assembly line to the event handler. Set the AssemblyLine for delete parameter to /AssemblyLines/cmDelete. Note: You may need to close the event handler in the Config Editor and reopen it before the cmUpdate connector appears in the drop-down list. 8. Save the configuration.
8.2 Develop the database Config

The database configuration updates employee records in the HR database. Based on the use cases, a record will be created in the database before provisioning user accounts, so there is no need to implement an assembly line to add new users. When an employee leaves the company, the employee record needs to be kept, so it is also unnecessary to create an assembly line to delete records from the database. This section describes the creation of the Config for updating the database.
8.2.1 Create the database Config

Launch the Config Editor and create a new Config named itso-hr.xml following the same procedure described in Create the DB2 Content Manager Config on page 374.
8.2.2 Add the dbUpdate assembly line

In this section, one assembly line is created. The steps for creating the assembly line which updates user records in the database are as follows: 1. Select Object New AssemblyLine. 2. In the Please Input Text dialog, enter dbUpdate as the name of the assembly line and click OK. The new assembly line will open in the Details Pane on the right-hand side of the Config Editor. 3. Click the Call/Return tab, then the Initial Work Entry sub-tab.
386
4. Describe the attributes that are to be passed in by the event handler. The definition of which attributes are passed to the event handler is governed by the provisioning policy created in 9.7.2, Create the DB2 Universal Database Provisioning Policy on page 436. Click Add a new attribute to the Attribute Map for each of the following attributes and enter the name listed: departmentnumber mail employeeNumber givenname homePostalAddress sn eruid
5. Click Perform quick discovery of schema to add the work attributes to the Schema pane. The Initial Work Entry tab should now look similar to Figure 8-13.
Figure 8-13 Database assembly line initial work entry attribute map
6. Switch to the Data Flow tab. 7. Click the Add component button and select Add new Connector. 8. From the list of connector types, select ibmdi.JDBC. This will be used to connect to the HR database.
387
9. Enter updateDB2 in the Name field. 10.Select Update from the Mode drop-down. 11.The selections are shown in Figure 8-14. Click OK.
Figure 8-14 Database update connector
12.After adding the connector, select Flow updateDB2, then select the Config tab and the Connection sub-tab. This may already be selected automatically after creating the connector. 13.Fill in the connection parameters as described below: JDBC URL: jdbc:db2://wpwin1.itso.ral.ibm.com:50000/HR Username: admin Password: <password> Schema: sstdb1 JDBC Driver: com.ibm.db2.jcc.DB2Driver 14.Click the Select button beside the Table Name field. 15.If the connection parameters are correct, a dialog should open with a drop-down list of table names to choose from, as shown in Figure 8-15. Select the UPEMP (employee table) and click OK.
Figure 8-15 Database table selection dialog
16.Select the Output Map tab for the updateDB2 connector. 17.Click the Connect to datasource button.
388
18.Click the Discover the schema of the datasource button. This will add each column in the UPEMP table to the schema as an attribute. 19.Drag the following names from the schema to the connector Attribute Map on the left pane of the Output Map tab: DEPTNUMBER EMAIL EMPLOYEENUMBER FIRSTNAME HOMEADDRESS1 LASTNAME SHORTNAME STATE
These are the columns that will be updated in the database by this connector. 20.Since database records only need to be updated, uncheck the Add column for each attribute in the Attribute Map. 21.The output attributes need values. Most of these values come directly from the assembly lines work object. When an attribute is selected in the left-hand pane of the Output Map, the right-hand pane shows how the value is populated. Associate the output attribute with the work attribute by selecting the checkbox for the work attribute in the right-hand pane of the Output Map. By default when an attribute is selected the work attribute pane will show the same attribute name in red and it will be checked. For all but the STATE attribute, do the following steps: a. Select the attribute in the attribute map. b. Uncheck the attribute of the same name in the work attribute pane. The name will be in a red font. c. Check the corresponding work attribute as defined in step 4 on page 387. The STATE attribute in the HR database identifies whether the employee record is for an active, retired, or terminated employee. For this example well assume that updates are only provisioned for active employees. Extending the example to handle changes in employee STATE is left as an exercise. Hardcode the STATE attribute to the active state: a. Select the STATE attribute. b. Select the Advanced Mapping checkbox. c. Enter ret.value = 1; in the text box that appears. Once complete, the Output Map should look similar to Figure 8-16.
389
Figure 8-16 Database connector output map
22.Select the Link Criteria tab for the updateDB2 connector. This tab defines how to select the database records that will get updated when the connector is called. 23.The record to be updated will be found by looking for the user ID if it is provided, or the employee number. Select Build criteria with custom script, then add the following script (Example 8-5).
Example 8-5 Link criteria for database connector // $dn will always be passed in by Tivoli Identity Manager, // so use the uid as the shortname to lookup the employee. // This relies on the design of the uid being the same as the // shortname in the database and the uid being unique. var dn = work.getString("$dn"); var comma = dn.indexOf(',');
390
var equalSign = dn.indexOf('='); var shortname = dn.substring(equalSign+1,comma); var newfilter = 'shortname=\''+shortname+'\''; // New employees only have an employee number, not a shortname // in the database, so also look at the employee number. var empNum = work.getString('employeenumber'); if (empNum!=null) newfilter += ' or employeenumber=' + empNum; task.logmsg("employee record filter: "+newfilter); ret.filter = newfilter;
24.Save the configuration. For example, select File Save.
8.2.3 Add the ListenForDBUpdates event handler

User information provisioned from Tivoli Identity Manager will be received by an event handler that is always running on the Tivoli Directory Integrator server. The event handler will launch the dbUpdate assembly line whenever it receives an update. Add the event handler to the database Config as follows: 1. Select Object New EventHandler. 2. Select ibmdi.DSMLv2EventHandler, enter ListenForDBUpdates as the name, then click OK. The Select EventHandler dialog is shown in Figure 8-17.
Figure 8-17 Database event handler dialog
3. Configure the event handler. Each Config will have an event handler running at the same time, so each event handler must be configured to listen on a different port. This configuration is used during the setup of the database provisioning policy within Tivoli Identity Manager.
391
For the ITSO identity and access management system example, authentication will not be configured between Tivoli Identity Manager and Tivoli Directory Integrator. Most of the configuration settings can be left with their default values. Set the following configuration values: a. Change the HTTP Port to 8801. b. Add a new naming context. Multiple naming contexts can be added to use different assembly lines based on the distinguished name in the request received. For this example only one naming context will be used since all database updates will come from a single source: Tivoli Identity Manager. Click Add/Delete, then enter dc=com and click Add in the dialog box. c. Database records will only be updated so only one assembly line is needed. However, accounts will be added and updated in Tivoli Identity Manager so provisioning will include add and update requests. The event handler needs to receive both types of request, so both the AssemblyLine for add and AssemblyLine for modify settings need to be configured. Select /AssemblyLines/dbUpdate from thedrop-down list for both. 4. Save the configuration.
8.2.4 Assembly line for deleting entries

When developing the assembly lines and provisioning policies, it can be useful to be able to delete employee database entries even though this functionality wont be used in the runtime environment. The database Config provided with this book includes a dbDelete assembly line that will delete entries from the database. The assembly line contains a JDBC connector in Delete mode. The script in the link criteria locates the entry to be deleted based on the databases shortname attribute and the distinguished name passed in from Tivoli Identity Manager.
8.3 Develop the LDAP Config

The LDAP configuration adds, updates, and deletes employee account entries in the employee directory. Access to portlets is defined within WebSphere Portal using LDAP groups. The LDAP configuration will map roles defined for the user within Tivoli Identity Manager to LDAP groups in the employee directory. To keep it simple, there is a one-to-one mapping between roles and groups. This section describes the creation of the Config for updating the employee directory. Not all areas will be described in detail since they are similar to the creation of the other Configs. Refer to 8.1, Develop the DB2 Content Manager Config on page 374 for more information.
392
8.3.1 Create the LDAP Config

Launch the Config Editor and create a new Config named itso-ldap.xml following the same procedure described in 8.1.1, Create the DB2 Content Manager Config on page 374.
8.3.2 Add the ldapUpdate assembly line

The ldapUpdate assembly line adds and updates entries in the employee directory. The steps for creating the ldapUpdate assembly line are: 1. Create a new assembly line named ldapUpdate. 2. Add the following attributes to the Call/Return Initial Work Entry list of work attributes: $dn cn givenname sn departmentnumber employeenumber employeetype erpassword telephonenumber mail title postaladdress street st postalcode homepostaladdress manager eruid
Note: An attribute is needed to pass a list of names of the roles that the employee is assigned. These role names will be mapped to LDAP groups. Rather than extend the Tivoli Identity Manager schema for the Person object, an unused attribute, employeetype, is reused for this purpose.
393
3. Click Perform quick discovery of schema to add the work attributes to the schema pane. 4. Switch to the Data Flow tab and add a new connector of type ibmdi.LDAP, with name updateLDAP, in Update mode, as shown in Figure 8-18.
Figure 8-18 LDAP update connector
5. Fill out the connection configuration for the new connector with the following information: LDAP URL: ldap://tdiwin1.itso.ral.ibm.com:389 Login username: cn=root Login password: secret Search Base: dc=itso,dc=ibm,dc=com Search Filter: uid=* Check Detailed Log 6. Select Output Map and click the Perform quick discovery of schema button. This will add some of the most important LDAP attributes to the schema pane, as shown in Figure 8-19. However, it does not add all the attributes that are to be updated in the employee directory.
394
Figure 8-19 Quick discovery of schema
7. In the schema pane, click Connect to the data source. If the configuration is correct, this will connect to the LDAP directory and display a Connection established message as shown in Figure 8-20. 8. Click the Discover the schema of the data source button. It will take a few seconds to add all the schema attributes.
395
Figure 8-20 Connection established
9. There are more attributes in the schema than will be updated through Tivoli Identity Manager provisioning. Select the following attributes and drag them to the work attributes pane as shown in Figure 8-21: $dn cn departmentNumber employeeNumber givenName homePostalAddress mail manager o objectClass ou postalAddress postalCode sn st street telephoneNumber title uid userPassword
396
Figure 8-21 Connector work attributes
Note: Depending on the window size, the schema pane may have a vertical scroll bar. If the attribute list is long enough, it will have its own vertical scroll bar. If the pane is small enough that a horizontal scroll bar appears, the scroll bar for the attribute list will not be visible unless the horizontal scroll bar is moved to the right (see Figure 8-22).
Figure 8-22 Schema pane scroll bars
397
10.Some of the attributes cannot be directly passed from Tivoli Identity Manager to the employee directory. They need to be mapped or modified to the format expected in the directory. a. The $dn attribute is required by the LDAP connector. Since the assembly line handles both add and update, it is necessary for the current $dn value to be used if it exists. If it does not exist, then it needs to be generated. As mentioned previously, the work object represents the attributes within the assembly line. Another object used in this code is the current object. The current object contains the attributes of the entry that the connector found in the employee directory based on the link criteria. For more information on these objects, refer to the information on the global Entry object instances within the Reference Guide, IBM Tivoli Directory Integrator V6.0, SC32-1720-00 available at:
http://publib.boulder.ibm.com/infocenter/tiv2help/index.jsp?toc=/com.ibm .IBMDI.doc/toc.xml
Select the $dn work attribute and create an Advanced Mapping with the JavaScript provided in Example 8-6.
Example 8-6 JavaScript for $dn var incomingDN = work.getString("$dn"); var end = incomingDN.indexOf(","); var begin = incomingDN.indexOf("=")+1; var outgoingDN = "uid=" + incomingDN.substring(begin,end) + ","; var newUID = work.getString("eruid"); if (newUID!=null) { var genDN = "uid=" + work.getString("eruid") + ","; task.logmsg("generated DN: "+ genDN); outgoingDN = genDN; } var deptdn='cn=users,dc=itso,dc=ibm,dc=com'; outgoingDN += deptdn; task.logmsg('check for a current $dn'); if (current!=null) { var currentId = current.getString("$dn"); if (currentId!=null) { task.logmsg('found a $dn'); outgoingDN=currentId; } }
398
task.logmsg('using dn: ' + outgoingDN); ret.value = outgoingDN;
Note: To simplify this example, the parent distinguished name is hardcoded. The employee directory tree could have been designed to allow a dynamic lookup of the appropriate parent distinguished name based on the department number. b. The cn attribute is another mandatory attribute for the LDAP connector. An advanced mapping will be used to set its value. For this example, if a new cn value isnt passed to the assembly lines work object, then it will be built by combining the givenname and sn attributes from the work object or the current object. The code is provided in Example 8-7.
Example 8-7 Advanced mapping for cn attribute var newCN = work.getString("cn"); if (newCN==null) { //If no cn provided, use firstname + lastname var firstname = work.getString("givenname"); if (firstname==null) { firstname = current.getString("givenname"); if (firstname==null) firstname=""; } var lastname = work.getString("sn"); if (lastname==null) { lastname = current.getString("sn"); if (lastname==null) lastname=""; } if (firstname!=null || lastname!=null) { newCN=firstname + " " + lastname; } } ret.value = newCN;
399
c. The objectClass attribute is also required for the LDAP connector. Since all the entries being added to the directory by this connector are employee entries, the value can be hardcoded to inetOrgPerson as shown in Figure 8-23.
Figure 8-23 Objectclass advanced mapping
d. For the mandatory surname attribute, sn, if a new value isnt passed to the assembly line, then the current sn will be used. When the employee is first provisioned to the employee directory, it is assumed that the sn will be provided so additional code isnt needed to create a value based on other attributes. Add the advanced mapping script in Example 8-8 to the sn attribute.
Example 8-8 Advanced mapping for sn var newSN = work.getString("sn"); if (newSN==null) { newSN=current.getString("sn"); } ret.value = newSN;
e. For attributes that are mapped to the assembly lines initial work entry (Call/Return tab) under a different name than the connector discovered from the actual LDAP directory schema, the default mapping in the connector must be updated. This is the case for the connectors userPassword attribute which must be mapped to the erpassword attribute from the initial work entry. Select userPassword, then in the schema pane unselect userPassword and select erpassword. The proper selection is shown in Figure 8-24. Likewise, uid must be mapped to eruid.
400
Figure 8-24 Mapping userPassword
11.The Link Criteria needs to locate the appropriate directory entry based on the user Id. The user Id is obtained by parsing the $dn attribute value passed in by Tivoli Identity Manager. The user Id is then used to search the directory for a matching value in the uid attribute. Add the JavaScript in Example 8-9 to the connectors Link Criteria.
Example 8-9 Link criteria for LDAP connector var dn = work.getString("$dn"); //$dn starts with eruid=<userId>, var end = dn.indexOf(","); var filter = dn.substring(2,end); //result is uid=<userId> task.logmsg('add/modify user filter: ' + filter); ret.filter = filter;
12.The ldapUpdate assembly line can now update employee entries in the directory. Part of updating the employee entries also includes updating the employee group memberships. This will be added later. For now, save the configuration.
8.3.3 Add the ldapGroupUpdate assembly line

The ldapGroupUpdate assembly line handles the addition and removal of an employee from groups within the employee directory. Whenever an employee is updated the group membership is updated to match the roles assigned to that employee within Tivoli Identity Manager. Since it is an employee update that triggers the assembly line, it is not obvious which roles have been added or removed from the employee, so a script is used to check the entire list of roles against the group memberships in the LDAP directory: 1. Create a new assembly line named ldapGroupUpdate.
401
2. Add the following attributes to the Call/Return Initial Work Entry list of work attributes: roles uniquemember 3. Click Perform quick discovery of schema to add the work attributes to the schema pane. 4. Each assembly line has a limit to the number of entries that a connector will return. Since this assembly line needs to go through all the groups, set the limit to value comfortably larger than the number of groups. Select the Config tab. Enter 50 in the Max duplicate entries returned field. Note: By default, the Max duplicate entries field is empty. However, the implied value is 10. It can be set to 0 for an unlimited number of entries, but this isnt recommended due to the potential for scalability problems. 5. Switch to the Data Flow tab and add a new connector of type ibmdi.LDAP, with name updateGroups, in Lookup mode. 6. The connector configuration is similar to the configuration for the updateLDAP connector. The only difference is the search filter which needs to locate groups instead of user entries in the directory. The filter is (objectclass=groupofuniquenames). Refer to Figure 8-25 for the configuration values.
Figure 8-25 Group connector configuration
7. Select the Input Map tab and click the Perform quick discovery of schema button.
402
8. Only three attributes need to be retrieved from the group directory entries. From the list of schema attributes discovered, drag the following attributes to the work attributes pane: $dn cn uniquemember The input map is shown in Figure 8-26.
Figure 8-26 Group connector input map
9. The link criteria is simpler for this connector since all groups will be retrieved. Select the Link Criteria tab, then click the Add new Link Criteria button. 10.From the Connector Attributedrop-down list, select $dn, type $dn in the Value entry field as shown in Figure 8-27, then click OK.
Figure 8-27 Group connector $dn link criteria
403
11.Add another link criteria in the same manner for connector attribute objectclass, with value groupofuniquenames. This matches the search filter defined in the configuration. These link criteria will cause the connector to retrieve all groups in the employee directory. The completed link criteria are shown in Figure 8-28.
Figure 8-28 Group connector complete link criteria
12.The other connectors in this book operate on a single entry that matches the link criteria. This connector needs to operate on multiple entries since the link criteria will return all the groups that have been defined. The Hooks tab contains a hook called On Multiple Entries that is used to handle this situation. It is in this hook that the groups will be updated to match the employees role assignments. The script makes use of thisConnector, which is the object for the connector that the script is running in. It has methods getFirstDuplicateEntry and getNextDuplicateEntry for cycling through all the entries that match the link criteria. The LDAP connector also provides methods to interact with directory entries. The thisConnector.connector instance of the LDAP connector makes use of some of these methods to update group membership. It compares the value of the uniquemember attribute with a specific group directory entry to determine if the employee belongs to the group. It also adds and removes uniquemember attribute values for a group directory entry. For each group, the cn of the group is compared with the list of role names that are assigned to the employee. If it is in the list, then the employee needs to be a member of that group. The code then checks whether the employees distinguished name is in the set of uniquemember values for the group. If the employee is not already in the group, then the employee is added. If the group does not match a role name, then the employee should not be in the group. A comparison is done to see if the employee is currently a member. If a match is found, then the employee is removed from the group.
404
Select the Hooks tab, then select DataFlow (Lookup) Lookup On Multiple Entries and add script in Example 8-10.
Example 8-10 Group membership update code var myEntry=thisConnector.getFirstDuplicateEntry(); var roles = work.getAttribute("roles"); var uniqueMbr = work.getString("uniquemember"); while (myEntry != null && roles != null) { var thisGroup = myEntry.getString("cn"); task.logmsg('** Check membership for group: ' + thisGroup); var value=null; for(i=0;i<roles.size();i++) { if (thisGroup.equalsIgnoreCase(roles.getValue(i))) { value=uniqueMbr; } } var grpDN = myEntry.getString("$dn"); if (value==null) { if (thisConnector.connector.compare(grpDN,"uniquemember",uniqueMbr)) { task.logmsg("*** Removing uniquemember attribute value "+uniqueMbr+" from " + grpDN +" ***"); thisConnector.connector.removeAttributeValue(grpDN,"uniquemember",uniqueMbr); } } else { if (!thisConnector.connector.compare(grpDN,"uniquemember",uniqueMbr)) { task.logmsg("*** adding uniquemember attribute value "+uniqueMbr+" to " + grpDN +" ***"); thisConnector.connector.addAttributeValue(grpDN,"uniquemember",uniqueMbr); } } myEntry = thisConnector.getNextDuplicateEntry(); }
13.Save the configuration.
405
8.3.4 Update groups from within the ldapUpdate assembly line

In this section the ldapUpdate assembly line is modified to call the ldapGroupUpdate assembly line. With this change, every time an employees role is modified, the group memberships will be updated in the employee directory. 1. Open the ldapUpdate assembly line, and add a function component to it. To do this, click the Add component button within the assembly lines Data Flow tab, then select Add function component from the menu that pops up. 2. In the dialog, select ibmdi.AssemblyLineFC, enter fcGroupUpdate as the name, and click OK. Refer to Figure 8-29.
Figure 8-29 Function component
3. Select the Config tab for the fcGroupUpdate function component. 4. From the AssemblyLine drop-down list, select /AssemblyLines/ldapGroupUpdate. 5. Select the Output Map tab, then click the Perform quick discovery of Function Schema button. 6. Select the two attributes in the schema pane and drag them to the connector attribute pane. The Output Map should now look like Figure 8-30.
406
Figure 8-30 Function component output map
7. Select the roles connector attribute, deselect the roles attribute in the work entry attributes list in the right-hand pane, then select the employeetype attribute. This will make the roles attribute passed to the ldapGroupUpdate assembly line contain the employeetype attribute values from the ldapUpdate assembly line. 8. The uniquemember attribute needs to contain the distinguished name for the employee as it exists within the employee directory. This requires an advanced mapping script to create the value. Add the script in Example 8-11 to the Advanced Mapping for uniquemember.
Example 8-11 Advanced mapping for uniquemember var dn = work.getString("$dn"); var end = dn.indexOf(","); var parentDN=""; //All users have the same parent DN parentDN='cn=users,dc=itso,dc=ibm,dc=com'; var mbr = dn.substring(2,end) + "," + parentDN; task.logmsg('function component uniquemember: ' + mbr); ret.value=mbr;
Note: Just like the script in Example 8-6, the parent distinguished name is hardcoded for simplicity in this example. 9. Save the configuration.
407
8.3.5 Add the ListenForLDAPUpdates event handler

Creation of an event handler is detailed in 8.2.3, Add the ListenForDBUpdates event handler on page 391. Create an ibmdi.DSMLv2EventHandler event handler named ListenForLDAPUpdates for the LDAP Config with the following configuration values: HTTP Port: 8803 Naming Context: dc=com AssemblyLine for add: /AssemblyLines/ldapUpdate AssemblyLine for modify: /AssemblyLines/ldapUpdate Also, append erpassword to the end of the comma-delimited list of attributes in the Binary Attributes field. Important: The password is sent by Tivoli Identity Manager to the event handler in binary form. The event handler must be configured to accept the erpassword attribute in binary form. Without this configuration change the password added to the LDAP directory will be corrupted and users will not be able to login to WebSphere Portal. Save the configuration.
8.3.6 Assembly line for deleting entries

In the runtime environment for this example, employee entries are not deleted from the employee directory. When an employee is terminated, the accounts in Tivoli Identity Manager are suspended only. However, when developing the assembly lines and provisioning policies it can be useful to also be able to delete LDAP accounts. The LDAP Config provided with this book includes an ldapDelete assembly line which will delete entries from the directory. The assembly line contains an LDAP connector in Delete mode. The script in the link criteria locates the entry to be deleted based on the distinguished name passed in from Tivoli Identity Manager. Refer to the Config for full details. Note: For details on deploying the TDI configuration to a runtime environment, refer to 11.3, Deploy the TDI configuration files on page 472.
408
8.4 Testing the Configs

The assembly lines and their use of the connectors can be tested within the Config Editor by hard coding values and running the assembly line. However, to fully test the configuration, it is better to run the event handlers and trigger events from within Tivoli Identity Manager. This establishes confidence that the proper attributes can be provisioned from Tivoli Identity Manager through to the back-end system. In order to test the Tivoli Directory Integrator configuration files from Tivoli Identity Manager, it is first necessary to set up the Tivoli Identity Manager environment. Follow the steps in these sections to prepare the Tivoli Identity Manager server: Section 9.1, Create Identity Manager Services on page 412 Section 9.2, Create Organizational Units and Persons on page 415 Section 9.3, Create and Grant Organizational Roles on page 419 Section 9.4, Modify the user interface on page 421 Within the Tivoli Directory Integrator Config Editor, run the event handler to be tested. The event handler will launch the assembly line when it receives an event. Also make sure the back-end system is available for the connectors to connect to. Next create the Tivoli Identity Manager provisioning policy associated with the Tivoli Directory Integrator configuration that you wish to test: Section 9.7.2, Create the DB2 Universal Database Provisioning Policy on page 436 Section 9.7.3, Create the Tivoli Directory Server Provisioning Policy on page 440 Section 9.7.4, Create the DB2 Content Manager Provisioning Policy on page 444 Note: When the policy is created, it will be enforced for any existing users that match the membership setting for the policy. To make it easier to test the provisioning of individual users, set the policy membership to one role rather than multiple roles or All(*) users. Then a user can be provisioned and deprovisioned by adding and removing the role from the user. At this point, tests can be performed by working within the Tivoli Identity Manager client as the administrator (for example: itim manager):
409
The add assembly line is triggered whenever a new Person is created in Tivoli Identity Manager that matches the policy membership criteria. If membership is for a specific role, then assigning that role to an existing user will also trigger the add assembly line. The modify assembly line is triggered when any of the attributes specified in the provisioning policy are updated on the Person. The delete assembly line is triggered by deleting the Person, including accounts or by modifying the Person to make the provisioning policy no longer apply. The latter approach is easier for assembly line testing since it removes the need to repeatedly fill in attributes for the user. For example, if the policys membership is defined for a single role, then removing that role from the Person will trigger the delete assembly line. Note: The provisioning of a user creates an account for that user within Tivoli Identity Manager. For this example, the provisioning policies are set up to use the attributes from the Person object within Tivoli Identity Manager to populate the users account attributes. It isnt necessary to manipulate the individual accounts because, for this example, Tivoli Identity Manager is configured to handle the accounts automatically. Each service for this example is set to correct non-compliance and the policys attributes are marked mandatory. This causes the policy to be enforced after updates are made on the Person object as outlined above. Each change submitted for the Person will generate a request within Tivoli Identity Manager. View the request to verify that it completed successfully or to diagnose errors communicating with Tivoli Directory Integrator. Look at the assembly line logging output in the Config Editor to track the processing of the received request from the event handler through to the final connector. Then check the back-end system directly to verify that the user is properly provisioned.
410
Chapter 9.
Tivoli Identity Manager customization

This chapter describers how to customize the default Tivoli Identity Manager installation to meet the specific requirements of the ITSO example scenario. The customization of Tivoli Identity Manager includes the creation of several Tivoli Identity Manager components such as Services and Persons, as well as modifying some of the components that are already created by the default installation. This chapter is organized into the following sections: Create Identity Manager Services Create Organizational Units and Persons Create and Grant Organizational Roles Modify the user interface Create the Password Policy Create Workflows Create Identity Manager Provisioning Policies
411
9.1 Create Identity Manager Services

This section describes the procedure to add new service profiles and the creation of services in Tivoli Identity Manager. Tivoli Identity Manager service is the interface to communicate with a managed resource such as an LDAP server. Service profile consists of a set of files that describe the Tivoli Identity Manager service and the accounts managed by that service. Before creating a new service in Tivoli Identity Manager, the corresponding service profile must be installed. This section includes the following tasks: 1. Add Service Profiles 2. Create Services 3. Modify Services
9.1.1 Add Service Profiles

For the ITSO working example, we need to add three service profiles to the default Tivoli Identity Manager installation on the Identity Manager node. The configuration files required for these service profiles are included in the ITSO sample code c:\6692code\config\tim_serviceprofiles directory: 1. Execute the following tasks to add a new service profile called dsml2ldapservice: a. Login to the Identity Manager node as administrator. b. Navigate to the c:\itim45\data\remote_resources directory, and create dsml2ldapservice directory. c. Copy all the files from sample code directory c:\6692code\config\tim_serviceprofiles\dsml2ldapservice to the directory c:\itim45\data\remote_resources\dsml2ldapservice. d. Ensure that the following WIndows services are running on the Identity Manager node: IBM WebSphere Application Server V5 - server1 IBM Tivoli Directory Server V5.2
e. Open a Windows command prompt window and navigate to the directory c:\itim45\bin\win. f. Add the dsml2ldapservice service profile by executing the following command:
config_remote_services dsml2ldapservice
When it completes, it will display the following message:

[main] dsml2ldapservice profile successfully installed
412
2. Using the above procedure, add the following two service profiles on the Identity Manager node: config_remote_services dsml2db2service config_remote_services dsml2CMservice 3. Restart the following Windows services: IBM WebSphere Application Server V5 - server1 IBM Tivoli Directory Server V5.2
9.1.2 Create Services

The service definition in Tivoli Identity Manager contains the necessary details to communicate with the Tivoli Identity Manager agent software running on the managed resource. In our runtime environment, we have used Tivoli Directory Integrator to develop custom agents to manage accounts in DB2, Tivoli Directory Server and DB2 Content Manager. Using the procedure outlined in Tivoli Access Manager service configuration on page 199, create the following services in Tivoli Identity Manager. DB Service: Specify the following parameters while creating the service Service Type: dsml2db2service Service Name: DB Service URL: http://<tdiwin1_IP_Address>:8801 UserId: admin Password: <password> Naming Context: dc=com
CM Service: Specify the following parameters while creating the service Service Type: dsml2CMservice Service Name: CM Service URL: http://<tdiwin1_IP_Address>:8802 UserId: admin Password: <password> Naming Context: dc=com
Chapter 9. Tivoli Identity Manager customization
413
LDAP Service: Specify the following parameters while creating the service Service Type: dsml2ldapservice Service Name: LDAP Service URL: http://<tdiwin1_IP_Address>:8803 UserId: admin Password: <password> Naming Context: dc=com
9.1.3 Modify Services

This section describes the procedure to modify the services that were created in the previous section. 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click PROVISIONING. 3. Click the ITSO organization tree. It will display a list of services that were created earlier. 4. Modify the CM Service. a. Click CM Service. It will display CM Service Menu. b. Click Policy Enforcement. c. The Service Policy Enforcement page will be displayed. Select Correct Noncompliance from the drop-down menu of Enforcement Action. Click Submit. d. When it displays the dialog, The process will change compliance of accounts, click OK. e. When you return to the Service Policy Enforcement page, click Submit. f. When you return to the CM Service Menu page, click Back to list of services. 5. Repeat the process to modify the DB Service and LDAP Service.
414
9.2 Create Organizational Units and Persons

This section describes how to create Organizational Units and Person entities in Tivoli Identity Manager required for the ITSO example scenario.
9.2.1 Create Organizational Unit

To create the Organizational Unit in Tivoli Identity Manager, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click MY ORGANIZATION. 3. Click the ITSO organization tree. 4. From the left hand side navigation bar, click Manage Organizational Units. 5. It opens the Add | Modify | Delete Organizational Unit(s) page. Click Add to add new Organizational Unit. 6. We specified the following details on the Add | Modify Organizational Unit page as shown in Figure 9-1. a. Enter HRD10 in the Organizational Unit Name field. b. Click Search located in the Supervisor section of the page. c. Enter admin on the Search form and click Search. d. Select System Administrator, and then click Add. e. Click Done. 7. When you return to the Add | Modify Organizational Unit page, click Submit. When you return to the Add | Modify | Delete Organizational Unit(s) page, the HRD10 Organizational Unit should now be listed under the ITSO entry in the organization tree.
415
Figure 9-1 Create HRD10 Organizational Unit
9.2.2 Create Person

To create the Person entity within Tivoli Identity Manager, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click MY ORGANIZATION. 3. Click Manage People. 4. Under the ITSO organization tree, click HRD10. 5. It displays Use this screen to add, delete, and manage people page. Click Add. 6. Select Person from the Type of Person to Add drop-down list, and then click Submit.
416
7. When the Add | Modify Person form appears, we entered the following information: a. Click the Personal Information tab and enter the following information: Last Name: manager1 Full Name: hr manager1
b. Click Corporate Information tab, and enter 100002 in the Employee Number field. Note: This employee number is the value specified in the hr-itso.ldif used to import HR application users into LDAP directory on the Directory node. We entered this value for consistency. c. Click Submit. 8. When the form, Click Submit button for immediate scheduling or select a specific time appears, click Submit. 9. When you return to the Use this screen to add, delete, and manage people form, click Refresh. You should see the hr manager1 Person displayed on the page.
9.2.3 Create the organization structure

This section outlines additional Organizational Units and Persons that need to be created for the ITSO example scenario. Note: Refer to 9.2.1, Create Organizational Unit on page 415 and 9.2.2, Create Person on page 416 for details on creating Organizational Units and Persons. 1. Create the Organizational Unit HRD01 in HRD10 Organizational Unit with the following details: Organizational Unit Name: HRD01 Supervisor: hr manager1 2. Create the Person hr specialist1 in HRD01 Organizational Unit with the following details: Last Name: specialist1 Full Name: hr specialist1 Employee Number: 100003
417
3. Create the Organizational Unit DEV10 in ITSO Organizational Unit with the following details: Organizational Unit Name: DEV10 Supervisor: System Administrator 4. Create the Person Dave manager1 in DEV10 Organizational Unit with the following details: Last Name: manager1 Full Name: dev manager1 Employee Number: 100001 5. Organizational Unit DEV01 in DEV10 Organizational Unit with the following details: Organizational Unit Name: DEV01 Supervisor: dev manager1 When complete, the organization structure should look like Figure 9-2.
Figure 9-2 ITSO organization structure
418
9.3 Create and Grant Organizational Roles

This section describes how to create Organizational Roles to represent each group created within the LDAP directory on the Directory node for the ITSO example scenario. In addition, we will grant the Organizational Roles to the Persons created in the previous section.
9.3.1 Create Organizational Roles

To create the Organization Roles, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click MY ORGANIZATION. 3. Create an Organizational Role in the ITSO organizational unit. a. Click the ITSO organization tree. b. From the left hand side navigation bar, click Manage Organizational Roles. c. The Use this screen to add, modify, and delete organizational role(s) page will appear. Click Add. d. When it displays the page, Select the type of Organizational Role role to add, select Static from the drop-down list, and then click Continue. e. When it displays the page, Enter Organizational Role Attributes and Submit or Cancel, we specified the Name value as wpsadmins. Click Submit. Note: wpsadmins is the group used for WebSphere Portal administrators. 4. Create the Organizational Roles in the HRD10 organizational unit. a. Click the HRD10 organization tree. b. From the left hand side navigation bar, click Manage Organizational Roles. c. When the page, Use this screen to add, modify, and delete organizational role(s) appears, click Add. d. When the page, Select the type of organizational role to add appears, select Static from the drop-down list, and then click Continue. e. When Enter Organizational Role Attributes and Submit or Cancel page appears, enter A_Legals (Organizational Role) in the Name field, and then click Submit.
419
f. Repeat this process to add each of the following Organization Roles: A_Supervisors A_Publishers A_Researchers hrmanagers hrspecialists
5. Create the Organizational Roles in the DEV10 organizational unit. a. Click the DEV10 organization tree. b. From the left hand side navigation bar, click Manage Organizational Roles. c. When the page, Use this screen to add, modify, and delete organizational role(s) appears, click Add. d. When the page, Select the type of organizational role to add appears, select Static from the drop-down list, and then click Continue. e. When Enter Organizational Role Attributes and Submit or Cancel page appears, enter devmanagers in the Name field, and then click Submit.
9.3.2 Grant Organizational Roles

To grant Organizational Roles to the Person created in 9.2, Create Organizational Units and Persons on page 415, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click MY ORGANIZATION. 3. Grant the HRD10 Organizational Role. a. Click the HRD10 organization tree. b. From the Use this screen to add, modify, and delete organizational role(s), page, click hrmanagers. c. When the page, There are no Users. Click Add button to Add appears, click Add. d. When the page, Add Member appears, specify the following information: i. Select Person from the drop-down list of the Select option. ii. Select Full Name and Contains from the drop-down list (default values) iii. Enter hr manager in the right most text field box and click Search. e. When the search results containing the Person hr manager1 are displayed, check hr manager1 and click Continue.
420
f. When the Add People Confirmation page appears, click Submit. g. Click Refresh. h. The hr manager1 should be displayed in the User List tab. Click Cancel. 4. Repeat the above steps to do the following steps: Grant hrspecialists role to hr specialist1 Person in the HRD10 organizational unit. Grant devmanagers role to dev manager1 Person in the DEV10 organizational unit.
9.4 Modify the user interface

Tivoli Identity Manager administrators can customize the user interface. For example, they can add and remove fields from various forms displayed to the users. This section describes the procedure to modify the Tivoli Identity Manager user interface to add additional fields to the Person form for the ITSO example scenario.
9.4.1 Add attributes to user interface

To add attributes (uid, userpassword) to the user interface, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click CONFIGURATION. 3. When the Configuration page appears, click USER INTERFACE CUSTOMIZATION. 4. When it displays the page, User Interface Customization, double-click Person located in the left hand side column. It expands the Person entry and display a child Person entry (with a form image next to it) under the root Person entry. 5. Double-click the child Person entry. 6. Add uid attribute to form. a. From the Attribute List window located on the right hand side of the page, select uid and click Add Row (see annotation on Figure 9-3).
421
Add Row
Size
Figure 9-3 Default Person Form
b. The Person form will be updated with the new $uid field. Click the $uid on the Person form, the Properties window will display the default values for uid: Name: uid Data Type: Directory String Label: $uid
c. Enter 50 for the value for Size in Properties window (see Figure 9-3). 7. Add userpassword attribute to form. Repeat the above steps to add the userpassword attribute to the Person form.
422
8. Now that the userpassword attribute has been added to the Person form, we will customize the type of field displayed. Right-click $userpassword, and select Change To Password. The modified Person form is shown in Figure 9-4. 9. Click Save (see annotation on Figure 9-4) to save the form.
Save
Figure 9-4 Modified Person Form
10.When the dialog, Form template is saved successfully appears, click OK.
423
9.4.2 Update the Person entries

After modifying the user interface, the Person form now contains two new fields User Id (uid) and Password (userpassword). This section describes the procedure to set the User Id and Password values for the Person entries that were already created: 1. Complete the following steps to update the User Id and Password values for hr manager1 Person located in HRD10 organizational unit: a. Login to Tivoli Identity Manager as an administrator (for example, itim manager). b. Click MY ORGANIZATION. c. Click the ITSO and then HRD10 organization tree. d. Click hr manager1 Person. e. When it displays the page, Select an option, click Access Personal Information. f. Enter hrmanager1 for User Id value. g. Enter the password for the Password value. h. Click Submit. i. When it displays the page, Click Submit button for immediate scheduling or select a specific time, click Submit again. 2. Using the above steps, set the User Id and Password values for the following Persons. hr specialist1 located in HRD01 organizational unit User Id: hrspecialist1 Password: <password> User Id: devmanager1 Password: <password>
dev manager1 located in DEV10 organizational unit
424
9.5 Create the Password Policy

The Password Policy in Tivoli Identity Manager contains the rules to enforce strong password construction. Complete the following tasks to create a Password Policy: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click PROVISIONING. 3. Click the ITSO organization tree. 4. From the left hand side navigation bar, click Define Password Policies. 5. When the page, No password policy exists. Please click Add button to add a new password policy appears, click Add. 6. When Define Policy page appears, do the following steps: a. Click the GENERAL tab, and enter the following information: Policy Name: PasswordPolicy Service Resolution Scope: select SubTree Status: select Enabled
b. Click the SERVICES tab and check All Types of Services. c. Click Rules Tab. Specify the following values. The completed form is shown in Figure 9-5: Minimum Length: 8 Minimum Alphabetic Characters Required: 1 Minimum Numeric Characters Required: 1 Starts with Characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ Repeated History Length: 3 Check Disallow User Name? Check Disallow User Name(with Case-Insensitivity)? Check Disallow User ID? Check Disallow User ID(with Case-Insensitivity)?
425
Figure 9-5 Password Policy
7. Click Submit. When you return to the Add | Modify | Delete Password Policies page, the new policy PasswordPolicy should be listed on the page.
9.6 Create Workflows

This section describes the procedure to modify the default operational workflows to implement the approval process for the ITSO example scenario.
426
9.6.1 Modify selfRegister workflow

Complete the following steps to modify the selfRegister workflow of the Person entity in Tivoli Identity Manager. 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click CONFIGURATION. 3. Click ENTITIES. It displays a list of available entities. 4. Click Person. 5. When it displays the page, Modify an entity, click Define Operations. 6. When the Define Operations page appears as shown in Figure 9-6, click selfRegister under Operation.
Figure 9-6 Define Operations Page
7. When the Operation Diagram page appears, double-click the LOCATIONSEARCH element. 8. The Properties: Script Node page appears with the default JavaScript. Replace the LocationSearch Node properties with the following values:
427
a. Enter FindOrganizationalUnit in the Activity ID field. b. Enter Find the Organizational Unit that this person will belong to in the Activity Name field. c. Replace the JavaScript displayed in the dialog, with the JavaScript listed in Example 9-1. d. Click Save on the Operation Diagram page. When it displays the dialog, Workflow Saved, click OK. Note: We found that we could not cut and paste into the JavaScript dialog. For this reason we had to manually type the contents of Example 9-1 into the JavaScript dialog. If you do not enter the information within a specified time defined within WebSphere Application Server, the session will timeout. We suggest you enter the information, click OK and then click Save. Then return to verify the JavaScript was entered correctly.
Example 9-1 FindOrganizationalUnit JavaScript var thisPerson = person.get(); var orgUnit = thisPerson.getProperty(ou); if(orgUnit.length < 1) { process.setResult(SF,OU attribute was not passed correctly.); } else { var filt = (organizationalUnit= + orgUnit[0] + ); var ouSearch = new ContainerSearch(); var ouResult = ouSearch.searchByFilter(OrganizationalUnit,filt,2); if (ouResult.length < 1) { process.setResult(SF,A Organizational Unit was not found.); } else { container.set(ouResult[0]); process.setResult(SS,Found your Organizational Unit); } }
9. Add an Approval element to the Operation Diagram by dragging it from the left hand side column to the workflow design space. 10.Double-click the Approval element. 11.When the Properties: Approval Node page appears, specify the following values for the Approval Node as seen Figure 9-7:
428
a. Enter GetSupervisorApproval in the Activity ID field. b. Enter Get Supervisors Approval in the Activity Name field. c. Enter Custom in the Participant field. d. In the sidebox next to the Participant drop-down box, click ... to open a Java Applet Window. e. Enter the JavaScript shown in Example 9-2 on page 429 and then click OK.
Figure 9-7 Approval Node Properties Example 9-2 GetSupervisorApproval Node Participant JavaScript var ou = container.get(); var supervisor = ou.getProperty(ersupervisor); if (supervisor.length > 0) { return new Participant(ParticipantType.USER,supervisor[0]); } else { return new Participant(ParticipantType.SYSTEM_ADMIN); }
429
f. When you return to the Properties: Approval Node page, select Person Type under Input Parameters, and click Search Relevant Data. g. When the Relevant Data Search page appears, select Person Type on the Relevant Data Search page (see Figure 9-8), and then click OK.
Figure 9-8 Relevant Data Search Page
h. When returning to the Properties: Approval Node page, select OrganizationalContainer Type under Input Parameters, and then click Search Relevant Data. i. Select OrganizationalContainer on the Relevant Data Search page and click OK. j. When returning to the Properties: Approval Node page, click OK. 12.Insert the GetSupervisorApproval element between the FindOrganizationalUnit element and CREATEPERSON element as in the following instructions: a. Drag the Transition Line end point from the right side of the FindOrganizationalUnit element towards the left side of GetSupervisorApproval element. b. Draw a new Transition Line between GetSupervisorApproval element and CREATEPERSON element. i. Double-click the new Transition Line. It opens Properties: Transition page. ii. Change the Condition value to Approved. iii. Click OK. The completed design of the selfRegistration workflow is shown in Figure 9-9.
430
Figure 9-9 Design of selfRegistration Workflow
13.Click Save. 14.Click Exit on the Operation Diagram page. 15.When you return to the Define Operations page, click Done. 16.When you return to the Modify an entity page, click Apply Changes. 17.Click Logout to logout of Tivoli Identity Manager.
9.6.2 Modify transfer workflow

Complete the following steps to modify the selfRegister workflow of the Person entity in Tivoli Identity Manager. 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click CONFIGURATION. 3. Click ENTITIES. 4. When the list of available entities appears, click Person. 5. When Modify an entity page appears, click Define Operations. 6. When the Define Operations page appears, click transfer under Operation. 7. Add an Approval element to the Operation Diagram and specify the following values to the Approval Node: a. Enter GetSupervisorsApproval Activity ID field. b. Enter Get Supervisors Approval in the Activity Name field.
431
c. Enter Custom in the Participant field. d. In the sidebox next to the Participant drop-down box, click ... to open a Java Applet Window. e. Enter the JavaScript shown in Example 9-3, and then click OK.
Example 9-3 GetSupervisorsApproval Node Participant JavaScript var ou = container.get(); var supervisor = ou.getProperty(ersupervisor); if(supervisor.length > 0) { return new Participant(ParticipantType.USER,supervisor[0]); } else { return new Participant(ParticipantType.SYSTEM_ADMIN); }
f. Select Person Type under Input Parameters and click Search Relevant Data. g. Select Person Type on the Relevant Data Search page, and click OK. h. When you return to the Properties: Approval Node page, select OrganizationalContainer Type under Input Parameters, and then click Search Relevant Data. i. Select OrganizationalContainer on the Relevant Data Search page and click OK. j. Click OK on the Properties: Approval Node page. 8. Insert the GetSupervisorsApproval element between the Start element and TRANSFERPERSON element as in the following instructions: a. Drag the Transition Line end point from the right side of the Start element towards the left side of GetSupervisorsApproval element. b. Double-click the Transition Line. c. When the Properties: Transition page appears, change the Condition value to Custom. d. Enter true in the window below Condition as shown in Figure 9-10. e. Click OK.
432
Figure 9-10 Transition Line Properties
f. Draw a new Transition Line between GetSupervisorsApproval element and TRANSFERPERSON element. g. Double-click the new Transition Line. It opens Properties: Transition page. Change the Condition value to Approved. Click OK. The completed design of the selfRegistration workflow is shown in Figure 9-11.
Figure 9-11 Design of transfer Workflow
433
9. Click Save on the Operation Diagram page. When it displays the dialog, Workflow Saved, click OK. 10.Click Exit on the Operation Diagram page. 11.When you return to the Define Operations page, click Done. 12.When you return to the Modify an entity page, click Apply Changes. 13.Click Logout to logout of Tivoli Identity Manager. Note: The modifications made to the selfRegister and transfer workflows will not be effective until the next cache refresh, which is usually 10 minutes. Alternatively, you may restart the following Windows services: IBM WebSphere Application Server V5 - server1 IBM Tivoli Directory Server V5.2
9.7 Create Identity Manager Provisioning Policies

This section describes the procedure to modify the Provisioning Policy to manage the Tivoli Identity Manager accounts. The name of this policy is Default provisioning policy for ITIM and it is created by the Tivoli Identity Manager installation. In addition, this section describes how to create Provisioning Policies to manage user accounts in the following repositories: DB2 Universal Database (HR application database) Tivoli Directory Server (employee directory) DB2 Content Manager Tivoli Access Manager This section is organized into the following tasks: 1. 2. 3. 4. 5. Modify the Default provisioning policy for ITIM Create the DB2 Universal Database Provisioning Policy Create the Tivoli Directory Server Provisioning Policy Create the DB2 Content Manager Provisioning Policy Create the Tivoli Access Manager Provisioning Policy
9.7.1 Modify the Default provisioning policy for ITIM

Complete the following steps to modify the Default provisioning policy for ITIM: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click PROVISIONING.
434
3. Click the ITSO organization tree. 4. From the left hand side navigation bar, click Define Provisioning Policies. 5. When the Add | Modify | Delete Provisioning Policies page appears, click Default provisioning policy for ITIM. 6. When Default provisioning policy for ITIM page appears, click the ENTITLEMENTS tab. 7. Click ITIM Service. 8. When the ITIM Service page appears, click Get detail located next to the Advanced Provisioning Parameter List. 9. When the Entitlement Default Attributes page appears, click Add. 10.When the Add Account Attribute(s) page appears, check User Id and Password, and then click Add. 11.When you return to the Entitlement Default Attributes page, do the following steps: a. Enter the JavaScript shown in Example 9-4 in the value box for Password attribute. Note that we entered pa55word since the password policy requires alpha numeric passwords.
Example 9-4 Password attribute JavaScript {var value=subject.getProperty("userpassword"); if (value.length > 0) { return value[0]; } else { return "pa55word"; } }
b. Enter the JavaScript shown in Example 9-5 in the value box for User Id attribute.
Example 9-5 User Id attribute JavaScript {var value=subject.getProperty("uid"); if (value.length > 0) { return value[0]; } else { return subject.getProperty("sn"); } }
i. Click Submit. 12.When you return to the ITIM Service page, change the Type from Manual to Automatic, and then click Submit. 13.When it displays Entitlement has been modified successfully, click OK. 14.When you return to the Default provisioning policy for ITIM page, click Submit.
435
15.When it displays the page, Modify Schedule, click Submit. 16.Verify provisioning policies. The modifications made in this section to the provisioning policy should create a Tivoli Identity Manager user account for the Persons that already exist in Tivoli Identity Manager. This can be verified by performing a login to Tivoli Identity Manager with the User Id and the Password values of any Person that was specified in the 9.4.2, Update the Person entries on page 424 (for example, hrmanager1, hrspecialist1, devmanager1).
9.7.2 Create the DB2 Universal Database Provisioning Policy

The database provisioning policy governs the update of database accounts, or employee records in the HR database, based on changes made to a users Person object within Tivoli Identity Manager. This section requires that the database service and account have already been defined as described in 9.1.2, Create Services on page 413. Complete the following steps to create the DB2 Universal Database Provisioning Policy: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Select PROVISIONING. 3. Click the ITSO organization tree. 4. From the left hand side navigation bar, click Define Provisioning Policies. 5. Below the list of provisioning policies, click Add. 6. Select the GENERAL tab, and enter Database Provisioning Policy in the the policy name field. 7. All employees have records so theyll all need to be provisioned. The users that the policy applies to are defined under the Membership tab. Select the MEMBERSHIP tab, then click Add. 8. Select All(*) from the drop-down list, then click Continue. Note: When the policy is submitted for saving, it will be applied to all users that currently exist within Tivoli Identity Manager. If you wish to do some initial testing on a small number of users, temporarily limit this by selecting an Organizational Role to apply the policy to. Then only users assigned to that role will be provisioned.
436
9. The ENTITLEMENTS tab identifies which services this policy targets. The database service is the target of this policy. Click the ENTITLEMENTS tab, then click Add. A new window will open. 10.This policy should be applied automatically whenever user information is updated. Select Automatic from the Type drop-down list. Note: Set this to Manual if you dont want the provisioning policy to applied at this point in time. Change it to Automatic when ready to provision users. 11.For Target Type, select Service. 12.Select dsml2db2service from the Service Type drop-down list. 13.Select DB Service from the Service Name drop-down list. At this point the window should be similar to Figure 9-12.
Figure 9-12 Database policy entitlements
14.The parameters to be provisioned through the DB Service need to be added to the policys parameter list. Select the Get detail link for the Advanced Provisioning Parameter List. 15.An empty list of parameters is displayed. Click Add.
437
16.A list of attributes, including those defined in the service profile, is displayed. Select Next if necessary to see them all. Check the check box for the following attributes, then click Add: User Id First Name Last Name Department Number Email Address Home Address Employee Number (visible by clicking Next)
17.For each of these attributes, the value will be obtained from the Person object being provisioned. Example 9-6 shows the example JavaScript for retrieving the employee number from the Person (subject). Properties can be multi-value attributes. In this case there will only be one value for employee number so only the first cell in the array is returned. Enter the JavaScript list in Example 9-6 into the Value field for the Employee Number attribute.
Example 9-6 Retrieve the employee number from the Person object. {var value=subject.getProperty("employeenumber"); if (value.length > 0) { return value[0]; } else { return " "; } }
18.Use the code in Example 9-6 for the other attributes by changing the name of the property retrieved from the subject to the appropriate ldap attribute name. The policy attributes and corresponding property names are listed in Table 9-1.
Table 9-1 Property names for policy attributes Policy attribute name User Id First Name Last Name Email Address Home Address Employee Number Property name uid givenname sn mail homepostaladdress employeenumber
438
19.Some of the attributes should have the setting in the Enforcement column set to Mandatory either as a selected check box or drop-down list selection. Set the enforcement to Mandatory for all the attributes that were added above. After entering all JavaScript, the page should look like Figure 9-13.
Figure 9-13 TIM dialog with JavaScript to retrieve the employee number from the Person object
20.Set the enforcement to Mandatory for the Department Number attribute and add the script in Example 9-7. This script will use the organizational unit that the employee belongs to in Tivoli Identity Manager if the department number attribute is not set. Since the names are the same, this is a valid substitute.
Example 9-7 Department number policy script {var value=subject.getProperty("departmentnumber"); if (value.length > 0) { return value[0]; } else { value=subject.getProperty("parent");
439
if (value.length > 0) { var parentOu = value[0].getProperty("ou"); if (parentOu.length > 0) { return parentOu[0]; } } else { return " "; } } }
21.Click Submit. Note: Clicking Submit before adding the script to set a policy attribute will result in the policy attribute being removed from the Advanced Provisioning Parameter List. 22.When returning to the Add Entitlement page, click Add. 23.When the Entitlement has been added in the list successfully dialog appears, click OK. 24.Click Submit, then Submit again to save the provisioning policy and apply it to existing users within Tivoli Identity Manager.
9.7.3 Create the Tivoli Directory Server Provisioning Policy

The LDAP provisioning policy defines how updates made to the employees Person object in Tivoli Identity Manager get provisioned to the employee LDAP directory on the Tivoli Directory Server. This section requires that the database service has already been defined, as described in 9.1.2, Create Services on page 413. In order for the policy to update entries in the LDAP directory, the Tivoli Directory Integrator configuration described in 8.3, Develop the LDAP Config on page 392 must be running. To create the Tivoli Directory Server Provisioning Policy, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Select PROVISIONING. 3. Click the ITSO organization tree. 4. From the left hand side navigation bar, click Define Provisioning Policies. 5. Below the list of provisioning policies, click Add. 6. When the New Provisioning Policy page appears, do the following steps:
440
a. Select the GENERAL tab, and enter LDAP Provisioning Policy in the policy name field. b. All employees have entries in the employee directory so theyll all need to be provisioned. Select the MEMBERSHIP tab, then click Add. Select All(*) from the drop-down list, then click Continue. c. Select the ENTITLEMENTS tab, then click Add. A new window will open. i. This policy should be applied automatically whenever user information is updated. Select Automatic from the Type drop-down list. ii. For Target Type, select Service. iii. Select dsml2ldapservice from the Service Type drop-down list. iv. Select LDAP Server from the Service Name drop-down list. The Entitlements page should look like Figure 9-14.
Figure 9-14 LDAP provisioning policy entitlement
d. The parameters to be provisioned through the LDAP Service need to be added to the policys parameter list. Select the Get detail link for the Advanced Provisioning Parameter List. e. An empty list of parameters is displayed. Click Add.
441
f. A list of attributes, including those defined in the service profile, should be displayed. Select Next if necessary to see them all. Check the check box for the following attributes, then click Add: Employee Type First Name Postal Code Department Number Email Address Full Name Telephone Number Street Employee Number User Id State Password Postal Address Last Name Home Address Title
7. Enter the JavaScript listed in Example 9-6 on page 438 to set the values for the attributes listed in Table 9-2. Substitute the property name in the code with the property name in Table 9-2. Note: We found that we could not cut and paste into the JavaScript dialog. For this reason, we had to manually type the JavaScript into the dialog. If you do not enter the information within a specified time defined within WebSphere Application Server, the session will time out. We suggest that you enter the information, click OK and then click Save. Then return to verify that the JavaScript was entered correctly. 8. Set the enforcement to Mandatory for all the attributes added above.
Table 9-2 LDAP provisioning policy attributes Policy attribute name Email Address Password Home Address Postal Address State Property name mail userPassword homepostaladdress postaladdress st
442
Policy attribute name User Id Employee Number Telephone Number Postal Code Street Full Name Last Name Title First Name
Property name uid employeenumber telephonenumber postalcode street cn sn title givenname
Note: The User Id and Password policy attributes are updated with the uid and userpassword attribute values from the employees Person object in Tivoli Identity Manager. However, these policy attribute names refer to the account object attributes eruid and erpassword. The reason for this is that the account created within Tivoli Identity Manager as part of the provisioning process needs these attributes set. When provisioned out to the employee directory, the Tivoli Directory Integrator Assembly Line will map these to the uid and userpassword attributes in the LDAP directory. 9. Set the enforcement to Mandatory for the Department Number attribute and add the script in Example 9-7 on page 439. This script will use the organizational unit that the employee belongs to in Tivoli Identity Manager if the department number attribute is not set. Since the names are the same, this is a valid substitute. 10.Set the enforcement to Mandatory for the Employee Type attribute and add the script in Example 9-8. As mentioned previously, employee type is an unused attribute that is being reused to pass the list of role names that the employee has been assigned. This script loops through the values for the role property and adds the name of each role to an array. The array is then passed through the employee type attribute to Tivoli Directory Integrator. The role property cannot be passed directly. It has a property type of ldap distinguished name. Tivoli Directory Integrator would only receive the distinguished names of the roles. The plain text role name would not be available to the Tivoli Directory Integrator Assembly Line.
443
Example 9-8 Employee type policy script {var value=subject.getProperty("role"); if (value.length > 0) { var roles = new Array(); for (i=0;i<value.length;i++) { myrole = value[i]; roles[i]=myrole.getProperty("errolename")[0]; } return roles; } else { return " "; } }
11.Click Submit. 12.When returning to the Add Entitlement page, click Add. 13.When the Entitlement has been added in the list successfully dialog appears, click OK. 14.Click Submit, then Submit again to save the provisioning policy and apply it to existing users within Tivoli Identity Manager.
9.7.4 Create the DB2 Content Manager Provisioning Policy

The DB2 Content Manager Provisioning Policy defines how updates made to the employees Person object in Tivoli Identity Manager get provisioned to the DB2 Content Manager repository on Tivoli Directory Server. This section requires that the DB2 Content Manager service has already been defined, as described in 9.1.2, Create Services on page 413. In order for the policy to update Content Manager users, the Tivoli Directory Integrator configuration described in 8.1, Develop the DB2 Content Manager Config on page 374 must be running. To create the DB2 Content Manager Provisioning Policy, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Select PROVISIONING. 3. Click the ITSO organization tree. 4. From the left hand side navigation bar, click Define Provisioning Policies. 5. Below the list of provisioning policies, click Add. 6. Select the GENERAL tab, and enter CM Provisioning Policy in the policy name field.
444
7. Only employees with specific roles need accounts in DB2 Content Manager so only those employees need to be provisioned. Select the MEMBERSHIP tab, then click Add. 8. Select Organizational Role from the drop-down list, then click Continue. 9. To select from all the roles that are defined, enter * in the last field. This results in a search term of Name Contains *. Click Search. 10.Select the roles from the list whose employees need access to DB2 Content Manager. Select the following roles for the ITSO example: A_Legals A_Supervisors A_Publishers A_Researchers
11.Click Add. The membership list is shown in Figure 9-15.
Figure 9-15 CM provisioning policy membership
445
12.Select the ENTITLEMENTS tab, then click Add. A new window will open: a. This policy should be applied automatically whenever user information is updated. Select Automatic from the Type drop-down list. b. Select Service for the Target Type. c. Select dsml2CMservice from the Service Type drop-down list. d. Select CM Service from the Service Name drop-down list. The Entitlements page should look like the figure shown in Figure 9-16.
Figure 9-16 CM provisioning policy entitlement
e. The parameters to be provisioned through the CM Service need to be added to the policys parameter list. Select the Get detail link for the Advanced Provisioning Parameter List. f. An empty list of parameters is displayed. Click Add. g. A list of attributes, including those defined in the service profile, is displayed. Select Next if necessary to see them all. Check the check box for the attributes as shown in Figure 9-17, then click Add.
446
Figure 9-17 CM provisioning policy entitlement attributes
13.Enter the JavaScript found in Example 9-6 on page 438 to set the values for the attributes listed in Table 9-3. Substitute the property name in the code with the property name in Table 9-3. Also set the enforcement to Mandatory for all the attributes that were added above.
Table 9-3 CM Provisioning Policy attributes Policy attribute name User Id dn Property name uid dn
14.Set the enforcement to Mandatory for the Employee Type attribute and add the JavaScript listed in Example 9-8 on page 444. As mentioned previously, the employeetype is an unused attribute that is being reused to pass the list of role names that the employee has been assigned. 15.Set the enforcement to Mandatory for the Department Number attribute and add the script in Example 9-7 on page 439. This script will use the organizational unit that the employee belongs to in Tivoli Identity Manager if the department number attribute is not set. Since the names are the same, this is a valid substitute. 16.Click Submit. 17.Click Add.
447
18.Click Submit, then Submit again to save the provisioning policy and apply it to existing users within Tivoli Identity Manager.
9.7.5 Create the Tivoli Access Manager Provisioning Policy

Tivoli Access Manager Provisioning Policy controls the provisioning of accounts in Tivoli Access Manager user registry. To create the Tivoli Access Manager Provisioning Policy, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Select PROVISIONING. 3. Click the ITSO organization tree. 4. From the left hand side navigation bar, click Define Provisioning Policies. 5. When the Add | Modify | Delete Provisioning Policies page appears, click Add. 6. Select the GENERAL tab, and enter TAM Provisioning Policy in the Policy name field. Select the Service Resolution Scope as SubTree. 7. Click the Membership tab, then click Add. Select All(*) from the drop-down list, then click Continue. 8. Click the ENTITLEMENTS tab, then click Add. 9. When the Add Entitlement page appears do the following steps: a. Select Automatic from the Type drop-down list. b. For Target Type, select Service. c. Select TAM4Profile from the Service Type drop-down list. d. Select the Tivoli Access Manager from the Service Name drop-down list. e. Click Get detail located next to the Advanced Provisioning Parameter List. f. An empty list of parameters is displayed. Click Add. g. Select the check box for the following attributes, then click Add: Full Name User Id Password Last Name ertam4dn
h. When you return to the Entitlement Default Attributes page enter the JavaScript listed in Example 9-9 in the value box for Full Name attribute.
448
Example 9-9 Full Name attribute JavaScript { var value=subject.getProperty("cn"); if (value.length > 0) { return value[0]; } else { return " "; } }
i. Select Mandatory from the drop-down list of Full Name Enforcement. j. Select JavaScript/Constant from the drop-down menu of Full Name Expression Type. 10.Enter the JavaScript listed in Example 9-4 on page 435, into the value box for Password attribute. 11.Enter the JavaScript shown in Example 9-10, into the value box for ertam4dn attribute. Check the Mandatory box for the ertam4dn Enforcement.
Example 9-10 ertam4dn attribute JavaScript {var dn=" "; var userids = subject.getProperty("uid"); if (userids.length > 0) { dn = uid= + userids[0] + ,cn=users,dc=itso,dc=ibm,dc=com; } return dn;}
12.Enter the JavaScript shown in Example 9-5 on page 435, in the value box for User Id attribute. Check the Mandatory box for the User Id Enforcement. 13.Enter the JavaScript shown in Example 9-11, in the value box for Last Name attribute. Select Mandatory from the drop-down menu of Last Name Enforcement. Select JavaScript/Constant from the drop-down menu of Last Name Expression Type.
Example 9-11 Last Name JavaScript { var value=subject.getProperty("sn"); if (value.length > 0) { return value[0]; } else { return " "; } }
14.Click Submit. 15.When you return to the Add Entitlement page, click Add. 16.When the Entitlement has been modified successfully page appears, click OK. 17.When the TAM Provisioning Policy page appears, click Submit. 18.When the Modify Schedule page appears, click Submit.
449
450
10
Chapter 10.
Provisioning portlet application development

This chapter describes how the user provisioning portlet application was developed for the ITSO example scenario. The chapter includes a high level design, explanation of using the Tivoli Identity Manager APIs, information for preparing the environment for development, and programming details on each of the portlets. The chapter is organized into the following sections: Portlet application design Using the Tivoli Identity Manager APIs Prepare for the sample application Develop a portlet service Develop portlets
451
10.1 Portlet application design

The user provisioning portlets are written so that day-to-day account management tasks can be performed by users through the same portal interface that they use for their other business applications. Most of the portlets perform distinct tasks using different Tivoli Identity Manager APIs. However, each portlet must make an authenticated connection to the Identity Manager server. This common code will be implemented through a portlet service that all portlets can use. This is illustrated in Figure 10-1.
Portal Server
Request connection
Portlet Service
Establish connection
Portlets Portlets Portlets
Perform portlet task
Identity Manager Server
Figure 10-1 Portlet communication with Tivoli Identity Manager
Together, the user provisioning portlets will implement all but the first use case outlined in 3.3.1, Use case overview on page 101. The first use case utilizes the New Employee portlet from the HR application as described in the Appendix , Introduction to the HR application on page 526.
10.2 Using the Tivoli Identity Manager APIs

The Tivoli Identity Manager APIs are extensions to Tivoli Identity Manager that enable developers to programmatically interact with the Identity Manager server. Documentation on the these APIs is installed with Tivoli Identity Manager. Open the c:\itim45\extensions\index.html file, where c:\itim45 is the installation directory, as a starting point. This page provides links to the general API documentation, API Javadoc, and examples. The Tivoli Identity Manager API documentation is also available at:
http://publib.boulder.ibm.com/tividd/td/ITIM/SC32-1683-00/en_US/HTML/index.html
Of the extensions, the Applications extension is used the most often for implementing the user provisioning portlets.
452
10.3 Prepare for the sample application

This section describes the steps for loading the ITSO identity and access management system sample code into the Rational Application Developer workspace.
10.3.1 Import the project interchange file

All of the sample code is provided in a Rational Application Developer project interchange file. To load this file into the workspace, follow these steps: 1. Select File Import. 2. Select Project Interchange and click Next. 3. Click Browse next to the From zip file dropdown. 4. Navigate to UserProvisioning.zip. and click Open. 5. Click Select All to include all the projects in the interchange. 6. Click Finish.
10.3.2 Add the user library to the project build path

For each project in Rational Application Developer that uses the Tivoli Identity Manager API the sample code references a user library named TivoliIdentityManagerAPI in the build path. This user library needs to be created and the Tivoli Identity Manager JAR files added to it as follows: 1. Expand the Dynamic Web Projects folder. 2. Right-click the User Provisioning project and select Properties. 3. Click Java Build Path. 4. Click the Libraries tab. 5. Select TivoliIdentityManagerAPI (unbound) and click Edit. 6. Click User Libraries. 7. In the User Libraries window click New. 8. In the New User Library dialog enter TivoliIdentityManagerAPI, and click OK. 9. Click Add JARs. 10.Navigate to the Tivoli Identity Manager API JARs installed in 6.4.6, Tivoli Identity Manager V4.5.1 API installation on page 356, select the three JARs (api_ejb.jar, itim_api.jar, ldapjdk.jar), and click Open. 11.Click OK.
Chapter 10. Provisioning portlet application development
453
12.In the Add Library window verify that the new library name is selected and click Finish. 13.Click OK. 14.The projects will not automatically rebuild and pick up the newly defined user library. To force a rebuild select Project Clean, then select Clean all projects and click OK. The rebuild may take a few minutes.
10.3.3 Add the HR Application to the project build path

Some of the portlets require the HR Application services. Import the HR Application as described in Import the Project Interchange File on page 545.
10.3.4 Configure the WebSphere Portal V5.1 Test Environment

Be sure you have configured the WebSphere Portal test environment, as described in 6.5.3, WebSphere Portal V5.1 Test Environment configuration on page 358.
10.4 Develop a portlet service

Functionality common to many portlets can be provided by a portlet service. For the ITSO identity and access management system example, a portlet service is written to connect to the Tivoli Identity Manager server using the Tivoli Identity Manager APIs and retrieve some commonly used objects. In IBM WebSphere Portal V5.1 there is support for creating portlet services using the Java Portlet API (JSR 168). The service will be written to support portlets based on either the Java Portlet API or the IBM portlet API. For more information on portlet services, refer to the IBM WebSphere Portal for Multiplatforms Version 5.1 Information Center, available at:
http://publib.boulder.ibm.com/pvc/wp/510/ent/en/InfoCenter/index.html
10.4.1 Portlet service interfaces

It is the service interface that the portlets interact with. For this example, two service interfaces are provided for the service. TimApiService follows the Java Portlet API (JSR 168) programming model and is intended to be used by portlets that are implemented with the Java Portlet API. The TimApiServiceIBM interface uses the IBM portlet API from previous releases of WebSphere Portal.
454
Many of the class names are the same between these two APIs, but the classes come from different packages. The package hierarchy primarily used for TimApiServiceIBM is: org.apache.jetspeed.portlet TimApiService uses the following hierarchies instead: javax.portlet com.ibm.portal.portlet Although both portlet service interfaces are provided, the portlets in this example only use the TimApiServiceIBM interface.
10.4.2 Portlet service implementation

The implementation class is TimApiServiceImpl. It provides the implementation for both portlet service interfaces. The implementations for the TimApiServiceIBM methods simply call the corresponding methods of the TimApiService after converting the parameters. This is illustrated in Example 10-1.
Example 10-1 Call the Java Portlet API method implementation public PlatformContext getPlatform(PortletRequest request, PortletContext context) { return getPlatform( APIConverterFactory.getInstance().getRenderRequest(request), APIConverterFactory.getInstance().getPortletContext(context)); }
The implementation class also makes use of a helper class named PortletCredential4Itim. This class takes care of retrieving the Tivoli Identity Manager administrators password from the WebSphere Portal credential vault. In so doing, it also illustrates how the Java Portlet API (JSR 168) is used to instantiate a portlet service, the CredentialVaultService. Unlike the IBM portlet API, this involves finding the service home object by performing a JNDI lookup and then using the home object to get the service. Table 10-1 provides a brief summary of the methods in the portlet service implementation class.
455
Table 10-1 Summary of TimApiServiceImpl methods Method init Description Initialize the instance variables with the configuration parameter values from the portlet service registry. See 10.4.4, Deploy the portlet service for testing on page 458 for more information on the configuration parameters. Obtain the InitialPlatformContext. This establishes a context for communicating remotely with the Tivoli Identity Manager server. Log into the Tivoli Identity Manager server and return a Subject object. This handles the authentication of the user based on the user ID and password. For this example, the Tivoli Identity Manager administrator user ID and password are used for all communication with the remote server. Search for user accounts based on a provided filter. The search is performed using the SearchMO class. If multiple accounts are found, it returns the first account. Search for and return all accounts that match the filter provided. Search for a Person object based on a filter. Only the first Person object found is returned. Search for Tivoli Identity Manager organizational units within the entire organization. Search for organizational units within the branch of the organization tree specified. Search for roles defined within an organizational unit. Search for a role and return its name.
getPlatform
getSubject
getAccount
getAccounts getPerson getDivision getDepartment getRole getEmpRolesNames
10.4.3 Using the Tivoli Identity Manager APIs

Some of the key classes and interfaces used in the portlet service are presented in this section.
PlatformContext
Together with the InitialPlatformContext implementation of the PlatformContext interface, the PlatformContext is used to establish a context for communicating remotely with the Tivoli Identity Manager server.
456
The context is constructed with the following parameters: context factory: The WebSpherePlatformContextFactory class is used as the factory to create the platform context. platform URL: The IIOP URL of the Tivoli Identity Manager server. user ID: The user ID for the context. For this example, the Tivoli Identity Manager administrator ID is used. password: The password for the user ID. As the basis for communication with Tivoli Identity Manager, the context is used to get the login context in the getSubject method as well as for many of the Tivoli Identity Manager APIs.
PlatformCallbackHandler
Tivoli Identity Manager provides this CallbackHandler for use with the JAAS framework to authenticate with the Tivoli Identity Manager server. It is used with the LoginContext class to perform the login.
SearchMO
This class performs a managed object search. A managed object represents a Tivoli Identity Manager entity to manage. Examples of entities are account, role, and person entities. A separate value object holds the attribute information about the entity. A manager specific to the type of managed object aggregates the operations that can be performed, such as creating or validating objects. There are a number of methods in the portlet service which perform different types of searches; all with the SearchMO class. The parameters used in the portlet service to define the various searches are:
Table 10-2 SearchMO parameters used in the portlet service Parameter category Description This parameter restricts the search to a specific category of object within the Tivoli Identity Manager data model. Constants are defined in the ObjectProfileCategory class with the available categories. Of these constants, the ACCOUNT, PERSON, ROLE, and CONTAINER constants were used to restrict the searches to those types of entities. The CONTAINER constant is used to restrict searches to organizational units: the ORGUNIT constant will not produce the desired results. This parameter sets the context within which to search. It is used in this example to limit the search to a specific branch of the organization tree.
context
457
Parameter profile name
Description An ObjectProfile maps an object in the datastore with an entity in the data model. It is used to limit the search to a specific type of object. For this example, it is used to perform searches on Tivoli Identity Manager account objects. The profile name for these objects is ITIMProfileAccount. This is the search string or filter for the search. It must be given in the same format as would be used for an LDAP search. For example (eruid=user1) would be the filter to search for a user ID of user1.
filter
For example, one particular search the EntitlementRequest portlet does is a search for the users accounts, as seen in Example 10-2.
Example 10-2 Configuring the search for a users accounts SearchMO searchMO = new SearchMO(platform,subject); searchMO.setCategory(ObjectProfileCategory.ACCOUNT); DistinguishedName dn = new DistinguishedName(TENANT_DN); CompoundDN cdn = new CompoundDN(dn); searchMO.setContext(cdn); searchMO.setProfileName(PROFILENAME); //Filter should be set to "eruid" searchMO.setFilter("\"("+ filter + user+")\""); Collection accounts = searchMO.execute().getResults(); Iterator it2 =accounts.iterator();
Note: In situations where the results of a search could be large, the paging parameter should also be used. With paging enabled the search will return the results one page at a time, thereby avoiding the performance problems that could arise with a large resultset.
10.4.4 Deploy the portlet service for testing

For complete testing of the portlet service and the portlets that use it, the portlet service must be deployed within the Rational Application Developer test environment server as a portlet service. The steps are as follows: 1. Export the TimService project as a JAR file. 2. Place the JAR file in the <wp_root>\shared\app directory of the portal server. For example: C:\Program Files\Portal51UTE\PortalServer\shared\app.
458
3. Update the portlet service registry to register the service and provide the configuration parameters. Edit the <wp_root>\shared\app\config\services\PortletServiceRegistryService.properti es file and add the following configuration properties to the end of the file (also refer to Example 10-3): IBM_portlet_API_service_interface=service_implementation This registers the service for use by portlets implemented with the IBM portlet API. jndi:service_interface=service_implementation This registers the service for use by portlets implemented with the Java Portlet API (JSR 168). The service implementation was written to implement both services so while the interface listed here is different than that used for the IBM portlet API, the service implementation name is the same. service_implementation.tenantDN = org_DN This configuration parameter sets the distinguished name of the organization as defined in the Tivoli Identity Manager installation in Install Tivoli Identity Manager V4.5.1 FP16 on page 191. service_implementation.defaultOrg = internal_DN Within the Tivoli Identity Manager ldap directory, the organization has a generated distinguished name that is needed when using the Tivoli Identity Manager APIs. It is the same as the tenantDN with the generated erglobalid (usually erglobalid=00000000000000000000) prepended. service_implementation.itimAdmin = Tivoli Identity Manager administrator This specifies the user ID to connect to Tivoli Identity Manager with. It needs to have administrator access to interact with the Tivoli Identity Manager API on behalf of any user. service_implementation.password = administrator password The password in the credential vault cannot be accessed until the portlet user logs in. The password is provided here for portlets, such as Self-register, that are available to anonymous users. Note: Ideally a more secure method would be used for storing the password, but placing it in the service registry will suffice for this example. service_implementation.appServerURL = jndi_URL This parameter provides the URL for making a connection to the Tivoli Identity Manager server.
459
service_implementation.loginContext = JAAS_module The alias name used when creating the JAAS application login module configuration in Configure JAAS on page 232. The addition to the properties file should be similar to that shown in Example 10-3.
Example 10-3 Register service in PortletServiceRegistryService.properties # Register service for communication with Tivoli Identity Manager API com.ibm.sst.up.tim.servicelayer.TimApiServiceIBM=com.ibm.sst.up.tim.servicelaye r.TimApiServiceImpl jndi:com.ibm.sst.up.tim.servicelayer.TimApiService=com.ibm.sst.up.tim.servicela yer.TimApiServiceImpl # Configuration parameters for TimApiServiceImpl com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.tenantDN = ou=ITSO,dc=com com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.defaultOrg= erglobalid=00000000000000000000,ou=ITSO,dc=com com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.itimAdmin = itim manager com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.password=secret com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.appServerURL=iiop://timwin1.i tso.ral.ibm.com:2809 com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.loginContext=ITIM
4. If the test environment server is running, it needs to be restarted to pick up the service registration.
10.5 Develop portlets

There is a one-to-one mapping between the user provisioning portlets and the use cases described in 3.3.1, Use case overview on page 101. The purpose and behavior of each portlet will be described in this section. The key Tivoli Identity Manager APIs that are used will also be presented. The details of the portlets can be reviewed in the code samples. Further details and examples for the Tivoli Identity Manager APIs can be found within the extensions directory where Tivoli Identity Manager is installed (for example: c:\itim45\extensions\index.html). In order to test the portlets in the WebSphere Portal v5.1 Test Environment within Rational Application Developer, the portlet service must be deployed. Refer to 10.4.4, Deploy the portlet service for testing on page 458 for instructions on deploying the portlet service.
460
10.5.1 Develop the Self-register portlet

The SelfRegisterPortlet is implemented for use case UCF02: Employee Self-registration defined in Table 3-4 on page 104. This portlet is available to all employees, without logging in to the portal interface. It allows an employee to register themselves with the TIM system. When the employee first accesses the portal, they are new to the company and only have an employee number. They use this portlet to create a userid of their choice and also provide an answer to the security challenge. See Figure 10-2 for a sample of the user interface. Upon successful completion of using this portlet, the employees request to be added to the system will be put into their managers task list for approval/rejection.
Figure 10-2 SelfRegister portlet user interface
In the following sections we describe the key TIM APIs used in this portlet.
com.ibm.itim.dataservices.model.domain.Person
The Person class is the object that holds the attribute information of a person in the data model. The SelfRegister portlet issues a request to the TIM system to create a new Person object. When creating a new Person object, you specify the type of person via a profile parameter. The TIM system defines various types of profiles such as Person, Employee, Contractor and others. The self-register portlet creates a person using the PERSON_PROFILE (Example 10-4).
Example 10-4 Defining a new Person object Person thisPerson = new Person(PERSON_PROFILE);
461
com.ibm.itim.common.AttributeValue
We use the AttributeValue class to define a single name-value pair attribute. The AttributeValues class is a collection of AttributeValue objects, and defines the set of attributes for a Person (Example 10-5).
Example 10-5 Attributes for a Person AttributeValues attrValues = new AttributeValues(); AttributeValue av = new AttributeValue("sn", sn); attrValues.put(av); av=new AttributeValue("cn", cn); attrValues.put(av); av=new AttributeValue("givenname", givenName); attrValues.put(av); av=new AttributeValue("ou", ou); attrValues.put(av); av=new AttributeValue("departmentnumber", ou); attrValues.put(av); av=new AttributeValue("employeenumber", empNo); attrValues.put(av); av=new AttributeValue("uid", userId); attrValues.put(av); av=new AttributeValue("ersharedsecret", mother); attrValues.put(av); //now add the attributes to the Person we created above thisPerson.setAttributes(attrValues);
com.ibm.itim.apps.identity.SelfRegistrationManager
The createPerson() method issues a request to TIM to create a person, passing in a Person object (Example 10-6).
Example 10-6 Calling TIM to create a new Person SelfRegistrationManager selfRegister = new SelfRegistrationManager(platform); try { //create the new person selfRegister.createPerson(person); } catch (Exception e) { //handle the various exceptions }
462
10.5.2 Develop the Entitlement Request portlet

The EntitlementRequestPortlet is implemented for the use cases UCF03: Approval and Role Assignment, defined in Table 3-5 on page 105, and UCF08: Department Change, described in Table 3-10 on page 108. This portlet is available to managers, and allows the manager to assign a role to a new employee in their department. When the manager accesses the portlet, a list of outstanding work items is presented to them. Each item contains an employee name, a list of roles, and an Accept/Reject option. The manager can assign the role(s) for the employee and then submit the request to the TIM system. If the manager has no outstanding work items, the portlet shows them a message saying so. This portlet is responsible for setting the roles for the employee. In the case of the new employee, that means reading the roles selected by the manager and adding them to the person object. In the case of a transferring employee, the employee's existing roles must first be removed before the new ones are added. In the case of the transferring employee, we use the code as in Example 10-7 to get the collection of existing roles, loop through the collection and issue a removeRole() for each role. As long as there is at least one role to be deleted, we then issue the update(), passing the person.
Example 10-7 Removing roles from a person boolean updateNeeded = false; Collection empRoles = person.getRoles(); Iterator iterator = empRoles.iterator(); while (iterator.hasNext()) { DistinguishedName dnRole = (DistinguishedName)iterator.next(); person.removeRole(dnRole); updateNeeded = true; } if (updateNeeded) { try { Date date = new Date(); Request re = personMO.update(person, date); // commit change at the "date" time } catch(Exception e){ e.printStackTrace(); } }
463
In both cases (accepting a new employee and a transferring employee) we loop through the list of roles that the manager was able to select from, and issue an addRole() for each role selected by the manager. If there are any roles to be added, we then issue the update(). See Example 10-8 for sample code.
Example 10-8 Adding roles to a person for(int k=0; k<sessionBean.getNumOfRole(); k++) {
if(request.getParameter("entitlementrequest.EntitlementRequestPortletROLE"+i+k) !=null) { roleString = sessionBean.getRoleAvail(k); //add the chosen role to the employee DistinguishedName dnRoleName = new DistinguishedName(sessionBean.getRoleDn(k)); person.addRole(dnRoleName); updateNeeded = true; } }//end of for loop if (updateNeeded) { try { Date date = new Date(); date.setTime(date.getTime()+60000); //add a minute Request re = personMO.update(person, date); // commit change at the "date" time } catch(Exception e){ e.printStackTrace(); }
10.5.3 Develop the ResetPassword portlet

The ResetPassword portlet is implemented for use case UCF06: Employee Password Reset defined in Table 3-8 on page 107. It is available to all employees, without logging in to the portal interface. Employees are able to reset their password by providing their employee number and user ID, plus answering the password reset challenge question. The answer was provided by the employee during self-registration. Once this information is validated, a new password is generated for the user and displayed by the portlet. Behind the scenes, the password is provisioned to each of the users accounts so that they are all the same.
464
Example 10-9 shows using the PasswordManager class for getting all the accounts for a person using the getPasswordAccounts() method, then generating a new password using the generatePassword() method, and finally synchronizing it across all accounts using the synchPasswords() method.
Example 10-9 ResetPassword example String password = ""; PersonMO personMO = new PersonMO(platform,subject,person.getDistinguishedName()); Collection accountMOs = new Vector(); try{ PasswordManager pManager = new PasswordManager(platform,subject); accountMOs = pManager.getPasswordAccounts(personMO); password = pManager.generatePassword(accountMOs); Request request = pManager.synchPasswords(personMO,password,null); if( getPortletLog().isDebugEnabled() ) getPortletLog().debug("ResetPasswordPortlet.reset(). Reset request submitted."); } catch(RemoteException e){ e.printStackTrace(); } catch(ApplicationException e){ e.printStackTrace(); }
10.5.4 Develop the Password portlet

The Password portlet is implemented for use case UCF04 Employe Password Change defined in Table 3-6 on page 106. It is available to all users, and allows them to change their password. The password policy is checked to insure that the password is valid, and if so the change is made and the new password is provisioned to each of the users accounts so that they are all the same. Example 10-10 shows using the PasswordManager class to validate the new password against the password rules using the isPasswordValid() method.
465
Example 10-10 Checking that a new password is valid PasswordManager pManager = new PasswordManager(platform,subject); String msg = ""; boolean isValid = false; Collection accountMOs = new Vector(); PersonMO personMO = new PersonMO(platform,subject,person.getDistinguishedName()); try{ accountMOs = pManager.getPasswordAccounts(personMO); isValid = pManager.isPasswordValid(accountMOs,newPassword); } catch(InvalidPasswordException e){ e.printStackTrace(); msg = "Password does not comply with standards. Please try if( getPortletLog().isDebugEnabled() ) getPortletLog().debug("PasswordPortlet.changePassword(). not comply with standards."); } catch(PasswordRuleException e){ e.printStackTrace(); msg = "Password does not comply with standards. Please try if( getPortletLog().isDebugEnabled() ) getPortletLog().debug("PasswordPortlet.changePassword(). not comply with standards."); }
again."; Password does
again."; Password does
If the password is valid, then the new password is synchronized across all accounts using the synchPasswords() method. This is the same as in the ResetPassword portlet.
Example 10-11 Changing the password if (isValid){ Request request; request = pManager.synchPasswords(personMO,newPassword,null); msg = "Change Request Pending...Request has been submitted as " + request.getID(); } else { msg = "password does not comply with standards"; }
466
10.5.5 Develop the Update My Info portlet

The UpdateMyInfo portlet is implemented for use case in UCF05: Employee Self-care defined in Table 3-7 on page 106. It is available to all users, and allows the user to update their personal information. When the user access the portlet, they are shown a form with entry fields containing the values in the TIM system and the HR system. Example 10-12 shows the code for getting the person and the persons attributes from the TIM system.
Example 10-12 Getting the employees attributes from TIM Person employee = null; employee = factory.getPerson(filter,platform, subject); // read all the attributes for the person, and store them in the sessionBean. AttributeValues attrValues = new AttributeValues(); attrValues = employee.getAttributes();
Once the employee updates the pertinent data, they submit the form for processing. The portlet then takes the updated values from the form, sets attributes for each value, and then submits the update request. Example 10-13 shows setting a single attribute, and issuing the update() request.
Example 10-13 Updating the employees attributes String filter = "uid=" + user; Person employee= null; employee = factory.getPerson(filter,platform, subject); AttributeValue av=new AttributeValue("title", sessionBean.getJobtitle()); employee.setAttribute(av); PersonMO employeeMO = new PersonMO(platform,subject,employee.getDistinguishedName()); Request re = employeeMO.update(employee, null);
467
10.5.6 Develop the Update Roles portlet

The UpdateRoles portlet is implemented for use case UCF07: Role Change defined in Table 3-9 on page 108. It is available to managers and allows the manager to change the roles that an employee is assigned. The manager is presented with a list of roles applicable to their division and department, and is shown which roles the employee is currently assigned. The manager may add other roles, delete existing roles, or a combination of both. The code to process the roles is the same as handling the role processing in the EntitlementRequest portlet. See Example 10-7 on page 463 for removing roles, and Example 10-8 on page 464 for adding roles.
10.5.7 Develop the Update Employee Info portlet

The UpdateEmployeeInfo portlet is implemented for use case UCF08: Department Change defined in Table 3-10 on page 108. In addition, this portlet can be used to update the employees salary in the HR system. The manager enters the employee number for the employee to be updated, and is returned the division, department, and salary for that employee. The manager can change the division and/or department number to start the department change process. Example 10-14 shows the transfer request. The transfer() method is passed the OrganizationalContainerMO, which is created based on the distinguished name of the new department.
Example 10-14 Transfer request DistinguishedName orgDN = new DistinguishedName(newDeptName); OrganizationalContainerMO orgConMO = new OrganizationalContainerMO(platform, subject, orgDN) try { Request orgChgReq = employeeMO.transfer(orgConMO, null); message = message+ " Change Org Unit Request has been submitted as "+ orgChgReq.getID(); } catch (Exception e) { }
468
11
Chapter 11.
Application deployment
This chapter provides a procedure for deploying the applications to the ITSO identity and access management system runtime environment. In some cases, we will reference other sections of the redbook for details, and in others we have included the details in this chapter. It is important that you follow the sequence of the steps in this chapter due to some application and configuration dependencies. This chapter is organized into the following sections: Prerequisites Deploy the TDI connector for Content Manager Deploy the TDI configuration files Tivoli Identity Manager customization Deploy provisioning portlet application
469
11.1 Prerequisites
Prior to deploying the provisioning portlet application, you need to ensure that the following prerequisites have been met: Install and configure software for runtime environment ITSO sample code download and unpack Deploy HR application Deploy document management application
11.1.1 Install and configure software for runtime environment

The details on how to install and configure the runtime environment for the ITSO identity and access management system can be found in the following chapters: Chapter 4, Runtime environment installation on page 129 Chapter 5, Runtime environment configuration on page 235
11.1.2 ITSO sample code download and unpack

Download and unpack the sample code (additional or Web material). For details, refer to Appendix C, Additional material on page 591.
11.1.3 Deploy HR application

The ITSO example provisioning portlet application requires that the HR application is deployed. For details on deploying the HR application to the runtime environment, refer to Deploy the HR application to runtime environment on page 527.
11.1.4 Deploy document management application

The ITSO example provisioning portlet application requires that the ITSO custom document management application is deployed. For details on deploying the HR application to the runtime environment, refer to Deploy document management application on page 553.
470
11.2 Deploy the TDI connector for Content Manager

This section describes how to copy the CMConnector.jar to the proper location on the Directory node (location Tivoli Directory Integrator is installed). After copying the custom connector JAR file, some modifications must be made to the Tivoli Directory Integrator batch file prior to running the application. These modifications are needed to ensure that environment variables are set to allow the use of both APIs and that JDCB drivers will be loaded properly. Note: For detailed information on how to develop a custom Tivoli Directory Integrator connector for DB2 Content Manager, refer to Chapter 7, TDI connector for Content Manager development on page 363. To install and configure the connector, do the following steps: 1. Copy the CMConnector.jar to the <tdi_home>\jars\connectors directory on the Directory node (location Tivoli Directory Integrator is installed). 2. Modify the ibmdisrv.bat file. Note: In a development environment scenario, modify the ibmditk.bat in place of the ibmdisrv.bat fi.e a. Navigate to the <tdi_home> directory (for example, c:\ibm\DirectoryIntegrator). b. Open the ibmdisrv.bat in a text editor. c. Insert the following line after the setlocal entry to set the environment for Information Integrator for Content to access DB2 Content Manager:
call c:\ibm\db2cmv8\bin\cmbenv81.bat
d. Add the following after the PATH environment variable to set the environment for DB2 Universal Database JDBC driver:
PATH=%PATH%;c:\ibm\sqllib\bin;c:\ibm\sqllib\function;
where c:\ibm\sqllib is the home directory for the DB2 installation. The custom connector is now installed and will be available for use the next time Tivoli Directory Integrator is restarted.
Chapter 11. Application deployment
471
11.3 Deploy the TDI configuration files

This section describes how to deploy and run the Tivoli Directory Integrator config files in the runtime environment. Note: For details on developing the Tivoli Directory Integrator configuration files refer to Chapter 8, TDI Assembly Line development on page 373.
11.3.1 Deploy the TDI config files

To deploy the config files to the runtime environment, do the following steps: 1. Copy the three configuration files (itso-hr.xml, itso-ldap.xml, itso-cm.xml) from the c:\6692code\tdi_assemblylines directory to the c:\ibm\tdiwork directory on the Directory node (where Tivoli Directory Integrator is installed). Note: If you are using the configuration files included with the redbook sample code, then you will need to modify the server names for the repositories (Tivoli Directory Server, DB2 Universal Database). The following steps in this section describe how to modify the server names in the configuration files using the Tivoli Directory Integrator Config Editor. If you have completed Chapter 8, TDI Assembly Line development on page 373, the configuration values will already be defined. 2. Modify the itso-hr.xml to include the proper server name for DB2 Universal Database in runtime environment where the HR application database is deployed. a. Launch the Tivoli Directory Integrator Config Editor. Select Start Programs IBM Tivoli Directory Integrator IBM Tivoli Directory Integrator or run ibmditk.bat from the Tivoli Directory Integrator installation directory. b. When the prompted with the dialog, Your solution directory c:\ibm\tdiwork does not contain solution files. Do you want to create them? Click Yes. c. Select File Open from the menu bar. d. Select the itso-hr.xml file and then click Open. e. Expand AssemblyLines. f. Select dbUpdate. g. Select updateDB2 under Flow.
472
h. On the Connection tab, update the following for the runtime environment: JDBC URL: jdbc:db2://wpwin1.itso.ral.ibm.com:50000/HR Note: This is the hostname of Portal Server node where the HR application database is deployed. Username: admin Password: <password> Schema: sstdb1 JDBC Driver: com.ibm.db2.jcc.DB2Driver
i. Select dbDelete under AssemblyLines. j. Select deleteDB2 under Flow. k. On the Connection tab, update the following for the runtime environment: JDBC URL: jdbc:db2://wpwin1.itso.ral.ibm.com:50000/HR Note: This is the hostname of Portal Server node where the HR application database is deployed. Username: admin Password: <password> Schema: sstdb1 JDBC Driver: com.ibm.db2.jcc.DB2Driver
l. Select File Save to save the configuration updates. 3. Modify the itso-ldap.xml to include the proper server name of the Tivoli Directory Server used by the HR application in the runtime environment. a. Launch the Tivoli Directory Integrator Config Editor. b. Select File Open from the menu bar. c. Select the itso-ldap.xml file and then click Open. d. Expand AssemblyLines. e. Select ldapDelete. f. Select deleteLDAP under Flow. g. On the Connection tab, update the following for the runtime environment: JDBC URL: ldap://tdiwin1.itso.ral.ibm.com:389 Note: This is the hostname of Directory node where the Tivoli Directory Server is installed. Username: cn=root Password: <password> Search Base: dc=itso,dc=ibm,dc=com Search Filter: uid=*
473
h. Select ldapGroupUpdate under AssemblyLines. i. Select updateGroups under Flow. j. On the Connection tab, update the following for the runtime environment: JDBC URL: ldap://tdiwin1.itso.ral.ibm.com:389 Note: This is the hostname of Directory node where the Tivoli Directory Server is installed. Username: cn=root Password: <password> Search Base: dc=itso,dc=ibm,dc=com Search Filter: (objectclass=groupofuniquenames)
k. Select ldapUpdate under AssemblyLines. l. Select updateLDAP under Flow. m. On the Connection tab, update the following for the runtime environment: JDBC URL: ldap://tdiwin1.itso.ral.ibm.com:389 Note: This is the hostname of Directory node where the Tivoli Directory Server is installed. Username: cn=root Password: <password> Search Base: dc=itso,dc=ibm,dc=com Search Filter: uid=*
n. Select File Save to save the configuration updates. 4. Close the Config Editor.
11.3.2 Start the Tivoli Directory Integrator servers

A Tivoli Directory Integrator server is launched for each Config file by running the server batch file with parameters specifying the Config file and event handler to run. 1. Open three and command windows, and in each window navigate to the c:\ibm\DirectoryIntegrator directory. 2. Run the following commands each in its own command window:
ibmdisrv -c"itso-hr.xml" -t"ListenForDBUpdates" ibmdisrv -c"itso-ldap.xml" -t"ListenForLDAPUpdates" ibmdisrv -c"itso-cm.xml" -t"ListenForCMUpdates"
474
Note: By default, all three servers will write to the ibmdi.log file. This default is configured in log4j.properties. If you wish to write to separate logs, modify the Config file to add a Log scheme under Config Logging. Refer to the Logging section of the IBM Tivoli Directory Integrator 6.0: Users Guide. The -l parameter for ibmdisrv.bat does not redirect the ibmdi.log information. The log specified by this parameter only captures a limited amount of console output. For this reason it is not used above when launching the server. The System.out.println statements in the connector developed in Chapter 7, TDI connector for Content Manager development on page 363 go to the console output, so the -l parameter could be used with the Content Manager Config to redirect this output to a separate log file.
Important: If the Config has been password protected, the -P parameter must be used to specify the password.
11.3.3 Stop the Tivoli Directory Integrator servers

Each server launched in 11.3.2, Start the Tivoli Directory Integrator servers on page 474 has an event handler that will run indefinitely. To stop the server, go to the command window from which it was launched and terminate the batch file by pressing Ctrl+C.
11.4 Tivoli Identity Manager customization

Complete each of the following sections found Chapter 9, Tivoli Identity Manager customization on page 411: 1. Create Identity Manager Services. For details, refer to 9.1, Create Identity Manager Services on page 412. 2. Create Organizational Units and Persons. For details, refer to 9.2, Create Organizational Units and Persons on page 415. 3. Create and Grant Organizational Roles For details, refer to 9.3, Create and Grant Organizational Roles on page 419. 4. Modify the user interface. For details, refer to 9.4, Modify the user interface on page 421.
475
5. Create the Password Policy. For details, refer to 9.5, Create the Password Policy on page 425. 6. Create Workflows. For details, refer to 9.6, Create Workflows on page 426. 7. Create Identity Manager Provisioning Policies. For details, refer to 9.7, Create Identity Manager Provisioning Policies on page 434.
11.5 Deploy provisioning portlet application

This section describes how to deploy the User Provisioning application to the portal runtime. This section includes the following tasks to deploy the provisioning portlet application: 1. Deploy the TIM Portlet Service 2. Define the TIM Portlet Service 3. Enable sessions for anonymous users 4. Create TIM administrator user in Directory node 5. Create a Credential Vault Slot 6. Install the User Provisioning portlets 7. Create Portal pages 8. Add portlets to pages 9. Assign resource permissions 10.Externalize resources to Tivoli Access Manager
11.5.1 Deploy the TIM Portlet Service

Copy the TimService.jar file from the C:\6692code\user_provisioning ITSO sample code directory to the Portal Server node C:\WebSphere\PortalServer\shared\app directory.
11.5.2 Define the TIM Portlet Service

To update the portlet service registry to register the service and provide the configuration parameters, do the following steps: 1. Navigate to the <wp_root>\shared\app\config\services directory on the Portal Server node. 2. Open the PortletServiceRegistryService.properties.
476
3. Add the entries found in Example 11-1 to the bottom of the PortletServiceRegistryService.properties. The contents of Example 11-1 can be found in the c:\6692code\user_provisioning\TIMPortletServiceProperties.txt file.
Example 11-1 Register service in PortletServiceRegistryService.properties # Register service for communication with Tivoli Identity Manager API com.ibm.sst.up.tim.servicelayer.TimApiServiceIBM=com.ibm.sst.up.tim.servicelaye r.TimApiServiceImpl jndi:com.ibm.sst.up.tim.servicelayer.TimApiService=com.ibm.sst.up.tim.servicela yer.TimApiServiceImpl # Configuration parameters for TimApiServiceImpl com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.tenantDN = ou=ITSO,dc=com com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.defaultOrg= erglobalid=00000000000000000000,ou=ITSO,dc=com com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.itimAdmin = itim manager com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.password=secret com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.appServerURL=iiop://timwin1.i tso.ral.ibm.com:2809 com.ibm.sst.up.tim.servicelayer.TimApiServiceImpl.loginContext=ITIM
11.5.3 Enable sessions for anonymous users

In the ITSO example scenario, anonymous users will need to access the reset password and self-register portlets. By default, anonymous users do not get sessions created for them. To enable sessions for anonymous users, do the following steps: 1. Navigate to the <wp_root>\shared\app\config\services directory on the Portal Server node. 2. Open the NavigatorService.properties file. 3. Modify the following value in the NavigatorService.properties file.
public.session=true
4. Save the NavigatorService.properties file. 5. Restart the WebSphere_Portal application server for the changes to take effect.
C:\WebSphere\AppServer\bin\stopserver WebSphere_Portal -username wpsbind -password <your_password> C:\WebSphere\AppServer\bin\start WebSphere_Portal
477
11.5.4 Create TIM administrator user in Directory node

The user provisioning portlets create an LtpaToken for a Tivoli Identity Manager administrator account to communicate with the Tivoli Identity Manager server. The Tivoli Identity Manager administrator account must be created in the Tivoli Directory Server used by the WebSphere Portal server, which in our example is on the Directory node. To create the TIM administrator account in the Tivoli Directory Server, do the following steps: 1. Open a command window on the Directory node. 2. Copy the c:\6692code\user_provisioning\tim-tdi.ldif file to the c:\temp directory on the Directory node. 3. Modify the itim-tdi.ldif to include the desired password of the itim manager user. 4. Navigate to the c:\temp directory. 5. Enter the following command to import the tim-tdi.ldif file:
ldapadd -D cn=root -w? -i tim-tdi.ldif
You should see the following message:

adding new entry uid=itim manager,cn=users,dc=itso,dc=ibm,dc=com
6. Verify the user was added to the Tivoli Directory Server by entering the following command:
ldapsearch -b dc=itso,dc=ibm,dc=com -D cn=root -w? uid=itim*
You should see the entry details for the itim manager account. Note: The same Tivoli Identity Manager administrator user ID and password must be used when configuring the WebSphere Portal Credential Vault in Create a Credential Vault Slot on page 478.
11.5.5 Create a Credential Vault Slot

We will store the TIM administrators credential in the WebSphere Portal Credential Vault. Each portlet that needs to connect to TIM will retrieve the credential from the vault and pass it via the TIM API when creating a connection.
478
Note: When using WebSphere Portal with Tivoli Access Manager, it is possible to have the Credential Vault data store on the Tivoli Access Manager server. We chose to keep this within WebSphere Portal for our scenario. For information on configuring the WebSphere Portal Credential Vault with Tivoli Access Manager, refer to the IBM Redbook, Develop and Deploy a Secure Portal, Using WebSphere Portal V5 and Tivoli Access Manager V5.1, SG24-6325. To create and initialize the vault slot, do the following steps: 1. Ensure the WebSphere_Portal application server is started. 2. Log in to WebSphere Portal as an administrator user (for example, admin):
3. Click the Administration tab. 4. Click Access Credential Vault. 5. Click Add a vault slot. 6. When the Credential Vault page appears, enter the following: Name: itim manager Vault segment: select DefaultAdminSegment (default) Vault resource associated with the vault slot: select new. Provide the resource name: itim manager. Check the Vault slot is shared checkbox. Enter the TIM administrators userid and password. For example, we entered itim manager. Optional: you can provide a description if you would like. Our completed dialog looked like Figure 11-1. Click OK to create the vault slot.
479
Figure 11-1 Defining the Credential Vault slot
11.5.6 Install the User Provisioning portlets

To install the User Provisioning portlets, do the following steps: 1. Ensure the WebSphere_Portal application server is started. 2. Log in to WebSphere Portal as an administrator user (for example, admin):
3. Click the Administration tab. 4. Click Portlet Management Web Modules Install.
480
Tip: Updating the User Provisioning portlets To update the portlet application, click Portlets Manage Applications. Select the portlet application from the list (for example, UserProvisioning.war) and click Update. 5. Enter c:\6692code\user_provisioning\UserProvisioning.war in the Directory field, and then click Next. 6. You should see a listing of the portlets. Click Finish. When complete, you should see a message, Web module was successfully installed.
11.5.7 Create Portal pages

This section describes how to create portal pages for the User Provisioning application. When complete, you will have a hierarchy of portal pages as follows: My Portal User Provisioning Accept New Employee Update Employee Data Change Password Update My Info Reset Password Register To create a new page for the new User Provisioning page under MyPortal, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Portal User Interface Manage Pages. 4. Click My Portal. 5. Click New Page. 6. When the New Page properties page appears, we entered the following information and then clicked OK: Title: User Provisioning 7. You should see a message that the page was created successfully. Click OK.
481
8. Click the Up arrow next to the User Provisioning page to move it up in order to below Welcome (or HR Application) so that it is immediately visible when a user logs on to the portal. 9. Click User Provisioning. 10.Create the Accept New Employee page. a. Click New Page. b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: Accept New Employee c. You should see a message that the page was created successfully. Click OK. 11.Create the Update Employee Info page. a. Click New Page. b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: Update Employee Info c. You should see a message that the page was created successfully. Click OK. 12.Create the Change Password page. a. Click New Page. b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: Change Password c. You should see a message that the page was created successfully. Click OK. 13.Create the Update My Info page. a. Click New Page. b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: Update My Info c. You should see a message that the page was created successfully. Click OK. 14.Create the Reset Password page. a. Click New Page.
482
b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: Reset Password c. You should see a message that the page was created successfully. Click OK. 15.Create the Register page. a. Click New Page. b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: Register c. You should see a message that the page was created successfully. Click OK. When complete, you should see a page like Figure 11-2.
Figure 11-2 User Provisioning Pages
483
11.5.8 Add portlets to pages

To add the User Provisioning portlets to the portal pages, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Portal User Interface Manage Pages. 4. Click My Portal. 5. Click User Provisioning. 6. Add portlets to the Update Employee Info page. a. Click the Pencil icon (Edit Page Layout) next to the Update Employee Info page. b. Click Add portlets in the left-hand window. By default the portal page layout contains two columns. c. From the Edit Layout page, do the following and then click Search: Search by: select Title starts with Search: Update
d. When the search results are displayed, you should see several portlets listed. Check the following portlets to add to the page and then click OK: UpdateEmployeeInfo portlet UpdateRoles portlet
e. After adding the portlets, rearrange them to look like Figure 11-3. f. Click Done.
484
Figure 11-3 Update Employee Info page with portlets
7. Add a portlet to the Accept New Employee page. a. Click the Pencil icon (Edit Page Layout) next to the Accept New Employee page. b. By default the portal page layout contains two columns. Since there is only one portlet to add to this page, select the One column page layout. Click OK to the popup. c. Click Add portlets. d. From the Edit Layout page, do the following and then click Search: Search by: select Title starts with Search: Entitle
485
e. When the search results are displayed, you should see the portlet listed. Check the following portlet to add to the page and then click OK: Entitlement Request portlet f. Click Done. 8. Add a portlet to the Change Password page. a. Click the Pencil icon (Edit Page Layout) next to the Change Password page. b. By default the portal page layout contains two columns. Since there is only one portlet to add to this page, select the One column page layout. Click OK to the popup. c. Click Add portlets. d. From the Edit Layout page, do the following and then click Search: Search by: select Title starts with Search: Password
e. When the search results are displayed, you should see the portlet listed. Check the following portlet to add to the page and then click OK: Password portlet f. Click Done. 9. Add a portlet to the Update My Info page. a. Click the Pencil icon (Edit Page Layout) next to the Update My Info page. b. By default the portal page layout contains two columns. Since there is only one portlet to add to this page, select the One column page layout. Click OK to the popup. c. Click Add portlets. d. From the Edit Layout page, do the following and then click Search: Search by: select Title starts with Search: Update
e. When the search results are displayed, you should see several portlets listed. Check the following portlet to add to the page and then click OK: UpdateMyInfo portlet f. Click Done. 10.Add a portlet to the Reset Password page. a. Click the Pencil icon (Edit Page Layout) next to the Reset Password page.
486
b. By default the portal page layout contains two columns. Since there is only one portlet to add to this page, select the One column page layout. Click OK to the popup. c. Click Add portlets. d. From the Edit Layout page, do the following and then click Search: Search by: select Title starts with Search: Reset
e. When the search results are displayed, you should see the portlet listed. Check the following portlet to add to the page and then click OK: ResetPassword portlet f. Click Done. 11.Add a portlet to the Register page. a. Click the Pencil icon (Edit Page Layout) next to the Register page. b. By default the portal page layout contains two columns. Since there is only one portlet to add to this page, select the One column page layout. Click OK to the popup. c. Click Add portlets. d. From the Edit Layout page, do the following and then click Search: Search by: select Title starts with Search: Self
e. When the search results are displayed, you should see the portlet listed. Check the following portlet to add to the page and then click OK: SelfRegister portlet f. Click Done.
11.5.9 Assign resource permissions

This section describes how to assign resource permissions for the portal pages and portlets.
Assign portal page resource permissions

To modify the portal page resource permissions, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Portal User Interface Manage Pages.
487
4. Click My Portal. 5. Click User Provisioning. 6. Allow all anonymous portal users to access the Register page. a. Click the key icon (Set Page Permission) for the Register page. b. Uncheck the Allow Inheritance check boxes next to User and Privileged User. This turns off permission inheritance for the Register page for users and privileged users; otherwise, the page would always be visible for all authenticated portal users. c. Click Apply. d. Click OK on the popup dialog. e. Click the Pencil icon (Edit Role) next to User. f. Click Add to add a role. g. When the Search page appears, do the following steps: i. Select Users from the Search for Users or User Groups drop-down list. ii. Select cn from the Search by drop-down list. iii. Enter anonymous in the Search field and then click Search. iv. Check Anonymous Portal User. v. Click OK. h. Click the Register link (the link to the page). i. Click Apply. j. Click OK for the confirmation popup. k. Click Done. 7. Repeat the procedure in step 6 to grant access to the Anonymous Portal User for the Reset Password page. 8. Restrict access to the Accept New Employee page. a. Click the key icon (Set Page Permission) for the Accept New Employee page. b. Uncheck the Allow Inheritance check boxes next to User and Privileged User. This turns off permission inheritance for the Accept New Employee page for users and privileged users; otherwise, the page would always be visible for all authenticated portal users. c. Click Apply.
488
d. Click OK for the confirmation popup. e. Click the Edit Role (pencil) icon next to Privileged User. f. Click Add. g. Search for the desired group. Search for Users or User Groups: select User Groups Search on: all available Click Search
h. Check the boxes next to devmanagers and hrmanagers and click OK. i. Click Accept New Employees link. j. Click Apply. k. Click OK to the popup. l. Click Done. 9. Repeat the previous step for removing inheritance and adding page permissions for the pages and groups listed in Table 11-1.
Table 11-1 Assign page permissions Page Update Employee Info Change Password Update My Info Group devmanagers, hrmanagers A_Legals, A_Publishers, A_Researchers, A_Supervisors, devmanagers, hrmanagers, hrspecialists A_Legals, A_Publishers, A_Researchers, A_Supervisors, devmanagers, hrmanagers, hrspecialists
Assign portlet resource permissions

To modify the portlet permissions, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Access Resource Permissions. 4. Click Portlets. 5. Filter the list of displayed portlets by entering Reset in the Title contains search box, and click Search. 6. Assign access permissions to the Reset Password portlet: a. Click the Key icon (Assign Access) next to the Reset Password portlet.
489
b. Click the Pencil icon (Edit Role) next to Privileged User. c. Click Add. d. When the Search page appears, do the following steps: i. Select Users from the Search for Users or User Groups drop-down list. ii. Select cn from the Search by drop-down list. iii. Enter anonymous in the Search field and then click Search. iv. Check Anonymous Portal User. v. Click OK. e. Click Rest Password portlet link. f. Click Apply. g. Click OK to the popup. h. Click Portlets. 7. Repeat the procedure in the previous step to assign access permissions to the Self Register portlet. 8. Assign access permissions to the Entitlement Request portlet. a. From the Resource Permissions page, search for Entitlement Request portlet. b. Click the Key icon (Assign Access) next to the Entitlement Request portlet. c. Click the Pencil icon (Edit Role) next to Privileged User. d. Click Add. e. When the Search page appears, do the following steps: i. Select User Groups from the Search for Users or User Groups drop-down list. ii. Select All available from the Search by drop-down list. iii. Click Search. iv. Check devmanagers and hrmanagers. v. Click OK. f. Click Entitlement Request portlet link. g. Click Apply. h. Click OK to the popup. i. Click Portlets. 9. Repeat the procedure in the previous step to assign permissions for the remaining portlets and groups defined in Table 11-2.
490
Table 11-2 Portlet access permissions by group Portlet UpdateEmployeeInfo UpdateRoles UpdateMyInfo Password Group devmanagers, hrmanagers devmanagers, hrmanagers A_Legals, A_Publishers, A_Researchers, A_Supervisors, devmanagers, hrmanagers, hrspecialists A_Legals, A_Publishers, A_Researchers, A_Supervisors, devmanagers, hrmanagers, hrspecialists
11.5.10 Externalize resources to Tivoli Access Manager

Thus far we have configured the portal application resource permissions within WebSphere Portal. If you would like Tivoli Access Manager to perform authorization functions for the portlet applications (user provisioning, HR, and document management), you will need to externalize the resource permissions from WebSphere Portal to be managed by Tivoli Access Manager. For details, refer to the Develop and Deploy a Secure Portal, Using WebSphere Portal V5 and Tivoli Access Manager V5.1, SG24-6325.
491
492
12
Chapter 12.
Application walkthrough
This chapter provides an application walkthrough to validate the use cases defined in 3.3, Use case model on page 101 for the ITSO example scenario. The walkthrough will cover each path in the user provisioning application. However, it will only cover selected paths in the HR and document management applications to validate that users were provisioned properly. The chapter is organized into the following sections, which map to each of the use cases for the ITSO example scenario: Prerequisites Add new employee Employee self-registration HR manager employee approval and assign roles Employee password reset Employee password change Employee self-care Employee assigns document management report Employee role changed by manager Employee department change by manager
493
12.1 Prerequisites
Before performing the application walkthrough, ensure that the following prerequisites have been met: 1. Runtime environment installation and configuration. For details, refer to the following chapters: Chapter 4, Runtime environment installation on page 129. Chapter 5, Runtime environment configuration on page 235. 2. Start servers/Windows services on each node in the runtime environment. 3. Deploy the HR, document management, and user provisioning applications. For details, refer to Chapter 11, Application deployment on page 469. Note: As part of the application deployment, users and groups have been defined to seed the environment. This includes administrator users such as the hrspecialist1 used to add a new employee, hrmanager1 used to approve a new employee self-registration, and devmanager1.
12.2 Add new employee

The HR Specialist creates the initial profile for a new employee in the human resources application. The HR Specialist enters the employee's name and department in the HR application. An employee record is created in the HR application database containing the employee name, employee department, and a generated employe number. This procedure corresponds to UCF01 Hire Employee defined in Table 3-3 on page 104. To add a new employee to the ITSO HR application as the HR Specialist, do the following steps: 1. The HR Specialist enters the following URL in a Web browser to access the ITSO HR application:
https://wswin1.itso.ral.ibm.com/portal/wps/portal
Note: In this case the HR Specialist user ID already exists in the system and they will authenticate via the WebSEAL on the Reverse Proxy node. 2. When the Welcome page appears as seen in Figure 12-1, click Log in.
494
Figure 12-1 Welcome page
3. When the Login page appears, enter the following login credentials for the HR Specialist as seen in Figure 12-2, and then click Login: Username: hrspecialist1 Password: <hrspecialist1_password>
Figure 12-2 Login page
Chapter 12. Application walkthrough
495
4. When returning to the Welcome page you will notice several portal page tabs now that the user has authenticated. Click HR Application. 5. Click New Employee. 6. When New Employee page appears, enter the following information as seen in Figure 12-3, and then click Submit: First Name: John Last Name: Doe Department: select HRD01 Salary: 100000 You should see a message like the following:
You are assigned an employee number: 100007
The new employee will need the employee number to self-register in the user provisioning portlet application.
Figure 12-3 HR Application - New Employee page
7. Logout by clicking the Log out button.
496
12.3 Employee self-registration

Once the HR specialist has created the new employee and given the new employee their employee number, the new employee can self-register. The new employee navigates to the ITSO site to register for an account. The employee submits a request for an account using their employee number. The portlet passes the employee's completed request to the Tivoli Identity Manager, which requests approval from the employee's manager. This procedure corresponds to UCF02 Employee self-registration defined in Table 3-4 on page 104. To self-register with the ITSO user provisioning application as the new employee, do the following steps: 1. The new employee enters the following URL in a Web browser to access the ITSO user provisioning application:
2. When the Welcome page appears, click User Provisioning Register. 3. When the Self-Registration page appears, enter the following information as seen in Figure 12-4, and then click Submit: Employee Number: 100007 Note: The employee number is generated by the HR Specialist in 12.2, Add new employee on page 494 and provided to the new employee. User ID: jdoe Mothers Maiden Name: Ray You should see the following message:
Self Registration request has been submitted for User ID jdoe with Employee Number 100007 for approval.
4. Click OK to continue.
497
Figure 12-4 New employee self-registration
Tip: To verify that the request was submitted and pending approval in Tivoli Identity Manager, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager).
http://timwin1.itso.ral.ibm.com/enrole/logon
2. Click HOME (default). 3. Click View Pending Requests. You will see the pending requests in a list. If the request has already been processed, click View Completed Requests. 4. Click the request, and then view the details on the General, Data, Audit Log tabs.
498
12.4 HR manager employee approval and assign roles

Once the new employee has self-registered, the request is awaiting approval. The employees manager navigates to the ITSO identity and access management system to process outstanding requests. The manager sees the new employees request, selects a role to assign to the employee, and approves the request. Once approved, the Identity Manager creates accounts for the new employee in each application that is associated with the role assigned to the employee. A password is generated for each account and sent to the manager. This procedure corresponds to UCF03 Approval and Role Assignment defined in Table 3-5 on page 105. To approve the new employee and assign roles as the employees manager, do the following steps: 1. The manager of the employee enters the following URL in a Web browser to access the ITSO user provisioning application:
2. When the Welcome page appears, click Log in. 3. When the Login page appears, enter the following login credentials for the manager (for example, hrmanager1) of the employee, and then click Login: Username: hrmanager1 Password: <hrmanager1_password> 4. When the Welcome page appears, click User Provisioning Accept New Employee. 5. When the Accept New Employee page appears, do the following actions as seen in Figure 12-5 and then click Submit: Role: check A_Supervisors Select Approve
499
Figure 12-5 Accept New Employee page
Note: Once the manager submits the approval, the user will be provisioned. In our example, the self-registration request will be completed. Tivoli Identity Manager will enforce the provisioning policy for each back-end system. TIM will provision the users by passing the request to the Tivoli Directory Integrator event handlers for Tivoli Directory Server, DB2 Content Manager, and the HR application DB2 UDB database. In the case of Tivoli Access Manager, the Tivoli Identity Manager Agent for TAM will be used to provision the user. A change request will be made to update the role of the user within Tivoli Identity Manager. The change request is scheduled to occur 1 minute later to give TIM time to complete the registration request. 6. Click Log out.
500
12.5 Employee password reset

In practice, a generate password would be sent to the new employee. In our example, we chose to force the new employee to reset the password and retrieve it on screen to eliminate the need to set up a mail system for our scenario. The employee is unable to login to the system, thus will request a password reset. The password reset portlet will request a challenge question (mothers maiden name) provided during self-registration. Once submitted, the challenge answer is validated. A password is generated that satisfies the password policy. The password is provisioned to all accounts for the employee and displayed to the employee. Upon completion of this use case, the employee is expected to change the password as outlined in UCF04. This procedure corresponds to UCF06 Employee Password Reset defined in Table 3-8 on page 107. To reset the employee password, do the following steps: 1. The employee enters the following URL in a Web browser to access the ITSO user provisioning application:
2. When the Welcome page appears, click User Provisioning Reset Password. 3. When the Reset Password page appears, enter the following information as seen in Figure 12-6, and then click Submit: Employee Number: 100007 User ID: jdoe What is your mothers maiden name?: Ray Note: After clicking Submit, you should see a message like this one:
Your new password is on375kwj
As pointed out previously, in practice you would typically e-mail this type of information. In our example, we chose to present this information on screen to eliminate the need for a mail system in our scenario.
501
Figure 12-6 Employee Password Reset
502
12.6 Employee password change

When an employee password is reset, the new password is generated and typically alpha numeric in a format not easily remembered. For this reason, the ITSO user provisioning application provided the ability to submit password change requests to the employees desired password. The employee will log in to the system and submit a password change request. Once submitted, the new password is validated against the password policy in place. All accounts for the employee are then updated automatically with the new password. This procedure corresponds to UCF04 Employee Password Change defined in Table 3-6 on page 106. To change the employee password, do the following steps: 1. The employee enters the following URL in a Web browser to access the ITSO user provisioning application:
2. When the Welcome page appears, click Log in. 3. When the Login page appears, enter the following login credentials for the employee (for example, John Doe) and then click Login: Username: jdoe Password: <jdoe_password> Note: This may be the password generated by the password reset or simply a password change by the employee. 4. Click User Provisioning Change Password. 5. When the Change Password page appears, enter the following information as seen in Figure 12-7 on page 504, and then click Submit: Old Password: <old_password> New Password: <new_password> Confirm New Password: <new_password> Note: When the employee clicks Submit to change the password, Tivoli Identity Manager will evaluate the new password with the password policy defined in 9.5, Create the Password Policy on page 425.
503
Figure 12-7 Employee Change Password page
6. Click Log out.
12.7 Employee self-care

Employee self-care is a portlet interface for the users to updated their personal information. An employee will log in to the system and update their information in the employee record. Once the changes are submitted, each modified attribute is provisioned to each application that stores the attribute. This procedure corresponds to UCF05 Employee Self-care defined in Table 3-7 on page 106. To change the employee personal information, do the following steps: 1. The employee enters the following URL in a Web browser to access the ITSO user provisioning application:
2. When the Welcome page appears, click Log in.
504
3. When the Login page appears, enter the following login credentials for the employee (for example, John Doe) and then click Login: Username: jdoe Password: <jdoe_password> 4. Click User Provisioning Update My Info. 5. When the page, Welcome to Update My Information appears, we entered the information displayed in Figure 12-8, and then clicked Submit.
Figure 12-8 Update My Information page
505
Note: In Figure 12-8, notice the Bank ID, Bank Account, and Bank Transit fields. This information is updated in the HR application database directly. The remaining fields in Figure 12-8, are updated by Tivoli Identity Manager and provisioned accordingly. 6. Click OK on the confirmation page.
12.8 Employee assigns document management report

In the ITSO example scenario, the HR manager can assign roles to the new employee during the approval of the employ self-registration request. In our example, we assigned the A_Supervisor (role within WebSphere Portal, and group within DB2 Content Manager) to the John Doe employee. Users added to A_Supervisors can create new research reports in the ITSO custom document management application, and assign them to the A_Researcher (role within WebSphere Portal, and group within DB2 Content Manager). A researcher employee can then accept the research report and add the content for the research report, at which point the report progresses through a workflow in Content Manager with stages requiring approval (Supervisor, Legal, Publisher). For a full walkthrough of the ITSO document application refer to Run and verify the document management application on page 575. This section will demonstrate how the new employee named John Doe that was assigned A_Supervisors role/group can create a research report in the ITSO document management application. This will validate the user provisioning (create user, set ClientUserEditSSO privilege set, add to A_Supervisor group) to the DB2 Content Manager system. To create a research report in the ITSO document management application, do the following steps: 1. The employee enters the following URL in a Web browser to access the ITSO user provisioning application:
2. When the Welcome page appears, click Log in. 3. When the Login page appears, enter the following login credentials for the employee (for example, John Doe) and then click Login: Username: jdoe Password: <jdoe_password>
506
4. Click ITSO DM. 5. Click Assign Research. 6. When the ITSO DM - Assign Research Reports portlet appears, we entered the following information as seen in Figure 12-9 and then clicked Create: Topic: Research report 1 Title: Research report 1 Note: You should see a message like the following after clicking Create:
The report has been created.
This validates that the provisioning to DB2 Content Manager, authentication, and authorization is working properly.
Figure 12-9 Supervisor assigns research report to researchers group
7. Click Log out to log off as the Supervisor user. Tip: Content Manager Client for Windows For test purposes, we used the DB2 Content Manager Client for Windows to verify the document was created. We selected Search Basic. Select the desired item type (Research Report). For the Title of Research Report drop-down, we selected Is not null and clicked OK to initiate the search.
507
12.9 Employee role changed by manager

In this scenario, the employees manager changes the role assignment of the employee. The employees access to applications is automatically updated to reflect the new role. This procedure corresponds to UCF07 Role Change defined in Table 3-9 on page 108. To change an employee role, do the following steps: 1. The manager of the employee enters the following URL in a Web browser to access the ITSO user provisioning application:
2. When the Welcome page appears, click Log in. 3. When the Login page appears, enter the following login credentials for the manager (hrmanager1) and then click Login: Username: hrmanager1 Password: <hrmanager1_password> 4. When the Welcome page appears, click User Provisioning Update Employee Info. 5. Enter 100007 (John Doe employee #) in the Employee Number field of the Employee Roles portlet as seen in Figure 12-10, and then click Submit.
Figure 12-10 Employee Roles portlet
508
6. The Employee Roles portlet should be populated with the employees current role assignments. When we initially assigned roles for John Doe, only the A_Supervisors role was checked. a. Check the following roles (see Figure 12-11) to allow John Doe to be a superuser in the ITSO custom document management application: Check A_Legals Check A_Publishers Check A_Researchers
b. Click Change Role.
Figure 12-11 Select desired roles for employee
7. Click Log out. 8. Verify that the John Doe employee has full access to the ITSO custom document management application.
509
For details on using the ITSO document management application, refer to Run and verify the document management application on page 575.
12.10 Employee department change by manager

In this scenario, a manager transfers an employee in his department to a new department. The transfer is not complete until the employees new manager approves the change and assigns a role to the employee. This procedure corresponds to UCF08 Department change defined in Table 3-10 on page 108.
Change employee department

To change an employee to a new department, do the following steps: 1. The manager of the employee enters the following URL in a Web browser to access the ITSO user provisioning application:
2. When the Welcome page appears, click Log in. 3. When the Login page appears, enter the following login credentials for the manager (hrmanager1) and then click Login: Username: hrmanager1 Password: <hrmanager1_password> 4. When the Welcome page appears, click User Provisioning Update Employee Info. 5. Enter 100007 (John Doe employee #) in the Employee Number field of the Update Employee Information portlet as seen in Figure 12-12 on page 511, and then click Submit.
510
Figure 12-12 Update Employee Information portlet
6. When the Update Employee Info portlet appears with the employees current information, specify the following information as seen in Figure 12-13, and then click Update: Division: select DEV10 Department Number: select DEV01
511
Figure 12-13 Update Employee Info - change department
7. Click Log out.
Accept new employee transfer

The manager of the receiving department must approve the transfer of the employee. 1. The manager of the employee enters the following URL in a Web browser to access the ITSO user provisioning application:
2. When the Welcome page appears, click Log in. 3. When the Login page appears, enter the following login credentials for the manager (devmanager1) and then click Login: Username: devmanager1 Password: <devmanager1_password>
512
4. When the Welcome page appears, click User Provisioning Accept New Employee. 5. When the Accept New Employee page appears, do the following actions as seen in Figure 12-14 and then click Submit: Role: no selection Note: The DEV01 department does not have access to the ITSO document management application, thus the roles for this application are not listed. Select Approve Note: As a reminder, the change request is scheduled to occur 1 minute later to give TIM time to complete the registration request.
Figure 12-14 Accept New Employee after transfer
6. Click Log out. 7. Verify the John Doe employee can login and has the proper roles. Congratulations! You are now a security master.
513
514
13
Chapter 13.
Administration
There are many administration tasks that an IT specialist or security administrator will perform once the runtime has been implemented and the applications are deployed. Many of these tasks are detailed in the appropriate product documentation. This chapter focuses on administration tasks unique to the ITSO identity and access management system. First, we describe how to generate and review audit trail reports to ensure our ITSO identity and access management system is working properly. In addition, we have included common troubleshooting techniques used to resolve installation and configuration issues found while writing the redbook. The chapter is organized into the following sections: Generate and view a security audit report Log files Troubleshooting
515
13.1 Generate and view a security audit report

This section describes how to generate and review security audit reports to ensure that the ITSO identity and access management system is working properly. Tivoli Identity Manager administrators can generate reports for various types of transactions such as Accounts added, Accounts restored, Users added, operations requested by the users, and requests that are rejected. Tivoli Identity Manager installation creates some pre-defined Reports and a Report Designer interface. Administrators can access these Reports and the Report Designer from the Tivoli Identity Manager user interface. The output generated by the pre-defined Reports cannot be modified. Administrators can generate custom Reports using the built-in Report Designer or a third party report designer. In addition to the reports, Tivoli Identity Manager users and administrators can also view the transactions that are completed or pending, from the Tivoli Identity Manager user interface by clicking the View Pending Requests and View Completed Requests icons located in the Home task bar.
Example for generating the Account Add Report

To generate and view the a security report of new accounts created in the system during the previous month, do the following steps: 1. Login to Tivoli Identity Manager as an administrator (for example, itim manager). 2. Click Report. 3. When it displays the Reports Submenu page, click Operation Report. 4. When it displays the Operation Report page as shown in Figure 13-1, change the month value for the Start Date using the drop-down menu to the previous month. For example, if todays date is 05.31.2005 (31st May 2005), then change the month to 4. 5. Click Submit. It should generate the report and display it in portable document format. The sample report is shown in Figure 13-2. 6. The Report contains several entries and each entry is separated by a small line. Some of the fields shown in the Account Add Report for each entry are described here: Request Type: This field represents the type of request. In this example, its value is Account Add. Requested By: The person who requested the Account to be created. In this example, it is System Administrator.
516
Figure 13-1 Account Add Operations Report Generation
Requested For: The person for whom the Account is created. In this example, the report has entries for hr manager1, hr specialist1, and dev manager1. Subject: The Service on which the Account is created. In this example, the report has entries for Tivoli Access Manager and ITIM Service. State: The state of the operation. In this example, all entries contain the value Completed. Result Summary: This field shows the error messages generated while adding the Account. If this field is blank, then it implies that the Account is added successfully.
Chapter 13. Administration
517
Figure 13-2 Account Add Operations Report
Note: The report shows that the Account Add operation failed for hr manager1, hr specialist1 Persons on Tivoli Access Manager service. The reason for failure is the accounts were already created in Tivoli Access Manager user registry. So, these errors can be ignored. 7. Close the Report window and click Logout to logout of Tivoli Identity Manager.
13.2 Log files

As expected in a solution of this size, there are a number of log files to refer to if it doesnt operate as expected. We found the following information to be useful.
518
Tivoli Identity Manager: <was_home>\logs\itim.log Its not a log, but the history of completed requests can be viewed by the administrator within the Tivoli Identity Manager client. The requests Data and Audit Log tabs may have useful information if the request is not successful. Tivoli Directory Integrator: c:\ibm\tdiwork\ibmdi.log (working directory) WebSphere Portal: <wps_home>\log\wps*.log <wps_home>\log\SystemOut.log <wps_home>\log\SystemErr.log WebSphere Application Server: <was_home>\logs\server1\SystemOut.log <was_home>\logs\server1\SystemErr.log
13.3 Troubleshooting
This section includes troubleshooting tips for addressing installation and configuration issues we encountered while writing the redbook.
13.3.1 Tivoli Directory Server

When using Tivoli Directory Server V5.2 Configuration Tool + Fixpack 2, and DB2 Universal Database V8.2 + Fixpack 7a, we were not able to create the LDAP database. In addition, the log of previous failure displayed instead of configuration options and no way to clear log. To work around this issue, we had to first uninstall the Tivoli Directory Server V5.2, re-install Tivoli Directory Server, install DB2 Universal Database V8.2 + Fixpack 8, and then create the Tivoli Directory Server LDAP database. For more information, refer to 4.2.5, Tivoli Directory Server V5.2 installation on page 147.
13.3.2 Tivoli Identity Manager

This section includes tips for troubleshooting installation and configuration issues we encountered when using Tivoli Identity Manager V4.5.1.
519
WebSphere Application Server V5.1 and TIM V4.5.1 FP42

At the time of writing, Tivoli Identity Manager V4.5.1 FP42 was the current level. We found that when installing this level of product on WebSphere Application Server V5.1, Tivoli Identity Manager was not deployed properly to the server1 application server. To work around this install failure, we installed Tivoli Identity Manager V4.5.1 FP16, verified the Tivoli Identity Manager Server, and then installed Tivoli Identity Manager V4.5.1 FP42. This worked most of the time.
Tivoli Identity Manager V4.5.1 FP42 install failure

In one instance the Tivoli Identity Manager V4.5.1 FP42 installed failed by hanging during the update of the database toward the end of the installation. We then reran the FP42 install, which appeared to install successfully. During the install we noticed that on a system with 1 GB RAM, there was very little free memory which may have been a contributing factor for the initial failure. We found that the FP42 installer had reconfigured the configuration files to the default settings. We recommend that before installing Tivoli Identity Manager V4.5.1 FP42, that you first back up the C:\itim45\data directory containing the configuration files. To resolve this issue, we had to uninstall (see workaround in Tivoli Identity Manager uninstall JVM failure on page 520), install Tivoli Identity Manager V4.5.1 FP16 full install, and then install Tivoli Identity Manager V4.5.1 FP42.
Tivoli Identity Manager uninstall JVM failure

In our example, the Identity Manager node where Tivoli Identity Manager was installed had Windows 2000 Server + Service Pack 4 installed with WebSphere Application Server V5.1. We found that the Tivoli Identity Manager uninstall program had a configuration file named Uninstall ITIM.lax (space between Uninstall and ITIM), that referenced the WebSphere Application Server V5.1 JRE. The Tivoli Identity Manager uninstall program only supports the JVM 1.3.1 and WebSphere Application Server V5.1 uses JVM 1.4. To work around this issue, we did the following tasks: 1. Install the Sun Java 2 Standard Edition (J2SE) V1.3.1_04 JRE found at:
In our example, we installed to the c:\JavaSoft\JRE\1.3.1_04 directory. 2. Navigate to the c:\itim45\data folder.
520
3. Open the Uninstall ITIM.lax file in a text editor. 4. Modify the JVM path to point to the JVM 1.3.1: Original:
lax.nl.current.vm=c:\WebSphere\AppServer\java\bin\javaw.exe
Modified:
lax.nl.current.vm=c:\JavaSoft\JRE\1.3.1_04\bin\javaw.exe
5. From the Windows Explorer, navigate to the c:\itim\itimUninstallData directory and double-click Uninstall ITIM.exe to start the Uninstall wizard.
Tivoli Identity Manager Web interface requires Java plug-in

The Tivoli Identity Manager V4.5.1 Web interface - configuration menus require a Java plug-in for the Web browser to run applets. We found that the Tivoli Identity Manager Web interface was very particular in the level of the Java plug-in required for the configuration applets to work properly. The Java plug-in will need to be installed on systems where you will be using a Web browser to connect to the Tivoli Identity Manager Web interface. If the system with the Web browser accessing the Tivoli Identity Manager Web interface is connected to the Internet, when using the Configuration User Interface Customization menu, you will be redirected to the Sun site to download the Sun Java 2 Standard Edition (J2SE) V1.3.1_04 JRE. If you are not connected to the Internet, manually download and install Sun Java 2 Standard Edition (J2SE) V1.3.1_04 JRE at:
13.3.3 Tivoli Identity Manager Agent for TAM account create fails
At the time of writing the redbook, the most current version of the Tivoli Identity Manager Agent for TAM was V4.5.12. We found that when attempting to create a TAM account from Tivoli Identity Manager, the creation failed. To work around this issue, we used Tivoli Identity Manager Agent V4.5.9 for TAM. This problem has been reported to the IBM Tivoli Identity Manager organization and is planned to be fixed in V4.5.13.
521
13.3.4 WebSphere Portal V5.1 Test Environment

WebSphere Portal V5.1 runs on WebSphere Application Server V5.1. When a WebSphere Portal V5.1 Test Environment is created, it creates a copy of the WebSphere Application Server V5.1 configuration XML files. We found that with Rational Application Developer V6.0, each time a configuration change was made on the WebSphere Application Server V5.1 server1, we had to create a new WebSphere Portal V5.1 Test Environment server to pickup the changes made in WebSphere Application Server. For example, we were unable to use the WebSphere Application Server Administrative Console within the WebSphere Portal v5.1 Test Environment. When a WebSphere Portal v5.1 Test Environment server is created it will copy the server1 configuration which was set up in 6.4.6, Tivoli Identity Manager V4.5.1 API installation on page 356. For this reason, make sure that the Tivoli Identity Manager JARs are installed and the JAAS configuration is completed for server1 before creating a WebSphere Portal v5.1 Test Environment server. Otherwise you will need to create a new WebSphere Portal V5.1 Test Environment server after the configuration.
13.3.5 Page configuration reset when Portal Test Environment restarted

We found that when using the WebSphere Portal V5.1 Test Environment within Rational Application Developer, the portal page configuration was reset each time the server was restarted. To work around this issue, you could use an external WebSphere Portal V5.1 Test Environment. The trade-off is that you will need to export a WAR file from Rational Application Developer, and deploy the WAR file on the WebSphere Portal V5.1 server to perform testing.
522
Part 3
Part
Appendixes
523
524
Appendix A.
HR application
The HR application architecture uses a portal front-end and an EJB back-end. The HR application can be deployed to the runtime environment to further demonstrate Tivoli Identity Manager user provisioning to WebSphere Portal, Tivoli Directory Server and Tivoli Access Manager. The HR application data is stored in the HR DB2 UDB database. This appendix provides an overview of the HR application and describes how to deploy the application to the runtime environment. Lastly, although we do not explain how to develop this type of application, we provide instructions for importing and configuring the HR application in Rational Application Developer. The appendix is organized into the following sections: Introduction to the HR application Deploy the HR application to runtime environment Run the HR application in the runtime environment Set up HR application in Rational Application Developer
525
Introduction to the HR application

The HR application provides employees with the ability to submit vacation requests which can be approved or rejected by their managers. It also allows the addition of new employees and the update of salary information. The application uses a portal based front-end to manage user interaction and a EJB back-end for persistence. The front-end consists on several portlets which provide each functionality to the user: Welcome: a simple portlet with a welcome page Vacation Request: input form for vacation requests My HR Requests: shows the users vacation requests Process HR Requests: allows a manager to approve or reject the requests NewEmployee Portlet: allows the creation of new employees A high level description of the HR Application architecture is shown in Figure A-1.
Back-end Web Container H R P P P o r t l e t S e r v I c e HR AppServlet S S S E S S I O N F A A D E CMP EJB CMP EJB CMP EJB Database EJB Container
Front-end
HTTP connection
. . .
. . .
. . .
PortletServiceRegistryService.properties
Figure A-1 High level architecture for HR application
526
Each portlet provides the visible user interface and interacts with an implementation of the HRPortletService interface. This class is designed to encapsulate the communication between the front-end and the back-end, using different HTTP connections for each service. These connections are configured in the PortletServiceRegistryService.properties file. The entry point for the back-end is given by the HRAppServlet Web module, containing one servlet per service provided. Each servlet will interact with the HRRequestSession session bean which acts as a session facade. Each request received by the facade will make use of factories and action classes performing the actual business logic. Finally, the persistence layer is implemented using CMP entity beans.
Deploy the HR application to runtime environment

This section describes how to deploy the HR application in the ITSO identity and access management system runtime environment. The HR application deployment tasks are organized as follows: 1. Requirements to deploy and run the HR application 2. ITSO sample code download and unpack 3. Import users and groups into LDAP directory via ldif file 4. Create the HR application database 5. Deploy the HR application EAR file 6. Install the HR application shared libraries 7. Deploy the HR application WAR file 8. Modify the PortletServiceRegistryService.properties file 9. Create the portal pages 10.Add portlets to pages 11.Assign resource permissions 12.Additional configuration when deployed with Tivoli Access Manager
Requirements to deploy and run the HR application

For a high level understanding of the runtime environment required for the HR application as part of the ITSO identity and access management system, refer to 3.4.4, Runtime topology and product mapping on page 127. For detailed installation and configuration information for the runtime environment, refer to the following: Chapter 4, Runtime environment installation on page 129 Chapter 5, Runtime environment configuration on page 235
Appendix A. HR application
527
ITSO sample code download and unpack

Import users and groups into LDAP directory via ldif file
This section describes how to import users and groups into the LDAP directory for the ITSO working example using the c:\6692code\hrapp\itso-hr.ldif. Note: Initially, we will create users manually by importing users into the Tivoli Directory Server via an ldif file to seed the LDAP directory with users and groups listed in Table A-1. In addition, the user will need to be created in the HR application database. For example, the hrspecialist1 will be used to create a new employee in the HR application. The new employee will self register with the provisioning portlet application, given the employee number provided by the hrspecialist1. The request is sent to Tivoli Identity Manager and is pending approval by hrmanager1. Then, the hrmanager1 user will select the role (groups) to assign the new employee such that they have proper access to applications, as well as deny or approve the user provisioning request. Once the hrmanager1 approves the user provisioning request, the user is provisioned based on the TIM policies and workflow configured to the external systems (Tivoli Directory Server, Tivoli Access Manager, WebSphere Portal, and DB2 Content Manager). Table A-1 includes a listing of the HR application users and groups.
Table A-1 ITSO HR application users and groups Groups hrspecialists hrmanagers devusers devgroups devmanagers devmanager1 Users hrspecialist1 hrmanager1
To import the users and groups via the itso-hr.ldif file, do the following steps:
528
1. Ensure that you have created the suffix DN: dc=itso,dc=ibm,dc=com, users and groups for WebSphere Portal. When following the ITSO procedure, this was done in 5.3.1, Create a suffix on page 255. 2. Stop the IBM Tivoli Directory Server V5.2 Windows service. 3. Copy the ITSO provided c:\6692code\hrapp\itso-hr.ldif file to a temporary directory (for example, c:\temp) on the Directory node. 4. Modify the value of the userpassword in the itso-hr.ldif file for your environment. 5. Start the Tivoli Directory Server Configuration Tool by clicking Start Programs IBM Tivoli Directory Server V5.2 Directory Configuration. 6. Select Import LDIF data. 7. When the Import LDIF Data page appears, we entered the following and then clicked Import (bottom of page): Path and LDIF file name: c:\temp\itso-hr.ldif Select Standard import After the import has finished successfully, a message will be displayed reporting how many entries have been imported into the directory server. 8. When the import is complete, click Close. Close the Configuration Tool. 9. Restart the IBM Tivoli Directory Server V5.2 Windows service. 10.Verify the LDAP entries where created properly by performing an LDAP search. For example, we entered the following from a command window on the Directory Server node:
ldapsearch -h tdiwin1.itso.ral.ibm.com -b dc=itso,dc=ibm,dc=com -D uid=wpsbind,cn=users,dc=itso,dc=ibm,dc=com -w password -s sub uid=hrspecialist1
Where password is the defined password for wpsbind.
Create the HR application database

To create the HR application database, do the following steps: 1. Logon using a database administrator user or a user with database creation capabilities. 2. Open DB2 Command Window by clicking Start Programs IBM DB2 Command Line Tools Command Window. 3. Change directory to c:\6692code\hrapp and execute createDB.bat. The HR database will be created containing the required tables using the SSTDB1 schema.
529
4. To insert the sample data into the tables, execute insertData.bat in the DB2 Command window.
Deploy the HR application EAR file

This section describes how to deploy the HR application EAR file and create the supporting WebSphere Application Server data source.
Deploy the HR application EAR file

To deploy the HR application back-end components, do the following steps: 1. Ensure the server1 application server is started on the Portal Server node. 2. Start the WebSphere Administrative Console.
3. When prompted, logon as an administrator user (for example, wpsbind). Depending at which time you are deploying this application, WebSphere security may be enabled and will require a password for the user ID. 4. To install the HR application click Applications Install New Application. 5. Click Browse and select the HRApplication.ear file from the c:\6692code\hrapp directory, and then click Next. 6. Accept the default options and click Next. 7. Click Step 11 Summary. 8. At the Summary page, click Finish. 9. Wait until the Application HRApplication installed successfully message is displayed. Click Save to Master Configuration. 10.On the Save screen click Save.
Configure the HR application data source

To configure the HR data source do the following from the WebSphere Administrative Console: 1. Ensure the DB2UNIVERSAL_JDBC_DRIVER_PATH is defined for your DB2 Universal Database installation. a. Select Environment Manage WebSphere Variables. b. Search for DB2UNIVERSAL_JDBC_DRIVER_PATH variable. If not already configured, enter the directory for the DB2 Java driver. For example, we entered the following:
C:\IBM\SQLLIB\java
c. Click OK.
530
d. Click Save and click Save again when prompted. 2. Create a new user for J2C authentication data. a. Click Security JAAS Configuration J2C Authentication Data. b. Add a new entry by clicking New. c. On the New page, enter the following: Alias: HRUser User ID: admin Note: This user ID needs administrator authority to the database (SELECT, DELETE, INSERT and UPDATE privileges). Password: <password> Description: HR User
d. Click OK. e. Click Save and click Save again when prompted. 3. Create the JDBC Provider for DB2. a. Click Resources JDBC Providers. b. Click New. c. From the JDBC Providers drop-down list, select DB2 Universal JDBC Driver Provider, and then click OK. d. When the Configuration details page appears, accept the default settings and click OK. e. Click Save and click Save again when prompted. 4. Create the data source. a. Click the DB2 Universal JDBC Driver Provider from the JDBC Provider page. b. Click Data Sources. c. To add a data source click New. d. Enter the following and then click OK: Name: HR Application Datasource. JNDI Name: jdbc/ew/HRRequestDatasource Check Use this Data Source in container managed persistence (CMP). Component-managed Authentication Alias: select wpwin1/HRUser. Note: Where wpwin1 is the node name. Container-managed Authentication Alias: select HRUser. Mapping-Configuration Alias: select DefaultPrincipalMapping.
531
e. Click Apply. f. Click Custom Properties link at the bottom of the screen. g. Click databaseName link. h. Enter HR in the Value filed, and click OK. i. From the Custom Properties page, click serverName. j. Enter wpwin1 in the Value field, and click OK. k. Click Save and click Save again when prompted. 5. Test the connection. a. Select Resources JDBC Providers. b. Click DB2 UNIVERSAL JDBC Driver Provider. c. Click Data Sources. d. Check HR Application Datasource, and click Test Connection. Note: In some cases, we found that we had to restart the server1 application server for the test connection to work properly. Remember, when stopping the server, you will need to specify the user ID and password when WebSphere security is enabled. For example:
stopserver.bat server1 -user wpsbind -password <password>
Install the HR application shared libraries

To install the HR application shared libraries, do the following 1. Copy the following files from c:\6692code\hrapp to the <wp_home>\shared\app directory: HRPortletService.jar HR_JavaModule.jar 2. Ensure the server1 application server is started on the Portal Server node. 3. Start the WebSphere Administrative Console.
4. When prompted, logon as an administrator user (for example, wpsbind). Depending at which time you are deploying this application, WebSphere security may be enabled and will require a password for the user ID. 5. Click Environment Shared Variables WPSlib
532
6. Append the following lines at the Classpath text box: ${WPS_HOME}/shared/app/HRPortletService.jar ${WPS_HOME}/shared/app/HR_JavaModule.jar 7. Click OK. 8. Click the Save link at the top of the screen and then click the Save Button. 9. Click Logout to logout of the WebSphere Administrative Console. 10.Restart the WebSphere_Portal application server.
Deploy the HR application WAR file

To deploy the HR application front-end portlets, do the following steps: 1. Ensure that the WebSphere_Portal application server is started on the Portal Server node. 2. Enter the following URL in a Web Browser to access the WebSphere Portal home page.
3. Click Log in to log in as the IBM WebSphere Portal V5.1 administration user (for example, admin). 4. Click Administration. 5. Click Portlet Management Web Modules. 6. Click Install. 7. By clicking Browse select c:\6692code\hrapp\HRPortlets.war and then click Next. 8. The next screen will show the portlets to be installed within the war. Click Finish.
Modify the PortletServiceRegistryService.properties file

The HR application portlets require adding entries to the WebSphere Portal provided PortletServiceRegistryService.properties file. 1. Navigate to the following directory on the Portal Server node:
<wp_home>/shared/app/config/services
2. Open the PortletServiceRegistryService.properties in an editor. 3. Append the lines displayed in Figure A-1 on page 534 to the end of the PortletServiceRegistryService.properties file. You will need to update the hostname and port for your environment.
533
Note: In our example, we have configured an external IBM HTTP Server and thus did not specify a port. We have provided the entries to be added to the PortletServiceRegistryService.properties file, found in the c:\6692\hrapp folder of the ITSO provided sample code.
Example: A-1 Sample PortletServiceRegistryService.properties # *** HR Request Portlet Service *** com.ibm.sst.ew.hrservice.HRPortletService=com.ibm.sst.ew.hrservice.HRPortletServiceImpl # Define the variables with the servlet urls com.ibm.sst.ew.hrservice.HRPortletServiceImpl.getVacationData=http://wpwin1.itso.ral.ibm.com:90 80/HRAppServlet/GetVacationData com.ibm.sst.ew.hrservice.HRPortletServiceImpl.submitRequests=http://wpwin1.itso.ral.ibm.com:908 0/HRAppServlet/SubmitRequest com.ibm.sst.ew.hrservice.HRPortletServiceImpl.getRequests=http://wpwin1.itso.ral.ibm.com:9080/H RAppServlet/GetRequests com.ibm.sst.ew.hrservice.HRPortletServiceImpl.getAllEmployeeRequests=http://wpwin1.itso.ral.ibm .com:9080/HRAppServlet/GetAllEmployeeRequests com.ibm.sst.ew.hrservice.HRPortletServiceImpl.processRequests=http://wpwin1.itso.ral.ibm.com:90 80/HRAppServlet/ProcessRequests com.ibm.sst.ew.hrservice.HRPortletServiceImpl.getEmployeeNumber=http://wpwin1.itso.ral.ibm.com: 9080/HRAppServlet/GetEmployeeNumber com.ibm.sst.ew.hrservice.HRPortletServiceImpl.getDepartments=http://wpwin1.itso.ral.ibm.com:908 0/HRAppServlet/GetDepartments com.ibm.sst.ew.hrservice.HRPortletServiceImpl.addEmployee=http://wpwin1.itso.ral.ibm.com:9080/H RAppServlet/AddEmployee com.ibm.sst.ew.hrservice.HRPortletServiceImpl.getSalaryInformation=http://wpwin1.itso.ral.ibm.c om:9080/HRAppServlet/GetSalaryInformation com.ibm.sst.ew.hrservice.HRPortletServiceImpl.updateSalaryInformation=http://wpwin1.itso.ral.ib m.com:9080/HRAppServlet/UpdateSalaryInformation com.ibm.sst.ew.hrservice.HRPortletServiceImpl.getEmployee=http://wpwin1.itso.ral.ibm.com:9080/H RAppServlet/GetEmployee
Create the portal pages

This section describes how to create portal pages for the HR Application. When complete, you will have a hierarchy of portal pages as follows: My Portal HR Application Vacation Requests Process Requests
534
New Employee
To create a new page for the new HR Application page under MyPortal, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Portal User Interface Manage Pages. 4. Click My Portal. 5. Click New Page. 6. When the New Page properties page appears, we entered the following and then clicked OK: Title: HR Application Under Type of Page select the first layout model (one column) 7. You should see a message that the page was created successfully. Click OK. 8. Click the Up arrow next to the HR Application page to move it up in order to below Welcome so that it is immediately visible when a user logs on to the portal. 9. Click HR Application. 10.Create the Vacation Requests page. a. Click New Page. b. When the New Page properties page appears, we entered the following and then clicked OK: Title: Vacation Request c. You should see a message that the page was created successfully. Click OK. 11.Create the Process Requests page. a. Click New Page. b. When the New Page properties page appears, we entered the following and then clicked OK: Title: Process Request c. You should see a message that the page was created successfully. Click OK. 12.Create the New Employee page. a. Click New Page.
535
b. When the New Page properties page appears, we entered the following and then clicked OK: Title: New Employee c. You should see a message that the page was created successfully. Click OK.
Add portlets to pages

To add the HR Application portlets to the portal pages, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Portal User Interface Manage Pages. 4. Click My Portal. 5. Click HR Application. 6. Add portlets to the My Content page. a. Click the Pencil icon (Edit Page Layout) next to the My Content page. b. Click Add portlets. c. From the Edit Layout page, do the following and then click Search: Search on: select Title starts with Search for: HR
d. When the search results are displayed, you should see the portlet listed. Check the following portlets to add to the page and then click OK: HR - Corporate News HR - Welcome
7. Add portlets to the Vacation Request page. Add the following portlets to the Vacation Request page (same as previous step): HR - Vacation Request HR - My Requests
8. Add portlet to the Process Request page. Since there is only one portlet to add to this page, select the One column page layout. Click OK to the popup. Add the HR - Process Requests portlet to the Process Requests page. 9. Add portlet to the New Employee page.
536
Since there is only one portlet to add to this page, select the One column page layout. Click OK to the popup. Add the HR - New Employee portlet to the New Employee page. 10.Add HR - Welcome portlet to WebSphere Portal Welcome page. a. Select Portal User Interface Manage Pages. b. Click My Portal. c. Click Edit page layout (Pencil icon). d. Remove other WebSphere Portal portlets, and click Add Portlets. e. Search on HR, and check HR - Welcome portlet. Click OK. f. Click Done. g. Logout of WebSphere Portal. h. Login as the WebSphere Portal administrator. i. Select Portal User Interface Manage Pages. j. Click My Portal. k. The status for the Welcome page may be inactive. Click Inactive under status and it will become Active.
Assign resource permissions


2. Click the Administration tab. 3. Click Portal User Interface Manage Pages. 4. Click My Portal. 5. Assign resource permissions for the HR Application page. Allow all authenticated portal users to access the HR Application page. a. Click the key icon (Set Page Permission) under Assign access for HR Application page. b. Click the Pencil icon (Edit Role) next to Privileged User. c. Click Add to add a role.
537
d. Check all authenticated portal users. e. Click OK. f. Click HR Application link. g. Click Done. 6. Assign resource permissions for the New Employee page. Allow only the hrspecialists group to see the New Employee page. a. Restrict access. The permission inheritance for the New Employee page must be turned off for users and privileged users. Otherwise, the page would always be visible for all authenticated portal users. i. Click HR Application. ii. Click the key icon (Set Page Permission) next to the New Employee page in the page listing underneath HR Application. iii. Uncheck the Allow Inheritance check boxes next to User and Privileged User. iv. Click Apply. v. Click OK for the confirmation popup. vi. Click Done. b. Grant access to hrspecialists group i. Click the key icon again (Set Page Permission) next to the New Employee page in the page listing underneath HR Application. ii. Click the Edit Role (pencil) icon next to Privileged User. iii. Click Add. iv. Search for the desired group. Search for Users or User Groups: select User Groups Search on: cn Search for: hr* Note: The ITSO HR application groups are prefixed with hr, and the * being a wildcard to search for all groups. Click Search
c. Check the box next to hrspecialists and click OK. d. Click New Employee link. e. Click Apply. f. Click OK to the popup. g. Click Done.
538
7. Assign resource permissions for the Process Requests page. Allow only the hrmanagers group to see the Process Requests page. a. Restrict access. The permission inheritance for the Process Requests page must be turned off for users and privileged users. Otherwise, the page would always be visible for all authenticated portal users. i. Click HR Application. ii. Click the key icon (Set Page Permission) next to the Process Requests page in the page listing underneath HR Application. iii. Uncheck the Allow Inheritance check boxes next to User and Privileged User. iv. Click Apply. v. Click OK for the confirmation popup. vi. Click Done. b. Grant access to hrmanagers group. i. Click the key icon again (Set Page Permission) next to the Process Requests page in the page listing underneath HR Application. ii. Click the Edit Role (pencil) icon next to Privileged User. iii. Click Add. iv. Search for the desired group. Search for Users or User Groups: select User Groups Search on: cn Search for: hr* Note: The ITSO HR application groups are prefixed with hr, and the * being a wildcard to search for all groups. Click Search
c. Check the box next to hrmanagers and click OK. d. Click Process Requests link. e. Click Apply. f. Click OK to the popup. g. Click Done.
539

To modify the portlet resource permissions, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Access Resource Permissions. 4. Click Portlets. 5. Filter the list of displayed portlets by entering HR in the Title contains search box, and click Search. 6. Assign access permissions to the HR - New Employee portlet. a. Click the Key icon (Assign Access) next to the HR - New Employee portlet. b. Click the Pencil icon (Edit Role) next to Privileged User. c. Click Add. d. We selected All available from the Search by drop-down and then clicked Search. e. Check the hrspecialists group to assign access to the portlet and then click OK. f. Click HR - New Employee link. g. Click Apply. h. Click OK to the popup. i. Click Portlets link. 7. Repeat the process to assign permissions to the portlets and groups defined in Table 13-1.
Table 13-1 Portlet access permissions by group Portlet HR - Corporate News HR - My Requests HR - New Employee HR - Process Requests HR - Vacation Requests Group (Role) All Authenticated Portal Users All Authenticated Portal Users hrspecialists hrmanagers All Authenticated Portal Users
540
Portlet HR - Welcome
Group (Role) * All Authenticated Portal Users Note: Role - Privileged User * Anonymous Portal User Note: Role - Users. Beware of the configuration problem with the jmt.conf when using TAM, found in the notebox of 5.6.9, Configure the junction mapping table (JMT) on page 305.
Additional configuration when deployed with Tivoli Access Manager

If you plan to deploy the HR application in a runtime environment which includes Tivoli Access Manager, you will need to import the users into Tivoli Access Manager for authentication purposes. In addition, if you would like Tivoli Access Manager to perform authorization functions for the HR application, you will need to externalize the resource permissions from WebSphere Portal to be managed by Tivoli Access Manager. Note: Deploy and configure the application when using Tivoli Access Manager If you are deploying the application in an environment with Tivoli Access Manager WebSEAL configured, the URL to access WebSphere Portal will be as follows:
At the time of writing, we found that the WebSphere Portal V5.1 Administration - Resource Permission portlets did not work properly when using the jmt.conf described in 5.6.9, Configure the junction mapping table (JMT) on page 305. The Resource Permission portlets contain JavaScript with relative URLs that are not mapped properly when using the jmt.conf found in Example 5-13 on page 307. This problem is a result of the URLs being too long on the Windows platform. Refer to 5.6.9, Configure the junction mapping table (JMT) on page 305 for details on how to configure the environment to workaround this problem.
Import users into Tivoli Access Manager

In our example, the users were created in the Tivoli Directory Server in Import users and groups into LDAP directory via ldif file on page 528. The same set of users will need to be imported into Tivoli Access Manager.
541
Note: Once the ITSO provided provisioning portlet application is used, the users will automatically be created in the LDAP directory, Tivoli Access Manager, HR DB2 database, and DB2 Content Manager via Tivoli Identity Manager and Tivoli Directory Integrator. IBM WebSphere Portal V5.1 has a new feature to enable automatic user provisioning to Tivoli Access Manager V5.1. We did not configure this since we will provision users via Tivoli Identity Manager. For more information, refer to the WebSphere Portal V5.1 InfoCenter. To manually import the HR application users and groups into Tivoli Access Manager, do the following steps: 1. Open a command window. 2. Copy the c:\6692code\hrapp\hr-tam-user-import.pd to a temporary directory (for example, c:\temp) on a system where pdadmin is installed, such as the Reverse Proxy node. 3. From the temporary directory, enter the following command to import the WebSphere Portal users and groups into Tivoli Access Manager:
pdadmin -a sec_master hr-tam-user-import.pd
When prompted, enter the sec_master password. 4. To verify that the users and groups where imported properly, enter the following commands from a Windows command window:
Externalize the resource permissions

In Assign resource permissions on page 537, we assigned resource permissions for the portal pages and portlets based on the roles of users. If you would like Tivoli Access Manager to perform authorization functions for the HR application, you will need to externalize the resource permissions from WebSphere Portal to be managed by Tivoli Access Manager. For details, refer to the Develop and Deploy a Secure Portal, Using WebSphere Portal V5 and Tivoli Access Manager V5.1, SG24-6325.
542
Run the HR application in the runtime environment

This section describes how to run the HR application in the ITSO identity and access management system runtime environment. We will demonstrate how to create a new employee while logged in as hrspecialist1. 1. Enter the following URL in a Web browser to access the WebSphere Portal home page:
http://wpwin1.itso.ral.ibm.com/wps/portal/
2. Click Login. Login with the hrspecialist1 user ID and password. 3. Click HR Application. The Welcome page, similar to Figure A-2, should appear.
Figure A-2 HR Application - Welcome page
4. Click New Employee. 5. When New Employee page appears, enter the following as seen in Figure A-3 on page 544, and then click Submit: First Name: John Last Name: Doe Department: select DEV01 Salary: 100000
543
You should see a message like the following:

You are assigned an employee number: 100005
The new employee will need the employee number to self register in the provisioning portlet application.
Figure A-3 HR Application - New Employee page
6. Verify the Vacation Request portlet. 7. Logout by clicking the Log out button.
Set up HR application in Rational Application Developer

This section describes how to import and run the HR application into IBM Rational Application Developer V6.0.
544
Requirements to customize the HR application

For a high level understanding of the development environment required for the HR application as part of the ITSO identity and access management system, refer to 3.4.5, Development environment topology and product mapping on page 128. For detailed installation and configuration information for the development environment, refer to Chapter 6, Development environment installation on page 339.
Create the database and import the data,

To create the database see Create the HR application database on page 529.
Import the Project Interchange File

To import the HR application Project Interchange file into Rational Application Developer, do the following steps: 1. Open J2EE perspective Project Explorer view. 2. Select File Import. 3. When the Import Wizard wizard appears, select Project Interchange and click Next. 4. In the Import Projects screen, browse to the c:\6692code\hrapp folder and select HRApplication.zip. Click Open. 5. Click Select All and then Finish. The projects will be added to your workspace. You should now have the HR Application projects containing the HR application portlet source files, EJBs and Java modules.
Configure the HR application data source

To configure the HR application data source, refer to Configure the HR application data source on page 530.
Define the HR Service

To define the HR services, refer to Install the HR application shared libraries on page 532 and Modify the PortletServiceRegistryService.properties file on page 533.
545
Configure the WebSphere Portal V5.1 Test Environment

For details, refer to 6.5.3, WebSphere Portal V5.1 Test Environment configuration on page 358.
Configure Java build path and test environment to deploy

Now that the projects are in Rational Application Developer, we need to configure the Java build path and test environment, so that the source will be compiled correctly, and the application will run properly. 1. Open the J2EE perspective Navigator view. 2. Modify the server for the HR_JavaModule project to set up the proper JRE to compile and run. a. Right-click HR_JavaModule, and select Properties. b. Select the Server tab. c. Select WebSphere Application Server V5.1 stub from the Target runtime drop-down list, and then click OK. d. Repeat the process for the following projects: HRApplicationEAR HRAppServlet HRRequestEJB HRRequestSessionEJB
3. Modify the server for the HRPortletEAR to set up the proper JRE to compile and run. a. Right-click HRPortletEAR, and select Properties. b. Select the Server tab. c. Select WebSphere Portal V5.1 from the Target runtime drop-down list, and then click OK. Note: This is the WebSphere Portal V5.1 Test Environment created in Configure the WebSphere Portal V5.1 Test Environment on page 546. d. Repeat the process for the following projects: HRPortlets HRPortletService
546
4. Change the Workbench preferences to ignore unused import warnings. After making the configuration updates, you will still many warnings for unused imports. You change the preferences to filter out these warnings. a. Select Window Preferences. b. Select Java Compiler. c. Click the Unused Code tab. d. Select Ignore from the Unused Imports drop-down list. e. Click OK. f. You will be prompted to perform a full rebuild. Click Yes. 5. To perform a clean build for all projects do the following steps: a. Select Project Clean. b. Select Clean all projects and click OK. Note: In some cases, we found that IBM Rational Application Developer V6.0 should be restarted to solve the remaining compilation errors.
547
548
Appendix B.
Document management application

The document management application architecture uses a portal front-end and DB2 Content Manager for its document repository. The document management application can be deployed to the runtime environment to further demonstrate user provisioning from Tivoli Identity Manager and Tivoli Directory Integrator to the DB2 Content Manager system. This appendix provides an overview of the document management application and describes how to deploy the application to the runtime environment. Lastly, although we do not explain how to develop this type of application, we provide instructions for importing the ITSO custom document management application in Rational Application Developer. This appendix is organized into the following sections: Introduction to the document management application Deploy document management application Run and verify the document management application Set up DM application in Rational Application Developer
549
Introduction to the document management application

Note: The ITSO custom document management application found in this appendix is largely based on the application built in the IBM Redbook, Document Management, Using WebSphere Portal V5.0.2 and DB2 Content Manager V8.2, SG24-6349. We have updated this application to use WebSphere Portal V5.1 (previously used V5.0.2) and DB2 Content Manager V8.3 (previously used V8.2). The document management application demonstrates the life cycle of a research report from creation, through review, approvals and finally to publication. The application uses DB2 Content Manager as its repository, and also uses Content Managers workflow processing. The basic flow of the application starts with a supervisor defining a report to be written. A researcher then writes the report, and receives feedback from a variety of reviewers. Once finished, the report is approved by both the supervisor and a legal advisor, and then is published, where it becomes available to all users. The document management application uses a portal based front-end to connect to the Content Management system back-end. There are seven portlets: 1. ITSO DM - Task List - available to all users, this portlet shows what tasks the user has to work on 2. ITSO DM - My Documents - available to all researchers, this portlet shows what documents (reports) the researcher is working on 3. ITSO DM -Versioning - available to researchers, this portlet allows a researcher to check-in or check-out a report 4. ITSO DM - Document Details - available to all users, this portlet shows the details of a selected report 5. ITSO DM - Task Processing - available to all users, this portlet shows what tasks are available in the workflow 6. ITSO DM - All Published Documents - available to all users, this portlet shows all the reports that have made it through the workflow system and have been published 7. ITSO DM - Assign Research Reports - available to supervisors, this portlet allows a supervisor to define a new report to be completed
550
The portlets are available to different users, based on their roles in the scenario. For example, only users in the Supervisors group will see the ITSO DM - Assign Research Reports portlet. Additionally, the functions available in the portlets are determined by the current state of the document in the workflow process. For example, if no report has been defined by a supervisor, the researchers will not be able to accept a report. The workflow determines what user interface functions are available in the portlets.
User roles
The roles used in the document management application are defined in Table B-1.
Table B-1 Workplace roles in the ITSO scenario Role Researcher Description A professional with expertise in a particular area and able to carry out research, perform a detailed analysis, and produce a report summarizing results. A researcher can author a report or participate in peer reviews of reports authored by other researchers. A more experienced researcher with responsibilities for planning and directing research work by a group of researchers. A supervisor creates new report projects and also approves or rejects reports written by researchers. A legal professional to advise researchers and review reports to protect the corporation from legal action or wrong-doing. A legal advisor approves or rejects reports written by researchers. A publisher is able to publish all of the approved reports that are approved by legal.
Supervisor
Legal advisor
Publisher
Appendix B. Document management application
551
Document management application detailed scenario

The report life cycle starts when the supervisor creates request to prepare a report. Once the request is created, researchers receive notification of the research task in their task list. One of the researchers then acknowledges the assignment and accepts responsibility to create the report. The researcher carries out the necessary research and produces a draft report. The authoring researcher uses the workplace to submit the draft for peer review by other researchers. The researcher who accepts the review task first then becomes the activity owner. The peer researcher can provide comments with the report and either approve or reject the report. On approval, the report progresses to the supervisors group, while on rejection the report is returned to the researcher for rework. During rework the author of the document can read reviewers comments and make report updates. When the authoring researcher is satisfied the report is complete, the report is submitted for approval. The supervisor receives the request for approval in the employee workplace and reviews the report. The supervisor submits the report for approval by legal or rejects the report, returning it back to the researcher with comments for rework. Once the supervisor approves the report, it is sent to the legal advisor for approval. Upon receiving a request for approval, a legal advisor reviews the report and approves or rejects it. If approved, the report is submitted to the publishers and if rejected, the report is sent back to the researcher for rework. The publishers approval is the last step in the report creation process. Once approved, the document management system is notified that the report is to be published and the report is added to the published section of the workplace. All ITSO employees now have read access to the newly published report.
Use case diagram

The use case diagram graphically summarizes the interactions of users with the system. Figure B-1 shows the use case diagram.
552
Create New Report Draft
Researcher Author
Rework Annotated Report
Create Report Project

Researcher Reviewer
Supervisor
Review and Annotate Report
Approve Report for Publication

Legal Advisor Publisher
Publish Report
View Published Reports

Employee
Figure B-1 ITSO use case diagram for user actors
Deploy document management application

This section describes how to deploy the sample document management application to the ITSO identity and access management system runtime environment.
Prerequisites for application deployment

Prior to deploying the ITSO custom portal based document management application to the runtime environment, you will need to complete the following tasks to set up the environment:
553
Installation of the following nodes: 4.2, Directory node installation on page 135 (Tivoli Directory Integrator is not required for this sample application) 4.6, Content Management node installation on page 200 4.7, Portal Server node installation on page 209 Configuration of the following: 5.1, Configure WebSphere Portal for DB2 UDB on page 236 5.2, Configure WebSphere Portal with IBM HTTP Server on page 248 5.3, Configure WebSphere Portal with LDAP on page 255 5.4, Configure DB2 Content Manager with LDAP on page 265
Start the servers on runtime nodes

The following servers will need to be started on each of the nodes of the ITSO working example runtime environment, prior to application deployment.
Start servers on Directory node

Start the following servers on the Directory node: DB2 Windows services IBM Tivoli Directory Server V5.2 Windows service For administration purposes on the Directory Server node, you will need to start the following in addition to the above listed services: IBM HTTP Server V1.3.26 Windows service server1 application server IBM Tivoli Directory Admin Daemon V5.2 Windows service
Start servers on Content Management node

Start the following servers on the Content Management node: DB2 Windows services ICM LS Monitor ICMNLSDB Windows service (Library Server) IBM HTTP Server V1.3.28 Windows service icmrm application server (Resource Manager)
Start servers on Portal Server node

Start the following servers on the Portal Server node: DB2 Windows services IBM HTTP Server V1.3.28 Windows service WebSphere_Portal application server For administration purposes, we will start server1: server1 application server
554
ITSO sample code download and unpack

DB2 Content Management application deployment

This section describes how to deploy the DB2 Content Manager assets of the custom document management application the Document Management node of the ITSO identity and access management system runtime environment. The DB2 Content Manager application deployment includes the following tasks: 1. 2. 3. 4. 5. Import users and groups into LDAP directory via ldif file Import users into CM via the LDAP User Import Scheduler Define the access control permissions Define data model (item type and attributes) Define the workflow
Import users and groups into LDAP directory via ldif file
This section describes how to import users and groups into the LDAP directory for the ITSO working example using the c:\6692code\DocMgtApp\config\ldap\itso-dm.ldif. Note: Initially, we will create users manually by importing users into the Tivoli Directory Server via an ldif file, and then import them into DB2 Content Manager using the LDAP User Import Scheduler. Once everything is deployed and working, we can verify the provisioning of users from the provisioning portlets (Tivoli Identity Manager and Tivoli Directory Integrator). Table B-2 includes a listing of the ITSO working example users and groups.
Table B-2 ITSO working example users and groups Groups A_Researchers Users Researcher1 Researcher2 A_Supervisors A_Publishers A_Legals Supervisor1 Publisher1 Legal1
555
To import the users and groups for the ITSO working example via the itso-dm.ldif file, do the following steps: 1. Ensure you have create the suffix DN: dc=itso,dc=ibm,dc=com, users and groups for WebSphere Portal. When following the ITSO procedure, this was done in 5.3.1, Create a suffix on page 255. 2. Stop the IBM Tivoli Directory Server V5.2 Windows service. 3. Copy the ITSO provided c:\6692code\DocMgtApp\config\ldap\itso-dm.ldif file to a temporary directory (for example, c:\temp) on the Directory node. 4. Modify the value of the userpassword in the itso-dm.ldif file for your environment. 5. Start the Tivoli Directory Server Configuration Tool by clicking Start Programs IBM Tivoli Directory Server V5.2 Directory Configuration. 6. Select Import LDIF data. 7. When the Import LDIF Data page appears, we entered the following information and then clicked Import (bottom of page): Path and LDIF file name: c:\temp\itso-dm.ldif Select Standard import After the import has finished successfully, a message will be displayed reporting how many entries have been imported into the directory server. 8. When the import is complete, click Close. Close the Configuration Tool. 9. Restart the IBM Tivoli Directory Server V5.2 Windows service. 10.Verify the LDAP entries where created properly by performing an LDAP search. For example, we entered the following from a command window on the Directory Server node:
ldapsearch -h <ldap_server_hostname> -b dc=itso,dc=ibm,dc=com -D uid=wpsbind,cn=users,dc=itso,dc=ibm,dc=com -w password -s sub uid=Researcher1
Import users into CM via the LDAP User Import Scheduler

The users can be imported from the LDAP directory into DB2 Content Manager, from the System Administration Client LDAP Import wizard (only supports import of users) or the LDAP Import Scheduler (import users and groups). Note: As a reminder, this process is done to verify the application deployment. Chapter 11, Application deployment on page 469 demonstrates how users can be provisioned from the provisioning portlets to DB2 Content Manager.
556
To configure the DB2 Content Manager LDAP User Import Scheduler to import LDAP users into DB2 Content Manager, do the following steps: 1. Click Start Programs IBM DB2 Content Manager Enterprise Edition LDAP user import scheduler. Note: For more information regarding the settings of the LDAP User Import Scheduler refer to the online help available from the tool.
Figure 13-3 Content Manager - LDAP User Import Scheduler
2. When the LDAP user import scheduler window appears, we entered the following as seen in Figure 13-3 and then clicked Save. LDAP Directory (Source): LDAP object class for groups: groupOfUniqueNames This value should match the group objectclass in the LDAP directory. LDAP search scope: uniquemember LDAP root DN: cn=root LDAP root DN password: <password>
557
Import Schedule: Check Enable for the ICMNLSDB Admin ID: icmadmin Admin ID Password: <password> User group: Select Maintain the LDAP group names In our example, we want the import utility to create groups found in the LDAP directory in Content Manager and add users to those groups. or Select Put all users in one group, enter <group> Schedule time: <24_hour_time> Day of week: <day> To select more than one day use the control key. User filter: (objectclass=inetOrgPerson) The LDAP user filter provides a query string to match users in the LDAP user registry. The default user filter we have defined will retrieve all inetOrgPerson user objects. Note: We found the <wp_home>\config\wpconfig.properties file useful in determining the proper values and/or looking at the LDAP directory schema implemented.
Enter the privilege set: ClientUserEditSSO Attention: The default privilege set is ClientUserReadOnly. Due to the security model of Content Manager, we needed to assign the users of the Content Manager application a higher privilege set (ClientUserEdit) for the access permissions to work properly. In our example, we are passing a token from the portlet to the Content Manager for a trusted logon. We needed to create a privilege set with two additional privileges (AllowConnectToLogon, AllowTrustedLogon) beyond the system defined ClientUserEdit privilege set. We created the ClientUserEditSSO privilege set in 5.4.6, Create the ClientUserEditSSO privilege sets on page 272. Remember all users in the LDAP directory will be created in Content Manager with the privilege set defined in the LDAP User Import Scheduler. If your system resources are protected with ACLs properly, this should not be an issue. On the other hand it would be preferred that you create users with a restrictive privilege set and only add more powerful privilege sets to users that require the access.
558
3. You should see a message window, Successfully updated cmbschinfo.ini with schedule information. Click OK. 4. Verify the users were created in the DB2 Content Manager. a. Check that the user exist in the System Administration Client, b. Verify you can logon to a Content Manager application such as the DB2 Content Manager Client for Windows with one of the newly added users. 5. Now that you have verified the users have been added for testing purposes, disable the LDAP User Import Scheduler since in the future we will provisioning users via Tivoli Identity Manager. a. Click Start Programs IBM DB2 Content Manager Enterprise Edition LDAP user import scheduler. b. Uncheck the Enable checkbox. c. Enter the <ldap_root_DN_password> in the LDAP root DN password field, and then click Save. Tip: Windows Scheduled Task The configuration data for the Content Manager LDAP User Import Scheduler is saved to the c:\ibm\cmgmt\cmbschinfo.ini. When saving the settings, the LDAP User Import Scheduler creates a Windows Scheduled Task, which will run the following batch file:
c:\IBM\db2cmv8\admin\common\cmldapimpusers81.bat ICMNLSDB ICM
The output from running the task can be found in the following:
c:\IBM\db2cmv8\admin\common\cmldapimpusers81.ICMNLSDB.ICM.log
The settings for this scheduled task can be modified accordingly to your environment. Keep in mind that if you have an LDAP directory with very large number of users and groups, this could have a performance impact on the system.
559
Attention: At the time of writing, using IBM DB2 Content Manager V8.3, Enterprise Edition, we found that the DB2 Content Manager LDAP User Import Scheduler had to problems/limitations: 1. When a user is deleted from LDAP, the Content Manager LDAP User Import Scheduler is supposed to delete a user / group from DB2 Content Manager and does not. 2. Content Manager LDAP User Import Scheduler does not modify an existing group with a new user.
Define the access control permissions

This section describes how to define access control permissions for the groups and users defined to the groups for the ITSO working example. There are two methods that can be used to create the required definitions: GUI (manual) Using the System Administration Client takes longer, but provides the advantage of being able to complete tasks in the GUI. API (automatic) Run the Java programs included in the 6692code.zip download for this redbook. This saves time, but you will have to look at the System Administration Client later to see what the program created. To create the access control permissions for the ITSO working example by running a Java application (API - automatic), do the following on the Portal Server node (location Information Integrator for Content is installed): 1. Ensure the Library Server and Resource Manager are started on the Content Management node. 2. Ensure you have downloaded and unpacked the ITSO sample files as described in ITSO sample code download and unpack on page 555 on the Portal Server node. 3. Ensure that you have imported users and groups on the Content Management node. Import users and groups into LDAP directory via ldif file on page 555 Import users into CM via the LDAP User Import Scheduler on page 556 4. Open a command window with the DB2 Information Integrator for Content environment set on the Portal Server node. 5. Run cmbenv81.bat found in the C:\IBM\db2cmv8\bin directory. 6. In the command window, navigate to the following directory:
c:\6692code\DocMgtApp\cmsetup
560
7. Enter the following command to create a privilege set, create ACLs and assign new privilege set to groups:
java com.ibm.bsd.setup.ICMACLCreation
A number of message lines will be shown to indicate progress. When the program is done, it should display the following message:
========================================== ICMACLCreation program completed. ==========================================
8. For further verification, you may want to use the System Administration Client in order to view the created definitions.
Define data model (item type and attributes)

To create the data model item type and attributes for the ITSO working example by running a Java application (API - automatic), do the following on the Portal Server node (location Information Integrator for Content is installed): 1. Open a command window with the DB2 Information Integrator for Content environment set on the Portal Server node. 2. Run cmbenv81.bat found in the C:\IBM\db2cmv8\bin directory. 3. In the command window, navigate to the following directory:
4. Enter the following command to run the item type and attribute creation program:
java com.ibm.bsd.setup.ICMDataModelCreation
5. A number of message lines will be shown to indicate progress. When the program is done, it should display the following message:
========================================== ICMDataModelCreation program completed. ==========================================
Define the workflow

To define the workflow for the ITSO example custom document management application, do the following on the Portal Server node (location Information Integrator for Content is installed): 1. Open a command window with the DB2 Information Integrator for Content environment set on the Portal Server node. 2. Run cmbenv81.bat found in the C:\IBM\db2cmv8\bin directory.
561
3. In the command window, navigate to the following directory:

4. Enter the following command to run the workflow creation program:

java com.ibm.bsd.setup.DocRoutingDefinitionCreation
5. A number of message lines will be shown to indicate progress. When the program is done, it should display the following message:
========================================== DocRoutingDefinitionCreation program completed. ==========================================
WebSphere Portal application deployment

This section describes how to deploy and configure the WebSphere Portal application for the ITSO custom document management application. The high level steps to deploy the application are as follows: 1. Add II4C common directory and jars to classpath 2. Install the document management portlets
Add II4C common directory and jars to classpath

This section describes how to add the Information Integrator for Content (II4C) common directory, and jar files to the WebSphere Portal class path to make them accessible to the application. Note: In our example, for simplicity we chose to add the Information Integrator for Content jars to the WPSlib shared library. This will have the effect to being loaded for all applications running on the WebSphere_Portal application server. Alternatively, the Information Integrator for Content jars could be added to the WebSphere Portal application WAR file. 1. Ensure server1 is started on the Portal Server node. 2. Start the WebSphere Administrative Console and login as wpsadmin.
http://wpwin11.itso.ral.ibm.com:9090/admin
3. Logon as user wpsbind. Note: WebSphere security is now enabled.
562
4. From the WebSphere Administrative Console select Environment Shared Libraries. 5. Click WPSlib. 6. Add the following line to the Classpath properties window, and then click OK:
c:/IBM/db2cmv8/cmgmt c:/IBM/db2cmv8/lib/cmbsdk81.jar c:/IBM/db2cmv8/lib/cmb81.jar
7. Click Save. 8. When the Save to Master Configuration window appears, click Save. 9. Logout of the WebSphere Administrative Console by clicking Logout. 10.Stop the server1 application server.
c:\ibm\WebSphere\AppServer\bin\stopServer.bat server1
11.Stop and restart the WebSphere_Portal application server.
Install the document management portlets

To install the ITSO custom document management portlets, do the following steps: 1. Ensure the WebSphere_Portal application server is started. 2. Log in to WebSphere Portal as an administrator user (for example, admin):
3. Click the Administration tab. 4. Click Portlet Management Web Modules Install. Tip: Updating the ITSO custom document management portlets To update the portlet application, click Portlets Manage Applications. Select the portlet application from the list (for example, DocManagement.war) and click Update. 5. Enter c:\6692code\DocMgtApp\DocManagement.war in the Directory field, and then click Next. 6. You should see a listing of the portlets. Click Finish. When complete, you should see a message, Web module was successfully installed.
563
Create Portal pages

This section describes how to create portal pages for the ITSO working example document management application. When complete you will have a hierarchy of portal pages as follows: My Portal ITSO DM Assign Research My Content My Tasks All Published Documents To create a new page for the new DocManagement page under MyPortal, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Portal User Interface Manage Pages. 4. Click My Portal. 5. Click New Page. 6. When the New Page properties page appears, we entered the following information and then clicked OK: Title: ITSO DM 7. You should see a message that the page was created successfully. Click OK. 8. Click the Up arrow next to the ITSO DM page to move it up in order to below Welcome so that it is immediately visible when a user logs on to the portal. 9. Click ITSO DM. 10.Create the Assign Research page. a. Click New Page. b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: Assign Research c. You should see a message that the page was created successfully. Click OK.
564
11.Create the My Content page. a. Click New Page. b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: My Content c. You should see a message that the page was created successfully. Click OK. 12.Create the My Tasks page. a. Click New Page. b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: My Tasks c. You should see a message that the page was created successfully. Click OK. 13.Create the All Published Documents page. a. Click New Page. b. When the New Page properties page appears, we entered the following information and then clicked OK: Title: All Published Documents c. You should see a message that the page was created successfully. Click OK. When complete, you should see a page similar to Figure 13-4.
565
Figure 13-4 Portal pages for the document management application
Add portlets to pages

To add the ITSO document management portlets to the portal pages, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Portal User Interface Manage Pages. 4. Click My Portal. 5. Click ITSO DM. 6. Add portlets to the My Content page.
566
a. Click the Pencil icon (Edit Page Layout) next to the My Content page. b. Click Add portlets in the left-hand window. By default the portal page layout contains two columns. c. From the Edit Layout page, do the following and then click Search: Search on: select Title contains Search for: ITSO
d. When the search results are displayed, you should see the portlet listed. Check the following portlets to add to the page and then click OK: ITSO DM - My Documents ITSO DM - Document Details ITSO DM - Versioning
e. After adding the portlets, rearrange them to look like Figure 13-5 on page 568. f. Click Done.
567
Figure 13-5 My Content page portlets
7. Add portlets to the My Task page. Add the following portlets to the My Task page (same as previous step): ITSO DM - Task List ITSO DM - Task Processing ITSO DM - Document Details
When done, the page layout should look as depicted in Figure 13-6.
568
Figure 13-6 My Tasks page portlets
8. Add portlet to the All Published Documents page. Since there is only one portlet to add to this page, select the One column page layout. Click OK to the popup. Add the ITSO DM - All Published Documents portlet to the All Published Documents page. 9. Add portlet to the Assign Research page. Since there is only one portlet to add to this page, select the One column page layout. Click OK to the popup. Add the ITSO DM - Assign Research Reports portlet to the Assign Research page.
569
Assign resource permissions


2. Click the Administration tab. 3. Click Portal User Interface Manage Pages. 4. Click My Portal. 5. Allow all authenticated portal users to access the ITSO DM page. a. Click the key icon (Set Page Permission) under Assign access for ITSO DM page. b. Click the Pencil icon (Edit Role) next to Privileged User. c. Click Add to add a role. d. Check all authenticated portal users. e. Click OK. f. Click ITSO DM link. g. Click Done. Note: In the following procedure, you will assign individual permissions to the pages created earlier. Pages underneath ITSO DM shall only be visible for certain sample user groups. The following steps show how to do this for the My Content page. 6. First, permission inheritance for the My Content page must be turned off for users and privileged users (see Figure 13-7 on page 571). Otherwise, the page would always be visible for all authenticated portal users. a. Click ITSO DM. b. Click the key icon (Set Page Permission) next to the My Content page in the page listing underneath ITSO DM. c. Uncheck the Allow Inheritance check boxes next to User and Privileged User. d. Click Apply. e. Click OK for the confirmation popup.
570
f. Click Done.
Figure 13-7 Disable permission inheritance for the My Content page
7. Allow only the A_Researchers group to see the My Content page: a. Click the key icon again (Set Page Permission) next to the My Content page in the page listing underneath ITSO DM. b. Click the Edit Role (pencil) icon next to Privileged User. c. Click Add. d. Search for the desired group. Search for Users or User Groups: select User Groups Search on: cn Search for: A_* Note: The ITSO groups are prefixed with A_, and the * being a wildcard to search for all groups. Click Search
e. Check the box next to A_Researchers and click OK. f. Click My Content link.
571
g. Click Apply. h. Click OK to the popup. i. Click Done. 8. Repeat the above steps for removing inheritance and adding page permissions for the pages and groups listed in Table 13-2.
Table 13-2 Assign page permissions Page ITSO DM My Content My Tasks All Published Documents Assign Research Group/Role all authenticated portal users A_Researchers A_Researchers, A_Supervisors, A_Legals, A_Publishers A_Researchers, A_Supervisors, A_Legals, A_Publishers A_Supervisors

To modify the portlet permissions, do the following steps: 1. Log in to WebSphere Portal as an administrator user (for example, admin):
2. Click the Administration tab. 3. Click Access Resource Permissions. 4. Click Portlets. 5. Filter the list of displayed portlets by entering ITSO in the Title contains search box, and click Search. 6. Assign access permissions to the ITSO DM - Task List portlet. a. Click the Key icon (Assign Access) next to the ITSO DM - Task List portlet. b. Click the Pencil icon (Edit Role) next to Privileged User. c. Click Add. d. We selected All available from the Search by drop-down and then clicked Search. e. Check the following groups to assign access to the portlet and then click OK: A_Researchers A_Supervisors A_Legals A_Publishers
572
f. Click OK. g. Click ITSO DM - Task List link. h. Click Apply. i. Click OK to the popup. j. Click Portlets link. 7. Repeat the process to assign permissions to the portlets and groups defined in Table 13-3.
Table 13-3 Portlet access permissions by group Portlet ITSO DM - Task List ITSO DM - My Documents ITSO DM - Versioning ITSO DM - Document Details ITSO DM - Task Processing ITSO DM - All Published Documents ITSO DM - Assign Research Reports Group A_Researchers, A_Supervisors, A_Legals, A_Publishers A_Researchers A_Researchers A_Researchers, A_Supervisors, A_Legals, A_Publishers A_Researchers, A_Supervisors, A_Legals, A_Publishers A_Researchers, A_Supervisors, A_Legals, A_Publishers A_Supervisors
Additional configuration when deployed with Tivoli Access Manager

If you plan to deploy the ITSO custom document management application in a runtime environment which includes Tivoli Access Manager, you will need to import the users into Tivoli Access Manager for authentication purposes. In addition, if you would like Tivoli Access Manager to perform authorization functions for the application, you will need to externalize the resource permissions from WebSphere Portal to be managed by Tivoli Access Manager.
573
Note: Deploy and configure the application when using Tivoli Access Manager If you are deploying the application in an environment with Tivoli Access Manager WebSEAL configured, the URL to access WebSphere Portal will be as follows:
At the time of writing, we found that the WebSphere Portal V5.1 Administration - Resource Permission portlets did not work properly when using the jmt.conf described in 5.6.9, Configure the junction mapping table (JMT) on page 305. The Resource Permission portlets contain JavaScript with relative URLs that are not mapped properly when using the jmt.conf found in Example 5-13 on page 307. This problem is a result of the URLs being too long on the Windows platform. Refer to 5.6.9, Configure the junction mapping table (JMT) on page 305 for details on how to configure the environment to workaround this problem.
Import users into Tivoli Access Manager

In our example, the users were created in the Tivoli Directory Server in Import users and groups into LDAP directory via ldif file on page 555. The same set of users will need to be imported into Tivoli Access Manager. Note: Once the ITSO provided provisioning portlet application is used, the users will automatically be created in the LDAP directory, Tivoli Access Manager, HR DB2 database, and DB2 Content Manager via Tivoli Identity Manager and Tivoli Directory Integrator. To manually import the ITSO custom document management application users and groups into Tivoli Access Manager, do the following steps: 1. Open a command window. 2. Copy the c:\6692code\DocMgtApp\config\ldap\dm-tam-user-import.pd to a temporary directory (for example, c:\temp) on a system where pdadmin is installed, such as the Reverse Proxy node. 3. From the temporary directory, enter the following command to import the WebSphere Portal users and groups into Tivoli Access Manager:
pdadmin -a sec_master dm-tam-user-import.pd
When prompted, enter the sec_master password.
574
4. To verify that the users and groups where imported properly, enter the following commands from a Windows command window:
Externalize the resource permissions

In Assign resource permissions on page 570, we assigned resource permissions for the portal pages and portlets based on the roles of users. If you would like Tivoli Access Manager to perform authorization functions for the document management application, you will need to externalize the resource permissions from WebSphere Portal to be managed by Tivoli Access Manager. For details, refer to the Develop and Deploy a Secure Portal, Using WebSphere Portal V5 and Tivoli Access Manager V5.1, SG24-6325. You have now completed the deployment of the ITSO custom document management application. Continue to the next section to run the document management application.
Run and verify the document management application

Now that the ITSO custom document management application has been deployed, we recommend that you verify it is working properly within the runtime environment. This section includes the following tasks to verify the ITSO document management application is deployed correctly: 1. 2. 3. 4. 5. 6. 7. 8. Add ITSO provided theme Supervisor assigns report to researcher group Researcher accepts and enters report content Researcher submits report for peer review Researcher adds comments for review complete Supervisor approves and submits to legal Legal approves and submits for publishing Publisher approves and publishes the report
Note: At the time of writing, occasionally clicking a button did not work the first time clicked. We simply clicked the button again and it worked. We did not have time to fully debug this problem. The sample is shipped as-is.
575
Add ITSO provided theme

To facilitate in understanding who is logged on (user role) during the application walkthrough, we have provided a modified Corporate theme (default.jsp) that displays the logged in user ID in the heading of the page. This update is optional for application functionality. Note: The URL noted to access the application will change once the Tivoli Access Manager WebSEAL is deployed. To add the ITSO provided theme, do the following steps: 1. Navigate to the following directory on the Portal Server node:
<was_home>/installedApps/wpwin1/wps.ear/wps.war/themes/html/Corporate
Note: In our example, we updated the Corporate theme to display the logged in user name. 2. Back up the original default.jsp. 3. Copy the ITSO provided default.jsp, c:\6692code\DocMgtApp\config\DMthem\default.jsp. 4. Enter the portal URL in a Web browser. For example, we entered the following information:
5. Click Log in the upper right of the page. 6. Enter the wpsadmin user ID and password, and then click Log in: User ID: wpsadmin Password: <password> 7. Click Administration. 8. Click Portal User Interface Manage Pages. 9. Click My Portal. 10.Click Edit Page Properties icon for the ITSO DM page. 11.Select the Corporate from the Theme drop-down list, and then click OK. 12.Click OK. 13.Click Logout.
576
Supervisor assigns report to researcher group

In this scenario, a supervisor (for example, Supervisor1) will create a new research report, which will then be available to users of the researcher group to be accepted. 1. Enter the portal URL in a Web browser. For example, we entered the following information:
2. Click Log in the upper right of the page. 3. Enter a user ID that is a member of the A_Supervisors user group. For example we entered the following information and then clicked Log in: User ID: Supervisor1 Password: <password> Note: If you created the users and groups using the ITSO working example itso-dm.ldif the default <password> is password. 4. Click the ITSO DM page. 5. Click the Assign Research page. 6. When the ITSO DM - Assign Research Reports portlet appears, we entered the following as seen in Figure B-2 and then clicked Create: Topic: Research report 1 Title: Research report 1 7. Click Log out to log off as the Supervisor user. Tip: Content Manager Client for Windows For test purposes, we used the DB2 Content Manager Client for Windows to verify that the document was created. We selected Search Basic. Select the desired item type (Research Report). For the Title of Research Report drop-down, we selected Is not null and clicked OK to initiate the search.
577
Figure B-2 Supervisor assigns research report to researchers group
Researcher accepts and enters report content

Now that the research report has been assigned to the researchers group, a researcher needs to acknowledge and accept the assignment. 1. Enter the portal URL in a Web browser. For example, we entered the following information:
2. Click Log in the upper right of the page. 3. Enter the researcher user ID that will accept the research report assignment. For example we entered the following information and then clicked Log in: User ID: Researcher1 Password: <password> Note: If you created the users and groups using the ITSO working example itso-dm.ldif the default <password> is password. 4. Click the ITSO DM page. 5. Click the My Tasks page. 6. Click Accept for the desired report as seen in Figure B-3 in the ITSO DM Task List portlet.
578
Figure B-3 Researcher accepts the assignment
7. Once you have accepted the assignment, the ITSO DM - Document Details portlet will be displayed. Click the Action button. 8. Modify the contents of the document in the Document body text field and then click Save document details as seen in Figure B-4. 9. Continue to the next section without logging out.
579
Figure B-4 Researcher enters report details and saves content
580
Researcher submits report for peer review

Once the report is put into a draft state (A_Draft), the research can put the report out for review to a peer researcher. 1. Enter the portal URL in a Web browser. For example, we entered the following information:
2. Click Log in the upper right of the page. 3. Enter the researcher user ID who created the draft research report. For example we entered the following information and then clicked Log in: User ID: Researcher1 Password: <password> 4. Click the ITSO DM My Tasks page. 5. Click Ready for Review for the desired report in the ITSO DM - Task Processing portlet. 6. When done, click Log off.
Researcher adds comments for review complete

In this scenario, a peer research analyst will review the draft report submitted by a peer research analyst. In our example, Researcher2 will review the draft report created by Researcher1. 1. Enter the portal URL in a Web browser. For example, we entered the following information:
2. Click Log in the upper right of the page. 3. Enter the researcher user ID who will review the draft report. For example we entered the following information and then clicked Log in: User ID: Researcher2 Password: <password> 4. Click the ITSO DM My Tasks page. 5. Select the desired report for review. For example, we clicked Accept for the Research report 1. 6. The research reviewer can add comments, such as Research report 1 looks great. Approve. as seen in Figure B-5. Click Save comments.
581
Figure B-5 Researcher reviewer comments and submits report for supervisor review
582
7. Click Reviewed in the ITSO DM - Task Processing portlet. 8. When done, click Log off.
Supervisor approves and submits to legal

Once the draft report is reviewed and comments have been responded to, it can be submitted to the supervisor for approval. When the supervisor approves the report it is submitted to legal for review. 1. Enter the portal URL in a Web browser. For example, we entered the following information:
2. Click Log in the upper right of the page. 3. Enter the supervisor who will approve the report. For example we entered the following information and then clicked Log in: User ID: Supervisor1 Password: <password> 4. Click the ITSO DM My Tasks page. 5. Click Accept for the desired report to be approved. 6. The report details will be populated including the document details to facilitate comment. Click Approve in the ITSO DM - Task Processing portlet. 7. When done, click Log off.
Legal approves and submits for publishing

Once the supervisor has approved the report, it is submitted to legal for approval. 1. Enter the portal URL in a Web browser. For example, we entered the following information:
2. Click Log in the upper right of the page. 3. Enter the legal user ID who will approve the report. For example, we entered the following information and then clicked Log in: User ID: Legal1 Password: <password>
583
4. Click the ITSO DM My Tasks page. 5. Click Accept for the desired report to work with. 6. The report details should be displayed for review and comment purposes. Click Approve in the ITSO DM - Task Process View portlet. 7. When done, click Log off.
Publisher approves and publishes the report

Once legal has approved the report, it is submitted to the publisher for final approval to be published. 1. Enter the portal URL in a Web browser. For example, we entered the following information:
2. Click Log in the upper right of the page. 3. Enter the publisher user ID who will approve the report to be published. For example we entered the following information and then clicked Log in: User ID: Publisher1 Password: <password> 4. Click the ITSO DM My Tasks page. 5. Click Accept for the desired report to work with. 6. The report details should be displayed for review and comment purposes as seen in Figure B-6. Click Publish in the ITSO DM - Task Process View portlet.
584
Figure B-6 Publisher review of report
585
7. Click the All Published Documents tab. A list of reports that are published will be displayed as seen in Figure B-7.
Figure B-7 All Published Documents
8. When done, click Log off. This concludes the ITSO custom portal based document management application walkthrough.
Set up DM application in Rational Application Developer

This section describes how to import the redbook sample code Project Interchange zip file into Rational Application Developer.
Prerequisites for importing

Install Rational Application Developer: See Chapter 6, Development environment installation on page 339 for instructions on installing Rational Application Developer. ITSO sample code download and unpack: See ITSO sample code download and unpack on page 555 for information about the code provided with this redbook.
586
Importing a project interchange file

To import a Project Interchange file, do the following steps: 1. Start Rational Application Developer. 2. From the Workbench, select File Import. 3. From the Import dialog, select Project Interchange as seen in Figure B-8, and then click Next.
Figure B-8 Import a Project Interchange file
587
4. When prompted, enter the Project Interchange path and file name, and the target workspace location. For example, we entered the following information: From zip file: c:\6692code\DocMgmtApp\DocMgtPI.zip Project location root: c:\Workspace 5. After entering the zip file, select all the projects and then click Finish. For example, we checked DocManagememnt, DocManagementEAR, and cmsetup and clicked Finish as seen in Figure B-9 on page 588
Figure B-9 Import Project Interchange Contents
Upon completion of the import, you will have loaded the DocManagementEAR project into the Enterprise Applications folder, the DocManagement project into the Dynamic Web Projects folder, and the cmsetup project into the Other Projects folder.
588
Fixing build path problems

You will need to update the cmsetup ad DocManagement projects Java Build Path in order to point to the correct library locations.
Fix the cmsetup projects build path

1. Right-click the cmsetup project and select Properties. 2. Select Java Build Path and then the Libraries tab. 3. Select the cmb81.jar file and click the Edit.... button. 4. Browse to the location where your cmb81.jar file is located, select it and click Open. 5. Back on the Libraries tab, select the cmbsdk81.jar file and click the Edit... button. 6. Browse to the location where your cmbsdk81.jar file is located, select it and click Open. 7. Click OK to close the Properties window.
Fix the DocManagement projects build path

1. Right-click the DocManagement project and select Properties. 2. Select Java Build Path and then the Libraries tab. 3. Select the cmb81.jar file and click the Edit.... button. 4. Browse to the location where your cmb81.jar file is located, select it and click Open. 5. Back on the Libraries tab, select the cmbsdk81.jar file and click the Edit... button. 6. Browse to the location where your cmbsdk81.jar file is located, select it and click Open. 7. Back on the Libraries tab, select the db2java.zip file and click the Edit... button. 8. Browse to the location where your db2java.zip file is located, select it and click Open. 9. Click OK to close the Properties window.
Clean the projects

1. Select Project from the main Rational Application Developer menu, then Clean... 2. Select the Clean all projects radio button, and click OK.
589
590
Appendix C.
Additional material
This redbook refers to additional material that can be downloaded from the Internet as described below.
Locating the Web material

The Web material associated with this redbook is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/SG246692
Alternatively, you can go to the IBM Redbooks Web site at:

ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with the redbook form number, SG246692.
Using the Web material

The additional Web material that accompanies this redbook includes the following files: File name 6692code.zip Description Sample code for the redbook.
591
System requirements for downloading the Web material

The following system configuration is recommended: Hard disk space: Operating System: Processor: Memory: 25 MB Windows 1 GHz 512 MB
Download and unpack the Web material

This section describes the process for downloading the ITSO sample code 6692code.zip and unpacking the zip file. 1. Download the ITSO sample code 6692code.zip file at:
ftp://www.redbooks.ibm.com/redbooks/SG246692
Note: For a description of the ITSO sample code and where to download, refer to Appendix C, Additional material on page 591. 2. Unpack the 6692code.zip file. For example, we unpacked the zip to the c:\6692code directory.
Description of Web material

After unpacking the Web material (sample code), you will have the a directory structure that looks like that shown in Table 4.
Table 4 Sample directory structure Directory c:\6692code c:\6692code\config c:\6692code\DocMgmtApp c:\6692code\hrapp c:\6692code\user_provisioning c:\6692code\tdi_assemblylines c:\6692code\tdi_cm_connector c:\6692code\tim_serviceprofiles Description Root directory of sample code and configuration files. Configuration files used to set up the runtime environment. Document Management application assets. HR application assets. Provisioning portlet application assets. Tivoli Directory Integrator Assembly Lines for ITSO example. Tivoli Directory Integrator custom DB2 Content Manager connector Tivoli Identity Manager service profiles for the ITSO example.
592
Related publications
The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.
IBM Redbooks
For information on ordering these publications, see How to get IBM Redbooks on page 595. Note that some of the documents referenced here may be available in softcopy only. Develop and Deploy a Secure Portal, Using WebSphere Portal V5 and Tivoli Access Manager V5.1, SG24-6325 Document Management, Using WebSphere Portal V5.0.2 and DB2 Content Manager V8.2, SG24-6349 Identity Management Design Guide with Tivoli Access Manager, SG24-6996 WebSphere Portal Collaboration Security Handbook, SG24-6438 Rational Application Developer V6 Programming Guide, SG24-6449 Lotus Security Handbook, SG24-7017 Enterprise Security Architecture Using IBM Tivoli Security Solutions, SG24-6014
Other publications
These publications are also relevant as further information sources: Planning and Installing Your Content Management System, IBM DB2 Content Manager V8.3 Enterprise Edition, GG27-1332-03 System Administration Guide, IBM DB2 Content Manager V8.3 Enterprise Edition, SC27-1335-06 Server Installation Guide on Windows using WebSphere, IBM Tivoli Identity Manager V4.5.1, SC32-1148-02 Server Installation Guide on Windows using WebSphere, IBM Tivoli Identity Manager V4.5.1, SC32-1148-02 Base Administration Guide, IBM Tivoli Access Manager V5.1, SC32-1360
593
Base Installation Guide, IBM Tivoli Access Manager V5.1, SC32-1362 Administration Java Classes Developer Reference, IBM Tivoli Access Manager V5.1, SC32-1356 Authorization Java Classes Developer Reference, IBM Tivoli Access Manager V5.1, SC32-1350 Command Reference, IBM Tivoli Access Manager V5.1, SC32-1354 Error Message Reference, IBM Tivoli Access Manager V5.1, SC32-1353 Performance Tuning Guide, IBM Tivoli Access Manager V5.1, SC32-1351 Problem Determination Guide, IBM Tivoli Access Manager V5.1, SC32-1352 IBM Global Security Kit, Secure Sockets Layer Introduction and iKeyman Users Guide V7a, SC32-1363 Installation Guide, Reverse Password Synchronization for Tivoli Access Manager WebSEAL (product guide, which is included with IBM Tivoli Identity Manager Agent V4.5.10 for IBM Tivoli Access Manager V5.1 for e-business). Getting Started Guide, IBM Tivoli Directory Integrator V6.0, SC32-1716-00 Users Guide, IBM Tivoli Directory Integrator V6.0, SC32-1718-00 Administrator Guide, IBM Tivoli Directory Integrator V6.0, SC32-1719-00 Reference Guide, IBM Tivoli Directory Integrator V6.0, SC32-1720-00 Users Guide, IBM Tivoli Directory Integrator V5.2, SC32-1378-00
Online resources
These Web sites and URLs are also relevant as further information sources: IBM DB2 Universal Database V8 Fixpacks:
http://www.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v8fphist. d2w/report#WIN-32
IBM Tivoli Support home page:

http://techsupport.services.ibm.com/guides/tivoli_contacts.html
IBM WebSphere Application Server support page:

http://www.ibm.com/software/webservers/appserv/was/support/
IBM Tivoli Directory Server support home page:

http://www.ibm.com/software/sysmgmt/products/support/IBMDirectoryServer.html
594
IBM Tivoli Directory Integrator support home page:

http://www.ibm.com/software/sysmgmt/products/support/IBMDirectoryIntegrator .html
IBM Tivoli Access Manager support home page:

http://www.ibm.com/software/sysmgmt/products/support/IBMTivoliAccessManager fore-business.html
IBM Tivoli Identity Manager APIs:

http://publib.boulder.ibm.com/tividd/td/ITIM/SC32-1683-00/en_US/HTML/index. html
Sun Java 2 Standard Edition V1.3.1._04 download page:

IBM WebSphere Portal V5.1 InfoCenter:

How to get IBM Redbooks

You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at this Web site:
ibm.com/redbooks
Help from IBM

IBM Support and downloads
ibm.com/support
IBM Global Services

ibm.com/services
Related publications
595
596
Index
A
Access Manager node installation 157 software product mapping 133 ActiveX Control 294 actors use case model 101 add new employee application walkthrough 494 adding a theme 576 administration identity and access management 515 administrator authority 217 All Published Documents 586 application deployment 469 application architecture components 22 layer description Client layer 23 Data layer 23 Network layer 23 Portal layer 23 Portal services layer 23 Security layer 23 product mapping Client layer 24 Data layer 24 Network layer 24 Portal layer 24 Portal services layer 24 Security layer 24 application deployment document management 553 HR application 527 application walkthrough 493 architecture guidelines 15 authorization 63 operational modeling application architecture components 22 assign doc mgt report application walkthrough 506 audit trail 5 authentication 4, 7, 48 basic definition 4 guidelines 48 Content Manager using LDAP 53 DB2 Content Manager 49 SSO for Portal and Content Manager 52 WebSphere Portal 48 WebSphere Portal using LDAP 53 high level architecture walkthrough 7 portal and CM integration 52 WebSphere Portal 48 Authorization Tivoli Access Manager configuration 321 WebSphere Portal vs TAM 67 authorization 4, 8, 63 basic definition 4 DB2 Content Manager 64 guidelines 63 DB2 Content Manager 64 Tivili Access Manager 66 WebSphere Portal 63 high level architecture walkthrough 8 Tivoli Access Manager 66 WebSphere Portal 63
B
Back-end application cookies 71 Backup DB2 database 266 basic authentication 298 browser Java plug-in 195 business challenges 99 business scenario business challenges 99 initial context 98
C
Checkpoint for Portal 219, 247 Client layer 23 ClientUserEditSSO 272 Client-Web application single sign-on 55 Cloudscape 236 cluster environment 236 cmbcmenv.properties 266, 269 CMConnector 365
597
common LDAP user registry 52 Conceptual model description 17 ConfigService.properties 316 Configuration authorization WebSphere Portal using TAM 321 DB2 Content Manager LDAP 265 IBM HTTP Server 248 mutual SSL WebSEAL and Portal 276 session timeouts 335 WebSEAL 335 WebSphere Portal 335 TIM Agent for TAM 172 Tivoli Access Manager 162 Web Portal Manager 170 WebSEAL 179 Tivoli Directory Integrator 373 Tivoli Directory Server 150 create a suffix 255 create LDIF file 256 for Tivoli Access Manager 160 import LDIF file 257 Tivoli Identity Manager reverse password synchronization 324, 328 Tivoli Identity Manager Agent for TAM profile 199 Tivoli Web Admin Tool 150, 152 WebSEAL session timeout 335 WebSphere Portal enable LDAP 258 for DB2 UDB 236 IBM HTTP Server 248 LDAP 255 login/logout with WebSEAL 311 session timeout 335 TAM using TAI 284 WebSphere Portal TAI 308 configuration wizard 247 Content Management node installation 200 software product mapping 134 Content Manager create user IDs 252 cookie 61 Corporate theme 576 create a WebSEAL junction 295
create admin user and assign rights 136 create TIM Services 412 Credential Service 5 Credential Vault 5, 54
D
Data layer 23 DB2 ConfigWizard DB transfer 247 DB2 Content Manager authorization components access control list 65 privilege 65 privilege group 65 privilege set 65 ClientUserEditSSO 272 configuration generate cmbcmenv.properties 266 icmxlslg.dll LDAP user exit 270 LDAP 265 create Windows user IDs 204 installation 200 DB2 Content Manager administrator 12 DB2 Content Manager Client search title is not null 507, 577 DB2 Content Manager Client for Windows installation 208 DB2 Information Integrator for Content installation 157 DB2 Universal Database installation 137 DbDriver 238 DbDriverDs 238 DbLibrary 238 DbPassword 238 DbType 238 DbUrl 238 DbUser 238 define additional MIME types WebSphere Application Server 294 deployment application 469 design guidelines 15 Design principals 37 access decision evaluation on-demand 38 access evaluated on-demand implication 38 motivation 38 capture access events
598
implication 39 motivation 39 capture authentication events and logs 38 centralized security 38 implication 38 motivation 38 Development environment architecture overview 340 configuration 356 Content Manager with LDAP 357 DB2 Content Manager with LDAP 356 Portal with LDAP 356 TIM customization 361 WebSphere Portal with LDAP 356 hardware used 341 installation 339 Content Management node 344 DB2 Information Integrator for Content 355 Development node 344 Identity Manager node 343 Tivoli Identity Manager APIs 356 software used 342 software used by ITSO 342 solution software 10 VMWare 343 Development topology selection application considerations 31 develop and test end-to-end 37 develop TDI components 37 develop Web applications 36 document management 35 HR application 34 user provisioning portlet 32 Directory node installation 135 software product mapping 132 Directory Server node start and stop servers 554 document management application deploy to runtime 553 introduction 550 Domain zone categories 18 controlled 19, 21 External Controlled 19 restricted 19, 21 secured 19, 21 uncontrolled 19 dynurl.conf 303
E
employee approval and role assignment application walkthrough 499 employee dept changed by mgr application walkthrough 510 employee password change application walkthrough 503 employee password reset 501 employee role changed by mgr application walkthrough 508 employee self registration application walkthrough 497 employee self-care application walkthrough 504 Enterprise runtime topology 27 Entry runtime topology 25 Extended enterprise HA runtime topology 30 Extended enterprise runtime topology 28 external authorization 327
F
favicon.ico 337 FeedbackDbName 238 FeedbackDbPassword 238 FeedbackDbUrl 238 FeedbackDbUser 238 firewall applications 213 forms authentication 298 front-end use cases 103 functional requirements 99
G
Global Sign-on 5, 55 GSKit 140 GSO See Global Sign-on guidelines architecture 15 authentication 48 authorization 63 design 15 single sign-on 48 single sign-on (SSO) 48 user provisioning 39
H
high level solution architecture 5
Index
599
authorization 8 single sign-on authentication 7 user provisioning 5 HR application deploy to runtime 527 introduction 526 httpd.conf 248, 252
I
IBM DB2 Information Integrator for Content installation 224 IBM DB2 Universal Database 242 IBM GSKit determine version installed 141 installation 140, 142 known issues 142 uninstall 141 IBM HTTP Server configuration 248 certificate 251 enable httpd.conf for SSL 248 WebSphere plug-in 249 enable mutual SSL 283 export CA certificate 278 import WebSEAL certificate 281 installation 220 verification 252 IBM HTTP Server configuration create key store 250 create self-signed certificate 251 IBM Java Runtime Environment installation 158 IBM Lotus Workplace Web Content Manager 247 ICMADMIN 204 ICMCONCT 204 icmxlslg.dll 270 identity and access management administration 515 concepts audit trail 5 authentication 4 authorization 4 Credential Vault 5 identity management 4 shared LDAP user registry 5 single sign-on 5 user provisioning 4 development topologies
application considerations 31 develop all Web applications 36 develop and test end-to-end 37 develop TDI components 37 document management 35 HR application 34 user provisioning portlet 32 high level solution architecture 5 key concepts 4 runtime topologies 24 Enterprise runtime 27 Entry runtime 25 Extended enterprise HA runtime 30 Extended enterprise runtime 28 solution software 9 Identity management 39 identity management 4 Identity Manager node installation 183 software product mapping 134 import WebSphere Portal users into TAM 301 initial context 98 Installation DB2 Content Manager 200 DB2 Content Manager for Windows 208 DB2 Information Integrator for Content 224 DB2 Universal Database V8.2 137 development environment 339 IBM GSKit 159 IBM GSKit V7.0.3.8 140 IBM HTTP Server 221 IBM Java Runtime Environment 158 IBM Rational Application Developer 345 TIM Reverse Password Synchronization Agent 330 Tivoli Access Manager 161 Web Portal Manager 167 Tivoli Directory Client SDK V5.2 159 Tivoli Directory Integrator V6.0 155 Tivoli Directory Server V5.2 147 Tivoli Identity Manager Agent for TAM 171 Tivoli Identity Manager V4.5.1 Fixpack 16 185 WebSEAL 177 WebSphere Application Server V5.0.2 143 WebSphere Application Server V5.1.1 201 WebSphere Portal 210 Windows 2000 Server 135 installation Rational Application Developer
600
Interim Fix 0004 352 WebSphere Portal V5.1 Test Environment 349 Integration guidelines 68 access control of resources within portlets 74 access control of WP resources 74 back-end application cookies 71 junction mapping table 72 TAI junction considerations 70 WebSEAL junctions 68 WebSEAL session considerations 74 WebSEAL URL based access control 73 WebSphere Portal session considerations 74 IT architect 11 IT specialist 11 ITSO working example application deployment 469 deploy provisioning portlets 476 deploy TDI configuration files 472 deploy TDI connector for CM 471 prerequisites 470 TIM customization 475 application walkthrough 493 add new employee 494 assign doc mgt report 506 employee approval 499 employee dept changed by mgr 510 employee password change 503 employee password reset 501 employee role changed by mgr 508 employee self registration 497 employee self-care 504 legal approves report 583 publisher approves report 584 report listed in all published docs 586 research reviewer reviews report 581 researcher accepts report 578 researcher enters report content 578 researcher submits report for review 581 supervisor approves report 583 supervisor assigns report 577 architecture decisions 112 business requirements 99 funtional 99 non-functional 100 business scenario 98 business challenges 99 initial context 98 planning
hardware used 131 runtime environment diagram 130 software used by node 132 sample code download 592 software by node Access Manager node 133 Content Management node 134 Directory node 132 Identity Manager node 134 Portal Server node 135 Reverse Proxy node 133 solution architecture 109 architectural decisions 112 development product mapping 128 development topology selection 128 overview 110 runtime product mapping 127 runtime topology 127 solution architecture details 118 solution design 109 theme 576 use case details UCF01 Hire employee 103 UCF02 Employee self-registration 104 UCF03 Approval and role assignment 105 UCF04 Employee password change 106 UCF05 Employee self-care 106 UCF06 Employee password reset 107 UCF07 Role change 108 UCF08 Department change 108 use case model 101 actors 101 overview 101 summary of use cases 103
J
J2EE developer 11 JAAS configuration 232 Java Archive 294 Java database 236 Java developer 11 Java Runtime Environment 158 java.security properties file 206 JcrDbName 238 jcrDbPassword 238 jcrDbUrl 238 JdbcProvider 238 JMT
Index
601
See Junction Mapping Table jmt.conf 307 JRE See Java Runtime Environment junction 295 Junction Mapping Table limitations 72 Junction mapping table 72 junction mapping table (JMT) 305
Microsoft Windows 2000 Server installation 135 MIME types 294 ActiveX Control (cab) 294 Java Archive (jar) 294 Modifying web.xml 311
N
Network layer 23 Network zone uncontrolled 20 Network zones 20 controlled 20 non-functional requirements 100
K
key concepts 4 audit trail 5 authentication 4 authorization 4 Credential Vault 5 identity management 4 shared LDAP user registry 5 single sign-on 5 user provisioning 4
O
Operational model 16 contents description of each node 16 description of middleware services 16 description of walkthroughs 16 mapping matrix 16 one or more diagrams 16 systems management strategy 16
L
LDAP repository 5 ldapGroupUpdate assembly line 401 ldapmodify 286 Library Server DB2 Content Manager installation 200 Light Weight Third Party Authentication 308 Lightweight Directory Access Protocol 48 Lightweight Third Party Authentication 61 LikemindsDbName 238 LikemindsDbPassword 238 LikemindsDbUrl 238 LikemindsDbUser 238 ListenForCMUpdates event handler 382 ListenForDBUpdates event handler 391 log files Tivoli Directory Integrator 519 Tivoli Identity Manager 519 WebSphere Application Server 519 WebSphere Portal 519 logout.html 314 LTPA tokens 54
P
pdadmin 297, 302, 542, 574 PDAdminID 324 PDAdminPW 324 Physical model description 17 platformCallbackHandler 457 platformContext 456 Portal administrator 12, 217 Portal developer 11 Portal layer 23 Portal Server node software product mapping 135 start and stop servers 554 Portal services layer 23 Portal-Backend SSO 55 portlet service interfaces 454 product mapping 24 Project manager 12 provisioning portlet application 451 add portlets to pages 484 assign resource permissions 487
M
Matching topics to roles 12
602
create admin in LDAP 478 create credential vault slot 478 create portal pages 481 define TIM portlet service 476 deploy TIM portlet service 476 design 452 develop portlet service 454 develop portlets EntitlementRequestPortlet 463 Password change 465 ResetPassword 464 self-registration 461 UpdateEmployeeInfo 468 UpdateMyInfo 467 UpdateRoles 468 enable sessions for anonymous users 477 externalize resources to TAM 491 install portlets 478, 480 Publisher approval 585
Portal administrator 12 Portal developer 11 Project manager 12 Security administrator 12 security architect 11 Runtime environment configuration 235 installation 129 planning 130 solution software 9 Runtime topology selection Enterprise 27 Entry 25 Extended enterprise 28 Extended enterprise HA 30
S
Screaming Media portlets 220 SearchMO 457 Security administrator 12 Security and design guidelines authorization TAM vs WP 67 design principals 37 identity management 39 single sign-on 55 Security architect 11 security audit report generate 516 view 516 Security design objectives 18 security hardening 335 Security layer 23 security problem domain audit trail 3 authorization 3 provision users 3 SSO authentication 3 self-signed certificate 251 Sequence diagrams common access patterns 76 access protected page with existing valid session 79 access protected portal page with invalid credentials 80 access protected portal page, provide credentials 78 access unprotected portal pages 77 both WebSEAL and WebSphere Portal ses-
R
Rational Application Developer installation 345 Rational Product Updater 352 Realms of single sign-on 55 Redbooks Web site 595 Contact us xvii Referential Integrity Plug-in for TIM 189 Research reviewer approval 582 Researcher accepts report assignment 579 Researcher enters report content 580 Resource Manager DB2 Content Manager installation 200 reverse password synchronization 328 Reverse Password Synchronization Agent installation 330 Reverse Proxy node installation 176 software product mapping 133 RMADMIN 205 roles 327 Roles and skills 11 Content Manager administrator 12 IT architect 11 IT specialist 11 J2EE developer 11 Java developer 11
Index
603
sions time out 87 WebSEAL session times out before WebSphere Portal session 82 WebSphere Portal logout after WebSEAL session timeout 91 WebSphere Portal session times out before WebSEAL session 84 Session considerations 74 session timeouts WebSEAL 335 WebSphere Portal 335 signle sign-on authentication 7 Single sign-on guidelines 48 Trust Association Interceptor 57 realms 55 selecting a solution 62 single sign-on 5 Single sign-on guidelines 55 LTPA token 61 solution software development environment 10 runtime environment 9 Specified model description 17 SrvSslCfg 322 SSO See Single sign-on start and stop servers Directory Server node 554 Portal Server node 554 Supervisor assigns research report 507, 578 System Administration Client DB2 Content Manager installation 200
T
TAI See Trust Association Interceptor TAMExternalAccessControlServices 327 Target redbook audience 10 theme 576 Tivoli Access Manager authorization 66 authorization vs WebSphere Portal 67 configuration 162 Authorization Server 164 Directory Server 160
Policy Server 163 Runtime 162 Web Portal Manager 167 create objects WebSphere Portal URIs 303 Global Sign-on 5 installation 161 update Windows registry 165 Java Runtime Environment configuration 223 installation 222 user create 321 Web Portal Manager verification 171 WebSEAL configuration 179 create a junction 295 installation 177 Tivoli Directory Client SDK installation 159 Tivoli Directory Integrator connector overview 364 create DB2 Content Manager Config 374 database Config 386 add ListenFor DBUpdates event handler 391 create database Config 386 DB2 Content Manager Config 374 add cmAdd assembly line 375 add cmDelete assembly line 385 add cmUpdate assembly line 383 add ListenForCMUpdates event handler 382 deploy configuration files 472 deploy connector for CM 471 develop assembly lines 373 develop custom connector 363 compile connector class 368 create configuration file 367 create connector class 364 package connector 368, 370 installation 155 LDAP Config 392 add ldapGroupUpdate assembly line 401 add ldapUpdate assembly line 393 create LDAP Config 393 update groups within ldapUpdate 406 start servers 474 testing Configs 408
604
Tivoli Directory Server 52 configuration 150 create a suffix 255 create LDIF file 256 import LDIF file 257 Configuration Tool 150 configure directory database 151 create a suffix 160 handling thread limitations 190 installation 147 set admin DN and password 150151 Web Administration Tool 151 configuration 152 Tivoli Identity Manager configuration reverse password synchronziation 328 create ACI 329 create and grant organizational roles 419 customization 411, 475 create Organizational Roles 419 create Organizational Units 415 create Password policy 425 create Person 415 create Services 412 create Provisioning Policies 434 create Workflows 426 modify user interface 421 installation 185 reverse password synchronization agent 330 organizational structure create 417 Organizational Units 414 create 415 Persons create 416 Services add Service profiles 412 create Services 413 modify Service profiles 414 using APIs in portlets 452 Tivoli Identity Manager Agent for TAM configuration 172 installation 171 Tivoli Identity Manager API installation 231 ToolBarInclude.jsp 316 Topology zones 17 troubleshooting
TIM Agent for TAM 521 Tivoli Directory Server 519 Tivoli Identity Manager 519 WebSphere Portal Test Environment 522 Trust Association Interceptor 57, 308 methods 58 settings 309 summary how it works 58 Trust Association Interceptor configuration 311
U
URL filtering 299 use case diagram 102 Use case model use case details 103 use case diagram 552 use case summary 103 use case model 101 actors 101 overview 101 user provisioning 45 basic definition 4 guidelines 39 common LDAP directory 41 identity management overview 39 TDI connectors 47 TIM modify user interface 44 TIM OU and Persons 43 TIM password policy 44 TIM provisioning policies 46 TIM service 42 TIM services, workflows, policies 41 TIM workflows 45 high level architecture walkthrough 5 user registry 5
V
Verfication WebSphere Portal LDAP 264 Verification external authorization TAM for WebSphere Portal 327 IBM HTTP Server 252 TAI configuration 302, 311 create/login new user 321 Tivoli Access Manager Web Portal Manager 171 WebSphere Application Server V5.0.2 146
Index
605
WebSphere Portal 219 vertical cloning 236 VMWare 343
W
Web Portal Manager 167 web.xml WebSphere Portal 312 WebSphere Portal SSL 278 webseaId-default.conf 298 WebSEAL 177 additional parameters 301 configuration 179181 create a junction 295 create junction syntax parameters 296 enable forms authentication 298 export certificate 281 favicon.ico configuration 337 import IBM HTTP Server certificate 279 installation 177 junction cookies 300 junction mapping 300 junction mapping table 305 modify URLs to back-end 299 processing of URLs 300 URL based access control 73 URL filtering 299 user sessions 74 WebSEAL junction -b supply option 70 -b supply option using mutual SSL 70 custom TAI plugin 70 WebSEAL junctions 68 options 68 cookie handling 68 encryption 68 number of junctions 68 TAI 70 WebSEAL to web application authentication flow 57 WebSEAL user sessions 74 WebSphere Application Server configuration create host alias for SSL 252 define additional MIME types 294 establish trust relationship TAI 308
verification 253 WebSphere Application Server V5.0.2 installation 143 verification 146 WebSphere Application Server V5.1 installation 201 WebSphere plug-in 220 WebSphere Portal 217, 236 access categories WP_admin_access 303 WP_all_access 303 WP_authenticated_access 303 WP_no_access 303 add a theme 576 authorization vs TAM 67 ConfigService.properties 316 configuration authorization with TAM 321 create Test Environment server 359 enable security 258 external Web server 253 for DB2 UDB 236 IBM HTTP Server 248 LDAP 255 login/logout with WebSEAL 311 session timeout 335 TAM authentication using TAI 284 Test Environment 358 Credential Service 54 Credential Vault 5, 54, 57 databases 236 create 236 installation 210 CDs 211 eliminate prompted for CDs 211 installation types Custom 210 Full 210 Test Environment 210 migration from Cloudscape to DB2 UDB 240 read-only LDAP access 258 Test Environment 349 installation CDs 350 theme 576 URIs 303 define access controls 302 user sessions 75 verification 219
606
WebSphere Portal user sessions 75 WebSphere Portal V5.1 Test Environment 349 Windows 2000 Server create admin user 136, 209 right assignments 136 wmm_LDAP.xml.IBM_DIRECTORY_SERVER.1.w mm 259 WmmDbName 239 WmmDbPassword 239 WmmDbUrl 239 WmmDbUser 239 wmmLDAPAttributes_IBM_DIRECTORY_SERVER .xml 260 workflows 426 WP_admin_access 303 WP_all_access 303 WP_authenticated_access 303 WP_no_access 303 wpconfig.properties 243, 261 Web server settings 254 WpsHostName 320 wp-itso.ldif 256257 wp-junction.pd 295, 297 wpsDbName 238 WpsHostName 254, 320 WpsHostPort 254 wpslogout.html 312 wp-tam-acl.pd 304 wp-tam-user-import.pd 302 wpwin1_svrsslcfg.bat 322
Index
607
608

(1.0 spine) 0.875<->1.498 460 <-> 788 pages
Back cover

Explore identity and access management concepts, architecture and technology options Provision users to multiple systems and develop a custom portal interface Deploy and manage an identity and access management solution
The identity and access management solutions described in this IBM Redbook include the following key areas: User provisioning: Develop a portlet interface for self-care (user and account management), and approval of user provisioning requests by utilizing the Tivoli Identity Manager (TIM) APIs, services, workflow and policies. Tivoli Directory Integrator Assembly Lines and connectors are used to provision users to an LDAP directory, DB2 UDB database, and DB2 Content Manager. Authentication: Provide an integrated single sign-on (SSO) authentication solution using Tivoli Access Manager, and related technologies such as trusted association interceptor (TAI), Credential Vault, and LtpaToken. Authorization: Manage user access control through TIM provisioning policies and role mapping with products that have access models such as Tivoli Access Manager, WebSphere Portal, and DB2 Content Manager. First, we describe the key concepts, benefits, and architecture of an identity and access management solution. Then we present an end-to-end working example scenario for identity and access management system. The example includes business requirements, architecture, details for implementing the runtime and development environments, creation of Identity Manager policies and workflow, provisioning portlet development, deployment, and administration. Finally, we provide procedures to deploy and run the HR and document management applications used in the working example.
INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION
BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.
For more information: ibm.com/redbooks
SG24-6692-00
ISBN 0738490199

Identity and Access Management Solutions Using WebSphere Portal V5.1, Tivoli Identity Manager V4.5.1, and Tivoli Access Manager V5.1 Sg246692

Diunggah oleh

Informasi Dokumen

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Identity and Access Management Solutions Using WebSphere Portal V5.1, Tivoli Identity Manager V4.5.1, and Tivoli Access Manager V5.1 Sg246692

Diunggah oleh

Hak Cipta:

Format Tersedia

Front cover

Identity and Access Management Solutions

Copyright IBM Corp. 2005. All rights reserved.

Identity and Access Management Solutions

3.4.2 3.4.3 3.4.4 3.4.5

Identity and Access Management Solutions

Identity and Access Management Solutions

Identity and Access Management Solutions

Identity and Access Management Solutions

Copyright IBM Corp. 2005. All rights reserved.

Identity and Access Management Solutions

The team that wrote this redbook

Copyright IBM Corp. 2005. All rights reserved.

Identity and Access Management Solutions

Become a published author

Send your comments in an email to:

Identity and Access Management Solutions

Introduction to identity and access management

Copyright IBM Corp. 2005. All rights reserved.

Identity and Access Management Solutions

Copyright IBM Corp. 2005. All rights reserved.

1.1 Introduction to identity and access management

1.1.1 Key concepts

Identity and Access Management Solutions

Shared LDAP user registry

1.1.2 High level solution architecture

Identity and Access Management Solutions

TDI Assembly Lines 1

Client Web Browser

Reverse Proxy TAM WebSEAL

Directory Tivoli Directory Integrator Tivoli Directory Server

Single sign-on (SSO) authentication

Identity and Access Management Solutions

1.2 Solution software

1.2.1 Runtime environment solution software

1.2.2 Development environment solution software

1.3 Target audience

Identity and Access Management Solutions

1.3.1 Roles and skills

Content Manager administrator

1.3.2 Matching redbook topics to roles and skills

Part 2, ITSO identity and access management working example

Identity and Access Management Solutions

Secondary All user roles

Chapter 12, Application walkthrough on page 493

Appendix B, Document management application on page 549

Identity and Access Management Solutions

Architecture and design guidelines

Copyright IBM Corp. 2005. All rights reserved.

2.1 Operational modeling guidelines

2.1.1 Operational model overview

Identity and Access Management Solutions

Conceptual corresponds to an early stage of design. Conceptual nodes

2.1.2 Topology zones

Chapter 2. Architecture and design guidelines

Add security design objectives to architecture

Domain zone categories

Identity and Access Management Solutions

Restricted Protocol Firewall Domain Firewall Domain Firewall

Figure 2-1 Domain zone categories

Chapter 2. Architecture and design guidelines

Internet (uncontrolled zone)

Internet DMZ (controlled zone)