administration guide - ibm - united states server., access manager., , administration guide

Tivoli® Access Manager for e-businessVersion 6.1.1

Administration Guide

SC23-6504-01

��

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

Edition notice

This edition applies to version 6, release 1, modification 1 of IBM Tivoli Access Manager (product number5724-C87) and to all subsequent releases and modifications until otherwise indicated in new editions.

All rights reserved.

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

Contents

About this publication . . . . . . . . ixIntended audience . . . . . . . . . . . . ixPublications . . . . . . . . . . . . . . ix

IBM Tivoli Access Manager for e-business library ixRelated products and publications . . . . . . xiAccessing terminology online . . . . . . . xiiAccessing publications online . . . . . . . xiiOrdering publications . . . . . . . . . . xii

Accessibility . . . . . . . . . . . . . . xiiiTivoli technical training . . . . . . . . . . xiiiTivoli user groups . . . . . . . . . . . . xiiiSupport information . . . . . . . . . . . xiiiConventions used in this publication . . . . . xiv

Typeface conventions . . . . . . . . . . xivOperating system-dependent variables andpaths . . . . . . . . . . . . . . . xiv

Chapter 1. Tivoli Access Manageroverview . . . . . . . . . . . . . . 1Core technologies. . . . . . . . . . . . . 1

Authentication. . . . . . . . . . . . . 2Authorization . . . . . . . . . . . . . 2Quality of Protection. . . . . . . . . . . 2Scalability . . . . . . . . . . . . . . 3Accountability . . . . . . . . . . . . . 4Centralized management . . . . . . . . . 4

Security policy overview . . . . . . . . . . 5Authorization API standard . . . . . . . . . 5Authorization: conceptual model . . . . . . . 6

The benefits of a standard authorization service . 7Tivoli Access Manager authorization serviceoverview . . . . . . . . . . . . . . 8

Tivoli Access Manager authorization service . . . . 9Components . . . . . . . . . . . . . 9Authorization service interfaces . . . . . . 10Replication for scalability and performance . . . 10

Implementing a network security policy . . . . . 11Defining and applying security policy . . . . 11The authorization process: step-by-step . . . . 13

Tivoli Access Manager authorization API . . . . 14Using the authorization API: examples . . . . 14Authorization API: remote cache mode . . . . 15Authorization API: local cache mode . . . . . 16

External authorization capability . . . . . . . 17Extending the authorization service . . . . . 17Imposing conditions on resource requests . . . 18The authorization evaluation process . . . . . 18Implementing an external authorization service 20Deployment strategies . . . . . . . . . . 20

Chapter 2. Web Portal Manager . . . . 23Types of administration . . . . . . . . . . 25Delegate administration tasks . . . . . . . . 25

Self-care . . . . . . . . . . . . . . 26Self-registration . . . . . . . . . . . . 26

Web Portal Manager common tasks . . . . . . 26Starting Web Portal Manager . . . . . . . 26Logging in and signing off . . . . . . . . 27Accessing online help . . . . . . . . . . 27

Customizing the Web Portal Manager interface . . 28Customizing the images . . . . . . . . . 28

Self-registration tasks . . . . . . . . . . . 28Performing self-registration . . . . . . . . 28Changing Java Server Pages . . . . . . . . 29

Chapter 3. Tivoli Access Manageradministration . . . . . . . . . . . 33Domains . . . . . . . . . . . . . . . 33Protected object space . . . . . . . . . . . 34Users and groups . . . . . . . . . . . . 36Security policy . . . . . . . . . . . . . 37ACL policies . . . . . . . . . . . . . . 38

Using ACL policies with the authorization service 38Evaluating ACL policies . . . . . . . . . 39

Protected object policies . . . . . . . . . . 40Authorization rules . . . . . . . . . . . . 40

How authorization rules differ . . . . . . . 40When to use authorization rules . . . . . . 41

Guidelines for a secure object space . . . . . . 41

Chapter 4. Default security policy . . . 43Default administration users and groups . . . . 43

iv-admin group . . . . . . . . . . . . 43sec_master user . . . . . . . . . . . . 43ivmgrd-servers group . . . . . . . . . . 43Administration users . . . . . . . . . . 43

Defining and applying security policy . . . . . 45ACL policies . . . . . . . . . . . . . 45Protected object policies . . . . . . . . . 45Authorization rules . . . . . . . . . . . 46

Sparse security policy model . . . . . . . . 47Security policy inheritance . . . . . . . . 47default-root ACL policy . . . . . . . . . 48Control permission . . . . . . . . . . . 48Traverse permission . . . . . . . . . . 48Resolving an access request . . . . . . . . 49Applying ACL policies to different object types 50ACL policy inheritance example . . . . . . 50

Default ACL policies . . . . . . . . . . . 51default-root ACL policy . . . . . . . . . 51default-management ACL policy . . . . . . 52default-replica ACL policy . . . . . . . . 52default-config ACL policy . . . . . . . . 52default-gso ACL policy . . . . . . . . . 52default-policy ACL policy . . . . . . . . 52default-domain ACL policy . . . . . . . . 53default-proxy ACL policy. . . . . . . . . 53

/Management permissions . . . . . . . . . 53/Management/ACL permissions . . . . . . 53/Management/Action permissions . . . . . 54

© Copyright IBM Corp. 1999, 2010 iii

/Management/POP permissions . . . . . . 55/Management/Server permissions. . . . . . 55/Management/Config permissions . . . . . 55/Management/Policy permissions . . . . . . 56/Management/Replica permissions . . . . . 56/Management/Users permissions . . . . . . 56/Management/Groups permissions . . . . . 57/Management/GSO permissions . . . . . . 58/Management/Rule permissions . . . . . . 58/Management/Domain permissions . . . . . 59/Management/Proxy permissions . . . . . . 59

Chapter 5. Managing domains. . . . . 61Logging in to domains . . . . . . . . . . 61Creating a domain . . . . . . . . . . . . 61Modifying the description for a domain . . . . . 62Listing domains . . . . . . . . . . . . . 63Deleting a domain . . . . . . . . . . . . 64

Chapter 6. Managing object spaces . . 65Creating an object space . . . . . . . . . . 65Listing object spaces . . . . . . . . . . . 67Copying an object space . . . . . . . . . . 67Importing object spaces . . . . . . . . . . 68Exporting object spaces . . . . . . . . . . 68Deleting an object space . . . . . . . . . . 69

Chapter 7. Managing protected objects 71Creating an object . . . . . . . . . . . . 71Listing objects . . . . . . . . . . . . . 73Importing objects . . . . . . . . . . . . 73Exporting objects . . . . . . . . . . . . 74Deleting an object . . . . . . . . . . . . 74

Chapter 8. Managing access control . . 77ACL policies . . . . . . . . . . . . . . 77ACL entries . . . . . . . . . . . . . . 78

Type attribute . . . . . . . . . . . . 79ID attribute . . . . . . . . . . . . . 79Permissions attribute . . . . . . . . . . 79

Action groups and actions . . . . . . . . . 80Default permissions in the primary action group 80Custom permissions in custom action groups . . 81

Managing ACL policies . . . . . . . . . . 83Creating an ACL policy . . . . . . . . . 84Modifying the description of an ACL policy . . 84Listing ACL policies . . . . . . . . . . 85Viewing an ACL policy . . . . . . . . . 85Cloning an ACL policy . . . . . . . . . 86Importing ACL policies . . . . . . . . . 86Exporting all ACL policies . . . . . . . . 86Exporting a single ACL policy . . . . . . . 87Exporting multiple ACL policies . . . . . . 87Attaching an ACL policy to an object . . . . . 88Detaching an ACL policy from an object. . . . 88Locating where an ACL policy is attached . . . 89Deleting an ACL policy . . . . . . . . . 89

Managing ACL entries in ACL policies . . . . . 90Creating an ACL entry . . . . . . . . . 90Modifying permissions for an ACL entry . . . 91

Removing ACL entries from an ACL policy. . . 91Managing extended attributes in ACL policies . . . 92

Creating extended attributes for an ACL policy 92Modifying extended attributes from an ACLpolicy . . . . . . . . . . . . . . . 93Listing extended attributes of an ACL policy . . 93Viewing extended attributes of an ACL policy . . 94Deleting extended attributes from an ACL policy 94Deleting extended attribute values from an ACLpolicy . . . . . . . . . . . . . . . 95

Managing action groups . . . . . . . . . . 95Creating action groups . . . . . . . . . 96Listing action groups . . . . . . . . . . 96Deleting an action group . . . . . . . . . 97

Managing actions . . . . . . . . . . . . 97Creating actions in an action group . . . . . 97Listing actions in an action group . . . . . . 98Deleting actions from an action group . . . . 98

Chapter 9. Protected object policymanagement. . . . . . . . . . . . 101Managing protected object policies . . . . . . 102

Creating a POP. . . . . . . . . . . . 102Modifying a POP . . . . . . . . . . . 104Listing POPs . . . . . . . . . . . . 105Viewing a POP . . . . . . . . . . . . 105Cloning a POP . . . . . . . . . . . . 106Importing POPs . . . . . . . . . . . 106Exporting all POPs . . . . . . . . . . 107Export a single POP . . . . . . . . . . 107Exporting multiple POPs . . . . . . . . 107Attaching a POP to an object . . . . . . . 108Detaching a POP from an object . . . . . . 108Locating where a POP is attached . . . . . 109Deleting a POP . . . . . . . . . . . . 109

Network-based authorization algorithm . . . . 110Network-based authorization policy . . . . . . 110Configuring POP attributes . . . . . . . . . 111

Setting a warning mode . . . . . . . . . 111Setting an audit level . . . . . . . . . . 111Setting a time-of-day restriction . . . . . . 112Specifying IP addresses and ranges . . . . . 113Setting a Quality of Protection level . . . . . 114

Step-up authentication . . . . . . . . . . 114Configuring levels for step-up authentication 115Applying step-up authentication policy. . . . 115Distinguishing step-up from multi-factorauthentication . . . . . . . . . . . . 116

Chapter 10. Authorization rulesmanagement . . . . . . . . . . . . 119Authorization rules overview . . . . . . . . 119Access decision information . . . . . . . . 119

Sources for retrieving ADI . . . . . . . . 119Volatile versus nonvolatile data . . . . . . 121

Authorization rule language . . . . . . . . 122ADI XML document model. . . . . . . . 122XML access decision information . . . . . . 124Defining an XML namespace . . . . . . . 126

Authorization rules evaluator . . . . . . . . 128

iv Administration Guide

Format and constraints of rules . . . . . . 129Examples of authorization rules . . . . . . 131Methods of providing ADI to the rulesevaluator . . . . . . . . . . . . . . 133Reason codes for rule failures . . . . . . . 135

Configuration file and initialization attributes . . 135resource-manager-provided-adi . . . . . . 136dynamic-adi-entitlement-services . . . . . . 136input-adi-xml-prolog and xsl-stylesheet-prolog 136[xmladi-attribute-definitions] . . . . . . . 137

Managing authorization rules . . . . . . . . 137Creating an authorization rule . . . . . . . 138Modifying an authorization rule . . . . . . 139Listing authorization rules . . . . . . . . 140Cloning an authorization rule . . . . . . . 140Importing authorization rules . . . . . . . 140Exporting all authorization rules . . . . . . 141Exporting a single authorization rule . . . . 141Exporting multiple authorization rules . . . . 141Attaching an authorization rule to a protectedobject . . . . . . . . . . . . . . . 142Detaching an authorization rule . . . . . . 143Locating where an authorization rule is attached 143Deleting an authorization rule . . . . . . . 144

Chapter 11. Managing users andgroups . . . . . . . . . . . . . . 145Managing users . . . . . . . . . . . . 145

Creating a user . . . . . . . . . . . . 146Listing users. . . . . . . . . . . . . 147Changing a password . . . . . . . . . 148Setting user policy. . . . . . . . . . . 149Setting global user policy . . . . . . . . 151Importing users . . . . . . . . . . . 153Deleting a user . . . . . . . . . . . . 154

Managing groups . . . . . . . . . . . . 154Creating a group . . . . . . . . . . . 155Listing groups . . . . . . . . . . . . 155Importing groups . . . . . . . . . . . 156Deleting a group . . . . . . . . . . . 157

Enabling dynamic group support. . . . . . . 158LDAP registry . . . . . . . . . . . . 158Active Directory . . . . . . . . . . . 158

Chapter 12. Certificate and passwordmanagement. . . . . . . . . . . . 159Initial configuration . . . . . . . . . . . 160Key file and stash file renewal information . . . 161Trust determination . . . . . . . . . . . 162

Reconfiguring the PDCA on the policy server 163Reconfiguring the PDCA on the runtimemachines . . . . . . . . . . . . . . 163Transferring the PDCA certificate to othermachines . . . . . . . . . . . . . . 164

Server certificate revocation . . . . . . . . 164Additional key and stash file considerations . . . 165

Chapter 13. Server management . . . 167Tivoli Access Manager servers . . . . . . . . 167

Proxy server. . . . . . . . . . . . . 168

Server dependencies . . . . . . . . . . 169Tivoli Access Manager utilities . . . . . . . 170Tivoli Access Manager servers tasks . . . . . . 170

Starting and stopping servers on Linux andUNIX operating systems. . . . . . . . . 170Starting and stopping servers on Windowsoperating systems . . . . . . . . . . . 171

Server configuration file tasks . . . . . . . . 172Changing configuration settings . . . . . . 172Automating server startup at boot time. . . . 173

Policy server administration tasks . . . . . . 174Replicating the authorization database . . . . 174Using the server replicate command. . . . . 175Setting the number of update-notifier threads 175Setting the notification delay time . . . . . 176

Chapter 14. High availability of thepolicy server. . . . . . . . . . . . 177Data integrity . . . . . . . . . . . . . 177Primary and replica LDAP servers . . . . . . 177Active and passive policy servers. . . . . . . 177High availability management. . . . . . . . 178

Verify the policy server setup for highavailability . . . . . . . . . . . . . 178Review log files . . . . . . . . . . . 179

Chapter 15. Multiple-tenancy policyserver . . . . . . . . . . . . . . 181

Chapter 16. Delegated administration 183Overview of delegated administration . . . . . 183Delegated role administration . . . . . . . . 185Administrative tasks for roles . . . . . . . . 186Delegated object space management . . . . . . 186

Structuring the object space for managementdelegation . . . . . . . . . . . . . 187Default administration users and groups . . . 187Example of management delegation . . . . . 187

Delegated user and group management . . . . 188Creating group container objects . . . . . . 189Creating groups . . . . . . . . . . . 190ACL policies affecting group management. . . 191ACL policies affecting user management . . . 192

Security policy for delegated administration . . . 193

Chapter 17. Diagnostics and auditing 197Diagnostic events . . . . . . . . . . . . 197Auditing events . . . . . . . . . . . . 197

Appendix A. Guidelines for changingconfiguring files . . . . . . . . . . 199General guidelines . . . . . . . . . . . 199Default values . . . . . . . . . . . . . 200Strings . . . . . . . . . . . . . . . 200Defined strings . . . . . . . . . . . . . 200File names . . . . . . . . . . . . . . 200Integers . . . . . . . . . . . . . . . 201Boolean values . . . . . . . . . . . . . 201

Contents v

Appendix B. Configuration filereference . . . . . . . . . . . . . 203Location of configuration files . . . . . . . . 204Tivoli Access Manager runtime configuration file 205Authorization server configuration file . . . . . 205Policy server configuration file . . . . . . . 206Policy proxy server configuration file . . . . . 206LDAP server configuration file . . . . . . . 207LDAP client with Active Directory serverconfiguration file . . . . . . . . . . . . 207Active Directory server configuration file . . . . 207Domino server configuration file . . . . . . . 208Web Portal Manager configuration file . . . . . 208Common audit service configuration files . . . . 208Resource manager configuration files . . . . . 209

Appendix C. Configuration file stanzareference . . . . . . . . . . . . . 211[authentication-mechanisms] stanza . . . . . . 211

cert-ldap . . . . . . . . . . . . . . 212cert-uraf . . . . . . . . . . . . . . 213passwd-ldap. . . . . . . . . . . . . 213passwd-uraf . . . . . . . . . . . . . 214

[aznapi-admin-services] stanza . . . . . . . 215service-id . . . . . . . . . . . . . . 215

[aznapi-configuration] stanza . . . . . . . . 217audit-attribute . . . . . . . . . . . . 217azn-app-host . . . . . . . . . . . . 218azn-server-name . . . . . . . . . . . 218cache-refresh-interval . . . . . . . . . . 219cred-attributes-entitlement-services . . . . . 219db-file . . . . . . . . . . . . . . . 220dynamic-adi-entitlement-services . . . . . . 221input-adi-xml-prolog . . . . . . . . . . 221listen-flags . . . . . . . . . . . . . 222logcfg . . . . . . . . . . . . . . . 222mode . . . . . . . . . . . . . . . 223pd-user-name . . . . . . . . . . . . 224pd-user-pwd . . . . . . . . . . . . 224permission-info-returned . . . . . . . . 224policy-cache-size . . . . . . . . . . . 225resource-manager-provided-adi . . . . . . 225xsl-stylesheet-prolog . . . . . . . . . . 226

[aznapi-cred-modification-services] stanza . . . . 227service-id . . . . . . . . . . . . . . 227

[aznapi-entitlement-services] stanza . . . . . . 228service-id . . . . . . . . . . . . . . 229

[aznapi-external-authzn-services] stanza . . . . 230policy-trigger . . . . . . . . . . . . . 230

[aznapi-pac-services] stanza . . . . . . . . 231service-id . . . . . . . . . . . . . . 232

[cars-client] stanza. . . . . . . . . . . . 233compress . . . . . . . . . . . . . . 233diskCachePath . . . . . . . . . . . . 233doAudit . . . . . . . . . . . . . . 234clientPassword . . . . . . . . . . . . 235clientUserName . . . . . . . . . . . 235errorFilePath . . . . . . . . . . . . 235flushInterval. . . . . . . . . . . . . 236keyFilePath . . . . . . . . . . . . . 236

lowWater . . . . . . . . . . . . . . 237hiWater . . . . . . . . . . . . . . 237maxCacheFiles . . . . . . . . . . . . 237maxCacheFileSize . . . . . . . . . . . 238maxErrorFiles . . . . . . . . . . . . 238maxErrorFileSize . . . . . . . . . . . 238maxTraceFiles . . . . . . . . . . . . 239maxTraceFileSize . . . . . . . . . . . 239numberCMThreads . . . . . . . . . . 239numberEQThreads . . . . . . . . . . 240numberRetries . . . . . . . . . . . . 240queueSize . . . . . . . . . . . . . 240rebindInterval . . . . . . . . . . . . 241retryInterval . . . . . . . . . . . . . 241serverURL . . . . . . . . . . . . . 241stashFilePath . . . . . . . . . . . . 242traceLevel . . . . . . . . . . . . . 242traceFilePath . . . . . . . . . . . . 242transferSize . . . . . . . . . . . . . 243useDiskCache . . . . . . . . . . . . 243

[cars-filter] stanza . . . . . . . . . . . . 244auditevent . . . . . . . . . . . . . 244

[configuration-database] stanza . . . . . . . 246file . . . . . . . . . . . . . . . . 246

[delegated-admin] stanza . . . . . . . . . 247authorize-group-list . . . . . . . . . . 247

[domains] and [domain=domain_name] stanzas . . 248allowed-registry-substrings . . . . . . . . 248database-path . . . . . . . . . . . . 249domain . . . . . . . . . . . . . . 249

[ivacld] stanza . . . . . . . . . . . . . 250log-file . . . . . . . . . . . . . . 250logcfg . . . . . . . . . . . . . . . 251permit-unauth-remote-caller . . . . . . . 252pid-file . . . . . . . . . . . . . . 252tcp-req-port . . . . . . . . . . . . . 253unix-user . . . . . . . . . . . . . . 253unix-group . . . . . . . . . . . . . 254

[ivmgrd] stanza . . . . . . . . . . . . 254provide-last-login . . . . . . . . . . . 254provide-last-pwd-change . . . . . . . . 255auto-database-update-notify . . . . . . . 255ca-cert-download-enabled . . . . . . . . 256database-path . . . . . . . . . . . . 256log-file . . . . . . . . . . . . . . 257logcfg . . . . . . . . . . . . . . . 257max-notifier-threads . . . . . . . . . . 258notifier-wait-time . . . . . . . . . . . 259pid-file . . . . . . . . . . . . . . 259standby . . . . . . . . . . . . . . 260tcp-req-port . . . . . . . . . . . . . 261unix-user . . . . . . . . . . . . . . 261unix-group . . . . . . . . . . . . . 261

[ldap] stanza . . . . . . . . . . . . . 262enhanced-pwd-policy. . . . . . . . . . 262max-auth-connections . . . . . . . . . 264enable-last-login . . . . . . . . . . . 265auth-using-compare . . . . . . . . . . 265authn-timeout . . . . . . . . . . . . 266bind-dn . . . . . . . . . . . . . . 266cache-enabled . . . . . . . . . . . . 267

vi Administration Guide

cache-group-expire-time . . . . . . . . . 267cache-group-membership . . . . . . . . 268cache-group-size . . . . . . . . . . . 268cache-policy-expire-time . . . . . . . . . 269cache-policy-size . . . . . . . . . . . 269cache-return-registry-id . . . . . . . . . 270cache-use-user-cache . . . . . . . . . . 270cache-user-expire-time . . . . . . . . . 271cache-user-size . . . . . . . . . . . . 271default-policy-override-support . . . . . . 271ldap-server-config . . . . . . . . . . . 272login-failures-persistent . . . . . . . . . 273max-search-size. . . . . . . . . . . . 273port . . . . . . . . . . . . . . . 274prefer-readwrite-server . . . . . . . . . 274search-timeout . . . . . . . . . . . . 274ssl-enabled . . . . . . . . . . . . . 275ssl-keyfile . . . . . . . . . . . . . 276ssl-keyfile-dn . . . . . . . . . . . . 276ssl-keyfile-pwd . . . . . . . . . . . . 277user-and-group-in-same-suffix . . . . . . . 277

[ldap] stanza for ldap.conf . . . . . . . . . 278cache-enabled . . . . . . . . . . . . 278connection-inactivity . . . . . . . . . . 278dynamic-groups-enabled . . . . . . . . 279enabled . . . . . . . . . . . . . . 279host . . . . . . . . . . . . . . . 280ignore-suffix . . . . . . . . . . . . . 280max-search-size. . . . . . . . . . . . 281max-server-connections . . . . . . . . . 281novell-suffix-search-enabled . . . . . . . 282port . . . . . . . . . . . . . . . 283replica. . . . . . . . . . . . . . . 283secauthority-suffix . . . . . . . . . . . 284ssl-port . . . . . . . . . . . . . . 284

[manager] stanza . . . . . . . . . . . . 285management-domain . . . . . . . . . . 285master-host . . . . . . . . . . . . . 286master-port . . . . . . . . . . . . . 286

[meta-info] stanza . . . . . . . . . . . . 287version . . . . . . . . . . . . . . 287

[pdconfig] stanza . . . . . . . . . . . . 287LdapSSL . . . . . . . . . . . . . . 287LdapSSLKeyFile . . . . . . . . . . . 288LdapSSLKeyFileDn . . . . . . . . . . 288LdapSSLKeyFilePwd . . . . . . . . . . 289

[pdaudit-filter] stanza . . . . . . . . . . 289logcfg . . . . . . . . . . . . . . . 289

[pdmgrproxyd] stanza . . . . . . . . . . 290cache-database . . . . . . . . . . . . 290log-file . . . . . . . . . . . . . . 291pid-file . . . . . . . . . . . . . . 292tcp-req-port . . . . . . . . . . . . . 292unix-group . . . . . . . . . . . . . 293unix-user . . . . . . . . . . . . . . 293

[pdrte] stanza . . . . . . . . . . . . . 294boot-start-ivacld . . . . . . . . . . . 294boot-start-ivmgrd . . . . . . . . . . . 294boot-start-pdproxyd . . . . . . . . . . 295configured . . . . . . . . . . . . . 295tivoli_common_dir . . . . . . . . . . 295

user-reg-host . . . . . . . . . . . . 296user-reg-hostport . . . . . . . . . . . 296user-reg-server . . . . . . . . . . . . 296user-reg-type . . . . . . . . . . . . 296

[pdwpm] stanza . . . . . . . . . . . . 296aclMembership . . . . . . . . . . . . 297authMethod . . . . . . . . . . . . . 297bannerFile . . . . . . . . . . . . . 298changePassword . . . . . . . . . . . 298debug . . . . . . . . . . . . . . . 299infoBarGif . . . . . . . . . . . . . 299jrteHost . . . . . . . . . . . . . . 300jrteProps . . . . . . . . . . . . . . 300loginGif . . . . . . . . . . . . . . 300splashGif . . . . . . . . . . . . . . 300wasEmbedded . . . . . . . . . . . . 301

[ssl] stanza . . . . . . . . . . . . . . 301ssl-authn-type . . . . . . . . . . . . 302ssl-auto-refresh . . . . . . . . . . . . 302ssl-cert-life . . . . . . . . . . . . . 302ssl-enable-fips . . . . . . . . . . . . 303ssl-io-inactivity-timeout . . . . . . . . . 303ssl-keyfile . . . . . . . . . . . . . 304ssl-keyfile-label . . . . . . . . . . . . 304ssl-keyfile-stash. . . . . . . . . . . . 305ssl-listening-port . . . . . . . . . . . 305ssl-local-domain . . . . . . . . . . . 306ssl-maximum-worker-threads . . . . . . . 306ssl-pwd-life . . . . . . . . . . . . . 307ssl-v3-timeout . . . . . . . . . . . . 307

[ssl] stanza for ldap.conf. . . . . . . . . . 308ssl-local-domain . . . . . . . . . . . 308

[uraf-registry] stanza . . . . . . . . . . . 308bind-id . . . . . . . . . . . . . . 309cache-mode . . . . . . . . . . . . . 309cache-lifetime . . . . . . . . . . . . 309cache-size . . . . . . . . . . . . . 310uraf-registry-config . . . . . . . . . . 311

[uraf-registry] stanza for domino.conf . . . . . 312enabled . . . . . . . . . . . . . . 312NAB . . . . . . . . . . . . . . . 312PDM . . . . . . . . . . . . . . . 313server . . . . . . . . . . . . . . . 313uraf-return-registry-id . . . . . . . . . 314

[uraf-registry] stanza for activedir.conf . . . . . 314dnforpd . . . . . . . . . . . . . . 314domain . . . . . . . . . . . . . . 315dynamic-groups-enabled . . . . . . . . 315enabled . . . . . . . . . . . . . . 315hostname. . . . . . . . . . . . . . 316multi-domain . . . . . . . . . . . . 316uraf-return-registry-id . . . . . . . . . 316use-email-as-user-id . . . . . . . . . . 317useEncryption . . . . . . . . . . . . 317

[uraf-registry] stanza for activedir_ldap.conf . . . 318change-pwd-using-ldap-api. . . . . . . . 318dnforpd . . . . . . . . . . . . . . 318domain . . . . . . . . . . . . . . 319dynamic-groups-enabled . . . . . . . . 320enabled . . . . . . . . . . . . . . 320ldap-client-timeout . . . . . . . . . . 321

Contents vii

max-connections-per-ad-domain . . . . . . 321multi-domain . . . . . . . . . . . . 321primary-domain . . . . . . . . . . . 322ssl-keyfile . . . . . . . . . . . . . 322ssl-keyfile-label . . . . . . . . . . . . 323ssl-keyfile-pwd . . . . . . . . . . . . 324uraf-return-registry-id . . . . . . . . . 324use-email-as-user-id . . . . . . . . . . 324ad-gc-server . . . . . . . . . . . . . 325ad-gc-port . . . . . . . . . . . . . 325UseSSL . . . . . . . . . . . . . . 326

[xmladi-attribute-definitions] stanza . . . . . . 326AttributeName . . . . . . . . . . . . 327

Appendix D. User registry differences 329General concerns . . . . . . . . . . . . 329LDAP concerns . . . . . . . . . . . . . 329

Sun Java System Directory Server concerns . . 330Microsoft Active Directory Application Mode(ADAM) concerns . . . . . . . . . . . 330

URAF concerns. . . . . . . . . . . . . 331Lotus Domino Server concerns . . . . . . 331Microsoft Active Directory Server concerns . . 331

Length of names . . . . . . . . . . . . 334

Appendix E. pdadmin to Web PortalManager equivalents . . . . . . . . 337

Appendix F. Managing user registries 345LDAP-specific tasks . . . . . . . . . . . 345

LDAP failover configuration . . . . . . . 345Using valid characters for LDAP user andgroup names . . . . . . . . . . . . 349Applying Tivoli Access Manager ACLs to newLDAP suffixes . . . . . . . . . . . . 350Setting the password history policy . . . . . 361

Active Directory-specific tasks . . . . . . . . 362Setting up Microsoft Windows 2003 DomainName System for Active Directory . . . . . 362

Adding a new domain name to a DNS . . . . 363Updating the Tivoli Access Manager schema 363Adding a Tivoli Access Manager user to theActive Directory system group . . . . . . 364Using valid characters for Active Directory user,group, and distinguished names . . . . . . 364Importing dynamic groups to Tivoli AccessManager . . . . . . . . . . . . . . 366Enabling change user password requests to beperformed using LDAP APIs . . . . . . . 366Enabling support for the use of email address orother alternate format as user identity . . . . 367

Novell-specific tasks . . . . . . . . . . . 368Updating the eDirectory schema . . . . . . 368Novell eDirectory maintenance activities thatcan damage schema modifications applied byTivoli Access Manager . . . . . . . . . 370

Appendix G. Support information . . . 373Searching knowledge bases . . . . . . . . . 373

Searching information centers . . . . . . . 373Searching the Internet . . . . . . . . . 373

Obtaining fixes . . . . . . . . . . . . . 373Registering with IBM Software Support . . . . 374Receiving weekly software updates . . . . . . 374Contacting IBM Software Support . . . . . . 375

Determining the business impact . . . . . . 375Describing problems and gathering information 376Submitting problems . . . . . . . . . . 376

Appendix H. Notices . . . . . . . . 379Trademarks . . . . . . . . . . . . . . 380

Glossary . . . . . . . . . . . . . 383

Index . . . . . . . . . . . . . . . 393

viii Administration Guide

About this publication

IBM® Tivoli® Access Manager for e-business provides an access controlmanagement solution to centralize network and application security policy fore-business applications.

The IBM Tivoli Access Manager for e-business: Administration Guide provides acomprehensive set of procedures and for managing Tivoli Access Manager serversand resources. This guide also provides you with valuable background andconceptual information about the wide range of Tivoli Access Managerfunctionality.

Intended audienceThis guide is for system administrators responsible for the deployment andadministration of base Tivoli Access Manager software.

Readers should be familiar with the following:v Microsoft® Windows® and UNIX® operating systemsv Database architecture and conceptsv Security managementv Internet protocols, including HTTP and TCP/IPv Lightweight Directory Access Protocol (LDAP) and directory servicesv Authentication and authorizationv Tivoli Access Manager security model and its capabilities

You should also be familiar with SSL protocol, key exchange (public and private),digital signatures, cryptographic algorithms, and certificate authorities.

PublicationsThis section lists publications in the IBM Tivoli Access Manager for e-businesslibrary and related documents. The section also describes how to access Tivolipublications online and how to order Tivoli publications.

IBM Tivoli Access Manager for e-business libraryThe following documents are in the Tivoli Access Manager for e-business library:v IBM Tivoli Access Manager for e-business: Quick Start Guide, GI11-9333

Provides steps that summarize major installation and configuration tasks.v IBM Tivoli Access Manager for e-business: Release Notes, GC23-6501

Provides information about installing and getting started, system requirements,and known installation and configuration problems.

v IBM Tivoli Access Manager for e-business: Installation Guide, GC23-6502Explains how to install and configure Tivoli Access Manager for e-business.

v IBM Tivoli Access Manager for e-business: Upgrade Guide, SC23-6503Upgrade from version 5.0, 6.0, or 6.1 to version 6.1.1.

v IBM Tivoli Access Manager for e-business: Administration Guide, SC23-6504

© Copyright IBM Corp. 1999, 2010 ix

Describes the concepts and procedures for using Tivoli Access Manager. Providesinstructions for performing tasks from the Web Portal Manager interface and byusing the pdadmin utility.

v IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide,SC23-6505Provides background material, administrative procedures, and for usingWebSEAL to manage the resources of your secure Web domain.

v IBM Tivoli Access Manager for e-business: Plug-in for Edge Server AdministrationGuide, SC23-6506Provides instructions for integrating Tivoli Access Manager with the IBMWebSphere® Edge Server application.

v IBM Tivoli Access Manager for e-business: Plug-in for Web Servers AdministrationGuide, SC23-6507Provides procedures and for securing your Web domain using a Web serverplug-in.

v IBM Tivoli Access Manager for e-business: Shared Session Management AdministrationGuide, SC23-6509Provides deployment considerations and operational instructions for the sessionmanagement server.

v IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide,SC23-6510Provides information for enabling SSL communication in the Tivoli AccessManager environment.

v IBM Tivoli Access Manager for e-business: Auditing Guide, SC23-6511Provides information about configuring and managing audit events using thenative Tivoli Access Manager approach and the Common Auditing andReporting Service. You can also find information about installing andconfiguring the Common Auditing and Reporting Service. Use this service forgenerating and viewing operational reports.

v IBM Tivoli Access Manager for e-business: Command Reference, SC23-6512Provides about the commands, utilities, and scripts that are provided with TivoliAccess Manager.

v IBM Tivoli Access Manager for e-business: Administration C API Developer Reference,SC23-6513Provides about using the C language implementation of the administration APIto enable an application to perform Tivoli Access Manager administration tasks.

v IBM Tivoli Access Manager for e-business: Administration Java Classes DeveloperReference, SC23-6514Provides about using the Java™ language implementation of the administrationAPI to enable an application to perform Tivoli Access Manager administrationtasks.

v IBM Tivoli Access Manager for e-business: Authorization C API Developer Reference,SC23-6515Provides about using the C language implementation of the authorization API toenable an application to use Tivoli Access Manager security.

v IBM Tivoli Access Manager for e-business: Authorization Java Classes DeveloperReference, SC23-6516Provides about using the Java language implementation of the authorization APIto enable an application to use Tivoli Access Manager security.

x Administration Guide

v IBM Tivoli Access Manager for e-business: Web Security Developer Reference,SC23-6517Provides programming and for developing authentication modules.

v IBM Tivoli Access Manager for e-business: Troubleshooting Guide, GC27-2717Provides problem determination information.

v IBM Tivoli Access Manager for e-business: Error Message Reference, GI11-8157Provides explanations and recommended actions for the messages and returncode.

v IBM Tivoli Access Manager for e-business: Performance Tuning Guide, SC23-6518Provides performance tuning information for an environment consisting of TivoliAccess Manager with the IBM Tivoli Directory Server as the user registry.

Related products and publicationsThis section lists the IBM products that are related to and included with a TivoliAccess Manager solution.

IBM Global Security KitTivoli Access Manager provides data encryption through the use of the GlobalSecurity Kit (GSKit), version 7.0. GSKit is included on the IBM Tivoli AccessManager Base CD for your particular platform, as well as on the IBM Tivoli AccessManager Web Security CDs, the IBM Tivoli Access Manager Shared Session ManagementCDs, and the IBM Tivoli Access Manager Directory Server CDs.

The GSKit package provides the iKeyman key management utility, gsk7ikm, whichcreates key databases, public-private key pairs, and certificate requests. The IBMGlobal Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide isavailable on the Tivoli Information Center Web site in the same section as theTivoli Access Manager product documentation.

IBM Tivoli Directory ServerIBM Tivoli Directory Server, version 6.1, is included on the IBM Tivoli AccessManager Directory Server set of CDs for the required operating system.

You can find additional information about Tivoli Directory Server at:

http://www.ibm.com/software/tivoli/products/directory-server/

IBM Tivoli Directory IntegratorIBM Tivoli Directory Integrator, version 6.1.1, is included on the IBM TivoliDirectory Integrator CD for the required operating system.

You can find additional information about IBM Tivoli Directory Integrator at:

http://www-306.ibm.com/software/tivoli/products/directory-integrator/

IBM DB2 Universal DatabaseIBM DB2 Universal Database™ Enterprise Server Edition, version 9.1, is providedon the IBM Tivoli Access Manager Directory Server set of CDs and is installed withthe Tivoli Directory Server software. DB2® is required when using Tivoli DirectoryServer or z/OS® LDAP servers as the user registry for Tivoli Access Manager. Forz/OS LDAP servers, you must separately purchase DB2.

You can find additional information about DB2 at:

About this publication xi

http://www.ibm.com/software/tivoli/products/directory-server

http://www-306.ibm.com/software/tivoli/products/directory-integrator/

http://www.ibm.com/software/data/db2

IBM WebSphere Application ServerWebSphere Application Server, version 6.1, is included on the IBM Tivoli AccessManager WebSphere Application Server set of CDs for the required operating system.WebSphere Application Server enables the support of the following applications:v Web Portal Manager interface, which administers Tivoli Access Manager.v Web Administration Tool, which administers Tivoli Directory Server.v Common Auditing and Reporting Service, which processes and reports on audit

events.v Session management server, which manages shared session in a Web security

server environment.v Attribute Retrieval Service.

You can find additional information about WebSphere Application Server at:

http://www.ibm.com/software/webservers/appserv/infocenter.html

Accessing terminology onlineThe Tivoli Software Glossary includes definitions for many of the technical termsrelated to Tivoli software. The Tivoli Software Glossary is available at the followingTivoli software library Web site:

http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm

The IBM Terminology Web site consolidates the terminology from IBM productlibraries in one convenient location. You can access the Terminology Web site athttp://www.ibm.com/software/globalization/terminology .

Accessing publications onlineThe documentation CD contains the publications that are in the product library.The format of the publications is PDF, HTML, or both. Refer to the readme file onthe CD for instructions on how to access the documentation.

The product CD contains the publications that are in the product library. Theformat of the publications is PDF, HTML, or both. To access the publications usinga Web browser, open the infocenter.html file. The file is in the appropriatepublications directory on the product CD.

IBM posts publications for this and all other Tivoli products, as they becomeavailable and whenever they are updated, to the Tivoli Documentation CentralWeb site at http://www.ibm.com/tivoli/documentation.

Note: If you print PDF documents on other than letter-sized paper, set the optionin the File → Print window that allows Adobe Reader to print letter-sizedpages on your local paper.

Ordering publicationsYou can order many Tivoli publications online at http://www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss.

You can also order by telephone by calling one of these numbers:v In the United States: 800-879-2755

xii Administration Guide

http://www.ibm.com/software/data/db2

http://www.ibm.com/software/webservers/appserv/was

http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm

http://www.ibm.com/software/globalization/terminology

http://www.ibm.com/tivoli/documentation

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

v In Canada: 800-426-4968

In other countries, contact your software account representative to order Tivolipublications. To locate the telephone number of your local representative, performthe following steps:1. Go to http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss.2. Select your country from the list and click Go.3. Click About this site in the main panel to see an information page that

includes the telephone number of your local representative.

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

Visit the IBM Accessibility Center at http://www.ibm.com/alphaworks/topics/accessibility/ for more information about IBM's commitment to accessibility.

For additional information, see the Accessibility Appendix in IBM Tivoli AccessManager for e-business Installation Guide.

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

Tivoli user groupsTivoli user groups are independent, user-run membership organizations thatprovide Tivoli users with information to assist them in the implementation ofTivoli Software solutions. Through these groups, members can share informationand learn from the knowledge and experience of other Tivoli users. Tivoli usergroups include the following members and groups:v 23,000+ membersv 144+ groups

Access the link for the Tivoli Users Group at http://www.tivoli-ug.org/.

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

OnlineAccess the Tivoli Software Support site at http://www.ibm.com/software/sysmgmt/products/support/index.html?ibmprd=tivman. Access the IBMSoftware Support site at http://www.ibm.com/software/support/probsub.html .

IBM Support AssistantThe IBM Support Assistant is a free local software serviceability workbenchthat helps you resolve questions and problems with IBM software

About this publication xiii

http://www.ibm.com/alphaworks/topics/accessibility/

http://www.ibm.com/alphaworks/topics/accessibility/

http://www.ibm.com/software/tivoli/education

http://www.tivoli-ug.org/

http://www.ibm.com/software/sysmgmt/products/support/index.html?ibmprd=tivman

http://www.ibm.com/software/sysmgmt/products/support/index.html?ibmprd=tivman

http://www.ibm.com/software/support/probsub.html


products. The Support Assistant provides quick access to support-relatedinformation and serviceability tools for problem determination. To installthe Support Assistant software, go to http://www.ibm.com/software/support/isa.

Troubleshooting GuideFor more information about resolving problems, see the IBM Tivoli AccessManager for e-business Installation Guide.

Conventions used in this publicationThis publication uses several conventions for special terms and actions, operatingsystem-dependent commands, and paths.

Typeface conventionsThis publication uses the following typeface conventions:

Bold

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

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

v Keywords and parameters in text

Italic

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

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

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

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

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

Monospace

v Examples and code examplesv File names, programming keywords, and other elements that are difficult

to distinguish from surrounding textv Message text and prompts addressed to the userv Text that the user must typev Values for arguments or command options

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

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

xiv Administration Guide

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

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

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

About this publication xv

xvi Administration Guide

Chapter 1. Tivoli Access Manager overview

Tivoli Access Manager is an authentication and authorization solution for corporateWeb, client/server, and existing applications. Tivoli Access Manager allows you tocontrol user access to protected information and resources. By providing acentralized, flexible, and scalable access control solution, Tivoli Access Managerallows you to build secure and easy-to-manage network-based applications ande-business infrastructure.

Tivoli Access Manager supports authentication, authorization, data security, andresource management capabilities. You use Tivoli Access Manager in conjunctionwith standard Internet-based applications to build highly secure and well-managedintranets.

Tivoli Access Manager provides the following frameworks:

Authentication frameworkThe Tivoli Access Manager authentication service uses a wide range ofbuilt-in authenticators and supports external authenticators.

Authorization frameworkThe Tivoli Access Manager authorization service, accessed through astandard authorization application programming interface (API), providespermit and deny decisions on access requests for native Tivoli AccessManager servers and other applications.

The authorization service, together with resource managers, provides astandard authorization mechanism for business network systems.

Tivoli Access Manager can be integrated into existing and emerging infrastructuresto provide secure, centralized policy management capability.

The following resource managers are some of the existing resource managers:

IBM Tivoli Access Manager WebSEALManages and protects Web-based information and resources. WebSEAL isincluded with Tivoli Access Manager for e-business.

IBM Tivoli Access Manager for Operating SystemsProvides a layer of authorization policy enforcement on Linux® and UNIXoperating systems in addition to that provided by the native operatingsystem.

Existing applications can take advantage of the Tivoli Access Managerauthorization service as well as provide a common security policy for the entireenterprise.

Core technologiesThe Tivoli Access Manager network security management solution provides andsupports the following core technologies:v Authenticationv Authorizationv Quality of Protection

© Copyright IBM Corp. 1999, 2010 1

v Scalabilityv Accountabilityv Centralized management

AuthenticationAuthentication is the first step a user must take when making a request for aresource that is protected by Tivoli Access Manager. During authentication, a useridentity is validated. The authentication process is usually dependent on thespecific requirements of the service-providing application. Tivoli Access Managerallows a highly flexible approach to authentication through the use of theauthorization API.

Tivoli Access Manager provides built-in support of user name and passwordauthentication through the authorization API. Applications can build any customauthentication mechanism that uses the authorization API.

AuthorizationAuthorization enforces the security policy by determining what objects a user canaccess and what actions a user can take on those objects and then grantingappropriate access to the user. Tivoli Access Manager handles authorizationthrough the use of the following:v Tivoli Access Manager authorization servicev Access control lists (ACLs), protected object policies (POPs), and authorization

rules for fine-grained access controlv Standards-based authorization API, using the aznAPI for C language

applications, and the Java Authentication and Authorization Service (JAAS) forJava language applications

v External authorization service capability

Quality of ProtectionQuality of Protection (QoP) is the degree to which Tivoli Access Manager protectsany information that is transmitted between a client and a server. The quality ofdata protection is determined by the combined effect of encryption standards andmodification-detection algorithms. The resource manager is responsible forensuring that the quality of data protection is enforced.

Tivoli Access Manager supports the following levels of Quality of Protection:v Standard Transmission Control Protocol (TCP) communication (no protection)v Data integrity – protects messages (data stream) from being modified during

network communicationv Data privacy – protects messages from being modified or inspected during

network communication

Supported encryption ciphersTivoli Access Manager uses encryption ciphers that are provided by GSKit andJava Secure Socket Extension (JSSE). To learn about these encryption ciphers, seethe GSKit and JSSE documentation.

Secure communicationTivoli Access Manager supports the data integrity and data privacy provided bythe Secure Socket Layer (SSL) communication protocol and the Transport LayerSecurity (TLS) communication protocol.

2 Administration Guide

The SSL handshake protocol provides security and privacy over the Internet. SSLworks by using public key for authentication and secret key to encrypt data that istransferred over the SSL connection.

The TLS protocol meets the Federal Information Processing Standards (FIPS) 140-2standard that describes United States Federal government requirements forsensitive, but unclassified use of information technology products. When FIPSmode is enabled in Tivoli Access Manager, TLS version 1 (TLSv1) is used insteadof SSL version 3 (SSLv3).

Tivoli Access Manager generates keys and certificates using FIPS-approvedoperations. Therefore, the client- and server-side keys and certificates are alwaysFIPS approved.

To switch from SSL to TLS, all server and remote runtime configurations must bechanged. In Tivoli Access Manager this indicates whether FIPS mode is enabled ordisabled in the environment. When FIPS mode is enabled, the desired protocol isTLS. When FIPS mode is not enabled, the desired protocol is SSL.

Note: SSL and TLS protocols cannot be mixed in a Tivoli Access Managerenvironment. If a previous release of Tivoli Access Manager runtime did notsupport TLS (currently communicating with SSL), these runtimes cannotcommunicate with a server that is enabled for FIPS (now communicatingwith TLS).

ScalabilityScalability is the ability to respond to increasing numbers of users who accessresources in the domain. Tivoli Access Manager uses the following techniques toprovide scalability:v Replication of services

– Authentication services– Authorization services– Security policies– Data encryption services– Auditing services

v Front-end replicated servers– Mirrored resources for high availability– Load balancing client requests

v Back-end replicated servers– Back-end servers can be Tivoli Access Manager WebSEAL, Tivoli Access

Manager for Operating Systems, Tivoli Access Manager for BusinessIntegration, or other application servers

– Mirrored resources (unified object space) for high availability– Additional content and resources– Load balancing of incoming requests

v Optimized performance by allowing for the off-loading of authentication servicesand authorization services to separate servers

v Scaled deployment of services without increasing management overhead

Chapter 1. Tivoli Access Manager overview 3

AccountabilityTivoli Access Manager provides a number of logging and auditing capabilities. Logfiles capture any error and warning messages generated by Tivoli Access Managerservers. Audit trail files monitor Tivoli Access Manager server activity.

Centralized managementThe following methods are provided for managing security policy and the TivoliAccess Manager servers:v pdadmin command line interfacev Web Portal Manager graphical user interface (GUI)v Administration API

You can accomplish most tasks using any of these methods. However, some taskscannot be performed using Web Portal Manager.

pdadmin command interfaceThe pdadmin command line interface is used for Tivoli Access Manageradministration. This interface provides commands for managing users, groups,roles, permissions, policies, domains, and servers, as well as for performing othertasks. This interface can be used in scripts or batch files to automate processing.

This interface is installed as part of the Tivoli Access Manager runtime package.

For specific task information, see the task-specific chapters in this guide. Fordetailed syntax information about the pdadmin command line interface, see theIBM Tivoli Access Manager for e-business: Command Reference.

Web Portal ManagerWeb Portal Manager is an optional Web-based interface used for Tivoli AccessManager administration. Web Portal Manager allows you to performadministrative tasks, such as managing users, groups, roles, permissions, policies,domains, and servers. This optional interface must be installed separately from theTivoli Access Manager Web Portal Manager CD for your operating system. A keyadvantage to using Web Portal Manager is that you can perform these tasksremotely using any supported Web browser. You do not need any special networkconfiguration.

For specific task information, refer to chapters in this guide. For more informationon using Web Portal Manager, see the Web Portal Manager online help.

Administration APIThe administration API provided by Tivoli Access Manager is a set ofprogramming interfaces that allow you to write applications to manage users,groups, roles, permissions, policies, domains, and servers. Both C and Javalanguage versions of these functions are available.

Details on the administration API are provided in the IBM Tivoli Access Manager fore-business: Administration C API Developer Reference and the IBM Tivoli AccessManager for e-business: Administration Java Classes Developer Reference.


Security policy overviewThe goal of any security policy is to adequately protect business assets andresources with a minimal amount of administrative effort. First, you must definewhat resources need to be protected. These could be any type of data object, suchas files, directories, network servers, messages, databases, or Web pages. Then, youmust decide what users and groups of users should have access to these protectedresources. You also need to decide what type of access to these resources should bepermitted. Finally, you must apply the proper security policy on these resources toensure that only the right users can access them.

The enforcement of the security policy is the job of the resource manager. Theresource manager calls the Tivoli Access Manager authorization service with thecredentials of the user making the request, the type of access desired, and theobject to be accessed. The credential provides detailed information, acquiredduring authentication, that describes the user, any group associations, and othersecurity-related identity attributes. Credentials can be used to perform a multitudeof services, such as authorization, auditing, and delegation.

The authorization service, also known as the authorization engine, uses thesecurity policy to determine whether the request should be allowed, denied, orconditionally allowed pending additional verification by the resource manager. Theresource manager takes the recommendation of the authorization service, performsany additional verification actions, and ultimately either denies the request, orpermits the request to be processed.

For example, suppose that Todd wants to access a particular Web page that islocated on a Web site protected by Tivoli Access Manager WebSEAL. WebSEAL is aresource manager that is responsible for managing and protecting Web-basedinformation and resources and must decide whether or not Todd can access thatpage. The resource manager obtains the credentials for Todd, and then asks theauthorization service whether Todd has read access to the Web page. Theauthorization service checks the security policy and determines that Todd shouldbe permitted access, so it recommends to the resource manager that the request begranted. The resource manager then directs Todd's request to the appropriateback-end Web server, which provides the Web page.

The security policy in Tivoli Access Manager is defined through the use of accesscontrol lists (ACLs), protected object policies (POPs), and authorization rules.

Authorization API standardAuthorization services are a critical part of the security architecture of anapplication. After a user passes the authentication process, authorization servicesproceed to enforce the business policy by determining what services andinformation the user can access.

For example, a user accessing a Web-based retirement fund could view personalaccount information after an authorization server verifies the identity, credentials,and privilege attributes of that user.

The standards-based authorization API (aznAPI) allows applications to call thecentralized authorization service, thus eliminating the necessity for developers towrite authorization code for each new application.


The authorization API allows businesses to standardize all applications on atrusted authorization framework. With the authorization API, businesses canprovide more control over access to resources on their networks.

Authorization: conceptual modelWhen servers enforce security in a domain, each client must provide proof of itsidentity. In turn, security policy determines whether that client is permitted toperform an operation on a requested resource. Access to every resource in adomain is controlled by a server. So the demands on the server for authenticationand authorization can provide comprehensive network security.

In security systems, authorization is distinct from authentication. Authorizationdetermines whether an authenticated client has the right to perform an operationon a specific resource in a domain. Authentication ensures that the individual iswho that individual claims to be.

In the Tivoli Access Manager authorization model, authorization policy isimplemented independently of the mechanism used for user authentication. Userscan authenticate their identity using either public/private key, secret key, orcustomer-defined mechanisms.

Part of the authentication process involves the creation of a credential thatdescribes the identity of the client. Authorization decisions made by anauthorization service are based on user credentials.

The resources in a domain receive a level of protection as dictated by the securitypolicy for the domain. The security policy defines the legitimate participants of thedomain. It also defines the degree of protection that is surrounding each resourcerequiring protection.

The authorization process, as shown in Figure 1 on page 7, includes the followingbasic components:

resource managerA resource manager responsible for implementing the requested operationwhen authorization is granted.

A component of the resource manager is a policy enforcer that directs therequest to the authorization service for processing.

authorization serviceAn authorization service that performs the decision-making action on therequest.


Traditional applications bundle the policy enforcer and resource manager into oneprocess. Examples of this structure include Tivoli Access Manager WebSEAL, TivoliAccess Manager for Operating Systems, and Tivoli Access Manager for BusinessIntegration.

The independent functionality of these authorization components allows flexibilityin the design of the security enforcement strategy.

For example, such independence allows the security administrator to control:v Where the processes are locatedv Who writes the code for the processesv How the processes perform their tasks

The benefits of a standard authorization serviceAuthorization in most systems, both existing and new, is tightly coupled toindividual applications. Companies typically build applications over time to servetheir business needs. Many of these applications require some specific form ofauthorization.

The result is often a wide variety of applications with differing authorizationimplementations. These proprietary authorization implementations require separateadministration, are difficult to integrate, and result in higher costs of ownership.

A distributed authorization service can provide these independent applicationswith a standard authorization decision-making mechanism. Benefits of such astandard authorization service include:v Reduced cost of developing and managing access to applicationsv Reduced total cost of ownership and management of separate authorization

systemsv Use the existing security infrastructurev Allow new businesses to open more securelyv Enable newer and different kinds of applicationsv Allow shorter development cyclesv Share information securely

Resource manager

Authenticatedclient

authorizationcheck

yes | no

request forresource

Authorizationservice

Policyenforcer

Resources

Applicationserver

Figure 1. General authorization model


Tivoli Access Manager authorization service overviewTivoli Access Manager can be integrated into existing and emerging infrastructuresto provide a secure, centralized policy management capability. The Tivoli AccessManager authorization service, together with resource managers, provides astandard authorization mechanism for business network systems, as shown inFigure 2:

Existing applications can take advantage of the authorization service. Authorizationpolicy is based on user or group roles and can be applied to network servers,individual transactions or database requests, specific Web-based information,management activities, and user-defined objects.

The authorization API allows existing applications to call the authorization servicewhich in turn makes decisions based on the corporate security policy. For moreinformation on authorization API, see “Tivoli Access Manager authorization API”on page 14.

The Tivoli Access Manager authorization service is also extensible and can beconfigured to call on other authorization services for additional processing usingthe external authorization service plug-in interface.

The authorization service provides the following benefits:v The service is application independent.v The service uses a standard authorization coding style that is language

independent (the authorization API).v The service is centrally managed and therefore easy to administer. The addition

of a new employee, for example, requires modifying the privilege database inone central location, rather than across multiple systems.

v The service addresses the application of security services in a heterogeneouscross-platform environment.

v The service integrates existing non-Tivoli Access Manager authorization systemsthrough an external authorization service capability.

v The service has a scalable and flexible architecture that can be easily integratedwith existing infrastructure.

Web PortalManager

Masterauthorization

database

Userregistry

Policy server

Authorizationserver

Replicaauthorization

database

Figure 2. Tivoli Access Manager server components


v The service enables multi-tiered authorization. A credentials packet can bepassed through the multiple layers of an application process or transaction.

v The service uses a common and effective auditing model.v The service is independent of any authentication mechanism.

Tivoli Access Manager authorization serviceThe Tivoli Access Manager authorization service is responsible for theauthorization decision-making process that helps to enforce a network securitypolicy. Authorization decisions made by the authorization service result in theapproval or denial of client requests to perform operations on protected resourcesin a domain.

ComponentsThe authorization service is made up of three basic components:v Master authorization policy databasev Policy serverv The authorization decision-making evaluator

Policy databaseThe policy database, also referred to as the master authorization policy databaseand the master authorization database, contains the security policy information forall resources in a domain. Each domain has its own policy database. The contentsof this database are manipulated using Web Portal Manager, the pdadmincommand-line interface, and the administration API.

Policy serverThe policy server maintains the policy databases, replicates this policy informationthroughout the domains, and updates the database replicas whenever a change ismade to the master.

The policy server also maintains location information about the other Tivoli AccessManager and non-Tivoli Access Manager resource managers operating in thedomain.

Authorization evaluatorThe authorization evaluator is the decision-making process that determines theability of the client to access a protected resource based on the security policy. Theevaluator makes its recommendation to the resource manager which, in turn,responds accordingly.

User registry replication parameters are configurable for each evaluator.

Figure 3 on page 10 illustrates the main components of the authorization service:


Authorization service interfacesThe authorization service has two interfaces where interaction takes place:

Management interfaceThe security administrator manages the security policy by using the WebPortal Manager or the pdadmin command-line interface to apply policyrules to resources in a domain. The security policy is managed in thepolicy database by the policy server.

This interface is complex and involves detailed knowledge of the objectspace, policies, and credentials.

Authorization APIThe authorization API passes requests for authorization decisions from theresource manager to the authorization evaluator which then passes back arecommendation whether the request must be granted or denied.

Replication for scalability and performanceAuthorization service components can be replicated to increase availability in aheavy-demand environment.

You can configure the master authorization policy database, containing policy rulesand credential information, to automatically replicate. Resource managers that callthe authorization service have two options for referencing this databaseinformation:v The application, when configured to work seamlessly with the authorization

evaluator, uses a local cache of the databaseThe database is replicated for each resource manager that uses the authorizationservice in local cache mode.

v The application uses a shared replica cached by the remote authorization servercomponentThe database is replicated for each instance of the authorization server. Manyapplications can access a single authorization server.

Authorization Service

PolicyServer

( )pdmgrdMaster

AuthorizationPolicy

AuthorizationEvaluator

AuthAPI

ResourceManager

Web PortalManager

ReplicaAuthorization

Policy

ManagementInterface

Figure 3. Authorization service components


Update notification from the policy server (whenever a change was made to themaster authorization policy database) triggers the caching process to update allreplicas, as shown in Figure 4:

Performance notesv You can update notifications directly from the policy server. You can also

configure the resource managers to verify the version of the masterauthorization policy database every few minutes to ensure that the updatenotification are not missed. Such a mechanism is called polling and is notenabled by default.If an update notification fails to reach a server, a log entry is created. In bothcases, a retry mechanism also ensures that the update happens in the future.

v The cached authorization policy information results in high system performance.For example, when WebSEAL does an authorization check, it checks the policyin its own cached version of the database. WebSEAL does not have to access thenetwork to obtain this information from the master database. The result is fastresponse times (performance) for authorization checks.

v Individual authorization results are not cached by the calling application server.

Implementing a network security policyThe security policy for a domain is determined by controlling user and groupparticipation in the domain and applying rules to resources requiring protection.These rules are defined through the use of access control lists (ACLs), protectedobject policies (POPs), and authorization rules. The authorization service enforcesthese policies by matching the credentials of a user with the permissions in thepolicy assigned to the requested resource. The resulting recommendation is passedto the resource manager, which completes the response to the original request.

Defining and applying security policyYou protect system resources by defining a security policy. This security policy iscreated by defining access control lists (ACLs), protected object policies (POPs),and authorization rules, and then applying these policies to the objectrepresentations of those resources in the object space. You can apply ACLs, POPs,


Policy


Policy


PolicyServer

(pdmgrd)Master

AuthorizationPolicy

Web PortalManager


AuthAPI

ResourceManager


Policy

Figure 4. Replicated authorization service components


and authorization rules to the same object. The pdadmin command-line interface,the Web Portal Manager, and the administration API are used to define this policy.

The authorization service performs authorization decisions based on the policiesapplied to these objects. When a requested operation on a protected object (alsoreferred to as a protected resource) is permitted, the resource manager responsiblefor the resource implements this operation.

One policy can dictate the protection parameters of many objects. Any change tothe security policy affects all objects to which the policy is attached.

Explicit and inherited policyA security policy can be explicitly applied or inherited. The Tivoli Access Managerprotected object space supports inheritance of ACLs, POPs, and authorizationrules. This factor is an important consideration for the security administrator whomanages the object space. The administrator needs to apply explicit policies only atpoints in the hierarchy where the rules must change, as shown in Figure 5:

Examples of policy types include:v Hardcoded rulesv External authorization capabilityv Special secure labelingv Access control lists (ACLs), protected object policies (POPs), and authorization

rules

Access control listsAn access control list (ACL) policy, or ACL policy, is the set of actions, controls, orpermissions that specifies the conditions necessary for a particular user or group toperform certain operations on that resource. ACL policy definitions are importantcomponents of the security policy established for a domain.

An ACL policy specifically determines what operations can be performed on aresource, and who can perform those operations. An ACL policy is made up of oneor more entries that include user and group designations and either their specificpermissions or rights.

Managementobjects

Webobjects

User-definedobjects

Explicit ruleInherited rule

Figure 5. Explicit and inherited policies


Protected object policiesProtected object policies (POPs) contain additional conditions that must be met inorder to be granted access. Unlike ACLs, which are dependent on what user orgroup is attempting the action, POPs affect all users and groups. POPs alsoindicate whether requests must be audited. It is the responsibility of Tivoli AccessManager and the resource manager to enforce the POP conditions.

Authorization rulesAuthorization rules are defined to specify further conditions that must be metbefore access to a resource is permitted. Rules allow you to make authorizationdecisions based on the context and the environment surrounding the request, aswell as who is attempting the access, and what type of action is being attempted.These conditions are evaluated as a Boolean expression to determine if the requestmust be allowed or denied.

The authorization process: step-by-stepFigure 6 illustrates the complete authorization process:

1. An authenticated client request for a resource is directed to the resourcemanager server and intercepted by the policy enforcer process. For example,the resource manager can be WebSEAL for Hypertext Transfer Protocol (HTTP),HTTPS access or another application.

2. The policy enforcer process uses the authorization API to call the authorizationservice for an authorization decision. For more information about theauthorization API, see “Tivoli Access Manager authorization API” on page 14.

3. The authorization service performs an authorization check on the resource. Seepage 37 for details on the algorithm used.

4. The decision to accept or deny the request is returned as a recommendation tothe resource manager (through the policy enforcer).

5. If the request is finally approved, the resource manager passes the request on tothe application responsible for the resource.

6. The client receives the results of the requested operation.

Client

AuthorizationService

Secure Domain

AuthorizationPolicy

Protected ObjectSpace

2. Request forAuthorization

(AuthAPI)

5. AuthorizedOperation

1. Request

6. Response

3. AuthorizationCheck

4. AuthorizationDecision(AuthAPI)

Resources

/

ResourceManager

PolicyEnforcer

Figure 6. The Tivoli Access Manager authorization process


Tivoli Access Manager authorization APIThe Tivoli Access Manager authorization application programming interface (API)allows Tivoli Access Manager applications and other applications to query theauthorization service to make authorization decisions.

The authorization API is the interface between the resource manager (requestingthe authorization check) and the authorization service itself. The authorization APIallows Tivoli Access Manager resource managers and other resource managers toask for an authorization decision, but shields the application from the complexitiesof the actual decision-making process.

The authorization API provides a standard programming model for codingauthorization requests and decisions. The authorization API lets you makestandardized calls to the centrally managed authorization service from any existingor newly developed application.

The authorization API can be used in one of the following modes:

Remote cache modeIn this mode, the API is initialized to call the (remote) authorization serverto perform authorization decisions on behalf of the application. Theauthorization server maintains its own cache of the replica authorizationpolicy database. This mode is best suited for handling authorizationrequests from application clients.

For more information about remote cache mode, see “Authorization API:remote cache mode” on page 15.

Local cache modeIn this mode, the API is initialized to download and maintain a localreplica of the authorization database for the application. Local cache modeprovides better performance because the application performs allauthorization decisions locally instead of across a network. However, theoverhead of database replication and the security implications of using thismode make it best suited for use by trusted application servers.

For more information about local cache mode, see “Authorization API:local cache mode” on page 16.

One of the primary values and benefits of the authorization API is its ability toshield the resource manager from the complexities of the authorization servicemechanism itself. Issues of management, storage, caching, replication, credentialformats, and authentication methods are all hidden behind the authorization API.

The authorization API also works independently from the underlying securityinfrastructure, the credential format, and the evaluating mechanism. Theauthorization API makes it possible to request an authorization check and get asimple yes or no recommendation in return. The details of the authorization checkmechanism are invisible to the user.

Using the authorization API: examplesApplications can use the authorization API to perform access control on specificand specialized processes.

Example 1A graphical interface can be designed to dynamically show task buttons asactive or inactive, according to the results of the authorization check.


Example 2Another use of the authorization API is demonstrated in Figure 7,illustrating a request for a Common Gateway Interface (CGI) transactionby a Web application.

The lowest level of authorization, as illustrated in Figure A of Figure 7, involves an“all-or-nothing” access control on the uniform resource locator (URL). Thiscoarse-grained level of authorization only determines if the client can run the CGIprogram. If access is allowed to the CGI application, no further control is availableto resources manipulated by the CGI application.

As illustrated in Figure B of Figure 7, access controls were set on resources that theCGI program manipulates. The Web application is configured to use theauthorization API. Now the CGI program can call the authorization service tomake authorization decisions on the resources it manipulates — based on theidentity of the requesting client.

Authorization API: remote cache modeIn remote cache mode, resource managers use the function calls provided by theauthorization API to communicate to the (remote) authorization server. Theauthorization server functions as the authorization decision-making evaluator andmaintains its own replica authorization policy database.

The authorization server makes the decision and returns a recommendation to theapplication through the API. The server can also write an audit record containingthe details of the authorization decision request.

There must be an authorization server running somewhere in a domain whenusing remote cache mode, as shown in Figure 8 on page 16. The authorizationserver can be located on the same machine as the application or on another

Third-PartyApplication

Client

WebApplication

ObjectsManipulated

by CGI



Client

WebApplication

ObjectsManipulated

by CGI


Figure A

Figure B

Fine-grainedAuthorized

AccessRequest

Response

Request

Response

Coarse-grainedAccess

API

Function Call

Figure 7. Example use of the authorization API


machine. You can also install the authorization server on more than one machine ina domain to allow for high availability. The authorization API transparentlyperforms failover when a particular authorization server fails.

Authorization API: local cache modeIn local cache mode, the API downloads and maintains a replica of theauthorization policy database on the local file system of the resource manager. Itperforms all authorization decisions in-memory, which results in higherperformance and better reliability.

The local replica is persistent across invocations of the application. When the APIstarts in replica mode, it checks for any updates to the master authorization policydatabase that might have occurred since the local replica was built.

AuthAPI


PolicyServer

(pdmgrd)Master

AuthorizationPolicy


AuthAPI



Policy

AuthenticatedClient

Resources

pdacld

Figure 8. Authorization API: remote cache mode


External authorization capabilityIn some situations, the standard Tivoli Access Manager policy implementations ofACLs, POPs, and authorization rules might not be able to express all theconditions required by the security policy of an organization. Tivoli AccessManager provides an optional external authorization capability to accommodateany additional authorization requirements.

The external authorization service allows you to impose additional authorizationcontrols and conditions that are dictated by a separate, external, authorizationservice module.

Extending the authorization serviceExternal authorization capability is automatically built into the Tivoli AccessManager authorization service. If you configure an external authorization service,the Tivoli Access Manager authorization service simply incorporates the accessdecision paths into its evaluation process.

Resource managers that use the authorization service, such as WebSEAL and anyapplication using the authorization API, benefit from the additional, but seamless,contribution of a configured external authorization service. Any addition to thesecurity policy through the use of an external authorization service is transparentto these applications and requires no change to the applications.

The external authorization service architecture allows the full integration of anexisting security service. An external authorization service preserves a the initial


PolicyServer

(pdmgrd)Master

AuthorizationPolicy


AuthAPI



Policy

AuthenticatedClient

Resources

Figure 9. Authorization API: local cache mode


investment that a company makes in security mechanisms by allowing existingservers to be incorporated into the Tivoli Access Manager authorizationdecision-making process.

Imposing conditions on resource requestsAn external authorization service can be used to impose more specific conditionsor system-specific side effects on a successful or unsuccessful access attempt.

Examples of such conditions include:v Causing an external auditing mechanism to record the successful or unsuccessful

access attemptv Actively monitoring the access attempt and causing an alert or alarm whenever

unacceptable behavior is detectedv Conducting billing or micro-payment transactionsv Imposing access quotas on a protected resource

The authorization evaluation processAn authorization decision that incorporates an external authorization server takesplace in the following manner:1. If a trigger condition is met during an access decision, the external

authorization services that were configured for that condition are each called inturn to evaluate their own external authorization constraints.Invocation of the external authorization service occurs regardless of whetherthe necessary permission is granted to the user by the Tivoli Access Managerauthorization service.

2. Each external authorization service returns a decision of permitted, denied, orindifferent.When indifferent is returned, the external authorization service hasdetermined that its functionality is not required for the decision process andthat it does not participate.

3. Each external authorization service decision is weighted according to the levelof importance that its decision carries in the process.The weighting of individual external authorization services is configured whenthe service plug-in is loaded.

4. All authorization decision results are summed and combined with the decisionmade by the Tivoli Access Manager authorization service. The resultingdecision is returned to the caller.

ExampleFigure 10 on page 19 illustrates an authorization decision involving an applicationserver and an external authorization service.


In this example, the purpose of the external authorization service is to impose aquota restriction on how often a photo-quality printer resource can be accessed.

The service implementation imposes a limit on the number of job submissions thatany one person can make to this printer in one week. An external authorizationservice trigger condition was attached to the photo printer resource so that theexternal authorization service is invoked anytime that the photo printer isaccessed.

The external authorization service was loaded with the default decision weightingof 101, which overrides any decision made by the Tivoli Access Managerauthorization service if required.1. The resource manager server receives a request from a client for access to an

online photo printing resource. The client is a member of the appropriate groupGraphicArtists and so is normally permitted to submit jobs to the printer.

2. The application server first consults the Tivoli Access Manager authorizationservice to determine whether the requesting user has permission to submit jobsto the printer.

3. The authorization service verifies the access permissions on the target requestedobject and compares the permissions against the capabilities of the requestinguser:group GraphicArtists rx

In the ACL on the printer resource, the x permission grants any user in theGraphicArtists group access to the resource. Therefore, the authorizationservice grants the user permission to submit the job.

4. The photo printer resource is being accessed and an external authorizationservice trigger condition was attached to this object. So a request is also madeto the external authorization service configured for that trigger condition.

Client


Third-PartyResource Manager

Secure Domain

AuthorizationPolicy

Protected ObjectSpace

2. Request forAuthorization

7. Denied Access

1. Request

8. Response:Denied

3. AuthorizationCheck

(allowed +100)

6. Combined AuthorizationDecision (denied -1)

Resources

/

ExternalAuthorization

Service

5. External AuthorizationResults (denied-101)

4. ExternalAuthorization

Check

Authzn API

Figure 10. External authorization service with an application server


The external authorization service receives all the Access Decision Information(ADI) that was passed in with the original access decision check by theresource manager server.

5. The external authorization service consults a record of previous accesses madeby this user. If the requesting user has not exceeded the quota for the week, itreturns an access decision of indifferent.The implication is that the external authorization service is indifferent to therequest and has no intention of participating in the access decision because itsconditions for denying access have not been met.However, if the user has exceeded the quota, then the external authorizationservice returns a decision of access denied.For this example, it is assumed that the requester has exceeded the quota andthat the external authorization service detects this problem and returns anaccess denied decision.

6. The Tivoli Access Manager authorization service receives the access deniedresult from the external authorization service. It then takes this decision andweights it with the default external authorization service weighting value of101.The results of the external authorization service decision, and the decisionmade by the Tivoli Access Manager authorization service, are combined. Theresult is access denied, because the result of the external authorization service(–101) outweighs that of the Tivoli Access Manager authorization service (100).

7. The resource manager server rejects the job submission to the photo printerresource.

8. The resource manager server returns a response to the caller to indicate that thejob was rejected.

Implementing an external authorization serviceTwo general steps are required to set up an external authorization service:1. Write an external resource manager service plug-in module with an

authorization interface that can be referenced during authorization decisions.2. Register the external authorization service with the resource manager so that

the resource manager can load the plug-in service at initialization time.

Registering the service sets a trigger condition for the invocation of the externalauthorization service. When the trigger condition is encountered during anauthorization check, the external authorization service interface is invoked to makean additional authorization decision.

Deployment strategiesTivoli Access Manager allows you to implement an external authorization servicein several ways:v Any number of external authorization services can be registered with resource

manager applications. Applications that can load external authorization servicesinclude the authorization server, other Tivoli Access Manager resource managers,and any other resource manager applications that you create.

v Remote-mode authorization API clients, which make requests to theauthorization server for authorization decisions, automatically use any externalauthorization service that is loaded by the authorization server.

v More than one external authorization service can be called for any single triggercondition. In this case, the results of each external authorization service is


weighted accordingly, and then the results are combined with the result of theTivoli Access Manager authorization service.

v Trigger conditions can be placed on objects, using a POP trigger, such that anyrequest to an object, regardless of the operation that is being requested, triggersa call to the external authorization services that are configured for the trigger.

v Trigger conditions can also be placed on the operations requested by a user. Forexample, an external authorization service can be triggered specifically when auser requests a Write operation to a protected resource, but not for any otheroperation. It is then possible to develop sets of operations for which one or moreexternal authorization services in combination are triggered according the set ofoperations requested.

v The external authorization services are implemented as dynamically loadablelibrary (dynamic link library (DLL)) modules. This feature greatly simplifies thetask of external authorization service development. There is no requirement tomake remote requests to the external authorization service and the overhead ofmaking the call is equivalent to the overhead of a function call.

v The combination of the authorization API and an external authorization serviceprovides a highly extensible and flexible solution for implementing a complexsecurity policy.


Chapter 2. Web Portal Manager

Tivoli Access Manager includes the following user interfaces that allow you tomanage domains, users and groups, permissions, policies, and other resources inyour enterprise:

pdadminpdadmin is a command-line interface that you can think about as thepdadmin shell.

The pdadmin command-line interface is installed as part of the TivoliAccess Manager runtime package. You can also automate certainmanagement tasks by writing scripts that use the pdadmin utility.

The IBM Tivoli Access Manager for e-business: Command Reference providesdetailed information about the pdadmin command-line interface, thecommands that you can run from this interface, and other utilities.

Web Portal Manager

Web Portal Manager is a management console that you can use to performtasks that are like the commands provided by the pdadmin commands.The Web Portal Manager is implemented as a plug-in to the IBMIntegrated Solutions Console. The Integrated Solutions Console is agraphical administration console that provides a framework foradministering multiple products. For example, your console enables you toadminister Tivoli Access Manager and WebSphere Application Server.

Web Portal Manager roles: Using Web Portal Management administratorroles, an enterprise can limit the Tivoli Access Manager administratoraccess to management functionality. Tivoli Access Manager 6.1.1administrators do not have to be WebSphere Application Serveradministrators. For example, one Tivoli Access Manager administrator canmanage policies and another administrator can manage WebSEALjunctions. The following list describes the capabilities of each Web PortalManagement role:

Role name: wpmpolicyadminwpmpolicyadmin is a Web Portal Manager policy administrator role.The following is a list of tasks that the wpmpolicyadmin roleperforms:v Object Space:

– Browse Object Space– Copy/Paste Object Space– Create Object– Import Object– Create Object Space

v Access Control List (ACL):– List ACLs– Create ACL– Import ACL– Export All ACLs– List Action Groups


– Create Action Groupv Protected Object Policy (POP):

– List POPs– Create POP– Import POP– Export All POPs

v Authorization (AuthzRules):– List AuthzRules– Create AuthzRule– Import AuthzRule– Export All AuthzRules

v Global Sign-On (GSO) Resources:– List GSOs– Create GSO– List GSO Groups– Create GSO Groups

v Secure Domain:– List Secure Domains– Create Secure Domain

Role name: wpmregistryadminwpmregistryadmin is a Web Portal Manager registry administratorrole. The following is a list of tasks that the wpmregistryadmin roleperforms:v User tasks:

– Search Users– Create User– Import User– Show Global User Policy– Change My Password

v Group tasks:– Search Groups– Create Group– Import Group

Role name: wpmwebsealadminwpmwebsealadmin is a Web Portal Manager WebSEAL administratorrole. The following is a list of tasks that the wpmwebsealadmin roleperforms:v List Junctionsv Create Junctionsv List Virtual Host Junctionsv Create Virtual Host Junctionsv Dynamic URL Files

Role name: wpmdelegateadminwpmdelegateadmin is a Web Portal Manager delegate administratorrole. The following is a list of tasks that the wpmdelegateadmin roleperforms:


v Manage Enterprise Domainsv Manage Rolesv Domain User Searchv Change My Password

Web Portal Manager is not installed as part of the Tivoli Access Managerruntime. To use Web Portal Manager, you must install it separately. TheIntegrated Solutions Console is automatically installed when you installWebSphere Application Server.

Note: For complete installation instructions, see the IBM Tivoli AccessManager for e-business: Installation Guide.

Although you can manage your enterprise using either interface, only a subset ofthe management tasks can be performed using Web Portal Manager. To comparethe mapping between the pdadmin utility and Web Portal Manager tasks, seeAppendix E, “pdadmin to Web Portal Manager equivalents,” on page 337.

Another difference between these interfaces is that when you use the pdadminutility, you can specify a file. When using Web Portal Manager, you cannot specifya file name. In some cases, however, you can copy and paste the contents of thefile.

This chapter contains the following sections:v “Types of administration”v “Delegate administration tasks”v “Web Portal Manager common tasks” on page 26v “Customizing the Web Portal Manager interface” on page 28v “Self-registration tasks” on page 28

Types of administrationTivoli Access Manager provides two types of administration:v Administrationv Delegate administration

You can use Web Portal Manager to perform both types of tasks. The administratoruses the same URL to connect to Web Portal Manager for both administration anddelegate administration.

Delegate administration tasksWeb Portal Manager delegate administration provides a Web-based interface thatincludes a set of delegated management services. The delegated managementservices enable a business to delegate user administration, group and roleadministration, security administration, and application access provisioning toparticipants (subdomains) in the business system. These subdomains can furtherdelegate management and administration to trusted subdomains under theircontrol, thus supporting multilevel delegation and management hierarchy based onroles.

The delegate administration supports the following operations:v Creation of multiple enterprise domains

Chapter 2. Web Portal Manager 25

v Assignment of users to be domain administratorsv Assignment of administrator types (such as: Tivoli Access Manager

Administrator, Domain Administrator, Senior Administrator, Administrator, andSupport Administrator) and enforcement of the administrative tasks that can beperformed with each administrator type

v Use of self-registration, meaning to become a registered Tivoli Access Manageruser without the involvement of an administrator, and self-care to reduce theadministration load.

Refer to Chapter 16, “Delegated administration,” on page 183 for a completedescription of Tivoli Access Manager delegate administration tasks.

Self-careWeb Portal Manager deployments can grow to support large number of users. Asthe number of users grows, so does the number of administrators required tomanage these users. Self-registration and self-care are features of the Web PortalManager that can be used to reduce the administration load.

Web Portal Manager supports self-care operations by allowing Tivoli AccessManager users to change their Tivoli Access Manager password through WebPortal Manager. Users can go to the Web Portal Manager delegate administrationpage and manage their passwords. After logging in, the user must go to theChange My Password task.

Self-registrationSelf-registration is the process by which a user can enter required data to become aregistered Tivoli Access Manager user, without the involvement of anadministrator.

Web Portal Manager includes a sample application that allows end users toperform self-registration. This sample is supported only on an LDAP registry, notDomino® or Active Directory.

Included with Web Portal Manager is sample code that implements aself-registration page. The sample code shows how to use the Tivoli AccessManager Java Administration APIs along with Java 2 Platform, Enterprise Edition(J2EE) servlets and Java Server Pages (JSPs) to implement self-registration. See“Self-registration tasks” on page 28.

Web Portal Manager common tasksThis chapter provides procedures for the more common Web Portal Manager tasks,such as:v “Starting Web Portal Manager”v “Logging in and signing off” on page 27v “Accessing online help” on page 27

Starting Web Portal ManagerBefore starting Web Portal Manager, ensure that the WebSphere Application Serveris running. While the WebSphere server is running, use one of the following Webaddresses to start Web Portal Manager for administration:v If you installed, configured, and enabled SSL or FIPS, type the following Web

address:


https://hostname:9043/ibm/console

where hostname is the machine where IBM HTTP server and WebSphereApplication Server are running, and 9043 is the secured port for the IntegratedSolutions Console.For example:https://testgroup.austin.ibm.com:9043/ibm/console

Note: For information about enabling FIPS in a WebSphere environment, see theWebSphere Application Server documentation.

v If you do not have SSL or FIPS installed, configured, and enabled, type thefollowing Web address:http://hostname:9060/ibm/console

where hostname is the machine where IBM HTTP server and WebSphereApplication Server are running, and 9060 is the non-secured port for theIntegrated Solutions Console.For example:http://testgroup.austin.ibm.com:9060/ibm/console

The Web Portal Manager delegate administration tasks are accessed from the sameWeb address as are the Web Portal Manager administration tasks. Users can go tothe Web Portal Manager delegate administration page and manage theirpasswords. After logging in, the user must select Delegate Administration >Change My Password.

Logging in and signing offTo log in to Web Portal Manager, complete the following steps:1. Launch the Integrated Solutions Console.2. Provide the appropriate user name, and click Log in.3. In the navigation panel, expand Tivoli Access Manager, and then expand Web

Portal Manager or Delegate Administration, depending on the tasks you needto perform.

4. In the navigation pane, click a task to display the Web Portal Manager Sign Onfields.

5. Provide Web Portal authentication, such as the following information, and thenclick Sign On:v Name of the domain in which you want to perform tasksv User namev Password associated with the user name

6. After the Tivoli Access Manager splash screen appears in the content pane,select and perform tasks, as needed.

Note: After a certain period of inactivity, the system might prompt you to login again.

7. Click Logout at the top right of the Integrated Solutions Console to terminatethe session and log out of the Integrated Solutions Console.

Accessing online helpInstructions for completing tasks using Web Portal Manager are documented in theonline help system. Refer to the help system when you enter information in fieldsor select or clear choices.


To access online help, complete the following steps:1. Use Web Portal Manager to log in to the domain.2. Select a task such as Group → Import Group.3. In the task title bar, click the question mark icon on the right side of the page.

A help window contains the online information for completing the task.4. Close the help window after you complete the task.

Customizing the Web Portal Manager interfaceWeb Portal Manager allows you to customize the interface. You can customize thebranding of Web Portal Manager by modifying the configuration to specify whichWeb page (HTML or JSP file) or image (GIF file) must be loaded when Web PortalManager starts.

Customizing the imagesCustomizing images in Web Portal Manager consists of placing new replacementimages where the default images are currently located. To customize the images forWeb Portal Manager, complete the following steps:1. Change the value of the following entries in the amconf.properties

configuration file to specify the new images to display:

loginGifShows the specified image on the login page. The default value isaccessmanager.gif.

splashGifShows the specified image on the welcome page, after the login page.The default value is accessmanager.gif.

2. Place the new images in the following directory for administration:

For Linux and UNIX operating systemswebsphere_install_dir/WebSphere/AppServer/systemApps/isclite.ear/iscwpm.war/images/en

For Windows operating systemswebsphere_install_dir\Program Files\IBM\WebSphere\AppServer\systemApps\isclite.ear\ iscwpm.war\images\en

where websphere_install_dir is the directory where WebSphere is installed.3. For locale-specific versions of these images, create a locale-specific subdirectory

under the /images directory and place the new images in this subdirectory.4. Restart the WebSphere server.

Self-registration tasksTivoli Access Manager provides a self-registration sample to demonstrate how itworks.

Note: This sample is supported only when your Tivoli Access Manager userregistry is an LDAP user registry. You cannot perform self-registration tasksfor an IBM Lotus® Domino or a Microsoft Active Directory user registry.

Performing self-registrationOne possible scenario for implementing self-registration is where a user opens aWeb browser to view a self-registration Web page. On this Web page, the user


enters specific identification information (either company-specific or user-specific)with a Tivoli Access Manager user ID and password. The identification informationprovided by the user is then validated and the user is created in the Tivoli AccessManager registry.

Because users do not typically have permission to create objects in Tivoli AccessManager, the self-registration sample requires the ID and password of anadministrator who has permission to create users. This login information is thenused to create users when somebody enters the required information about theregistration page.

The following information is requested the first time the self-registration sample isaccessed. This data is saved by the servlet in memory and then used to createusers who request to be registered.v Administrator namev Passwordv Registry container

The administrator name and password must be the name of an administrator whohas permission to create users in Tivoli Access Manager. The sec_masteradministrator has the proper access by default. The Registry Container field mustbe the base name in LDAP where user entries must go. This value is used toconstruct the distinguished name (DN) of self-registered users.

For example, enter o=ibm,c=us and the registered users are created in LDAP as,cn=FirstnameLastname,o=ibm,c=us. The user is not added to any groups. In a realapplication, the user would probably be added to some groups to have access tosome applications. After the administrator information is entered, this page is notshown again. If you access the sample, you are shown only the registration pagewhere you can enter the given name, family name, and a password.

The administrator login is saved in the servlet session. Any user who accesses theself-registration sample from the same browser can create a user in Tivoli AccessManager. You must restart the application server to clear the administrator logininformation.

For this sample, the ID and password are not saved in a secure manner. If you usethis sample as the basis for a production registration application, you mustconsider ways to secure the administrator login information.

Changing Java Server PagesThe provided sample application includes the following Java Server Pages (JSPs):

regAdmin.jspThe page that is displayed to gather login information for theadministrator.

regProp.jspThe page that is displayed to gather the given name, family name, andpassword of the user.

regControl.jspThe code that creates the user. This page receives and processes theregistration requests. This page could also be a servlet class.

The files are installed in the following directory:


For Linux and UNIX operating systemswebsphere_install_dir/WebSphere/AppServer/profile/profile_name/installedApps/cell_name/TAMWPM.ear/pdadmin.war/images/register.war/register

For Windows operating systemswebsphere_install_dirProgram Files\IBM\WebSphere\AppServer\profile\profile_name\ installedApps\cell_name\TAMWPM.ear\register.war\ register

where websphere_install_dir is the directory where WebSphere is installed,profile_name is the name of the application profile, and cell_name is the name of theWebSphere cell.

When the administrator login information is entered, a PDContext object is createdand stored in the user servlet session as shown in the following code sample:String adminid = request.getParameter("admin");String adminPassword = request.getParameter("password");String ldapSuffix = request.getParameter("suffix");...// Try a login

try {ctx = new PDContext(adminid,

adminPassword.toCharArray(),url);

// Save the PDcontext and the LDAP Suffixsession.setAttribute("regAdminCtx", ctx);session.setAttribute("ldapSuffix", ldapSuffix);

}catch(PDException e) {

// process exception...

}

After the user enters the new user information, the PDContext object is retrievedfrom the session and used to create the user as shown in the following codefragment:// Creating the Access Manager User

pwd = request.getParameter("password");ldapcn = request.getParameter("ldapcn");ldapsn = request.getParameter("ldapsn");ldapdn = "cn=" + ldapcn + ldapsn + "," + ldapSuffix;userid = ldapcn + ldapsn;desc = ldapcn + " " + ldapsn;ctx = (PDContext)session.getAttribute("regAdminCtx");

// Make sure the session has not timed outif ( ctx == null ) {

%><%@ include file="regAdmin.jsp" %

<% return;}

PDMessages messages = new PDMessages();try {

createUser(bundle, ctx, userid, pwd, desc, ldapcn,ldapsn, ldapdn, usergroups, acc_valid,pwd_valid, gso_user, no_pwd_pol,messages);

succmsg = userid +ResourceFile.getString(bundle,

"userRegisteredMsg");}


catch(PDException e) {// process exception...

}

The new user ID is the given name and family name concatenated together.


Chapter 3. Tivoli Access Manager administration

The administration of Tivoli Access Manager involves the following major tasks:1. Creating domains and subdomains for management purposes, as necessary.2. Install and configure resource managers. All the Tivoli Access Manager resource

managers, such as WebSEAL or Tivoli Access Manager for Operating Systems,and other components, such as plug-ins for Web Server, automatically create aprotected object space and create the required protected resources (also knownas protected objects) when they are configured.

3. Create additional object spaces, as needed, for management purposes.4. Define protected objects in the object space, as needed, to represent the

resources that are to be protected. For protected objects, you can define thefollowing characteristics:v Who is allowed access.v What type of access is permitted.v When that access is allowed.v What other conditions that must be met before permitting access.v Whether the access request is audited.

5. Define users and groups that require access to the protected resources.6. Implement your security policy by attaching an access control list (ACL) policy, a

protected object policy (POP), and an authorization rule to objects in theprotected object space.

DomainsA domain consists of all the resources that require protection along with theassociated security policy used to protect those resources. The resources that youcan protect depend on the resource managers that are installed. Depending on theresource managers that are installed, these resources can be any physical or logicalentity, including objects such as files, directories, Web pages, printer and networkservices, and message queues. Any security policy that is implemented in adomain affects only the objects in that domain. Users with authority to performtasks in one domain do not necessarily have the authority to perform those tasksin other domains.

Tivoli Access Manager creates a domain, referred to as the management domain, aspart of its initial configuration. The default name of this management domain isDefault, and by default it is located in a stand-alone naming context, a suffixcalled secAuthority=Default. This domain is used by Tivoli Access Manager tomanage the security policy of all domains and is available for managing otherprotected resources as well. The administrator can rename the managementdomain and change its location when the Policy Server is configured.

For small and moderately sized enterprises, one domain is typically sufficient. Ifonly one domain is needed, no explicit action needs to be taken.

In large enterprises, however, you might want to define two or more domains.Each domain is given a name and is established with a unique set of physical andlogical resources. The security administrator can define the resources in a domainbased on geography, business unit, or major organizational division within the


enterprise. The security policy defined in the domain affects only the resources inthat domain, which allows data to be partitioned and managed independently.

A multiple domain environment can be invaluable when there is a business needto keep a physical separation between different sets of data. The following otherbenefits are associated with using multiple domains:

Increased securitySecurity policy data for each domain is mutually exclusive. Users, groups,and resources that are defined within a domain cannot be associated withanother domain. For example, suppose that a user named John Doe isidentified as JohnDoe in the Sales domain and as JDoe in the Advertisingdomain. Although the same person, each user ID is unique for eachdomain. Therefore resources available to user JohnDoe can be grantedaccess only by the unique identity by which the user is defined in thatdomain (Sales) or by groups that are defined in the Sales domain thatJohnDoe is a member of. Likewise, user JDoe, even though it is the sameperson, can be granted access only by the unique identity by which theuser is defined in the Advertising domain.

Simplified administrationYou can assign independent administrators to handle policy managementtasks for each domain. For example, assume that you are an IT specialistfor a large corporation, assigned to deploy Tivoli Access Manager from asingle data center. You could create a separate domain (with a uniquepolicy database and an administrator) for each organization, division, orgeographic area in your company. As users, groups, or resources change,the assigned administrator is responsible for updating the security policyfor that particular domain. This domain administrator can also delegateadministration tasks to others within that specific domain.

An administrator assigned to a specific domain has authority only within thatdomain. However, by default, an administrator can view users and groups definedin the user registry that are not necessarily Tivoli Access Manager users or groups.This feature is beneficial if, for example, an administrator wants to import a useror group from a different domain. Conversely, if you are the administrator of themanagement domain and want to limit the registry data that a domainadministrator can access, you can add the allowed-registry-substrings stanzaentry to the [domains] stanza in the ivmgrd.conf configuration file for the policyserver.

For more information about managing domains, see Chapter 5, “Managingdomains,” on page 61.

Protected object spaceTivoli Access Manager represents resources within a domain using a virtualrepresentation called the protected object space. The protected object space is thelogical and hierarchical portrayal of resources belonging to a domain.

The structure of the protected object space consists of two types of objects:

Resource objectsResource objects are the logical representation of actual physical resources,such as files, services, Web pages, message queues, and so on, in a domain.


Container objectsContainer objects are structural components that allow you to groupresource objects hierarchically into distinct functional regions.

Security policy can be applied to both types of objects. Figure 11 shows a logicalrepresentation of a protected object space with multiple container and resourceobjects. This illustration shows container objects as white boxes and resourceobjects as gray boxes.

The structural top of the protected object space is the root container object. Below theroot container object are one or more container objects. Each container objectrepresents an object space that consists of a related set of resources. Theseresources can be resource objects or container objects.

The installation of Tivoli Access Manager creates the /Management object space. Thisobject space consists of the objects that are used to manage Tivoli Access Manageritself. Under the /Management object space, the installation creates the followingcontainer objects:v /Usersv /Groupsv /POPv /Actionv /ACLv /GSOv /Serverv /Configv /Replica

Figure 12 on page 36 shows the complete /Management object space that is createdduring the installation of Tivoli Access Manager.

Container objects

Resource objects

Figure 11. Tivoli Access Manager protected object space

Chapter 3. Tivoli Access Manager administration 35

Each resource manager that protects a related set of resources creates its own objectspace. For instance, the installation of the WebSEAL component creates the/WebSEAL object space, and Tivoli Access Manager for Operating Systems createsthe /OSSEAL object space.

Users and groupsTivoli Access Manager maintains information about Tivoli Access Manager usersand groups in the user registry. In you have a user registry that maintains usersand groups for another application, you can import this user registry informationinto Tivoli Access Manager. If a required user or group was not in the user registrybefore it was imported into Tivoli Access Manager or a new user or group needs tobe added to the Tivoli Access Manager user registry, you can create it using TivoliAccess Manager.

Tivoli Access Manager supports two types of group definitions. The most commontype of group maintains the group membership as an explicit list of members(users). This type of group is sometimes referred to as a static group, because themembership is listed and maintained.

For Active Directory and LDAP registry users, Tivoli Access Manager also supportsthe use of dynamic groups. Dynamic groups are groups whose members areautomatically resolved when the group is accessed. This resolution is based on theresults of a defined search filter. For example, you create a dynamic group formembers of department XYZ. If you import a new user whose data matches anentry in the search filter, the user is automatically added to the group. If anexisting employee switches department, the user is automatically removed fromthe group. Manual intervention is not required.

The creation and management of a dynamic group can be complex and is specificto the vendor implementation, because it requires a search-like filter to be specifiedand used for group membership resolution. Because of these variables, dynamicgroups cannot be created or maintained using Tivoli Access Manager utilities oruser interfaces. The vendor-specific tools must be used to create and maintaindynamic groups. Tivoli Access Manager, however, can import and use thesedynamic groups after they are created.

Tivoli Access Manager supports different types of users. When a domain is created,a special user known as the domain administrator is created. For the managementdomain, the domain administrator is sec_master. The sec_master user and

Server ReplicaGSO Config

ActionUsers Groups POP ACL

Management

/ (root)

Figure 12. Regions of the Tivoli Access Manager protected object space


associated password are created during the configuration of the Tivoli AccessManager policy server. For other domains, the user ID and password of thedomain administrator are established when the domain is created. The domainadministrator has nearly complete control of the domain. Think of the domainadministrator as the Tivoli Access Manager equivalent to the Linux or UNIX rootaccount or the Microsoft Windows Administrator user.

The domain administrator is added as a member of the Tivoli Access Manageriv-admin group within the domain. The iv-admin group represents those userswith domain administration privileges. When adding users to the iv-admin group,ensure that you do not compromise the security of your domain.

Security policyAccess to objects in a domain is controlled by attaching security policy to objects inthe protected object space. After attaching a security policy to an object, anychange to the security policy is reflected immediately throughout the domain. Eachsecurity policy can be defined using a combination of the following controls:

Access control list policiesAn access control list (ACL) policy specifies what set of predefined actionsthat a set of users and groups can perform on an object. For example, aspecific set of groups or users can be granted read access to an object.

Protected object policiesA protected object policy (POP) specifies access conditions that areassociated with an object. A POP affects all users and groups. For example,a time-of-day restriction can be placed on an object that excludes all usersand groups from accessing that object during the specified time.

Authorization rulesAn authorization rule specifies a complex condition that is evaluated todetermine whether access is permitted. The data used to make thisdecision can be based on the context of the request, the currentenvironment, or other external factors. For example, a request to modify anobject more than five times in an eight-hour period could be denied.

Security policy can be explicitly applied to an object or can be inherited by anobject that is above it in the hierarchy. Apply an explicit security policy in theprotected object space only at those points in the hierarchy where the securitypolicy must change.

Security policy is implemented by strategically attaching ACL policies, POPs, andauthorization rules to objects that require protection. The Tivoli Access Managerauthorization service decides whether to permit or deny access to objects based onthe credentials of the user that is making the request and the specific permissionsand conditions that are set in the ACL policies, POPs, and authorization rules.

The authorization service uses the following algorithm to process the securitypolicy that is attached to a protected object:1. Check permissions in the ACL policy to determine whether the user can

override the attached POP or authorization rule. See “Evaluating ACL policies”on page 39 for information about the evaluation process.

2. When there is an authorization rule attached and the user cannot override it,gather the Access Decision Information (ADI).

3. When there is a POP attached, check the Internet Protocol (IP) endpointauthentication method policy.


4. When there is a POP attached, check the time-of-day policy.5. When there is a POP attached, check the audit-level policy, and audit the access

decision.6. When an authorization rule is attached and the user cannot override the

authorization rule, check the authorization rule policy.7. When an external authorization service (EAS) operation or a POP trigger

applies to this access decision, invoke the EAS.

If any of the ACL policy, POP, or authorization rule evaluations fail, the accessrequest is denied. The EAS can override this decision on its own, if it wasdesigned to do.

ACL policiesThe policy that defines who has access to an object, and what operations can beperformed on the object, is known as the ACL policy. Each ACL policy has aunique name and can be applied to multiple objects within a domain.

An ACL policy consists of one or more of the following entries descriptions:v The names of users and groups whose access to the object is explicitly controlledv The specific operations permitted to each user, group, or rolev The specific operations permitted to the special any-other and unauthenticated

user categories

Using ACL policies with the authorization serviceTivoli Access Manager relies on ACL policies to specify the conditions necessaryfor a particular user to perform an operation on a protected object. When an ACLpolicy is attached to an object, entries in the ACL specify what operations areallowed on this object and who can perform those operations.

Tivoli Access Manager uses a default set of actions that cover a wide range ofoperations. Actions, or permissions, are represented by single alphabetic ASCIIcharacters (a-z, A-Z). Each permission is displayed (by the pdadmin utility or WebPortal Manager) with a label describing the operation it governs. In addition, theWeb Portal Manager groups the ACL policies according to their use in a particularpart of the object space (such as WebSEAL) or their use across the entire objectspace (Base, Generic).

A resource manager software typically contains one or more operations that areperformed on protected resources. Tivoli Access Manager requires that resourcemanagers make calls to the authorization service before the requested operation isallowed to progress. This call is made through the authorization applicationprogramming interface (authorization API) for both Tivoli Access Manager servicesand other applications.

The authorization service uses the information contained in the ACL entry to makea simple “yes” or “no” response to the following question:

Does this user or group have the appropriate permission to perform therequested operation on the requested object? For example, does the user havethe view (r) permission to view an object?


The authorization service has no knowledge about the operation requiring the read(r) permission. It is merely noting the presence or absence of the r action bit in theACL entry of the requesting user or group.

The authorization service is independent of the operations being requested. Thisindependence is why it is easy to extend the benefits of the authorization service toother applications.

Evaluating ACL policiesTivoli Access Manager follows a specific evaluation process to determine thepermissions granted to a particular user by an ACL policy. When you understandthis process, you can determine how best to keep unwanted users from gainingaccess to resources.

Evaluating authenticated requestsTivoli Access Manager evaluates an authenticated user request in the followingorder:1. Match the user ID with the user ACL entries. The permissions granted are the

permissions in the matching entry.Successful match

Evaluation stops here.Unsuccessful match

Continue to the next step.2. Determine the groups to which the user belongs and match group ID with the

group ACL entries. If more than one group entry is matched, the resultingpermissions are a logical “or” operation (most permissive) of the permissionsgranted by each matching entry.Successful match

Evaluation stops here.Unsuccessful match

Continue to the next step.3. Grant the permissions of the any-other entry, if it exists.

Successful matchEvaluation stops here.

Unsuccessful matchContinue to the next step.

4. An implicit any-other entity exists when there is no any-other ACL entry. Thisimplicit entry grants no permissions.Successful match

No permissions granted. End of evaluation process.

Evaluating unauthenticated requestsTivoli Access Manager evaluates an unauthenticated user by granting thepermissions from the unauthenticated ACL entry.

The unauthenticated entry is a mask (a bit-wise “and” operation) against theany-other entry when permissions are determined. A permission forunauthenticated is granted only if the permission also appears in the any-otherentry.

Because unauthenticated depends on any-other, it makes little sense for an ACLentry to contain unauthenticated without any-other. If an ACL entry containsunauthenticated without any-other, the default response is to deny permissions tounauthenticated.


Protected object policiesA protected object policy (POP) specifies security policy that applies to an objectregardless of what user or what operation is being performed. Each POP has aunique name and can be applied to multiple objects within a domain.

The purpose of a POP is to impose access conditions on an object based on thetime of the access and to indicate whether the access request must be audited.Specifically, the conditions you can apply are:v POP attributes, such as warning mode, audit level, and time-of-day.

More details about these attributes are in “Configuring POP attributes” on page111.

v Authentication strength POP (step-up).More details about this policy are in “Step-up authentication” on page 114.

v Quality of Protection POP.More details about this policy are in “Setting a Quality of Protection level” onpage 114.

v Network-based authentication POP.More details about this policy are in “Network-based authorization policy” onpage 110.

Authorization rulesAn authorization rule policy specifies security policy that applies to an objectbased on various conditions, such as context and environment. Each authorizationrule policy has a unique name and can be applied to multiple objects within adomain.

Like ACL policies and POPs, authorization rules are defined to specify conditionsthat must be met before access to a protected object is permitted. An authorizationrule is created using a number of conditions that are based on data supplied to theauthorization engine within the user credential, from the resource managerapplication or from the encompassing business environment. These conditions areevaluated as a Boolean expression to determine if access to the object must begranted or denied.

The language of an authorization rule allows you to work with complex,structured data. You can examine values in the rule data and make informedaccess decisions. The data used in an access decision can be defined staticallywithin the system or defined during a business process. Rules give you theflexibility of the policy defined by an external authorization service withoutrequiring that you develop and build the logic of an external authorization serviceinto a shared library plug-in.

How authorization rules differACL policies take a given predefined set of operations and control which users andgroups have permission to perform those operations on a protected object. Forexample, the ability of a user to read data associated with an object is eithergranted or denied by an ACL policy. POPs apply to all users and groups andcontrol conditions that are specific to a particular protected object. For example,time-of-day access excludes all users and groups from accessing an object outsideof the times set in the time-of-day policy.


Rules allow you to make decisions based on the attributes of a person or objectand the context and environment surrounding the access decision. For example,you can use a rule to implement a time-of-day policy that depends on the user orgroup. You also can use an authentication rule to extend the controls that areprovided by the ACL policies by implementing a more advanced policy, such asone based on quotas. An ACL policy can grant a group permission to write to aresource. A rule can go a step further by allowing you to determine if a group hasexceeded a specific quota for a given week before permitting that group to write toa resource.

When to use authorization rulesIn the Tivoli Access Manager authorization process, the entire security policy (ACLpolicies, POPs, and authorization rules) must permit access to the protected objectbefore access is granted. Authorization rules provide the flexibility needed toextend an ACL policy or POP by tailoring security policy to your needs.

Authorization rules can be used to extend the policy implemented by other TivoliAccess Manager policy types. However, these are not simply extensions of theexisting policy types. An authorization rule is a policy type that is rich enough infunctionality to replace the ACL policy and POP. However, using ACL policies andPOPs generally provides better performance. Therefore, use a rule to complementthese policies instead of replacing them.

Guidelines for a secure object spaceThe following guidelines are applicable for a secure object space:v Set high-level security policy on container objects at the top of the object space.

Set exceptions to this policy with explicit ACL policies, POPs, and authorizationrules on objects that are lower in the hierarchy.

v Arrange your protected object space so that most objects are protected byinherited, rather than explicit, ACL policies, POPs, and authorization rules.Reduce the risk of an error that could compromise your network by simplifyingthe maintenance of your tree. Inherited security policy lowers maintenancebecause it reduces the number of ACL policies, POPs, and authorization rulesthat you must maintain.

v Position new objects in the tree where they inherit the appropriate permissions.Arrange your object tree into a set of subtrees, where each subtree is governedby a specific access policy. You determine the access policy for an entire subtreeby setting explicit ACL policies, POPs, and authorization rules at the root of thesubtree.

v Create a core set of ACL policies, POPs, and authorization rules, and reuse thesepolicies wherever necessary.ACL policies, POPs, and authorization rule policies are a single-sourcedefinition. So any modification to the policy impacts all objects associated withthe ACL policy, POP, or authorization rule.

v Control user access through the use of groups.It is possible for an ACL policy to consist of only group entries. Individual userentries are not required in the ACL policy when the users can be categorizedinto groups instead. Authorization rules can also be written to consider anygroup memberships of an individual rather than the individual specifically. Thisfeature can reduce the complexity of the rule logic considerably.Access to an object by individual users can be efficiently controlled by addingusers to or removing users from these groups.


Chapter 4. Default security policy

Tivoli Access Manager establishes a default security policy to protect all objects ina domain. A set of administrative users and groups is established and granted apredefined set of permissions. The default security policy is described in thischapter.

Default administration users and groupsAt installation, Tivoli Access Manager provides several important administrationgroups. By default, these users and groups are given special permissions to controland manage all operations in a domain. This default security policy is defined bythe access control lists (ACLs) created during configuration.

The following sections detail the specific roles assigned to each of these users andgroups at installation time, and explain how to create administration users.

iv-admin groupThis group represents the administrator group. All members of this group areconsidered administrators of the domain by the default policy.

You can easily place users into an administration role by adding them to theiv-admin group. The danger with this procedure is that as soon as a user becomesa member of this group (with the default ACLs), that user has full rights toperform administration operations on any object in the protected object space.

When the policy server is configured, the administrator (sec_master) user iscreated and added to the iv-admin group. It is the combination of groupmemberships that grants sec_master complete rights for all operations within themanagement domain but only within the default policy. The sec_master user doesnot have rights to new groups created outside of the default policy unless it isadded as a user or a member of a group.

sec_master userThe sec_master user is created when Tivoli Access Manager is initially installedand configured. The default policy makes the sec_master user a member of theiv-admin group, permitting it to perform all actions within Tivoli Access Manager.Think of this account as the equivalent of the Linux or UNIX root account, or amember of the Microsoft Windows Administrator group.

ivmgrd-servers groupThe ivmgrd-servers group contains the policy servers and the policy proxy servers.By default, members of this group are authorized to delegate requests to otherTivoli Access Manager servers on behalf of the requestor.

Administration usersYou can create administration accounts with varying degrees of responsibility.Responsibility is delegated to administrators through strategically placedadministration ACLs.

The following list illustrates possible administration roles:


Security policy administratorSecurity policy administrators are responsible for defining and organizingsecurity policy in a domain. The administrator needs to be able to create,modify, and delete security policy. To perform these tasks, theseadministrators need the following permissions on the /Management/ACL,/Management/POP, and /Management/Rule resources:v Traverse (T)v Browse (b)v View (v)v Modify (m)v Delete (d)

These administrators need the following permissions to navigate theirsubtree of protected resources:v Traverse (T)v Browse (b)v View (v)

These administrators need the following permission to ability to attach anddetach security policy to the same subtree:v Attach (a)

These administrators must have the following permissions so as not to beaffected by security policies that apply to all users for the same subtree.v Bypass POP (B)v Bypass rule (R)

Protected resource administratorProtected resource administrators are responsible for adding and removinguser access to one or more protected resources. These tasks include:v Adding users to and removing users from groups that are defined in the

security policyv Adding permissions to and removing permissions from resources

These administrators need the following permission on the/Management/Groups protected resource or on the individual groups that aredefined in the /Management/Groups subtree:v Traverse (T)v Browse (b)v View (v)v Add (A)

Deployment administratorDeployment administrators are responsible for installation andconfiguration of the resource managers in the domain.

These administrators need the following permissions on the/Management/Server protected resource:v Traverse (T)v Browse (b)v View (v)v Modify (m)v Delete (d)

These permissions give the ability to configure resource managers into andout of the domain as well as update their configuration.


Defining and applying security policySecurity administrators protect system resources by defining a security policy. Asecurity policy consists of the access control list (ACL) policies, protected objectpolicies (POPs), and authorization rules that can be applied to the objectrepresentations of the system resources to be protected in the object space. You canapply ACL policies, POPs, and authorization rules to the same object.

The authorization service performs authorization decisions based on the policiesapplied to these objects. When a requested operation on a protected object ispermitted, the resource manager responsible for the resource implements thisoperation.

One policy can dictate the protection parameters of many objects. Any change toan ACL policy, POP, or authorization rule affects all objects to which the policy isattached.

ACL policiesAn ACL policy is the set of controls (permissions) that specifies the conditionsnecessary to perform certain operations on that resource. ACL policies areimportant components of the security policy that is established for the domain.ACL policies, like all policies, are used to stamp the set of security standards for anorganization on the resources that are represented in their protected object spaces.

An ACL policy provides the following controls:v What operations can be performed on an object or resourcev Who can perform an operation

An ACL policy is made up of one or more entries that include user and groupdesignations and their specific permissions.

Protected object policiesACL policies provide the authorization service with information that results in ayes or no answer on a request to access a protected object and perform someoperation on that object.

In contrast to ACL policies, protected object policies (POPs) contain additionalconditions on the request that are passed back to Tivoli Access Manager and theresource manager along with the yes ACL policy decision from the authorizationserver. It is the responsibility of Tivoli Access Manager and the resource managerto enforce the POP conditions.

The following table lists the available attributes for a POP that are provided byTivoli Access Manager.

user peter ---------T---rx

group engineering ---------T---rx

user michael ---------T---rx

unauthenticated ---------------

ACL

Figure 13. ACL policy

Chapter 4. Default security policy 45

Table 1. POP attributes that are enforced by Tivoli Access Manager

POP attribute Description

Name Name of the policy. This attribute relates to the pop-namevariable in the pop command documentation.

Description Descriptive text for the policy. This attribute appears inthe pop show command.

Warning mode Provides administrators a means to test ACLs, POPs, andauthorization rules. Warning mode provides a way totest security policy before they are made active.

Audit level Specifies the type of auditing: all, none, successful access,denied access, or errors. Audit level informs theauthorizations service that extra services are requiredwhen permitting access to the object.

Time-of-day access Day and time restrictions for successful access to theprotected object. Time-of-day places restrictions on theaccess to the object.

IP endpoint authorizationmethod policy

Specifies authorization requirements for access frommembers of external networks. IP endpointauthentication method policy places restrictions on theaccess to the object.

EAS trigger attributes Specifies an External Authorization Service (EAS) plug-inthat is invoked to make an authorization decision usingthe externalized policy logic of the customer.

Quality of Protection Specifies degree of data protection: none, integrity, orprivacy. Quality of Protections informs the authorizationsservice that extra services are required when permittingaccess to the object.

Although Tivoli Access Manager provides these POP attributes, it only enforces thefollowing attributes:v Namev Descriptionv Warning modev Audit levelv Time-of-day access

Each resource manager or plug-in can optionally enforce one or more of thefollowing attributes:v IP endpoint authorization method policyv EAS trigger attributesv Quality of Protection

The concept of inherited, or sparse ACLs as described in “Sparse security policymodel” on page 47 also applies to POPs in the same manner.

Authorization rulesAn authorization rule specifies the policy that applies to an object and that is basedon various conditions, such as context and environment. Each authorization rulehas a unique name and can be applied to multiple objects in a domain.

Like ACL policies and POPs, authorization rules are defined to specify conditionsthat must be met before access to a protected object is permitted. An authorizationrule is created using a number of Boolean conditions that are based on data that is


supplied to the authorization service within the user credential, from the resourcemanager, or from the encompassing business environment. The language of anauthorization rule allows customers to work with complex, structured data, byexamining the values in that data, and making informed access decisions. Thisinformation can be defined statically within the system or defined during abusiness process. Authorization rules can be used to implement extensibleattribute-based authorization policy using attributes within the businessenvironment or attributes from trusted external sources.

The authorization rule is stored as a text rule within a rule policy object and isattached to a protected object in the same way and with similar constraints as ACLpolicies and POPs.

Sparse security policy modelTo secure network resources in a protected object space, each object must beprotected by security policy.

You can assign security policy to an object in one of following ways:v Attach an explicit security policy on the object.v Allow the object to inherit its security policy from a preceding container object

in the hierarchy.

Adopting an inherited security scheme can greatly reduce the administration tasksfor a domain. This section discusses the concepts of inherited, or sparse securitypolicies.

Security policy inheritanceThe power of security policy inheritance is based on the following principle:

Any object without an explicitly attached security policy inherits the policy ofits nearest container object with an explicitly set security policy. Theinheritance chain is broken when an object has an explicitly attached securitypolicy.

Security policy inheritance simplifies the task of setting and maintaining accesscontrols on a large protected object space. In a typical object space, you need toattach only a few security policies at key locations to secure the entire object space.Therefore, it is called a sparse security policy model.

A typical object space begins with a single explicit security policy attached to theroot container object. The root ACL must always exist and can never be removed.Normally, the root ACL is an ACL with little restriction. All objects located in theobject space inherit this ACL.

When a region or subtree in the object space requires different access controlrestrictions, you attach an explicit security policy at the root of that subtree. Thisinterrupts the flow of inherited security policies from the primary object space rootto that subtree. A new chain of inheritance begins from this newly created explicitsecurity policy.


default-root ACL policyDuring the installation and initial configuration of Tivoli Access Manager, the ACLpolicy for the entire object space is created and explicitly set. This ACL policy isthe default-root ACL policy and includes the following users and permissions:group iv-admin TcmdbvaBRany-other Tunauthenticated T

Tivoli Access Manager checks inheritance beginning with the root of the protectedobject space. If you do not explicitly set an ACL policy on any other object in thetree, the entire tree inherits this root ACL policy.

There is always an explicit ACL policy set at the root of the protected object space.An administrator can replace this ACL policy with another ACL policy thatcontains different entries and permission settings, but the administrator cannotcompletely remove the root ACL policy.

Control permissionThe control (c) permission is a powerful permission that gives you ownership of anACL policy. Ownership allows you to modify entries in the ACL policy. Being ableto modify entries in the ACL policy means that you can create entries, deleteentries, grant permissions, and take away permissions.

The administrator who wants to delete a permission from an ACL policy musthave an entry in that ACL policy and must have the control permission set in thatentry.

The control permission allows you to grant administration powers to another user,such as the ability to attach or detach that ACL policy to objects. You must use thecontrol permission with great care, because of its powerful ownership properties.

Traverse permissionTivoli Access Manager access control depends on the following conditions:v The permission that controls the requested object must contain appropriate

access permissions for the requesting user.v The requested object must be accessible to the requesting user. Accessibility to

protected objects is controlled by the traverse (T) permission.

The traverse permission is applied only to container objects in the protected objectspace. The traverse permission specifies that a user or group that is identified inthe ACL entry has permission to pass through this container object to gain accessto a protected resource.

If there are no permissions defined for a user, that user cannot even traverse theroot container object. This user cannot gain access at all to the protected objectspace, regardless of any permissions that might be granted lower in the tree.

A protected object is accessible if the requester possesses the traverse permissionon each ACL attached to container objects above the requested resource on thepath towards root and including root.

Figure 14 on page 49 illustrates how the traverse permission works. Within thefictional ACME Corporation, there is an Engineering container object (directory),which contains a TechPubs directory. Kate (user kate) is a member of the Sales


department and requires traversing to the Engineering/TechPubs/ directory tree toreview a release note file (release_note). The administrator provides traverse forany-authenticated at the root. The administrator provides traverse permission forgroup sales on the Engineering directory. The TechPubs directory inherits the ACLfrom the Engineering directory. Although Kate has no other permissions in thesetwo directories, she can pass (traverse) through these directories to access therequired file. Because this file has read permission for Kate, she can view the file.

You can easily restrict access to the hierarchy below a given container objectwithout resetting individual permissions on these objects by deleting the traversepermission from the appropriate ACL policy. Deleting traverse permission on adirectory object protects all objects lower in the hierarchy, even if those objects thatcontain other less restrictive ACL policies.

For example, if sales group did not have the traverse permission on theEngineering directory, user kate could not access the release_note file eventhough the user has read permission for that file.

Resolving an access requestInheritance begins at the root of the protected object space and impacts all objectsin the object space until it reaches an object with an explicit ACL policy. At thispoint, a new chain of inheritance begins.

Objects below an explicitly set ACL policy inherit the new ACL policy. If youdelete an explicit ACL policy, permission for all objects reverts to the nearestcontainer object with an explicitly set ACL policy.

When a user tries to access a protected object (such as a document), Tivoli AccessManager checks whether that user has the permissions to access the object. TivoliAccess Manager checks each object along the object hierarchy for the properinherited or explicitly set permissions. A user is denied access to an object if anycontainer object in the hierarchy above the protected object does not include thetraverse permission for that user or is denied if the target object does not containsufficient permissions to perform the requested operation.

To succeed an access check, the requestor must have both of the followingpermissions:

EngineeringSales

TechPubs

release_note

group sales -------T---------

(ACL inherited)

user kate ---------------r-

ACME Corporation

/ (root) any-authenticated -------T---------

Figure 14. Traverse permission


v Permission to traverse the path to the requested object.v Appropriate permissions on the requested object.

For example, to determine whether a user can read the report.html resource in the/acme/engineering/project_Y/current/ object, Tivoli Access Manager performs thefollowing checks:1. Whether traverse permission is set on the root (/).2. Whether traverse permission is set on the acme, engineering, project_Y, and

current directories.3. Whether read permission is set on the report.htmlfile.

If any of these checks fail, the user is denied access.

Applying ACL policies to different object typesPermissions for various operations can be set in an ACL policy. Only a subset ofthese possible operations might be relevant for a specific object to which the ACLpolicy is attached.

The reason for this behavior is related to the following Tivoli Access Managerfeatures that are designed to make administration easier:v ACL policiesv ACL inheritance

ACL policies allow you to use the same set of permissions to multiple objects inthe protected object space. The ACL policy contains enough permissions to meetthe requirements of all objects to which the ACL applies. However, each individualobject might be affected by only a few of these permissions.

In an ACL inheritance model, any object without an explicitly attached ACL policyinherits the policy definitions from the nearest attached ACL policy to an objectabove it in the hierarchy.

In summary, an ACL policy has to describe the necessary permissions for all objecttypes to which it can apply, not just the object to which it is attached.

ACL policy inheritance exampleFigure 15 on page 51 illustrates the impact of a mixture of inherited and explicitACL policies in the fictional ACME corporate object space.

A corporate object space has a general security policy set at the root object. Root isfollowed by the /WebSEAL container object and individually controlled departmentalsubtrees.

In this example, the sales group is given ownership of its departmental subtree.The ACL policy on this subtree no longer acknowledges the unauthenticated orany-other entry types.

The ytd.html file has an attached ACL policy that grants read permission tomembers of the sales-vp group (who are also members of the sales group).

Note: This ACL policy scheme does not need to be changed when users are addedto or removed from the domain. Users can be added to or removed from the


existing groups.

Default ACL policiesYou can add entries for users, groups, any-other (any-authenticated), andunauthenticated to provide a broader range of control and better meet therequirements of your protected object space.

Users and groups with the control (c) permission own the ACL and have thepower to modify the ACL entries.

A detailed description of permissions can be found in “Default permissions in theprimary action group” on page 80.

The following default ACL policies are suggested starting points for securingmanagement operations in a domain:v default-rootv default-managementv default-configv default-gsov default-policyv default-domainv default-management-proxy

default-root ACL policyThe ACL policy for the entire object space is the default-root ACL policy. This ACLpolicy includes the following users and permissions:group iv-admin TcmdbvaBRany-other Tunauthenticated T

staff.html manager.htmltele.html president.html

WebSEAL server(www.acme.com/)

Departments

products.htmlclientA.html ytd.htmlsales.html

Sales

Note: group sales includes members of group sales-vp.

Personnel

Production Inventory

-------T------l---a--g--Tdm----lrx

---- --T-------r--

-abc --Tdm----lrx-

---- -------------

group iv-admingroup ivmgrd-serversgroup webseal-serversunauthenticatedany_authenticated

-abc---Tdm----lrx-------T------l---a--g--Tdm----lrx-------T------lrx

group iv-admingroup ivmgrd-serversgroup webseal-serversgroup sales

-------T------l---abc---Tdm----lrx

-a--g--Tdm----lrx

group iv-admingroup ivmgrd-serversgroup webseal-serversgroup sales-vp -------T-------r-

Figure 15. ACL inheritance example


The default-root ACL policy is a basic policy that enables everyone to traverse theobject space, but they cannot perform any other actions. Typically, you would notneed to change this setting.

One useful function of the default-root ACL policy is that it allows you to quicklydeny access to the entire object space for an individual user or group. Consider thefollowing entry in the default-root ACL policy:user john -----------------

The user john has no permissions. So this user cannot even traverse the rootcontainer object and cannot access the protected object space regardless of anypermissions that are granted lower in the tree.

default-management ACL policyThe default ACL policy of the /Management container object is thedefault-management ACL policy. At installation, this ACL policy is attached to the/Management container object in the object space. This ACL policy includes thefollowing users and permissions:group iv-admin TcmdbsvaBtNWARgroup ivmgrd-servers Tsany-other Tv

default-replica ACL policyThe default ACL policy for the /Management/Replica container object is thedefault-replica ACL policy. This ACL policy includes the following users andpermissions:group iv-admin TcbvaBRgroup ivmgrd-servers mgroup secmgrd-servers mdvgroup ivacld-servers mdv

default-config ACL policyThe default ACL policy for the /Management/Config container object is thedefault-config ACL policy. This ACL policy includes the following users andpermissions:Group iv-admin TcmdbsvaBRAny-other TvUnauthenticated Tv

default-gso ACL policyThe default ACL policy for the /Management/GSO container object is the default-gsoACL policy. This ACL policy includes the following users and permissions:group iv-admin TcmdbvaBNRany-other Tvunauthenticated Tv

default-policy ACL policyThe default ACL policy for the /Management/Policy container object is thedefault-policy ACL policy. This ACL policy includes the following users andpermissions:group iv-admin TcmdbvaBNRany-other Tvunauthenticated Tv


default-domain ACL policyThe default ACL policy for the /Management/Domain container object is thedefault-domain ACL policy. This ACL policy includes the following users andpermissions:group iv-admin TcmdbvaBNRgroup ivmgrd-servers v

default-proxy ACL policyThe default ACL policy for the /Management/Proxy container object is thedefault-proxy ACL policy. This ACL policy includes the following users andpermissions:group iv-admin Tcbvgroup ivmgrd-servers Tg

/Management permissionsThe /Management region of the protected object space contains multiple containerobjects.

The following security considerations apply for the /Management region of theprotected object space:v The /Management object begins the chain of permission inheritance for the entire

/Management region of the object space.v If you do not apply any other explicit permission, this object defines, through

inheritance, the security ACL policy for the entire /Management object space.v The traverse (T) permission is required for access to /Management.

The /Management region contains the following container objects that each requiresa specific set of permissions:v “/Management/ACL permissions”v “/Management/Action permissions” on page 54v “/Management/POP permissions” on page 55v “/Management/Server permissions” on page 55v “/Management/Config permissions” on page 55v “/Management/Policy permissions” on page 56v “/Management/Replica permissions” on page 56v “/Management/Users permissions” on page 56v “/Management/Groups permissions” on page 57v “/Management/GSO permissions” on page 58v “/Management/Rule permissions” on page 58v “/Management/Domain permissions” on page 59v “/Management/Proxy permissions” on page 59

/Management/ACL permissionsThis object allows administration users to perform high-level ACL managementtasks that can affect the security policy for the domain.

Permission Operation

d (delete) Delete an existing ACL policy.

m (modify) Create an ACL policy.



v (view) List and find view ACLs; show ACL details. This permission must be inan entry of an ACL attached to /Management/ACL object.

The acl find command shows the list of protected resources where this ACL isattached. You must have the view (v) permission on those protected resourcesbefore they can be shown.

You must create ACL administrator entries in the effective ACL policy for the/Management/ACL object. The ACL entry of an administrator might contain any ofthe permissions listed in the table. These permissions give the administratorpowers to create, view, and delete ACL policies.

An ACL administrator cannot modify an existing ACL unless there is an entry inthat ACL for the administrator containing the control (c) permission. Only theowner of an ACL can modify its entries.

The creator of a new ACL policy (m on /Management/ACL) becomes the first entry inthat ACL with the TcmdbsvaBIR permissions set by default.

For example, if sec_master is an administrator entry in the default-managementACL, with m permission, sec_master can create an ACL policy. User sec_masterbecomes the first entry in the new ACL, with TcmdbsvaBIR permissions.

Ownership of the default-management ACL itself is given to the iv-admin groupby default.

/Management/Action permissionsThis object allows administration users to manage custom actions and actiongroups. Action tasks and associated permissions include:


d (delete) Delete an existing action or action group.

m (modify) Create an action or action group.

To view an action or action group, no special permissions are required.

Resource managers can call the authorization service through the authorizationAPI. The following steps are required to integrate a resource manager with theauthorization service:1. Define the object space for the resource manager2. Define the action groups and actions for the resource manager3. Apply permissions on resources and objects that need protection

The administrator of a resource manager object space can use the pdadmin utilityto define new permissions and actions. Resource managers generally define theactions and action groups that are applicable to the resources that they areprotecting.

The administrator must have the m and d permissions on the Management/Actionobject to create and delete these new permissions or actions.


/Management/POP permissionsThis object allows administration users to manage protected object policies. Allpermissions must appear in entries for ACLs on /Management/POP. Action tasks andassociated permissions include:


d (delete) Delete a POP.

m (modify) Create POPs and modify POP attributes.

v (view) Find and list POPs and show POP details.

B (bypass POP) Override the POP on an object.

The pop find command shows the list of protected resources where this POP isattached. You must have the view (v) permission on those protected resourcesbefore they can be shown.

/Management/Server permissionsThe /Management/Server container object of the protected object space allowsadministrators to perform server tasks when the appropriate permissions are set.

Server management controls are used to determine whether a user has permissionto view configured resource managers, initiate a replication of one or moreresource managers, and to enable runtime tracing features on behalf of resourcemanagers.

Resource managers become available in the list of resource managers after they areconfigured into the domain. Resource managers are removed when they areunconfigured.

The viewable resource manager information allows other Tivoli Access Managerservers, particularly the policy server, to locate and communicate with thatresource manager.


s (server) Replicate the resource manager or the authorization database.

v (view) List registered servers and display server properties.

t (trace) Enable dynamic trace or statistics administration.

/Management/Config permissionsThe /Management/Config container object of the protected object space allowsadministrators to perform configuration tasks when the appropriate permissionsare set.

Configuration management controls are used to determine whether a user haspermission to configure, unconfigure, or update the configuration of a resourcemanager.

A server definition is created for a particular resource manager or the authorizationserver as part of the configuration process. The definition for a server is deletedwhen the server is unconfigured.


Server definitions contain information that allows other Tivoli Access Managerservers, particularly the policy server, to locate and communicate with thatresource manager.


m (modify) Configure a resource manager into a domain or update theconfiguration of a resource manager.

d (delete) Unconfigure a resource manager from a domain.

/Management/Policy permissionsThe /Management/Policy container object of the protected object space allowsadministrators to authorize the policy get and policy set commands when theappropriate permissions are set.


v (view) Required for policy get commands.

m (modify) Required for policy set commands.

/Management/Replica permissionsThe /Management/Replica container object of the protected object space controls thereplication of the master policy database. High-level controls on this object affectthe operation of the policy server and the resource managers in the domain.

Replica management controls are used to determine which resource managers areallowed to download the master policy database to their local file system.


v (view) Read the master policy database.

All Tivoli Access Manager servers that maintain a local replica of the policydatabase, which includes all resource managers and the authorization servers, mustbe granted view (v) permission on the /Management/Replica object. The replicationprocess requires that these processes be allowed to view and access entries out ofthe master policy database.

The Tivoli Access Manager installation automatically grants read permission to anyserver requiring access to the master policy database. When a resource manager isconfigured into the domain, it is automatically added as a member to theivacld-servers group. This group, by default, is given permission to download themaster policy database.

/Management/Users permissionsThis object allows administration users to manage user accounts. Action tasks andassociated permissions include:


d (delete) Delete a user account.

m (modify) Modify the details of a user account.

N (create) Create a user and optionally assign that user to one or more groups.Import group data from the user registry.



v (view) List user accounts and show details for a user account.

W (password) Reset and validate a user password.

The password (W) permission allows password resets and is appropriate to give tohelp desk administrators so that they can assist users who have forgotten theirpasswords. This permission allows an administrator to reset the password andthen to use the user modify password-valid command to set a value of no. Thisaction allows the user to log on and then forces the user to immediately apply anew password. Setting user modify password-valid to no for a user does notindicate if the password is not valid due to the maximum password age policy,which is a global setting. The policy set max-password-age command sets themaximum time before a password expires.

The ability for an administrator to manage all user accounts is controlled bypermissions on the /Management/Users object. For example, if an administrator hasview (v) permission on the /Management/Users object, that administrator can viewinformation about all users.

To limit the scope of administrator control to a specific group, remove theadministrator permissions from the /Management/Users object and applypermissions to the /Management/Groups object that is associated with the group tobe managed. For example, if an administrator is given view (v) permission on the/Management/Groups/Accounting object, that administrator can only viewinformation about users in the Accounting group.

If an administrator has view (v) permission to any group that the user is a memberof, the administrator can view the information for that user. Adding the view (v)permission to the /Management/Groups object itself allows an administrator to viewinformation about any user who is a member of any group.

Access granted by the /Management/Users object overrides any access restrictionsimposed by delegated administration policy ACLs under /Management/Groups/group_name. For information about delegated administration, see Chapter 16,“Delegated administration,” on page 183.

/Management/Groups permissionsThis object allows administration users to manage groups and group membership.

Permission Description

d (delete) Delete a group.

m (modify) Modify group descriptions. Remove one or more user members of agroup.

N (create) Create a group. Import group data from the user registry.

v (view) List groups and show group details.

A (add) Add one or more users to a group.

The add (A) permission is required on your entry in the ACL on a group to allowyou to add existing users to your group. Use the user create command, whichrequires the N permission, to create new users and optionally place them in one ormore existing groups.


The capability of adding existing users to your group is powerful because theowner of a group has control over all user members of the group. If you, as theowner of the group, also have the delete (d) permission, you can delete this userfrom the entire domain.

The ability for an administrator to manage all groups is controlled by permissionson the /Management/Groups object. For example, if an administrator has delete (d)permission on the /Management/Groups object, that administrator can delete anygroup.

To limit the scope of administrator control to a specific group, apply permissions tothe object that is associated with the group. For example, if an administrator isgiven delete (d) permission on the /Management/Groups/Travel/Europe object, thatadministrator can delete any group within that object.

Permissions on /Management/Groups objects affect the ability of an administrator tomanage users who are part of those groups. Giving an administrator delete (d)permission on a group allows that administrator to delete a user who is a memberof the group. If an administrator has view (v) permission on a group, thatadministrator can view information about the users that are part of those groups.

/Management/GSO permissionsThe /Management/GSO container object of the protected object space allowsadministrators to perform Global Sign-On (GSO) tasks when the appropriatepermissions are set.


N (create) Create a resource, resource group, or resource credential. Creating aresource, resource group, or resource credential also require the m(modify) permission.

d (delete) Delete a resource, resource group, or resource credential. Deleting aresource, resource group, or resource credential also require the m(modify) permission.

m (modify) Modify a resource group or resource credential.

v (view) List or show resources, resource groups, and resource credentials.

/Management/Rule permissionsThis object allows administration users to manage authorization rule policies. Allpermissions must appear in entries for ACLs on /Management/Rule.


R (bypass rule) Override the authorization rule policy on an object.

d (delete) Delete an authorization rule.

m (modify) Create authorization rules and modify authorization rule attributes.

v (view) Find and list authorization rules and show authorization rule details.

The authzrule find command shows the list of protected resources where this ruleis attached. You must have the view (v) permission on those protected resourcesbefore they can be shown.


/Management/Domain permissionsThe /Management/Domain container object of the protected object space allowsadministrators to perform domain tasks when that appropriate permissions are set.


m (modify) Modify or create a domain.

v (view) List and show domains.

d (delete) Delete a domain.

/Management/Proxy permissionsThe /Management/Proxy container object of the protected object space allowsadministrators or resource managers to perform delegated management tasks whenthe appropriate permissions are set.


g (delegate) Allows administrators and resource managers to act on the behalf ofthe specified credential.


Chapter 5. Managing domains

An administrator in the management domain can create additional domains. Adomain is given a unique name, and a domain administrator must be specifiedwhen the domain is created. Domain administrators can perform administrativetasks only within their own domains, and do not have the authority to performtasks in other domains.

Within a domain, an administrator can create users, groups, and other objects.Users and groups are specific to their domain and are not allowed to accessresources that are contained in other domains. If users and groups are createdoutside of Tivoli Access Manager, these users and groups can be imported intoother domains. Resources that are defined and access controls for resources that areprotected by Tivoli Access Manager are maintained on a per domain basis.Resources and access controls for resources cannot be shared among domains.

You can perform the following domain tasks:v “Logging in to domains”v “Creating a domain”v “Modifying the description for a domain” on page 62v “Listing domains” on page 63v “Deleting a domain” on page 64

Logging in to domainsYou can log in to a domain using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo log in to the domain that you created, complete the following steps:1. From the login screen, type the domain name that you created. The default

domain name is Default.2. Type the user ID that was created for this domain. The default user ID is

sec_master.3. Type the password associated with the user ID.

pdadminTo log in to a domain using the pdadmin utility, use the login command.

For example, for the myadmin_id administrator to log in interactively to theDomain-ABC domain using the login command, enter the following command:pdadmin login -a myadmin_id -p 12A345 -d Domain-ABC

For more information, see the IBM Tivoli Access Manager for e-business: CommandReference.

Creating a domainAny number of additional domains can be created in addition to the managementdomain.


Only an administrator who is logged in to the management domain is authorizedto create additional domains. A domain can be created only by an administratorwith the appropriate permissions within that management domain.

You can create a domain using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo create a domain, complete the following steps:1. Use Web Portal Manager to log in to the management domain as a domain

administrator.2. Click Secure Domain → Create Secure Domain.3. Type the Secure Domain Name that you want to create. For example, type

Domain-ABC.The following restrictions apply to the domain name:v The maximum length is limited to 64 characters.v The name can contain a-z, A–Z, 0–9, hyphen (-), underscore (_), period (.),

"at" symbol (@), or ampersand (&) characters.v The name can contain any character from a double-byte character set.

4. Optional: Type a Description of the domain, such as: Test Domain.5. Type a New Domain Administrator ID. For example, type myadmin_id.

Note: You must create an administrator ID for the domain.6. Type a New Administrator Password. For example, type 12A345. Passwords

must adhere to the password policies set by the domain administrator.7. Type the password again in Confirm Password.8. Click Create.

pdadminTo create a domain using the pdadmin utility, log in to the management domainand use the domain create command. For example, to create a domain namedDomain-ABC, enter the following command on a single line:pdadmin sec_master> domain create Domain-ABC myadmin_id 12A345 -desc "Test Domain"


Modifying the description for a domainOnly an administrator who is logged in to the management domain is authorizedto modify a domain description. A domain can be modified only by anadministrator with the appropriate permissions within the management domain.

You can modify a domain description using Web Portal Manager or the pdadminutility.

Web Portal ManagerTo modify a domain description, complete the following steps:1. Use Web Portal Manager to log in to the management domain as a domain

administrator.2. Click Secure Domain → List Secure Domain.


3. From the Manage Secure Domains page, click the name of the domain that youwant to change. For example, click Domain-ABC.

4. From the Secure Domain Properties page, edit the Description field to add anew description or change the existing description. For example, type new testdomain description to change the existing description.

5. Click Apply.

pdadminTo modify a domain description using the pdadmin utility, log in to themanagement domain as a domain administrator and use the domain modifycommand.

For example, to change the description of the domain named Domain-ABC to newtest domain description, enter the following command on a single line:pdadmin sec_master> domain modify Domain-ABC description "new testdomain description"


Listing domainsYou can list all domains, except for the management domain, using Web PortalManager or the pdadmin utility.

Only an administrator who is logged in to the management domain is authorizedto list domains. The administrator must have the appropriate permissions to listdomains within the management domain.

Web Portal ManagerTo list all domains, except for the management domain, complete the followingsteps:1. Use Web Portal Manager to log in to the management domain as a domain

administrator.2. Click Secure Domain → List Secure Domain.

The Manage Secure Domains page displays all the domain names, except for themanagement domain, as links. You can filter the domain names to view only thedomain names that meet the criteria you specify.

pdadminTo list all domains, except for the management domain, using the pdadmin utility,log in to the management domain as a domain administrator and use the domainlist command. To list domains, enter the following command:pdadmin sec_master> domain list


Chapter 5. Managing domains 63

Deleting a domainOnly an administrator who is logged in to the management domain is authorizedto delete domains. A domain can be deleted only by an administrator with theappropriate permissions within the management domain.

Deleting a domain deletes the specified Tivoli Access Manager group. If youspecify the optional registry entry option, all user and group information,including associated ACL entries, are deleted from the user registry when thedomain is deleted.

Note: The delete operation cannot be reversed.

You can delete a domain using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo delete a domain, complete the following steps:1. Use Web Portal Manager to log in to the management domain as a domain

administrator.2. Click Secure Domain → List Secure Domain.3. From the Domain List page select the domain you want to delete4. From the Domain Properties page click Delete.

To permanently remove domain information from the user registry, click DeleteRegistry Entry. Otherwise, the user and group information for the domainremains in the user registry and can be used if the domain is created again.

pdadminTo delete a domain using the pdadmin utility, log in to the management domain asa domain administrator and use the domain delete command.

To permanently remove domain information from the user registry, use the–registry option. Otherwise, the user and group information for the domainremains in the user registry and can be used if the domain is created again.

For example, to delete the domain named Domain-ABC and permanently remove thedomain information from the user registry, enter the following command:pdadmin sec_master> domain delete Domain-ABC –registry

Note: If you unconfigure the management domain using the pdconfig utility, anyadditional domain that exists is deleted.



Chapter 6. Managing object spaces

Tivoli Access Manager represents resources to be protected using a virtualrepresentation of the object space that is called the protected object space. An objectspace consists of resource objects and container objects. Resource objects are logicalrepresentations of resources to be protected. Container objects allow you to groupresource objects and other container objects hierarchically into logical groups orregions. Grouping similar objects makes it easier for you to administer a consistentsecurity policy.

Security policy is applied by attaching access control list (ACL) policies, protectedobject policies (POPs), and authorization rules to the objects within the object spacethat represent the physical resources to be protected. The Tivoli Access Managerauthorization service decided whether to permit or deny access to resources basedon user credentials and the conditions specified by the security policy.

The following object spaces are created during the installation of Tivoli AccessManager products:v The /Management object space during the installation of any Tivoli Access

Manager product, if it does not existv The /WebSEAL object space during the installation of Tivoli Access Manager for

e-businessv The /OSSEAL object space during the installation of Tivoli Access Manager for

Operating Systemsv The /PDMQ object space during the installation of Tivoli Access Manager for

Business Integration

You can perform the following object space tasks:v “Creating an object space”v “Listing object spaces” on page 67v “Copying an object space” on page 67v “Importing object spaces” on page 68v “Exporting object spaces” on page 68v “Deleting an object space” on page 69

In the following sections, instructions are provided for using either Web PortalManager or pdadmin, or both. For online help while using Web Portal Manager,click the question mark to open a separate help window for the current page.

Note: There are no equivalent pdadmin commands for importing, exporting, andcopying object spaces.

Creating an object spaceYou can create an object space using Web Portal Manager or the pdadmin utility.

To perform this task, the administrator requires the following permissions:v Create (N)v Modify (m)


Web Portal ManagerTo create an object space, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Create Object Space.3. Type an Object Name. This field is required. For example: /Test-Space4. Type a Description for the object space. For example: New Object Space

5. Click Create. To see the /Test-Space object space in the hierarchical structure,browse the object space. See “Listing object spaces” on page 67.

Because an object space consists of resource objects and container objects, you donot have to specify an object type when using Web Portal Manager.

pdadminTo create an object space in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the objectspace create command.

Note: Do not use the objectspace command on object spaces that are created by ordeveloped using Tivoli Access Manager. The following object spaces arecreated by Tivoli Access Manager:v /Managementv /WebSEALv /OSSEALv /PDMQ

For example, to create the /Test-Space object space that is an application containerobject, which is object type 14, enter the following command:pdadmin sec_master> objectspace create /Test-Space "New Object Space" 14

When creating an object space, an object type must be specified. This object spaceexample assigns an object type of 14, which is for an application container object.

“Protected object space” on page 34 discusses the two general types of objects:resource objects and container objects. You can select any of the listed object spacetypes, or use any unused category number listed in the following list to designatethe object space type and assign a meaning to it.

The following object space types are valid for Tivoli Access Manager:0 Unknown1 Secure domain2 File3 Executable program4 Directory5 Junction6 WebSEAL server7 Unused8 Unused9 HTTP server10 Nonexistent object11 Container object12 Leaf object13 Port14 Application container object15 Application leaf object16 Management object


17 Unused


Listing object spacesYou can list all object spaces using Web Portal Manager or the pdadmin utility.

To perform this task, the administrator requires the following permissions:v Browse (b)v View (v)

Web Portal ManagerTo list all object spaces, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Browse Object Space to display the Browse Object Space

page.

The Browse Object Space page displays all the objects in the domain in ahierarchical structure. All object spaces appear at the same structural level as thedefault /Management object space. Each object space and the corresponding objectare displayed as a link. When you select any link, the Protected Object Propertiespage for that object or object space is displayed.

pdadminTo list all object spaces in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the objectspace list command.pdadmin sec_master> objectspace list


Copying an object spaceYou can copy an object space using Web Portal Manager only.

Web Portal ManagerTo copy an object space, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Copy/Paste Object Space to display the Copy/Paste

Object Space page.3. To select which objects to copy, navigate the object space and select the

object-specific check boxes in the Copy column.4. To select where these objects are to be pasted, navigate to the object space and

select the object-specific check boxes in the Paste column.5. Click Copy/Paste to copy the selected object space hierarchies to the designated

locations.

If successful, the copied object space is shown under the pasted location. Tovalidate, click Refresh.

Chapter 6. Managing object spaces 67

Importing object spacesYou can import an object space using Web Portal Manager only.

Web Portal ManagerTo import an object space, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Import Object.3. From the Import Protected Object From File page, complete one of the

following steps:v In the Object File Name field, type the name of the object to import. For

example, type objectImport.xml.v Click Browse to select a file name.

4. Optional: Select the Create Groups check box to trigger the creation of a groupfor associated ACLs with entries with the type Group.

5. When the Create Groups box is selected, in the Registry Container text field,type the name of the registry container. For example, type o=ibm,c=us.

6. If the file containing the object space was encrypted when it was exported, inthe Encryption String text field, type the string that was used to encrypt theXML file.

7. Click Import.

If successful, the imported object space is available when you browse the objectspace.

Exporting object spacesYou can export an object space using Web Portal Manager only.

Web Portal ManagerTo export an object space, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Browse Object Space to display the Browse Object

Space page.3. Navigate the hierarchy and select the object that you want to export.4. From the Protected Object Properties page, click Export to display the Export

Object to File page.5. Optional: Select the Export Object including Children check box to descend

the object hierarchy and export all child objects.6. Optional: In the Encryption String text field, type the string to use to encrypt

the XML file. If not specified, the exported file is in plain text.7. When an Encryption String is provided, in the Confirm Encryption String

text field, type the string again.8. Click Export to display the File Download window.9. Click Save to display the Save As window.

10. Click Save to create the file that contains the exported description. The defaultfile name is objectExport.xml.

If successful, the exported XML description file is available in the specifiedlocation.


Deleting an object spaceYou can delete an object from the object space using Web Portal Manager or thepdadmin utility.

To perform this task, the administrator requires the following permissions:v Delete (d)v Modify (m)

Web Portal ManagerTo delete an object from the object space, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Browse Object Space.3. From the Browse Object Space page, expand and click the object space that you

want to delete.4. From the Protected Object Properties page, the name of the object space is

displayed in the Object Name field. Click Delete.5. To confirm the deletion, click Delete again.

If successful, a message displays indicating that the object space was deleted.

pdadminTo delete an object space in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the objectspace delete command.

For example, to delete the object space named /Test-Space, enter the followingcommand:pdadmin sec_master> objectspace delete /Test-Space


Chapter 6. Managing object spaces 69

Chapter 7. Managing protected objects

An object is a logical representation of a system resource. To protect objects, youneed to apply security policies. Security policies are the combination of accesscontrol list (ACL) policies, protected object policies (POPs), and authorization rulesthat you can attach to an object.

You can perform the following object tasks:v “Creating an object”v “Listing objects” on page 73v “Importing objects” on page 73v “Exporting objects” on page 74v “Deleting an object” on page 74


Note: There are no equivalent pdadmin commands for importing and exportingobjects.

After an object space is created, you can populate it with objects and then managethese objects. For information about creating an object space, see “Creating anobject space” on page 65.

Creating an objectYou can create an object using Web Portal Manager or the pdadmin utility. WebPortal Manager provides two ways of creating objects:v Specifying the fully qualified path of the new object starting at rootv Specifying the new object from the provided path of the parent object

To perform this task, the administrator requires the following permissions:v Create (N)v Modify (m)

Web Portal Manager, from rootTo create an object specifying the path from root, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Create Object to display the Create Protected Object

page.3. Type the full path of the object in the Object Name text field. For example,

type /Management/Groups/test-object.4. Optional: In the Description text field, type a description for the object. For

example, type Test Object.5. Click Create.

To be able to attach a policy to this protected object, click Object Space → BrowseObject Space. The Browse Object Space page provides a hierarchical view of all


the objects in the domain as links. Click the link for an object to go to its ProtectedObject Properties page. From this page, select the Can Policy be attached to thisobject check box and click Apply.

Web Portal Manager, from parent objectTo create an object when using the parent object as the base path, complete thefollowing steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Browse Object Space to display the Browse Object Space

page.3. Navigate the object hierarchy and select the link of the parent object to display

the Protect Object Properties page. For example, select the link that isassociated with the /Management/Groups object.

4. Click the Create Child Object link to display the Create Protected Object pagewhere the Object Name and Description text fields contain the values of theparent object.

5. In the Object Name text field, append a slash and the name of the new object.For example, append /test-object to the provided parent path of/Management/Groups.

6. Optional: In the Description text field, modify the description for the object.For example, type Test Object.

7. Click Create.

After the object is created, a dialog is displayed with the link to this object. Toattach a policy to this protected object, click this link to display its Protected ObjectProperties page. From this page, select the Can Policy be attached to this objectcheck box and click Apply.

pdadminTo create an object in the domain using the pdadmin utility, log in to the domainas the domain administrator and use the object create command.

For example, to create the object named /Management/test-object that is anapplication container object (14), enter the following command:pdadmin object create /Management/test-object “Test Object” 14

ispolicyattachable yes

The type can be one of the following object type categories:0 Unknown1 Secure domain2 File3 Executable program4 Directory5 Junction6 WebSEAL server7 Unused8 Unused9 HTTP server10 Nonexistent object11 Container object12 Leaf object13 Port14 Application container object


15 Application leaf object16 Management object17 Unused

When creating an object, a type must be specified. You can select an appropriatecategory, or use any number to designate the object type and assign a meaning toit.

If the ispolicyattachable option is omitted from the object create command, thiscommand assumes that you intended to use the objectspace create command. Anobject space is created rather than an object.


Listing objectsYou can list objects in the domain using Web Portal Manager or the pdadminutility. To perform this task, the administrator requires the following permissions:v Browse (b)v View (v)

Web Portal ManagerTo list objects, complete the following steps:1. Use Web Portal Manager log in to the domain as a domain administrator.2. Click Object Space → Browse Object Space.

The Browse Object Space page displays all the objects in the domain in ahierarchical structure. All object spaces appear at the same structural level as thedefault /Management object space. Each object space and each object are displayedas a link. When you select any link, the Protected Object Properties page for thatobject or object space is displayed.

pdadminTo list all objects in the domain using the pdadmin utility, log in to the domain asthe domain administrator and use the object list command.

For example, to list the objects under the /Management object space, enter thefollowing command:pdadmin sec_master> object list /Management


Importing objectsYou can import an object using Web Portal Manager only.

Web Portal ManagerTo import an object, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Import Object.

Chapter 7. Managing protected objects 73

3. From the Import Protected Object From File page, complete one of thefollowing steps:v In the Object File Name field, type the name of the object to import. For

example, type objectImport.xml.v Click Browse to select a file name.

4. Optional: Select the Create Groups check box to trigger the creation of a groupfor associated ACLs with the type Group.

5. When the Create Groups box is selected, in the Registry Container text field,type the name of the registry container. For example, type o=ibm,c=us.

6. If the file containing the object space was encrypted when it was exported, inthe Encryption String text field, type the string that was used to encrypt theXML file.

7. Click Import.

If successful, the imported object is available when you browse the object space.

Exporting objectsYou can export an object using Web Portal Manager only.

Web Portal ManagerTo export an object, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Browse Object Space to display the Browse Object

Space page.3. Navigate the hierarchy and select the object that you want to export.4. From the Protected Object Properties page, click Export to display the Export

Object to File page.5. Optional: Select the Export Object including Children check box to descend

the object hierarchy and export all child objects.6. Optional: In the Encryption String text field, type the string to use to encrypt

the XML file. If not specified, the exported file is in plain text.7. When an encryption string is provided, in the Confirm Encryption String text

field, type the string again.8. Click Export to display the File Download window.9. Click Save to display the Save As window.

10. Click Save to create the file that contains the exported description. The defaultfile name is objectExport.xml.


Deleting an objectYou can delete an object using Web Portal Manager or the pdadmin utility.

To perform this task, the administrator requires the following permissions:v Delete (d)v Modify (m)


Web Portal ManagerTo delete an object, complete the following steps:1. Use Web Portal Manager log in to the domain as a domain administrator.2. Click Object Space → Browse Object Space.

The Browse Object Space page provides a hierarchical display of all objects inthe domain as links.

3. Click the link for an object to see its properties. These properties includewhether ACL policies, POPs, and authorization rules are attached to the objectand whether the object has extended attributes. For example, click the/Management/text-object link to display its properties.

4. From the Protected Object Properties page, ensure the object named is the oneyou want to delete and click Delete.

pdadminTo delete an object in the domain using the pdadmin utility, log in to the domainas the domain administrator and use the object delete command.

For example, to delete the object named /Management/test-object, enter thefollowing command:pdadmin object delete /Management/test-object


Chapter 7. Managing protected objects 75

Chapter 8. Managing access control

A domain administrator can use access control list (ACL) policies to control accessto objects. ACL policies contain ACL entries that control who can access whichdomain resources and perform which actions. For more information about ACLpolicies, see “ACL policies.” For details about the ACL policy tasks that a domainadministrator can perform, see “Managing ACL policies” on page 83.

A domain administrator manages the ACL policies by adding, removing, andmodifying the ACL entries in the ACL policies. An ACL entry defines a user orgroup and which actions each can perform against a protected object. A domainadministrator can manage these ACL entries before or after the ACL policy isattached to domain resources. Any change to the ACL entry affects only the accessthat these users and groups have against a specific domain resource to which theACL policy is attached. For more information about ACL entries in an ACL policy,see “ACL entries” on page 78.

To define ACL entries, a domain administrator adds or removes permissions(actions) for specific users or groups. A permission is an action that is defined by anaction bit in an action group. An action group is a set of permissions. A domainadministrator can add to or remove from an ACL entry. When Tivoli AccessManager is installed, the primary action group is created, and contains 17permissions. These permissions are defined using action bits. As additionalresource managers are installed, additional action groups might be created. Asneeded, a domain administrator can create additional action groups and add newactions to previously created action groups. For additional information aboutactions and action groups, see “Action groups and actions” on page 80. For detailsabout the action group tasks that a domain administrator can perform, see“Managing action groups” on page 95. For details about the action tasks that adomain administrator can perform, see “Managing actions” on page 97.

A domain administrator can assign another user administrative authority. To defineanother administrative user, the domain administrator sets the ACL entries for thatuser to match the ACL entries of the domain administrator. In this situation, boththe new administrative user and the domain administrator have the sameauthority.

ACL policiesWithin the protected object space, ACL policies can be attached to resource objectsand container objects. Each ACL policy contains one or more ACL entries thataffect only that object. For example, the ACL policy that is attached to the spoolerobject might allow all requesters the following permissions:v Executev Listv Readv Write

However, the ACL policy that is attached to the docs_repository object mightallow all requesters the following permissions:v Listv Read


In this case, the ACL policy that is attached to these objects are both for allrequesters, but the permissions that are defined in the ACL entry for all requestersis different.

Container objects represent specific regions in the protected object space. After adomain administrator creates an ACL policy and attaches it to a container object,the ACL policy serves the following important security tasks:v The root (/) container object begins the chain of ACL inheritance for the entire

protected object space.v Through inheritance, the root object defines the security policy for the entire

object space.v Unless an explicit ACL policy is attached to a contained object, the ACL policy

for the container object defines the security policy for all resources in thatcontainer object.

v The traverse permission allows a requester to pass through a container object tothe requested object. To deny access to all objects in a region, remove thetraverse permission (T action bit) from the ACL entry.

v The traverse permission does not grant any other access controls to the containerobject.

ACL entriesEach ACL policy can contain one or more ACL entries. Each ACL entry containsattributes that identify the user or group and the actions that this user or groupcan perform. The number of required attributes for an ACL entry depends on theACL entry type. The general format of an ACL entry contains the followingattributes:

Type The type attribute specifies the entity category (user, group, or special) forwhich the ACL entry was created. For additional information about thetype attribute, see “Type attribute” on page 79.

ID The ID attribute is the unique identifier (name) of the user or group that isspecified with the type attribute. The any-other and unauthenticatedspecial entry types do not require the ID attribute. For additionalinformation about the ID attribute, see “ID attribute” on page 79.

PermissionsThe permissions attribute defines the set of permissions (actions) that arepermitted on the resource by this user or group. Permissions are definedusing action bits. Actions bits are defined in action groups. For additionalinformation about the permissions attribute, see “Permissions attribute” onpage 79. For additional information about action bits and action groups,see “Action groups and actions” on page 80.

Figure 16 shows the attributes of an ACL entry.

Figure 16. ACL entry attributes


Type attributeThe type attribute of an ACL entry type identifies the user, group, or special entityfor a specific ACL entry. The following types are supported:

user Sets permissions for a specific user in a domain. The user must be amember of the domain with an account in the registry. The user entry typerequires a user name (ID). The entry format is user ID permissions asshown in the following example:user anthony -------T-----r-

group Sets permissions for all members of a specific group in a domain. Thegroup entry type requires a group name (ID). The entry format is group IDpermissions as shown in the following example:group engineering -------T-----r-

any-otherSets permissions for all authenticated users. No ID designation is required.The entry format is any-other permissions as shown in the followingexample:any-other -------T-----r-

The any-other entry type is also known as any-authenticated.

unauthenticatedSets permissions for those users who have not been authenticated by thepolicy server. No ID attribute is required in the ACL entry. The entryformat is unauthenticated permissions as shown in the followingexample:unauthenticated -------T-----r-

This ACL entry is a mask (a bit-wise and operation) against the any-otherACL entry to determine the action set. A permission for unauthenticated isgranted only if the permission also appears in the any-other entry.

For example, when unauthenticated has read and write permissions andany-other has transverse and read permissions, the resulting action set isread only. This example is shown in the following equation:

unauthenticated -------------rw+ any-other -------T-----r-

-------------r-

ID attributeEach user ACL entry and each group ACL entry have unique identifiers (name).These names must represent valid users or groups that are created in a domainand have an account in the registry.

The any-other and unauthenticated special entry types do not use the ID attribute.

Permissions attributeEach ACL entry contains a set of permissions (actions) that describes the specificoperations that are permitted on the object by the user or group. Permissions arecontext sensitive. The behavior of certain permissions varies according to wherethe permissions are applied. For example, the modify permission (m action bit)behaves differently for protected resources in the /WebSEAL object space than forprotected resources in the /Management object space.

Chapter 8. Managing access control 79

Permissions control protected resources in the following ways:v Determine whether a user can perform operations on protected objectsv Determine whether an administrator can change security policy on the object

and any object that inherits permissionsv Determine whether Tivoli Access Manager itself can delegate credentials for a

user

Action groups and actionsA domain administrator defines the actions that requesters can perform on objectsin the protected object spaces. An action is a permission in an action group that isdefined in the action group by an action bit. A domain administrator modifies theACL entries in an ACL policy before or after the ACL policy is attached to anobject. The actions that can be defined in an ACL entry must be previously definedin an action group.

When Tivoli Access Manager is installed, the primary action group is created. Asadditional applications and resource managers are installed, additional actiongroups might be created. Independent of whether additional action groups arecreated during subsequent installations, a domain administrator can createadditional action groups. In the primary action group, an action group that iscreated during the installation of an application or resource manager, or a customaction group, a domain administrator can create custom permissions by definingnew action bits.

Default permissions in the primary action groupTivoli Access Manager defines permissions using action bits. When you installTivoli Access Manager, the default primary action group is created. This actiongroup contains 17 permissions. Web Portal Manager divides these permissions intothe following categories.v Basev Genericv Application

Table 2 shows the action bit in the primary action group, a brief description of itsassociated permission, and its category as shown in Web Portal Manager.

Table 2. Action bits, permissions, and Web Portal Manager category of the default primaryaction group

Action bit Description of permission Category

a Attach Base

A Add Base

b Browse Base

B Bypass protected object policy (POP) Base

c Control Base

d Delete Generic

g Delegation Base

l List directory Application

m Modify Generic

N Create Base

R Bypass rule Base


Table 2. Action bits, permissions, and Web Portal Manager category of the default primaryaction group (continued)

Action bit Description of permission Category

r Read Application

s Server administration Generic

t Trace Base

T Traverse Base

v View Generic

W Password Base

x Execute Application

Tivoli Access Manager provides the capability to define additional permissions foruse by resource managers. For more information, see “Managing action groups” onpage 95.

Custom permissions in custom action groupsThe default permissions in the primary action group are available to allapplications. If a custom action group uses these default permissions, theassociated actions must closely match that of the actual operation that is performedby an action in the primary action group. For example, the read permission (actionbit r) must be used only by an action that requires read-only access to a protectedobject.

The authorization service does not know or care about the action. So a customaction group can reuse an action bit from the primary action group to create anaction in a custom action group for an unrelated operation. However, this situationmight cause difficulty for a domain administrator who must be able to distinguishbetween two dissimilar uses of the same action bit.

If a custom action group uses an action that is not appropriately represented by adefault permission, a domain administrator can define a new action bit for apermission that can be used and be recognized by the authorization service. Fordetails, see “Managing action groups” on page 95.

When to create custom permissionsTo protect a printer from unauthorized use, a domain administrator can create acustom action. Figure 17 on page 82 shows an example of this requirement. A printspooling service is written with the authorization application programminginterface (authorization API) so that it can call the authorization service to performACL checks on requests made to the printer.

The default permissions do not include a permission for protecting printers.However, the printer can be protected by a custom action bit (p in this example).

An ACL policy is attached to the printer object. If a user requests the use of thisprotected printer, that user must have an ACL entry that contains the p action bit.The authorization service returns a favorable response if the p action bit is presentand the printing operation proceeds. If the authorization service returns anunfavorable response, the printing operation is not allowed to proceed.


Representation of custom actions and action groupsAs discussed in “ACL entries” on page 78, ACL entries contain an entry type, anID for user and group types, and the set of permissions (action bits).

You must use a special syntax to identify custom action bits that belong to actiongroups other than the primary action group. The primary action group is thedefault action group. Permissions that represent the action bits from multipleaction groups are presented in the following format:bits[group_1]bits_1...[group_n]bits_n

The following example is an example of the permissions attribute:abgTr[groupA]Pq[groupB]Rsy[groupC]ab

The previous permissions attribute has the following interpretation:v The primary action group contains the a, b, g, T, and r action bits.v The groupA action group contains the P and q action bits.v The groupB action group contains the R, s, and y action bits.v The groupC action group contains the a and b action bits.

Action group groupC contains action bits that use the same letters for action bits asused in the primary action group. The action bits are associated with a specificaction group (groupC). So the a and b action bits have unique identities and canrepresent different permissions from those action bits in the primary action group.

Scenario using custom actionsThe following scenarios show how to add custom actions to an ACL policy that isattached to a protected object:1. To show action groups, enter the following command:

pdadmin sec_master> action group list

primarytest-group

2. To list permissions in the test-group action group, enter the followingcommand:pdadmin sec_master> action list test-group

P Test-Action SpecialS Test-Action2 Special

3. To list ACL policies, enter the following command:pdadmin sec_master> acl list

default-webseal

Printspoolerservice

Authorizationservice

Authorizationpolicy

database

API

Printer ACLUser michael p

Can I use thisprinter?

"YES"

Figure 17. Permissions for a custom print spooler


default-rootdefault-gsodefault-policydefault-configtest-acldefault-replicadefault-management

4. To show details about the ACL name test-acl, enter the following command:pdadmin sec_master> acl show test-acl

ACL Name: test-aclDescription:Entries:

User sec_master TcmdbvaGroup ivmgrd-servers TlAny-other r

5. To add an ACL entry for the user named Kathy that contains permissions fromthe action groups named primary and test-group, enter the followingcommand:pdadmin sec_master> acl modify test-acl set user kathy brT[test-group]PS

6. To validate this addition, enter the following command:pdadmin sec_master> acl show test-acl

ACL Name: test-aclDescription:Entries:User sec_master TcmdbvaGroup ivmgrd-servers TlAny-other rUser kathy Tbr[test-group]PS

Managing ACL policiesYou can create and configure an ACL policy and attach it to objects in theprotected object space. ACL policies are placed in the master policy database on adomain-by-domain basis. The master policy database is controlled by the policyserver.

You can perform the following ACL policy tasks:v “Creating an ACL policy” on page 84v “Modifying the description of an ACL policy” on page 84v “Listing ACL policies” on page 85v “Viewing an ACL policy” on page 85v “Cloning an ACL policy” on page 86v “Importing ACL policies” on page 86v “Exporting all ACL policies” on page 86v “Exporting a single ACL policy” on page 87v “Exporting multiple ACL policies” on page 87v “Attaching an ACL policy to an object” on page 88v “Locating where an ACL policy is attached” on page 89v “Detaching an ACL policy from an object” on page 88v “Deleting an ACL policy” on page 89



Note: There are no equivalent pdadmin commands for importing, exporting, orcloning ACL policies.

Creating an ACL policyYou can create an ACL policy using Web Portal Manager or the pdadmin utility.After creating an ACL policy, it contains an entry for as the logged in user whocreated the ACL policy. This ACL entry has all the defined permissions. You mustmodify this ACL policy by adding ACL entries for the additional users and groupsthat need to manage this ACL policy and manage the objects to which this ACLpolicy is attached.

After adding the appropriate ACL entries for these users and groups, you mightneed to remove the ACL entry for the user who created the ACL policy.

Web Portal ManagerTo create an ACL policy, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → Create ACL.3. In the ACL Name file, type the name of the ACL policy. For example, type

Test-ACL.4. Optional: In the Description field, type a description of the ACL. For example,

type Test of new ACL.5. Click Create.

If successful, a link for this ACL policy is available when you list all ACL policies.You can now add and remove ACL entries from the ACL policy. For details aboutadding and removing ACL entries, see “Creating an ACL entry” on page 90 and“Removing ACL entries from an ACL policy” on page 91.

pdadminTo create an ACL policy in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the acl create command.

For example, to create an ACL policy named Test-ACL, enter the followingcommand:pdadmin sec_master> acl create Test-ACL


Modifying the description of an ACL policyYou can modify an ACL policy using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo modify the description of an ACL policy, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link for the ACL policy that you want

to change.


4. From the ACL Properties page, modify the text in the Description field, asappropriate.

5. Click Set.

pdadminTo modify the description of an ACL policy in the domain using the pdadminutility, log in to the domain as a domain administrator and use the acl modifycommand with the description option.

For example, to modify the description of the ACL named Test-ACL to be ACL forTest resources, enter the following command:pdadmin sec_master> acl modify Test-ACL description "ACL for Test resources"

To show the modifications to the ACL, use the acl show command. For example,to show the ACL named Test-ACL, enter the following command:pdadmin sec_master> acl show Test-ACL

ACL Name: Test-ACLDescription: ACL for Test resourcesEntries: User maryj r


Listing ACL policiesYou can list all ACL policies using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo list all ACL policies in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.

The Manage ACLs page displays all the ACL policies in the domains.

pdadminTo list all ACL policies in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the acl list command.pdadmin sec_master> acl list


Viewing an ACL policyYou can view an ACL policy using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo view an ACL policy in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link for the ACL policy that you want

to view.


pdadminTo view an ACL policy in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the acl show command.pdadmin sec_master> acl show test-acl


Cloning an ACL policyYou can clone an ACL policy using Web Portal Manager only. To clone an ACLpolicy in the domain using Web Portal Manager:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, select the ACL policy you want to clone.4. From the ACL Properties page, click Clone.5. From the Clone ACL page, type an ACL Name. For example, type Test-ACL.

The default value is the name of the original ACL with the prefix Clone.6. Optional: Type a Description of the ACL policy For example, type Clone of

new ACL. The default value is the description of the original ACL.7. Click Clone.

If successful, a link for the cloned ACL policy is created and a success message isdisplayed.

Importing ACL policiesYou can import an ACL policy using Web Portal Manager only. To import an ACLpolicy in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → Import ACL.3. From the Import ACL page, complete one of the following steps:

v In the ACL File Name field, type the name of the ACL to import. Forexample, type aclImport.xml.

v Click Browse to select a file name.4. Optional: Select the Create Groups check box to create a group for ACL entries

with the type Group.5. When Create Groups is selected: In the Registry Container text field, type the

name of the registry container for the ACL. For example, type o=ibm,c=us.6. If the file containing the ACL was encrypted when it was exported, in the

Encryption String text field, type the string that was used to encrypt the XMLfile.

7. Click Import.

If successful, the imported ACL policy is available when you list all the ACLpolicies.

Exporting all ACL policiesYou can export the definitions of all ACL policies using Web Portal Manager only.To export the definition of all ACL policies in the domain, complete the followingsteps:1. Use Web Portal Manager to log in to the domain as a domain administrator.


2. Click ACL → Export All to display the Export ACL to File page.3. Optional: In the Encryption String text field, type the string to use to encrypt


field, type the string again.5. Click Export to display the File Download window.6. Click Save to display the Save As window.7. Click Save to create the file that contains the exported description. The default

file name is aclExport.xml.


Exporting a single ACL policyYou can export the definition of a single ACL policy using Web Portal Manageronly. To export the definition of a single ACL policy in the domain, complete thefollowing steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, select the ACL that you want to export.4. From the ACL Properties page, click Export to display the Export ACL to File

page.5. Optional: In the Encryption String text field, type the string to use to encrypt


field, type the string again.7. Click Export to display the File Download window.8. Click Save to display the Save As window.9. Click Save to create the file that contains the exported description. The default

file name is aclExport.xml.


Exporting multiple ACL policiesYou can export the definition of ACL policies from a list using Web Portal Manageronly. To export the definition of ACL policies from the list in the domain, completethe following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, select the ACLs that you want to export.4. Click Export to display the Export ACL to File page.5. Optional: In the Encryption String text field, type the string to use to encrypt




9. Click Save to create the file that contains the exported descriptions. The defaultfile name is aclExport.xml.


Attaching an ACL policy to an objectYou can attach an ACL to a protected object using Web Portal Manager or thepdadmin utility.

To perform this task, the administrator requires the attach (a) permission.

Web Portal ManagerTo attach an ACL to a protected object, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link for the name of the ACL that you

want to attach to a protected object.4. From the ACL Properties page, click the Attach tab.5. Click Attach.6. From the Attach ACL page, type a Protected Object Path. For example, type

/Management/test-object.7. Click Attach.

If successful, the protected object is displayed as a protected object link for thenamed ACL.

pdadminTo attach an ACL to a protected object in the domain using the pdadmin utility,log in to the domain, and use the acl attach command.

For example, to attach an ACL named Test-ACL to a protected object named/Management/test-object, enter the following command:pdadmin sec_master> acl attach /Management/test-object Test-ACL


Detaching an ACL policy from an objectYou can detach an ACL from an object using Web Portal Manager or the pdadminutility.


Web Portal ManagerTo detach an ACL from a protected object in the domain, complete the followingsteps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link for the ACL policy to detach.4. From the ACL Properties page, click the Attach tab.


5. If the ACL is attached to protected objects, select one or more check boxes forthe protected objects from which you want to detach the ACL.

6. Click Detach. You are asked to confirm the detachment.

pdadminTo detach an ACL from a protected object in the domain using the pdadmin utility,log in to the domain, and use the acl detach command.

For example, to detach the ACL from the protected object named/Management/test-object, enter the following command:pdadmin sec_master> acl detach /Management/test-object


Locating where an ACL policy is attachedYou can find where an ACL is attached using Web Portal Manager or the pdadminutility.

Web Portal ManagerTo find where an ACL is attached, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL. A list of ACL names is displayed.3. From the Manage ACLs page, click the link for the name of the ACL.4. From the ACL Properties page, click the Attach tab.

pdadminTo find where an ACL is attached in the domain using the pdadmin utility, log into the domain as a domain administrator and use the acl find command.

For example, to find where the ACL named Test-ACL is attached, enter thefollowing command:pdadmin sec_master> acl find Test-ACL


Deleting an ACL policyYou can delete an ACL policy using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo delete an ACL policy, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, select one or more check boxes of the ACL

policies that you want to delete.4. Click Delete, and then confirm the deletion by clicking Delete again on the

Delete confirmation page.

If successful, the ACL policy is no longer included in the list of ACL policies in theManage ACLs page.


pdadminTo delete an ACL policy in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the acl delete command.

For example, to delete the ACL named Test-ACL, enter the following command:pdadmin sec_master> acl delete Test-ACL


Managing ACL entries in ACL policiesYou can perform the following ACL entry tasks on ACL policies:v “Creating an ACL entry”v “Modifying permissions for an ACL entry” on page 91v “Removing ACL entries from an ACL policy” on page 91

In the following sections, instructions are provided for using either Web PortalManager or the pdadmin utility, or both. For online help while using Web PortalManager, click the question mark to open a separate help window for the currentpage.

Creating an ACL entryYou can create an ACL entry for an ACL policy using Web Portal Manager or thepdadmin utility. Use this procedure to create the ACL entry for any user, group, orspecial ACL entry type (any-other and unauthenticated).

Web Portal ManagerTo create an ACL entry, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link for the ACL policy you want to

change.4. From the ACL Properties page, click Create.5. Select the appropriate entry type: user, group, any-other, or unauthenticated.6. For user or group, specify the name.7. Select the check box for each permission to enable.8. Click Apply.

pdadminTo create an ACL entry for an ACL policy in the domain using the pdadmin utility,log in to the domain as a domain administrator and use the acl modify commandwith the set option.

For example, to create the permissions for user maryj for the Test-ACL ACL policyto have r (read) action bit, enter the following command:pdadmin sec_master> acl modify Test-ACL set user maryj r

To show the modifications to the ACL, use the acl show command. For example,to show the ACL named Test-ACL, enter the following command:


pdadmin sec_master> acl show Test-ACL

ACL Name: Test-ACLDescription:Entries: User maryj r


Modifying permissions for an ACL entryYou can modify permissions for an ACL policy using Web Portal Manager or thepdadmin utility. Use this procedure to modify the permissions for any user, group,or special ACL entry type (any-other and unauthenticated).

Web Portal ManagerTo modify permissions in an ACL entry, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link for the ACL policy you want to

change.4. From the ACL Properties page, click the permission link.5. From the ACL Entry Properties page, select the check box for each permission

to enable or clear the check box for each permission to disable.6. Click Apply.

pdadminTo modify an ACL policy in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the acl modify command with the setoption.

For example, to modify the permissions for user maryj for the Test-ACL ACL policyto have r (read) and w (write) action bits, enter the following command:pdadmin sec_master> acl modify Test-ACL set user maryj rw


ACL Name: Test-ACLDescription:Entries: User maryj rw


Removing ACL entries from an ACL policyYou can remove ACL entries from an ACL policy using Web Portal Manager or thepdadmin utility. Use this procedure to remove the ACL entry for any user, group,or special ACL entry type (any-other and unauthenticated).

Web Portal ManagerTo remove an ACL entry, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.


3. From the Manage ACLs page, click the link for the ACL policy that you wantto remove.

4. From the ACL Properties page, select the user, group, or special ACL entry typeto remove.

5. Click Delete.

pdadminTo remove an ACL entry from an ACL policy in the domain using the pdadminutility, log in to the domain as a domain administrator and use the acl modifycommand with the remove option.

For example, to remove the ACL entry for user maryj from the Test-ACL ACLpolicy, enter the following command:pdadmin sec_master> acl modify Test-ACL remove user maryj


ACL Name: Test-ACLDescription:Entries:


Managing extended attributes in ACL policiesYou can perform the following extended attribute tasks on an ACL policy:v “Creating extended attributes for an ACL policy”v “Modifying extended attributes from an ACL policy” on page 93v “Listing extended attributes of an ACL policy” on page 93v “Viewing extended attributes of an ACL policy” on page 94v “Deleting extended attributes from an ACL policy” on page 94v “Deleting extended attribute values from an ACL policy” on page 95


Creating extended attributes for an ACL policyYou can create an extended attribute for an ACL policy using Web Portal Manageror the pdadmin utility.

Web Portal ManagerTo create an extended attribute for an ACL policy, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link of the ACL policy for which you

want to create an extended attribute.4. From the ACL Properties page, click the Extended Attribute tab.5. Click Create.


6. From the Create Extended Attribute page, define the extended attribute:a. In the Attribute Name field, type the name of the attribute. This field is

displayed only when the attribute type is “Generic Attribute”.b. In the Attribute Type field, select the type of attribute.c. In the Attribute Value field, select the value for the attribute, unless the

selected attribute type is “Generic Attribute”. When you select the “GenericAttribute” attribute type, type the value for the attribute.

7. Click Apply.

pdadminTo create an extended attribute for an ACL policy in the domain using thepdadmin utility, log in to the domain as a domain administrator and use the aclmodify command with the set attribute option.

For example, to create a generic attribute named Dept_No with a value of 445 andassociate it with the ACL named Test-ACL, enter the following command:pdadmin sec_master> acl modify Test-ACL set attribute Dept_No 445


Modifying extended attributes from an ACL policyYou can modify extended attributes for an ACL policy using the pdadmin utilityonly. Web Portal Manager does not support modifying attributes. To use WebPortal Manager, an administrator needs to delete the attribute and then create theattribute again.

pdadminTo modify an extended attribute for an ACL policy in the domain using thepdadmin utility, log in to the domain as a domain administrator and use the aclmodify command with the set attribute option.

For example, to modify a generic attribute named Dept_No and add a value of 445and associate it with the ACL named Test-ACL, enter the following command:pdadmin sec_master> acl modify Test-ACL set attribute Dept_No 445


Listing extended attributes of an ACL policyYou can list the extended attributes of an ACL policy using Web Portal Manager orthe pdadmin utility.

Web Portal ManagerTo list all the extended attributes of an ACL policy in the domain, complete thefollowing steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link for name of the ACL policy that

you want to view.4. From the ACL Properties page, click the Extended Attribute tab.


The ACL Properties page displays all the extended attributes for the selected ACLpolicy.

pdadminTo list all the extended attributes for an ACL policy using the pdadmin utility, login to the domain as a domain administrator and use the acl list command with theattribute option. For example, to list the extended attributes of the ACL policynamed pub_acl_3, enter the following command:pdadmin sec_master> acl list pub_acl_3 attribute


Viewing extended attributes of an ACL policyYou can view the extended attributes of an ACL policy using Web Portal Manageror the pdadmin utility.

Web Portal ManagerTo view the extended attributes of an ACL policy in the domain, complete thefollowing steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link for the ACL policy that you want

to view.4. Click the Extended Attribute tab.

pdadminTo view the extended attributes for an ACL policy using the pdadmin utility, log into the domain as a domain administrator and use the acl show command with theattribute option. For example, to show the myAttribute attribute of the test-aclACL policy, enter the following command:pdadmin sec_master> acl show test-acl attribute myAttribute


Deleting extended attributes from an ACL policyYou can delete an extended attribute for an ACL policy using Web Portal Manageror the pdadmin utility.

Web Portal ManagerTo delete an extended attribute for an ACL policy, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List ACL.3. From the Manage ACLs page, click the link for the ACL policy from which you

want to delete extended attributes.4. From the ACL Properties page, click the Extended Attributes tab.5. Select the extended attributes.6. Click Delete.


pdadminTo delete an extended attribute for an ACL policy in the domain using thepdadmin utility, log in to the domain as a domain administrator and use the aclmodify command with the delete attribute option.

For example, to delete the extended attributed named Dept_No from the ACLnamed Test-ACL, enter the following command:pdadmin sec_master> acl modify Test-ACL delete attribute Dept_No


Deleting extended attribute values from an ACL policyYou can delete a value for an extended attribute from an ACL policy using thepdadmin utility only.

pdadminTo delete an attribute value, log in to the domain as a domain administrator anduse the acl modify command with the delete attribute attribute_name attribute_valueoptions.

For example, to delete the value 445 from the extended attributed named Dept_Nofrom the ACL named Test-ACL, enter the following command:pdadmin sec_master> acl modify Test-ACL delete attribute Dept_No 445

Only the attribute value is deleted.


Managing action groupsPermissions are used to grant access to perform a specific operation on resourcesthat are protected by Tivoli Access Manager. Tivoli Access Manager provides 17predefined permissions for immediate use. These permissions are stored in thepredefined action group named primary.

Each permission is associated with an action bit. These predefined permissions aredescribed in “Default permissions in the primary action group” on page 80.

Tivoli Access Manager provides the ability to create resource manager-specificpermissions. For example, Tivoli Access Manager for Business Integration definesEnqueue and Dequeue permissions to grant access to put messages in a messagequeue or to get messages from the message queue.

Tivoli Access Manager supports a total of 32 action groups, including the primaryaction group.

When you define an action group, the following guidelines and limitations apply:v Each action group can hold up to 32 action bits (including the action bits for the

17 predefined permissions).v An action bit is made up of a letter: a-z, A-Z.v Each action bit character can be used only once within an action group.v You can reuse the same action bit in other action groups.


You can perform the following action group tasks:v “Creating action groups”v “Listing action groups”v “Deleting an action group” on page 97

Creating action groupsYou can create an action group using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo create an action group, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → Create Action Group.3. Type the new Action Group Name. For example, type test-group.4. Click Create.

If successful, a message is displayed when the action group is created.

pdadminTo create an action group in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the action group create command.

For example, to create an action group named test-group, enter the followingcommand:pdadmin sec_master> action group create test-group

The primary action group always appears in a group listing and cannot be deleted.

You must have an entry in an ACL on the /Management/ACL object with the modify(m) action to create action groups and the delete (d) permission to delete actiongroups.


Listing action groupsYou can list all action groups using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo list all action group, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List Action Groups.

The Manage Action Groups page displays a list of all action groups in the domain.

pdadminTo list all action groups in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the action group list command.

For example, to list all action groups, enter the following command:pdadmin sec_master> action group list



Deleting an action groupYou can delete an action group using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo delete an action group, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List Action Groups.3. From the Manage Action Groups page, select one or more check boxes for the

action groups that you want to delete.4. Click Delete.5. Confirm the deletion by clicking Delete again on the Delete Action Groups

page.

pdadminTo list action groups in the domain using the pdadmin utility, log in to the domainas a domain administrator and use the action group delete command.

For example, to delete the action group named test-group, enter the followingcommand:pdadmin sec_master> action group delete test-group


Managing actionsYou can perform the following action tasks:v “Creating actions in an action group”v “Listing actions in an action group” on page 98v “Deleting actions from an action group” on page 98

Creating actions in an action groupYou can create an action in an action group using Web Portal Manager or thepdadmin utility.

Web Portal ManagerTo create an action in an action group, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List Action Groups.3. From the Manage Action Group page, click the link for the action group name

in which to create the permission. For example, select the Test-Group link.4. From the Action Group Properties page, click Create to display the Create

Action page. The Action Group Name is automatically completed.5. Type a single character Action Name. For example, type x.6. In the Action Label field, type a short description of the permission. For

example, type Execute.7. In the Action Type field, type a description of the permission, such as the

application to which the permission is specific. For example, type WebSEAL.8. Click Create.

If successful, a message is displayed when the permission is created.


pdadminTo create an action in an action group using the pdadmin utility, log in to thedomain as a domain administrator and use the action create command.

For example, to create an x action bit in the Test-Group action group, enter thefollowing command:pdadmin sec_master> action create x Execute WebSEAL Test-Group


Listing actions in an action groupYou can list all actions in an action group using Web Portal Manager or thepdadmin utility.

Web Portal ManagerTo list all actions in an action group, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List Action Groups.3. From the Manage Action Group page, click the link for the action group name.

pdadminTo list the actions in an action group using the pdadmin utility, log in to thedomain as a domain administrator and the action list command.

For example, to list the actions in the Test-Group action group, enter the followingcommand:pdadmin sec_master> action list Test-Group


Deleting actions from an action groupYou can delete an action from an action group using Web Portal Manager or thepdadmin utility.

Web Portal ManagerTo delete an action from an action group, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List Action Groups.3. From the Manage Action Group page, click the link for the action group name

that contains the permission to be deleted.4. From the Action Group Properties page, select the permission to delete.5. Click Delete.6. Confirm the deletion by clicking Delete on the Delete Action page.

pdadminTo delete an action from an action group using the pdadmin utility, log in to thedomain as a domain administrator and the action delete command.

For example, to delete the x action bit from the Test-Group action group, enter thefollowing command:


pdadmin sec_master> action delete x Test-Group



Chapter 9. Protected object policy management

While the access control list (ACL) policies provide the authorization service withinformation to make a yes or no answer on a request to access a protected objectand perform some operation on that object, a protected object policy (POP) containsadditional conditions on the request that are passed back to the resource manageralong with the yes ACL policy decision from the authorizations service. It is theresponsibility of Tivoli Access Manager and the resource manager to enforce thePOP conditions.

Table 3 lists the available attributes for a POP that are provided by Tivoli AccessManager.

Table 3. POP attributes that are enforced by Tivoli Access Manager

POP attribute Description

Name Specifies the name of the policy. This attribute relates tothe pop-name variable in the pop commanddocumentation.

Description Specifies the descriptive text for the policy. This attributeappears in the pop show command.

Warning mode Provides administrators a means to test ACLs, POPs, andauthorization rules. Warning mode provides a way totest the security policy before it is made active.

Audit level Specifies the type of auditing: all, none, successful access,denied access, or errors. Audit level informs theauthorizations service that extra services are requiredwhen permitting access to the object.

Time-of-day Access Day and time restrictions for successful access to theprotected object. Time-of-day places restrictions on theaccess to the object.

IP endpoint authorizationmethod policy

Specifies authorization requirements for access frommembers of external networks. The IP endpointauthentication method policy places restrictions on theaccess to the object.

EAS trigger attributes Specifies an External Authorization Service (EAS) plug-inthat is invoked to make an authorization decision usingthe externalized policy logic of the customer.

Quality of Protection Specifies the degree of data protection: none, integrity, orprivacy. Quality of Protections informs the authorizationsservice that extra services are required when permittingaccess to the object.

Although Tivoli Access Manager provides these POP attributes, it only enforces thefollowing attributes:v Namev Descriptionv Warning modev Audit levelv Time-of-day Access


Each resource manager or plug-in can optionally enforce one or more of thefollowing attributes:v IP endpoint authorization method policyv EAS trigger attributesv Quality of Protection

For Tivoli Access Manager IP address support:v You can grant access to a protected resource based on the IP address that is used

by the identity. For example, only users from IP address 9.18.n.n are allowed toaccess the protected resource.

v You can define that an additional authentication level is required to access thisprotected resource based on the IP address that is used by the identity. Thestep-up level authentication is described in “Configuring levels for step-upauthentication” on page 115 and the IBM Tivoli Access Manager for e-business:WebSEAL Administration Guide.

Managing protected object policiesYou create and configure a protected object policy (POP) and then attach the POPto objects in the protected object space. POPs are placed in the masterauthorization database on a per domain basis, which is controlled by the policyserver.

You can perform the following POP tasks:v “Creating a POP”v “Modifying a POP” on page 104v “Listing POPs” on page 105v “Viewing a POP” on page 105v “Cloning a POP” on page 106v “Importing POPs” on page 106v “Exporting all POPs” on page 107v “Export a single POP” on page 107v “Exporting multiple POPs” on page 107v “Attaching a POP to an object” on page 108v “Locating where a POP is attached” on page 109v “Detaching a POP from an object” on page 108v “Deleting a POP” on page 109


Note: There are no equivalent pdadmin commands for importing, exporting, orcloning POPs.

Creating a POPYou can create a POP using Web Portal Manager or the pdadmin utility. Aftercreating a POP, you can attach it to an object. For information about attaching aPOP, see “Attaching a POP to an object” on page 108.


Web Portal ManagerTo create a POP, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → Create POP to display the Create POP page.3. In the POP Name field, type the name for the POP. For example, type

poptest1.4. In the Description field, type a description of the POP.5. Select one or more check boxes for the appropriate audit levels. The audit

level is the level of auditing that applies when a resource, to which this POPis attached, is accessed. You can select more than one audit level. Thefollowing choices are available:

PermitAudits all requests on a protected object that result in successfulaccess.

Deny Audits all requests on a protected object that result in denial of access.

Error Audits all internally generated error messages resulting from a denialof access to the protected object.

AdminAudits not used by Tivoli Access Manager. However, this option canbe used by custom applications.

For more information, refer to “Setting an audit level” on page 1116. Select the Warn Only On Policy Violation check box to enable warning mode

attributes. A warning mode attribute indicates whether a policy violation thatis related to a resource results in denial of access or in an auditable failure. Anauditable failure is an access attempt to a resource, to which a POP applies,that results in the access being audited, not denied.For more information, refer to “Setting a warning mode” on page 111.

7. Select a type of Quality of Protection. The level of protection that applieswhen a resource, to which this POP is attached, is accessed. The followingchoices are available:

None Requires no Quality of Protection.

IntegrityUses some mechanism to ensure that the data has not changed.

PrivacyRequires data encryption for Secure Sockets Layer (SSL).

For more information, refer to “Setting a Quality of Protection level” on page114.

8. Optional: For Time of Day Access, specify the days and times of the day thatthe resource can be accessed.v Select the check boxes for the days of the week that the resource can be

accessed.v Select either All Day or Between hours of for the access times that the

resource can be accessed on the selected days.v If you select Between hours of, you must also specify the Start time and

End time.v If you select Between hours of, you must also specify the Local Time or

UTC Time (Coordinated Universal Time).For more information, refer to “Setting a time-of-day restriction” on page 112.

Chapter 9. Protected object policy management 103

9. Click Create or click Create Another if you want to create another POP.If successful, a message confirming that the POP was created is displayed.

10. If you clicked Create, click Done. Otherwise, repeat this procedure starting atstep 3 on page 103 to create another POP.

pdadminTo create a POP in the domain using the pdadmin utility, log in to the domain as adomain administrator and use the pop create command.

For example, to create a POP named poptest1, enter the following command:pdadmin sec_master> pop create poptest1

The new POP contains the following default settings:pdadmin sec_master> pop show poptest1

Protected object policy: poptest1Description:Warning: noAudit level: noneQuality of protection: noneTime of day access: sun, mon, tue, wed, thu, fri, sat:

anytime:localIP Endpoint Authentication Method Policy

Any Other Network 0


Modifying a POPYou can modify a POP using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo modify a POP, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → List POP to display the Manage POPs page.3. Click the link for the POP. For example, select poptest1 to display the POP

Properties page.4. Click the General tab to change the information pertaining to the POP, as

needed. For example, change the description from Test POP to Test 1 for POP,and then click Apply.

5. Click the Attach tab to change the protected object attachments.6. Click the IP Auth tab to change the IP authentication.7. Click the Extended Attributes tab to change an extended attribute.

pdadminTo modify a POP using the pdadmin utility, log in to the domain as a domainadministrator and use the pop modify commands. For example to enable thewarning mode and set the audit level to permit and deny for the poptest1 POP,enter the following commands:pdadmin sec_master> pop modify poptest1 set warning yespdadmin sec_master> pop modify poptest1 set audit-level permit,deny

To show these modifications, use the pop show commands. For example, to showthe modifications to the poptest1 POP, enter the following command:


pdadmin sec_master> pop show poptest1

Protected object policy: poptest1Description: Test 1 for POPWarning: yesAudit level: permit, denyQuality of protection: noneTime of day access: sun, mon, tue, wed, thu, fri, sat:


Any Other Network 0


Listing POPsYou can list all POPs using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo view a list of all POPs, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → List POP to display the Manage POPs page.

All the POPs for the domain are listed as links.

pdadminTo list all POPs in the domain using the pdadmin utility, log in to the domain as adomain administrator and use the pop list command.

For example, to list all POPs, enter the following command:pdadmin sec_master> pop list


Viewing a POPYou can view a POP using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo view a POP, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → List POP to display the Manage POPs page.3. Click the link for the POP. For example, select poptest1 to display the POP

Properties page.4. On the General tab, change the information pertaining to the POP, as needed.

For example, change the description from Test POP to Test 1 for POP, andthen click Apply.

5. Click the Attach tab to view the protected object attachments.6. Click the IP Auth tab to view the IP authentication.7. Click the Extended Attributes tab to view all extended attributes.

pdadminTo view a POP using the pdadmin utility, log in to the domain as a domainadministrator and use the pop show commands.


For example, to show the modifications to the POP name poptest1, enter thefollowing command:pdadmin sec_master> pop show poptest1

Protected object policy: poptest1Description: Test 1 for POPWarning: noAudit level: noneQuality of protection: noneTime of day access: sun, mon, tue, wed, thu, fri, sat:


Any Other Network 0


Cloning a POPYou can clone a POP using the Web Portal Manager only. To clone a POP in thedomain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → List POP.3. From the Manage POPs page, select the POP you want to clone.4. From the POP Properties page, click Clone.5. From the Clone POP page, in the POP Name text field, type the name of the

POP. For example, type Test-POP. The default value is the name of the originalPOP with the prefix Clone. This field is required.

6. Optional: In the Description text field, type the description of the POP. Forexample, type Clone of new POP. The default value is the description of theoriginal POP.

7. Click Clone.

If successful, a link for this cloned POP is created and a success message isdisplayed.

Importing POPsYou can import a POP by using Web Portal Manager only. To import a POP in thedomain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → Import POP.3. From the Import POP page, complete one of the following steps:

v In the POP File Name field, type the name of the POP to import. Forexample, type popImport.xml.

v Click Browse to select a file name.4. If the file containing the POP was encrypted when it was exported, in the

Encryption String text field, type the string that was used to encrypt the XMLfile.

5. Click Import.

If successful, the imported POP is available when you list all the POPs.


Exporting all POPsYou can export all POPs using Web Portal Manager only. To export all POPs in thedomain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → Export All POPs to display the Export POP to File page.3. Optional: In the Encryption String text field, type the string to use to encrypt


field, type the string again.5. Click Export to display the File Download window.6. Click Save to display the Save As window.7. Click Save to create the file that contains the exported POP description. The

default file name is popExport.xml.

If successful, the exported POP description is available in the specified location.

Export a single POPYou can export a single POP using Web Portal Manager only. To export a singlePOP in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → List POP.3. From the Manage POPs page, select the POP that you want to export.4. From the POP Properties page, click Export to display the Export POP to File

page.5. Optional: In the Encryption String text field, type the string to use to encrypt


field, type the string again.7. Click Export to display the File Download window.8. Click Save to display the Save As window.9. Click Save to create the file that contains the exported POP description. The

default file name is popExport.xml.

If successful, the new XML file is available in the specified location.

Exporting multiple POPsYou can export POPs using Web Portal Manager only. To export POPs in thedomain from a list, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → List POP.3. From the Manage POPs page, select the POPs that you want to export.4. Click Export to display the Export POP to File page.5. Optional: In the Encryption String text field, type the string to use to encrypt




9. Click Save to create the file that contains the exported POP descriptions. Thedefault file name is popExport.xml.


Attaching a POP to an objectYou can attach a POP to an object using Web Portal Manager or the pdadminutility.


Web Portal ManagerTo attach a POP to an object, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → List POP to display the Manage POPs page.3. Click the link for the POP.4. From the POP Properties page, click the Attach tab.5. Click Attach to display the Attach POP page.6. Type the Protected Object Path for the protected object to which to attach the

POP. Express the path as the full path name. For example, type/WebSEAL/serverA/index.html.

7. Click Attach.

If successful, the protected object is added to the list at the POP Properties–Attachpage.

pdadminTo attach a POP to a protected object in the domain by using the pdadmin utility,log in to the domain as a domain administrator and use the pop attach command.

For example, to attach a POP named poptest1 to a protected object named/WebSEAL/serverA/index.html enter the following command:pdadmin sec_master> pop attach /WebSEAL/serverA/index.html poptest1


Detaching a POP from an objectYou can detach a POP from a protected object using Web Portal Manager or thepdadmin utility.

To perform this task, the administrator requires the attach (a) permissions.

Web Portal ManagerTo detach a POP from a protected object, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Object Space → Browse to display the Browse Object Space page.3. Click the link for the POP.4. From the POP Properties page, click the Attach tab.5. Select one or more check boxes for the protected objects from which you want

to detach the POP.


6. Click Detach to display the Detach POP from Object page, where you areprompted to confirm or cancel the detachment.

pdadminTo detach a POP from a protected resource in the domain by using the pdadminutility, log in to the domain as a domain administrator and use the pop detachcommands.

For example, to detach the POP from the protected object named/WebSEAL/serverA/index.html, enter the following command:pdadmin sec_master> pop detach /WebSEAL/serverA/index.html


Locating where a POP is attachedYou can locate where a POP is attached using Web Portal Manager or the pdadminutility.

Web Portal ManagerTo locate where a POP is attached, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click ACL → List POP. A list of POP names is displayed. Each POP name is a

link that you can click to display the POP properties page.3. Click the Attach tab.

pdadminTo locate where a POP is attached in the domain using the pdadmin utility, log into the domain as a domain administrator and use the pop find command.

For example, to find where the POP named poptest1 is attached, enter thefollowing command:pdadmin sec_master> pop find poptest1

/WebSEAL/serverA/index.html


Deleting a POPYou can delete a POP using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo delete a POP, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click POP → List POP to display the Manage POPs page.3. Select one or more check boxes for the POPs that you want to delete.4. Click Delete to display the Delete Pop page.5. Click Delete to confirm the deletion.

pdadminTo delete a POP in the domain using the pdadmin utility, log in to the domain as adomain administrator and use the pop delete command.


For example, to delete the POP named poptest2, enter the following command:pdadmin sec_master> pop delete poptest2


Network-based authorization algorithmThe authorization server uses the following algorithm to process the conditions ina POP:1. Check ACL permissions.

Note: The ACL policy bypass (B) permission overrides POP authorizationconditions on an object. This permission must be used only by ahigh-level administrator who needs full access to the protected objectspace.

2. Verify whether a rule is attached to the object, then verify that all the accessdecision information (ADI) is present for the coming rule evaluation. If it is not,then find it by querying one of the available sources.

3. Check the IP endpoint authentication method policy on the POP.4. Check the time-of-day policy on the POP.5. Check the audit level policy on the POP.6. Check the authorization rule policy if a rule is attached to the object.7. If an external authorization service (EAS) operation or POP trigger applies to

this access decision, then invoke the EAS that applies.

Network-based authorization policyThe network-based authorization policy allows you to control access to objectsbased on the IP address of the user. When an environment contains both IP version4 (IPv4) and IP version 6 (IPv6) address formats, be aware of the followingrestrictions:v For administration commands (for example, pop modify set ipauth), IPv4 clients

must provide addresses in IPv4 format even with IPv6 servers.v For C APIs, IPv4 clients must provide addresses in IPv4 format even with IPv6

servers.v For C APIs, IPv6 clients can provide addresses in IPv4 or IPv6 format to IPv6

servers.v For Java methods, both IPv4 and IPv6 clients must provide addresses in IPv4

format to IPv4 servers.v For Java methods, IPv4 clients can provide addresses in IPv4 or IPv6 format to

IPv6 servers.

For an IPv6 address to be accepted (commands, C APIs, and Java methods), theserver must be IPv6. You cannot provide an IPv6 address to an IPv4 server.

This authorization policy uses the IP endpoint authentication method policy POPattribute. You can use this functionality to prevent specific IP addresses or IPaddress ranges from accessing any resources in your domain. When setting anauthorization policy, you can apply requisite step-up configuration.


The network-based authorization policy is set in the IP endpoint authenticationmethod attribute of a POP. When you define a network-based authenticationpolicy, specify the two parts for the attribute:v Step-up authenticationv Allowed networks

You can also apply step-up authentication configuration to this policy and requirea specific authentication method for each specified IP address range. For moreinformation about authentication levels, see “Step-up authentication” on page 114.

Note: The IP address used by the resource manager for enforcing thenetwork-based authorization policy must be the IP address of the originatorof the connection. If your network topology uses proxies, the address thatappears to the resource manager might be the IP address of the policy proxyserver.

In this case, the resource manager cannot definitively identify the true IPaddress of the client. When setting a network-based authorization policythat depends on specific client IP addresses, ensure that those networkclients are connecting directly to the resource manager.

Configuring POP attributesPOP attributes impose access conditions on an object based on the time of theaccess and to indicate whether the access request must be audited.

Setting a warning modeThe pop modify set warning command defines the warning mode attribute toallow a security administrator to debug or troubleshoot the accuracy of theauthorization policy set on the protected object space.

When you set the warning mode attribute to yes, any action is possible by anyuser on the object where the POP is attached. Any access to an object is permittedeven if the security policy that is attached to the object is set to deny this access.

Audit records are generated that capture the results of all security policies withwarning mode set throughout the object space. The audit log shows the outcomeof an authorization decision as if the warning attribute was set to no. Therefore, theadministrator can determine if the policy is set and enforced correctly.

For example:pdadmin sec_master> pop modify poptest1 set warning yes

For more information about the pop commands, see IBM Tivoli Access Manager fore-business: Command Reference.

Setting an audit levelThe pop modify set audit-level command specifies the granularity level ofauditing for a POP. For example, if auditing is set to record unsuccessful events,you can use the results to detect an unusual number of failed access attempts on aparticular resource.


Auditing records are written in a standard Extensible Markup Language (XML)format that allows easy parsing to extract whatever information is required. Forexample:pdadmin sec_master> pop modify pop_name set audit-level permit,deny

Table 4. Audit levels

Value Description

permit Audit all requests on a protected object that result in successful access.

deny Audit all requests on a protected object that result in denial of access.

error Audit all internally generated error messages resulting from a denial ofaccess to the protected object.

You can apply any combination of these values or specify either all to audit allrequests or none to audit no requests. When enabling granular auditing, specifyone or more of the following values:v permitv denyv error

When you specify multiple granular values, use a comma as a separator characterbetween these values.

For more information about the pop commands, see IBM Tivoli Access Manager fore-business: Command Reference.

Setting a time-of-day restrictionThe pop modify set tod-access command defines the time-of-day (TOD) attributethat allows you to place specific day and time conditions on the access to aprotected object. This type of condition might be useful to limit access toinformation that regularly requires periods of inactivity for modification andupdates.pdadmin sec_master> pop modify pop_name set tod-accesstime_of_day_string

The time-of-day-string argument includes a day-range and a time-range and usesthe following format:{anyday|weekday|day_list}:{anytime|time_spec-time_spec}[:{utc|local}]

The day_list variable can be any combination of the following values:mon, tue, wed, thu, fri, sat, sun

The time_spec range variable must be expressed (using 24 hour time) in thefollowing format:hhmm-hhmm

For example, you can specify the time range using the following string:0700-1945

The optional time zone [:{utc|local}] for the server (not the client) is local bydefault.


For example to change the time-of-day attribute to Monday, Tuesday, and Fridayfrom 1:15 p.m. to 5:30 p.m. local time for the POP named poptest1, enter thefollowing command:pdadmin sec_master> pop modify poptest1 set tod-access mon,tue,fri:1315-1730

For more information about the pop modify commands, see IBM Tivoli AccessManager for e-business: Command Reference.

Specifying IP addresses and rangesThe pop modify set ipauth command allows the specification of a network (ornetwork range) and the required authentication level in the POP. The network (ornetwork range) can be an IP version 4 (IPv4) or an IP version 6 (IPv6) address.

Note: When adding addresses to a POP, IPv4 addresses must be specified in IPv4format, due to limitations in the operating system functions provided toTivoli Access Manager.

All POPs have an anyothernw (any other network) IP entry whose defaultauthentication level is 0. The anyothernw entry applies to all networks notspecified in the POP. Authentication level 0 adds no additional requirement forauthentication. The anyothernw authentication level can be modified to a non-zeronumber or to forbidden.

The anyothernw entry appears in a POP as Any Other Network in the output of thepop show command:pdadmin sec_master> pop show poptest1

Protected object policy: poptest1Description: Test POPWarning: noAudit level: noneQuality of protection: noneTime of day access: sun, mon, tue, wed, thu, fri, sat:


Any Other Network 0

For more information about setting the IP authentication mechanism using the popmodify command, see the IBM Tivoli Access Manager for e-business: CommandReference.

Adding IP entriesTo add IP entries to a POP, specify network (or network range) with anauthentication level as a number or as forbidden. Specifying an authenticationlevel of 0 indicates that authentication is allowed. A forbidden authentication levelindicates that authentication is denied. Specifying an authentication greater than 0provides the ability to step-up a user to an authentication level. The enforcement ofstep-up authentication is the responsibility of resource managers. For moreinformation about step-up authentication, see “Step-up authentication” on page114.

Note: When adding addresses to a POP, IPv4 addresses must be specified in IPv4format, due to limitations in the operating system functions provided toTivoli Access Manager.

The following example adds an IP entry for identities from IPv4 addresses thatbegin with 9.


pdadmin sec_master> pop modify poptest1 set ipauth add 9.0.0.0 255.0.0.0 5

The following example adds an entry for an IPv6 network range:pdadmin sec_master> pop modify poptest1 set ipauth add \

fedc:ba98:7654:3210:fedc:ba98:7654:3210 ffff:ffff:ffff:ffff:ffff:ffff:ffff:0 6

The following example prevents all users (except users specified like in theexamples above) from accessing the object:pdadmin sec_master> pop modify poptest1 set ipauth anyothernw forbidden

For more information about adding IP entries to a POP using the pop modifycommand, see the IBM Tivoli Access Manager for e-business: Command Reference.

Deleting IP entriesThe following example deletes an IPv4 entry from the poptest1 POP:pdadmin sec_master> pop modify poptest1 set ipauth remove 9.0.0.0 255.0.0.0

Only network entries that were previously added can be removed. For moreinformation about removing IP entries from a POP using the pop modifycommand, see the IBM Tivoli Access Manager for e-business: Command Reference.

Setting a Quality of Protection levelThe Quality of Protection POP attribute allows you to specify what level of dataprotection is required when performing an operation on an object.

The Quality of Protection POP attribute permits a single transaction where the yesresponse to the ACL decision also includes the required Quality of Protection level.If the resource manager cannot guarantee the required level of protection, therequest is denied.

Use the following pop modify command syntax to modify the QoP level for anobject:pdadmin sec_master> pop modify pop-name set qop {none|integrity|privacy}

QoP level Description

privacy Data encryption is required for Secure Sockets Layer (SSL).

integrity Use some mechanism to ensure that the data has not changed.

For example, to modify the POP named poptest1 to set the Quality of Protectionlevel to use SSL data encryption, enter the following command:pdadmin sec_master> pop modify poptest1 set qop privacy

Step-up authenticationYou can use protected object policies (POPs) to enforce certain access conditions onspecific resources. The authentication strength policy makes it possible to controlaccess to objects based on authentication method.

You can use this functionality, sometimes known as step-up authentication, toensure that users accessing more sensitive resources use a stronger authenticationmechanism. You might want this condition because of the greater threat ofimproper access to certain resources.


For example, you can provide greater security to a junctioned region of theprotected object space by applying a step-up POP policy that requires a strongerlevel of authentication than the client used when initially entering the domain.

The authentication strength policy is set in the IP endpoint authentication methodattribute of a POP policy.

Configuring levels for step-up authenticationThe first step in configuring authentication-specific access is to configure thesupported authentication methods and determine the order in which theseauthentication methods must be considered stronger.

Any client accessing a resource manager has an authentication level, such as“unauthenticated” or “password”, which indicates the method with which theclient was last authenticated by the resource manager.

In some situations, it might be necessary to enforce minimum safe levels ofauthentication required to access certain resources. For example, in oneenvironment, authentication by token pass code might be considered more securethan authentication by user name and password. Another environment mightrequire different standards.

Rather than forcing clients to restart their sessions with the resource manager whenthey do not meet the required level of authentication, the step-up authenticationmechanism provides clients a second chance to authenticate using the requiredmethod of authentication (level).

Step-up authentication allows resource managers to control how users accessprotected resources. If step-up authentication is required because the user has notauthenticated with the sufficient method, the access decision is still permitted bythe authorization engine but the resource manager is presented with a requiredauthentication level as an output of the authorization decision. The resourcemanager can then decide how to further authenticate the user to gain the requiredlevel of authentication needed for the user to access the protected object.

How a particular authentication method is mapped to an authentication level isdetermined by the resource manager application. For all cases, the absoluteminimum acceptable method of authentication must be set as level 0 with moresecure methods being mapped to integral numbers in ascending order (1..x) fromthat point forward.

Applying step-up authentication policyStep-up authentication is implemented through a POP policy placed on the objectsrequiring authentication-sensitive authorization. You use the IP endpointauthentication method attribute of a POP policy.

The pop modify set ipauth command specifies both the allowed networks and therequired authentication level in the IP endpoint authentication method attribute.

Note: When specifying an IPv4 address it must be in IPv4 format.

The configured authentication levels can be linked to IP address ranges. Thismethod is intended to provide management flexibility. If filtering users by IPaddress is not important, you can set a single entry for anyothernw (any othernetwork). This setting affects all accessing users, regardless of IP address, and


requires the users to authenticate at the specified level. This method is the mostcommon method for implementing step-up authentication.

The anyothernw entry is used as a network range that matches any network nototherwise specified in the POP. This method can be used to create a default entrythat could either deny all unmatched IP addresses or allow anyone access who canmeet the authentication level requirement.

By default, anyothernw appears in a POP with an authentication level index of 0.The entry appears as Any Other Network in the output of the pop show command.The following output shows a sample for the poptest1 POP:pdadmin sec_master> pop show poptest1

Protected object policy: poptest1Description: Test POPWarning: noAudit level: noneQuality of protection: noneTime of day access: sun, mon, tue, wed, thu, fri, sat:


Any Other Network 0

For more information about the pop modify set ipauth command, see the IBMTivoli Access Manager for e-business: Command Reference.

Distinguishing step-up from multi-factor authenticationTivoli Access Manager step-up authentication and multi-factor authentication aretwo different mechanisms for controlling access to resources. Tivoli AccessManager provides only step-up authentication functionality.

Multi-factor authentication forces a user to authenticate using two or more levelsof authentication. For example, the access control on a protected resource canrequire the user to authenticate with both user name and password (level 1) andalso require the user to authenticate with user name and token passcode (level 2).

Tivoli Access Manager step-up authentication relies on a pre-configured hierarchyof authentication levels and enforces a specific level of authentication according tothe policy set on a resource. Step-up authentication does not force the user toauthenticate using multiple levels of authentication to access any given resource.Instead, step-up authentication requires the user to authenticate at a level at leastas high as the level required by the policy protecting the resource.

The following example shows the series of commands that are needed to definestep-up authentication:pdadmin > pop create test1pdadmin > pop modify test1 set ipauth anyothernw 1pdadmin > pop attach /WebSEAL/hostA/junction test1

pdadmin > pop create test2pdadmin > pop modify test2 set ipauth anyothernw 2pdadmin > pop attach /WebSEAL/hostA/junction/applicationA test2

In the previous example, the /WebSEAL/hostA/junction object is protected by aPOP requiring authentication level 1, and the /WebSEAL/hostA/junction/applicationA object is protected by a POP requiring authentication level 2.


Under step-up authentication, user name/password (level 1) authentication isrequired to access /WebSEAL/hostA/junction.

However, user name/token passcode (level 2) authentication is required to access/WebSEAL/hostA/junction/applicationA. If the user is currently logged in with auser name and password, a prompt appears requesting user name and tokenpasscode information (the step-up). However, if the user initially logged in toWebSEAL using a user name and a token passcode, access to applicationA isimmediate (assuming a successful ACL check).

Multi-factor authentication requires both level 1 and level 2 authentication foraccess to applicationA.


Chapter 10. Authorization rules management

This chapter provides information about Tivoli Access Manager authorizationrules. Authorization rules are conditions contained in an authorization policy thatare used to make access decisions based on attributes such as user, application, andenvironment context.

This chapter contains the following sections:v “Authorization rules overview”v “Access decision information”v “Authorization rule language” on page 122v “Authorization rules evaluator” on page 128v “Examples of authorization rules” on page 131v “Methods of providing ADI to the rules evaluator” on page 133v “Reason codes for rule failures” on page 135v “Configuration file and initialization attributes” on page 135v “Managing authorization rules” on page 137

Authorization rules overviewAuthorization rules are defined to specify conditions that must be met beforeaccess to a protected object is permitted. A rule is created using a number ofBoolean conditions that are based on data supplied to the authorization enginewithin the user credential, from the resource manager application, or from theencompassing business environment. The language of an authorization rule allowscustomers to work with complex, structured data by examining the values in thatdata, and making informed access decisions. This information can be definedstatically within the system or can be defined during a business process. Rules canalso be used to implement extensible, attribute-based, authorization policy byusing attributes within the business environment or attributes from trusted externalsources.

A Tivoli Access Manager authorization rule is a policy type like an access controllist (ACL) or a protected object policy (POP). The rule is stored as a text rulewithin a rule policy object and is attached to a protected object in the same wayand with similar constraints as ACLs and POPs.

Access decision informationThe data and attributes that are used in rule conditions collectively are called accessdecision information (ADI). Authorization API attributes, which are name and valuepairs, form the basis of all ADI that can be referenced in a rule or presented to theauthorization engine.

Sources for retrieving ADIThe authorization engine can gather ADI from the following sources:v User credential entitlementsv Application context information passed in by the Tivoli Access Manager resource

manager


v Tivoli Access Manager authorization engine contextv Dynamic ADI retrieval entitlement services

User credential entitlementsAdditional entitlements data can be inserted as attribute name-value pairs into theclient credential by a Tivoli Access Manager authorization client during the userauthentication process or at any time during the process of the transaction. Forexample, Tivoli Access Manager can be configured to gather entitlements at thetime that a user is authenticated. You can configure entitlement services to runduring credential acquisition, collect entitlements data, and then append the datato the credential. Tivoli Access Manager provides a credential attributes entitlementservice that retrieves entitlements data from the user registry. Or, you can defineyour own entitlement services. For more information about defining entitlementservices, refer to IBM Tivoli Access Manager for e-business: Authorization C APIDeveloper Reference.

Any attribute added to the user credential can be used as ADI in a rule definition.There are also attributes that are built into the Tivoli Access Manager usercredential when it is created by the authorization engine. Just like attributes thatcan be added to the credential by the resource manager, the built-in credentialattributes can be used in authorization rules. The built-in credential attributesinclude items of information, such as the user name (or the principal UUID) andthe groups (or the group UUID) of which the user is a member.

See the IBM Tivoli Access Manager for e-business: Authorization C API DeveloperReference for a table of valid credential attribute names. All credential attributenames begin with azn_cred_ (for example, azn_cred_principal_uuid). This tablelists attribute names available within the Tivoli Access Manager authenticated usercredential, their value, and a description. Many attributes in this table are alsoavailable in an unauthenticated user credential, except attributes related to a theidentity of a user. For example, attributes such as the user name, principal UUID,group name, and group UUID, as well as the LDAP DN for LDAP configurationsare not available in an unauthenticated credential. When developing rules that usethese particular attributes, the authorization engine requires all ADI to be presentbefore a rule can be evaluated. If the ADI is not available, the authorizationdecision is returned with an error status. Requiring the user to authenticate beforeaccessing the protected object with such a rule attached ensures that theauthenticated credential information is available. This requirement can be achievedusing an ACL entry on the object that requires authenticated access.

Application context informationAuthorization rules might require application context information to complete anevaluation. Context information includes information that is not an entitlement butis specific to the current transaction or operation. An example is a transactionamount, such as purchase price or transfer amount. This information is passed tothe decision through the app_context attribute list of theazn_decision_access_allowed_ext() call. Tivoli Access Manager WebSEAL alsouses this mechanism to pass the values of certain HTML tags and HTML requestdata (from a get or post request) into the access decision for use in a ruleevaluation.

Authorization engine context informationAuthorization engine context information is provided automatically by theauthorization engine, if required, before the authorization rule is evaluated. TheADI provided by the authorization engine includes the name of the protected


object that is the target of the access decision and the string of operations that therequesting user wants to perform on the protected object.

The following attribute names are reserved for these data items:v azn_engine_target_resourcev azn_engine_requested_actions

Dynamic ADI retrieval entitlement servicesThe final source for retrieving ADI is the dynamic ADI retrieval entitlementsservice. This class of authorization entitlement services is designed to retrieve ADIfrom an external source. These services can be developed to retrieve ADI from anenterprise database containing employee, customer, partner, or inventoryinformation. The dynamic ADI retrieval service is called to retrieve ADI when theaccess decision is being made. Calling both at the same time has the benefit ofbeing able to retrieve volatile data, such as quotas, at a time when its value is mostcurrent.

The Tivoli Access Manager Attribute Retrieval Service (AMWebARS) is an exampleof a service that can retrieve ADI from external sources. AMWebARS is the officialpackage name for a Tivoli Access Manager J2EE Web service that implements adynamic ADI retrieval service. To facilitate communication between the resourcemanager, which is invoking the rules engine, and AMWebARS, which is performedusing SOAP over HTTP, the Access Manager runtime environment (pdrte package)provides an authorization entitlement service called azn_ent_amwebars.

See the IBM Tivoli Access Manager for e-business: Authorization C API DeveloperReference for more information about developing and using dynamic ADI retrievalentitlement services to fetch ADI when the rule is evaluated. See the IBM TivoliAccess Manager for e-business: Administration C API Developer Reference for anin-depth discussion of attribute lists, their formats, and of the authorization APIsthat are used to manipulate them. For more information about the constraints andformat for ADI, refer to “Format and constraints of rules” on page 129.

Volatile versus nonvolatile dataIn general, the source for any particular piece of ADI depends largely on what thedata is. The most important question is whether the data is volatile. For example,is it possible for the data to change during the lifetime of the session of the userand, if so, is it important to use the most up-to-date information when it does?Volatile data must be retrieved using a dynamic ADI retrieval service unless theresource manager application can provide this data.

Application-specific data that is nonvolatile and not user-specific is provided bythe resource manager application. Data that is nonvolatile and user-specific isloaded into the user credential when the user is authenticated and is kept with thecredential for the lifetime of the user session.

The set of data provided by the authorization engine, including the targetprotected object and permissions, is fixed and cannot be changed.

Chapter 10. Authorization rules management 121

Authorization rule languageExtensible Style Language (XSL) is the language used to specify rules andExtensible Markup Language (XML) is the language used for the data that formsan input to the rules. The combination of XML and XSL provides a platformindependent way to express both the inputs to the rules evaluator and the rulesthemselves.

XML also provides the ability to express complex data types in a structured andstandard manner in text format. This text format allows rules for processing theXML data to be written without having to cater to platform and programminglanguage specifics.

XSL is a functional stylesheet language that can be used to perform simple tasks orcomplex tasks depending on your needs. XSL possesses an inherent ability toanalyze and evaluate XML data, which is becoming the standard for datarepresentation in e-business models. XSL is built on other XML-based standardssuch as XPath, which is the expression language at the core of an authorizationrule.

To implement rules-based authorization policy, it is necessary to impose a numberof constraints on the XSL rules, including the requirements that the output of therule evaluation are simple text and that the output conforms to one of a known setof result strings. For more information about the format and constraints ofauthorization rules, see “Format and constraints of rules” on page 129.

It is also necessary to impose constraints on the XML input document that is builtas input to the rule evaluation. The ADI XML document model enables theauthorization engine to detect when ADI is missing and when it needs to berequested from the resource manager or an external entity through the dynamicADI retrieval service interface.

ADI XML document modelThe ADI XML document model (or ADI XML model) is a set of restrictions placedon the XSL/XML model by the authorization rules implementation to enable theinterface to be simple and yet functional for authorization purposes. The modelconstrains the authorization rules to function within a predetermined XMLdocument format with the same top-level XML document element for all rules. TheXML ADI that is imported by the rules evaluator from credential attributes, fromapplication context, or from other data sources must be inserted into this XMLdocument before authorization rules can use the data. Similarly to simplify theprocess of defining rules, the authorization rules must operate within the confinesof the ADI XML model. The ADI XML model requires the XML document tocontain the following top-level XML element into which all target ADI for aparticular rule evaluation is inserted. The XMLADI element is created automaticallyas part of the rule evaluation process by the authorization engine.<XMLADI></XMLADI>

As a result of this restriction, the XPath to the data used in an authorization rulemust include the prefix /XMLADI to access a particular data element within themodel. For example, if an ADI item of JohnSmith is added to the document toaccess the fields of JohnSmith within the ADI XML document, you have to specifythe XPath /XMLADI/JohnSmith to access the data contained in the XML objectJohnSmith.

An XPath is the path to a particular child element within the hierarchy of astructured XML data object. Much like a directory path on a hard disk drive isused to access a specific file, an XPath designation starts from the root of thedocument (in this case /XMLADI) and traces a path from this root down through itschild elements to the specific element that is being referenced. For example, usingthe example entitlement JohnSmith in the “XML entitlement example” on page 125as a reference, the JohnSmith XML object has a child element called CreditCard.The child elements of the CreditCard element are attributes which are common tomost credit cards. To access Balance under the CreditCard element of JohnSmith,you would use the following XPath:"/XMLADI/JohnSmith/CreditCard/Balance"

XPaths like this example are the means by which authorization rules access theADI data values that are needed to make attribute-based authorization decisions.

All data elements are restricted to work within the ADI XML model. So theauthorization rules must also be restricted to operate on or match XPaths withinthe model. Therefore, XSL template match statements are also restricted tomatching XPaths starting from /XMLADI within the ADI XML document. Foradditional information, see “Format and constraints of rules” on page 129.

Containers and XML ADI container namesWhen data is requested from a resource manager, the granularity of the XML datareturned is at the level of a single container of information. The container isnormally also the smallest data element (for example, elements that might beconsidered for billing purposes). This convention was adopted for the ADI XMLmodel as well. The ADI that is used in authorization rules is also defined andmanipulated as containers of XML data. For example, the JohnSmith XML objectdefined in “XML entitlement example” on page 125 is an example of an ADIcontainer.

To this end, the top-most element in the definition of an item of ADI is referred toas the container name of that item of ADI. When defining an authorization rule, theXPath to the XML definition of data in any ADI container must always bereferenced using the name of the container as the first element /XMLADI in theXPath specification for the data element.

Returning to the example ADI item JohnSmith, you can assume there is a containerreceived from the data provider named JohnSmith. To access any element withinthe JohnSmith container, the XPath specification must be prefixed with JohnSmith.For example, JohnSmith/CreditCard/AcctNumber refers to the AcctNumber value. Toaccess this information from within an authorization rule, this XPath must also beprefixed by the top-level element of the XML target ADI input document, which isXMLADI (for example, /XMLADI/JohnSmith/CreditCard/AcctNumber). However, bothof these XPaths are valid when used in an authorization rule due to the defaulttemplate match statement that is added to all authorization rules that do notexplicitly include one. The default template match statement matches the ADI XMLdocument from /XMLADI. So JohnSmith can be referred to either with a relativereference or with an absolute reference that is prefixed with /XMLADI. For additionalinformation, see “Format and constraints of rules” on page 129.

Limitations of container namesOne restriction imposed by the ADI XML document model is that each item ofADI that can be consumed by the rules evaluator must have a unique containername that cannot be confused with containers provided by other entitlements dataproviders. For example, if two different data providers provide a data item called


TxInfo, there is no way for the rules evaluator to know which provider it mustmake a request to in order to get this item of data. To help differentiate items ofADI with the same name, XML provides the ability to define namespaces for data.The namespace ID of the namespace can then be used to differentiate one ADIelement from another. For TxInfo, we could define a namespace companyA andreference this instance of ADI with companyA:TxInfo. For more information aboutnamespace definitions, see “Defining an XML namespace” on page 126.

This restriction on container naming among data providers is not enforced by theauthorization engine. On the contrary, if the engine encounters multiple instancesof the same item of ADI (for example, TxInfo), it adds them all to the ADI XMLdocument for use in the evaluation. In the ADI XML document, there can be twoitems of ADI data with the same container name within the ADI XML inputdocument. The assumption is then made that they are structured in the exact sameway. For example, a particular application request might involve a number ofindividual transactions each with its own transaction amount. An authorizationrule can be formulated to add all these items together and compare the sum of theitems to a predefined total transactions limit or to a per-transaction limit using anXSL node select statement. “Example: ADI from dynamic ADI retrieval services”on page 132 in the “Examples of authorization rules” on page 131 section in thischapter shows an example rule that sums multiple transaction elements in this wayand even counts the number of instances of a particular ADI element.

XML access decision informationBy default, the rule evaluator automatically transforms into XML format anyname/value pair attributes passed to it by the calling application that wereidentified as target access decision information (ADI) for the current evaluation.When transforming the attribute to XML, the attribute name is used as thecontainer name of the XML data item and the attribute value is converted into anXML value. The container name of an item of ADI equates to the XML elementname in the XML definition. For example, the following XML data is generated forattribute name VPS_CREDIT_CARD with a string attribute value of 5517 3394 83240965:<VPS_CREDIT_CARD>5517 3394 8324 0965</VPS_CREDIT_CARD>

The container name and XML element name in this case is VPS_CREDIT_CARD. Thegraphical user interface, the command-line interface, and the Tivoli AccessManager authorization API attribute list interfaces do not permit the administratorto define rules that contain invalid XML container names.

If the application passes entitlements or application context that have already beenformatted as XML for an access decision, the authorization rules evaluator expectsthe data to be of type azn_string_t and expects the format of the string to beXML. The attribute name must match the container name of the XML data item. Ifthe names do not match, the evaluator does not evaluate the rule correctly.

The evaluator identifies XML format data by locating the less than (<) character atthe beginning of the attribute value. If the attribute value does not begin with aless than character, the data is not considered to be an XML data item and theevaluator attempts to convert the data item to XML format automatically. Thismeans of identification is used only on attributes or application context identifiedas target ADI for the access decision. Therefore, non-XML attribute values startingwith a less than character cannot be used by the application and results in an errorstatus that is returned from the authorization decision. If the data is not correctXML, the XSL processor fails and returns an error to denote the failure.


Data items that must be defined in XML must be entirely defined in XML andmust not rely on the translation mechanism for non-XML items to generate theappropriate XML element name automatically. For example, to define an attributeto contain the XML definition of MY_CREDIT_CARD_NUM, you must add an attributewith the attribute name MY_CREDIT_CARD_NUM. The attribute value forMY_CREDIT_CARD_NUM is the following:<MY_CREDIT_CARD_NUM>5517 3394 8324 0965</MY_CREDIT_CARD_NUM>

By defining the XML element as opposed to only defining its value, XML attributescan be added to the element definition without affecting the name by which theADI is referred to when talking with data providers.

In the following definition of the XML item MY_CREDIT_CARD_NUM, the CardTypeXML attribute has the value of "visa". XML attributes are defined in the elementstart tag of the element to which they apply. XML attributes are equivalent to anyother first-level child element of the XML object. To reference the attributeCardType, the required XPath would be:/XMLADI/MY_CREDIT_CARD_NUM/CardType

XML attributes must not be confused with the authorization API attributes andattribute lists that are used to carry data into and out of the authorization process.<MY_CREDIT_CARD_NUM CardType="visa">

5517 3394 8324 0965</MY_CREDIT_CARD_NUM>

The ability to add XML attributes to an element definition is useful when it comesto defining a namespace for the data item. For more information about XMLnamespaces, see “Defining an XML namespace” on page 126.

If the ADI attribute contains multiple attribute values (string, XML, or anycombination), the evaluator converts each attribute value as a separate instance ofADI. For example, the TxData attribute has values of 100 and 500. The evaluatorinserts the following XML item declarations into the ADI XML document:<TxData>100</TxData><TxData>500</TxData>

The policy administrator can then design an authorization rule that uses XSLlanguage node selection statements to work with these two values independentlyor to add the values and compare the sum total with some predefined limit. IfTxData is compared to a value, it is treated as a node set comparison where eachTxData value is compared to the data in turn with success being indicated if any ofthe TxData values equal the target data. Node set comparisons have slightlydifferent behavior than expected when using the != operator. In most cases, use thenot() function instead. For information about when to use != and not() whencomparing a node set, see “Example: ADI from dynamic ADI retrieval services” onpage 132.

XML entitlement exampleThe following example is an ADI XML document that might be passed to the XSLprocessor from the rules evaluator during the evaluation of an authorization rule.

The document contains two containers: JohnSmith and AmountReqd. The attributevalue of the container JohnSmith is defined in XML. The AmountReqd container istranslated to XML from an incoming string application context attribute. Thecontainer JohnSmith is an entitlement and the container AmountReqd is an item oftransaction context.


The authorization rules evaluator automatically encompasses all the data under theXML top-level node declaration XMLADI when the ADI XML document is created, sothis top-level element was added for clarity.

The XML document that is passed to the evaluation routines by the authorizationrules evaluator is as follows:<XMLADI>

<JohnSmith><CreditCard>

<AcctNumber>0123456776543210</AcctNumber><Limit>10000.00</Limit><Balance>2000.00</Balance>

</CreditCard><MileagePlus>

<MemberStatus>100k</MemberStatus><CardNumber>12345678</CardNumber>

<MileagePlus><JohnSmith><AmountReqd>500.00</AmountReqd>

</XMLADI>

When referencing a particular ADI item within the XMLADI document available toa rule, the XPath path specifier can begin from the container name of the XMLelement, for example, JohnSmith, as the default template rule matches the /XMLADIelement automatically. If the callers want to specify their own template matchstatement explicitly, they can do so.

In this example, the ADI container names are JohnSmith and AmountReqd. Foradditional information, see “Format and constraints of rules” on page 129.

Defining an XML namespaceXML namespaces are used to differentiate between XML items with the same nameor are used to group XML data of the same type or function. The same principlescan be used with ADI that is defined for use with authorization rules. For example,a customer database and a product inventory database might both define ADIcalled name that could be used in authorization rules. By defining an XMLnamespace with the namespace ID item, you can differentiate between the twoinstances of name by calling the ADI from the product database item:name. Thisexample provides a namespace definition for the item namespace:xmlns:item="http://mycompany/namespaces/items

where xmlns is a standard XML attribute name and item is the namespace IDchosen for the namespace. The URI following the = is used to distinguish onenamespace ID from another.

This namespace declaration associates the namespace ID item with the URI string:http://mycompany/namespaces/items

The value of the URI string is of no consequence to the XML and XSL processorsbut it must be unique. Unlike the XML and XSL processors, the Tivoli AccessManager authorization engine does not permit two namespace IDs to be assignedthe same URI value. The Tivoli Access Manager authorization engine uses the URIto uniquely identify the namespaces. Defining two namespaces with the same URIresults in an initialization error. The authorization application cannot start, and anerror is logged to the error log of the application. The source from which the itemname is to be obtained must be aware of this relationship. The source must be ableto make the connection between the item:name requested by the authorization


engine and the name data stored in the product database. The source must also beable to provide this data to the authorization engine in an attribute calleditem:name when it is needed. For example, a dynamic ADI retrieval service mustunderstand that, when it is asked for item:name, it must fetch the required valueby looking for name in the product database. The service needs to return the datato the authorization engine in an attribute called item:name. When an applicationuses namespaces to differentiate or aggregate ADI items, it is required to define thenamespace for both the XML and XSL processors.

To define a namespace for the XSL processor, add the namespace definition to thexsl-stylesheet-prolog configuration file entry discussed in “input-adi-xml-prologand xsl-stylesheet-prolog” on page 136. This is an example of how to add anamespace definition for the item namespace to the xsl-stylesheet-prolog entry:xsl-stylesheet-prolog = <?xml version=’1.0’ encoding=’UTF-8’?><xsl:stylesheet xmlns:xsl=’http://www.w3.org/1999/XSL/Transform’

xmlns:item="http://mycompany/namespaces/items" version=’1.0’><xsl:output method = ’text’ omit-xml-declaration=’yes’

encoding=’UTF-8’ indent=’no’/><xsl:template match=’text()’></xsl:template>

There are two ways to define a namespace prefix to the XML processor:v Define the namespace globally for the entire XMLADI document.v Define it individually within those ADI items that use the prefix.

In both cases, the namespace declaration must be included in the start tag for theXML element.

The first and simplest method of defining a namespace for the XML processor is toadd the namespace definition to the XMLADI document element start tag. Addingthe definition to the XMLADI document element start tag is easiest to do becauseit automatically defines the namespace for the entire document. Therefore, any ADIitems in the document whose names are prefixed with this namespace ID do nothave to have the namespace definition added to their own element start tag. Thismethod does not suffer any of the drawbacks of defining the namespace by usingthe second method. The [xmladi-attribute-definitions] stanza was added to theconfiguration file to allow customers to define namespaces globally for use withinthe XMLADI document. For information about how to add a namespace definitionto the [xmladi-attribute-definitions] stanza, refer to“[xmladi-attribute-definitions]” on page 137.

The second method of specifying an XML namespace definition to the XMLprocessor is to add the definition to the XML value of the ADI element. Forexample, to add the XML namespace definition to the item:name XML item with astring value of Widget A, you would define item:name in XML as follows:<item:name xmlns:item="http://mycompany/namespaces/items">

Widget A</item:name>

The ADI item:name must be added to an attribute list with the item:name attributename and its value is the entire XML element definition in the example entered asa single contiguous text string. There are some drawbacks to defining the XMLnamespace within the XML definition of each ADI item rather than defining itglobally for the entire XMLADI document. For instance, the value of any ADIitems that use a namespace ID prefix must be in XML because the namespacedefinition can only be added to the XML definition of the value of the item, as


demonstrated for item:name in the example. As a result, items of ADI withnamespace prefixes cannot simply have the value 100. The value of the item mustbe an XML fragment, such as the string <prefix:adi_name>100</prefix:adi_name>.

Also, any ADI source that can provide values for namespace prefixed ADI itemswould need to ensure that the appropriate namespace definitions for the item areadded to each XML formatted value that it returns. When the service does notnormally return XML formatted data and is not aware of namespace prefixes, itmust be changed so that it does, which translates to increased processing overheadfor dynamic ADI retrieval services. By defining the namespace globally, all thesecomplications can be avoided. If a namespace has not been defined for either theXML or XSL processors, an error is logged to the application error logs to the effectthat the namespace ID does not have an associated URI mapping. This problemmight occur during the creation of the rule if the XSL processor has not beennotified of the new namespace, or during rule evaluation if the XML processor hasnot been notified.

Authorization rules evaluatorThe authorization rules evaluator evaluates authorization rules within theconstraints that are required by the authorization engine.

The authorization rules evaluator takes the rule policy that is attached to the targetprotected object and evaluates the rule by calling the XSL processor. The inputXML document for the transformation contains a definition for how theauthorization engine can retrieve one of the following sources for the ADI:v User credential entitlements that is requesting the authorizationv Application context information that is passed in by the access decision call

(passed in by the resource manager)v Tivoli Access Manager authorization engine contextv Dynamic ADI retrieval entitlement services

The authorization engine expects the rules evaluation to result in the return of oneof the string identifiers as shown in Table 5. These identifiers ensure uniquenesswhen an XSL rule is written incorrectly and the evaluation returns incorrectinformation. Delimiting the identifiers with an exclamation point (!) enables theevaluator to identify errant cases.

Table 5. String identifiers returned by rules evaluation

Delimiter Meaning

!TRUE! Access is permitted.

!FALSE! Access is denied.

!INDIFFERENT! The rules engine has no opinion.

The identifiers must be the only text in the output document; although they can besurrounded by white space. If a value other than the defined valid values or anempty document is returned, the access decision fails and an error code is returnedto the resource manager to indicate that the rule is not compliant. The format of anauthorization rule is outlined in “Format and constraints of rules” on page 129.

In addition, the maximum length of any result text that is returned by a ruleevaluation is limited to 1023 characters. Rules returning more text than this limitcauses the access decision to fail at runtime with a minor error code ofivacl_s_rule_result_string_too_large.


Format and constraints of rulesAn authorization rule must be defined as an XSL template in an XSL stylesheetusing the stylesheet prolog that is specified in the configuration file. The rule mustbe written in a valid XSL template rule format and must return a text documentthat contains one of the following string identifiers:v !TRUE!v !FALSE!v !INDIFFERENT!

The identifiers must be the only text in the output document but they can besurrounded by white space. The identifiers are not case-sensitive. If a value otherthan one of the identifiers listed or an empty document is returned, the accessdecision fails and an error code is returned to the resource manager indicating thatthe rule is not compliant. For more information about string identifiers, see“Authorization rules evaluator” on page 128.

For authorization decisions, the rule must return the expected decision data to therules evaluator. The data that is returned from the rules-driven entitlementsinterface must be able to be expressed as a text name-value attribute pair in theentitlements output parameter of the azn_entitlement_get_entitlements()method. Many data providers return entitlements data in XML format; thus, noadditional transformation is required to pass these entitlements into the rulesevaluator as ADI.

All ADI that is passed to the rules evaluator must be specified in XML. Non-XMLADI that is passed to the access decision or retrieved from the credential isformatted into XML by the evaluator before an authorization rule can be evaluated.

The result of the XSL transformation performed by an XSL authorization rule mustbe a text output document that contains only one of the supported stringidentifiers.

The following example references the XML data item that is defined in JohnSmith.The condition that the following example rule evaluates is expressed, as follows:if ((AmountReqd + Credit Card Balance) < Credit Card Limit

&& MileagePlus Status is "100k")

The corresponding authorization rule is:<xsl:if test="(AmountReqd + JohnSmith/CreditCard/Balance)

< JohnSmith/CreditCard/Limitand JohnSmith/MileagePlus/MemberStatus = ’100k’">

!TRUE!</xsl:if>

This example rule is the simplest form for specifying an authorization rule. It doesnot include its own template match statement and it accepts the default templatematch statement, which is set to /XMLADI. Template match statements are an XSLlanguage construct that is used to select the point in the hierarchy of an XMLdocument at which the XSL rules, which are contained within the template matchstatement, are applied. The default template match statement of the ADI XMLmodel matches from the top of the XMLADI document by specifying the XPath/XMLADI.

To add your own template match statement to a rule definition, only twoadditional lines are needed. For example, to rewrite the example to include your


own explicit template match statement that matches from the root of the XMLADIdocument, you would modify the rule as follows:<xsl:template match="/XMLADI"><xsl:if test="(AmountReqd + JohnSmith/CreditCard/Balance)

< JohnSmith/CreditCard/Limitand JohnSmith/MileagePlus/MemberStatus = ’100k’)

!TRUE!</xsl:if></xsl:template>

To reference any data item in the document, the XPath to each node must includethe XMLADI node. For example, to access the credit card balance, the full pathwould be /XMLADI/JohnSmith/CreditCard/Balance. When a rule is built, the rulewriter must understand what the correct XPath, used to access the XML datanodes and subnodes, is from the current point in the tree. The current point in thetree is selected by using the template match statement. The template matchstatement allows an XSL programmer to shorten the XPath to each data element byspecifying that the XPath processing occur further down the XML document tree.

The <xsl:template match="/XMLADI"> statement tells the XSL processor that allrelative XPaths within the bounds of the template statement must be assumed tobe relative to the node XMLADI. To shorten the XPaths even further, the templatematch statement could be set at /XMLADI/JohnSmith in which case, the credit cardbalance could be referred to as CreditCard/Balance.

Policy administrators must also make the following assumptions about the XSLstylesheet document that is created by the rules evaluator to contain the rule thatthey devise:v If a stylesheet prolog is specified in the azn client configuration file, that prolog

is imported into the empty stylesheet. If no prolog is specified, the followingdefault prolog is used instead:<?xml version="1.0" encoding=’UTF-8’?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

version="1.0">

<xsl:output method="text" omit-xml-declaration="yes"

encoding=’UTF=8’ indent="no"/>

<xsl:template match="text()"></xsl:template>

v Among other things, this prolog sets the XSL stylesheet syntax to version 1.0,which is supported by the embedded XSL processor. The prolog sets thenamespace for XSL documents to xsl, which requires that all XSLlanguage-specific identities be prefixed by xsl:. This prefix is the standard modeof operation for XSL stylesheets. Most attributes in this prolog must be in thestylesheet or, if not, the results that are returned from the rules evaluator do notconform to the expected results.

v All authorization rules must be enclosed in an xsl:template match statement. Ifthe rule is defined with its own xsl:template match statement, the rule isaccepted as is. This acceptance allows the rule creator to specify the level withinthe ADI XML document at which the rule matches data items. But in this case,the match statement must be the first statement encountered by the evaluatorwhen validating the rule or it is assumed that there is no template matchstatement. If there is a match statement but the match statement does not beginwith the /XMLADI absolute path, the rule is returned as invalid. Relative matchstatements are not accepted at this level.

v If no match statement is specified in the rule, the rule is automatically enclosedin the following match statement:<xsl:template match="/XMLADI">

...<xsl:template>

v Therefore, all rules devised without an explicit template match statement mustuse XPath expressions that assume the XML context node is /XMLADI. The XPathexpression for any ADI item must begin with the container name of the itemand must be fully qualified.

Examples of authorization rulesFollowing are example rules that demonstrate how rules can be implemented.v “Example: ADI from resource manager”v “Example: ADI from entitlement data”v “Example: ADI from dynamic ADI retrieval services” on page 132

Example: ADI from resource managerThe following example relies mostly on ADI that is passed in to the access decisioncall but it also requires an ADI container called printQuota to be stored in therequesting user credential or passed in as application context. The access decisionlogic defined by this rule is to permit access only when one of the followingconditions is true:v The user is in the printUsers groupv The user has requested a print operation (p)v The user has requested to queue a print job for printing later (q) and the print

quota is less than 20<xsl:if test=’azn_cred_groups = "cn=printUsers,o=ibm,c=us"

and (contains(azn_engine_requested_actions,"p")or contains(azn_engine_requested_actions,"q"))

and printQuota <20’>!TRUE!

</xsl:if>

The test condition for the group name returns an appropriate result regardless ofthe number of groups that the requesting user is in. The condition is an XSL nodetest that compares each value within the XML element azn_cred_groups with theDN string. It is important to note that the syntax for determining the opposite case(for example, that the requesting user is not in the printUsers group) requires aslightly different expression, because it is a node test. See “Example: ADI fromentitlement data” for an example of how to test for whether a set of values like theazn_cred_group_names attribute does not contain a certain member.

Example: ADI from entitlement dataIn the following example, the rule works on data that is within the authorizationcredential. It evaluates the following attributes:v azn_cred_principal_namev azn_cred_groupsv azn_cred_registry_id

Each of the xsl:when statements are evaluated. The first statement with conditionsthat are all true returns a result. Each condition tested has a comment that explainsits action.

<xsl:choose>

<xsl:when test="azn_cred_principal_name = ’myuser0’">!TRUE!

</xsl:when>

<xsl:when test="azn_cred_principal_name = ’myuser1’">

!FALSE!</xsl:when>



<xsl:when test="azn_cred_registry_id = ’cn=myuser3,secAuthority=Default’">!TRUE!

</xsl:when>



<xsl:when test="azn_cred_groups = ’mygroup1’and not (azn_cred_groups = ’mygroup2’)">!TRUE!

</xsl:when>

<xsl:otherwise>!FALSE!

<xsl:otherwise></xsl:choose>

The fourth xsl:when statement uses the not() function to negate the Boolean resultof the following test:azn_cred_groups = ’mygroup2’

The not() function is used instead of the valid authorization rule operator !=operator because, in this case, the azn_cred_groups attribute is a multi-valuedattribute. Multi-valued attributes like azn_cred_groups return a set of values,referred to as a node-set in XSL, to be tested by the condition. Each node value inthe set is tested against the condition individually and !TRUE! is returned if any ofthe conditions evaluate to true. In any case, where the user is in more than onegroup, other than mygroup2, the result of the node test is always !TRUE!. To test thenonexistence of something in a node-set, use the not() function instead of the !=operator. For example, you can test that the condition group is mygroup2 is nottrue.

Example: ADI from dynamic ADI retrieval servicesThe following example evaluates an application-defined XML input document thatis provided by a dynamic entitlement service that was written using the dynamicADI retrieval service. The code that must be written might create a batch objectthat contains a list of operations that are to be performed together. The batch objectconsists of a number of transaction elements. Each transaction consists of an itemand the amount of those items to order.

With these assumptions, the following XML object could be used as input formaking the authorization decision:<batch>

<max_tx_count>5</max_tx_count><max_tx_amount>150</max_tx_amount><account>customerA</account><transaction>

<item>widgetA</item>

<amount>10</amount></transaction><transaction>

<item>widgetB</item><amount>20</amount>

</transaction><transaction>

<item>widgetC</item><amount>30</amount>


<item>widgetD</item><amount>40</amount>


<item>widgetE</item><amount>50</amount>

</transaction></batch>

With this expected XML object, you could create the following authorization rule:<xsl:if test="azn_cred_groups = batch/account

and count (batch/transaction) <= batch/max_tx_countand sum (batch/transaction/amount) <= batch/max_tx_amount">

!TRUE!</xsl:if>

The authorization rule checks that the requesting user is a member of a groupwhose name matches the name of the account in the transaction (in this example, itis customerA). If the requesting user is not a member of this group, the user is notauthorized to submit batch requests on behalf of customerA. Then, the rule checksthat the total number of transactions within the batch is less than or equal to themax_tx_count element of the batch object and that the total number of itemsordered in the entire request is less than the max_tx_amount element of the batchobject. The rule calls the count() and sum() functions. The count() function countsthe number of instances of a transaction element within the batch. The sum()function totals the value of all the amount elements within all transaction elementsin the batch.

For additional information of creating authorization rules, see the IBM Tivoli AccessManager for e-business: Authorization C API Developer Reference.

Methods of providing ADI to the rules evaluatorA resource manager application can provide ADI from the resource manager to therules evaluator in one of the following ways:v Adding the attributes to the application context parameterv Configuring the rules evaluator to supply the missing ADI to the authorization

engine only when it is explicitly requested

The first method is to provide the ADI by adding the attributes to the applicationcontext parameter passed to the azn_decision_access_allowed_ext() method. Theproblem with this method is that the resource manager must either know whichADI is going to be needed by a particular access decision. Alternatively, you canprovide all the ADI for all known rules to the authorization engine for every accessdecision call regardless of whether a rule is involved in the decision.

The first method might be acceptable and even desirable for a smaller set of ADI.However, for a larger and more varied set of possible ADI, a second method isneeded. You can configure the resource manager to supply the missing ADI to theauthorization engine only when it is explicitly requested. With this method, theauthorization engine can be configured with a set of ADI prefixes that can beprovided by the resource manager upon request. The authorization engine fails theaccess decision and notifies the resource manager of the ADI it needs in apermission information attribute returned by theazn_decision_access_allowed_ext() method. The attribute contains a list of theADI that is needed to successfully evaluate the rule. The ADI was not found in theapplication context that was passed in and did not have a prefix matching thosethat the resource manager identified as its own.

The permission information attribute is named azn_perminfo_rules_adi_requestand contains a text attribute value for each item of ADI required. The resourcemanager looks for this attribute when the access decision fails, and when it ispresent, scans the list of ADI names in the attribute and gathers the requested datato try the access decision with this additional data again. If the requested datacannot be provided, the resource manager must deny access and log the problemas a failure due to insufficient rules data. The requested list contains only the ADIitems that are identified as being provided by the resource manager. The uniqueprefix added to the attribute name is used to identify the ADI. All resourcemanagers that provide data to the evaluation process in this manner must define aunique prefix by which their ADI data set can be identified.

Permission information is returned to a resource manager application only whenthe authorization client was configured that way. To activate the return of theazn_perminfo_rules_adi_request permission information attribute, the name ofthis attribute must either be added to the azn_init_set_perminfo_attrsinitialization attribute or the equivalent permission-info-returned entry in the[aznapi-configuration] stanza.

The ADI prefixes that are recognized by the resource manager can be configuredusing the resource-manager-provided-adi entry or theazn_init_resource_mgr_provided_adi initialization attribute. For more informationabout the configuration entry, see “resource-manager-provided-adi” on page 136.For more information about the initialization attribute, see the IBM Tivoli AccessManager for e-business: Authorization C API Developer Reference.

The authorization engine attempts to anticipate the need to request informationfrom the resource manager by obtaining the rule policy object on the protectedobject early in the access decision process. The authorization engine then comparesthe required ADI in the rule with the ADI names in the application contextparameter that is passed by the resource manager. The ADI names, which aremissing from the application context and which are specific to the resourcemanager, are added to the returned permission information object.

ADI prefixes must be unique to identify them as resource manager ADI and toavoid conflict with ADI provided in the credential from the authorization engine orfrom an external data provider.


Reason codes for rule failuresWhen this mode of operation is selected, the authorization engine processes allpolicies for the access decision as normal. If the rule evaluation fails, the enginereturns access denied with a reason code in the azn_perminfo_reason_rule_failedpermission information attribute list.

This feature allows the target application to fail or permit the access request basedon the rule failure reason code it is given by the resource manager. When access isdenied, the application must check the permission_info attribute list returned fromthe access decision call to determine if a rule failure reason code was returnedfrom the access decision. The resource manager does not need to check for theattribute on a successful access decision call. The Tivoli Access Manager fore-business application is an example of an aznAPI resource manager that can makeuse of the rule failure reason code. When configured, Tivoli Access Manager fore-business forwards the reason code to the protected Web application. Theprotected Web application must be mounted through a secure junction to haveaccess to the reason code defined for the authorization rule. The use of rule failurereason codes in Tivoli Access Manager for e-business is limited to the protectedobject space of junctioned Web applications.

The attribute value (the reason code) of the azn_perminfo_reason_rule_failedattribute is a single string whose value is determined and defined by the policyadministrator and is set in the rule policy object when it is first created. The onlyconstraint on the value of the reason code is that the value must be a string.

The following conditions must be met before a rule failure reason code is returnedto the caller:v The reason code is returned only when the access request is denied and the rule

policy evaluation denies access, but not for every case in which access is denied.The reason code is not returned when the rule evaluation succeeds. The rulefailure reason code is not returned if the rule failed due to a rule syntax error orif there was insufficient ADI to perform the rule evaluation. In the latter cases,the authorization decision is failed with an error status.

v There must be a reason code set in the attached rule policy object. This value isset in the rule policy using the admin API or the pdadmin utility.

v The aznAPI application must be enabled to return the rule failure reason aspermission information. To perform this action, either theazn_init_set_perminfo_attrs initialization parameter or the equivalentconfiguration file entry in the [aznapi-configuration] stanza (stanza entrypermission-info-returned) must include the attribute nameazn_perminfo_reason_rule_failed. This feature enables the attribute to bereturned by the authorization engine in the permission information outputparameter (perminfo) of azn_decision_access_allowed_ext(). For moreinformation about permission information attributes and how to configure theauthorization engine to return them, refer to the IBM Tivoli Access Manager fore-business: Authorization C API Developer Reference.

Configuration file and initialization attributesA number of configuration file entries and initialization attributes are available tocontrol aspects of the initialization of the rules evaluator within the authorizationengine. The configuration entries are in the configuration file of the resourcemanager. An example of this aznAPI.conf configuration file is provided in theexample/authzn_demo/cpp directory of the Tivoli Access Manager ApplicationDeveloper Kit (ADK) package. Configuration files are also used by Tivoli Access


Manager resource management applications, such as Tivoli Access Manager fore-business, and these configuration entries can be added to the configuration file ofthese applications. Refer to the documentation for the specific Tivoli AccessManager application for more information about the application configuration file.

Initialization attributes are the programmatic equivalent of configuration attributesand are intended to be used to develop a custom resource manager application.For more information about the authorization-rule-specific initialization attributesand the process of developing a custom resource manager aznAPI application, seethe IBM Tivoli Access Manager for e-business: Authorization C API Developer Reference.

resource-manager-provided-adiThe resource-manager-provided-adi configuration stanza entry defines the prefixesthat the authorization engine uses to determine the set of missing ADI that isprovided by the resource manager. This entry uses a string prefix as its value. Tospecify more than one prefix you must add multiple stanza entries as in thefollowing examples:resource-manager-provided-adi = sales_customer_

resource-manager-provided-adi = sales_item_

These examples notify the authorization engine that any ADI it requires that beginswith sales_customer_ or sales_item_ be provided by the resource managerapplication. ADI items named sales_customer_name, sales_customer_address,sales_item_count, and sales_item_price are examples of ADI that theauthorization engine would request from the resource manager.

dynamic-adi-entitlement-servicesThe dynamic-adi-entitlement-services configuration entry lists the service IDs ofthe dynamic ADI retrieval entitlement services that must be called by theauthorization engine if ADI is missing from the requesting user credential or fromthe application context, and cannot be gathered from the resource manager. Anyentitlement service configured under this entry is called by the authorizationengine using the azn_entitlement_get_entitlements() interface and is passed theazn_perminfo_rules_adi_request attribute. The string values of this attribute arethe container names of the ADI that are still required. If the dynamic ADI retrievalservice can fulfill the request, it returns the requested data to the authorizationengine in the entitlements parameter. Examples of entitlement services that can beused in this manner are the Cred Attributes Entitlement Service and theEntitlement Service Demo, both of which are provided with Tivoli Access Manager.For more information about configuring and using entitlement services, see theIBM Tivoli Access Manager for e-business: Authorization C API Developer Reference.

To specify that the authorization engine must call multiple dynamic ADI retrievalservices, you must specify multiple entries. The following examples demonstratehow to specify the service IDs of two different entitlement services for use asdynamic ADI entitlement services. The service IDs must correspond to validentitlement service definitions in the [aznapi-entitlement-service] stanza.dynamic-adi-entitlement-services = ent_cred_attrs_iddynamic-adi-entitlement-services = ent_svc_demo_id

input-adi-xml-prolog and xsl-stylesheet-prologThe input-adi-xml-prolog and xsl-stylesheet-prolog configuration entries weredefined to allow augmentation of the XML and XSL prolog statements that are


appended to the ADI XML document and authorization rule stylesheet before theyare passed to the rules evaluator for processing. The format and defaults for eachof these entries are:input-adi-xml-prolog=<?xml version="1.0" encoding="UTF-8"?>

andxsl-stylesheet-prolog=<?xml version="1.0" encoding=’UTF-8’?><xsl:stylesheet xmlns:xsl=’http://www.w3.org/1999/XSL/Transform’ version=’1.0’><xsl:output method = ’text’omit-xml-declaration=’yes’ encoding=’UTF-8’indent=’no’/><xsl:template match=’text()’></xsl:template>

Due to the constraints imposed by the authorization rule model, there are anumber of prolog attributes that are required by the authorization engine (all ofwhich are specified in the default prolog entries.) If any of these attributes arechanged or omitted from the entry, the authorization client fails to start andreturns an error.

Note: Ensure that you are familiar with the Xalan XSL processor, the Xerces XMLprocessor, and the use of prolog statements before any attempt is made tochange these entries from the defaults provided.

[xmladi-attribute-definitions]The [xmladi-attribute-definitions] stanza enables customers to add XMLattribute definitions, such as XML namespace definitions, to the XMLADIdocument start tag. For example, when an application wants to use namespaces todifferentiate or aggregate ADI items, as discussed in “Defining an XMLnamespace” on page 126, the XML processor must be notified of the namespace byusing an XML namespace definition. The namespace definition can be added tothis stanza, and it is automatically added to the XMLADI document element starttag. The benefit of adding definitions to the XMLADI document start tag is thatthe attribute definitions are available for all ADI items that are defined in theXMLADI document, whether their values were retrieved from the credential,generated by the authorization engine or retrieved by a dynamic ADI entitlementservice. For example:[xmladi-attribute-definitions]

xmlns:myNS = "http://myURI.mycompany.com"appID = ’"Jupiter" - Account Management Web Portal Server #1.’

The XMLADI element start tag that results from these definitions is:<XMLADI xmlns:myNS="http://myURI.mycompany.com"

appID=’"Jupiter" - Account Management Web Portal Server #1.’>

Both the namespace ID myNS and the attribute appID are defined globally in theXMLADI document.

Managing authorization rulesYou can perform the following authorization rule tasks:v “Creating an authorization rule” on page 138v “Modifying an authorization rule” on page 139v “Listing authorization rules” on page 140v “Cloning an authorization rule” on page 140v “Importing authorization rules” on page 140


v “Exporting all authorization rules” on page 141v “Exporting a single authorization rule” on page 141v “Exporting multiple authorization rules” on page 141v “Attaching an authorization rule to a protected object” on page 142v “Detaching an authorization rule” on page 143v “Locating where an authorization rule is attached” on page 143v “Deleting an authorization rule” on page 144


Notes:

1. There are no equivalent pdadmin commands for importing, exporting, orcloning authorization rules.

2. When providing rule text with the pdadmin utility, enclose the rule text indouble quotation marks ("). Double quotation marks embedded within the ruletext must be escaped with a backward slash (\) so that they are ignored by thepdadmin utility. The XSL processor treats single and double quotation marksequally for defining text strings so they can be used interchangeably, but theymust always be paired appropriately. For example:pdadmin sec_master> authzrule create testrule1

"<xsl:if test=’some_piece_of_ADI =\"any string\"’>!TRUE!</xsl:if>"

Creating an authorization ruleYou can create an authorization rule using Web Portal Manager or the pdadminutility.

Web Portal ManagerTo create an authorization rule, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → Create AuthzRule to display the Create AuthzRule page.3. Type the AuthzRule Name for the authorization rule that you want to create

(for example, r2).

Note: Do not use the following characters in the name of a rule:! " # & ( ) * + , ; : < > = @ \ |

4. In the Description field, type a description of the authorization rule. Forexample, type the following text:time-of-day rule for engineering object space

5. In the AuthzRule Text field, type the text of the rule policy. For example, typethe following information:<xsl:template match="/XMLADI">

<xsl:if test="(AmountReqd +JohnSmith/CreditCard/Balance)<JohnSmith/CreditCard/Limit

and JohnSmith?mileagePlus/MemberStatus=’100k’>!TRUE!

</xsl:if></xsl:template>

6. In the Fail Reason field, type the text that you want to be returned to theresource manager if the rule denies access to a protected object. For example,type error.


7. Click Create. If successful, the new rule is displayed as a link on the ManageAuthzRules page. If you select the authorization rule link, the properties of thatrule are displayed.

pdadminTo create an authorization rule using the pdadmin utility, log in to the domain as adomain administrator and use the authzrule create command. For example, tocreate a rule named r2 with a rule file named engineering.xsl that implementsthe time-of-day rule for the engineering object space and returns a fail reason codeof error, enter the following command on a single line:pdadmin sec_master> authzrule create r2 -rulefile engineering.xsl

-desc "time-of-day rule for engineering object space"-failreason error


Modifying an authorization ruleYou can modify an authorization rule using Web Portal Manager or the pdadminutility.

Web Portal ManagerTo modify an authorization rule, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.

A list of authorization rules that were created in Tivoli Access Manager aredisplayed. Each rule is a link that displays properties for that rule whenselected.

3. Click the authorization rule link for the rule that you want to change. TheAuthzRule Properties page is displayed.

4. As needed, change the following information:v The descriptionv The authorization rule textv The fail reasonFor example, if no description currently exists, add a description. If adescription currently exists, change the authorization rule description by typingthe new description in the Description field (for example, adding the wordsupdated June 23 2003):updated June 23 2003 time-of-day rule for engineering object space

5. Click Apply for the changes to take effect.

pdadminTo modify an authorization rule in the domain using the pdadmin utility, log in tothe domain as a domain administrator and use the authzrule modify command.

For example, to change the rule named r2 to return a fail reason code of warning,enter the following command:pdadmin sec_master> authzrule modify r2 failreason warning



Listing authorization rulesYou can list the authorization rules that were created using Web Portal Manager orthe pdadmin utility.

Web Portal ManagerTo list all existing authorization rules, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.

A list of names for authorization rules that were created in Tivoli AccessManager are displayed as links. If you select an authorization rule link, theproperties of that rule are displayed.

pdadminTo list authorization rules in the domain using the pdadmin utility, log in to thedomain as a domain administrator and use the authzrule list command.pdadmin sec_master> authzrule list


Cloning an authorization ruleYou can clone an authorization rule using Web Portal Manager only.

Web Portal ManagerTo clone an authorization rule in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → List AuthzRule.3. From the Manage AuthzRules page, select the authorization rule you want to

clone.4. From the AuthzRule Properties page, click Clone.5. From the Clone AuthzRule page, type an AuthzRule Name For example, type

Test-AuthzRule. The default value is the name of the original authorization rulewith the prefix Clone. This field is required.

6. Optional: Type a Description of the authorization rule. For example, type Cloneof new authorization rule. The default value is the description of the originalauthorization rule.

7. Click Clone. If successful, a link for this cloned authorization rule is createdand a success message is displayed.

Importing authorization rulesYou can import an authorization rule by using Web Portal Manager only.

Web Portal ManagerTo import an authorization rule in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → Import AuthzRule.3. From the Import AuthzRule page, complete one of the following steps:

v In the AuthzRule File Name field, type the name of the authorization rule toimport. For example, type ruleImport.xml.

v Click Browse to select a file name.


4. If the file containing the authorization rule was encrypted when it wasexported, in the Encryption String text field, type the string that was used toencrypt the XML file.

5. Click Import.

If successful, the imported rule is available when you list all the rules.

Exporting all authorization rulesYou can export all authorization rules by using Web Portal Manager only.

Web Portal ManagerTo export all authorization rules in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → Export All AuthzRules to display the Export AuthzRule to

File page.3. Optional: In the Encryption String text field, type the string to use to encrypt


field, type the string again.5. Click Export to display the File Download window.6. Click Save to display the Save As window.7. Click Save to create the file that contains the exported rule descriptions. The

default file name is ruleExport.xml.

If successful, the exported rule descriptions are available in the specified location.

Exporting a single authorization ruleYou can export a single authorization rule using Web Portal Manager only.

Web Portal ManagerTo export a single authorization rule in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → List AuthzRule.3. From the Manage AuthzRules page, select the authorization rule that you want

to export.4. From the AuthzRule Properties page, click Export to display the Export

AuthzRule to File page.5. Optional: In the Encryption String text field, type the string to use to encrypt


field, type the string again.7. Click Export to display the File Download window.8. Click Save to display the Save As window.9. Click Save to create the file that contains the exported authorization rule

description. The default file name is ruleExport.xml.

If successful, the exported rule description is available in the specified location.

Exporting multiple authorization rulesYou can export multiple authorization rules using Web Portal Manager only.


Web Portal ManagerTo export authorization rules in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → List AuthzRule.3. From the Manage AuthzRules page, select the authorization rule that you want

to export.4. Click Export to display the Export AuthzRule to File page.5. Optional: In the Encryption String text field, type the string to use to encrypt


field, type the string again.7. Click Export to display the File Download window.8. Click Save to display the Save As window.9. Click Save to create the file that contains the exported authorization rule

descriptions. The default file name is ruleExport.xml.


Attaching an authorization rule to a protected objectYou can attach an authorization rule to a protected object using Web PortalManager or the pdadmin utility.

Web Portal ManagerTo attach a rule to a protected object, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.


3. Click the link for the authorization rule that you want to attach to an object.For example, the r2 authorization rule. The AuthzRule Properties page isdisplayed.

4. Click the Attach tab to view a list of protected objects to which theauthorization rule is already attached, if any.

5. Click Attach to display the Attach AuthzRule page.6. Type the Protected Object Path of the protected object to which you want to

attach the authorization rule. This field is required. Be sure to type the full pathname. For example, type the following path:/WebSEAL/tivoli.com/w3junction/index.html

7. Click Attach. If successful, the new protected object is added as a link to thelist of objects to which the authorization rule is attached on the AuthzRuleProperties–Attach page.

pdadminTo attach an authorization rule to a protected object using the pdadmin utility, login to the domain as a domain administrator and use the authzrule attachcommand.

For example, to attach a rule named r2 to a protected object named/WebSEAL/tivoli.com/w3junction/index.html, enter the following command:pdadmin sec_master> authzrule attach /WebSEAL/tivoli.com/w3junction/index.html r2



Detaching an authorization ruleYou can detach an authorization rule from a protected object using Web PortalManager or the pdadmin utility.

Web Portal ManagerTo detach a rule from a protected object, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.


3. Click the link for the authorization rule that you want to detach from an object.The AuthzRule Properties page is displayed.

4. Click the Attach tab to view a list of protected objects to which theauthorization rule is already attached, if any.

5. Select one or more check boxes for the protected objects from which you wantto detach the authorization rule.

6. Click Detach to display the Detach AuthzRule from Object page where you areprompted to confirm or cancel the request.

pdadminTo detach a rule from a protected object in the domain using the pdadmin utility,log in to the domain as a domain administrator and use the authzrule detachcommand.

For example, to detach a rule from a protected object named /WebSEAL/tivoli.com/w3junction/index.html, enter the following command:pdadmin sec_master> authzrule detach /WebSEAL/tivoli.com/w3junction/index.html


Locating where an authorization rule is attachedYou can find the protected objects that have an authorization rule attached usingWeb Portal Manager or the pdadmin utility.

Web Portal ManagerTo find protected objects that are attached to a rule, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → List AuthzRule. A list of authorization names is displayed.

Each authorization rule name is a link that you can click to display theAuthzRule Properties page.

3. Click the Attach tab.

pdadminTo find all the protected objects to which an authorization rule is attached in thedomain using the pdadmin utility, log in to the domain as a domain administratorand use the authzrule find command.


For example, to find the protected objects attached to a rule named r2, enter thefollowing command:pdadmin sec_master> authzrule find r2


Deleting an authorization ruleYou can delete an authorization rule using Web Portal Manager or the pdadminutility.

Web Portal ManagerTo delete an authorization rule, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.


3. Select one or more check boxes for the links that you want to delete. Forexample, you might select the check box for the authorization rule named r2.

4. Click Delete to display the Delete AuthzRules page where you are prompted toconfirm or cancel the deletion.

pdadminTo delete an authorization rule in the domain using the pdadmin utility, log in tothe domain as a domain administrator and use the authzrule delete command.

For example, to delete a rule named r2, enter the following command:pdadmin sec_master> authzrule delete r2



Chapter 11. Managing users and groups

An initial domain administrator is created when a new domain is created. Thedomain administrator has the necessary privileges to manage the domain. Thedomain administrator can create and configure users, groups, resources, andapplications, and can delegate administration tasks within the domain as required.

A user represents any authenticated Tivoli Access Manager identity. Typically, theseauthenticated identities represent network users or resource managers.

A group is a collection of one or more users. An administrator can use group ACLentries to assign the same permissions to multiple users. New users to the domaingain access to objects by becoming members of groups. Group membershipeliminates the need to create new ACL entries for each new user. Groups canrepresent organizational divisions or departments within a domain. Groups arealso useful in defining roles or functional associations.

An account refers to users and groups collectively.

A registry unique identifier (UID) specifies the location in the user registry wherethe new user is created. Similarly, a registry group unique identifier (GID) specifiesthe location in the user registry where the new group is created. For registry UIDsand GIDs, you must type the full path name for the new user or group. The pathformat depends on the type of registry that the product is using. The following listshows sample formats for different user registries:

LDAP cn=IBM-Support,o=ibm,c=us

Active Directorycn=IBM-Support,dc=Austin,dc=US

Dominocn=IBM-Support,dc=Austin,dc=USIBM-Support/Austin/US

The registry UID or registry GID provides extra security in the case where a useror group is deleted from the domain and then recreated with the same name. Forexample, even though a new user has the same name as the deleted user, TivoliAccess Manager allocates a new registry UID to this user. Because the registry UIDis new, any existing ACL entries that refer to the old user name do not grant anyrights to the new user. Stale UIDs from deleted users and groups are silentlyremoved by the policy server.

Managing usersYou can perform the following user tasks:v “Creating a user” on page 146v “Listing users” on page 147v “Changing a password” on page 148v “Setting user policy” on page 149v “Setting global user policy” on page 151v “Importing users” on page 153v “Deleting a user” on page 154



Creating a userYou can create a user using Web Portal Manager or the pdadmin utility.

When a user is created, the domain administrator assigns a user name, which issometimes referred to as a principal name. The user name must be unique withinthe domain, because it is used by Tivoli Access Manager to identify this user. Aregistry user identifier, known as a distinguished name (DN), is also assigned touniquely identify the user definition in the user registry. The format of the DNdepends on the registry type being used. Also assigned are the common name (CN)and surname (SN) of the user being defined.

Note: When Active Directory Application Mode (ADAM) is used as the userregistry, users must be created within the same ADAM partition in whichTivoli Access Manager was configured.

Web Portal ManagerTo create a user in a domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click User → Create User.3. In the User Id text field, type the user name (for example maryj).4. Click Group Membership to search for groups in which the user can be a

member.5. In the First Name text field, type the name of the user (for example Mary).6. In the Last Name text field, type the family or surname of the user (for

example Jones).7. In the Password text field, type the password. Passwords must adhere to the

password policies that are set by the domain administrator.8. In the Confirm Password text field, type the password again.9. In the Description text field, type the description for the user (for example,

Member of Marketing Group.10. In the Registry UID text field, type the registry UID. The registry UID

specifies the location in the user registry where the new user is created. Forexample: cn=maryj,o=ibm,c=us,dc=mkt. Lotus Notes® users require the fullpath name for the user being created. For example: Mary Jones/IBM/US

11. Select the Account Valid check box to indicate that the new user canparticipate in the domain. If this option is not selected, the new user accountis not valid and the user cannot log in.

12. Select the GSO User check box to indicate the use of global sign-on (singlesign-on) for Tivoli Access Manager.

13. Select the Password Valid check box to force a password change the next timethe user logs in to the domain. If this option is not selected, the user isinformed that the password has expired.

14. Click No Password Policy to indicate that you do not want the initialpassword to conform to the password policies that are set by the domainadministrator.

15. Click Create.


A message is shown if the user ID is created.

pdadminTo create a user using the pdadmin utility, log in to the appropriate domain as adomain administrator and use the user create command to create the user.

For example, to create the user named maryj with global sign-on capability, enterthe following command:pdadmin sec_master> user create –gsouser maryj "cn=Mary Jones,o=IBM,c=us,dc=mkt" \"Mary Jones" Jones pwd2pwd2

The format of the distinguished name depends on the type of user registry. Formore information, see the IBM Tivoli Access Manager for e-business: CommandReference.

Listing usersYou can search for users using Web Portal Manager or the pdadmin utility.However, when the user registry contains a large number of user definitions, usewildcard characters with discretion. When a pattern includes one or more wildcardcharacters, the command attempts to find all user definitions that match thespecified pattern, but displays only the specified number of matching definitions inthe user registry. For example if the user registry contains 10,000 definitions,specifying a single wildcard (“*”), with a limit of 100, finds all 10, 000 definitionsbut displays only the first 100 matching definitions.

Note: If a large number of users are defined in the user registry (for example,more than 100,000), avoid using the global wildcard (*). Instead, use a searchfilter that is as specific as possible, or qualify the search pattern to limit thesearch results.

For example, if you are using the pdadmin tool and listing users whosenames start with John, limit the search results by specifying the number ofrecords to return, as in the following command: pdadmin user list john*100

For the specific syntax of the user list command, see the IBM Tivoli AccessManager for e-business: Command Reference.

For more specific information about tuning the directory server to achieve bestresults, see the IBM Tivoli Access Manager for e-business: Performance Tuning Guide.

Web Portal ManagerTo search for and list up to a maximum of 100 users:1. Use Web Portal Manager to log in to the appropriate domain as a domain

administrator.2. Click User → Search Users to display the User Search page.3. At the User Search page, specify the pattern to filter user ID names. Use

wildcard characters with discretion.4. Use the default value of 100 or type another value in the Maximum Results

field. This number limits the number of user IDs that are displayed.5. Click Search to display a table of user IDs. Each user ID is displayed as a link.

From the User Search page, you can perform these tasks: create a user, deleteone or more existing users, and click the link to view user properties.

Chapter 11. Managing users and groups 147

6. Use the default value of 15 user IDs per page, or click Options to type thenumber of user IDs to view per page. Toggle back by clicking Hide Options.

7. Use the default value of None, meaning that no text is used for filtering, or, clickFilters to find user IDs that contain, start with, or end with the text that youspecify. Toggle back by clicking Hide Filters.

pdadminTo search for a list of users using the pdadmin utility, log in to the domain as adomain administrator and use the user list command to list users.

For example, to search for and list up to a maximum of 100 users, enter thefollowing command:pdadmin sec_master> user list * 100


Changing a passwordYou can change a user password using Web Portal Manager or the pdadmin utility.The new password must comply with the password policies that are currently ineffect.

Note: When using Active Directory as your user registry and the Active Directoryserver is running on Windows 2003 SP1 or later, old passwords might stillbe able to be used after a password change.

For additional information, see the following Web page:

http://support.microsoft.com/?id=906305

When setting or changing a password, the password must comply with thefollowing policies:v The defined Tivoli Access Manager password policyv The password policy for the underlying operating systemv The password policy for the underlying user registry

When enforcing the password policy, Tivoli Access Manager validates compliancein the following sequence:1. Against the Tivoli Access Manager password policy currently in effect2. Against the underlying user registry

Although a password complies to the defined Tivoli Access Manager passwordpolicy, validation might fail against the password policy of the underlyingoperating system or user registry.

For additional information about setting the password policy for Tivoli AccessManager users, see“Setting global user policy” on page 151.

Web Portal ManagerTo change the password for the specified user ID, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click User → Change My Password.


http://support.microsoft.com/?id=906305

3. Verify that the User ID identifies the login identifier for the user whosepassword you want to change.

4. In the Current Password text field, type the existing password for the specifieduser ID.

5. In the New Password text field, type the new password for the specified userID.

6. In the Confirm New Password text field, type the password again.7. Click Apply.

pdadminTo change the password for the user using the pdadmin utility, log in to thedomain as a domain administrator and use the user modify command with thepassword option.

For example, to change the password for the user dlucas to newpasswd, enter thefollowing command:pdadmin sec_master> user modify dlucas password newpasswd


Setting user policyYou can change the user policy settings for specific users, such as passwordpolicies, login-failure policies, access policies, and account expiration policies usingWeb Portal Manager or the pdadmin utility.

Note:

v The valid range for numbers can be any number. However, use areasonable number for the task that you want to perform. For example, aminimum password length must be long enough to protect your systembut not so short as to make it easy for someone to determine yourpassword by trying different combinations.

v When defining the password policy, ensure that this definition complieswith the password policy of the underlying operating systems and userregistries.

v When using Tivoli Directory Server as your user registry, you can takeadvantage of its password history policy. For additional information aboutsetting the password history policy when using Tivoli Directory Server asyour user registry, see “Setting the password history policy” on page 361.

Web Portal ManagerTo change policy settings for a specific user, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click User → Search Users to display the User Search page.3. From the list of matching users, select the user whose policy needs to be

changed. The User Properties page for that user is displayed.4. Click the Policy tab.5. Modify the following policies as needed:

v For Max Login Failures, select Unset or Set to set or unset the maximumnumber of login failures before the account is no longer allowed toparticipate in the secure domain. If you select Set, either accept the defaultvalue of 10 or change the value to a number equal to or greater than zero.


v For Disable Time Interval, select Unset, Disable, or Set to set the time, inseconds, or to disable each user account when the maximum number of loginfailures is exceeded. If you select Set, either accept the default value of 180seconds or change the value to a number equal to or greater than zero.

v For Minimum Password Length, select Unset or Set to set the minimumnumber of characters required for the password. If you select Set, eitheraccept the default value of eight alphanumeric characters or change the valueto a number greater than zero.

v For Maximum Password Age, select Unset or Set to set the maximum time apassword can be used before it expires. The maximum password age isrelative to the last time the password was changed. If you select Set, eitheraccept the default value of 91 days (91-00:00:00) or change the value to anumber equal to or greater than zero. A value of 0 (000-00:00:00) indicatesthat the password never expires.

v For Minimum Password Alphas, select Unset or Set to set the minimumnumber of alphabetic characters required in a password. If you select Set,either accept the default value of four alphabetic characters or change thevalue to a number greater than zero.

v For Minimum Password Non-Alphas, select Unset or Set to set theminimum number of non-alphabetic characters required in a password. Ifyou select Set, either accept the default value of one non-alphabetic characteror change the value to a number greater than one.

v For Max Password Repeated Characters, select Unset or Set to set themaximum number of repeated characters allowed in a password. If youselect Set, either accept the default value of two repeated characters orchange the value to a number greater than two.

v For Password Spaces Allowed, select Unset, Yes, or No to determinewhether spaces are allowed in passwords. You can accept the default settingof Unset. You can change the value to Yes to allow spaces in passwords or toNo to not allow spaces in passwords.

v For Max Concurrent Web Sessions, select Displace, Unset, Unlimited, orSet to set the maximum number of concurrent Web sessions allowed. If youselect Set, type a number equal to or greater than one.

Note: This policy applies only to certain components. A Web session is a usersession that is maintained by the Web security solutions, such asWebSEAL and plug-in for Web Servers. Refer to the componentadministration guides to see if this setting is applicable and whetherspecific configuration options are required to enforce this policy.

v For Account Expiration Date, select Unset, Unlimited, or Set to set theaccount expiration date. You can accept the default setting of Unset. You canchange it to Unlimited or Set.If you select Set, type the four-digit year in the Year field.Either accept the default value of Jan 01-00:00:00 or change the value to thedate and time, specified as Month DD:hh:mm:ss. The hours must be enteredusing a 24-hour clock (for example, 09 for 9:00 a.m. or 14 for 2:00 p.m.).

v For Time of Day Access, select Unset or Set to set the time of day accesspolicy. If you select Set, either accept the default settings or change them.You can change these values:– Select the days of the week from the choices provided.– Select All Day or Between hours of.


If you select Between hours of, also select the Start Time. The start timeformat is specified as hours and minutes. The start time is expressed byusing a 24-hour clock.If you select Between hours of, also select the End Time. The end timeformat is specified as hours and minutes. The end time is expressed byusing a 24-hour clock.If you select Between hours of, also select Local Time or UTC Time. Thetime zone is local by default; UTC is Coordinated Universal Time.

6. Click Apply.

pdadminTo set or change user policy settings using the pdadmin utility, log in to thedomain as a domain administrator and use the policy set command.

For example, to set the maximum password age of 31 days 8 hours and 30 minutesfor user bsmith, enter the following command:pdadmin sec_master> policy set max-password-age 031-08:30:00 -user bsmith


Setting global user policyYou can change global user settings, such as password policies, login-failurepolicies, access policies, and account expiration policies using Web Portal Manageror the pdadmin utility.

Notes:

v The valid range for numbers can be any number. However, use areasonable number for the task that you want to perform. For example, aminimum password length must be long enough to protect your systembut not so short as to make it easy for someone to determine passwordsby trying different combinations.

v When defining the password policy, ensure that this definition complieswith the password policy of the underlying operating systems and userregistries.

v When using Tivoli Directory Server as your user registry, you can takeadvantage of its password history policy. For additional informationabout setting the password history policy when using Tivoli DirectoryServer as your user registry, see “Setting the password history policy” onpage 361.

Web Portal ManagerTo change global user settings, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click User → Show Global User Policy.3. For Max Login Failures, select Unset or Set to set or clear the maximum

number of login failures before the account is no longer allowed to participatein the secure domain. If you select Set, either accept the default value of 10 orchange the value to a number equal to or greater than zero.

4. For Disable Time Interval, select Unset, Disable, or Set to set the time, inseconds, or to disable each user account when the maximum number of loginfailures is exceeded. If you select Set, either accept the default value of 180seconds or change the value to a number equal to or greater than zero.


5. For Minimum Password Length, select Unset or Set to set the minimumnumber of characters required for the password. If you select Set, eitheraccept the default value of eight alphanumeric characters or change the valueto a number greater than zero.

6. For Maximum Password Age, select Unset or Set to set the maximum time apassword can be used before it expires. The maximum password age isrelative to the last time the password was changed. If you select Set, eitheraccept the default value of 91 days (91-00:00:00) or change the value to anumber greater than zero.

7. For Minimum Password Alphas, select Unset or Set to set the minimumnumber of alphabetic characters required in a password. If you select Set,either accept the default value of four alphabetic characters or change thevalue to a number greater than zero.

8. For Minimum Password Non-Alphas, select Unset or Set to set the minimumnumber of non-alphabetic characters required in a password. If you select Set,either accept the default value of one non-alphabetic character or change thevalue to a number greater than one.

9. For Max Password Repeated Characters, select Unset or Set to set themaximum number of repeated characters allowed in a password. If you selectSet, either accept the default value of two repeated characters or change thevalue to a number greater than two.

10. For Password Spaces Allowed, select Unset, Yes, or No to determine whetherspaces are allowed in passwords. You can accept the default setting of Unset.You can change the value to Yes to allow spaces in passwords or to No to notallow spaces in passwords.

11. For Max Concurrent Web Sessions, select Displace, Unset, Unlimited, or Setto set the maximum number of concurrent Web sessions to allow. If you selectSet, type a number equal to or greater than one.

Note: This policy applies only to certain components. A Web session is a usersession that is maintained by the Web security solutions, such asWebSEAL and plug-in for Web Servers. Refer to the componentadministration guides to see if this setting is applicable and whetherspecific configuration options are required to enforce this policy.

12. For Account Expiration Date, select Unset, Unlimited, or Set to set theaccount expiration date. You can accept the default setting of Unset. You canchange it to Unlimited or Set.If you select Set, type the four-digit year in the Year field.Either accept the default value of Jan 01-00:00:00 or change the value to thedate and time, specified as Month DD:hh:mm:ss. The hours must be enteredusing a 24-hour clock (for example, 09 for 9:00 a.m. or 14 for 2:00 p.m.).

13. For Time of Day Access, select Unset or Set to set the time of day accesspolicy. If you select Set, either accept the default settings or change them.You can change these values:v Select the days of the week from the choices provided.v Select All Day or Between hours of.

If you select Between hours of, also select the Start Time. The start timeformat is specified as hours and minutes. The start time is expressed byusing a 24-hour clock.If you select Between hours of, also select the End Time. The end timeformat is specified as hours and minutes. The end time is expressed byusing a 24-hour clock.


If you select Between hours of, also select Local Time or UTC Time. Thetime zone is local by default; UTC is Coordinated Universal Time.

14. Click Apply.

pdadminTo set or change global user settings using the pdadmin utility, log in to thedomain as a domain administrator and use the policy set command.

For example, to set a global user policy to a maximum password age of 31 days 8hours and 30 minutes, enter the following command:pdadmin sec_master> policy set max-password-age 031-08:30:00


Importing usersYou can import a user that exists in a user registry and make that user a TivoliAccess Manager user using Web Portal Manager or the pdadmin utility.

When a user is imported, the domain administrator assigns a user name, which issometimes referred to as a principal name. The user name must be unique withinthe domain because it is used by Tivoli Access Manager to identify this user.

Note: When ADAM is used as the user registry, you can import only existing usersdefined within the same ADAM partition in which Tivoli Access Managerwas configured.

Web Portal ManagerTo import a user that exists in a user registry and make that user a Tivoli AccessManager user, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click User → Import User.3. Type a User Id (for example maryj).4. Click Group Membership to search for groups in which the user can be a

member.5. Type a Registry UID. The registry UID specifies the location in the user

registry to be imported. For example: cn=maryj,o=ibm,c=us,dc=mkt. Lotus Notesusers require the full path name for the user being imported. For example: MaryJones/IBM/US

6. Select the Account Valid check box to indicate that the new user can participatein the domain. If this option is not selected, the new user account is not validand the user cannot log in.

7. Select the GSO User check box to indicate that the user can use the globalsign-on (single sign-on) for Tivoli Access Manager.

8. Select the Password Valid check box to force a password change the next timethe user logs in to the domain. If this option is not selected, the user isinformed that the password has expired.

9. Click Create.

A message is shown if the user ID is created.


pdadminTo import a user that exists in a user registry and make that user a Tivoli AccessManager user using the pdadmin utility, log in to the appropriate domain as adomain administrator and use the user import command to import the user.

For example, to import the user information for the user named maryj from theexisting user registry definition, enter the following command:pdadmin sec_master> user import –gsouser maryj "cn=Mary Jones,o=IBM,c=us,dc=mkt"

Note: When using an LDAP user registry and if necessary, the user informationthat is imported to the domain can be imported again to another domain.


Deleting a userYou can delete a user using Web Portal Manager or the pdadmin utility. When youdelete a user, this user is removed from all objects with which it is associated. Forexample, if this user is the only ACL entry that is associated with an ACL policy,no other user or group can manage this ACL policy. Before deleting a user, youmust validate that there are other users or groups that can manage this ACL policy.

Web Portal ManagerTo delete a user from a domain, complete the following steps:1. User Web Portal Manager to log in to the domain as a domain administrator.2. Click User → Search Users.3. Search for one or more user names to delete and click Search.4. Select the check boxes next to the user names to delete and then click Delete.5. From the Delete Selected Users page, click Delete Users to confirm the deletion

or click Delete Users and Registry Entries to also remove the registry entriesassociated with the selected users.

pdadminTo delete a user from the domain using the pdadmin utility, log in to the domainas a domain administrator and use the user delete command to delete a user. Anyresource credentials associated with a user account are automatically removedwhen the user account is deleted. If the user does not exist in the user registry, anerror is displayed.

For example, to delete the user named jdoe and the associated information fromthe user registry, enter the following command:pdadmin sec_master> user delete –registry jdoe


Managing groupsYou can perform the following group tasks:v “Creating a group” on page 155v “Listing groups” on page 155v “Importing groups” on page 156v “Deleting a group” on page 157



Creating a groupYou can create a group using Web Portal Manager or the pdadmin utility.

When a group is created, the domain administrator assigns a group name. Thegroup name must be unique within the domain because it is used by Tivoli AccessManager to identify this group.

Note: When Active Directory Application Mode (ADAM) is used as the userregistry, groups must be created within the same ADAM partition in whichTivoli Access Manager was configured.

For more information about groups, see “Creating groups” on page 190.

Web Portal ManagerTo create a group in the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Group → Create Group.3. Type a Group Name for the group (for example, sales).4. Optional: Type a Description for the group (for example, Sales).5. Type a Registry GID. The registry GID specifies the location in the user

registry where the new group is created. For example:cn=Sales,o=ibm,c=us,dc=mkt. Lotus Notes users require the full path name forthe group being created. For example: Sales/IBM/US.

6. Optional: Type the path in the Object Container field to the Tivoli AccessManager object space where the group is to be created.

7. Click Create.

The new group is displayed as a link. Select the link and the properties for thenew group are displayed.

pdadminTo create a group in the domain using the pdadmin utility, log in to the domain asa domain administrator and use the group create command to create a group andoptionally place this group in a group container object. If the container object doesnot currently exist, it is automatically created.

For example, to create the group named sales, enter the following command:pdadmin sec_master> group create sales "cn=sales,o=IBM,c=us,dc=mkt" Sales


Listing groupsYou can search for group names using Web Portal Manager or the pdadmin utility.

Web Portal ManagerTo search for and list up to a maximum of 100 groups, complete the followingsteps:


1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Search Groups.3. At the Group Search page, use the special character (*) to filter group names.4. Use the default value of 100 or type a Maximum Results number to limit the

number of group names that you want to view.5. Click Search to display a table of group names. Each group name is displayed

as a link.From the Group Search page, you can perform these tasks: create a group,delete one or more existing groups, and click the link to view group properties.

6. Use the default value of 15 group names per page, or click Options to enter thenumber of group names you want to view per page. Toggle back by clickingHide Options.

7. Use the default value of None, meaning that no text is used for filtering, or, clickFilters to find group names that contain, start with, or end with the text thatyou specify. Toggle back by clicking Hide Filters.

pdadminTo search for a list of groups using the pdadmin utility, log in to the domain as adomain administrator and use the group list command to list groups.

For example, to search for and list up to a maximum of 100 groups, enter thefollowing command:pdadmin sec_master> group list * 100


Importing groupsYou can import an existing group from a user registry into the domain and makethat group a Tivoli Access Manager group using Web Portal Manager or thepdadmin utility.

When a group is imported, the domain administrator assigns a group name. Thegroup name must be unique within the domain because it is used by Tivoli AccessManager to identify this group.

Note: When ADAM is used as the user registry, you can import only existinggroups defined within the same ADAM partition in which Tivoli AccessManager was configured.

Attention: If you import a dynamic group, ensure that the policy server isenabled for dynamic group support. For blade systems to benefit from dynamicgroup support, also enable this stanza entry on each blade system. For detailsabout enabling the policy server for dynamic groups, see “Enabling dynamic groupsupport” on page 158.

Web Portal ManagerTo import an existing group from a user registry into the domain and make thatgroup a Tivoli Access Manager group, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Group → Import Group.3. Type a Group Name for the group. For example, type sales.


4. Type a Registry GID. The registry GID specifies the location in the userregistry of the group to be imported. For example, typecn=sales,o=ibm,c=us,dc=mkt. Lotus Notes users require the full path name forthe group being imported. For example: sales/IBM/US.

5. Optional: Type the path in the Object Container field to the Tivoli AccessManager object space where the group is to be imported.

6. Click Import.

The new group is displayed as a link. Select the link to display the properties forthe new group.

pdadminTo import an existing group from a user registry into the domain and make thatgroup a Tivoli Access Manager group using the pdadmin utility, log in to thedomain as a domain administrator and use the group import command to importan existing group and optionally place this group in a group container object. Ifthe container object does not currently exist, it is automatically created.

For example, to import the existing group named "cn=sales,o=IBM,c=us,dc=mkt"from the user registry, enter the following command:pdadmin sec_master> group import sales "cn=sales,o=IBM,c=us,dc=mkt"

Note: The group information that is imported to the domain can be importedagain to another domain, if necessary.


Deleting a groupYou can delete a group using Web Portal Manager or the pdadmin utility. Whenyou delete a group, this group is removed from all objects with which it isassociated. For example, if this group is the only ACL entry that is associated withan ACL policy, no other user or group can manage this ACL policy. Before deletinga group in this case, you must validate that there are other users or groups thatcan manage this ACL policy.

Web Portal ManagerTo delete a group from the domain, complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Group → Search Groups.3. Search for one or more group names to delete and click Search.4. Select check boxes next to the group names to delete, and click Delete.5. From the Delete Selected Groups page, click Delete Groups to confirm the

deletion or click Delete Groups and Registry Entries to also remove theregistry entries associated with the selected groups.

pdadminTo delete a group from the domain using the pdadmin utility, log in to the domainas a domain administrator and use the group delete command to delete a group.

For example, to delete the group named sales and the associated information fromthe user registry, enter the following command:pdadmin sec_master> group delete –registry sales



Enabling dynamic group supportTo enable dynamic group support on the policy server and all servers wheredynamic groups are supported, use the pdadmin utility. The command you rundepends on the type of user registry.

LDAP registryFor LDAP registry users, modify the dynamic-groups-enabled entry in the [ldap]stanza of the ldap.conf file. To do so, edit the configuration files with a text editoror use the pdadmin utility as follows:pdadmin sec_master> config modify keyvalue set

"c:\Program Files\Tivoli\Policy Director\etc\ldap.conf"ldap" "dynamic-groups-enabled" yes

For configuration changes to take effect, you must restart the updated server.

Note: Dynamic groups are not supported for the ADAM registry.

Active DirectoryFor Active Directory registry users, modify the dynamic-groups-enabled entry inthe [uraf-registry] stanza in the activedir.conf and activedir_ldap.conf files. Todo so, edit the configuration files with a text editor or use the pdadmin utility asfollows:pdadmin sec_master> config modify keyvalue set

"c:\Program Files\Tivoli\Policy Director\etc\activedir.conf""uraf-registry" "dynamic-groups-enabled" yes

pdadmin sec_master> config modify keyvalue set"c:\Program Files\Tivoli\Policy Director\etc\activedir_ldap.conf""uraf-registry" "dynamic-groups-enabled" yes

Note: Do not change this value if Active Directory cannot handle dynamic groups.

For information about setting up your environment to enable an ActiveDirectory registry to handle dynamic groups, consult the Microsoft Web site.Microsoft supports Active Directory dynamic groups only for WindowsServer 2003 and beyond. For more information, see “Importing dynamicgroups to Tivoli Access Manager” on page 366.

For configuration changes to take effect, restart the server.


Chapter 12. Certificate and password management

This chapter describes how Tivoli Access Manager uses server-side and client-sidecertificates for authentication, key files and stash files, the configuration settings forthe default lifetime for both the certificates and the key file passwords, and theinitial configuration settings.

This chapter describes certificate and password management from the perspectiveof the administration C API runtime. However, Tivoli Access Manager provides aJava runtime for performing the same tasks. For more information about theadministration Java runtime and classes, see the IBM Tivoli Access Manager fore-business: Administration Java Classes Developer Reference and the IBM Tivoli AccessManager for e-business: Authorization Java Classes Developer Reference.

This chapter includes the following information:v “Initial configuration” on page 160v “Key file and stash file renewal information” on page 161v “Trust determination” on page 162v “Server certificate revocation” on page 164v “Additional key and stash file considerations” on page 165

Tivoli Access Manager can use Secure Sockets Layer (SSL) for encryption, systemauthentication, and application-level authentication. When installed andconfigured, SSL uses certificates for operation that help to ensure a secureenvironment. Tivoli Access Manager can also use Transport Layer Security (TLS)version 1 instead of SSL. To use TLS, Federal Information Processing Standards(FIPS) must be enabled.

In the secure environment, the policy server acts as the certificate authority (CA)and is responsible for the creation and renewal of certificates. The Tivoli AccessManager runtime package (PDRTE) relies on only SSL server-side authenticationand does not require a client-side certificate. However, all the Tivoli AccessManager servers, such as the policy server, the authorization server, the policyproxy server, and the resource manager servers rely on client-side certificates tooperate.

The Tivoli Access Manager servers use certificates to authenticate themselves. Forexample, when the authorization server wants to communicate with the policyserver, it presents its client-side certificate. In this example, the policy server can beconsidered the server and the authorization server as the client. The policy serververifies that the certificate is valid and is signed by a trusted signer. In this case,the trusted signer is the policy server itself, using the Tivoli Access Managercertificate authority (PDCA) certificate. The authorization server does the same forthe certificate presented by the policy server. As part of the Tivoli Access Managerapplication-level authentication, after the policy server determines that theauthorization server certificate is good, it tries to map that certificate to a TivoliAccess Manager user. If the authentication succeeds, the servers can communicate.

The certificates used by Tivoli Access Manager are kept in key files. Key files have a.kdb extension (or .ks extension for Java keystores). Key files must be secured andprotected by the strictest operating system controls available, because they contain


the private keys for the certificates. For example, the key file for the policy serveris ivmgrd.kdb and, by default, it can be read and written to by only the ivmgruser.

The certificate files in a directory need to be accessible to the user ivmgr (or allusers). Ensure that the ivmgrd.kdb file and the directory or folder that contains theivmgrd.kdb file is accessible by the user ivmgr (or all users). In other words,ensure that these users have the appropriate permissions for this file.

Furthermore, to facilitate unattended server operation, there are files that containan obfuscated (not encrypted) version of the password to the key files. Theseversions are called stash files, and the stash files are denoted by a .sth file extension.Java key files that are generated by Tivoli Access Manager do not havecorresponding stash files. Again, these stash files must be secured using nativestandard operating system measures. For the policy server, the stash file isivmgrd.sth and its permissions are the same as the ivmgrd.kdb key file.

For security reasons, both the certificates and the key file passwords can be set toexpire after a configurable amount of time. The default lifetime for a certificate isfour years. The default lifetime for a key file password is 183 days. The fixedlifetime for the PDCA certificate is 20 years. By default, the Tivoli Access Managerservers refresh the certificates and passwords automatically while they are running.The refresh process reissues a new certificate with a new lifetime and generates anew password with the configured lifetime.

The Tivoli Access Manager calculates the life span of the certificate when you openthe PDContext. When opening the security context, the Tivoli Access Managerverifies the need to refresh the context. If there is a need to refresh the certificate,then Tivoli Access Manager creates an SSLContext with the new certificate andprocesses the request.

If the servers are not running within a specified time frame, their certificates orpasswords can expire. In this case, a manual refresh is necessary. Furthermore, if acertificate or a password or the entire key file is damaged, a manual refresh iswarranted to keep the Tivoli Access Manager domain secure. For informationabout performing a manual refresh, see “Key file and stash file renewalinformation” on page 161.

Initial configurationThe certificates used by the Tivoli Access Manager servers are created as part oftheir initial configurations. In a brand-new Tivoli Access Manager installation, thepolicy server is the first server configured. As part of its configuration, the PDCAcertificate is created, and a personal certificate that is used by the policy server iscreated and signed by the PDCA certificate. Both of these certificates are located inthe ivmgrd.kdb key file. Also, as part of the policy server configuration, the TivoliAccess Manager runtime key file pd.kdb is created, and the PDCA certificate isinserted into it as a trusted certificate.

When new systems are added to the Tivoli Access Manager domain, the TivoliAccess Manager runtime package is configured first. Again, as part of thisconfiguration, the system pd.kdb and pd.sth files are created and the PDCAcertificate is included in the key files as a trusted certificate.

When new resource managers, such as WebSEAL, are configured, the svrsslcfgutility or an equivalent application programming interface (API) is run. This utility


creates a key file (such as pdacld.kdb) and places a personal certificate for theserver in it. The utility also inserts the PDCA certificate as a trusted certificate inthe key file. These two certificates are obtained from the policy server and aretransported to the client machine over SSL using the Tivoli Access Managerruntime key file.

The configuration files and certificate-related stanza entries, such as the configuredkey file and the configured stash files, are discussed in Appendix B, “Configurationfile reference,” on page 203.

Key file and stash file renewal informationThe following table lists the servers and their associated key files and stash files. Italso describes how they are created and refreshed.

Table 6. Server key and stash files

Server Key and stash files How createdHow automatically

updatedHow manually

updated

Tivoli AccessManager runtimepackage

pd.kdb and pd.sth(does not contain aclient-side certificate)

During runtimeconfiguration

Running thepdadmin1 utility

Running thebassslcfg utility withthe –chgpwd option

Policy server ivmgrd.kdb andivmgrd.sth

During serverconfiguration

Running thepdmgrd1,2 command

Running themgrsslcfg utility withthe -chgpwd3 and-chgcert3 options

Proxy server pdmgrproxyd.kdband pdmgrproxyd.sth

During serverconfiguration

Running thepdmgrproxyd1

command

Running the svrsslcfgutility with the–chgpwd4 and the–chgcert5 options

Authorization server ivacld.kdb ivacld.sth During serverconfiguration

Running the pdacld1

commandRunning the svrsslcfgutility with the-chgpwd4 and-chgcert5 options

Resource manager The key files andstash file names areresourcemanager-dependent,and the file name isconfigurable.6

Running the svrsslcfgutility with the–config option

Running an instanceof the resourcemanager1

Running the svrsslcfgutility with the–chgpwd7 and–chgcert8 options

Table notes:1 Automatic certificate and password refresh can be turned off by setting the

ssl-auto-refresh stanza entry to no in the [ssl] stanza in the respectiveconfiguration file.

2 Because the policy server also acts as the CA for the secure domain, it must berecycled after a refresh. It continues to operate normally until it is recycled,except it cannot issue or renew certificates for other servers until it is recycled.The policy server log file contains a message stating when the server needs tobe restarted.

3 Before running this command, the policy server must be stopped.4 Before running this command, the authorization server must be stopped.5 Before running this command, the policy server must be running, and the

authorization server must be stopped.6 Java resource managers have an equivalent to key files, known as Java

keystores, where the application personal certificate and the PDCA certificate

Chapter 12. Certificate and password management 161

are stored. Java resource managers do not have a stash file equivalent. Thenames of keystores are created by running the Java SvrSslCfg class with the–action config option.

7 Before running this command, the resource manager must be stopped.8 Before running this command, the policy server must be running, and the

resource manager must be stopped.

Trust determinationEach key file contains a list of trusted certificate authorities (CAs). For TivoliAccess Manager, each key file except for ivmgrd.kdb key file has the Tivoli AccessManager certificate authority (PDCA) certificate as a trusted CA. This CA is thecertificate that is used to sign all the other Tivoli Access Manager certificates. ThisCA is created during policy server configuration and is placed in the ivmgrd.kdbfile.

It is important to protect the ivmgrd.kdb file to keep the private key in the PDCAcertificate from being compromised. If it is compromised, it must be regenerated. Ifthe compromise happens, each key file and each certificate in the domain needs tobe regenerated.

Use the following process for regenerating these files in the domain:1. Regenerate the PDCA certificate and policy server certificate by generating a

new ivmgrd.kdb file using the mgrsslcfg –config utility. (The policy servermust be stopped.)

2. Regenerate the Tivoli Access Manager runtime certificates on the policy serverby running the bassslcfg –config utility.

3. After obtaining the CA certificate, you can choose to automatically downloadthe CA certificate or manually copy the file.v If auto-download is set to on (enabled) and the policy server is running, the

CA certificate is automatically obtained. By default, auto-download isenabled.

v If auto-download is set to off (disabled), the base-64 DER encoded version ofthe PDCA certificate must be copied to the machine. This file is stored aspdcacert.b64 on the policy server.

4. On each runtime machine, run the bassslcfg –config utility.5. On each authorization server in the domain, regenerate its key files by running

the svrsslcfg –config utility. (The policy server must be running.) Thiscommand updates both the server certificate for the authorization server and itstrusted certificate (the new PDCA certificate).

6. On each resource manager in the domain, regenerate its key files by runningthe svrsslcfg –config utility. (The policy server must be running.) Thiscommand updates both the server certificate for the authorization server and itstrusted certificate (the new PDCA certificate).

From the Java perspective, the Tivoli Access Manager runtime also stores thePDCA certificate. If the PDCA certificate is compromised and must be regenerated,all servers that are configured to use Tivoli Access Manager Runtime for Java mustbe reconfigured. All resource managers that were previously configured with theSvrSslCfg class must also be reconfigured.


Reconfiguring the PDCA on the policy serverWhen the certificate is compromised or has expired, you need to reconfigure thePDCA on the policy server. To reconfigure the PDCA, complete the followingsteps:1. Stop all Tivoli Access Manager services that are running on the machine by

entering the following command:pd_start stop

2. Change to the directory where the key files are located. Assuming the defaultdirectory on a Linux or UNIX operating system, enter the following command:cd /var/PolicyDirector/keytab

3. Rename the ivmgrd.kdb key file, ivmgrd.sth stash file, and pdcacert.b64 PDCAfile by entering the following commands:mv ivmgrd.kdb ivmgrd.kdb.oldmv ivmgrd.sth ivmgrd.sth.oldmv pdcacert.b64 pdcacert.b64.old

4. Change to the PolicyDirector/sbin directory. Assuming the default directory ona Linux or UNIX operating system, enter the following command:cd /opt/PolicyDirector/sbin

5. Configure the policy manager server to create a new key file and stash file byentering the following command:mgrsslcfg -config

6. Change the ownership of the newly created key file, stash file, and certificate toivmgr:ivmgr by entering the following commands:chown ivmgr:ivmgr /var/PolicyDirector/keytab/ivmgrd.kdbchown ivmgr:ivmgr /var/PolicyDirector/keytab/ivmgrd.sthchown ivmgr:ivmgr /var/PolicyDirector/keytab/pdcacert.b64

7. Configure the Tivoli Access Manager runtime using the bassslcfg –configutility. For example, enter the command but replace the values for the –c and–h options.bassslcfg -config -h myhostname -c /var/PolicyDirector/keytab/pdcacert.b64

8. Start the Tivoli Access Manager services on the machine by entering thefollowing command:pd_start start

The management environment must be running.

After regenerating the PDCA certificate on the policy server, you might need tocopy the PDCA certificate to each runtime machine in the domain. Ifauto-download is enabled, you do not need to copy the file.

Reconfiguring the PDCA on the runtime machinesAfter reconfiguring the policy server and transferring the newly generated PDCAcertificate to each runtime machine, complete the following steps on each runtimemachine:1. Stop all Tivoli Access Manager services that are running on the machine by

entering the following command:pd_start stop

2. Change to the PolicyDirector/sbin directory. Assuming the default directory ona Linux or UNIX operating system, enter the following command:cd /opt/PolicyDirector/sbin


3. Configure the Tivoli Access Manager runtime using the bassslcfg –configutility. For example, enter the command but replace the values for the –c and–h options.bassslcfg -config -h myhostname -c /var/PolicyDirector/keytab/pdcacert.b64

4. Start the Tivoli Access Manager services on the machine by entering thefollowing command:pd_start start

Transferring the PDCA certificate to other machinesAfter regenerating the PDCA certificate, you might need to transfer it to eachmachine in the domain. When auto-download is disabled, you need to copy thefile manually to each machine. If the File Transfer Protocol (FTP) is supported inyour environment, you can use one of the following FTP option:v Use the put command from the policy server to transfer the certificate to the

other machinev Use the get command from the other machine to retrieve the certificate from the

policy server

The following steps assume that the pdcacert.b64 certificate is retrieved from thepolicy server:1. Connect to the runtime machine by opening an FTP session. To illustrate,

pdruntime1 is the name of the runtime machine.ftp pdruntime1

2. Log in to the remote machine using the appropriate user ID and password.3. Change to the directory where the certificate is stored. Assuming the default

directory on a Linux or UNIX operating system, enter the following command:cd /var/PolicyDirector/keytab

4. Indicate that the file to be transferred is a text (ASCII) file by entering thefollowing command:ascii

5. To view the transfer process visually, enter the following command:hash

6. Start the transfer by entering the following command:put pdcacert.b64

7. After the transfer completes, end the FTP session by entering the followingcommand:quit

Server certificate revocationIf the certificate on a C-based resource manager is compromised, you can run thesvrsslcfg –chgcert utility to replace the existing server certificate and update thePDCA certificate. For Java-based resource managers, thePDAppSvrConfig.replaceAppSvrCert() method must be used.

You can also unconfigure and reconfigure the server by running the svrsslcfg–unconfig and svrsslcfg –config utilities. Make sure that the policy server isrunning. These commands update both the server certificate for the authorizationserver and its trusted certificate (the new PDCA certificate). Similarly, a Java-basedresource manager can be unconfigured and reconfigured using the Java SvrSslCfgclass.


Additional key and stash file considerationsAdditional considerations for key file and stash file renewal include:v When a certificate and the password to the key file containing that certificate are

both expired, the password must be refreshed. For example, for theauthorization server, run the svrsslcfg –chgpwd utility and then the svrsslcfg–chgcert utility. You must run these utilities, because a valid password is neededto open the key file to obtain the certificate.

v The value for the lifetime of a certificate is controlled by the value of thessl-cert-life entry in the [ssl] stanza of the ivmgrd.conf file when the policyserver is started. Any certificates that are issued or renewed use this value. Toincrease or decrease this value, change the value and restart the policy server.The new value is in effect only for certificates that are issued or renewed fromthat point onward. The actual time used is the lesser of the value specified in theivmgrd.conf configuration file and the number of days before the policy serverCA certificate expires.

v For automatic password renewal, the value for the lifetime of a password iscontrolled by the value of the ssl-pwd-life entry in the [ssl] stanza that is ineffect when the server is started. For manual password renewal, the value isdictated by the value supplied to the svrsslcfg –chgpwd utility. This value isalso written into the appropriate configuration file.

v The key file password refresh occurs after half the lifetime of the passwordexpiration date. If the blade server is not running during the second half of thepassword life, an ACL update is unable to refresh the password because thisoperation uses the connection from the management server to the blade server,using the SSL connection protected by the certificate (which, in turn, is protectedby the password).

v Tivoli Access Manager servers can also communicate with Lightweight DirectoryAccess Protocol (LDAP) using SSL. In the standard configuration, thiscommunication uses server-side authentication only. Therefore, the Tivoli AccessManager server needs only the CA certificate that signed the LDAP servercertificate or the LDAP server certificate itself. The expiration and managementof these certificates are not handled by Tivoli Access Manager. However, it ispossible to include the LDAP certificate in the key file for a resource manager byrunning the svrsslcfg –config utility with the -C option.For certificates that are not managed by Tivoli Access Manager, these certificatesmust be refreshed by using the same mechanism used to create the initialcertificate. The new certificate can be replaced in the key file by running thesvrsslcfg –modify –C new_cert_filename utility.

v After running the bassslcfg –config utility, you might need to change thepermissions on the pd.kdb and pd.sth files.

v The configuration files mentioned are found in the install_dir/etc directory. Forexample, on an AIX® system, the policy server, authorization server, and runtimeconfiguration files are /opt/PolicyDirector/etc/ivmgrd.conf,/opt/PolicyDirector/etc/ivacld.conf, and /opt/PolicyDirector/etc/pd.conf.Similarly, the key files and stash files can be found in the install_dir/keytabsdirectory.

v Tivoli Access Manager does not distinguish between export and domesticencryption. For Java-based encryption, the strength is regulated by thejurisdiction files that are present in the Java runtime environment. There is noset length for keys generated by the Tivoli Access Manager runtime.

v Both the public keys that are included in certificates and the private keys thatmight be stored in key files have key lengths. The maximum key length is 2048


bits. Public keys having 2048 bit key lengths can be generated by using theconfiguration utilities (bassslcfg, mgrsslcfg, or svrsslcfg).


Chapter 13. Server management

This chapter provides detailed information for performing general administrationand configuration tasks on the Tivoli Access Manager servers.

This chapter contains the following information:v “Tivoli Access Manager servers”v “Tivoli Access Manager utilities” on page 170v “Tivoli Access Manager servers tasks” on page 170v “Server configuration file tasks” on page 172v “Policy server administration tasks” on page 174

Tivoli Access Manager serversTivoli Access Manager consists of the following server processes, or daemons:

pdmgrdThe server process for the policy server.

pdacldThe server process for the authorization server.

pdmgrproxydThe server process for the policy proxy server

The policy server manages the policy database, also called the master authorizationdatabase, and maintains location information about other Tivoli Access Managerservers in the domain. There must be at least one policy server defined for eachdomain.

Web PortalManager

Masterauthorization

database

Userregistry

Policy server

Authorizationserver

Replicaauthorization

database

Figure 18. Tivoli Access Manager server components


The authorization server allows other applications to make authorization calls toTivoli Access Manager using the authorization application programming interface(API). The authorization server also acts as a logging and auditing collection serverto store records of server activity.

The policy proxy server helps support several network deployment strategies forthe policy server and the resource managers. A resource manager can be any serveror application that uses the Authorization API to process client requests for accessto resources, such as WebSEAL servers or Authorization API applications.

Proxy serverA policy proxy server is a server that acts as an intermediary between a less trustednetwork and a more trusted network so that the enterprise can ensure security,administrative control, and caching service. A policy proxy server is associatedwith or part of a gateway server that separates the enterprise network from theoutside network and a firewall server that protects the enterprise network fromoutside intrusion. In a Tivoli Access Manager environment, the policy proxy serverruns on behalf of the policy server for a given number of resource manager andadministrative tasks, such as the pdadmin commands.

The policy proxy server serves many important functions in a Tivoli AccessManager environment. The proxy can be used to terminate any connections from aless trusted network and to pass those requests to a policy server in a more trustednetwork using a different connection. This protects the policy server in the moretrusted network from denial-of-service attacks and other similar attacks. In thisdeployment scenario the proxy is deployed in what is commonly called thedemilitarized zone (DMZ).

Also, the proxy is useful in a wide-area network (WAN) deployment where thepolicy server and several applications are deployed at separate locations across aslow connection. Typically this happens when the policy server and theapplications are deployed in different geographical locations. If a proxy isdeployed on the same network as the applications and the applications areconfigured to go through the proxy, only the proxy contacts the policy serverinstead of each application. This configuration is important for the followingreasons:v The policy proxy server can be configured to cache security policy such that

when a policy update occurs at the policy server, only one copy of the policy istransmitted from the policy server to the proxy. The proxy then provides thepolicy to all the applications. If the proxy was not there, each individualapplication would request and receive the policy from the policy server,significantly increasing the network traffic.

v This configuration can also improve security because firewalls between thelocations can be configured to only allow the proxy to contact the policy serverand not the applications.

Figure 19 on page 169 shows the interaction between applications, the policy proxyserver, and the policy server.


Server dependenciesTake the following dependencies into account during your server configuration:v There must be at least one instance of the policy server.v There must be at least one policy server defined. You can have a single policy

server and create as many domains as you want. When a domain is created, aseparate policy database is also created for each domain. The single policy servercan access any of the distinct policy databases.

v The policy server manages the policy database.v There must be only one policy database (master authorization database) in a

domain.v The policy database must reside on a highly available policy server with a

robust file system.v Each policy database is subject to a regular backup procedure. The administrator

can specify the location for the backup files.v The policy servers provide authorization database replication services to all

other Tivoli Access Manager servers in the domain running in local cache mode.v Each resource manager, such as Tivoli Access Manager WebSEAL, Tivoli Access

Manager for Business Integration, or Tivoli Access Manager for OperatingSystems, applies security policy based on information from either the policydatabase or from a replicated authorization database.

InternetInternet

Central Office

Branch Office

Subnet DMZ

Policy Proxy Server

Internal Network

Policy Server

Policy Proxy ServerApplication Application Application

Firewall

Figure 19. Proxy server

Chapter 13. Server management 169

Tivoli Access Manager utilitiesThe Tivoli Access Manager utilities are discussed in detail in the IBM Tivoli AccessManager for e-business: Command Reference. The table at the beginning of the utilitiessection lists available utilities and their purposes.

The pdadmin utility, which is also discussed in IBM Tivoli Access Manager fore-business: Command Reference, provides commands that assist in troubleshootingproblems. For example, the pdadmin utility includes the server task stats andserver task trace commands that allow you to enable statistics gathering andcapture information about error conditions. In addition, the IBM Tivoli AccessManager for e-business: Troubleshooting Guide provides further diagnostic informationfor using the Tivoli Access Manager pdadmin utility and other utilities.

Tivoli Access Manager servers tasksThis section describes the following server processes:v “Starting and stopping servers on Linux and UNIX operating systems”v “Starting and stopping servers on Windows operating systems” on page 171

Starting and stopping servers on Linux and UNIX operatingsystems

Server processes are normally enabled and disabled through automated scripts thatrun at system startup and shutdown.

In Linux and UNIX environments, you can also use the pd_start utility tomanually start and stop the server processes. This technique is useful when youneed to customize an installation or when you need to perform troubleshootingtasks. You can run scripts only on the local machine.

The syntax for the pd_start utility is as follows:# pd_start {start|restart|stop|status}

You can run the pd_start utility from any directory. This utility is located in thefollowing directory:/opt/PolicyDirector/bin/

Starting the Tivoli Access Manager servers using the pd_startutilityUse the pd_start utility to start all Tivoli Access Manager servers not currentlyrunning on a particular machine:# pd_start start

This utility waits until all servers have started before returning the prompt.

Starting individual servers manuallyYou can manually start the servers individually by running the server-specificutilities.

You must run the start commands as an administration user, such as root.

Start the Tivoli Access Manager servers in the following order:1. For the policy server, enter the following command:


install_path/bin/pdmgrd

2. For the policy proxy server, enter the following command:install_path/bin/pdmgrproxyd

3. For the authorization server, enter the following command:install_path/bin/pdacld

Restarting the Tivoli Access Manager servers using the pd_startutilityUse the pd_start utility to stop all Tivoli Access Manager servers on a particularmachine and then restart the servers:pd_start restart

This utility waits until all servers have started before returning the prompt.

Stopping the Tivoli Access Manager servers using the pd_startutilityUse the pd_start utility to stop all Tivoli Access Manager servers on a particularmachine in the correct order:pd_start stop

This utility waits until all servers have stopped before returning the prompt.

Displaying server status using the pd_start utilityUse the pd_start command to display server status:pd_start status

Tivoli Access Manager Servers:Server Enabled Running

pdmgrd yes yeswebseald no nopdacld yes nopdmgrproxyd no no

Starting and stopping servers on Windows operating systemsOn Microsoft Windows operating systems, use the Services window that isaccessed from the Control Panel window to start and stop the server processesmanually and to control whether these servers are started when the system isbooted. This capability can be useful when customizing an installation or whentroubleshooting problems. Administrative privileges are required to use this utility.

You can start and stop all Tivoli Access Manager servers, or you can start and stopthem individually. The servers must be stopped and started in the correct order.

The servers must be started in the following order:1. Policy server2. Proxy server3. Authorization server

The servers must be stopped in the following order:1. Authorization server2. Proxy server3. Policy server


The AutoStart Service automatically starts each of the Tivoli Access Managerservers whenever the Startup Type is set to Automatic. After the servers start, theAutoStart Service exits.

To prevent automatic starting of a Tivoli Access Manager server by the AutoStartService, use the startup properties to set that server Startup Type to Disabled.

Starting the Tivoli Access Manager servers from the ServiceswindowYou can also use the Services Control Panel to manually start the individualservers:1. From the Start menu, select Settings � Control Panel.2. Double-click Administrative Tools.3. Double-click Services.4. From the Name column, right-click the Tivoli Access Manager servers to start,

and click Start.

Note: The servers must be started in the following sequence:v Policy serverv Proxy serverv Authorization server

Repeat the last step until all servers are started.

Stopping the Tivoli Access Manager servers from the ServiceswindowYou can also use the Services Control Panel to manually stop the individualservers:1. From the Start menu, select Settings � Control Panel.2. Double-click Administrative Tools.3. Double-click Services.4. From the Name column, right-click the Tivoli Access Manager servers to stop,

and click Stop.

Note: The servers must be stopped in the following sequence:v Authorization serverv Proxy serverv Policy server

Repeat the last step until all servers are stopped.

Server configuration file tasksYou can use the server configuration files to customize the operation of TivoliAccess Manager and its servers. Various server configurations are discussed inAppendix B, “Configuration file reference,” on page 203.

Changing configuration settingsThe configuration files, stanzas, and stanza entries are described in Appendix B,“Configuration file reference,” on page 203. To change a configuration setting,complete the following steps:


1. Make a backup copy of the configuration file that you plan to modify. Having abackup copy allows you to return the configuration file to a known workingstate, if you encounter an error.

2. Stop the Tivoli Access Manager servers that are affected.3. Use one of the following mechanisms to modify the configuration file:

v Use the pdadmin config commands to modify the configuration file.v Use the appropriate configuration tool for your server to change the

configuration settings:– For the ivmgrd.conf file, use the mgrsslcfg utility.– For the pd.conf file, use the bassslcfg utility.– For all other configuration files, use the svrsslcfg utility.

Note: Many stanzas or values are created or modified only by using TivoliAccess Manager configuration utilities. Some values are completedautomatically after the configuration is completed. Do not modify thesevalues.

4. Start the Tivoli Access Manager servers that are affected.

For example, if you want to change the ivmgrd.conf file, you must stop the policyservers, make the change, and then restart all the policy servers for the change tobecome effective.

Automating server startup at boot timeStanza entries for automating server startup are located in the [pdrte] stanza ofthe pd.conf configuration file.

By default, the pd.conf file is installed at the following location for Linux andUNIX operating systems:/opt/PolicyDirector/etc/pd.conf

By default, the pd.conf file is installed at the following location for Windowsoperating systems:c:\Program files\tivoli\Policy Director\etc\pd.conf

Policy serverWhen the PDMgr package is installed, the policy server automatically starts aftereach system reboots:[pdrte]boot-start-ivmgrd = yes

To prevent the policy server from automatic startup, set:boot-start-ivmgrd = no

Authorization serverWhen the PDAcld package is installed, the authorization server automaticallystarts after each system reboots:[pdrte]boot-start-ivacld = yes

To prevent the authorization server from automatic startup, set:boot-start-ivacld = no


Proxy serverWhen the PDMgrProxyd package is installed, the policy proxy server automaticallystarts after each system reboots:[pdrte]boot-start-pdmgrproxyd = yes

To prevent the policy proxy server from automatic startup, set:boot-start-pdmgrproxyd = no

Policy server administration tasksThe policy server manages the policy database (or databases), and maintainslocation information about other Tivoli Access Manager servers in each domain.The policy server typically requires little administration or configuration. Thissection describes configuration tasks available to the administrator.v “Replicating the authorization database”v “Setting the number of update-notifier threads” on page 175v “Setting the notification delay time” on page 176

Replicating the authorization databaseA Tivoli Access Manager domain administrator can make security policy changesto a domain at any time. A primary responsibility of the policy server is to makethe necessary adjustments to the domain master authorization database to reflectthese changes.

When the policy server modifies the master authorization database, it can send outnotification of this change to all resource manager servers (with replica databases).The authorization servers must then request a database update from the policyserver.

Note: Additionally, resource manager servers can check for database updates bypolling the policy server at regular intervals. Polling configuration for aWebSEAL client, for example, is explained in the IBM Tivoli Access Managerfor e-business: WebSEAL Administration Guide.

Tivoli Access Manager allows you to configure update notifications from the policyserver to be an automatic process or a manually controlled task. Theauto-database-update-notify stanza entry is located in the [ivmgrd] stanza of theivmgrd.conf configuration file. By default, the stanza entry value is set to yes(update notification is automatically performed by the policy server):[ivmgrd]auto-database-update-notify = yes

This automatic setting is appropriate for environments where database changes arefew and infrequent. When you configure update notification to be automatic, youmust also correctly configure the max-notifier-threads and notifier-wait-timestanza entries. For more information about these entries, see “Setting the numberof update-notifier threads” on page 175 and “Setting the notification delay time”on page 176.

When you configure update notification to be manual, manual application of theserver replicate command controls this event.[ivmgrd]auto-database-update-notify = no


This manual setting is appropriate for environments where database modificationsoccur frequently and involve substantial changes. In some cases several databasemodifications can generate many update notifications that soon become obsoletebecause of the continuing changes to the master database. These obsoletenotifications cause unnecessary network traffic and impair the performance ofresource managers because of continued requesting and processing of policyupdates.

The manual control of update notification allows you to complete the process ofmodifying the master authorization database before update notifications are sentout to authorization servers with database replicas.

In manual mode, update notification uses the notifier thread pool (as it does inautomatic mode). Therefore, the manual mode setting is affected by themax-notifier-threads stanza entry value. For more information about this stanzaentry, see “Setting the number of update-notifier threads.”

Using the server replicate commandWhen you configure update notification to be manual, manual application of theserver replicate command controls this event.pdadmin_secmaster> server replicate -server test_server

When the -server option (test_server in the previous example) is specified, onlythat server is notified of changes to the master authorization database. A responseis returned indicating the success or failure of the notification and the replication.

When the -server option is not specified, all configured resource manager serversreceive update notifications. A successful response indicates only that the policyserver has begun sending out update notifications. The response does not indicatesuccess or failure of the actual notification and replication processes.

The authorization required to run this command is the s action bit on the/Management/Server object.

For more information about the server replicate command, see the IBM TivoliAccess Manager for e-business: Command Reference.

Setting the number of update-notifier threadsThe policy server is responsible for synchronizing all database replicas in thedomain. When a change is made to the master database, notification threadsannounce this change to all replicas configured to receive update notifications.Each replica must then download the new information or the changes from themaster.

The policy server configuration file, ivmgrd.conf, contains a stanza entry for settingthe maximum number of update-notifier threads. This pool of threads allowssimultaneous (parallel) notification.

For example, to concurrently notify 30 replicas of a database change, the threadpool must be set to at least 30. If there are more than 30 replicas, another round ofnotifications occurs (in this example, 30 at a time). All replicas are guaranteed to benotified, regardless of the value of this stanza entry.

The performance goal of the update-notifier threads value is to announce adatabase change as quickly as possible. Generally the value must be set to equal


the number of existing replicas. This results in the performance advantage of asingle pool of threads quickly accomplishing the notification task to all replicas atonce.

The default event notifier thread pool is set as the following:[ivmgrd]max-notifier-threads = 10

When the auto-database-update-notify stanza entry is set to yes, you mustcorrectly configure this stanza entry and also the notifier-wait-time stanza entry.See also “Setting the notification delay time.”

Setting the notification delay timeWhen the policy server is instructed to make a change to the master authorizationdatabase, it waits for a default period of time before sending out notifications todatabase replicas. The default time delay is set at 15 seconds. This time delay isreset with each subsequent change to the database.

The purpose of the time delay is to prevent the policy server from sendingindividual replica notifications for each change in a series of database changes. Thetime delay helps to ensure optimal performance of the Tivoli Access Managersystem.

This performance feature is particularly important for environments where batchchanges are made to the authorization database. It is not efficient for policychanges to be sent to database replicas until all changes are made.

You can override this default notification time delay by changing thenotifier-wait-time entry value in the [ivmgrd] stanza of the ivmgrd.confconfiguration file. For example:[ivmgrd]notifier-wait-time = 20

By default, the value is set to 15 seconds.

When the auto-database-update-notify entry is set to yes, you must configurethis entry and the max-notifier-threads entry. See also “Setting the number ofupdate-notifier threads” on page 175.


Chapter 14. High availability of the policy server

This chapter provides information on ensuring that Tivoli Access Managerprovides high availability for the policy server should a server failure occur. Thischapter describes how Tivoli Access Manager supports the replication capability ofthe LDAP directory server to ensure that its data is always available.

This chapter includes the following information:v “Data integrity”v “Primary and replica LDAP servers”v “Active and passive policy servers”v “High availability management” on page 178

Data integrityYou should ensure that the data that is needed by Tivoli Access Manager is alwaysavailable. To ensure data redundancy, all data should be stored on data devicesthat are Redundant Array of Independent Disks (RAID) secured.

Authorization information and decision making can be off-loaded to authorizationservers. All data should be subject to a robust backup process to ensure that youcan recover the data in the event of a hardware or software error. The pdbackuputility provides backup, restore, and extract capabilities for Tivoli Access Managerdata. See IBM Tivoli Access Manager for e-business: Command Reference for moreinformation on this utility.

Primary and replica LDAP serversTivoli Access Manager allows primary and replica LDAP servers. The replicaLDAP server, on a different node, can assume LDAP server operations if theprimary LDAP server fails.

During failover, no write operations can occur. Only read-only LDAP serveroperations are permitted during failover.

Refer to the LDAP server documentation for complete information about highavailability of LDAP servers.

Active and passive policy serversThe policy server manages the master policy database and the policy databases forthe other secure domains. The policy server also maintains location informationabout other servers in the domain. When the policy server fails or when thesystem on which the policy server is located become unavailable, an outage mightresult because of the lack data redundancy.

To provide the redundancy for the shared data and for the functions that areprovided by the Tivoli Access Manager policy server, you can install and configurea primary policy server and a standby policy server. The standby server takes overpolicy server functions in the event of a system or primary policy server failure.


The standby policy server acts as the primary policy server until the originalprimary policy server is up and running again. The standby server reverts back toserving as the failover server.

If you plan to set up a primary and standby policy server, the following rulesapply:v A 2-node IBM AIX High-Availability Cluster Multiprocessing (HACMP)

environment consisting of one active server and one standby server was tested.Therefore, IBM supports only an AIX HACMP version 5.1 or later 2-nodeenvironment.

v A primary and a standby policy servers must be installed and configured onseparate machines, and both policy servers must be within the AIX HACMPcluster environment.

v The user registry servers (such as an LDAP server, Active Directory, or LotusDomino) must be on a machine other than the machines where the primary andstandby policy servers are installed.

v Back up any shared data or any shared policy database before configuring theprimary and standby servers to the shared file system.

v Each AIX system must have access to a shared disk array that is configured fordata redundancy.

v The primary and a standby policy server must be configured to the shared filesystem, and the shared file system must be mountable by each server.

v Both the policy database and the configuration files, which are used by thepolicy server, must be located on a shared disk array.

Follow the procedure in the IBM Tivoli Access Manager for e-business: InstallationGuide for setting up a policy standby server.

High availability managementThe procedure for setting up a standby policy server is discussed in the IBM TivoliAccess Manager for e-business: Installation Guide. The following tasks are proceduresto ensure that you correctly followed the initial Tivoli Access Managerconfiguration procedures for setting up HACMP Tivoli Access Manager primaryand standby servers.

Verify the policy server setup for high availabilityTo verify that the installation and configuration procedures were correctlyfollowed, ensure that the following primary tasks are completed:v Make sure that you have set up the required soft links from the active primary

server to the standby server.v Make sure that you have modified the appropriate configuration options in the

ivmgrd.conf and pd.conf configuration files on both the primary and standbypolicy servers. These configuration files must have the same default settings forthe following required user and group IDs:– The ivmgr user ID– The tivoli user ID– The ivmgr group ID– The tivoli group ID

v Make sure you copy files from the local AIX file system for the primary server,the standby server, and the policy server to the shared file system, that theshared file system is located on a common directory, and that each user andgroup has the necessary access permissions.


If any of these items are incorrectly set, return to the procedure for setting up astandby policy server in the IBM Tivoli Access Manager for e-business: InstallationGuide.

Review log filesYou can monitor the transition process of the primary policy to the standby serverby examining the hacmp.log file to verify that all HACMP failover operationsoccurred. The procedure for reviewing HACMP logs can be found in the in theHACMP documentation. This log is usually found in the /tmp directory.

If a read or write operation error occurred during the policy server failover, youcan review the primary policy server log files. The location of the Tivoli AccessManager log files depends on whether Tivoli Common Directory is used. See theIBM Tivoli Access Manager for e-business: Troubleshooting Guide for information aboutthese log files and the XML log file viewer.

Chapter 14. High availability of the policy server 179

Chapter 15. Multiple-tenancy policy server

A multiple-tenancy server refers to a server that permits the hosting of multiplecustomers on a single server instead of on multiple client machines. For example,your company might be sharing applications or data on your company's serverwith your customer (for example, Smith-Davis Enterprises). Before you add dataand information that belongs to another customer (for example, Systems, Inc.), youmust somehow ensure that these two customers cannot get access to the othercompany's data or applications.

Using a multiple-tenancy (multi-domain) server, you can run each company'sapplications or data in an isolated server environment. Running in an isolated orpartitioned server environment replaces the need to use multiple physical serversfor each customer and their applications. Depending on the demands of yourcustomers and their applications, you can host multiple clients on a single server.Replacing multiple servers with one server reduces the costs to your company forthe services you provide to your customers. For example, fewer servers reducehardware costs and reduce IT personnel burden. It is easier to manage a singleserver than it is to manage multiple servers.

A multiple-tenancy server does not have to be less secure than the traditionalone-server, one-client approach. Using technologies such as SSL and restrictedaccess, you can protect two customers (users) on the same server from one another.Extra layers of security for multiple-user applications are designed into TivoliAccess Manager. Tivoli Access Manager compartmentalizes each domain to sealusers off from one another rather than using the multiple-user security provisionsthat are provided by the native operating system.

The Tivoli Access Manager runtime clients must be configured into a specificdomain at installation time. The domain membership information accompanieseach subsequent request from the client to the policy server. The [domains] stanzain the ivmgrd.conf configuration file for the multiple-tenancy policy server containsa list of valid existing domains. See “[domains] and [domain=domain_name]stanzas” on page 248 for an explanation of each stanza entry.

Each domain must have its own [domain=domain_name] stanza. For example, to setup separate domains for Smith-Davis Enterprises and Systems, Inc., you mightcreate two domains uniquely named smithdavis and systemsinc, respectively:[domains]

domain = smithdavisdomain = systemsinc

[domain=smithdavis]

[domain=systemsinc]

The multi-tenancy domains implemented by Tivoli Access Manager results inseparate databases for each protected object space. All of the databases can use thesame underlying user registry (one LDAP registry with distinct and separatedistinguished names). For example, to specify the sde0001.db file, specify the filename and directory in this stanza entry:[domain=smithdavis]database-path = D:\smithdavis\sde0001.db


The distinguished name (DN) can be used to restrict the registry into which userscan be created or imported. The distinguished name substrings must appear in theuser's distinguished name, for example:cn=sdeuser1,ou=sde,dc=mkt,c=US

The previous distinguished name has the following representation:cn = common name (sdeuser1) for K.L. Loganou = organizational unit (sde) for Smith-Davis Enterprisesdc = domain component (mkt) for Marketing Groupc = country (US) for United States

To restrict user accounts to be created in the dc=mkt,c=US directory container forthe smithdavis domain, you would specify to allow this registry substring in thisstanza entry:[domain=smithdavis]allowed-registry-substrings = "dc=mkt,c=US"

To restrict user accounts to be created in the dc=mkt directory container for thesmithdavis domain, regardless of where that container exists within the registry,specify the following stanza entry:[domain=smithdavis]allowed-registry-substrings = "dc=mkt"

A completed [domains] stanza in the ivmgrd.conf configuration file might look likethe following stanza example for the policy server:[domains]domain = smithdavisdomain = systemsinc

[domain=smithdavis]database-path = D:\smithdavis\sde0001.dballowed-registry-substrings = "dc=mkt,c=US"

[domain = systemsinc]database-path = D:\systemsinc\sysinc0001.dballowed-registry-substrings = "dc=sales,c=US"


Chapter 16. Delegated administration

Tivoli Access Manager allows high-level administrators to delegate managementresponsibilities of the domain to lower-level administrators. This capability is vitalto successfully manage large domains that are composed of numerousdepartments.

Tivoli Access Manager supports delegated administration in the following areas:v Delegated management of resources in subregions of the object space

Administration capabilities are restricted to a portion of the object space.v Delegated management of groups and users

Administration capabilities are restricted to a portion of the user population.

This chapter contains the following sections:v “Overview of delegated administration”v “Delegated role administration” on page 185v “Delegated object space management” on page 186v “Delegated user and group management” on page 188v “Security policy for delegated administration” on page 193

Overview of delegated administrationDelegated administration provides a Tivoli Access Manager administrator theability to create delegate user domains, create new users, add existing users toadditional domains, and assign various types of administrators to the domains.These delegate administrators can then perform a subset of administrative tasks onthe users in their assigned domain. This concept of delegate user administrationcan be applied to all Tivoli Access Manager users so that a hierarchy of userdomains is formed. In this hierarchical arrangement, each Tivoli Access Manageruser can be managed only by the administrators for the domain of which the useris a member or by the administrators for the super domains (explained later in thischapter). The actual tasks that administrators can perform depend on theirassigned administrator types.

A Tivoli Access Manager administrator, such as sec_master, can create a number ofenterprise domains and assign one or multiple types of administrators to eachenterprise domain. The administrator for an enterprise domain can create newusers in the domain and add existing Tivoli Access Manager users to the domain.

In addition to this user-related task, Tivoli Access Manager administrators cancreate new domains below the enterprise domain level (subdomains) and assignusers to be the administrators for these new domains (domain administrators).Administrators of the new domains can then create new users in their owndomain.

The Tivoli Access Manager administrator for the enterprise domain (the domain'ssuperdomain) also has authority to administer the domain. Tivoli Access Manageradministrators can create and manage as many domains under their authority asnecessary to fulfill their unique business needs.


Note: An enterprise domain is basically the top-level domain, and any domaincreated below an enterprise domain level is just called a domain.

As an example of this type of multiple domain administration in Figure 20, a TivoliAccess Manager administrator can create enterprise domains A and B and assignan administrator for each domain. The domain administrator for enterprise domainB can create new users P and Q. A Tivoli Access Manager administrator can createdomains C and D below the enterprise domains A and B, and assign domainadministrators to C and D. The Tivoli Access Manager administrator can thencreate domain E below domain D, and assign a domain administrator to E. Thedomain administrator for domain E can then create new users X, Y, and Z withindomain E. Because a domain administrator for a domain can also administer thatdomain's subdomains, both the domain administrators for domain D and thedomain administrator for enterprise domain B can create users (or perform otheradministrative tasks) for domain E.

For each delegate user domain (including the enterprise domain), predefinedadministrator types can be assigned in that domain. The following are the variousadministrator types and the set of administrative tasks that can be performed byadministrators assigned to each of these types:

Tivoli Access Manager administratorThe Tivoli Access Manager administrator is a member of the iv-admingroup. The Tivoli Access Manager administrator can perform all delegateadministration tasks.

Domain administratorThe domain administrator can perform administrative tasks for the users intheir domain. Domain administrators can create new users andadministrators in their own domain, and assign an existing domain user tobe an administrator (of any type except domain administrator) for thedomain.

Senior administratorA senior administrator has the same authority as a domain administrator,except that a senior administrator cannot assign additional administrators.

Secure domain

Enterprise domain A Enterprise domain B . . .

(Users P, Q, . . .)

Domain C Domain D

Domain E(Users X, Y, Z, . . .)

. . .

Figure 20. Delegate administrators


AdministratorAn administrator has the same authority as a senior administrator, exceptthat an administrator cannot create new domain users. An administratorcan modify existing users' properties.

Support AdministratorA support administrator serves the user in a help desk role and can viewusers’ properties, change users’ passwords, and modify the Is PasswordValid? flags for users.

The delegate user administration tool enforces the administrative tasks that can beperformed with each administrator type. When an administrator logs in,administrative tasks become available in accordance to the administrator type ofthat user.

Delegated role administrationAnother part of the Tivoli Access Manager delegate administration system is roleadministration. To successfully deploy Tivoli Access Manager, a security policymust be defined that regulates access to objects, and the actions that can beperformed on those objects. Execution of this policy is usually difficult because thesecurity policy is often defined by high-level members of an organization with anemphasis on global security issues. The policy then must be put into action bylocal members of the organization, who see the lower-level details andimplementation concerns. Often these two groups have similar goals for overallorganizational security, but interconnecting these two disparate points of view ischallenging. Role-based administration provides an enhanced ability fororganizational security to meet the requirements of today’s complex securityrequirements for scalability, simplicity, and flexibility.

To understand role administration, the first concept that must be defined is a role.A role consists of a number of tasks, responsibilities, or skills required to fulfill aspecific job requirement. When this definition is contrasted against the accesscontrol list (ACL) model, a role becomes a list of one or more pairs of objects andone or more access permissions that are applied to the object. For example:v object 1: permission 1v object 2: permission 2, 3, and 4v object 3: permission 5

For a role to be used it must be activated. A role is activated when a Tivoli AccessManager administrator enables its definition in the Tivoli Access Managernamespace. After a role is activated and a user is assigned to the role, the user haspermission 1 for object 1, permissions 2, 3, and 4 for object 2, and permission 5 forobject 3. The access permissions for these objects allow the user to access theobjects, and therefore perform the job responsibility defined by the role. Forexample, an accountant role can be defined to consist of the following two pairs ofobjects and permissions:v Payroll check object: create/modify/deletev Reimbursement request object: approve

When this role is activated and an employee in the accounting department isassigned to this role, that employee can create, modify, or delete a payroll checkand approve a reimbursement request; thus, performing the job that an accountantis expected to perform.

Chapter 16. Delegated administration 185

Administrative tasks for rolesTo successfully administer roles, an administrator must be able to perform threetypes of tasks:

Role creationRole creation involves defining a role so that it has a list of one or morepairs of Tivoli Access Manager objects and permissions that can be appliedto the objects. When a role is created, a Tivoli Access Manager group iscreated to represent the role. A corresponding group object in themanagement object space is also created. The object/permissions pairinformation for the role is stored in the extended attributes associated withthe group object. Only a Tivoli Access Manager administrator can create arole.

Role assignmentRole assignment consists of assigning a user to a role that was alreadycreated. The purpose behind assigning users to roles is to let those usershave access permissions on objects defined in the role. This functionreduces the workload involved in maintaining user-permission-objectrelationships, because role assignment is separated from object/accesspermission management. When a user is assigned to a role in Web PortalManager, the user is added as a member of the group that represents therole. Domain administrators, senior administrators, and administrators of adomain can assign users in their domains to a role.

Role activationRole activation enables a newly created role to function. After a role iscreated and a user is assigned to that role, the user does not have accesspermissions for the objects defined in the role until the role is activated.When a role is activated in Web Portal Manager, an ACL entry thatcontains the group that represents the role and the access permissionsdefined in the role are added to the ACL for each object defined in therole. Because a user was added to the group when the user is assigned tothe role, that user has permissions to access the objects only after a role isactivated. Only a Tivoli Access Manager administrator can activate a role.

A role is an entity that can be delegated and administered. When a role is created,it can be assigned to an enterprise domain. Domain administrators can in turnassign any of the roles within that domain to any subdomain. When a role isassigned to a subdomain, an administrator for that subdomain can assign anysubdomain users to that role. This process of assigning roles to subdomains can berepeated as needed so that roles can be made available to the appropriate users.Role assignment to an enterprise domain can be performed only by the TivoliAccess Manager administrator. Domain administrators can assign a role to theirsubdomains.

Delegated object space managementThe distribution of administration responsibilities within a domain is calledmanagement delegation. The need for management delegation generally arises fromthe growing demands of a large site containing many distinct departmental orresource divisions.


Typically, a large object space can be organized into regions representing thesedepartments or divisions. Each distinct region of the domain is usually betterorganized and maintained by a manager who is more familiar with the issues andneeds of that branch.

Structuring the object space for management delegationStructure your object space to contain distinct regions, or branches, wheresubmanagement responsibilities specific to that branch can be carried out.

In Figure 21, both the Engineering and Publications regions of the object spacerequire separate management control. Control of these regions begins with the rootof each region and extends to all objects below the root.

Default administration users and groupsTivoli Access Manager provides several important administration groups duringinstallation. For information on these user and groups, see “Default administrationusers and groups” on page 43.

Example of management delegationA large object space might require many administration users to manage a varietyof subbranches. In this scenario, the access control lists (ACLs) for the directorieson the path to each of these branches must contain entries for each account, withtraverse permission. For a site with many administration users, these ACLs couldcontain a long list of entries representing all these administration accounts.

The following technique resolves the problem of numerous ACL entries foradministrators:1. Create an administration group account.2. Add all new administration users to this group.3. Add this group as an ACL entry (with traverse) to the directories leading to

each subbranch that requires management delegation.4. At each branch root ACL, create an administration group for each subbranch

and add the appropriate user to the appropriate subbranch administrationgroup (with b, c, T, plus other appropriate permissions).

5. Remove the administration group ACL entry (and any other entry) from theroot.

Object space

/WebSEAL

Engineeringserver

Publications

Marketingserver

Resources

Figure 21. Structuring the object space for management delegation


Now, only that user has control over the root and all objects below the root.

In Figure 22, the iv-admin group contains all administration users. Thepub-manager user is a member of this group and therefore, has the traversepermission required to navigate to the/Publications directory.

The /Publications directory includes the pub-manager user entry in its ACL.Because pub-manager is the delegated administrator of this branch (with theappropriate permissions), pub-manager can remove the iv-admin group account(and any other ACL entries) from the /Publications ACL to gain total control overthis branch of the Web space.

Delegated user and group managementIn order to manage a large or complex set of users, you can delegate themanagement of specific groups of users to lower-level administrators. When anadministrator is given policy management control of a group, that administratorhas policy management control over the user members of that group.

Delegated group management defines:v Who has administration responsibility for a specific group (and the user

members of that group).v What level of group and user control was given to this administrator.

In this discussion, the term, administrator, refers to the responsibilities and controlsgranted to an otherwise typical user. An administrator of delegated duties is anormal user with additional powers to perform certain management tasks.

Setting up delegated group management requires the following steps:1. Determine a logical and practical hierarchy of the users and user types who are

members of the domain.2. Create group container objects that reflect this hierarchy.3. Create appropriate administration groups within these container objects.

/WebSEAL

/Resources

/Marketing

group iv-admin. . .user pub-manager

bT

abcTdmlrx/Publications

user sec_mastergroup iv-admin

AbcTdmlrxbT

user sec_mastergroup iv-admin

abcTdmlrxbT

ExplicitACL

InheritedACL

Figure 22. Management Delegation Example


4. Add the appropriate user to the appropriate administration group with thespecific permissions needed to perform the required tasks.

Creating group container objectsBy default, the /Management region of the Tivoli Access Manager object space has aGroups container object that you can use to organize the hierarchy of groups inyour domain.

Container objects are structural designations that allow you to organize the objectspace into distinct and hierarchical functional regions. Group container objects allowyou to define distinct categories of group types.

To create actual groups within each specific group container object using WebPortal Manager or the pdadmin utility, log in to the domain as a domainadministrator.

Web Portal ManagerTo create a new group container object using Web Portal Manager, complete thefollowing steps:1. Log in to the domain.2. Click Object Space → Create Object.3. In the Object Name text field, type the full path for the object name. For

example: /Management/Groups/Travel4. In the Description text field, type the description for the object space. For

example: Travel Container Object

5. Click Create.

To see the new object in the hierarchical structure, browse the object space. See“Listing object spaces” on page 67.

pdadminTo create a new group container object using the pdadmin utility, log in to thedomain and use the object create command.

For example, to create the new /Management/Group/Accounting delegate containerobject for the Accounting department and allow delegate administrators to attachACL policies, enter the following command:pdadmin>object create /Management/Group/Accounting "Accounting Department"

14 ispolicyattachable yes

-

-

+

/Management

/Management/Groups

/Management/Groups/Travel

Figure 23. Group container object


You can also use the group create command to create a group container object. See“Creating groups.”

For more information about the object create command, see the IBM Tivoli AccessManager for e-business: Command Reference.

Creating groupsTo create a new group and optionally place this group in a group container objectusing Web Portal Manager or the pdadmin utility, log in to the desired domain asa domain administrator.

Web Portal ManagerTo create a new group and optionally place this group in a group container object,complete the following steps:1. Use Web Portal Manager to log in to the domain as a domain administrator.2. Click Group → Create Group.3. In the Group Name text field, type the name for the group (for example,

group1). This field is required.4. Optional: In the Description text field, type the description for the group (for

example, Travel group 1).5. In the Registry GID text field, type the registry GID. The registry GID specifies

the location in the user registry where the new group is created. For example:cn=travel,c=us. Lotus Notes users require the full path name for the userbeing created. For example: travel/US.

6. Optional: In the Object Container text field, type the path to the Tivoli AccessManager object space where the group is to be created. Be sure to type the pathusing a leading backward slash (/):/Travel

The path is created under /Management/Groups (for example,/Management/Groups/Travel).

7. Click Create.

The new group is displayed as a link. Select the link and the properties for thenew group are displayed.

pdadminTo create a new group and optionally place this group in a group container objectusing the pdadmin utility, log in to the domain and use the group createcommand. This command has the following syntax:pdadmin>group create group_name dn cn [group_container]

Argument Description

group_name Name of the new group object.

dn Distinguished name for the new group.

cn Common name for the new group.

group_container Relative path name for the group container object where this newgroup should be located. If no group container object is specified,the group is placed under /Management/Groups.

If the container object does not currently exist, it is created.


For example:pdadmin>group create group1 “cn=travel,c=us” Group1 Travel

pdadmin>group create group2 “cn=travel,c=us” Group2 Travel

Notes:

1. All new group container objects that you create appear under the default/Management/Groups container. To create a container at another sublevel, use arelative path name for the group_container variable.

2. The group create command does not allow you to create a group containerobject without a group.

3. To add a new group to the object space, the administrator must have create (N)permission on the ACL governing the associated group container object.If no group container object is specified, the administrator ACL entry (with thecreate permission) must be specified in the ACL governing the/Management/Groups container.At installation, a single default ACL (default-management), which is attached to/Management, defines the permissions on all groups and group containers. Youmust add explicit ACLs to customize this control.

4. You can add multiple groups to a single group container.The ACL on the group container object controls (through inheritance) all groupslocated under the container object. The container object and its groups are nowthe domain of the administrator with the delegated responsibilities.

5. The placement of a new group in the object space is fixed on creation.As soon as a group is created, you can move its position only by deleting thegroup from the object space (but not LDAP) and then importing the group to anew location (users in the group are maintained).

For more information about the group create command, see the IBM Tivoli AccessManager for e-business: Command Reference.

ACL policies affecting group managementAuthorization to control a group of users is obtained by attaching an appropriateACL to the group object or group container object.

The ACL, constructed and attached by a higher-level administrator, should containthe appropriate permissions for the actions that must be performed by thedelegated administrator of that group (or groups).

If the group is located under the /Management/Groups section of the object space,the ACL must be attached to /Management/Groups or the group itself.

If the group is located under a group container object, the ACL must be attached tothe group container object or the group itself. If you attach the ACL to the/Management/Groups container object, the ACL would impact all other groupcontainer objects located below /Management/Groups in the object space.

The ACL that is attached to one of these locations (or inherited from above)determines:v Who controls the group object and the users in the groupv What actions can be performed on the group and its users


The following operations and ACL permissions are appropriate for groupmanagement:

Operation Permission

create (a new group) import (group data from the userregistry)

N (create)

delete (a group) d (delete)

show (group details) v (view)

modify (group description) m (modify)

add (an existing user to a group) A (add)

remove (a user member of the group) A (add)

You can use the pdadmin utility or Web Portal Manager to perform theseoperations.

Attention:

The add (A) permission allows you to add any existing user to your groups. If anoutside user is placed in a group, the administrator of that group has control of theuser (and might share control of the user with administrators of other groupswhere that user is a member). This permission is should be granted only tohigh-level administrators who are responsible for user and group organization andcorporate policy.

Use caution when assigning an administrator the A permission. A delegatedadministrator with the A permission should not have m, W, N, or d permissions.

Notes:

1. The create (N) permission must be located in an ACL that is attached to/Management/Groups or on a group container object.

2. All other permissions listed can be located in an ACL attached to/Management/Groups, a group container object, or the group object itself.

ACL policies affecting user managementThe group administrator can perform an action on a user if the administrator hasthe appropriate permission defined on any of the groups where that user is amember.

The following operations and ACL permissions are appropriate for usermanagement:

Operation Permission

create (a new user within one or more specifiedgroups) import (user data from the user registry)

N (create)

delete (a user) d (delete)

show (user details) v (view)

modify (user description) m (modify)

account valid m (modify)

reset password W (password)

password-valid W (password)


You can use the appropriate pdadmin utility or Web Portal Manager to performthese operations.

Notes:

1. The create (N) permission (in the group ACL or group container ACL) allowsyou to create or import a user and enter that user into the groups you control.user create user1 “cn=user1,c=us” user1 user1 adcde group1user import user2 “cn=user2,c=us” group1

2. You can also create a user without designating a group. In this case, however,the create (N) permission must be located in an ACL on the /Management/Userscontainer object.The ACL attached to /Management/Users defines the permissions for all users(whether they are members of a group or not).

3. A group administrator can perform an operation on a user if that administratorhas the appropriate permission defined in any group where that user is amember.

4. If a user is not a member of any group, an administrator must haveappropriate permissions in an ACL on /Management/Users to performoperations on that user.

5. The password (W) permission is appropriate for help desk operators who mustassist users who have forgotten their passwords.The operator can reset the forgotten password to some known value, and thenset user modify password-valid (pdadmin) to no. This action forces the user tochange the password at the next login. Setting user modify password-valid tono for a user does not indicate if the password is not valid due to themax-password-age policy, which is a global setting. The policy setmax-password-age command sets the maximum time before a passwordexpires.

6. The view (v) permission is used to control the output of user list, user list-dn,user show groups, group list, and group list-dn commands. The viewpermission is used to filter the output of these commands. If the user does nothave view permission on a group or user that is being returned by thecommand, that group or user is filtered from the output.

Security policy for delegated administrationThe previous sections described how to delegate administration of security policyfor protecting resources and delegating management of the users who access thoseresources. These two aspects of delegated administration often need to becombined to establish a complete delegated administration security policy.

Be careful which permissions you grant in combination with each other.

For example, the A permission should never be granted together with the m, W, ord permissions except to the most trusted administrators. The consequence ofgranting both A and W to administrators is that the administrators can add anyuser to the group for which they have these permissions and then change thatuser’s password. Any user can be chosen, including a more senior administrator oreven sec_master. In this way, a malicious administrator could gain full access tothe system by logging in as the senior user.

The consequence of granting the A and m permissions together are similar exceptthat an administrator with both of these permissions needs only this combinationto disable any account in the group. The consequence of granting the A and d


permissions together are similar except that an administrator with both of thesepermissions needs only this combination to delete any user ID in the group.

You must establish groups that you use to delegate user management tasks. Thesetasks include creating new users, deleting users and resetting passwords.Administrators that perform user administration tasks should have the N, d, m, W,and v permissions to create, delete, modify (disable or change description), reset orinvalidate passwords, and view users they are responsible for managing. Thesegroups are used only for delegating user management. These groups should not beused for protecting other resources in the domain.

You must also establish groups that you use to delegate management of a securitypolicy for protected resources within the domain. Administrators controllingsecurity policy for these groups should have the A and v permissions but none ofthe N, d, m, or W permissions. These groups are used to control access toresources that need protecting.

Example:

Suppose that you have a Web space accessible to the Internet with resources thatshould be:v Publicly accessiblev Accessible only to customers and employeesv Accessible only to employees

The space can be structured as follows:/WebSEAL/

www.company_ibm.com/customers/sales/

An ACL at the root of the www.company_ibm.com Web space allows public access toeverything in the Web space. An ACL at customers allows access to customers andsales people. Another ACL at sales allows access only to sales people. These ACLsmight look like the following example:public-access

user sec_master abcTdmlrxany-other Tlrxunauthenticated Tlrx

customer-accessuser sec_master abcTdmlrxgroup customers Tlrxgroup sales Tlrxany-otherunauthenticated

sales-accessuser sec_master abcTdmlrxgroup sales Tlrxany-otherunauthenticated

These ACLs would be attached, respectively, to the following objects:/WebSEAL/www.company_ibm.com/WebSEAL/www.company_ibm.com/customers/WebSEAL/www.company_ibm.com/sales

Suppose that you have the following delegated user administration policy. Salespeople (members of the sales group) are allowed to create new accounts for


customers and grant them access to the customers portion of the Web space. Onlyadministrators (members of the sales-admin group) are allowed to manageaccounts for new sales people.

The following group structure implements this policy:/Management/

Groups/sales <- ACL sales-adminsales-users <- ACL sales-users-admincustomers <- ACL customers-admincustomers-users <- ACL customers-users-admin

The sales-admin ACL is used to administer membership of the sales group, whichin turn, is used to control access to the sales-people-only portion of the Webspace. The only permission required is for the sales-admin group to be able to addand remove users from this group. The view (v) permission is also useful toadministrators to allow them to view group membership and users in the group.sales-admin

group super-admin Tabcgroup admin TAv

The sales-users-admin ACL, by attachment to the sales-users group, controls whocan manage users who are members of the sales-users group (this is thesales-admin group again).sales-users-admin

group super-admin Tabcgroup admin TNWdmv

Similarly, the customers-admin ACL is used to administer membership to thecustomers group, which in turn, is used to control access to the customers-onlyportion of the Web space.customers-admin

group super-admin Tabcgroup sales TAv

The customers-users-admin ACL, by attachment to the customers-users group,controls who can manage the members of the customers-users group (this thesales group again). Members of the sales-admin group can manage customers.customers-users-admin

group super-admin Tabcgroup sales TNWdmvgroup admin TNWdmv

In each ACL, a super-admin group entry is granted attach, browse, and controlpermissions. Members of the super-admin group are responsible for administeringthese ACLs.


Chapter 17. Diagnostics and auditing

Tivoli Access Manager provides ways to collect events that you can use fordiagnostic and auditing purposes of the servers. Events for diagnostics andauditing pertain to the operations of the Tivoli Access Manager servers. Theseevents do not pertain to the installation of the these servers.

To enable diagnostics and auditing, you define which types of events to capture.When events are captured, they can be written to log files, to the standard output(STDOUT) device, to the standard error (STDERR) device, or to a combination ofthese destinations. Beyond these destinations, when events are captured, they canbe redirected to a remote server or redirected to an application for processingusing log agents.

During the installation of the Tivoli Access Manager servers, the installation logscapture all messages for that specific installation. When using the installationwizard, each server has its own log file. When using a native installation, theinstallation uses the operating system logs. For information about installation logs,see the IBM Tivoli Access Manager for e-business: Troubleshooting Guide.

Diagnostic eventsFor diagnostics, define which message events and which trace events to capture.These events can help you troubleshoot problems.

To configure diagnostic events, define statements in the server-specific routing files.Each server has an associated routing file. The statements in these routing files arefor both message events and trace events. You define the statements for messageevents by severity level. You define the statements for trace events by trace leveland optionally by component.

For additional information about message and trace events, see the IBM TivoliAccess Manager for e-business: Troubleshooting Guide.

Auditing eventsFor auditing purposes, define which audit, statistic, or other type of events tocapture. These events allow you to create snapshots of a variety of server activities.You can log audit events using either the native Tivoli Access Manager approachor IBM Common Auditing Service.

To configure auditing events, define stanza entries in the configuration files.Depending on your desired approach, define different stanza entries in differentconfiguration files. For native Tivoli Access Manager auditing, you define logcfgentries in the appropriate stanza of the server-specific configuration files. For theCommon Auditing Service, define entries in the [cars-filter] stanza.

For additional information about audit events, see the IBM Tivoli Access Manager fore-business: Auditing Guide.


Appendix A. Guidelines for changing configuring files

These guidelines are provided to help you make changes to the Tivoli AccessManager configuration files. The guidelines are divided into the followingcategories:v General guidelinesv Default valuesv Stringsv Defined stringsv File namesv Integersv Boolean values

General guidelinesUse the following general guidelines when making changes to the configurationsettings:v Use the config modify command in the pdadmin command line interface to

update configuration files for Tivoli Access Manager. See "config modify" in theIBM Tivoli Access Manager for e-business: Command Reference for more informationand instructions for using these commands.– To modify a single key/value pair, use the pdadmin (local login) config

modify command with the set option. The following command is an examplethat modifies the dynamic-groups-enabled value in the uraf-registry stanzaof the activedir.conf file on a Windows platform:pdadmin> login localpdadmin local> config modify keyvalue set "C:\Program Files\Tivoli\PolicyDirector\etc\activedir.conf" "uraf-registry" "dynamic-groups-enabled" yes

– To modify multiple key/value pairs, use the pdadmin (local login) configmodify command with the append option. The following command is anexample that modifies multiple values for the domain option in theuraf-registry stanza of the activedir_ldap.conf file on a Windows platform.pdadmin> login localpdadmin local> config modify keyvalue append "C:\Program Files\Tivoli\PolicyDirector\etc\activedir_ldap.conf" "uraf-registry" "domain""dc=my_ad_domain, dc=com|myhost.my_ad_domain.com

pdadmin local> config modify keyvalue append "C:\Program Files\Tivoli\PolicyDirector\etc\activedir_ldap.conf" "uraf-registry" "domain""dc=my_ad_domain2, dc=com|myhost2.my_ad_domain2.com

v There is no order dependency or location dependency for stanzas in anyconfiguration file.

v Stanza entries are marked as required or optional. When an entry is required,the entry must contain a valid key and value.

v Do not change the names of the keys in the configuration files. Changing thename of the key might cause unpredictable results for the servers.

v Stanza entries and key names are case-sensitive. For example, usessl and UseSSLare treated as different entries.

v Spaces are not allowed for names of keys.


v For the key value pair format of key = value, the spaces surrounding the equalsign (=) are not required, but they are recommended.

v Non-printable characters (such as tabs, carriage returns, and line feeds) thatoccur at the end of a stanza entry are ignored. Non-printable characters areASCII characters with a decimal value less than 32.

Default valuesUse the following guidelines when changing default configuration settings:v Many values are created or modified only by using configuration programs. Do

not manually edit these stanzas or values.v Some values are filled in automatically during configuration. These values are

needed for the initialization of the server after the configuration.v The default values for a stanza entry might be different, depending on the server

configuration. Some key value pairs are not applicable to certain servers and areomitted from the default configuration file for this server.

StringsSome values accept a string value. When you manually edit the configuration file,use the following guidelines to change configuration settings that require a string:v String values are expected to be characters that are part of the local code set.v Additional or different restrictions on the set of allowable string characters

might be imposed. For example, many strings are restricted to ASCII characters.Consult each stanza entry description for any restrictions.

v Double quotation marks are sometimes, but not always, required when you usespaces or more than one word for values. Refer to the descriptions or examplesfor each stanza entry when in doubt.

v The minimum and maximum lengths of user registry-related string values, ifthere are limits, are imposed by the underlying registry. For example, for ActiveDirectory the maximum length is 256 alphanumeric characters.

Defined stringsSome values accept a string value, but the value must be one of a set of definedstrings. When you manually edit the configuration file, make sure that the stringvalue you type matches one of the valid defined strings values.

For example, the [aznapi-configuration] stanza section contains the followingentry:mode = {local|remote}

The value for mode is expected to be local or remote. Any other value is invalidand results in an error.

File namesSome values are file names. For each stanza entry that expects a file name as avalue, the description of the stanza entry specifies which of the followingconstructs are valid:

FilenameNo directory path included.


Relative filenameA directory path is allowed but not mandatory.

These files typically are expected to be located relative to the location of astandard Tivoli Access Manager directory. The stanza entry for eachrelative path name lists the root directory to which the file name is relative.

Fully qualified absolute pathAn absolute directory path is required.

Some stanza entries allow more than one of the above choices.

The set of characters permitted in a file name can be determined by the file systemand by the local code set. For Windows operating systems, file names cannot havea backward slash (\), a colon (:), a question mark (?), or double quotation marks(").

IntegersMany stanza entries expect the value for the entry to be expressed as an integer.When defining an entry with an integer, consider the following guidelines:v Some stanza entries that take an integer value expect integer values within a

valid range. The range is described in terms of a minimum value and a maximumvalue.For example, in the [ivmgrd] stanza, the max-notifier-thread stanza entry has aminimum value of 1 thread and a maximum value of 128 threads.

v For some entries, the integer value must be positive, and the minimum value is1. For other entries, a minimum integer value of 0 is allowed.Use caution when setting an integer value to 0. For example, an integer value of0 might disable the function that is controlled by that stanza entry. For example,in the [ivacld] stanza, the entry tcp-req-port = 0 disables the port number. Or,an integer value of 0 might indicate that the number is unlimited. For example,in the [ldap] stanza, the entry max-search-size = 0 means there is no limit tothe maximum search size.

v For some entries requiring integer values, Tivoli Access Manager does notimpose an upper limit for the maximum number allowed. For example, there istypically no maximum for timeout-related values, such as timeout = number inthe [ldap] stanza.For this type of entry, the maximum number is limited only by the size ofmemory allocated for an integer data type. This number can vary, based on thetype of operating system. For systems that allocate 4 bytes for an integer, thisvalue is 2147483647.However, as the administrator, use a number that represents the value that ismost logical for the value you are trying to set.

Boolean valuesMany stanza entries represent a Boolean value. Tivoli Access Manager recognizesthe Boolean values yes and no.

Some of the entries in the configuration files are read by other servers and utilities.For example, many entries in the [ldap] stanza are read by the LDAP client. Someof these other programs recognize additional Boolean characters:v yes or true

v no or false

Appendix A. Guidelines for changing configuring files 201

Anything other than yes|true, including a blank value, is interpreted as no|false.

The recognized Boolean entries are listed for each stanza entry. Refer to theindividual descriptions to determine when true or false are also recognized.


Appendix B. Configuration file reference

The operation of the Tivoli Access Manager servers is controlled through the use ofconfiguration files. Each configuration file contains sections that are called stanzas.

Server configuration files are ASCII text-based and contain stanza entries.Configuration files are processed only when the servers start. The followingconfiguration files are currently used by Tivoli Access Manager:

pd.confThe configuration file that is used by the authentication server to configurethe Tivoli Access Manager runtime. For details about the stanzas containedin this configuration file, see “Tivoli Access Manager runtime configurationfile” on page 205.

ivacld.confThe configuration file that is used to configure the Tivoli Access Managerauthorization server. For details about the stanzas contained in thisconfiguration file, see “Authorization server configuration file” on page205.

ivmgrd.confThe configuration file that is used to configure the Tivoli Access Managerpolicy server. For details about the stanzas contained in this configurationfile, see “Policy server configuration file” on page 206.

pdmgrproxyd.confThe configuration file that is used to configure the Tivoli Access Managerpolicy proxy server. For details about the stanzas that are contained in thisconfiguration file, see “Policy proxy server configuration file” on page 206.

ldap.confThe configuration file that is used by the LDAP-based server to configurethe LDAP-based user registry. For details about the stanzas that arecontained in this configuration file, see “LDAP server configuration file”on page 207.

activedir_ldap.confThe configuration file that is used to configure the Active Directory userregistry when it is used on a non-Windows platform. For details about thestanzas that are contained in this configuration file, see “LDAP client withActive Directory server configuration file” on page 207.

activedir.confThe configuration file that is used by the Microsoft Active Directory serverto configure the Active Directory user registry. For details about the stanzasthat are contained in this configuration file, see “Active Directory serverconfiguration file” on page 207.

domino.confThe configuration file that is used by the IBM Lotus Domino server toconfigure the Domino-based user registry. For details about the stanzasthat are contained in this configuration file, see “Domino serverconfiguration file” on page 208.

amconf.propertiesThe configuration file that is used to configure Web Portal Manager. For


details about the stanzas contained in this configuration file, see “WebPortal Manager configuration file” on page 208.

pdaudit.server.confThe configuration file that is used to configure the Common AuditingService for each Tivoli Access Manager server or server instance. Fordetails about the stanzas that are contained in this template file, see“Common audit service configuration files” on page 208.

The following server-specific configuration files are generated during theconfiguration of the Common Auditing Service client:

pdaudit.pdmgr.confThe configuration file that is used to configure the CommonAuditing Service for the Tivoli Access Manager policy server. Donot confuse this configuration file with the ivmgrd.confconfiguration file.

pdaudit.pdproxymgr.confThe configuration file that is used to configure the CommonAuditing Service for a Tivoli Access Manager policy proxy server.Do not confuse this configuration file with the pdmgrproxyd.confconfiguration file.

pdaudit.pdacld.confThe configuration file that is used to configure the CommonAuditing Service for the Tivoli Access Manager authorizationserver. Do not confuse this configuration file with the ivacld.confconfiguration file.

pdaudit.instance-webseald-host.confThe configuration file that is used to configure the CommonAuditing Service for a specific instance of a Tivoli Access ManagerWebSEAL server. Do not confuse this configuration file with thewebseald-instance.conf configuration file.

pdaudit.webpi.confThe configuration file that is used to configure the CommonAuditing Service for a Tivoli Access Manager Plug-in for WebServers. Do not confuse this configuration file with thepdwebpi.conf configuration file.

pdaudit.appsvr.confThe template configuration file that is used to configure theCommon Auditing Service for any Tivoli Access Manager resourcemanagers. Do not confuse this configuration file with theaznAPI.conf configuration file.

aznAPI.confA template configuration file that is used to configure any Tivoli AccessManager resource manager. For details about the stanzas that are containedin this template file, see “Resource manager configuration files” on page209.

Location of configuration filesIf you did not change the installation directories while installing Tivoli AccessManager, the configuration files are located in one of the followingplatform-specific directories:


Linux and UNIX operating systems/opt/PolicyDirector/etc

Windows operating systemsc:\program files\tivoli\policy director\etc

If you did not change the installation directories while installing the common auditservice, the templates for the configuration files are located in one of the followingplatform-specific directories:

Linux and UNIX operating systems/opt/PolicyDirector/etc/audit

Windows operating systemsc:\program files\tivoli\policy director\etc\audit

Tivoli Access Manager runtime configuration fileFor Tivoli Access Manager servers, you must have the pd.conf configuration file.Use this configuration file to automate server startup, to indicate whether theTivoli Access Manager runtime is configured, and specify information about theuser registry.

Stanza entries for automating server startup are located in the [pdrte] stanza ofthe pd.conf configuration file.

This configuration file can include the following stanzas:v [meta-info]

v [pdrte]

v [ssl]

v [manager]

The unconfiguration of the server using the pd.conf configuration file also queriesinformation from this configuration file.

Authorization server configuration fileWhen you use the Tivoli Access Manager authorization server, you must have theivacld.conf server configuration file. Use this configuration file to customize theoperation of each authorization server.


v [ivacld]

v [ldap]

v [uraf-registry]

v [ssl]

v [manager]

v [authentication-mechanisms]

v [aznapi-configuration]

v [xmladi-attribute-definitions]

v [aznapi-entitlement-services]

v [aznapi-external-authzn-services]

Appendix B. Configuration file reference 205

v [aznapi-pac-services]

v [aznapi-cred-modification-services]

v [aznapi-admin-services]

v [configuration-database]

The unconfiguration of the server using the ivacld.conf configuration file alsoqueries information from this configuration file.

Policy server configuration fileWhen you use the Tivoli Access Manager policy server, you must have theivmgrd.conf server configuration file. Use this configuration file to customize theoperation of each policy server.


v [ivmgrd]

v [ldap]

v [uraf-registry]

v [ssl]








v [delegated-admin]


v [domains]

v [domain=domain_name]

The unconfiguration of the server using the ivmgrd.conf configuration file alsoqueries information from this configuration file.

Policy proxy server configuration fileWhen you use the Tivoli Access Manager policy proxy server, you must have thepdmgrproxyd.conf server configuration file. Use this configuration file tocustomize the operation of each policy proxy server.


v [pdmgrproxyd]

v [ldap]

v [uraf-registry]

v [ssl]

v [manager]







The unconfiguration of the server using the pdmgrproxyd.conf configuration filealso queries information from this configuration file.

LDAP server configuration fileWhen you use LDAP as the user registry for Tivoli Access Manager, use theldap.conf configuration file to customize the LDAP-based stanza entries.

This configuration file includes the following stanzas:v [ldap]

v [meta-info]

v [ssl]

Note: The ldap.conf configuration file contains the following stanzas that containentries that are for internal use only:v [ldap-generic-general]v [ldap-generic-pwd-change-error-map]v [ldap-generic-acls]

Do not modify any of the values that are defined in these stanzas.

The contents of the [ldap] stanza are different in the activedir.conf anddomino.conf configuration files.

LDAP client with Active Directory server configuration fileWhen you use an LDAP client to retrieve data for the Active Directory userregistry to which the Tivoli Access Manager policy server is configured, you musthave the activedir_ldap.conf configuration file. Use this configuration file tocustomize the operation of each Active Directory user registry.

For example, you might have multiple platforms where the policy server isconfigured to use the Active Directory user registry. Other blades, such asWebSEAL on one platform, and the authorization server are configured to use theLDAP client to retrieve data from that Active Directory user registry on anotherplatform.


v [uraf-registry]

Active Directory server configuration fileWhen you use the Microsoft Active Directory server as your user registry for TivoliAccess Manager, you must have the activedir.conf configuration file. Use thisconfiguration file to customize the operation of each Active Directory user registry.

Note: Active Directory is supported only on Microsoft Windows for the policyserver.


This configuration file can include the following stanzas:v [uraf-registry]v [meta-info]v [configuration-database]

The unconfiguration of the server using activedir.conf also queries informationfrom this configuration file.

Also, you can set values for the [uraf-registry] stanza in the ivmgrd.conf andivacld.conf configuration files.

Domino server configuration fileWhen you use the Lotus Domino server as your user registry for Tivoli AccessManager, you must have the domino.conf configuration file. Use this configurationfile to customize the operation of each Domino user registry.


v [uraf-registry]


The unconfiguration of the server using the domino.conf configuration file alsoqueries information from this configuration file.

You can set values for the [uraf-registry] stanza in the ivmgrd.conf andivacld.conf configuration files.

Web Portal Manager configuration fileWhen you use Web Portal Manager to perform administrative tasks, you musthave the amconf.properties configuration file. Use this configuration file to specifycustomized images, whether the change-password pages are to be displayed, andthe authentication login method to use.

This configuration file includes only the [pdwpm] stanza.

Common audit service configuration filesWhen you use the common audit service for creating Tivoli Access Manager auditreports, you must have a server-specific pdaudit.conf configuration file. Use thisconfiguration file to customize auditing operations for that Tivoli Access Managerserver.

This configuration file can include the following stanza:v [cars-client]

v [cars-filter]

v [pdaudit-filter]


Resource manager configuration filesTivoli Access Manager provides a sample file that includes the more commonconfiguration stanzas needed by resource managers. Your documentation sources,when implementing your own plug-in or security-enhanced application, includethe IBM Tivoli Access Manager for e-business: Authorization C API Developer Referenceor IBM Tivoli Access Manager for e-business: Authorization Java Classes DeveloperReference.

When creating your own security resource manager or extending the functionsprovided by Tivoli Access Manager, you can use the aznAPI.conf configuration file.This file is included as a sample with the authorization ADK package in the/example/authzn/demo/cpp subdirectory.

This configuration file can include the following stanzas:v [aznapi-configuration]


v [ssl]

v [ldap]

v [uraf-registry]






v [manager]



Appendix C. Configuration file stanza reference

Within configuration files, stanza labels appear within brackets, such as[stanza-name]. For example, the [ssl] stanza in the ivmgrd.conf configuration filedefines the Secure Sockets Layer (SSL) configuration settings for the policy server.The [ldap] stanza defines the configuration settings that are required by the policyserver to communicate with an LDAP-based user registry.

Each stanza in a Tivoli Access Manager configuration file contains one or more keyvalue pairs, which contain information that is expressed as a paired set ofparameters. Each stanza entry is a key-value pair in the following format:key = value

You should not change the names of the keys in the configuration files. Changingthe name of the key might cause unpredictable results in the servers. Note thatspaces surrounding the equal sign (=) are not required but are recommended.

The initial installation of Tivoli Access Manager establishes many of the defaultvalues. Some values are static and never change; other values can be modified tocustomize server functionality and performance.

The following stanza descriptions provide a list of the valid stanza entries. Eachstanza entry consists of key value pairs. Each stanza entry includes a description ofits default behavior, when applicable.

[authentication-mechanisms] stanzaThis stanza defines the libraries that are to be used for each form of authentication.Tivoli Access Manager supports the following authentication forms:v Password authenticationv Certificate authentication

Resource managers, such as WebSEAL, can support additional forms ofauthentication.

The configuration entries in this stanza are required by the server to communicatewith a user registry. The resource manager can use either a User Registry AdapterFramework (URAF) registry (Active Directory or Domino) or an LDAP registry.

Because a user registry is either a URAF registry or an LDAP registry, certain keyvalue pairs in the [authentication-mechanisms] stanza are mutually exclusive. Thefollowing example shows how to configure the authentication mechanism for anLDAP user registry:passwd-ldap = fully_qualified_pathcert-ldap = fully_qualified_path#passwd-uraf = fully_qualified_path#cert-uraf = fully_qualified_path

In this example, the URAF registry items are commented out by using the poundsign (#) before the stanza entry. The LDAP-oriented stanza entries are notcommented out.


The stanza entries for configuring the Tivoli Access Manager user registry arelocated in the [authentication-mechanism] stanza of the following configurationfiles:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy serverv The configuration files for your resource managers

The aznAPI.conf configuration file is provided with Tivoli Access Manager as asample file for creating the configuration file for resource managers. Developersof service plug-ins should provide the standard functions. Before implementingservice plug-ins, read and thoroughly understand the concepts discussed in theIBM Tivoli Access Manager for e-business: Authorization C API Developer Reference.

cert-ldap

Syntaxcert-ldap = fully_qualified_path

DescriptionLocation of the library to use for LDAP certificate authentication.

Optionsfully_qualified_path

Represents an alphanumeric string. String values are expected to becharacters that are part of the local code set. The set of characterspermitted in a file name can be determined by the file system and by thelocal code set. For Windows operating systems, file names cannot have abackward slash (\), a colon (:), a question mark (?), or double quotationmarks ("). For Linux and UNIX operating systems, path names and filenames are case-sensitive.

UsageConditional. This stanza entry is required when you use an LDAP user registry.Comment out this stanza entry when you use a URAF user registry.

You can manually edit these values. No configuration utility is required.

Default valueThe following list shows the default, server-dependent values:

AIX /opt/PolicyDirector/lib/libcertauthn.a

HP-UX/opt/PolicyDirector/lib/libcertauthn.sl

Linux /opt/PolicyDirector/lib/libcertauthn.so

Solaris/opt/PolicyDirector/lib/libcertauthn.so

Windowsinstall_dir\bin\certauthn.dll

ExampleExample for Solaris operating environments:cert-ldap = /opt/PolicyDirector/lib/libcertauthn.so

& -cfgfile [/opt/PolicyDirector/etc/server_name.conf]


cert-uraf

Syntaxcert-uraf = fully_qualified_path

DescriptionLocation of the library to use for URAF certificate authentication.



UsageConditional. This stanza entry is required when you use a URAF user registry.Comment out this stanza entry when you use an LDAP user registry.



AIX /opt/PolicyDirector/lib/liburafcertauthn.a

HP-UX/opt/PolicyDirector/lib/liburafcertauthn.sl

Linux /opt/PolicyDirector/lib/liburafcertauthn.so

Solaris/opt/PolicyDirector/lib/liburafauthn.so

Windowsinstall_dir\bin\urafcertauthn.dll

ExampleExample for Windows operating systems:cert-ldap = C:\Program Files\Tivoli\Policy Director\bin\certauthn.dll

& -cfgfile [C:/pd/etc/server_name.conf]

passwd-ldap

Syntaxpasswd-ldap = fully_qualified_path

DescriptionLocation of the library to use for LDAP password authentication.


Represents an alphanumeric string. String values are expected to becharacters that are part of the local code set. The set of characterspermitted in a file name can be determined by the file system and by the

Appendix C. Configuration file stanza reference 213

local code set. For Windows operating systems, file names cannot have abackward slash (\), a colon (:), a question mark (?), or double quotationmarks ("). For Linux and UNIX operating systems, path names and filenames are case-sensitive.

UsageConditional. This stanza entry is required when you use an LDAP user registry.Comment out this stanza entry when you use a URAF user registry.



AIX /opt/PolicyDirector/lib/libldapauthn.a

HP-UX/opt/PolicyDirector/lib/libldapauthn.sl

Linux /opt/PolicyDirector/lib/libldapauthn.so

Solaris/opt/PolicyDirector/lib/libldapauthn.so

Windowsinstall_dir\bin\ldapauthn.dll

ExampleExample for Solaris operating environments:passwd-ldap = /opt/PolicyDirector/lib/libldapauthn.so

& -cfgfile [/opt/PolicyDirector/etc/server_name.conf]

passwd-uraf

Syntaxpasswd-uraf = fully_qualified_path

DescriptionLocation of the library to use for URAF password authentication.



UsageConditional. This stanza entry is required when you use a URAF user registry.Comment out this stanza entry when you use an LDAP user registry.




AIX /opt/PolicyDirector/lib/liburafauthn.a

HP-UX/opt/PolicyDirector/lib/liburafauthn.sl

Linux /opt/PolicyDirector/lib/liburafauthn.so

Solaris/opt/PolicyDirector/lib/liburafauthn.so

Windowsinstall_dir\bin\urafauthn.dll

ExampleExample for Windows operating systems:passwd-uraf = c:\program files\tivoli\policy director\bin\urafauthn.dll

& -cfgfile [c:/pd/etc/server_name.conf]

[aznapi-admin-services] stanzaAn administration service plug-in enables applications to performapplication-specific administration tasks. The administration service plug-in isaccessed by a calling application using one of the Tivoli Access Manageradministration interfaces.

The calling application can be an administrative utility such as the pdadmin utilityor Web Portal Manager, or the calling application can be a custom-built applicationthat uses the Tivoli Access Manager administration APIs.

The administration service maps the administration API calls to the correspondingadministration service API calls and carries out the requested action. Eachadministration service plug-in is a standalone module that is dynamically loadedinto the authorization service.

The parameters for configuring Tivoli Access Manager administration serviceplug-ins are declared in the [aznapi-admin-services] stanza of these configurationfiles provided by Tivoli Access Manager:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy serverv The configuration files for the configured administration service plug-ins for

your resource managersThe aznAPI.conf configuration file is provided with Tivoli Access Manager as asample file for creating your own resource manager configuration file.Developers of service plug-ins should provide the standard functions. Beforeimplementing service plug-ins, read and thoroughly understand the conceptsdiscussed in the IBM Tivoli Access Manager for e-business: Authorization C APIDeveloper Reference.

service-id

Syntaxservice-id = {short_name|path_to_dll}

[-pobj protected_object_hierarchy_name ] [& params]


DescriptionDefines the authorization API service for functions that enable a plug-in to obtainthe contents of a defined portion of the protected object hierarchy, or to enable aplug-in to define application-specific administration tasks that also returncommands that perform those tasks.

Each stanza entry defines different types of aznAPI service.

OptionsEach entry has the following format.

service-idDeveloper-specified ID of the administration service. An authorization APIapplication can register more than one administration service plug-in, buteach must have a unique service ID.

short_name|path_to_dllThe path to the dynamic link library (DLL) that contains the executablecode for the service executable.

If the DLL is located in a directory that is normally searched by the system(for example, /usr/lib on Linux and UNIX operating systems or the valueof the PATH environment variable on Windows operating systems), do notspecify the full path to the DLL, specify the DLL name only. If you want aplatform-independent DLL name, so it can be loaded on any supportedplatform, provide a short name. The short name is prepended andappended with known library prefixes and suffixes for each platform, andeach possibility is searched in turn. For example, using a short name ofazn_ent_user, the following names are automatically searched for on eachplatform:

AIX libazn_ent_user.solibazn_ent_user.a

HP-UXlibazn_ent_user.sl

Linux libazn_ent_user.so

Solarislibazn_ent_user.so

Windowsazn_ent_user.dll

protected_object_hierarchy_nameOptional: The name of the protected object hierarchy. This option referseither to the name of a protected object space (hierarchy) or to a protectedobject. Protected object hierarchy names must be unique for eachadministration service plug-in within the scope of an authorization APIapplication. To support failover, multiple authorization API applicationinstances can be registered to service the same protected object hierarchynames. Failover support allows for the administration of an object space ifa particular authorization API application server fails.

params Optional: The additional initialization arguments that can be passed to theexternal authorization service. The arguments must be preceded by theampersand (&); for example, & -server fred. The authorization servicedoes not process the characters after the ampersand. It passes thesecharacters directly to the administration service plug-in. The service


definition is discussed in more detail in the IBM Tivoli Access Manager fore-business: Authorization C API Developer Reference.

UsageOptional

Default valueThere is no default value.

ExampleAZN_ADMIN_SVC_TRACE = pdtraceadmin

[aznapi-configuration] stanzaTivoli Access Manager allows a highly flexible approach to authorization throughthe use of the authorization API. The standards-based authorization API allowsapplications to make calls to the centralized authorization service. Tivoli AccessManager provides built-in support of user name and password authentication aswell through the authorization API.

The configuration key value pairs that are used for configuring audit files forTivoli Access Manager servers are located in the [aznapi-configuration] stanza ofeach of the following configuration files:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy serverv The configuration files for your resource managers

Other stanza entries that apply to the configuration files of your resourcemanagers are discussed in the IBM Tivoli Access Manager for e-business:Authorization C API Developer Reference. Developers should read and thoroughlyunderstand these concepts so that they can provide the required standardfunctions. A sample aznAPI.conf configuration file is provided with TivoliAccess Manager to use as a guide for creating your own resource managerconfiguration file.

audit-attribute

Syntaxaudit-attribute = azn-attr

DescriptionName of the access decision information (ADI) attribute to audit. An attribute canestablish accountability by providing information to help identify potentiallyinappropriate access of assets. You can grant or deny access based on the rules thatare applied to attributes.

For example, the WebSEAL switch-user authentication feature provides amechanism to allow certain users to impersonate another user. When switch-user isused, an authorization request is evaluated against an assumed identity rather thanthe actual identity of the user. It is desirable to allow administrators to capture theuser's actual identity.

You can audit the names or descriptions of the Tivoli Access Manager policies(ACL, POP, and authorization rule) that are applied to the object being accessed.


Optionsazn_attr

The authorization API attribute represents an alphanumeric string that isnot case-sensitive. String values are expected to be characters that are partof the local code set.

UsageOptional


ExampleThe following example shows the configuration for WebSEAL:audit-attribute = tagvalue_su-admin

azn-app-host

Syntaxazn-app-host = other_hostname

DescriptionAttribute that is used to specify the host name that the policy server should usewhen communicating with the resource manager.

OptionsFor other_hostname, you can provide any valid internet host name. If this attributeis not specified, the default host name is used. Examples of valid host names:v mycomputer.city.company.com

v mycomputer

By default, this attribute is disabled. When disabled, the stanza entry iscommented out by using a pound sign (#) at the beginning of the stanza entry. Thefollowing example shows a commented out entry:#azn-app-host = libra

To enable this value, uncomment the entry by removing the pound sign. Be sure toinclude a host name value.

UsageOptional


Exampleazn-app-host = libra.dallas.ibm.com

azn-server-name

Syntaxazn-server-name = server–hostname


DescriptionUnique name of the Tivoli Access Manager resource manager, the policy proxyserver, authorization server, or policy server, that is configured into the domain.The hyphen (-) character is required.

Note: The host name is generated and set during configuration. Do not edit thisstanza entry.

cache-refresh-interval

Syntaxcache-refresh-interval = {disable|default|number_seconds}

DescriptionPoll interval (in seconds) between checks for updates to the master policydatabase.

Note: The local cache is rebuilt only if an update is detected.

This stanza entry is not used in the ivmgrd.conf file. The policy server has its ownstanza entries for specifying the path to the master policy database.

Optionsdisable

The interval value in seconds is not set.

defaultThe default value of 600 seconds is used.

number_secondsThe exact time interval in number of seconds. This valid is between 0 andthe size of an unsigned integer. The unsigned integer is approximately 136years.

UsageOptional

Default valuedefault

Examplecache-refresh-interval = 500

cred-attributes-entitlement-services

Syntaxcred-attributes-entitlement-services =

{short_name_entitlement_service|path_to_dll}

DescriptionService that provides the ability to add external information to the user credentialin the form of credential attributes and allows applications to use that informationin making access decisions. These extended attributes are stored in the userregistry.


This service can also work with attributes using an API call. A list of authorizationAPI entitlement service IDs are queried by the azn_id_get_creds() interface tocompile a list of attributes to be added to the user credential while the credential isbeing built.

A list of service identifiers, which can be found within the [aznapi-entitlement-services] stanza, is queried to compile a list of attributes. The attributes are addedto the user credential while the credential is being built. Each service ID is queriedin the order it is declared in the list. The attribute returned is inserted into thecredential attribute list of each credential that is built. The following exampleshows two entries from the credential attribute list:cred-attribute-entitlement-services = myEntSvcIDcred-attribute-entitlement-services = myOtherEntSvcID

Note: You cannot use this stanza entry to override read-only attributes in thecredential attribute list that include the principal name, principal UUID, andothers. The exception to this rule is for the azn_cred_groups attribute.

The IBM Tivoli Access Manager for e-business: Authorization C API Developer Referencelists the read-only attributes, contains more information about this service, andexplains why administrators who do not want this capability should ensure thatthe azn_mod_rad service is not loaded by the application.

UsageOptional


Examplecred-attribute-entitlement-services = myEntSvcID

db-file

Syntaxdb-file = fully_qualified_path

DescriptionName and location of the resource manager policy database cache file. This valuemust be specified, and each server provides its own value.



UsageRequired for each specified server.



ExampleThe following example sets the policy database using an absolute path on aWindows operating system:db-file = C:\pd\db\ivacld.db

The following example sets the policy database using a relative path on a Linux orUNIX operating system:db-file = ./authzn_demo.db

dynamic-adi-entitlement-services

Syntaxdynamic-adi-entitlement-services = entitlement_service

DescriptionDynamic access decision information (ADI) retrieval entitlement service.

Optionsentitlement_service

A string value for the container names of the required ADI. A list ofconfigured authorization API entitlements service identifiers (IDs) isqueried by the authorization rules engine when missing ADI is detectedduring an authorization rule evaluation.

When ADI is found to be missing during a rule evaluation, each service inthis list is queried in the order defined in this entry. These stanza entriesmust refer to existing entitlements services.

The service ID (for example, bank_A_ADI) are loaded by using serviceentries in the entitlement service configuration [aznapi-entitlement-services] stanza or in an initialization attribute.

Refer to “dynamic-adi-entitlement-services” on page 136 and the IBM TivoliAccess Manager for e-business: Authorization C API Developer Reference formore information about rules processing and this service, respectively.

UsageOptional


Example[aznapi-entitlement-services]dynamic-adi-entitlement-services = bank_A_ADIdynamic-adi-entitlement-services = bank_B_ADI

input-adi-xml-prolog

Syntaxinput-adi-xml-prolog = prolog_attrs

DescriptionProlog to be added to the top of the XML document that is created using theAccess Decision Information (ADI) needed to evaluate a Boolean authorizationrule.


If a style sheet prolog is specified, that prolog is imported into the empty stylesheet. If no prolog is specified, a default prolog value is used instead. All of therequired prolog attributes are specified in the default prolog entries.

Note: If any of these attributes are changed or omitted from the entry, theauthorization client fails to start and returns an error.

Optionsprolog_attrs

Prolog attributes that are required by the authorization engine and includethe following attributes:<?xml version="1.0" encoding="UTF-8"?>

Refer to “input-adi-xml-prolog and xsl-stylesheet-prolog” on page 136 formore information.

UsageOptional

Exampleinput-adi-xml-prolog = <?xml version="1.0" encoding="UTF-8"?>

listen-flags

Syntaxlisten-flags = {enable|disable}

DescriptionIndication of whether to turn on or off the reception of policy cache updatenotifications.

Optionsenable Activates the notification listener.

disableDeactivates the notification listener.

UsageOptional

Default valuedisable

Examplelisten-flags = enable

logcfg

Syntaxlogcfg = audit.azn:[log-agent][[param[=value]] ...]

DescriptionEnables logging and auditing for the application. Category, destination, and otherparameters are used to capture Tivoli Access Manager auditing and logging events.


Each server provides its own event logging setting in its correspondingconfiguration file.

Optionsaudit.azn:log-agent

Category of auditing event. Also indicates that the destination wherelog-agent is one of the following agents:v stdoutv stderrv filev pipev remote

param=valueAllowable parameters. The parameters vary, depending on the category,the destination of events, and the type of auditing you want to perform.

Refer to IBM Tivoli Access Manager for e-business: Troubleshooting Guide forinformation about the log agents and the configuration parameters.

UsageOptional

Default valueRemove the pound signs (#) at the beginning of the configuration file lines toenable authentication or authorization auditing (or both) for the application.

Examplelogcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log

mode

Syntaxmode = {local|remote}

DescriptionOperating mode for the resource manager. This value cannot be changed afterresource manager configuration.

Note: This stanza entry is set during configuration. Do not change it.

Optionslocal The resource manager uses a local policy cache.

remoteThe resource manager uses a remote policy cache that is maintained by theauthorization server.

Some configuration attributes apply only to resource managers that areconfigured to use local mode.

UsageRequired

Default valuelocal

Examplemode = remote


pd-user-name

Syntaxpd-user-name = server_name/hostname

DescriptionTivoli Access Manager user account for the resource manager server, either thepolicy proxy server, authorization server, or policy server, that is configured intothe domain. The forward slash (/) character is required.

Note: The server name or host name is generated and set during configuration. Donot edit this stanza entry.

pd-user-pwd

Syntaxpd-user-pwd = server_password

DescriptionTivoli Access Manager user account password for the resource manager, which canbe the policy proxy server, authorization server, or policy server, that is configuredinto the domain.

Note: The server password is generated and set during configuration. Do not editthis stanza entry.

permission-info-returned

Syntaxpermission-info-returned = {attribute1 attribute2 ...}

DescriptionSet of attributes that the caller wants to receive from theazn_decision_access_allowed_ext() function in the permission informationattribute list. Before using this stanza entry and value, read and thoroughlyunderstand the concept as it is discussed in the IBM Tivoli Access Manager fore-business: Authorization C API Developer Reference.

You can also define your own attributes. For example, you can set an attribute onan ACL using the acl modify command with the set attribute option.

When you add an attribute name to the list, the attribute can be returned only aspermission information if it is applicable to the current decision call.

OptionsFor a list of the strings recognized by the authorization engine, refer to IBM TivoliAccess Manager for e-business: Authorization C API Developer Reference.

UsageOptional

Default valueNo information is returned.


ExampleThe following example returns permission information for all attributes in the list:permission-info-returned = azn_perminfo_all_attrs

policy-cache-size

Syntaxpolicy-cache-size = size

DescriptionMaximum size of the in-memory policy cache. This size is configurable. The cacheconsists of policy and the relationships between policy and resources. Theknowledge that a resource has no directly associated policy is also cached.

The maximum cache size should be relative to the number of policy objectsdefined and the number of resources protected as well as the available memory.

As a starting point, use the following algorithm:

3 * (number of policy objects + number of protected resources)

This value controls how much information is cached. A larger cache potentiallyimproves the application performance, but uses additional memory as well.

Optionssize Size is specified as the number of entries.

UsageOptional

Default value32768

Examplepolicy-cache-size = 32768

resource-manager-provided-adi

Syntaxresource-manager-provided-adi = prefix

DescriptionPrefix that the authorization engine uses to determine the set of missing accessdecision information (ADI) provided by the resource manager. To specify morethan one prefix, add multiple stanza entries.

These entries must refer to existing entitlements services that were loaded usingservice entries in the [aznapi-entitlement-services] configuration stanza or thatwere loaded using an initialization attribute. If an ADI is found to be missingduring a rule evaluation, each service in this list is queried in the order defined.

Optionsprefix A string prefix for its value. For example, if you want to notify the

authorization engine that any ADI beginning with sales_customer_ beprovided by the resource manager application, the stanza entry would be:


resource-manager-provided-adi = sales_customer_

Refer to “resource-manager-provided-adi” on page 136 for moreinformation about rule processing.

UsageOptional


ExampleThe following example shows multiple stanza entries:resource-manager-provided-adi = sales_item_resource-manager-provided-adi = sales_customer_

xsl-stylesheet-prolog

Syntaxxsl-stylesheet-prolog = prolog_attrs

DescriptionThe prolog to be added to the top of the XSL stylesheet that is created using theXSL text that defines a Boolean authorization rule.

If a style sheet prolog is specified, that prolog is imported into the empty stylesheet. If no prolog is specified, a default prolog value is used instead. All of therequired prolog attributes are specified in the default prolog entries.

When not specified, the default XSL stylesheet prolog is:!<-- Required for XSLT language --><?xml version="1.0" encoding=’UTF-8’?><xsl:stylesheet xmlns:xsl=

"http://www.w3.org/1999/XSL/Transform" version="1.0">

!<-- Required to constrain output of rule evaluation --><xsl:output method="text" omit-xml-declaration="yes"

encoding=’UTF-8’ indent="no" />

!<-- Need this to ensure default text node printing isoff -->

<xsl:template match="text()"></xsl:template>

Note: If any of the required prolog attributes are changed or omitted from theentry, then the authorization client fails to start and returns an error.

Use caution when changing this setting. Refer to “input-adi-xml-prolog andxsl-stylesheet-prolog” on page 136 for more information.

Optionsprolog_attrs

Prolog attributes that are required by the authorization server.

UsageOptional


ExampleSee “Defining an XML namespace” on page 126 for a complete explanation of thename space example.

[aznapi-cred-modification-services] stanzaA credential modification service plug-in enables authorization API applications toperform modifications on a Tivoli Access Manager credential. The credentialsmodification service can then return this modified credential for use by the callingapplication. Applications can use this service to add additional information to auser's credential. For example, this additional information could include the creditcard number and credit limit of the user. Each credential modification serviceplug-in is a standalone module that is dynamically loaded into the authorizationservice.

The parameters for configuring Tivoli Access Manager credential modificationservice plug-ins are declared in the [aznapi-cred-modification-services] stanzaof each of the configuration files provided with Tivoli Access Manager:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy serverv The configuration file for configured credentials modification service plug-ins for


service-id

Syntaxservice-id = short_name|path_to_dll [ & params ...]

DescriptionDefines the authorization API service for the credentials attribute list modificationservice. Each stanza entry defines different types of aznAPI service.

OptionsEach entry has the following format:

service-idDeveloper-specified ID of the credential modification service. The serviceID string must be unique.

short_name|path_to_dllThe path to the dynamic link library (DLL) that contains the executablecode for the service.

If the DLL is located in a directory that is normally searched by the system(for example, /usr/lib on Linux and UNIX operating systems or the valueof the PATH environment variable on Windows operating systems), do notspecify the full path to the DLL, specify only the DLL name. If you want aplatform-independent DLL name, so it can be loaded on any supportedplatform, provide a short name. The short name is appended with known


library prefixes and suffixes for each platform, and each possibility issearched in turn. For example, using a short name of azn_ent_user, thefollowing table shows the names that are automatically searched for oneach platform:






params Optional: The parameters to pass to the service when it is initialized by theaznAPI service. Parameters are considered to be all data following theampersand (&). The service definition is discussed in more detail in theIBM Tivoli Access Manager for e-business: Authorization C API DeveloperReference.

UsageOptional


ExampleAZN_MOD_SVC_RAD_2AB = azn_mod_rad

[aznapi-entitlement-services] stanzaAn entitlement services plug-in enables authorization API applications to retrievethe entitlements for a user from an entitlements repository. Each entitlementservices plug-in is a standalone module that is dynamically loaded into theauthorization service.

The stanza entries for configuring Tivoli Access Manager entitlement servicesplug-ins are declared in the [aznapi-entitlement-services] stanza of each of theseconfiguration files provided by Tivoli Access Manager:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy serverv The configuration file for configured entitlement services plug-ins for your

resource managersThe aznAPI.conf configuration file is provided with Tivoli Access Manager as asample file for creating your own resource manager configuration file.Developers of service plug-ins should provide the standard functions. Beforeimplementing service plug-ins, read and thoroughly understand the conceptsdiscussed in the IBM Tivoli Access Manager for e-business: Authorization C APIDeveloper Reference.


service-id

Syntaxservice-id = {short_name|path_to_dll} [ & params ...]

DescriptionDefines the authorization API service for the entitlement services of the protectedobjects. Each stanza entry defines different types of aznAPI service.


service-idDeveloper-specified ID by which the service can be identified by theaznAPI client. The service ID string must be unique.


If the DLL is located in a directory that is normally searched by the system(for example, /usr/lib on Linux and UNIX operating systems or the valueof the PATH environment variable on Windows operating systems), do notspecify the full path to the DLL, specify only the DLL name. If you want aplatform-independent DLL name, so it can be loaded on any supportedTivoli Access Manager platform, provide a short form library name. Theshort name is appended with known library prefixes and suffixes for eachplatform, and each possibility is searched in turn. For example, using ashort form library name of azn_ent_user, the following names that areautomatically searched for on each platform:






params Optional: One or more parameters to pass to the service when it isinitialized by the aznAPI service. Parameters are considered to be all datafollowing the ampersand (&). The service definition is discussed in moredetail in the IBM Tivoli Access Manager for e-business: Authorization C APIDeveloper Reference.

UsageOptional


Examplecredattrs_ent_svc = azn_ent_cred_attrs


[aznapi-external-authzn-services] stanzaAn external authorization service plug-in is an optional extension of the TivoliAccess Manager authorization service that allows you to impose additionalauthorization controls and conditions. You can use an external authorizationservice plug-in to force authorization decisions to be made is based onapplication-specific criteria that are not known to the Tivoli Access Managerauthorization service. Each external authorization service plug-in is a standalonemodule that is dynamically loaded into the authorization service.

The parameters for configuring Tivoli Access Manager external authorizationservice plug-ins are declared in the [aznapi-external-authzn-services] stanza ofthis configuration file provided by Tivoli Access Manager:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The configuration file for configured external authorization service plug-ins for


policy-trigger

Syntaxpolicy-trigger = {short_name|path_to_dll} [-weight number]

[ & params ...]

DescriptionDefines the authorization API service for external authorization service definitionsthat force authorization decisions to made based on application-specific criteria.Each stanza entry defines different types of aznAPI service, and each entry is thesame format.

Optionspolicy-trigger

The policy trigger is the way that an external authorization service isinvoked. It is either a service ID or an access control list (ACL) actionstring. For example, it can be my_service_1 or Trx. If the service is definedan ID, the service ID is used as an extended attribute on a POP thattriggers the external authorization service when an object has this POPattached to it. If the service is defined using an ACL action string, theservice is invoked when this ACL action mask is requested as part of anauthorization decision.

The policy trigger can be any string that is recognized as a valid key name.The policy-trigger is case-sensitive, because the actions themselves arecase-sensitive. However, the policy trigger is not case-sensitive if thetrigger is a POP attribute.



If the DLL is located in a directory that is normally searched by the system(for example, /usr/lib on Linux and UNIX operating systems or the valueof the PATH environment variable on Windows operating systems), do notspecify the full path to the DLL, specify only the DLL name. If you want aplatform-independent DLL name, so it can be loaded on any supportedplatform, provide a short name. The short name is appended with knownlibrary prefixes and suffixes for each platform, and each possibility issearched in turn. For example, using a short name of azn_ent_user, thefollowing names that are automatically searched for on each platform:






[-weight number]Optional: A weighting that is assigned in the access decision process to theparticular external authorization service. This option is an unsigned size_tvalue. This value signifies the weight that any decision that is returned bythis external authorization service should be given in the entire decisionprocess. The default value is 101.

params Optional: Additional initialization information to pass to the externalauthorization service in the form of arguments. The arguments must bepreceded by the ampersand (&); for example, & -server fred. The servicedefinition is discussed in more detail in the IBM Tivoli Access Manager fore-business: Authorization C API Developer Reference.

UsageOptional


[aznapi-pac-services] stanzaA PAC services plug-in gives authorization API applications the ability to moveTivoli Access Manager credentials back and forth between the native Tivoli AccessManager credentials format and an alternate format called privilege attributecertificate (PAC). Each PAC services plug-in is a standalone module that isdynamically loaded into the authorization service.

Identity information can be obtained from a PAC. Applications can convert usercredentials to PACs for use within other authorization domains. Applications canthen pass the PACs to a server in another authorization domain and perform anoperation.

The stanza entries for configuring Tivoli Access Manager PAC services plug-ins aredeclared in the [aznapi-pac-services] stanza of each of these configuration filesprovided by Tivoli Access Manager:


v The configuration file for configured PAC services plug-ins for your resourcemanagers

The aznAPI.conf configuration file is provided with Tivoli Access Manager as asample file for creating your own resource manager configuration file. Developersof service plug-ins should provide the standard functions. Before implementingservice plug-ins, read and thoroughly understand the concepts discussed in theIBM Tivoli Access Manager for e-business: Authorization C API Developer Reference.

service-id

Syntaxservice-id = {short_name|path_to_dll}

[ & params ... ]

DescriptionDefines the authorization API service for the Tivoli Access Manager privilegeattribute certificate (PAC) encoding service. Each stanza entry defines differenttypes of aznAPI authorization service.


service-idDeveloper-specified ID of the PAC service that produces the PAC. Theservice ID string must be unique.

short_name|path_to_dllThe path to the dynamic link library (DLL) that contains the executablecode for the service executable.

If the DLL is located in a directory that is normally searched by the system(for example, /usr/lib on Linux and UNIX operating systems or the valueof the PATH environment variable on Windows operating systems), do notspecify the full path to the DLL, specify only the DLL name. If you want aplatform-independent DLL name, so it can be loaded on any supportedplatform, provide a short name. The short name is appended with knownlibrary prefixes and suffixes for each platform, and each possibility issearched in turn. For example, using a short form library name ofazn_ent_user, the following names that are automatically searched for oneach platform:






params Optional: Parameters to pass to the service when it is initialized by theaznAPI service. Parameters are considered to be all data following theampersand (&). The service definition is discussed in more detail in theIBM Tivoli Access Manager for e-business: Authorization C API DeveloperReference.


UsageOptional


[cars-client] stanzaThe [cars-client] stanza contains the configuration of the client for the commonaudit service. The entries in this stanza specify the characteristics of the connectionto the common event Web service and how the client processes audit log events.You must specify the doAudit and serverURL entries. If these entries are notspecified, the common audit service is not configured for use by Tivoli AccessManager.

If secure communication with the common event Web service is required, you needto specify the keyFilePath and stashFilePath entries.

The stanza entry for common audit processing is located in the [pdcars-filter]stanza of the pdaudit.conf file.

compress

Syntaxcompress = {yes|no}

DescriptionIndicates whether the data that is sent during a network transfer is compressed.

Optionsyes Compresses the data that is sent during a network transfer.

no Does not compress the data that is sent during a network transfer. This isthe default value.

UsageOptional

Default valueThe default value is no.

Examplecompress = yes

diskCachePath

SyntaxdiskCachePath = fully_qualified_path

DescriptionSpecifies the name and location of the file to be used to cache events. The file mustexist at the specified location.

When events are written to the disk cache file, a cache manager thread periodicallychecks (using the setting of the rebindInterval entry) to determine whether the


audit Web service can accept events. When the service is available, the cachemanager sends the events from the disk cache file.

The name of the disk cache file must be unique. If more than one server or serverinstance is configured to use the same disk cache file, errors will occur.



UsageConditional. This entry is used when the useDiskCache entry is set to auto oralways.


doAudit

SyntaxdoAudit = {yes|no}

DescriptionAn indication of whether auditing using the Common Auditing Service is enabledor disabled. When auditing is disabled, events are not forwarded to the auditserver.

After configuring the Common Auditing Service, you can start auditing using thefollowing steps:1. Enter the following commands:

> pdadmin login -lpdadmin local> config modify keyvalue set config_file cars-client doAudit yes

2. Restart the server.

To stop auditing, complete the following steps:1. Enter the following commands:

> pdadmin login -lpdadmin local> config modify keyvalue set config_file cars-client doAudit no

2. Restart the server.

Optionsyes Enables auditing using the common audit service.

no Disables auditing for the common audit service. This is the default value.

UsageRequired


Default valueThe default value is no.

ExampledoAudit = yes

clientPassword

SyntaxclientPassword = password

DescriptionSpecifies the password for the WebSphere audit ID.

UsageConditional. This stanza entry is required only when using secure communicationswith the Web service.


clientUserName

SyntaxclientUserName = user_id

DescriptionSpecifies the WebSphere audit ID used by the administrator. This ID isauthenticated with HTTP basic authentication.



errorFilePath

SyntaxerrorFilePath = fully_qualified_path

DescriptionSpecifies the name and location of the error log file. If the file does not exist at thespecified location, it will be created by the server identity.

The name of the log file must be unique. If more than one server or server instanceis configured to use the same log file, errors will occur.


Represents an alphanumeric string. String values are expected to becharacters that are part of the local code set. The set of characterspermitted in a file name can be determined by the file system and by thelocal code set. For Windows operating systems, file names cannot have a


backward slash (\), a colon (:), a question mark (?), or double quotationmarks ("). For Linux and UNIX operating systems, path names and filenames are case-sensitive.

UsageOptional


flushInterval

SyntaxflushInterval = interval

DescriptionLimits the time an event waits in the queue before being forwarded to the auditserver. When events are generated at a slow rate and the queue does not reach thehigh water mark in a timely manner, use this entry to forward the events in thequeue at the designated interval.

Optionsinterval

Specifies the number of seconds that an event waits in the queue.

UsageConditional. This entry is used when the useDiskCache entry is set to auto ornever.


ExampleflushInterval = 600

keyFilePath

SyntaxkeyFilePath = fully_qualified_path

DescriptionSpecifies the SSL key file name and location. Use the SSL key file to handlecertificates that are used to communicate with the common event Web service. Thefile extension can be anything, but the extension is usually .kdb.






lowWater

SyntaxlowWater = number

DescriptionSpecifies the low water mark for the number of events that can be in the queuebefore events are no longer removed from the queue and written to the disk cachefile.

When the audit server is slow and the event queue fills up, events are removedfrom the queue and written to the disk cache file until the number of the events isqueue is equal to or less than the low water mark. When this low water mark isreached, queued events are sent directly to the audit server.

UsageConditional. This entry is used when the useDiskCache entry is set to auto.

Default valueThe default value is 10.

hiWater

SyntaxhiWater = number

DescriptionSpecifies the high water mark for the number of events that can be in the queue.When this high water mark is reached, events are sent to the audit server.

Optionsnumber

Indicates the maximum number of events that can be in the queue.

UsageOptional. This entry is used when the useDiskCache entry is set to auto or never.


ExamplehiWater = 30

maxCacheFiles

SyntaxmaxCacheFiles = number


DescriptionSpecifies the maximum number of disk cache files that can be created. Unlike errorlog and trace files, disk cache files can be used again.

After all of the events in the disk cache file are sent to the audit Web service, thecache manager deletes that cache file.



maxCacheFileSize

SyntaxmaxCacheFileSize = size

DescriptionSpecifies the maximum size in bytes of the disk cache file. When this size isreached, the cache file rolls over and a new cache file is created. The maximumsize is 1 gigabyte (1,073,741,824 bytes).



maxErrorFiles

SyntaxmaxErrorFiles = number

DescriptionSpecifies the maximum number of error log files that can be created before theoldest log file is used again.

UsageOptional


maxErrorFileSize

SyntaxmaxErrorFileSize = size

DescriptionSpecifies the maximum size in bytes of the error log file. When this size is reached,the log file rolls over and a new error log file is created. For additional informationabout how log files roll over, see the IBM Tivoli Access Manager for e-business:Administration Guide.


UsageOptional


maxTraceFiles

SyntaxmaxTraceFiles = number

DescriptionSpecifies the maximum number of trace files that can be created before the oldesttrace file is used again.

UsageOptional


maxTraceFileSize

SyntaxmaxTraceFileSize = size

DescriptionSpecifies the maximum size in bytes of the trace log file. When this size is reached,the log file rolls over and a new error log file is created. For additional informationabout how log files roll over, see the IBM Tivoli Access Manager for e-business:Administration Guide.

UsageOptional


numberCMThreads

SyntaxnumberCMThreads = number_of_threads

DescriptionNumber of threads to create for the cache manager. These threads read events fromthe disk cache files and sends them to the server.

Optionsnumber_of_threads

Represents a numeric value.

UsageOptional. This entry is used when the useDiskCache entry is set to auto or always.



ExamplenumberCMThreads = 2

numberEQThreads

SyntaxnumberEQThreads = number_of_threads

DescriptionNumber of threads to create to service the event queue.

Optionsnumber_of_threads

Represents a numeric value.



ExamplenumberEQThreads = 2

numberRetries

SyntaxnumberRetries = number

DescriptionWhen an error occurs during a network transfer, specifies the number of attemptsto make to send the data.

UsageOptional


queueSize

SyntaxqueueSize = size

DescriptionMaximum number of audit events that can be queued.




rebindInterval

SyntaxrebindInterval = seconds

DescriptionSpecifies that number of seconds that the cache manager waits before attemptingto establish a connection to the audit Web service.



retryInterval

SyntaxretryInterval = seconds

DescriptionWhen an error occurs during a network transfer, specifies the number of secondsto wait before another attempt is made to send the data.

UsageOptional


serverURL

SyntaxserverURL = url

DescriptionSpecifies the URL of the common auditing Web service. For secure communication,use the following URL:

https://hostname:9443/CommonAuditService/service/Emitter

For nonsecure communication, use the following URL:http://hostname:9080/CommonAuditService/service/Emitter

Optionsurl The URL of the common auditing Web service.

UsageRequired



stashFilePath

SyntaxstashFilePath = fully_qualified_path

DescriptionSpecifies the SSL password stash file name and location. The password is used toprotect private keys in the key file. The password might be stored encrypted in thestash file. The file extension can be anything, but it is usually .sth.





traceLevel

SyntaxtraceLevel = level

DescriptionSpecifies the level of trace events to write to the trace log. The following settingsare valid:

1 Indicates that events resulting from error conditions only are written to the log.

2 Indicates that the following events only are written to the log file:v Error conditionsv Entry and exit trace points

3 Indicates that events resulting from error conditions and from all trace pointsin the code are written to the log.

UsageConditional. Required when traceFilePath is defined.


traceFilePath

SyntaxtraceFilePath = fully_qualified_path


DescriptionSpecifies the name and location of the trace file. If the file does not exist at thespecified location, it will be created by the server identity.

The name of the trace file must be unique. If more than one server or serverinstance is configured to use the same trace file, errors will occur.



UsageOptional


transferSize

SyntaxtransferSize = size

DescriptionNumber of audit events to send on each network transfer.

UsageOptional


useDiskCache

SyntaxuseDiskCache = {auto|always|never}

DescriptionSpecifies whether to enable disk caching, and, when enabled, indicates how tohandle disk caching.

Optionsalways Indicates that audit events are always written directly to the disk cache on

the caller thread. There is no event queue.

never Indicates that audit events are written to the event queue. There is no diskcache.

auto Indicates that audit events are written to the event queue except when theserver is down or the event queue is full. Under these conditions, the auditevents are written to disk cache.


UsageOptional

Default valueThe default value is auto.

[cars-filter] stanzaThe stanza entry for common audit filtering of the Tivoli Access Manager runtimeis located in the [cars-filter] stanza of the pdaudit.conf file.

auditevent

Syntaxauditevent = type, [outcome=outcome]

DescriptionIdentifies the events to be captured for auditing. Events can be identified by eventtype, application name, and outcome. If an event logged by an application matchesany configured filter entry (auditevent or outcome), it is forwarded to the CommonAuditing Service server.

For each event type to capture, the configuration file must include a separatestanza entry.

To add event types to the event filter, use the config modify command with theappend option.

To remove event types from the event filter, use the config modify command withthe remove option.

Note: With the auditevent entry, do not use the config modify command with theset option. Using the set option overwrites the first auditevent entry in theconfiguration file.

Optionstype Specifies one of the following event types:

authn Indicates authentication events. This event type can be used withall Tivoli Access Manager servers.

authn_creds_modifyIndicates events that modify credentials for users. This event typecan be used with all Tivoli Access Manager servers.

authn_terminateIndicates termination events. These types of events are the resultsof a timeout, an administration terminating a session, or auser-initiated log out. This event type can be used with all TivoliAccess Manager servers.

authz Indicates authorization events. This event type can be used with allTivoli Access Manager servers.

mgmt_configIndicates configuration and other management events for a server.This event type can be used with the policy server.


mgmt_policyIndicates events for security policy management, such as thecreation of an ACL. This event type can be used with the policyserver.

mgmt_registryIndicates events for registry management, such as creating usersand groups, administrator-initiated password changes, andmodifying properties of users and groups. This event type can beused with the policy server.

mgmt_resourceIndicates events for resource events. This event type can be usedwith the policy server.

password_changeIndicates events for user-initiated password changes. This eventtype can be used with the policy server, WebSEAL server, or theplug-in for Web servers.

Administrator-initiated password changes are classified as registrymanagement events.

resource_accessIndicates events that record all accesses to a resource, such as a fileor HTTP request and response events outside of authorizationevents. This event type can be used with the WebSEAL server orthe plug-in for Web servers.

runtimeIndicates runtime events, such as starting and stopping securityservers. Events generated from administrator-initiated tasksclassified as management tasks. This event type can be used withall Tivoli Access Manager servers. Additionally, this event type canbe used for reporting WebSEAL statistics.

outcome=outcomeSpecifies one of the following outcomes:

all Records all outcomes. This is the default value.

successRecords successful outcomes only.

unsuccessfulRecords unsuccessful outcomes only.

unknownRecords outcomes where success could not be determined. Thisvalue applies to authz and resource_access event types only.

UsageRequired.


Exampleauditevent = authn, outcome=unsuccessfulauditevent = authz, outcome=unknown


[configuration-database] stanzaThe stanza entry defines the name and location of the Tivoli Access Managerobfuscated password configuration file. Tivoli Access Manager creates a newconfiguration file containing all the obfuscated entries. For example, All bind (login) passwords are obfuscated and placed in the configuration file. Both the existingconfiguration file and the obfuscated configuration file have the same file name,except that .obf is appended to the file name (for example, ivmgrd.conf.obf).

In addition, Tivoli Access Manager creates the [configuration-database] stanza, asneeded, whenever an obfuscated entry is automatically added to the obfuscatedconfiguration file. This stanza has a stanza entry that points to the name andlocation of the obfuscated configuration file. The [configuration-database] stanzacan be located in every configuration file, including the pd.conf configuration file,if an obfuscated value is added to the file.

You should never edit the entry in the [configuration-database] stanza. The oneexception might be if the file is to be moved permanently to a different location.This scenario is the only circumstance where the file name and location should bemodified. Remember that whenever the configuration file is moved to a differentlocation, you must move the obfuscated file also.

file

Syntaxfile = fully_qualified_path

DescriptionFile name and location where the obfuscated configuration file information islocated.

Note: The obfuscated password is generated and set by the configuration utility.Do not edit this stanza entry.

The name of the obfuscated configuration file is the same name as the relatedconfiguration file name. The file extension can be anything, but the extension isusually .conf.obf. For example, the obfuscated configuration file for ldap.conf isldap.conf.obf.



UsageConditional. This stanza entry is required only if, during configuration, passwordswere obfuscated.


Default valueThe following table shows the default installation location by platform.

Platform File name

Linux or UNIX /opt/PolicyDirector/etc/server_name.conf.obf

Windows c:\program files\tivoli\policy director\etc\server_name.conf.obf

ExampleThe following example of setting the location of the obfuscated configuration filewhen using Microsoft Active Directory as the user registry on a Windowsoperating system:c:\program files\tivoli\policy director\etc\activedir.conf.obf

[delegated-admin] stanzaThe Tivoli Access Manager configuration can require that the user be authorized toview each group that is returned in the group list. Or, the user can be authorizedto return the list without authorizing first.

For delegated administration, you should use one type of interface throughout theentire process for optimal results. Use either Web Portal Manager or the pdadminutility. This stanza relates only to the pdadmin utility.

The stanza entries for turning on or off the setting for authorization checks for thedelegated management of groups and users are located in the [delegated-admin]stanza of the following configuration file:v The ivmgrd.conf configuration file for the policy server

authorize-group-list

Syntaxauthorize-group-list = {yes|no}

DescriptionIndication of whether authorization checks on the group list and group list-dncommands should be made.

This keyword is provided as a performance feature.

Optionsyes Enables authorization checks.

no Disables authorization checks.

UsageOptional

Default valueno

Exampleauthorize-group-list = yes


[domains] and [domain=domain_name] stanzasThe [domains] stanza contains a list of domains. Each domain specified under thisstanza must have its own [domain=domain_name] stanza. The following exampleshows domains named d and mydomain:[domains]domain = ddomain = mydomain

[domain=d]

[domain=mydomain]

The stanza entries for configuring multiple domains are located in the [domains]and the [domain=domain_name] stanzas of the following configuration file:v The ivmgrd.conf configuration file for the policy server

allowed-registry-substrings

Syntaxallowed-registry-substrings = dn

DescriptionDistinguished name (DN) substring that restricts into which registry locationsusers can be created in or be imported from.

The DN of the user being created or imported must contain the substring valuespecified. The DN substring value restrictions are registry dependent. Most userregistries allow an alphanumeric string that is not case-sensitive. String values areexpected to be characters that are part of the local code set.

You can specify one or more relative DNs to use when creating users. Byspecifying one or more substrings, you can restrict creating and importing usersand groups to the relative DNs that are identified by the substrings. For example,you can specify the DN substring dc=mkt to restrict users who are created orimported into a domain named Marketing:

As a management domain administrator, complete the following tasks:1. Manually add the dn value for each domain created, except the Management

(policy server) domain.2. Notify the domain administrator, after this key value pair is added, to add this

string to the DN option when creating and importing users or groups.

Optionsdn The distinguished name substring

UsageOptional


Exampleallowed-registry-substrings = "dc=mkt"


database-path

Syntaxdatabase-path = fully_qualified_path

DescriptionFile name and location of the policy database for the domain listed. The name ofthe database is the same as the domain name. The file extension can be anything,but the extension is usually .db.

Note: Editing this entry is not recommended.

OptionsThe fully_qualified_path value represents an alphanumeric string. String values areexpected to be characters that are part of the local code set. The set of characterspermitted in a file name can be determined by the file system and by the localcode set. For Windows operating systems, file names cannot have a backward slash(\), a colon (:), a question mark (?), or double quotation marks ("). For Linux andUNIX operating systems, path names and file names are case-sensitive.

UsageConditional. This stanza entry is required when the user creates at least onedomain.

Default valueThe following table shows the default value by platform.

Platform File name

Linux or UNIX /var/PolicyDirector/db/domain_name.db

Windows c:\program files\tivoli\policy director\db\domain_name.db

ExampleThe following example shows the setting of the database path on a Windowsoperating system:d:\programs\ibm\am\db\dname1.db

domain

Syntaxdomain = domain_name

DescriptionName of the domain that was created.

OptionsThe domain_name value is an alphanumeric, case-sensitive string. String values areexpected to be characters that are part of the local code set.

UsageConditional. This stanza entry is required when the user creates at least onedomain.



Exampledomain = mydomain1

[ivacld] stanzaThe stanza entries for configuring authorization server-related information arelocated in the [ivacld] stanza in the following configuration file:v The ivacld.conf configuration file for the authorization server

log-file

Syntaxlog-file = fully_qualified_path

DescriptionLocation and name of the log file. Messages are redirected from STDOUT andSTDERR and sent to the server log file as defined in the authorization serverrouting file (pdacld_routing). The authorization server relies on the routing file todetermine the log file names and path.

At startup of the authorization server, a check is made to see if the routing fileexists. If it exists, the routing file is used and this stanza entry is ignored;otherwise, this stanza entry is used.


During installation of Tivoli Access Manager, if you enabled Tivoli CommonDirectory to specify one common directory location for all your base componentlog files, the default installation directory is different. For example:log-file = TCD/HPD/logs/msg__pdacld_utf8.log

The 3-character identifier used in the example is HPD, which specifies that the logfiles are for the Tivoli Access Manager common components.

UsageRequired


Platform File name

Linux or UNIX /var/PolicyDirector/log/msg__pdacld_utf8.log

Windows c:\program files\tivoli\policy director\log\msg__pdacld_utf8.log

ExampleThe following example sets the log file as Tivoli Common Directory on a Windowsoperating system:


log-file = C:\pd\log\msg__pdacld_utf8.log

The following example sets the log file as Tivoli Common Directory on a Linux orUNIX operating system:/PolicyDirector/TAMBase/HPD/logs/msg__pdacld_utf8.log

logcfg

Syntaxlogcfg = audit.azn:{log-agent} path=path

flush_interval=interval log_id

DescriptionEnables logging and auditing for the authorization component.


Optionsaudit.azn

Category that indicates auditing of the authorization component.

log-agentIndicates that the destination where log-agent is one of the followingvalues:v stdoutv stderrv filev pipev remote

path = pathSpecifies the name and location of the log file that is used for the log-agent.

flush_interval = intervalSpecifies the frequency for flushing log file buffers.

log_id Specifies the identifier for directing events from additional categories to thesame log-agent.

Remove the pound signs (#) at the beginning of the configuration file lines toenable authentication or authorization auditing (or both) for the application.

UsageOptional


ExampleThe following example shows the configuration for authentication andauthorization auditing:logcfg = audit.azn:file path=/var/PolicyDirector/audit/

ivacld.log,flush_interval=20,log_id=PDAclAuditlogcfg = audit.authn:file log_id=PDAclAudit


permit-unauth-remote-caller

Syntaxpermit-unauth-remote-caller= {true|false}

DescriptionIndication of whether authorization API clients should be authorized by theauthorization server before their requests are processed.

Optionstrue Authorization API clients should not be authorized.

Attention: Specifying true exposes the policy database in the domain forall clients to read, not just those that were properly authorized withmembership in the remote-acl-users group. Depending on the nature ofthe policy within the domain security, system planners must consider theability for any client to read system-defined policy to be a securityproblem.

false Authorization API clients should be authorized.

UsageOptional

Default valuefalse

Examplepermit-unauth-remote-caller= false

pid-file

Syntaxpid-file = fully_qualified_path

DescriptionLocation and name of the PID file.



UsageRequired


Platform File name

Linux or UNIX /var/PolicyDirector/log/ivacld.pid


Platform File name

Windows c:\progra files\tivoli\policy director\log\ivacld.pid

ExampleExample for a Windows operating system:pid-file = C:\pd\log\ivacld.pid

tcp-req-port

Syntaxtcp-req-port = {0|port}

DescriptionTransmission Control Protocol (TCP) port on which the server is listening forrequests.

Options0 Disable the port number.

port Enable the port number. Use any valid port number. A valid port numberis any positive number that is allowed by TCP/IP and that is not currentlybeing used by another application. Use the default value, or use a portover 1000 that is not currently being used.

UsageRequired

Default value7136

Exampletcp-req-port = 7136

unix-user

Syntaxunix-user = user_name

DescriptionThe Linux or UNIX user account for this server. The server will run as this useraccount.

OptionsThe user_name value represents an alphabetic string for the name associated withthe user account.

UsageRequired

Default valueivmgr

Exampleunix-user = ivmgr


unix-group

Syntaxunix-group = group_name

DescriptionThe Linux or UNIX group account for this server. The server will run as thisaccount.

OptionsThe group_name value represents an alphabetic string for the group associated withthe user account.

UsageRequired

Default valueivmgr

Exampleunix-group = ivmgr

[ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are locatedin the [ivmgrd] stanza in this configuration file:v The ivmgrd.conf configuration file for the policy server

provide-last-login

Syntaxprovide-last-login = {yes|true|no|false}

DescriptionUse the provide-last-login option for reporting information about the last logininstance of a user.

To record the last login information for LDAP based registries, set [ldap]enable-last-login to yes.

For Microsoft Active Directory registry, Tivoli Access Manager uses the ActiveDirectory user attribute lastLogonTimestamp to report the last login time of theuser. This attribute is a system attribute and is updated automatically by ActiveDirectory. Tivoli Access Manager has no control over this attribute except reportingthe value when required. This attribute is not updated every time a user logs insuccessfully. When a user logs in successfully, this attribute is only updated if itscurrent value is older than the current time minus the value of themsDS-LogonTimeSyncInterval attribute.

Thus the value that Tivoli Access Manager reports for the last login of a user mightnot be the exact time that a user last logged in. The reported time might be theactual last login time minus the configurable value of msDS-LogonTimeSyncInterval.You can configure the default value of msDS-LogonTimeSyncInterval to suit the enduser domain policy.


To leverage the lastLogonTimestamp attribute, the Active Directory domains mustbe at Microsoft Windows 2003 domain functional level. For more informationabout lastLogonTimestamp and msDS-LogonTimeSyncInterval, visit the Microsoftsupport Web site.

Optionsyes|true

Set the provide-last-login option to yes, to let the policy server report thetime of last login of a user.

no|falseSet the provide-last-login option to no, to disable reporting of the lastlogin information about a user.

provide-last-pwd-change

Syntaxprovide-last-pwd-change = {yes|true|no|false}

DescriptionUse the provide-last-pwd-change option to permit reporting of information aboutthe last password change instance of a user.

Optionsyes|true

Set the provide-last-pwd-change option to yes, to let the policy serverreport the last password change instance of a user.

no|falseSet the provide-last-pwd-change option to no, to disable reporting of thelast password change instance of a user.

auto-database-update-notify

Syntaxauto-database-update-notify = {yes|true|no|false}

DescriptionIndication of automatic or manual update notification for policy database replicas.

Optionsyes|true

Enable automatic update notification. This automatic setting is appropriatefor environments where database changes are few and infrequent. Whenyou configure update notification to be automatic, you must also correctlyconfigure the max-notifier-threads= and notifier-wait-time= stanzaentries.

no|falseEnable manual update notification.

UsageRequired

Default valueyes


Exampleauto-database-update-notify = yes

ca-cert-download-enabled

Syntaxca-cert-download-enabled = {yes|no}

DescriptionThe policy server always allows the download of the CA certificate. It is up to theclient application to allow whether the CA certificate can be downloaded.Independent of the defined value, the policy server ignores this configurationsetting.

UsageIgnored

database-path

Syntaxdatabase-path = fully_qualified_path

DescriptionLocation and name of the master policy database. The file extension can beanything, but the extension is usually .db.

Note: Editing this stanza entry is not recommended.



UsageRequired


Platform File name

Linux or UNIX /var/PolicyDirector/db/master_authzn.db

Windows c:\program files\tivoli\policy director\db\master_authzn.db

ExampleThe following example set the path to the master policy database on a Windowsoperating system:database-path = C:\pd\db\master_authzn.db


log-file


DescriptionLocation and name of the log file. Messages are redirected from STDOUT andSTDERR and sent to the server log file as defined in the policy server routing file(pdmgrd_routing). The policy server relies on the routing file to determine the logfile names and path.

At startup of the policy server, a check is made to see if the routing file exists. If itexists, the routing file is used and this stanza entry is ignored; otherwise, thisstanza entry is used.


UsageRequired


Platform File name

Linux or UNIX /var/PolicyDirector/log/msg__pdmgrd_utf8.log

Windows c:\program files\tivoli\policy director\log\msg__pdmgrd_utf8.log

During installation of Tivoli Access Manager, if you enabled Tivoli CommonDirectory to specify one common directory location for all your log files, thedefault installation directory is different.

ExampleThe following example sets the log file on a Windows operating system withoutTivoli Common Directory:log-file = C:\pd\log\msg__pdmgrd_utf8.log

The following example sets the log file on a Linux or UNIX operating system withTivoli Common Directory:log-file = TCD_directory/HPD/logs/msg__pdmgrd_utf8.log

The 3-character identifier used in the example is HPD, which specifies that the logfiles are for Tivoli Access Manager.

logcfg

Syntaxlogcfg = audit.azn:{log-agent} path=path

flush_interval=interval log_id




Optionsaudit.azn

Category that indicates auditing of the authorization component.

log-agentIndicates that the destination where log-agent is one of the followingvalues:v stdoutv stderrv filev pipev remote

path = pathSpecifies the name and location of the log file that is used for the log-agent.

flush_interval = intervalSpecifies the frequency for flushing log file buffers.

log_id Specifies the identifier for directing events from additional categories to thesame log-agent.

Remove the pound signs (#) at the beginning of the configuration file lines toenable authentication or authorization auditing (or both) for the application.

UsageOptional


ExampleThe following example sets the configuration for authentication and authorizationauditing only :logcfg = audit.azn:file path=/var/PolicyDirector/audit/

pdmgrd.log,flush_interval=20,log_id=PDMgrAuditlogcfg = audit.authn:file log_id=PDMgrAudit#logcfg = audit.mgmt:file log_id=PDMgrAudit

max-notifier-threads

Syntaxmax-notifier-threads = number_threads

DescriptionMaximum number of event notifier threads. The policy server is responsible forsynchronizing all database replicas in the secure domain. When a change is madeto the master database, notification threads do the work of announcing this changeto all replicas. Each replica then has the responsibility to download the newinformation from the master.


When the update notification stanza entry is set to yes, you must correctlyconfigure this stanza entry and also the notifier-wait-time= stanza entry.

Optionsnumber_threads

Generally, this value should be set to equal the number of existing replicas.Specify a valid, positive whole number. Valid range for the number ofthreads is between 1 and 128.

UsageConditional. This stanza entry is required when auto-database-update-notify =yes.

Default value10

Examplemax-notifier-threads = 20

notifier-wait-time

Syntaxnotifier-wait-time = time_seconds

DescriptionTime in seconds that the authorization policy database is idle before notification issent to replicas. When the policy server is instructed to make a change to themaster policy database, it waits for a default period of time before sending outnotifications to database replicas. This time delay is reset with each subsequentchange to the database.

When the update notification stanza entry is set to yes, you must correctlyconfigure this stanza entry and also the max-notifier-threads= stanza entry.

Optionstime_seconds

The number of seconds the authorization policy database is idle beforenotification is sent to replicas.

UsageConditional. This stanza entry is required when the auto-database-update-notify= yes.

Default value15

Examplenotifier-wait-time = 30

pid-file






UsageRequired


Platform File name

Linux or UNIX /var/PolicyDirector/log/ivmgrd.pid

Windows c:\program files\tivoli\policy director\log\ivmgrd.pid

ExampleExample for a Linux or UNIX operating system:pid-file = /var/PolicyDirector/log/ivmgrd.pid

standby

Syntaxstandby = {0|number}

DescriptionNumber of standby policy servers

Note: The number of standby servers is generated and set by the configurationutility. Do not edit this stanza entry.

Options0 Zero indicates that no policy servers are standby servers.

numberThe number of standby policy servers. Use a number that is a positivewhole number. Currently, this number is only 1.

UsageRequired

Default value0

Examplestandby = 1


tcp-req-port


DescriptionTCP port on which the server is listening for requests.

Options0 Disables the port number.

port Enables the port number. Specify any valid port number. A valid portnumber is any positive number that is allowed by TCP/IP and that is notcurrently being used by another application. Use the default port number,or use a port number over 1000 that is currently not being used.

UsageRequired

Default value8135


unix-user


DescriptionThe Linux or UNIX user account for this server. The server will run as thisaccount.

Optionsuser_name

Represents an alphabetic string for the name associated with the useraccount.

UsageRequired

Default valueivmgr


unix-group


DescriptionThe Linux or UNIX group account for this server. The server will run as thisaccount.


Optionsgroup_name

Represents an alphabetic string for the group associated with the useraccount.

UsageRequired

Default valueivmgr


[ldap] stanzaThis stanza defines configuration key value pairs that are required for the TivoliAccess Manager servers to communicate with the server that is associated with anLDAP user registry.

The value for the user registry stanza entry (ldap-server-config) is determined bythe pd.conf file. The pd.conf file is created when the Tivoli Access Managerruntime component is configured.

The key value pairs that are used only for the LDAP registry server are located inthe ldap.conf configuration file in the [ldap] stanza. The LDAP server stanzaentries are described separately in “[ldap] stanza for ldap.conf” on page 278.

The key value pairs that are for the server configuration files are located in the[ldap] stanza of each of the following configuration files:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy serverv Your resource managers' configuration file for configured LDAP entries

The aznAPI.conf configuration file is provided with Tivoli Access Manager as asample file for creating your own resource manager configuration file.Developers of service plug-ins should provide the standard functions. Beforeimplementing service plug-ins, read and thoroughly understand the conceptsdiscussed in the IBM Tivoli Access Manager for e-business: Authorization C APIDeveloper Reference.

enhanced-pwd-policy

Syntaxenhanced-pwd-policy = {yes|true|no|false}

DescriptionThe LDAP registries Tivoli Access Manager uses provide password policyenforcement for LDAP accounts. Tivoli Access Manager uses LDAP accountpasswords for authentication. So Tivoli Access Manager is subject to LDAP registrypassword policies. When the enhanced-pwd-policy option is enabled, Tivoli AccessManager efficiently identifies the underlying LDAP registry password policy andreacts appropriately. The Tivoli Access Manager password policy is enforcedconcurrently and is not affected by the enhanced-pwd-policy option.


This option is supported for Sun Directory Server 6.3.1 and Tivoli Directory Server.For Tivoli Directory Server, Tivoli Access Manager versions older than 6.1.1provide limited support for handling LDAP registry password policies. Theenhanced-pwd-policy option enhances such support.

When you set the auth-using-compare option to no, a user password isauthenticated by creating a connection to the LDAP registry and binding theconnection using the user password. Success or failure of the binding is noted andthe connection is closed. If you set the enhanced-pwd-policy option is set to yeswhen auth-using-compare is set to no, the user password changes occur on theconnection used to authenticate the user.

Such behavior increases the duration of the connection and might cause thenumber of simultaneous instances to increase. If the increase in simultaneousconnections is not acceptable, use the max-auth-connections option to limit thenumber of simultaneous connections. For detailed information about themax-auth-connections option, see the max-auth-connections section.

Note: Only Tivoli Directory Server supports enabling of the auth-using-compareoption. For other LDAP servers, Tivoli Access Manager considers this optiondisabled.

Tivoli Access Manager WebSEAL 6.1.1 takes advantage of enhanced-pwd-policy.

The password policies and account states supported by Tivoli Access Manager are:v Password resetv Locked accountsv Expired accountsv Grace login for expired accountsv Accounts whose passwords are going to expire

Optionsyes|true

When the enhanced-pwd-policy option is set to true, Tivoli AccessManager efficiently identifies the underlying LDAP registry passwordpolicy and reacts appropriately.

no|falseWhen the enhanced-pwd-policy option is set to false, the behavior ofTivoli Access Manager towards LDAP registry password policyenforcement remains unchanged.

Default valueThe default value of enhanced-pwd-policy is no|false

ExampleAn example of this feature is: LDAP reports that an account is expired and allowsgrace login. The user is informed that the account is expired, and is provided agrace login page and an option to change the password.

Using enhanced-pwd-policy with Tivoli Directory Server: If you enableenhanced-pwd-policy for the Tivoli Directory Server when using Tivoli DirectoryServer for the registry, you must:v Manually update the access control lists (ACL) of the server so that users can

change their passwords.


v Set auth-using-compare to no in each configuration file where you setenhanced-pwd-policy to yes.

Complete the following steps to update LDAP access control lists:v To ensure that users can change their passwords, suffixes that contain or will

contain Tivoli Access Manager user accounts must have an LDAP ACL thatpermits users to change their passwords.An example of the suffix that you create is o=ibm,c=us. An example of a suffixthat Tivoli Access Manager creates is secAuthority=Default. Each of thesesuffixes requires an LDAP ACL to let the users change their passwords.1. For the suffix that you created, create a file, for example, addacl1.ldif, that

contains the following:dn:o=ibm,c=uschangetype:modifyadd:aclEntryaclEntry:access-id:cn=this:at.userPassword:rwsc

2. Run the command:idsldapmodify -D "cn=root" -w "password"-h your.ldap.host.name -f "addacl1.ldif"

Behavior of Tivoli Access Manager policy server LDAP accounts and policies: ThepwdMustChange option in the LDAP policy prevents the policy server from startingduring configuration.

The account used for configuration does not exist before the configuration starts.So you cannot set a policy to override the global policy. To create Tivoli AccessManager LDAP server accounts, you might have to temporarily disable the globalpolicies before configuration.

After you configure the Tivoli Access Manager server LDAP accounts and thepolicy server, set a policy for each Tivoli Access Manager server LDAP account tooverrides any global policy that affects the use of the LDAP account.

max-auth-connections

Syntaxmax-auth-connections = {0|unlimited number of simultaneous connections used for userauthentication|any number higher than 0|actual number of simultaneousconnections used for user authentication}

DescriptionUse the max-auth-connections option to determine how many simultaneousconnections to your LDAP server are permitted for user authentication. This optionhas no effect if auth-using-compare is enabled. The benefit of themax-auth-connections option is greater if enhanced-pwd-policy is enabled. Seeenhanced-pwd-policy for details.

Options0|unlimited number of simultaneous connections used for userauthentication

When you set max-auth-connections to 0 (zero), you can use unlimitedLDAP server connections simultaneously to authenticate users.


any number higher than 0|actual number of simultaneous connections used foruser authentication

If you set max-auth-connections to a value greater than 0 (zero), thenumber of simultaneous connections used for user authentication is limitedto the number you specify.

Default valueBy default, max-auth-connections is set to 0 (zero.)

enable-last-login

Syntaxenable-last-login = {yes|true|no|false}

DescriptionFor LDAP-based registries, each Tivoli Access Manager server that provides a loginservice requires you to set the enable-last-login option to store the last login dateof a user in LDAP. Examples of such servers are:v WebSEAL.v Policy Server.v Authorization Server.v Local-mode authorization and Java Authorization applications that allow user

authentication directly to the registry.

Optionsyes|true

Set the value of the enable-last-login option to yes if you want last thelogin information of users to be recorded and displayed to users.

no|falseSet the value of the enable-last-login option to no if you do not want thelast login information of users to be recorded and displayed to users.

auth-using-compare

Syntaxauth-using-compare = {yes|true|no|false}

DescriptionChoice of whether ldap_compare() is used instead of the ldap_bind() call to verifythe password and authenticate the user. For those LDAP servers that allow it, acompare operation might perform faster than a bind operation. The value for eachserver can be different, depending on how that server is configured.

This option changes the method used by the following authorization API calls:v azn_util_client_authenticate()v azn_util_password_authenticate()

Optionsyes|true

A compare operation is used to authenticate LDAP users.

no|falseA bind operation is used to authenticate LDAP users.


Any value other than yes|true, including a blank value, is interpreted asno|false.

For information on how to use this key value pair for performance tuning, see theIBM Tivoli Access Manager for e-business: Performance Tuning Guide.

UsageOptional

Default valueThe default values are server-dependent.

Exampleauth-using-compare = yes

authn-timeout

Syntaxauthn-timeout = {0|number_seconds}

DescriptionAmount of time (in seconds) that is allowed for authentication operations beforethe LDAP server is considered to be down. If specified, this value overrides anyvalue set for the timeout entry for authentication operations.

Note: Do not specify this stanza entry in the ldap.conf server configuration file.

Options0 No timeout (synchronous).

number_secondsThe number of seconds allowed for authentication operations. Specify apositive whole number. There is no range limitation for timeout values.

UsageOptional

Default value0

Exampleauthn-timeout = 0

bind-dn

Syntaxbind-dn = LDAP_dn

DescriptionLDAP user distinguished name (DN) that is used when binding (signing on) to theLDAP server. The LDAP_dn value is created, based on the server name that wasspecified with the –n server_name option and the local host of the machine.

Use the svrsslcfg utility to set the LDAP_dn value.



OptionsLDAP_dn

Distinguished name that is used to bind to the LDAP server

UsageConditional. This stanza entry is required when using an LDAP user registry.

Default valueThe default value is server-dependent.

ExampleThe following example sets the distinguished name for the policy server:bind-dn = cn=ivmgrd/master,cn=SecurityDaemons,secAuthority=Default

cache-enabled

Syntaxcache-enabled = {yes|true|no|false}

DescriptionIndication of whether LDAP client-side caching is used to improve performance forsimilar LDAP queries.

Optionsyes|true

Enables LDAP client-side caching.

no|falseDisables LDAP client-side caching. This value is the default value.Anything other than yes|true, including a blank value, is interpreted asno|false.


UsageOptional

Default valueno

Examplecache-enabled = no

cache-group-expire-time

Syntaxcache-group-expire-time = number_seconds

DescriptionAmount of time (in seconds) until a group entry in the cache is considered staleand is discarded. This stanza entry is ignored if the cache is not enabled.


Optionsnumber_seconds

The amount of time specified in seconds. Specify a positive whole number.

UsageOptional

Default value300 (5 minutes)

Examplecache-group-expire-time = 600

cache-group-membership

Syntaxcache-group-membership = {yes|true|no|false}

DescriptionIndication of whether group membership information is cached. This stanza entryis ignored if the cache is not enabled.

Optionsyes|true

Group membership is cached.

no|falseGroup membership is not cached. Anything other than yes|true, includinga blank value, is interpreted as no|false.

UsageOptional

Default valueyes|true

Examplecache-group-membership = no

cache-group-size

Syntaxcache-group-size = group_entries

DescriptionNumber of entries in the LDAP group cache. This stanza entry is ignored if thecache is not enabled.

Optionsgroup_entries

A positive whole number that represents the number of entries is theLDAP group cache.

UsageOptional


Default value64

Examplecache-group-size = 100

cache-policy-expire-time

Syntaxcache-policy-expire-time = number_seconds

DescriptionAmount of time in seconds until a policy entry in the cache is considered stale andis discarded. This stanza entry is ignored if the cache is not enabled.


The amount of time specified in number of seconds. Specify a positivewhole number.

UsageOptional

Default value30

Examplecache-policy-expire-time = 60

cache-policy-size

Syntaxcache-policy-size = policy_entries

DescriptionNumber of entries in the LDAP policy cache. This stanza entry is ignored if thecache is not enabled.

Optionspolicy_entries

A positive whole number that represents the number of entries is theLDAP policy cache.

UsageOptional

Default value20

Examplecache-policy-size = 50


cache-return-registry-id

Syntaxcache-return-registry-id = {yes|no}

DescriptionIndicates whether the LDAP cache returns the TAM user identity as it is stored inthe registry or the value entered by the user.

Note: Refer to Appendix A, “Guidelines for changing configuring files,” on page199 for guidelines on changing configuration file properties.

Optionsyes Return the TAM user identity as it is stored in the registry. This option

returns the user identity exactly as it was created and preserved in theregistry.

no Return the TAM user identity as the value is entered by the user.

UsageOptional

Default valueno

Examplecache-return-registry-id = no

cache-use-user-cache

Syntaxcache-use-user-cache = {yes|true|no|false}

DescriptionIndication of whether to use the user cache information. This stanza entry isignored if the cache is not enabled.

Optionsyes|true

Use user information from the cache.

no|falseDo not use user information from the cache. Anything other than yes|true,including a blank value, is interpreted as no|false.

UsageOptional

Default valueyes|true

Examplecache-use-user-cache = no


cache-user-expire-time

Syntaxcache-user-expire-time = number_seconds

DescriptionAmount of time in seconds until a user entry in the cache is considered stale andis discarded. This stanza entry is ignored if the cache is not enabled.


The amount of time specified in number of seconds. Use a number that isa positive whole number.

UsageOptional

Default value30

Examplecache-user-expire-time = 120

cache-user-size

Syntaxcache-user-size = user_entries

DescriptionNumber of entries in the LDAP user cache. This stanza entry is Ignored if thecache is not enabled.

Optionsuser_entries

A positive whole number that represents the number of entries is theLDAP user cache.

UsageOptional

Default value256

Examplecache-user-size = 1000

default-policy-override-support

Syntaxdefault-policy-override-support = {yes|true|no|false}

DescriptionIndication of whether user-level policy support is allowed.


Optionsyes|true

User policy support is disabled, and only the global (default) policy ischecked. This option allows the user policy to not be checked, even if it isspecified.

no|falseUser policy support is enabled. When a user policy is specified by theadministrator, it overrides the global policy. If no value is specified,default-policy-override-support = no becomes the value.


UsageOptional

Default valueno

Exampledefault-policy-override-support = yes

ldap-server-config

Syntaxldap-server-config = fully_qualified_path

DescriptionLocation of the ldap.conf configuration file.

Note: When the ldap-server-config entry is specified in the configuration file, thevalues for enabled, host, port, max-search-size, and replica are obtainedfrom the ldap.conf file. If any of these entries exist in the configuration file,their values are overridden by the values from the ldap.conf file.



UsageThis stanza entry is required for ivmgrd.conf.


Platform File name

Linux or UNIX /opt/PolicyDirector/etc/ldap.conf

Windows c:\program files\tivoli\policydirector\etc\ldap.conf


ExampleThe following example set the location of the LDAP server for a Linux or UNIXoperating system:ldap-server-config = /opt/PolicyDirector/etc/ldap.conf

login-failures-persistent

Syntaxlogin-failures-persistent = {yes|no}

DescriptionIndicates whether the tracking of login failures is persistent (maintained in theregistry) or done in the local process cache.

Optionsyes Tracking of failures is maintained in the registry.

no Tracking of failures is done in the local process cache.

UsageOptional

Default valueno

Examplelogin-failures-presistent = yes

max-search-size

Syntaxmax-search-size = [0|number_entries]

DescriptionLimit for the maximum search size, specified as the number of entries, that can bereturned from the LDAP server. The value for each server can be different,depending on how the server was configured.

Options0 The number is unlimited. There is no limit to the maximum search size.

number_entriesThe maximum number of entries for search, specified as an integer wholenumber. This value can also be limited by the LDAP server itself.

UsageOptional

Default valueThe default value is server-dependent, but defaults to 2048 if not configured.

Examplemax-search-size = 2048


port

Syntaxport = port

DescriptionNon-SSL IP port number that is used for communicating with the LDAP server.

Optionsport The port number configured for the LDAP server.

UsageRequired for the policy proxy server and authorization server; not required for thepolicy server.

Default value389

Exampleport = 389

prefer-readwrite-server

Syntaxprefer-readwrite-server = {yes|true|no|false}

DescriptionIndication of whether the client can question the Read/Write LDAP server beforequerying any replica Read-only servers that are configured in the domain.

The default value can be different. For example, the default value for ivmgrd.confis yes while the default value for ivacld.conf is no.

Optionsyes|true

Enables the client to be able to question the Read/Write LDAP server.

no|falseDisables the client. Anything other than yes|true, including a blank value,is interpreted as no|false.

UsageOptional

Default valueThere is no default value. The default value is server dependent.

Exampleprefer-readwrite-server = no

search-timeout

Syntaxsearch-timeout = {0|number_seconds}


DescriptionAmount of time in seconds that is allowed for search operations before the LDAPserver is considered to be down. If specified, this value overrides any value that isset for the timeout entry for search operations.

Note: Do not specify this stanza entry in the ldap.conf server configuration file.

Options0 No timeout (synchronous).

number_secondsThe number of seconds allowed for search operations. Specify a positivewhole number. There is no range limitation for timeout values.

UsageOptional

Default value0

Examplesearch-timeout = 0

ssl-enabled

Syntaxssl-enabled = {yes|true|no|false}

DescriptionIndication of whether the Tivoli Access Manager server uses SSL to communicatewith the LDAP server. The value for each Tivoli Access Manager server can bedifferent, depending on how that server was configured. If this value is set to yesand Federal Information Processing Standards (FIPS) mode is enabled(ssl-enable-fips=yes), LDAP is told to use whatever secure communicationprotocol it chooses for FIPS enablement.

If you specify that the authorization API (aznAPI) should use SSL to communicatewith the LDAP server, you must enable SSL using this stanza entry.

If you enable SSL communication, you must specify an SSL key file name and, ifthere are multiple keys in the file, the key file DN.

Optionsyes|true

Enables SSL communication.

no|falseDisables SSL communication. Anything other than yes or true, including ablank value, is interpreted as no or false.

UsageRequired to enable SSL communication. When ssl-enabled = yes, the LdapSSLentry in the ldap.conf file must be set to useSSL.

Default valueThere is no default value. The default values are server-dependent.


Examplessl-enabled = yes

ssl-keyfile

Syntaxssl-keyfile = ldap-ssl-key-filename

DescriptionSSL key file name and location. Use the SSL key file to handle certificates that areused in LDAP communication. The file extension can be anything, but theextension is usually .kdb.

The certificate files in a directory need to be accessible to the server user (or allusers). Make sure that server user (for example, ivmgr) or all users have permissionto access the .kdb file and the folder that contains the .kdb file.

Optionsldap-ssl-key-filename

A valid file name is an alphanumeric string that is not case-sensitive. Stringvalues are expected to be characters that are part of the local code set. ForWindows operating systems, file names cannot have a backward slash (\),a colon (:), a question mark (?), or double quotation marks. For Linux andUNIX operating systems, path names and file names are case-sensitive.

UsageConditional. This stanza entry is required only when the LDAP server isconfigured to perform client authentication (ssl-enabled = yes).


Platform File name

Linux or UNIX /opt/PolicyDirector/keytab/server_name.kdb

Windows c:\program files\tivoli\policy director\keytab\server_name.kdb

ExampleThe following example sets the SSL key file for a UNIX policy server:ssl-keyfile = /ldap52kdb/a17jsun.kdb

ssl-keyfile-dn

Syntaxssl-keyfile-dn = ldap-ssl-keyfile-label

DescriptionKey label of the client certificate within the SSL key file.

Optionsldap-ssl-keyfile-label

Identifies the client certificate that is presented to the LDAP server.


UsageConditional. This stanza entry is required only when the LDAP server isconfigured to perform client authentication.

Default valueIf the default policy server key database is being used, the default client certificatevalue is PDLDAP.

Examplessl-keyfile-dn = "PDLDAP"

ssl-keyfile-pwd

Syntaxssl-keyfile-pwd = ldap-ssl-keyfile-password

DescriptionDeprecated: The ssl-keyfile-pwd entry is deprecated in the [ldap] stanza.Although this entry might exist in a configuration file, it will be ignored.

user-and-group-in-same-suffix

Syntaxuser-and-group-in-same-suffix = {yes|true|no|false}

DescriptionIndication of whether the groups, in which a user is a member, are defined in thesame LDAP suffix as the user definition.

When a user is authenticated, the groups in which the user is a member must bedetermined in order to build a credential. Normally, all LDAP suffixes are searchedto locate the groups of which the user is a member.

Optionsyes|true

The groups that are assumed to be defined in the same LDAP suffix as theuser definition. Only that suffix is searched for group membership. Thisbehavior can improve the performance of group lookup, because only asingle suffix is searched. Use this option only if group definitions arerestricted to the same suffix as user definitions.

no|falseThe groups might be defined in any LDAP suffix. Anything other thanyes|true, including a blank value, is interpreted as no|false.

For information on how to use this key value pair for performance tuningpurposes, see the IBM Tivoli Access Manager for e-business: Performance Tuning Guide.

UsageOptional

Default valueno

Exampleuser-and-group-in-same-suffix = yes


[ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for theLDAP server. For example, you can find the configuration keys and values forLDAP failover, including the use of master server and replica servers, in thisstanza.

The user registry type value is determined by the pd.conf file. The pd.conf file iscreated when the Tivoli Access Manager runtime is configured.

For information on how to use the key value pairs in this stanza for performancetuning, see the IBM Tivoli Access Manager for e-business: Performance Tuning Guide.

cache-enabled

Syntaxcache-enabled = {yes|true|no|false}

DescriptionIndication of whether LDAP client-side caching is used to improve performance forsimilar LDAP queries.

Optionsyes|true

Enables LDAP client-side caching.

no|falseDisables LDAP client-side caching. This value is the default value.Anything other than yes|true, including a blank value, is interpreted asno|false.

For information on how to use this key value pair for performance tuningpurposes, see the IBM Tivoli Access Manager for e-business: Performance Tuning Guide.

UsageOptional

Default valueno

Examplecache-enabled = no

connection-inactivity

Syntaxconnection-inactivity = number_seconds

DescriptionSpecifies the number of seconds of inactivity allowed on a given LDAP connectionbefore the connection is taken down.

This parameter is not available using the pdconfig utility. The parameter must bemodified manually using the pdadmin command line (local login). For moreinformation, refer to "pdadmin commands" in the IBM Tivoli Access Manager fore-business: Command Reference.



The number of seconds of inactivity allowed on a given LDAP connection.The valid range for this parameter is 0 to 31536000. A connection-inactivityvalue of 0 indicates that connection inactivity is not tracked and theconnections, once established, are left connected permanently.

UsageOptional

Default valueIf this parameter is not specified, the default value is 0.

Exampleconnection-inactivity = 0

dynamic-groups-enabled

Syntaxdynamic-groups-enabled = {yes|true|no|false}

DescriptionIndication of whether dynamic groups are supported. This key value pair appliesto supported LDAP registries. Tivoli Access Manager supports dynamic groupswith IBM Tivoli Directory Server regardless of this setting.

Note: This stanza entry can be used only in the ldap.conf configuration file.

Optionsyes|true

Tivoli Access Manager attempts to resolve dynamic group membership.

no|falseTivoli Access Manager does not attempt to resolve dynamic groupmembership. Anything other than yes|true, including a blank value, isinterpreted as no|false.

UsageOptional

Default valueno

Exampledynamic-groups-enabled = no

enabled

Syntaxenabled = {yes|true|no|false}

DescriptionIndication of whether LDAP is being used as the user registry. Only one userregistry can be specified at a time.


If enabled, other required stanza entries are an LDAP server host name, and portwith which to bind to the server, a bind user DN, and bind user password(obfuscated).

Optionsyes|true

Enables LDAP user registry support.

no|falseDisables LDAP user registry support and indicates that LDAP is not theuser registry being used. Anything other than yes or true, including ablank value, is interpreted as no or false.

UsageConditional. This stanza entry is required when LDAP is the user registry.

Default valueThe default value can be different, depending on how the server is configured.

Exampleenabled = yes

host

Syntaxhost = host_name

DescriptionHost name of the LDAP server. Valid values for host_name include any validInternet Protocol (IP) host name.

When LDAP is the configured user registry, use the svrsslcfg utility to set thehost_name value. The host that is specified by this entry is assumed to be areadwrite type of server with a preference of 5. For a general description of servertypes and preferences, see “replica” on page 283.

Optionshost_name

The value is taken from the pd.conf file. The pd.conf file is created whenthe Tivoli Access Manager runtime is configured.

UsageRequired

Default valueThere is no default value. The value is taken from the pd.conf file.

Examplehost = librahost = libra.dallas.ibm.com

ignore-suffix

Syntaxignore-suffix = suffix_dn


DescriptionLDAP server suffix that is to be ignored when searching for user and groupinformation. By default, all defined suffixes in the LDAP server are searched whenacquiring User and group information.

Note: This stanza entry can be used only in the ldap.conf configuration file.

Optionssuffix_dn

Specifies the suffix distinguished name (DN) that you want to be ignored.Repeat this stanza entry for each suffix you want to be ignored. Forexample, if you specify ignore-suffix = o=tivoli,c=us, any user or groupthat includes o=tivoli,c=us as part of the DN is ignored.

UsageOptional

Default valueAll defined suffixes are searched.

Exampleignore-suffix = o=tivoli,c=us

max-search-size

Syntaxmax-search-size = [0|number_entries]

DescriptionLimit for the maximum search size, specified as the number of entries, that can bereturned from the LDAP server. The value for each server can be different,depending on how the server was configured.

Options0 The number is unlimited. There is no limit to the maximum search size.

number_entriesThe maximum number of entries for search, specified as an integer wholenumber. This value can be limited by the LDAP server itself.

UsageOptional

Default valueThe default value is server-dependent, but it defaults to 2048 if it is not configured.

Examplemax-search-size = 2048

max-server-connections

Syntaxmax-server-connections = number_connections


DescriptionIndicates the maximum number of connections that are allowed with the LDAPserver. The Tivoli Access Manager runtime maintains a pool of connections foreach LDAP server. From this pool, an available connection is chosen to performrequests to the LDAP server. If all connections are busy, a new connection isestablished with the LDAP server, up to the maximum server connection pool size.

This parameter is not available using the pdconfig utility. The parameter must bemodified manually using the pdadmin command line (local login). For moreinformation, refer to "pdadmin commands" in the IBM Tivoli Access Manager fore-business: Command Reference.

Optionsnumber_connections

The maximum number of connections allowed with the LDAP server. Thevalid range for this parameter is 2-16. Values greater than 16 are set to 16.

UsageOptional

Default valueIf this parameter is not specified, the default pool size is 16.

Examplemax-server-connections = 16

novell-suffix-search-enabled

Syntaxnovell-suffix-search-enabled = {yes|true|no|false}

DescriptionWhen the Novell eDirectory LDAP server is used as the user registry, AccessManager uses this option to determine whether to search the entire directorynamespace for user, group, and policy information using a baseless (global root)search or to automatically determine the set of naming contexts hosted by theLDAP server and search each defined naming context individually for user, group,and policy information.

Optionsyes|true

Access Manager performs naming context (suffix/partition) discovery andsearches each naming context for user, group, and policy information. Theoptional ignore-suffix parameter(s) will be honored.

no|falseAccess Manager performs a baseless (global root) search of the entirenamespace for user, group, and policy information. The optionalignore-suffix parameter(s) will be ignored.

UsageOptional; this stanza entry can be used only in the ldap.conf configuration file.

Default valueno


Examplenovell-suffix-search-enabled = no

port

Syntaxport = port

DescriptionNon-SSL IP port number that is used for communicating with the LDAP server.

Optionsport The value configured for the LDAP server.

UsageRequired

Default value389

Exampleport = 389

replica

Syntaxreplica = ldap-server, port, type, pref

DescriptionDefinition of the LDAP user registry replicas in the domain.

Optionsldap-server

The network name of the server.

port The port number for the LDAP server. A valid port number is any positivenumber that is allowed by TCP/IP and that is not currently being used byanother application.

type Either readonly or readwrite.

pref A number between 1 and 10, where 10 is the highest preference. The serverwith the highest preference is chosen for LDAP operations. If multipleservers have the same preference value, then load balancing occurs amongthe least busy of the servers.

UsageOptional

Default valueNo replicas are specified.

ExampleThe following example shows one replica that is specified and two replicas that arecommented out:


replica = freddy,390,readonly,1#replica = barney,391,readwrite,2#replica = benny,392,readwrite,3

secauthority-suffix

Syntaxsecauthority-suffix = suffix

DescriptionProvides a suffix under which the secAuthorityInfo object is located; this parameterserves as a starting search location for the secAuthorityInfo object when TivoliAccess Manager is started. If this parameter is set, the specified suffix will besearched first to locate the secAuthorityInfo object for the domain. If thisparameter is not set, or if the secAuthorityInfo object is not located within thesuffix specified by the parameter, then the entire set of suffixes will be searched.

Optionssuffix Suffix under which the secAuthorityInfo object is located.

UsageOptional.

This parameter must be set manually using the pdadmin utility, as in the followingexample:>pdadmin login -l>pdadmin local>config modify keyvalue set"c:\Progra~1\Tivoli\Policy Director\etc\ldap.conf"ldap secauthority-suffix "c=US"

Default valueNo suffixes are specified.

Examplesecauthority-suffix = c=US

ssl-port

Syntaxssl-port = port

DescriptionSSL IP port that is used to connect to the LDAP server.

Optionsport Any valid port number. A valid port number is any positive number that is

allowed by TCP/IP and that is not currently being used by anotherapplication.

UsageConditional. This stanza entry is required when the LDAP server is configured toperform client authentication (ssl-enabled = yes).

Default value636


Examplessl-port = 636

[manager] stanzaThe stanza entries for configuring the master server settings are located in the[manager] stanza of each of the following configuration files:v The ivacld.conf configuration file for the authorization serverv The pd.conf configuration file when you use the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy server

management-domain

Syntaxmanagement-domain = {default|domain_name}

DescriptionName of the management domain. This value is created and set by one of thefollowing utilities:v For the pd.conf file, the value is set using the bassslcfg utility.v For other configuration files, the value is set using the svrsslcfg utility.

Note: The internal interface that Tivoli Access Manager uses to access the LDAPserver when "LDAP" is selected as registry type is called the IntraVerseRegistry API (IRA). Function call are required to accurately specify the targetdomain for requests. If the IRA cannot determine the target domain from theira_local_domain or ira_authority options, the IRA uses the value of themanagement-domain parameter in the pd.conf file. If the runtime has notbeen configured, or if the management-domain parameter is missing, then themanagement domain is assumed to be Default.

OptionsDefault

Specifies the Management domain. This value is the default value for allservers.

domain_nameSpecifies the user-specified domain. Use this value when you configureyour own name for the domain.

The domain_name value is an alphanumeric, case-sensitive string. Stringvalues are expected to be characters that are part of the local code set.

Valid characters for domain names for U.S. English are the letters a-Z, thenumbers 0-9, a period (.), an underscore (_), a plus sign (+), a hyphen (-),an "at" symbol (@), an ampersand (&), and an asterisk (*). You cannot use aspace in the domain name.

UsageRequired

Default valueDefault

Examplemanagement-domain = mymgmtdomain


master-host

Syntaxmaster-host = server_hostname

DescriptionHost name of the Tivoli Access Manager server. The following host names arevalid:v mycomputer.city.company.comv mycomputer

Optionsserver_hostname

Represents the valid name for the host.

UsageRequired


Examplemaster-host = ammaster

master-port

Syntaxmaster-port = port

DescriptionTCP port on which the server listens for requests. This value is created and set byone of the following utilities:v For the pd.conf file, the value is set using the bassslcfg utility.v For all other configuration files, the value is set using the svrsslcfg utility.

Optionsport Any valid port number. A valid port number is any positive number that is

allowed by TCP/IP and that is not currently being used by anotherapplication. Use the default port number value, or use a port over 1000that is currently not being used.

UsageRequired


Examplemaster-port = 7135


[meta-info] stanzaThe stanza entry for configuring Tivoli Access Manager version information islocated in the [meta-info] stanza of each of the following configuration files:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The pd.conf configuration file when you use the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy server

version

Syntaxversion = number

DescriptionVersion of Tivoli Access Manager in decimal format.

Note: This value is generated. Do not change it.

[pdconfig] stanzaThis stanza defines the configuration key value pairs that are required for theLDAP server. The entries in this stanza are for internal use only. Do not modify thevalues in this file. To properly configure these entries, use the pdconfig utility.

LdapSSL

SyntaxLdapSSL = {ssl|nossl}

DescriptionIndication of whether to enable SSL communication on the LDAP server. If theLDAP server is not SSL enabled, any Tivoli Access Manager server that is SSLenabled cannot communicate with the LDAP server.

Note: The entries in this stanza are for internal use only. Do not modify the valuesin this file. To properly configure these entries, use the pdconfig utility.

Optionsssl Enables SSL communication. SSL is automatically configured.

nossl Disables SSL communication. Anything other than ssl, including a blankvalue, is interpreted as nossl.

UsageOptional

Default valueThe default value is server dependent.

ExampleLdapSSL = nossl


LdapSSLKeyFile

SyntaxLdapSSLKeyFile = ldap-ssl-key-filename


The certificate files in a directory need to be accessible to the server user (or allusers). Make sure that the server user (for example, ivmgr) or all users havepermission to access the .kdb file and the folder that contains the .kdb file.


Optionsldap-ssl-key-filename

The file name and location that represents an alphanumeric string that isnot case-sensitive. String values are expected to be characters that are partof the local code set. The set of characters permitted in a file name can bedetermined by the file system and by the local code set. For Windowsoperating systems, file names cannot have a backward slash (\), a colon (:),a question mark (?), or double quotation marks ("). For Linux and UNIXoperating systems, path names and file names are case-sensitive.

UsageConditional. This stanza entry is required when LdapSSL = ssl.


Platform File name

Linux or UNIX /opt/PolicyDirector/keytab/ivmgrd.kdb

Windows c:\program files\tivoli\policy director\keytab\ivmgrd.kdb

ExampleLdapSSL = sslLdapSSLKeyFile = /opt/PolicyDirector/keytab/ivmgrd.kdb

LdapSSLKeyFileDn

SyntaxLdapSSLKeyFileDn = keyLabel

DescriptionKey label of the client certificate within the SSL key file. This stanza entry is usedwhen the LDAP server is configured to perform client authentication.



OptionskeyLabel

Identifies the client certificate that is presented to the LDAP server.



ExampleLdapSSL = sslLdapSSLKeyFileDn = "PD_LDAP"

LdapSSLKeyFilePwd

SyntaxLdapSSLKeyFilePwd = ldap-ssl-keyfile-password

DescriptionPassword to access the SSL key file.


Optionsldap-ssl-keyfile-password

The password that is associated with the SSL key file. The default SSL keyfile is key4ssl.



ExampleLdapSSL = sslLdapSSLKeyFilePwd = mysslpwd

[pdaudit-filter] stanzaThe stanza entry for Tivoli Access Manager auditing support is located in the[pdaudit-filter] stanza of the pdaudit.conf configuration file.

logcfg

Syntaxlogcfg = audit.azn:[log-agent][[param[=value]] ...]




Optionsaudit.azn:log-agent

Category of auditing event. Also indicates that the destination wherelog-agent is one of the following agents:v stdoutv stderrv filev pipev remote

param=valueAllowable parameters. The parameters vary, depending on the category,the destination of events, and the type of auditing you want to perform.

Refer to IBM Tivoli Access Manager for e-business: Troubleshooting Guide forinformation about the log agents and the configuration parameters.

UsageOptional

Default valueRemove the pound signs (#) at the beginning of the configuration file lines toenable authentication or authorization auditing (or both) for the application.

Examplelogcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log

[pdmgrproxyd] stanzaThe stanza entries for configuring the policy proxy server are located in thefollowing configuration file:v The pdmgrproxyd.conf configuration file for the policy proxy server

cache-database

Syntaxcache-database = {yes|no}

DescriptionIndication of whether in-memory caching of the policy database is enabled.

Optionsyes Enables in-memory caching of the policy database.

no Disables in-memory caching of the policy database.

UsageRequired

Default valueno

Examplecache-database = yes


log-file


DescriptionLocation and name of the log file. Messages are redirected from STDOUT andSTDERR and sent to the server log file as defined in the policy proxy serverrouting file (pdmgrproxyd_routing). The policy proxy server relies on the routingfile to determine the log file names and path.

At startup of the policy proxy server, a check is made to see if the routing fileexists. If it exists, the routing file is used and this stanza entry is ignored;otherwise, this stanza entry is used.



UsageRequired


Platform File name

Linux or UNIX /var/PolicyDirector/log/msg__pdmgrproxyd_utf8.log

Windows c:\prograrm files\tivoli\policy director\log\msg__pdmgrproxyd_utf8.log

During installation of Tivoli Access Manager, if you enabled Tivoli CommonDirectory to specify one common directory location for all your log files, thedefault installation directory is different.

ExampleThe following example shows a Windows operating system without TivoliCommon Directory:log-file = c:\pd\log\msg__pdmgrproxyd_utf8.log

The following example shows a Linux or UNIX operating system with TivoliCommon Directory:log-file = TCD_directory/HPD/logs/msg__pdmgrproxyd_utf8.log

The 3-character identifier used in the example is HPD, which specifies that the logfiles are for the Tivoli Access Manager common component.


pid-file





UsageRequired


Platform File name

Linux or UNIX /var/PolicyDirector/log/pdmgrproxyd.pid

Windows c:\program files\tivoli\policy director\log\pdmgrproxyd.pid

Examplepid-file = c:\pd\log\pdmgrproxyd.pid

tcp-req-port


DescriptionTCP port on which the server is listening for requests.

Options0 Disables the port number.

port Enables the port number. Use any valid port number. A valid port is anypositive number that is allowed by TCP/IP and that is not currently beingused by another application. Use the default port number value, or use aport number over 1000 that is currently not being used.

UsageRequired

Default value8138



unix-group


DescriptionThe Linux or UNIX group account for this server. The group name and user nameare different items, and both can have the same value. The user name is set as thegroup owner of the policy proxy server files. The validity of the group namespecified depends on the requirements of the specific Linux or UNIX operatingsystem.

Optionsgroup_name

Represents an alphabetic string for the group associated with the useraccount.

UsageConditional. This stanza entry is required when working with Linux or UNIXgroup accounts.

Default valueivmgr


unix-user


DescriptionThe Linux or UNIX user account for this server. The group name and user nameare different items, but both can have the same value. The user name is set as theuser owner of the proxy manager files. The validity of the user name specifieddepends on the requirements of the specific Linux or UNIX operating system.

Optionsuser_name

Represents an alphabetic string for the name associated with the useraccount.

UsageConditional. This stanza entry is required when working with Linux or UNIX useraccounts.

Default valueivmgr



[pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after eachsystem reboot. When the authorization server is installed, the authorization serverdaemon automatically starts after each system reboot.

The stanza entries for automating server startup when using any of the userregistries are located in the [pdrte] stanza of the following configuration file:v The pd.conf configuration file when you use the authorization server

When you use the Tivoli Access Manager authorization server, you must have thepd.conf configuration file.

boot-start-ivacld

Syntaxboot-start-ivacld = {yes|no}

DescriptionIndication of whether to start the authorization server at system boot.

Optionsyes Start the authorization server at system boot.

no Do not start the authorization server at system boot.

UsageConditional. This stanza entry is required for Linux and UNIX operating systemsonly.

Default valueno

Exampleboot-start-ivacld = yes

boot-start-ivmgrd

Syntaxboot-start-ivmgrd = {yes|no}

DescriptionIndication of whether to start the policy server at system boot.

Optionsyes Start the policy server at system boot.

no Do not start the policy server at system boot.


Default valueno


Exampleboot-start-ivmgrd = yes

boot-start-pdproxyd

Syntaxboot-start-pdproxyd = {yes|no}

DescriptionIndication of whether to start the policy proxy server at system boot.

Optionsyes Start the policy proxy server at system boot.

no Do not start the policy proxy server at system boot.


Default valueno

Exampleboot-start-pdproxyd = yes

configured

Syntaxconfigured = {yes|no}

DescriptionIndication of whether the Tivoli Access Manager runtime package was configured.

Note: This value is generated. Do not change it.

tivoli_common_dir

Syntaxtivoli_common_dir = fully_qualified_path

DescriptionFile name and location for message files and trace log files. Indicates whetherTivoli Common Directory is used.




UsageConditional. This stanza entry is required when you configure the IBM TivoliAccess Manager Runtime for Java environment for Tivoli Common Directory(TCD) logging.

Default valueRefer to IBM Tivoli Access Manager for e-business: Troubleshooting Guide for moreinformation about Tivoli Common Directory.

user-reg-host

Syntaxuser-reg-host = hostname

DescriptionUser registry host name.

Note: This value is generated during configuration. Do not change it.

user-reg-hostport

Syntaxuser-reg-hostport = port

DescriptionNon-SSL IP port number that is used for communicating with the user registryserver.


user-reg-server

Syntaxuser-reg-server = server_name

DescriptionUser registry server name.


user-reg-type

Syntaxuser-reg-type = {ldap|domino|active_directory}

DescriptionUser registry type.


[pdwpm] stanzaThe stanza entry for configuring Web Portal Manager information is located in the[pdwpm] stanza of the amconf.properties configuration file.


This configuration file is in the /classes subdirectory of one of the followingoperating system-specific directories:

For Linux and UNIX operating systemswebsphere_install_dir/WebSphere/AppServer/systemApps/isclite.ear/iscwpm.war/

For Windows operating systemswebsphere_install_dirProgram Files\IBM\WebSphere\AppServer\systemApps\isclite.ear\iscwpm.war\

where websphere_install_dir is the directory where WebSphere is installed.

The /images/en subdirectory under the iscwpm.war directory contains the defaultGIF files for English locales.

For changes to the amconf.properties file to take effect, restart the WebSphereserver.

For additional information about customizing Web Portal Manager, see“Customizing the Web Portal Manager interface” on page 28.

aclMembership

SyntaxaclMembership = {true|false}

DescriptionIndicates whether the ACL Management tab is shown for the User and Groupproperties page.

UsageRequired

Default valuetrue

authMethod

SyntaxauthMethod = {FORM|BASIC|SSO|TAI}

DescriptionSpecifies the authentication method.

OptionsFORM Use when FORM-based login is needed.

BASIC Use when basic authentication is needed.

SSO Use for single sign-on, when Web Portal Manager is junctioned behindWebSEAL or when WebSphere Application Server security is in use.

TAI Use when Web Portal Manager is junctioned behind WebSEAL andWebSphere Application Server security is in use

UsageRequired


Default valueFORM

ExampleauthMethod = BASIC

bannerFile

SyntaxbannerFile = file_name

DescriptionSpecifies which JSP or HTML file is loaded.

Optionsfile_name

The name of the JSP or HTML file to load. The JSP or HTML file must inone of the following directories:

For administration/pdadmin.war

For delegate administration/delegate.war

UsageRequired

Default valuetop_banner.jsp

ExamplebannerFile = top_banner.jsp

changePassword

SyntaxchangePassword = {true|false}

DescriptionIndication of whether the password-change pages are displayed so that users canchange their passwords with Web Portal Manager.

Passwords for Web Portal Manager must adhere to the password policies that is setby the administrator. By default, passwords must contain a minimum of eightcharacters (consisting of at least one number and four letters) and a maximum oftwo repeated characters.

Optionstrue Display pages that allow Web Portal Manager users to change their

passwords.

false Do not display pages that allow Web Portal Manager users to change theirpasswords.

UsageRequired


Default valuetrue

ExamplechangePassword = false

debug

Syntaxdebug = {true|false}

DescriptionDetermines whether the trace is permitted to be displayed to standard out (stdout)when an exception is thrown.

Optionstrue Allows the trace information to be displayed to standard output.

false Does not allow the trace information to be displayed to standard output.

UsageRequired

Default valuefalse

Exampledebug = true

infoBarGif

SyntaxinfoBarGif = file_name

DescriptionSpecifies which image is shown in the on the bottom right of the page.

Optionsfile_name

The name of the GIF file. The GIF file must in one of the followingdirectories under the /pdadmin.war directory for administration or/delegate.war directory for delegate administration:v /imagesv /images/locale

UsageRequired

Default valueinfobar_ibm.gif

ExampleinfoBarGif = infobar_ibm.gif


jrteHost

SyntaxjrteHost = hostname

DescriptionIndicates the host name of the system where the Tivoli Access Manager Runtimefor Java package is installed and configured.


This stanza entry requires the jrteProps stanza entry.

jrteProps

SyntaxjrteProps = fully_qualified_path

DescriptionIndicates the file name and location of the properties file that is used by the TivoliAccess Manager Runtime for Java environment. This stanza entry requires thejrteHost stanza entry.


loginGif

SyntaxloginGif = file_name

DescriptionSpecifies which image is shown on the login page.

Optionsfile_name


UsageRequired

Default valueaccessmanager.gif

ExampleloginGif = accessmanager.gif

splashGif

SyntaxsplashGif = file_name


DescriptionSpecifies which image is shown on the Welcome page, after the Login page

Optionsfile_name


UsageRequired

Default valueaccessmanager.gif

ExamplesplashGif = accessmanager.gif

wasEmbedded

SyntaxwasEmbedded = {true|false}

DescriptionIndicates whether only the User, Group, GSO, and Policy pages are displayed.

This stanza entry is for internal use only. Do not change it.

UsageRequired

Default valuefalse

[ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL)configuration settings for the Tivoli Access Manager servers. The stanza entries forconfiguring Tivoli Access Manager SSL settings are located in the [ssl-info]stanza of each of the following configuration files:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The pd.conf configuration file when you use the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy serverv Your resource managers' configuration file for configured SSL entries

The aznAPI.conf configuration file is provided with Tivoli Access Manager as asample file for creating your own resource manager configuration file.Developers of service plug-ins should provide the standard functions. Beforeimplementing service plug-ins, read and thoroughly understand the conceptsdiscussed in the IBM Tivoli Access Manager for e-business: Authorization C APIDeveloper Reference.


ssl-authn-type

Syntaxssl-authn-type = certificate

DescriptionType of authentication.

Note: This value is created and its value set during configuration for theauthentication server and the policy proxy server. This stanza entry is notused for the policy server.

Do not edit this stanza entry.

Default valuecertificate

ssl-auto-refresh

Syntaxssl-auto-refresh = {yes|no}

DescriptionIndication of whether automatic refresh of the SSL certificate and the key databasefile password occur.

This value is created and its value set using one of the following utilities:v For the ivmgrd.conf configuration file, it is set using the mgrsslcfg utility.v For the pd.conf configuration file, it is set using the bassslcfg utility.v For all other configuration files, it is set using the svrsslcfg utility.

Note: This value is set using a configuration utility. Do not edit this stanza entry.

Optionsyes Enables automatic certificate and password refresh.

no Disables automatic certificate and password refresh.

ssl-cert-life

Syntaxssl-cert-life = number_days

DescriptionValue for the lifetime in number of days of a certificate. Any issued or renewedcertificates must use this value.

For the ivmgrd.conf configuration file, set this value using the mgrsslcfg utility toa value between 1 and 7299. (The default is 1460, or four years.) The name andpath are fixed for this configuration file. Use this utility to modify this value afterinitial configuration.

To increase or decrease the value, change the value and restart the policy server.The new value is in effect only for certificates that are issued or that are renewed


from that point on. If both the certificate and the password to the key database filethat contains the certificate expire, the password must be refreshed first.

Notes:

1. Only the policy server uses this value.2. The password value is set using the mgrsslcfg utility.3. Do not edit this stanza entry.

ssl-enable-fips

Syntaxssl-enable-fips = {yes|no}

DescriptionDetermines whether Federal Information Process Standards (FIPS) mode isenabled. If enable, set to yes, Transport Layer Security (TLS) version 1 (TLSv1) isthe secure communication protocol used. If not enabled, set to no, SSL version 3(SSLv3) is the secure communication protocol used.

Optionsyes Indicates that TLSv1 is the secure communication protocol.

no Indicates that SSLv3 is the secure communication protocol.

UsageRequired

Default valueThere is no default value. This value is set by the configuration utility that isassociated with each server.

Examplessl-enable-fips = no

ssl-io-inactivity-timeout

Syntaxssl-io-inactivity-timeout = {0|number_seconds}

DescriptionDuration in seconds that an SSL connection waits for a response before timing out.For certain administration request, such as looking up members in a large userregistry group over an SSL connection, you might receive the HPDBA0219E errormessage when the timeout value is too small. To resolve this problem, increase thistimeout value in the pd.conf configuration file.

This timeout value is created, and the value is set using one of the followingutilities:v For the ivmgrd.conf configuration file, it is set using the mgrsslcfg utility.v For the pd.conf configuration file, it is set using the bassslcfg utility.v For all other configuration files, it is set using the svrsslcfg.

Note: The timeout value is set using the configuration utility. Do not edit thisstanza entry.


Options0 No timeout is allowed.

number_secondsSpecifies the number of seconds that an SSL connection waits for aresponse before timing out. There is no range limitation for this timeoutvalue.

UsageRequired

Default valueThere is no default value. This value is set by the configuration utility that isassociated with each server.

Examplessl-io-inactivity-timeout = 300

ssl-keyfile

Syntaxssl-keyfile = key-path

DescriptionFile name and location on the local system of the SSL key file. If the key-value pairdoes not exist in the configuration file, the application fails. The file extension canbe anything, but it is usually .kdb. By default, the key file is located in one of thefollowing operating system-specific directories:

Linux and UNIX operating systems/var/PolicyDirector/keytab

Windows operating systemsc:\program files\tivoli\policy director\keytab

The certificate files in a directory need to be accessible to the server user (or allusers). Make sure that server user (for example, ivmgr) or all users have permissionto access the .kdb file and the folder that contains the .kdb file.

This file is created, and the value is set using one of the following utilities:v For the ivmgrd.conf configuration file, it is set using the mgrsslcfg utility.v For the pd.conf configuration file, it is set using the bassslcfg utility.v For all other configuration files, it is set using the svrsslcfg utility.

Note: The file name, including extension, is generated and set by the configurationutility. Do not edit this stanza entry.

ssl-keyfile-label

Syntaxssl-keyfile-label = label

DescriptionLabel of key to use other than the default. Quotation marks surrounding the labelvalue are not permitted.


This label is created, and the value is set using one of the following utilities:v For the ivmgrd.conf configuration file, it is set using mgrsslcfg utilityv For the pd.conf configuration file, this entry does not apply.v For all other configuration files, it is set using the svrsslcfg utility.

Note: The label is set by the configuration utility. Do not edit this stanza entry.

ssl-keyfile-stash

Syntaxssl-keyfile-stash = stash-path

DescriptionFile name and location of the SSL password stash file that is used to protectprivate keys in the key file. The password might be stored encrypted in the stashfile.

The file extension can be anything, but it is usually .sth. By default, the key file islocated in one of the following operating system-specific directories:

Linux and UNIX operating systems/var/PolicyDirector/keytab

Windows operating systemsc:\program files\tivoli\policy director\keytab

This file is created, and the value is set using one of the following utilities:v For the ivmgrd.conf configuration file, it is set using the mgrsslcfg utility.v For the pd.conf configuration file, it is set using the bassslcfg utility.v For all other configuration files, it is set using the svrsslcfg utility. The path is

defined by the –d option, and the name is defined by the –n option.

Note: The file name, including extension, is generated and set by the configurationutility. Do not edit this stanza entry.

ssl-listening-port

Syntaxssl-listening-port = {0|port}

DescriptionTCP port to listen on for incoming requests.

Note: The policy server does not use this stanza entry.

Options0 Disables listening. The value is specified during configuration by using the

svrsslcfg utility.

Note: Do not change this parameter directly; the parameter should bemodified only by issuing the scrsslcfg -chgport command so thatthe policy server knows that the listening port has been changed.Otherwise, the resource manager cannot receive policy updatenotifications or pdadmin server task commands.


port Enables listening at the specified port number. The valid range for port isany positive number that is allowed by TCP/IP and is not currently beingused by another application.

There is no one default value, because the configuration programs for eachdaemon specify its own default value. For example, when configuring thepolicy proxy server, the user is prompted for a port, with 8139 as thedefault. This value is then used in the call to the SSL configuration utility.

UsageRequired, except for the policy server.

Default valueIf not specified during configuration, the default value is 0. Otherwise, the value isserver-dependent.

Examplessl-listening-port = 8139

ssl-local-domain

Syntaxssl-local-domain = {Default|domain_name}

DescriptionThe name of the local domain. The server runs on this domain. If this value is notin the configuration file, then operations that rely on its presence fail.

The domain name value is created during configuration, but you can change itusing one of the following utilities:v For the ivmgrd.conf configuration file, change it using the mgrsslcfg utility.v For the pd.conf configuration file, change it using the bassslcfg utility.v For all other configuration files, change it using the svrsslcfg utility.

Note: This value is set during configuration or set using the configuration utility.Do not edit this stanza entry.

ssl-maximum-worker-threads

Syntaxssl-maximum-worker-threads = number_threads

DescriptionNumber of threads that can be created by the server to handle incoming requests.

Optionsnumber_threads

Number of threads that can be specified. The valid range must be equal toor greater than 1. The maximum number varies, because it is dependent onavailable system resources.

UsageRequired



Examplessl-maximum-worker-threads = 50

ssl-pwd-life

Syntaxssl-pwd-life = number_days

DescriptionPassword lifetime for the key database file, specified in the number of days. Forautomatic password renewal, the value for the lifetime of a password is controlledby the number_days value when the server is started.

The number of days between 1 and 7299 is created, and the value is set using oneof the following utilities:v For the ivmgrd.conf configuration file, it is set using the mgrsslcfg utility.v For the pd.conf configuration file, it is set using the bassslcfg utility.v For all other configuration files, it is set using the svrsslcfg utility.

For manual password renewal, the value is dictated by the value supplied to thesvrsslcfg –chgpwd utility. This value is also written into the appropriateconfiguration file.

Notes:

1. If a certificate and the password to the key database file containing thatcertificate are both expired, the password must be refreshed first.

2. The password value is set using the configuration utility. Do not edit thisstanza entry.

ssl-v3-timeout

Syntaxssl-v3-timeout = number_seconds

DescriptionSession timeout in seconds for SSL v3 connections between clients and servers.This timeout value controls how often a full SSL handshake is completed betweenTivoli Access Manager clients and servers.

This timeout value is created, and the value is set using one of the followingutilities:v For the ivmgrd.conf configuration file, it is set using the mgrsslcfg utility.v For the pd.conf configuration file, it is set using the bassslcfg utility.v For all other configuration files, it is set using the svrsslcfg. The path is defined

by the –d option, and the name is defined by the –n option.

Notes:

1. Tivoli Access Manager components might not function with small timeoutvalues in some network environments.

2. The timeout value is set using the configuration utility. Do not edit this stanzaentry.


[ssl] stanza for ldap.confThe ldap.conf configuration file defines the SSL configuration settings for theLDAP server. The stanza entries for configuring SSL settings are located in the[ssl] stanza of the following configuration file:v The ldap.conf configuration file for the LDAP server

ssl-local-domain

Syntaxssl-local-domain = {Default|domain_name}

DescriptionThe name of the local domain. The server runs on this domain. If this value is notset in the configuration file, operations that rely on its presence fail.

Note: This value is created and set by using the svrsslcfg utility. Do not edit thisstanza entry.

[uraf-registry] stanzaA User Registry Adapter Framework (URAF) stanza is required when theconfigured registry type is not LDAP. The stanza entries for configuringURAF-based registry settings for the server are located in the [uraf-registry]stanza of the following configuration files:v The ivmgrd.conf configuration file for the policy serverv The ivacld.conf configuration file for the authorization serverv The pdmgrproxyd.conf configuration file for the policy proxy serverv Your resource managers' configuration file for configured registry types that are

not LDAPThe aznAPI.conf configuration file that is provided with Tivoli Access Manageris a sample file for creating configuration files for your own resource managers.Developers of service plug-ins should provide the standard functions. Beforeimplementing service plug-ins, read and thoroughly understand the conceptsdiscussed in the IBM Tivoli Access Manager for e-business: Authorization C APIDeveloper Reference.

You can set additional stanza entries in the [uraf-registry] stanza of theactivedir.conf, activedir_ldap.conf, or domino.conf configuration files. Theconfiguration file that is used depends on the type of URAF user registry that youconfigure.

Most information in this stanza is filled in during configuration, with the exceptionof the cache-related items that must be manually updated by the Tivoli AccessManager administrator. The cache-mode, cache-size, and cache-lifetime stanzaentries do not appear in ivmgrd.conf configuration file, because the policy serverobject should not be cached.

Note: Do not place the following stanza entries in the [uraf-registry] stanza ofthe activedir.conf, activedir_ldap.conf, or domino.conf configuration files:v uraf-registry-config

v bind-id


bind-id

Syntaxbind-id = server_id

DescriptionThe login identity of the server administrator or of the user that is used to bind(sign on) to the registry server. Only the server uses this ID.

If the ID belongs to a user rather than an administrator, the user must haveprivileges to update and modify data in the user registry. For an IBM LotusDomino user registry, a Lotus Notes ID file provides the bind ID equivalent.


cache-mode

Syntaxcache-mode = {enabled|disabled}

DescriptionMode for caching that represents the cache being either turned on or turned off.

Note: This stanza entry is not in the ivmgrd.conf configuration file, because youdo not want to cache the policy server object.

Optionsenabled

Turns the cache on. You would enable the cache mode to improve theperformance of repetitive Read actions on a specified object, such as: loginperformance that is done more than once a day. Performance for Writeactions would not be improved.

disabledTurns the cache off. You would disable the cache mode for better security.Caching opens a small window for users to go from server to server inorder to bypass the maximum number of failed login attempts.

UsageOptional, normally provided for all Tivoli Access Manager servers, except thepolicy server

Default valueenabled

Examplecache-mode = enabled

cache-lifetime

Syntaxcache-lifetime = number_seconds


DescriptionNumber of seconds that the objects are allowed to stay in the cache.

If cache-mode = enabled and this stanza entry is not used.

For performance tuning, the longer the time specified, the longer the repetitiveRead advantage is held. A smaller number of seconds negates the cache advantagefor user-initiated Reads.



The timeout specified in number of seconds between 1 and 86400.

UsageOptional

Default value30

Examplecache-lifetime = 63200

cache-size

Syntaxcache-size = {number_objects|object_type:cache_count_value;[...]}

DescriptionMaximum number of objects for a particular object type that can be in the cache atone time without hash table collisions. Or, if it is not numeric, the value is a list ofone or more object types and their cache counts.

If cache-mode = enabled and this stanza entry is not used, the default value forcache size is used.

Performance tuning depends on how much memory is dedicated to a cache orhow many objects you typically have repetitive read operations on (such as howmany users you have logging in a day). For example, a setting of 251 might not begood if you have 1000 users logging in and out several times a day. However, ifonly 200 of those users log in and out repetitively during the day, a setting of 251might work well.


Optionsnumber_objects

Maximum number of objects (as a prime number) for the cache countbetween 3 and a maximum number that is logical for the task and thatdoes not affect performance. Non-prime numbers are rounded up to thenext higher prime number. If the number fails, the default value is used.


object_type:cache_count_valueList of one or more object types and their cache counts.

UsageOptional

Default valueThe default value is server-specific.

ExampleThe following example sets the cache to a total of 251 object:cache-size = 251

The following example sets the cache to 251 objects for each of the user, group,resgroup, resource, and rescreds objects:cache-size = user:251;group:251;resgroup:251;resource:251;rescreds:251;

The following example sets the cache to 251 objects for each of the user and groupobjects. The other object types are not cached.cache-size = user:251;group:251;

uraf-registry-config

Syntaxuraf-registry-config = fully_qualified_path

DescriptionFile name and location of the URAF registry configuration file for Tivoli AccessManager.



UsageConditional. This stanza entry is required for URAF user registries only.

Default valueThe default value is server-specific. It is generated, but it can be changed. Thedefault URAF registry configuration files can be one of the following files:v domino.confv activedir.confv activedir_ldap.conf

ExampleThe following Windows example uses an IBM Domino server as the user registryfrom a Windows client:uraf-registry-config = c:\program files\tivoli\policy director\etc\

domino.conf


The following Windows example uses a Microsoft Active Directory server as a userregistry from Windows Active Directory Domain or from a client of an ActiveDirectory Domain.uraf-registry-config = c:\program files\tivoli\Policy Director\etc\

activedir.conf

The following Windows example uses a Microsoft Active Directory server as a userregistry from a Windows 2003 client:uraf-registry-config = c:\program files\tivoli\policy director\etc\

activedir_ldap.conf

The following example using an Microsoft Active Directory server as the userregistry from a UNIX client:uraf-registry-config = /opt/PolicyDirector/etc/activedir_ldap.conf

[uraf-registry] stanza for domino.confThe stanza entries for configuring an IBM Lotus Domino server as the URAF userregistry are located in the [uraf-registry] stanza of the following configurationfile:v The domino.conf configuration file to configure IBM Lotus Domino as the user

registry server

enabled

Syntaxenabled = {yes|no}

DescriptionIndication of whether Domino is being used as the user registry.

When set to yes, the configuration file must set the following entities:v server

v PDM

v NAB

Optionsyes Indicates that Domino is the user registry.

no Indicates that Domino is not the user registry. Anything other than yes,including a blank value, is interpreted as no.

UsageRequired

Default valueno


NAB

SyntaxNAB = nsf_filename


DescriptionIBM Lotus Domino Name and Address Book (NAB) database.

Optionsnsf_filename

The names.nsf file name conforms to the underlying operating system filenaming conventions of the Domino server. The database is set atconfiguration time and cannot be changed. The file name extension mustalways be .nsf.

UsageConditional. This stanza entry is required when enabled = yes.

Default valuenames.nsf

ExampleNAB = names.nsf

PDM

SyntaxPDM = nsf_filename

DescriptionTivoli Access Manager meta-data database.

Optionsnsf_filename

Represents a Domino database file name. The file name conforms to theunderlying operating system file naming conventions of the Dominoserver. The database is created on the Domino server during configurationand cannot be changed. The recommended file name extension is .nsf.


Default valuePDMdata.nsf

ExamplePDM = PDMdata.nsf

server

Syntaxserver = server_name

DescriptionName of the IBM Lotus Domino server.

Optionsserver_name


Represents an alphanumeric string that is not case-sensitive. String valuesare expected to be characters that are part of the local code set. Theminimum and maximum lengths of the name are imposed by theunderlying registry.



Exampleserver = grizzly/Austin/IBM

Where grizzly is the host name of the Domino server machine and the remainderof the name is the Domino domain name.

uraf-return-registry-id

Syntaxuraf-return-registry-id = {yes|no}

DescriptionIndicates whether the URAF registry returns the TAM user identity as it is storedin the registry or the value entered by the user.





UsageOptional

Default valueno

Exampleuraf-return-registry-id = no

[uraf-registry] stanza for activedir.confThe stanza entries for configuring a Microsoft Active Directory server as the URAFuser registry are located in the [uraf-registry] stanza of the followingconfiguration file:v activedir.conf to configure Microsoft Active Directory as the URAF user registry

dnforpd

Syntaxdnforpd = ad_dn


DescriptionDistinguished name that is used by Active Directory to store Tivoli AccessManager data.

Note: This stanza entry is set during configuration. Do not edit this entry.

domain

Syntaxdomain = root_domain_name

DescriptionActive Directory root (primary) domain.

Note: This name is domain-dependent, based on what you selected during theconfiguration of the Tivoli Access Manager runtime. Do not edit this entry.


Syntaxdynamic-groups-enabled = {yes|no}

DescriptionIndication of dynamic group support.

Note: Microsoft supports Active Directory dynamic groups only for WindowsServer 2003 and beyond. Do not change this value if Active Directory is notcapable of handling dynamic groups.

For information about setting up your environment to enable an ActiveDirectory registry to handle dynamic groups, consult the Microsoft Web site.

Optionsyes Tivoli Access Manager attempts to resolve dynamic group membership.

no Tivoli Access Manager does not attempt to resolve dynamic groupmembership.

UsageOptional

Default valueno

Exampledynamic-groups-enabled = yes

enabled


DescriptionIndication of whether Active Directory is being used as the user registry.


Optionsyes Indicates that Active Directory is the user registry.

no Indicates that Active Directory is not the user registry. Anything other thanyes, including a blank value, is interpreted as no.

UsageConditional. This stanza entry is required when your user registry is MicrosoftActive Directory.

Default valueno


hostname

Syntaxhostname = host_name

DescriptionActive Directory DNS host name.

Note: This value is automatically filled in during the configuration of the TivoliAccess Manager runtime. Do not edit this entry.

multi-domain

Syntaxmulti-domain = {true|admd|false}

DescriptionIndication of whether the domain is a single domain configuration or amulti-domain configuration. Selection is made during the configuration of theTivoli Access Manager runtime.

Note: This stanza entry is set during configuration. Do not edit it.






returns the user identity exactly as it was created and preserved in theregistry, which is case-sensitive.



UsageOptional

Default valueno


use-email-as-user-id

Syntaxuse-email-as-user-id = {yes|no}

DescriptionIndicates whether support is enabled for using an alternate format for theuserPrincipalName registry attribute. This support ensures that Tivoli AccessManager works with the Microsoft Active Directory registry when theuserPrincipalName attribute of the Active Directory user object is required to havea non-default value.

Note: To fully enable this support, this option must be enabled in all Tivoli AccessManager runtime configured environments.

Optionsyes Support is enabled for using an alternate format for the userPrincipalName

registry attribute.

no Support for an alternate format userPrincipalName is disabled.


Default valueno

Exampleuse-email-as-user-id = no

useEncryption

SyntaxuseEncryption = {true|false}

DescriptionIndication of whether encryption communication to Active Directory is being used.

Note: This value is specified during the configuration of the Tivoli Access Managerruntime. Do not edit this entry.


[uraf-registry] stanza for activedir_ldap.confWhen you use an LDAP client to retrieve data for the Active Directory userregistry that the Tivoli Access Manager server is configured to, you must have theactivedir_ldap.conf server configuration file. Use this configuration file tocustomize the operation of each Active Directory registry server.

The stanza entries for configuring the Microsoft Active Directory as the userregistry on a Tivoli Access Manager server are located in the [uraf-registry]stanza of the following configuration file:v activedir_ldap.conf

change-pwd-using-ldap-api

Syntaxchange-pwd-using-ldap-api = {yes|no}

DescriptionIndicates whether password change requests are performed using a direct LDAPconnection to the Active Directory server.

When this option is set to yes, the Policy Server does not need to be available toprocess the password change request.

Notes:

1. To implement this functionality across an enterprise system, this option must beenabled (set to yes) in every IBM Tivoli Access Manager run-time configuredenvironment in which change password requests are to be handled usingLDAP APIs rather than the Policy Server.

2. Before this option is enabled, Tivoli Access Manager must be configured forSecure Socket Layer (SSL) for a connection between the LDAP client and theActive Directory server. The Active Directory environment must also be able toaccept LDAP connections over SSL.

Optionsyes Indicates that password change requests are performed using a direct

LDAP connection to the Active Directory server; the Policy Server does notneed to be available.

no Indicates that password change requests are performed using the AccessManager Policy Server and are treated as password resets.


Default valueno

Examplechange-pwd-using-ldap-api = no

dnforpd

Syntaxdnforpd = ad_dn


DescriptionDistinguished name that is used by Active Directory to store Tivoli AccessManager data.

Note: This stanza entry value is set during configuration. Do not change it.

domain

Syntaxdomain = secondary_domain_name

DescriptionName of Active Directory secondary or child domain host name. This host name isin the same forest as the root domain, its host name, and zero or more replica hostnames. This name is domain-dependent, based on what you select during theconfiguration of the Tivoli Access Manager runtime.

For the Active Directory single domain configuration, either primary-domain= ordomain= can be used to enter the domain name information.

For the Active Directory multiple domain configuration, multiple domain nameentries are allowed.

Optionssecondary_domain_name

An alphanumeric, case-sensitive string. String values are expected to becharacters that are part of the local code set. The maximum length for thedomain name is user registry dependent. For Active Directory thatmaximum length is 256 alphanumeric characters.

Use the following format to specify a domain:domain = nnn|hhh[|rrr1[|rrr2[|...]]]

Where:

nnn The primary domain name. The name format can be eitherchild.ibm.com or dc=child,dc=ibm,dc=com.

hhh The primary domain host name or IP address.

rrr The primary domain replica host name or IP address.

Square brackets ([]) show entries that are optional and the required verticalbar (|) acts as a separator.

UsageConditional. This stanza entry is required when your user registry is MicrosoftActive Directory and when the multi-domain entry is set to true or admd.


Exampledomain = dc=child,dc=ibm,dc=com|adhost.child.ibm.com|adhostreplica.child.ibm.com



Syntaxdynamic-groups-enabled= {yes|no}

DescriptionIndication of dynamic group support.

Note: Before enabling dynamic group support on blade servers, you must firstenable dynamic group support on the policy server. Remember that whiledynamic group support must be enabled on the policy server, you candisable this option for a blade server. If disabled, the blade server cannotbenefit from dynamic group support.

Optionsyes Tivoli Access Manager attempts to resolve dynamic group membership.

no Tivoli Access Manager does not attempt to resolve dynamic groupmembership.

UsageOptional

Default valueno

Exampledynamic-groups-enabled = no

enabled


DescriptionIndication of whether Active Directory is being used as the user registry.

When set to yes, the following entries must be set:v ssl-keyfile

v ssl-keyfile-pwd

Optionsyes Indicates that Active Directory is the user registry.

no Indicates that Active Directory is not the user registry. Anything other thanyes, including a blank value, is interpreted as no.


Default valueno



ldap-client-timeout

Syntaxldap-client-timeout = {0|number_seconds}

DescriptionAmount of time that is allowed for to LDAP simple bind and LDAP searchesbefore the LDAP client is considered to be down.

Options0 Unlimited amount of time for synchronous operations only.

number_secondsAmount of time, in seconds, allowed for asynchronous operations. Thenumber of seconds is specified as a positive whole number. The suggestedrange is between 240 to 900.

UsageRequired

Default value0

Exampleldap-client-timeout = 520

max-connections-per-ad-domain

Syntaxmax-connections-per-ad-domain = {2-16}

DescriptionSpecifies the number of concurrent connections with each Microsoft ActiveDirectory domain.


Default value16

Examplemax-connections-per-ad-domain = 16

multi-domain

Syntaxmulti-domain = {true|admd|false}

DescriptionIndication of whether the domain is a single-domain configuration or amulti-domain configuration. Selection is during the configuration of the TivoliAccess Manager runtime.

Note: This stanza entry is set during configuration. Do not edit it.


primary-domain

Syntaxprimary-domain = primary_domain_name

DescriptionActive Directory primary domain host name, and zero or more replica host names.Only one primary domain entry is allowed. This name is domain-dependent, basedon what you select during the configuration of the Tivoli Access Manager runtime.

For the Active Directory multi-domain configuration, the primary domain entrymust contain the root domain information.

For the Active Directory single domain configuration, either the primary-domain =entry or the domain = entry can be used for the domain information.

Optionsprimary_domain_name

An alphanumeric, case-sensitive string. String values are expected to becharacters that are part of the local code set. The maximum length for thedomain name is user registry dependent. For Active Directory thatmaximum length is 256 alphanumeric characters.

Use the following format to specify a domain:primary-domain = nnn|hhh[|rrr1[|rrr2[|...]]]

Where:

nnn The primary domain name. The name format can be either ibm.comor dc=ibm,dc=com.

hhh The primary domain host name or IP address.

rrr The primary domain replica host name or IP address.

Square brackets ([]) show entries that are optional and the required verticalbar (|) acts as a separator.

UsageRequired


Exampleprimary-domain = dc=ibm,dc=com|adprim.ibm.com|adprimreplica1.ibm.com

ssl-keyfile

Syntaxssl-keyfile = ldap-ssl-key-filename



The certificate files in a directory need to be accessible to the server user (or allusers). Make sure that the server user (for example, ivmgr) or all users havepermission to access the .kdb file and the folder that contains the .kdb file.

The location and file name value represents an alphanumeric string that is notcase-sensitive. String values are expected to be characters that are part of the localcode set. The set of characters permitted in a file name can be determined by thefile system and by the local code set. For Windows operating systems, file namescannot have a backward slash (\), a colon (:), a question mark (?), or doublequotation marks ("). The maximum string length for the Active Directory userregistry is 256 alphanumeric characters. For Linux and UNIX operating systems,path names and file names are case-sensitive.

UsageConditional. This stanza entry is required when ssl-enabled = yes.


Platform File name

Linux or UNIX /opt/PolicyDirector/keytab/server_name.kdb

Windows c:\program files\tivoli\policy director\keytab\server_name.kdb

Examplessl-keyfile = /opt/PolicyDirector/keytab/ivmgrd.kdb

ssl-keyfile-label

Syntaxssl-keyfile-label = key_label

DescriptionSpecifies the key label that is used to identify the client certificate. that is presentedto the LDAP server. It is the key label of the client certificate within the SSL keyfile.

Optionskey_label

An alphanumeric string that is not case-sensitive. String values areexpected to be characters that are part of the local code set. The minimumand maximum lengths of the ID, if there are limits, are imposed by theunderlying registry. The key label must be enclosed in double quotationmarks.

UsageConditional. This stanza entry is required when the LDAP server is configured toperform client authentication.


Examplessl-keyfile-label = "PDLDAP"


ssl-keyfile-pwd

Syntaxssl-keyfile-pwd = ldap-ssl-keyfile-password

DescriptionPassword to access the SSL key file. The password associated with the default SSLkey file is key4ssl.



Examplessl-keyfile-pwd = key4ssl








UsageOptional

Default valueno


use-email-as-user-id

Syntaxuse-email-as-user-id = {yes|no}

DescriptionIndicates whether support is enabled for using an alternate format for theuserPrincipalName registry attribute. This support ensures that Tivoli Access


Manager works with the Microsoft Active Directory registry when theuserPrincipalName attribute of the Active Directory user object is required to havea non-default value.

Note: To fully enable this support, this option must be enabled in all Tivoli AccessManager runtime configured environments. If this property is enabledmanually using the pdadmin utility, the ad-gc-server entry must also bemodified to add the hostname(s) for the global catalog server.

Optionsyes Support is enabled for using an alternate format for the userPrincipalName

registry attribute.

no Support for an alternate format userPrincipalName is disabled.


Default valueno

Exampleenabled = no

ad-gc-server

Syntaxad-gc-server = gc_server_hostname

DescriptionSpecifies the Active Directory hostname for the Global Catalog server. This valuemust be set and in effect prior to enabling support for alternate UPNs. Thisproperty accepts multiple values.

Optionsgc_server_hostname

Active Directory hostname for the Global Catalog server.

UsageRequired when the use-email-as-user-id option is enabled (use-email-as-user-id= yes).

Default valuenone

Examplead-gc-server = gc-server1.tivoli.com

ad-gc-server = gc-server2.tivoli.com

ad-gc-port

Syntaxad-gc-port = {3268|3269}


DescriptionSpecifies the port number for the Active Directory Global Catalog on the GlobalCatalog server.

Note: This value is automatically set and should not be modified manually.

Options3268 Port number reserved by Microsoft Active Directory for Global Catalog in

a non-SSL environment.

3269 Port number reserved by Microsoft Active Directory for Global Catalog inan SSL environment.

UsageRequired when the use-email-as-user-id option is enabled (use-email-as-user-id= yes).

Default valuenone

UseSSL

SyntaxUseSSL = {yes|no}

DescriptionIndication of whether to use SSL.

Optionsyes Specifies that you want to use SSL.

no Specifies that you do not want to use SSL.

UsageRequired

Default valueyes

Exampleusessl = no

[xmladi-attribute-definitions] stanzaThe stanza entries for configuring the Access Decision Information ExtensibleMarkup Language (ADI XML) document attribute definitions are located in the[xmladi-attribute-definitions] stanza. This stanza can be found or placed intoany of the Tivoli Access Manager configuration files, except for the pd.confconfiguration file.

The aznAPI.conf configuration file is provided with Tivoli Access Manager as asample file for creating your own resource manager configuration file. Developersof service plug-ins should provide the standard functions. Before implementingservice plug-ins, read and thoroughly understand the concepts discussed in theIBM Tivoli Access Manager for e-business: Authorization C API Developer Reference.


AttributeName

SyntaxAttributeName = "AttributeValue"

DescriptionDefinition of ADI XML document attributes that are inserted into the XML ADIelement start tag to enable attributes to be defined for the entire XML ADIdocument and for all ADI defined in the XML ADI document.

The ADI XML model requires that the XML document contains the followingtop-level XML element into which all target ADI for a particular rule evaluation isinserted. The XMLADI element is created automatically as part of the ruleevaluation process<XMLADI></XMLADI>

UsageRequired

Examplexmlns:myNS = "http://myURI.mycompany.com"appID = ’"Jupiter" - Account Management Web Portal Server #1.’

The attribute value must be enclosed in either double or single quotation marks.

The following XMLADI element start tag defines these attributes:<XMLADI xmlns:myNS="http://myURI.mycompany.com"appID=’"Jupiter" - Account Management Web Portal Server #1.’>

For more information, see Chapter 10, “Authorization rules management,” on page119.

Appendix D. User registry differences

Each user registry presents unique concerns when integrated with Tivoli AccessManager. This release of Tivoli Access Manager supports LDAP and URAF userregistries.

Tivoli Access Manager supports the following LDAP user registries:v Tivoli Directory Serverv IBM z/OS Security Server LDAP Serverv Novell eDirectory Serverv Sun Java System Directory Serverv Sun ONE Directory Serverv Microsoft Active Directory Application Mode (ADAM)

Tivoli Access Manager supports the following URAF user registries:v Microsoft Active Directory Serverv Lotus Domino Server

General concernsThe following concerns are specific to all of the supported user registries:v Avoid using the forward slash (/) character when defining the names for users

and groups when that name is defined using distinguished names strings. Eachuser registry treats this character differently.

v Avoid using leading and trailing blanks in user and group names. Each userregistry treats blanks differently.

LDAP concernsThe following concerns are specific to all of the supported LDAP user registries:v There are no configuration steps needed in Tivoli Access Manager to make it

support LDAP's own Password Policy. Tivoli Access Manager does not assumethe existence or non-existence of LDAP's own Password Policy at all.Tivoli Access Manager enforces its own Password Policy first and foremost.Tivoli Access Manager will attempt to update password in LDAP only when theprovided password passes Tivoli Access Manager's own Password Policy check.After that Tivoli Access Manager tries to accommodate LDAP's own PasswordPolicy to the best of its ability using the return code that its get from LDAPduring a password related update.If Tivoli Access Manager can map this return code without any ambiguity withthe corresponding Tivoli Access Manager error code, it will do so and willreturn a proper error message.

v To take advantage of the multi-domain support in Tivoli Access Manager, youmust use an LDAP user registry. When using a URAF user registry, only a singleTivoli Access Manager domain is supported.

v When using an LDAP user registry, the capability to own global sign-oncredentials must be explicitly granted to a user. After this capability is granted, it


can subsequently be removed. Conversely, users that are created in a URAF userregistry are automatically given this capability. This capability cannot beremoved.

v Leading and trailing blanks in user names and group names are ignored whenusing an LDAP user registry in a Tivoli Access Manager secure domain. Toensure consistent processing regardless of the user registry, define user namesand group names without leading or trailing blanks.

v Attempting to add a single duplicate user to a group does not produce an errorwhen using an LDAP user registry.

v The Tivoli Access Manager authorization API provides a credentials attributeentitlements service. This service is used to retrieve user attributes from a userregistry. When this service is used with an LDAP user registry, the retrievedattributes can be string data or binary data. However, when used with a URAFuser registry, the retrieved attributes can be string data, binary data, or integerdata.

Sun Java System Directory Server concernsThe following concerns are specific to Sun Java System Directory Server:v If the user registry contains more entries than the defined look-through limit, the

directory server might return the following status that Tivoli Access Managertreats as an error:LDAP_ADMINLIMIT_EXCEEDED

When the directory server is installed, the default value is 5000. To modify thisvalue, perform the following steps from the Sun Java System Directory ServerConsole:1. Select the Configuration tab.2. Expand the Data entry.3. Select Database Settings.4. Select the LDBM Plug-in Settings tab.5. In the Look-through Limit field, type the maximum number of entries that

you want the server to check in response to the search, or type -1 to defineno maximum limit.

If you bind the directory as the Directory Manager, the look-through limit isunlimited and overrides any settings specified in this field.

Microsoft Active Directory Application Mode (ADAM) concernsThe following concerns are specific to ADAM.v Policy Server configuration allows you to select between a standard or minimal

data model for the user registry. Because ADAM allows only a single namingattribute to be used when creating LDAP objects, ADAM requires the minimaldata model. Regardless of which data model is chosen during Policy Serverconfiguration, Access Manager always uses the minimal data model whenADAM is selected as the user registry.

v The common name (cn) attribute is a single-value attribute and can store onlyone value. The ADAM registry requires the value of cn to be the same as the cnnaming attribute in the distinguished name (dn) attribute. When creating a useror group in Tivoli Access Manager, specify the same value for cn as the cnnaming attribute in the dn. Tivoli Access Manager ignores the value of the cnattribute if it is different from the value of the cn naming attribute in the dn. For


example, you cannot use the following command to create a user because thevalue of the cn attribute, fred, is different from the cn naming attribute in thedn, user1:pdadmin user create user1 cn=user1,o=ibm,c=us fred smith password1

URAF concernsThe following concerns are specific to the supported URAF user registries:v When using a URAF user registry, only one Tivoli Access Manager domain is

supported. To take advantage of the Tivoli Access Manager multidomainsupport, use an LDAP user registry.

v Users created in a URAF user registry are automatically given the capability toown global sign-on credentials. This capability cannot be removed. When usingan LDAP user registry, this capability must be explicitly granted. After thiscapability is granted, it can subsequently be removed.

v The Tivoli Access Manager authorization API provides a credentials attributeentitlements service. This service is used to retrieve user attributes from a userregistry. When this service is used with a URAF user registry, the retrievedattributes can be string data, binary data, or integer data. However, when usedwith an LDAP user registry, the retrieved attributes can be only string data orbinary data.

Lotus Domino Server concernsIn addition to the general URAF-specific concerns, the following concerns arespecific to Lotus Domino Server:v Leading and trailing blanks in user names and group names are significant

when using Lotus Domino Server as the user registry in a Tivoli Access Managersecure domain. To ensure consistent processing, regardless of the user registry,define user names and group names without leading or trailing blanks.

v When creating names for users or groups and that name is defined with adistinguished name string that contains a forward slash (/) character, you mustdefine that name using distinguished name designations. For example, to createa user with the distinguished name string username/locinfo, use the followingcommand:pdadmin user create myuser cn=username/o=locinfo test test testpwd

v When the following conditions occur, the lastLogin value reported by thepdadmin user show command might not reflect the actual last login time of theuser:– URAF cache is enabled on a Tivoli Access Manager blade server such as

WebSEAL.– The provide-last-login property is set in the Policy Server configuration file

to show the last login time stamp,

The pdadmin command queries information directly from the registry while theblade server keeps the lastLogin value in cache until the cache expires and useractivity exists. The lastLogin value in blade server cache and the registry mightnot be synchronized. If the cache is disabled for a Tivoli Access Manager bladeserver, the pdadmin user show command shows the latest lastLogin value.

Microsoft Active Directory Server concernsIn addition to the general URAF-specific concerns, the following concerns arespecific to Microsoft Active Directory Server:

Appendix D. User registry differences 331

v For Microsoft Active Directory registry, Tivoli Access Manager uses the ActiveDirectory user attribute lastLogonTimestamp to report the last login time of theuser. This attribute is a system attribute and is updated automatically by ActiveDirectory. Tivoli Access Manager has no control over this attribute exceptreporting the value when required. This attribute is not updated every time auser logs in successfully. When a user logs in successfully, this attribute is onlyupdated if its current value is older than the current time minus the value of themsDS-LogonTimeSyncInterval attribute.

v For Microsoft Active Directory registry, Tivoli Access Manager uses the ActiveDirectory user attribute lastLogonTimestamp to report the last login time of theuser. This attribute is a system attribute and is updated automatically by ActiveDirectory. Tivoli Access Manager has no control over this attribute exceptreporting the value when required. This attribute is not updated every time auser logs in successfully. When a user logs in successfully, this attribute is onlyupdated if its current value is older than the current time minus the value of themsDS-LogonTimeSyncInterval attribute.

v Users created in Active Directory may have an associated primary group. TheActive Directory default primary group is Domain Users.But Active Directory does not add the primary group information to the user'smemberOf or the group's member attribute. This means that when Tivoli AccessManager queries for a list of members of a group, the result does not includeany members for whom the group is the primary group. Additionally, whenTivoli Access Manager queries for all the groups to which a user belongs, thequery result does not display the primary group of the user.For this reason, avoid using a Tivoli Access Manager group as the ActiveDirectory primary group for Tivoli Access Manager users.

v Tivoli Access Manager does not support cross domain group membership oruniversal groups. Tivoli Access Manager does not support importing these typesof groups.

v When Tivoli Access Manager imports a dynamic group, the ivacld-servers andremote-acl-users groups apply read permission on each authorization store towhich the dynamic group belongs. This read permission enables Tivoli AccessManager blade servers, such as WebSEAL, to have read permission to theregistry authorization store; thus, providing the blade server with the ability toread dynamic group data, such as group membership for building Tivoli AccessManager credentials. Manually removing this read permission while TivoliAccess Manager is configured to the Active Directory registry results in adversebehavior, such as inaccurate group membership.

v If the option to change a user's password using LDAP APIs is enabled in anenvironment where:

– Tivoli Access Manager is configured to use the Active Directoryuser registry

and

– Tivoli Access Manager blade servers use LDAP APIs to communicate withthe Active Directory server,

Tivoli Access Manager must be configured with Secure Socket Layer (SSL) toallow connections between the LDAP client and the Active Directory server. TheActive Directory environment must also be enabled to accept LDAP connectionsover Secure Socket Layer (SSL).


v When using an Active Directory user registry in a Tivoli Access Managerconfiguration with blade servers that use LDAP APIs to communicate with theActive Directory server, Access Manager supports user password changerequests using either the Policy Server or LDAP APIs. Change user passwordrequests using the LDAP APIs do not require the Policy Server to beup-and-running.The use of LDAP APIs to communicate with the Active Directory Server forblade servers is a multi-platform support that allows blade servers to beinstalled on machines that are not clients of the same domain as the policyserver. In this configuration, the policy server must be installed and configuredon a Windows operating system.

v When using an Active Directory user registry, each user name and each groupname in a domain must be unique. User and group short name values that arestored in the sAMAccountName attribute of Active Directory user objects andgroup objects. Active Directory user objects and group objects both have thesAMAccountName attribute as one of their attributes. Microsoft requires that thesAMAccountName attributes be unique within an Active Directory domain.

v When using a multi-domain Active Directory user registry, multiple users andgroups can be defined with the same short name as long as they are located indifferent domains. However, the full name of the user or group, including thedomain suffix, must always be specified to Tivoli Access Manager.

v Leading and trailing blanks in user names and group names are ignored whenusing Microsoft Active Directory Server as the user registry in a Tivoli AccessManager secure domain. To ensure consistent processing, regardless of the userregistry, define user names and group names without leading or trailing blanks.

v Tivoli Access Manager supports the use of an email address or other alternateformat of the userPrincipalName attribute of the Active Directory registry userobject as a Tivoli Access Manager user identity. This is an optional enhancement;when it is enabled, both the default and the email address or other alternateformat of the userPrincipalName can co-exist in the Tivoli Access Managerenvironment.The default format of the userPrincipalName registry attribute isuser_id@domain_suffix, where domain_suffix is the Active Directory domainwhere the user identity is created.For example, [email protected] is the value of the userPrincipalName;tivoli.com is the Active Directory domain where the user identity is created.The Tivoli Access Manager user identity corresponding to the registry user inthis example is either [email protected] or johndoe, depending on whetherTivoli Access Manager is configured to use Active Directory with multipledomains or a single domain, respectively.The alternate format of the userPrincipalName attribute is user_id@any_suffix,where any_suffix can be any domain (Active Directory or non-Active Directory)other than the Active Directory domain in which the user identity is created. Forexample, if the registry user johndoe@other_domain.com is created in ActiveDirectory tivoli.com, and the registry user [email protected] is created inActive Directory domain child_domain.tivoli.com. Both of these users can beTivoli Access Manager users, and their user identities arejohndoe@other_domain.com and [email protected], respectively.The alternate user principal name (UPN) support must be enabled in all TivoliAccess Manager run-time environments to ensure that Tivoli Access Manageruser identities work properly with alternate UPNs.


Once the use of alternate UPN format as Access Manager user identity isenabled, it cannot be reversed without breaking Tivoli Access Managerfunctionalities.

v Although users and groups can be created with names that use a distinguishedname string that contain a forward slash (/) character, subsequent operations onthe object might fail. Some Active Directory functions interpret the forward slashcharacter as a separator between the object name and the host name. To avoidthe problem, do not use a forward slash character to define the user.

Length of namesThe maximum lengths of various names that are associated with Tivoli AccessManager vary depending on the user registry that is being used. See Table 7 for acomparison of the maximum lengths that are allowed and the recommendedmaximum length to use to ensure compatibility with all the user registries that aresupported by Tivoli Access Manager.

Table 7. Maximum lengths for names by user registry and the optimal length across user registries

Name IBM TivoliDirectory

Server

IBM z/OSSecurityServer

NovelleDirectory

Server

Sun JavaSystem

DirectoryServer

MicrosoftActive

DirectoryServer

LotusDominoServer

ActiveDirectory

ApplicationMode

(ADAM)

Optimallength

First name(LDAP CN)

256 256 64 256 64 960 64 64

Middlename

128 128 128 128 64 65535 64 64

Last name(surname)

128 128 128 128 64 960 64 64

Registry UID(LDAP DN)

1024 1024 1024 1024 2048 255 1024 255

Tivoli AccessManageruser identity

256 256 256 256 64 196 -domain_

name_length

64 64

Userpassword

unlimited unlimited unlimited unlimited 256 unlimited 128 256

Userdescription

1024 1024 1024

Group name 256 256 256 256 64 196 -domain_

name_length

64 64

Groupdescription

1024 1024 1024

Singlesign-onresourcename

240 240 240 240 60 256 240 60

Singlesign-onresourcedescription

1024 1024 1024

Singlesign-on userID

240 240 240 240 60 256 240 60

Singlesign-onpassword

unlimited unlimited unlimited unlimited 256 unlimited unlimited 256


Table 7. Maximum lengths for names by user registry and the optimal length across user registries (continued)

Name IBM TivoliDirectory

Server

IBM z/OSSecurityServer

NovelleDirectory

Server

Sun JavaSystem

DirectoryServer

MicrosoftActive

DirectoryServer

LotusDominoServer

ActiveDirectory

ApplicationMode

(ADAM)

Optimallength

Singlesign-ongroup name

240 240 240 240 60 256 240 60

Singlesign-ongroupdescription

1024 1024 1024

Action name 1 1 1

Actiondescription,action type

unlimited unlimited unlimited

Object name,objectdescription


Object spacename, objectspacedescription


ACL name,ACLdescriptions


POP name,POPdescription


Although the maximum length of an Active Directory distinguished name (registryUID) is 2048, the maximum length of each relative distinguished name (RDN) is64.

If you configure Tivoli Access Manager to use multiple Active Directory domains,the maximum length of the user identity and group name does not include thedomain suffix. When using multiple domains, the format of a user identity isuser_id@domain_suffix. The maximum length of 64 applies only to the user_idportion. If you use an email address or other alternate format for the Tivoli AccessManager user identity in the Active Directory, the maximum name length remainsthe same, but includes the suffix.

Although the lengths of some names can be of unlimited, excessive lengths canresult in policy that is difficult to manage and might result in poor systemperformance. Choose maximum values that are logical for your environment.


Appendix E. pdadmin to Web Portal Manager equivalents

This appendix shows the mapping of the administration pdadmin commands toWeb Portal Manager.

Information about the pdadmin utility can be found in the IBM Tivoli AccessManager for e-business: Command Reference.

Table 8. Mapping between the pddamin utility and Web Portal Manager

pdadmin utility Web Portal Manager

acl attach object_name acl_name ACL → List ACL → click ACL name → Attachtab → Attach → type protected object path →Attach

acl create acl_name ACL → Create ACL → fill in form → Create

acl delete acl_name ACL → List ACL → select ACL names →Delete

acl detach object_name ACL → List ACL → click ACL name → Attachtab → select protected object → Detach

acl find acl_name ACL → List ACL → click ACL name → Attachtab

acl list ACL → List ACL

acl list acl_name attribute ACL → List ACL → click ACL name →Extended Attribute tab

acl modify acl_name delete attributeattribute_name

ACL → List ACL → select ACL name →Extended Attribute tab → select attributes →Delete

acl modify acl_name delete attributeattribute_name attribute_value

Not supported

acl modify acl_name description description ACL → List ACL → click ACL name → modifydescription → Set

acl modify acl_name remove any-other ACL → List ACL → click ACL name → selectAny-other → Delete

acl modify acl_name remove groupgroup_name

ACL → List ACL → click ACL name → selectgroup name → Delete

acl modify acl_name removeunauthenticated

ACL → List ACL → click ACL name → selectUnauthenticated → Delete

acl modify acl_name remove user user_name ACL → List ACL → click ACL name → selectuser name → Delete

acl modify acl_name set any-otherpermissions

ACL → List ACL → click ACL name → selectAny-other → Create → select permissions →Apply

acl modify acl_name set attributeattribute_name attribute_value

ACL → List ACL → click ACL name →Extended Attribute tab → Create → fill inform → Apply

acl modify acl_name set group group_namepermissions

ACL → List ACL → click ACL name → Create→ select Group → specify group name → selectpermissions → Apply


Table 8. Mapping between the pddamin utility and Web Portal Manager (continued)


acl modify acl_name set unauthenticatedpermissions

ACL → List ACL → click ACL name → Create→ select Unauthenticated → selectpermissions → Apply

acl modify acl_name set user user_namepermissions

ACL → List ACL → click ACL name → Create→ select User → specify user name → selectpermissions → Apply

acl show acl_name ACL → List ACL → click ACL name

acl show acl_name attribute attribute_name ACL → List ACL → click ACL name →Extended Attribute tab

action create name description action_type ACL → List Action Groups → click primaryaction group → Create → fill in form → Create

action create name description action_typeaction_group_name

ACL → List Action Groups → click actiongroup → Create → fill in form → Create

action delete name ACL → List Action Groups → click primaryaction group → select actions → Delete

action delete name action_group_name ACL → List Action Groups → click actiongroup → select actions → Delete

action group create action_group_name ACL → Create Action Group → type groupname → Create

action group delete action_group_name ACL → List Action Groups → select actiongroups → Delete

action group list ACL → List Action Groups

action list ACL → List Action Groups → click primaryaction group

action list action_group_name ACL → List Action Groups → click actiongroup

admin show configuration Not supported

authzrule attach object_name ruleid AuthzRule → List AuthzRule → clickauthorization rule name → Attach tab →Attach → type protected object path → Attach

authzrule create ruleid {–rulefile filename |ruletext} [–desc description] [–failreasonfailreason]

AuthzRule → Create AuthzRule → fill inform → Create

authzrule delete ruleid AuthzRule → List AuthzRule → selectauthorization rule name → Delete

authzrule detach object_name AuthzRule → List AuthzRule → clickauthorization rule name → Attach tab → selectobject names → Detach

authzrule find ruleid AuthzRule → List AuthzRule → clickauthorization rule name → Attach tab

authzrule list AuthzRule → List AuthzRule

authzrule modify ruleid {–rulefile filename |ruletext rule_text | description description |failreason failreason

AuthzRule → List AuthzRule → clickauthorization rule name → modify fields →Apply

authzrule show ruleid AuthzRule → List AuthzRule → clickauthorization rule name

config modify svrpassword config_filepassword

Not supported




config modify keyvalue set [–obfuscate]config_file stanza key value

Not supported

config modify keyvalue append[–obfuscate] config_file stanza key value

Not supported

config modify keyvalue remove config_filestanza key value

Not supported

config modify keyvalue remove config_filestanza key

Not supported

config show config_file stanza key Not supported

context show Not supported

domain create domain domain_admin_iddomain_admin_password [–desc description]

Secure Domain → Create Secure Domain →fill in form → Create

domain delete domain [–registry] Secure Domain → List Secure Domain →select secure domain names → Delete

domain list Secure Domain → List Secure Domain

domain modify domain descriptiondescription

Secure Domain → List Secure Domain →click secure domain name → modifydescription → Apply

domain show domain Secure Domain → List Secure Domain →click secure domain name

errtext error_number Not supported

exit Not supported

group create group_name dn cn[group_container]

Group → Create Group → fill in form →Create

group delete [–registry] group_name Group → Search Groups → type pattern andmaximum results → Search → select groupnames → Delete

group import group_name dn[group_container]

Group → Import Group → fill in form →Import

group list pattern max_return Group → Search Groups → type pattern andmaximum results → Search

group list-dn pattern max_return Not supported

group modify group_name add user

group modify group_name add (user_1 user_2[... user_n])

Group → Search Groups → type pattern andmaximum results → Search → click groupname → Members tab → select users → Add

group modify group_name descriptiondescription

Group → Search Groups → type pattern andmaximum results → Search → click groupname → type description → Apply

group modify group_name remove user

group modify group_name remove (user_1user_2 [... user_n])

Group → Search Groups → type pattern andmaximum results → Search → click groupname → Members tab → select user names →Remove

group show group_name Group → Search Groups → type pattern andmaximum results → Search → click groupname

group show-dn dn Not supported

Appendix E. pdadmin to Web Portal Manager equivalents 339



group show-members group_name Group → Search Groups → type pattern andmaximum results → Search → click groupname → Members tab

help {topic | command} Not supported

login –a admin_id –p password [–d domain |–m]

Not supported

login –l Not supported

logout Not supported

object access object_name permissions Not supported

object create object_name description typeispolicyattachable {yes | no}

Object Space → Create Object → fill in form→ Create

The type field is not supported.

You can select the Can Policy be attached tothis object check box on the ProtectedObject Properties page.

object delete object_name Object Space → Browse Object Space →expand and click object name → Delete

object exists object_name Not supported

object list Object Space → Browse Object Space →expand

object list object_name Object Space → Browse Object Space →expand and click object name

object list object_name attribute Object Space → Browse Object Space →expand and click object name → ExtendedAttributes tab

object listandshow object_name Not supported

object modify object_name deleteattribute_name

Object Space → Browse Object Space →expand and click object name → ExtendedAttributes tab → select attribute → Delete

object modify object_name deleteattribute_name attribute_value

Not supported

object modify object_name set attributeattribute_name attribute_value

Object Space → Browse Object Space →expand and click object name → ExtendedAttributes tab → Create → fill in form →Apply

object modify object_name set descriptiondescription

Object Space → Browse Object Space →expand and click object name → modifydescription → Apply

object modify object_nameisPolicyAttachable {yes | no}

Object Space → Browse Object Space →expand and click object name → select orclear check box→ Apply

object modify object_name type type Not supported

object show object_name Object Space → Browse Object Space →expand and click object name

object show object_name attributeattribute_name

Object Space → Browse Object Space →expand and click object name → ExtendedAttributes tab




objectspace create objectspace_name Object Space → Create Object Space → fill inform → Create

objectspace delete objectspace_name Object Space → Browse Object Space → clickobject space name → Delete

objectspace list Object Space → Browse Object Space

policy get policy_name User → Show Global User Policy

policy get policy_name –user user_name User → Search Users → type pattern andmaximum results → Search → click user name→ Policy tab

policy set policy_name policy_value User → Show Global User Policy → modifyvalue → Apply

policy set policy_name policy_value –useruser_name

User → Search Users → type pattern andmaximum results → Search → click user name→ Policy tab → modify value → Apply

pop attach object_name pop_name POP → List POP → click POP name → Attachtab → Attach → type protected object path →Attach

pop create pop_name POP → Create POP → fill in form → Create

pop delete pop_name POP → List POP → select POP names →Delete

pop detach object_name POP → List POP → click POP name → Attachtab → select object → Detach

pop find pop_name POP → List POP → click POP name → Attachtab

pop list POP → List POP

pop list pop_name POP → List POP → click POP name

pop list pop_name attribute POP → List POP → click POP name →Extended Attributes tab

pop modify pop_name delete attributeattribute_name

POP → List POP → click POP name →Extended Attributes tab → select attributes →Delete

pop modify pop_name delete attributeattribute_name attribute_value

Not supported

pop modify pop_name set attributeattribute_name attribute_value

POP → List POP → click POP name →Extended Attributes tab → Create → fill inform → Apply

pop modify pop_name set audit-level {all |none | audit_level_list}

POP → List POP → click POP name → selector clear appropriate check boxes → Apply

pop modify pop_name set descriptiondescription

POP → List POP → click POP name → modifydescription → Apply

pop modify pop_name set ipauth addnetwork netmask authentication_level

POP → List POP → click POP name → IPAuth tab → Create → type the network, netmask, and authentication level → Apply

pop modify pop_name set ipauth addnetwork netmask forbidden

POP → List POP → click POP name → IPAuth tab → Create → type network and netmask and select Forbidden check box →Apply




pop modify pop_name set ipauthanyothernw authentication_level

POP → List POP → click POP name → IPAuth tab → Create → select Any OtherNetwork check box and type authenticationlevel → Create

pop modify pop_name set ipauthanyothernw forbidden

POP → List POP → click POP name → IPAuth tab → Create → select Any OtherNetwork and Forbidden check boxes →Create

pop modify pop_name set ipauth removenetwork netmask

POP → List POP → click POP name → IPAuth tab → select IP authorization entries →Delete

pop modify pop_name set qop {none |integrity | privacy}

POP → List POP → click POP name → selectappropriate quality of protection → Apply

pop modify pop_name set tod-access {anyday| weekday | day_list}:{anytime |time_spec-time_spec}[:utc | local]

POP → List POP → click POP name → definetime of day access → Apply

pop modify pop_name set warning {yes |no}

POP → List POP → click POP name → selector clear Warn Only On Policy Violationcheck box → Apply

pop show pop_name POP → List POP → click POP name

pop show pop_name attribute POP → List POP → click POP name →Extended Attributes tab

quit Not supported

rsrc create resource_name [–desc description] GSO Resource → Create GSO → fill in form →Create

rsrc delete resource_name GSO Resource → List GSO → select resources→ Delete

rsrc list GSO Resource → List GSO

rsrc show resource_name GSO Resource → List GSO → click resource

rsrccred create resource_name rsrcuserresource_userid rsrcpwd resource_pwd rsrctype{web | group} user user_name

User → Search Users → Search → click username → GSO Credentials tab → Create → fillin form → Create

rsrccred create resource_group_name rsrcuserresource_userid rsrcpwd resource_pwd rsrctype{web | group} user user_name

User → Search Groups → Search → click username → GSO Credentials tab → Create → fillin form → Create

rsrccred delete resource_name rsrctype {web |group} user user_name

User → Search Users → Search → click username → GSO Credentials tab → selectcredentials → Delete

rsrccred delete resource_group_name rsrctype{web | group} user user_name

User → Search Groups → Search → click username → GSO Credentials tab → selectcredentials → Delete

rsrccred list user user_name User → Search Users → Search → click username → GSO Credentials tab

rsrccred modify resource_name rsrctype {web| group} [–rsrcuser resource_userid][–rsrcpwd resource_pwd] user user_name

User → Search Users → Search → click username → GSO Credentials tab → Create →modify form → Create




rsrccred modify resource_group_namersrctype {web | group} [–rsrcuserresource_userid] [–rsrcpwd resource_pwd] useruser_name

User → Search Groups → Search → click username → GSO Credentials tab → Create →modify form → Create

rsrccred show resource_name rsrctype {web |group} user user_name

User → Search Users → Search → click username → GSO Credentials tab

rsrccred show resource_group_name rsrctype{web | group} user user_name

User → Search Groups → Search → click username → GSO Credentials tab

rsrcgroup create resource_group_name [–descdescription]

GSO Resource → Create GSO Group → fillin form → Create

rsrcgroup delete resource_group_name GSO Resource → List GSO Groups → selectresource groups → Delete

rsrcgroup list GSO Resource → List GSO Groups

rsrcgroup modify resource_group_name addrsrcname resource_name

GSO Resource → List GSO Groups → selectresource group → select members → Add

rsrcgroup modify resource_group_nameremove rsrcname resource_name

GSO Resource → List GSO Groups → selectresource group → select members → Remove

rsrcgroup show resource_group_name GSO Resource → List GSO Groups → selectresource group

server list Not supported

server listtasks server_name Not supported

server replicate server_name Not supported

server show server_name Not supported

server task server_name {help | stats |trace}

Not supported

server task server_name server_task Not supported

For more information about the WebSEALserver tasks and junction points, see the IBMTivoli Access Manager for e-business: WebSEALAdministration Guide.

user create [–gsouser] [–no-password-policy] user_name dn cn sn password [group1[group2 ...]]

User → Create User → fill in form → Create

user delete [–registry] user_name User → Search Users → type pattern andmaximum results → Search → select usernames → Delete

user import [–gsouser] user_name dn[group_name]

User → Import User → fill in form → Import

user list pattern max_return User → Search Users → type pattern andmaximum results → Search

user list-dn pattern max_return Not supported

user modify user_name account-valid {yes |no}

User → Search Users → type pattern andmaximum results → Search → click user name→ select or clear check box → Apply

user modify user_name password password User → Search Users → type pattern andmaximum results → Search → click user name→ modify password→ Apply




user modify user_name password-valid {yes| no}

User → Search Users → type pattern andmaximum results → Search → click user name→ select or clear check box → Apply

user show user_name User → Search Users → type pattern andmaximum results → Search → click user name

user show-dn dn Not supported

user show-groups user_name User → Search Users → type pattern andmaximum results → Search → click user name→ Groups tab


Appendix F. Managing user registries

This chapter contains a subset of user registry tasks that are specific to theinstallation of Tivoli Access Manager. For common administrative tasks for yourparticular registry (tasks that are not specific to Tivoli Access Manager), refer to thedocumentation that came with your user registry product.

This chapter contains the following sections:v “LDAP-specific tasks”v “Active Directory-specific tasks” on page 362v “Novell-specific tasks” on page 368

LDAP-specific tasksLDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includeslow-level network protocol definitions plus data representation and handlingfunctionality. A directory that is accessible through LDAP is commonly referred toas an LDAP directory. An example of an LDAP server product is the TivoliDirectory Server, which is included with Tivoli Access Manager.

This section contains the following topics:v “LDAP failover configuration”v “Using valid characters for LDAP user and group names” on page 349v “Applying Tivoli Access Manager ACLs to new LDAP suffixes” on page 350

LDAP failover configurationThe Lightweight Directory Access Protocol (LDAP) defines a standard method foraccessing and updating information in a directory. Directories are usually accessedusing the client/server model of communication. Any server that implementsLDAP is an LDAP server.

The LDAP distributed architecture supports scalable directory services with serverreplication capabilities. Server replication improves the availability of a directoryservice. Tivoli Directory Server replication is based on a master-subordinate model.Sun Java System Web Server replication is based on a supplier/consumer model,which Tivoli Access Manager still treats as a master-subordinate or peer-to-peerrelationship.

Active Directory Application Mode (ADAM) replication is based on membership ina configuration set, which is a group of ADAM instances that share and replicate acommon configuration partition and schema partition. ADAM uses a multi-masterform of replication, which means that any instance in the configuration set iswritable and will propagate the changes to all other instances in the configurationset.

Note: ADAM instances cannot replicate with Active Directory, and they replicateon a schedule that is completely independent of the Active Directoryreplication schedule, even when ADAM is running in an Active Directorydomain.


Tivoli Access Manager treats each ADAM instance in a configuration set as areplica. The Access Manager directory partition that contains the secAuthorityInfosubtree must be replicated to each of the ADAM instances in the configuration set.Note that the default replication schedule for ADAM is once per hour. Thisschedule can be changed, but the most frequent rate at which ADAM will replicateis four times an hour; updates to one instance in a configuration set will not bepropagated for at least fifteen minutes. Therefore, when Tivoli Access Manager isused with ADAM, it is recommended that one instance in the configuration set isconfigured to have a higher read/write preference than all other instances. Thisway, updates are directed to the ADAM instance with the highest preference andno other instances will be used as failover unless the preferred instance is down.For information about setting the ADAM replication schedule, refer to ADAMdocumentation. For information about setting preference values, see “Settingpreference values for replica LDAP servers” on page 348.

Note: When using SSL, the same Certificate Authority should issue the ADAMcertificate for each instance in the configuration set. This way, Tivoli AccessManager can validate the ADAM certificate from each instance. If theADAM instances in the configuration set are on the same system, theinstances can share the same certificate.

When using a generic LDAP server, the failover configuration depends on thespecific LDAP server. As long as this LDAP server recognizes the concept ofmaster-subordinate, Tivoli Access Manager can use this replication support. Forinformation about whether your LDAP server supports replication in this manner,see the documentation for your LDAP server.

The combination of a master server and multiple replicated servers helps to ensurethat directory data is always available when needed. If any server fails, thedirectory service continues to be available from another replicated server. TivoliAccess Manager supports this replication capability.

The master-subordinate replication modelReplication involves two types of directories: master/peer and replica. LDAP refersto the master as the master server and to the replica as the replica server. Evenwhen peer-to-peer replication is being used, the peer servers can be considered“masters” for the Tivoli Access Manager perspective. All updates are made on themaster server and these updates are subsequently propagated to the replicaservers. Each replica server directory contains a copy of the data in the masterserver directory.

Changes to the directory can be made only to a master server, which is alwaysused for write operations to the directory. For Tivoli Access Manager, these typesof servers are configured as readwrite servers. Either the master or the replicas canbe used for read operations. When the original master server is out of service foran extended period of time, a replica server can be promoted as a master server toallow write operations to the directory.

Tivoli Access Manager failover capability for LDAP serversTivoli Access Manager connects to the LDAP master server (indicated by the hostkey in the ldap.conf configuration file) when it starts up. If the LDAP masterserver is down for any reason, the Tivoli Access Manager server must be able toconnect to an available LDAP replica server for any read operations.For TivoliAccess Manager, these types of servers are configured as readonly servers.


Many operations, especially those from regular users, are read operations. Theseinclude operations such as user authentication and signon to back-end junctionedWeb servers. After proper configuration, Tivoli Access Manager performs failoverto a replica server when it cannot connect to the master server.

You can find the configuration parameters for LDAP failover in the [ldap] stanzaof the ldap.conf configuration file:

This configuration file is in one of the following operating system-specificlocations:

On Linux and UNIX operating systems/opt/PolicyDirector/etc/ldap.conf

On Windows operating systemsinstall_path\etc\ldap.conf

Master server configurationTivoli Directory Server supports the existence of a single read-write master LDAPserver or multiple peer-to-peer read/write servers. Sun Java System Web Serversupports multiple read-write LDAP servers. Tivoli Access Manager treats the SunJava System supplier server as the master server for configuration purposes.

The active configuration lines in the ldap.conf file represent the parameters andvalues for this master LDAP server. You determine these values during TivoliAccess Manager configuration. For example:[ldap]enabled = yeshost = outbackport = 389ssl-port = 636max-search-size = 2048

Entity Description

enabled Tivoli Access Manager uses an LDAP user registry. Values are yesand no.

host The network name of the machine where the LDAP masterserver is located. This server is assumed to be a readwrite serverwith a preference of 5.

port The TCP listening port of the LDAP master server.

ssl-port The SSL listening port of the LDAP master server.

max-search-size The Tivoli Access Manager limit for an LDAP client search ofdatabase items - such as a request for the Web Portal Manager tolist users from the LDAP database.

If you make a change to the LDAP database, such as adding a new user accountthrough the Web Portal Manager, Tivoli Access Manager uses the read-write(master) LDAP server.

Replica server configurationTivoli Directory Server supports the existence of one or more read-only replicaLDAP servers. Sun Java System Web Server supports the existence of one or moreread-only replica LDAP servers referred to as consumers.

You must add lines to the [ldap] stanza that identifies any replica servers availableto Tivoli Access Manager. Use the following syntax for each replica:

Appendix F. Managing user registries 347

replica = ldap_server,port,type,preference

Entity Description

ldap-server The network name of the LDAP replica server.

port The port this server listens on. Generally, use 389 or 636.

type The functionality of the replica server, which is either readonly orreadwrite. Normally, use read-only. A read-write type wouldrepresent a master server.

preference A number from 1 to 10. The server with the highest preferencevalue is chosen for LDAP connections. See “Setting preferencevalues for replica LDAP servers.”

Example:replica = replica1.ldap.tivoli.com,389,readonly,4replica = replica2.ldap.tivoli.com,389,readonly,4

Changes to the ldap.conf file do not take effect until you restart Tivoli AccessManager.

Setting preference values for replica LDAP serversEach replica LDAP server must have a preference value (1 to 10) that determinesits priority based on one of the following selections:v The primary read-only access serverv A backup read-only server during a failover

The higher the number, the higher the priority. If the primary read-only server failsfor any reason, the server with the next highest preference value is used. If two ormore servers have the same preference value, a least-busy load balancingalgorithm determines which one is selected.

Remember that the master LDAP server can function as both a read-only and aread-write server. For read-only access, the master server has a hardcoded defaultpreference setting of 5. This preference setting allows you to set replica servers atvalues higher or lower than the master to obtain the required performance. Forexample, with appropriate preference settings, you could prevent the master serverfrom handling everyday read operations.

You can set hierarchical preference values to allow access to a single LDAP server(with failover to the other servers), or set equal preferences for all servers andallow load balancing to dictate server selection.

The Table 9 illustrates some possible preference scenarios. “M” refers to the master(read-only/read-write) LDAP server; “R1”, “R2” and “R3” refer to the replica(read-only) LDAP servers.

Table 9. Potential preference scenarios

M R1 R2 R3 Failover preference

5 5 5 5 All servers have the same preference values. Load balancingdetermines which server is selected for each accessoperation.


Table 9. Potential preference scenarios (continued)

M R1 R2 R3 Failover preference

5 6 6 6 The three replica servers have the same preference value.This value is higher than the master server value. Loadbalancing determines server selection among the threereplicas. The master is used only if all three replica serversbecome unavailable.

5 6 7 8 Server 3 (with the highest preference value) becomes theprimary server. If server 3 fails, server 2 becomes theprimary server because it has the next highest preferencevalue.

Preference values affect only read-only access to the LDAP database. Tivoli AccessManager always uses the master (read-write) server when you need to make achange to the LDAP database.

Also note that some Tivoli Access Manager daemons (such as the policy server)override the preference settings in their configuration files to indicate that theread-write server is preferred. This override occurs because those daemons usuallymake update operations that should go to the master LDAP server.

Server pollingIf an LDAP server does fail, Tivoli Access Manager continuously polls the server tocheck for its return to active duty. The poll time is 10 seconds.

Using valid characters for LDAP user and group namesWhen using LDAP as the user registry, the set of valid characters allowed within auser or group name is determined by the following Internet Engineering TaskForce (IETF) Request for Comments (RFC):v 2253 Lightweight Directory Access Protocol (v3): UTF-8 String Representation of

Distinguished Names

v 2254 The String Representation of LDAP Search Filters

The specific LDAP server can also dictate the validity of these characters.

In general, you can use special characters within a distinguished name. However,certain special characters require an additional escape character. The followingspecial characters must be escaped when used in a distinguished name:v Plus sign (+)v Semicolon (;)v Comma (,)

For example, to create a user containing a semicolon using the pdadmin utility:pdadmin> user create "user;one" "cn=user\;one,o=tivoli,c=us""user;one" "user;one" password1

Note: Avoid using the backward slash character (\) as part of a user or groupname. For more information, see "Characters disallowed for user and groupname" in Appendix A of the IBM Tivoli Access Manager for e-business:Command Reference.

If you use special characters when using the pdadmin utility, enclose eachargument of the user or group command with double quotation marks. The double


quotation marks allow the argument to be entered without being subject tointerpretation by the operating system shell command processor.

Due to the variability of special character handling in general, avoid using specialcharacters.

Applying Tivoli Access Manager ACLs to new LDAP suffixesGenerally, the LDAP naming model is maintained in a hierarchical namespaceknown as the Directory Information Tree (DIT). Many LDAP server products, suchas Tivoli Directory Server, which is included with Tivoli Access Manager, and theSun Java System Web Server and Novell eDirectory, maintain the data of the DITin a hierarchical namespace that is often represented as a tree structure. The top ofthe tree is referred to as a naming context. Sometimes, this naming context is calleda suffix, because it represents the ending portion of a distinguished name (DN). Forexample, the c=us suffix might be created to represent country-specific data withinan organization. An entry within this suffix might have a DN similar to cn=JoeWilliams,ou=austin,o=ibm,c=us. The set of suffixes that is maintained by theLDAP server can be configured using the vendor-specific LDAP administrationtools.

When the Tivoli Access Manager policy server is configured, it attempts to applyappropriate access controls in the form of Access Control Lists (ACLs) to eachLDAP suffix that is in the LDAP server. This access control gives appropriatepermissions to allow Tivoli Access Manager to create and manage user and groupinformation in these suffixes.

Note: The Tivoli Access Manager policy server does not attempt to apply ACLs toeach LDAP suffix when ADAM is used as the user registry. Access toADAM registry entries is controlled by administration groups withinADAM.

For LDAP server types other than ADAM, if an LDAP administrator adds anLDAP suffix after Tivoli Access Manager is configured and wants Tivoli AccessManager to manage users and groups in this new suffix, the appropriate ACLsmust be applied to the new suffix.

To apply the appropriate access controls to a newly created LDAP suffix, use theivrgy_tool utility with the add-acls parameter. For more information, see"ivrgy_tool" in the IBM Tivoli Access Manager for e-business: Command Reference.Alternately, you can manually apply the following ACLs to each new suffix:cn=SecurityGroup,secAuthority=Default

v Full accesscn=ivacld-servers,cn=SecurityGroups,secAuthority=Default

v readv searchv comparev write for the following attributes:

– secAcctValid– secPwdFailCountTime– secPwdFailures– secPwdLastChanged– secPwdLastFailed– secPwdLastUsed– secPwdUnlockTime– secPwdValid


cn=remote-acl-users,cn=SecurityGroups,secAuthority=Defaultv readv searchv comparev write for the following attributes:


When using a generic LDAP server, the same access controls should be given tothe specified groups. For information about how to set access control for a genericLDAP server, see the documentation that is associated with the generic LDAPserver.

If a Tivoli Access Manager administrator created a domain other than the initial\Management domain, which is created during the configuration of the policyserver, the following additional ACLs should be applied to the new suffix for eachdomain:cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains,secAuthority=Default

v Full accesscn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default



cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default




Where domain_name is the name of the additional administrative domain. For a listof domains, use the domain list command.

Example proceduresThe following example procedures can be used for either Tivoli Directory Server orSun Java System Web Server, depending on the LDAP server type being used. Thefollowing example procedures assume the newly created c=fr suffix. Substituteyour newly created suffix for this value in the following procedures.

Tivoli Directory Server: This procedure describes how to apply the appropriateTivoli Access Manager access controls in Tivoli Directory Server for a newlycreated suffix. This procedure uses the Tivoli Directory Server Web AdministrationTool and assumes that this tool is installed and configured into the WebSphereApplication Server.1. Access the login page using a supported Web browser. The default login page

is the following URL:

http://server_name:12100/IDSWebApp/IDSjsp/Login.jspWhere server_name is the host name of the application server where the WebAdministration Tool is installed.

If the list of console server contains the LDAP server to be administered, select itshost name and go to step 4. If this list does not contain the server, add it as aconsole server.2. Add an LDAP server to the list of console servers:

a. Log in as the Console Admin. The default Console Admin identity issuperadmin and the default password is secret.

b. In the navigation area on the left, click Console administration andManage console servers. This action presents a list of LDAP servers thatare currently configured for administration.

c. Click Add and type the host name and port number for the LDAP serverto be administered.

d. Click OK to add the server.e. Click Close to complete the action.f. From the navigation area, click Logout.

3. Access the login page using the URL in step 1 and select from the list theLDAP server that you added.

4. In the Login window, type the LDAP server administrator in the Usernamefield (for example, cn=root) and password in the password field, and clickLogin.

5. In the navigation area on the left, click Directory management and Manageentries.

If you see the newly added suffix in the Manage entries window on the right, goto step 7 on page 353. If you do not see the newly added suffix, add an entry for anewly created suffix.6. Add a suffix:

a. Click Add to display the Add an entry window.b. Select the appropriate structural object class for the newly added suffix.

For the c=fr suffix, the appropriate object class is country.c. Click Next to display the Select auxiliary object classes window where you

can add additional object classes appropriate for the entry type.d. Because this example does not use other object classes, click Next to define

the selected structural object class.


e. In the Relative DN field, type c=fr and leave the Parent DN field blank.The only required attribute is c for country. Fill in the value fr, and clickFinish to return to the Manage entries window. You should now see thenewly added suffix in the list of top-level entries.

7. In the Manage entries window:a. From the Select column, select the suffix.b. From the Select Action list, select Edit ACL.c. Click Go to display the Edit ACL window that shows the current ACLs on

the suffix.8. In the Edit ACL window:

a. Click Non-filtered ACLs.b. Ensure that the Propagate ACLs option is selected.c. Click Add to display the Add access rights window.

9. In the Add access rights window:a. In the Subject DN (distinguished name) field, type

cn=SecurityGroup,secAuthority=Default.b. Set the Add child right to grant.c. Set the Delete entry right to grant.d. Set the normal, sensitive, critical, system and restricted security classes to

grant for the read, write, search, and compare actions.e. Click OK to return to the Edit ACL window.

10. In the Edit ACL window, click Add to display the Add access rights window.11. In the Add access rights window:

a. In the Subject DN (distinguished name) field, type cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default.

b. Set the Subject Type to group.c. Set the normal security classes to grant for the read, search, and compare

actions.d. From the Attributes list, select secAcctValid and click Define. Repeat this

step for each of the following attributes:v secPwdFailCountTimev secPwdFailuresv secPwdLastChangedv secPwdLastFailedv secPwdLastUsedv secPwdUnlockTimev secPwdValid

e. After defining these attributes, set each of these attributes to grant for theread, write, search, and compare actions.

f. Click OK to return to the Edit ACL window.

If you have other domains and need to add domain ACLs, continue to step 12. Ifyou have no further domains, this completes the access control. Go to step 17 onpage 354. This sample procedure has additional domains the require domain ACLs.12. In the Edit ACL window, click Add to display the Add access rights window.

In the Add access rights window:a. In the Subject DN (distinguished name) field, type

cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains,secAuthority=Default, where domain_name is the domain name beingprotected.


b. Set the Add child right to grant.c. Set the Delete entry right to grant.d. Set the normal, sensitive, critical, system and restricted security classes to

grant for the read, write, search, and compare actions.e. Click OK to return to the Edit ACL window.

13. In the Edit ACL window, click Add to display the Add access rights window.14. In the Add access rights window:

a. In the Subject DN (distinguished name) field, type cn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default, where domain_name is the domain name beingprotected.





f. Click OK to return to the Edit ACL window.15. In the Edit ACL window, click Add to display the Add access rights window.16. In the Add access rights window:

a. In the Subject DN (distinguished name) field, type cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default, where domain_name is the domain name beingprotected.





f. Click OK to return to the Edit ACL window.

This completes the addition of the access control for the suffix.17. Click Close.You do not need to restart the LDAP server for the changes to take affect.


18. If you no longer need to use the Web Administration Tool, click Logout.

Sun Java System Web Server: The following procedure describes how to applythe appropriate Tivoli Access Manager access controls to the newly created suffixfor Sun Java System Web Server. This procedure uses the Sun Java System ServerConsole, version 5.2.1. Start the Sun Java System Server Console using one of the following

commands:v On Linux and UNIX operating systems, enter the following command from

the Sun Java System Web Server installation directory:# ./startconsole

v On systems running the Solaris operating environment, when not using theSolaris packaged version:a. Change to the server root directory.b. Enter the following command:

startconsole arguments

c. Type –h to display a usage message explaining command linearguments.

v On Windows operating systems, select Start � Programs � Sun Java SystemServer Products � Sun Java System Server Console Version 5.2.

2. Log in to the Sun Java System Server Console:a. Type the LDAP administrator ID, which is usually cn=Directory Manager

b. Type the password for this administrator.c. Click OK.

3. Select the Sun Java System Domain to be used by Tivoli Access Manager.4. Expand the server name and Server Group.5. Select Directory Server to display the configuration information about the Sun

Java System Directory server.6. Click Open to access the Sun Java System Directory server.7. Click the Directory tab. If the newly created suffix is displayed on the left

pane, go to step 8. If the newly created suffix is not displayed, create an entryfor the new suffix before applying access controls to the suffix.

Note: These instructions assume an example suffix. Create the entry type andname that corresponds to your actual suffix.

To create the entry:a. Right-click the name of the server at the top of the directory tree, and

select Object → New Root Object to display a list of root suffixes.b. Select c=fr from the list of root suffixes. The New Object selection window

is displayed.c. In the New Object selection window, scroll down and select Country as

the new object entry type.d. Click OK to display the Property Editor window.e. In the Country field type fr, and click OK.f. Select View → Refresh to display the new suffix.

8. Right-click c=fr in the left pane, and select Object → Set Access Permissions todisplay the Manage Access Control for c=fr window.

9. Click New to display the Edit ACI for c=fr window.10. In the Edit ACI for c=fr window:


a. In the ACI name field, type SECURITY GROUP – ALLOW ALL.b. Highlight All Users, and click Remove.c. Click Edit Manually.d. Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="*")(version 3.0; acl "SECURITY GROUP – ALLOW ALL";allow (all)groupdn = "ldap:///cn=SecurityGroup,secAuthority=Default";)

e. Click Check Syntax to ensure validate the text. Correct errors until thesyntax validates.

f. Click OK to return to the Manage Access Control for c=fr window.11. Click New to display the Edit ACI for c=fr window.12. In the Edit ACI for c=fr window:

a. In the ACI name field, type PD Servers GROUP – ALLOW READ.b. Highlight All Users, and click Remove.c. Click Edit Manually.d. Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="*")(version 3.0; acl "PD Servers GROUP – ALLOW READ";allow (read, search, compare)groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default";)



a. In the ACI name field, type SECURITY GROUP– ALLOW WRITE.b. Highlight All Users, and click Remove.c. Click Edit Manually.d. Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="secAcctValid ||secPwdFailCountTime || secPwdFailures || secPwdLastChanged ||secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime ||secPwdValid")(version 3.0; acl "SECURITY GROUP– ALLOW WRITE";allow (read, search, compare)groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default";)



a. In the ACI name field, type PD Remote ACL Users GROUP – ALLOW READ.b. Highlight All Users, and click Remove.c. Click Edit Manually.d. Replace the default ACI text with the following text:


(target="ldap:///c=fr")(targetattr="*")(version 3.0; acl "PD Remote ACL Users GROUP – ALLOW READ";allow (read, search, compare)groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default";)




(target="ldap:///c=fr")(targetattr="secAcctValid ||secPwdFailCountTime || secPwdFailures || secPwdLastChanged ||secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime ||secPwdValid")(version 3.0; acl "SECURITY GROUP– ALLOW WRITE";allow (read, search, compare)groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default";)



a. In the ACI name field, type PD Deny-Others.b. Highlight All Users, and click Remove.c. Click Edit Manually.d. Replace the default ACI text with the following text:

(targetfilter="(secAuthority=Default)")(version 3.0; acl "PD Deny-Others";deny(all)groupdn != "ldap:///cn=SecurityGroup,secAuthority=Default||ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default||ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default";)


f. Click OK to return to the Manage Access Control for c=fr window.

If you have no further domains, this completes the access control. You can skip tostep 33 on page 359. If you have additional domains and need to add domainACLs, continue with step 21.21. Click New to display the Edit ACI for c=fr window.22. In the Edit ACI for c=fr window:

a. In the ACI name field, type SECURITY GROUP – ALLOW ALL.b. Highlight All Users, and click Remove.c. Click Edit Manually.d. Replace the default ACI text with the following text:


(target="ldap:///c=fr")(targetattr="*")(version 3.0; acl "SECURITY GROUP - ALLOW ALL;allow (all)groupdn = "ldap:///cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)

where domain_name is the name of the domain being protected.e. Click Check Syntax to ensure validate the text. Correct errors until the

syntax validates.f. Click OK to return to the Manage Access Control for c=fr window.


a. In the ACI name field, type PD Servers GROUP – ALLOW READ.b. Highlight All Users, and click Remove.c. Click Edit Manually.d. Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="*")(version 3.0; acl "PD Servers GROUP - ALLOW READ";allow (read, search, compare)groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)





(target="ldap:///c=fr")(targetattr="secAcctValid ||secPwdFailCountTime || secPwdFailures || secPwdLastChanged ||secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime ||secPwdValid")(version 3.0; acl "SECURITY GROUP– ALLOW WRITE";allow (read, search, compare)groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)



a. In the ACI name field, type PD Remote ACL Users GROUP – ALLOW READ.b. Highlight All Users, and click Remove.c. Click Edit Manually.d. Replace the default ACI text with the following text:


(target="ldap:///c=fr")(targetattr="*")(version 3.0; acl "PD Remote ACL Users GROUP - ALLOW READ";allow (read, search, compare)groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)





(target="ldap:///c=fr")(targetattr="secAcctValid ||secPwdFailCountTime || secPwdFailures || secPwdLastChanged ||secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime ||secPwdValid")(version 3.0; acl "SECURITY GROUP– ALLOW WRITE";allow (read, search, compare)groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)



a. In the ACI name field, type PD Deny-Others.b. Highlight All Users, and click Remove.c. Click Edit Manually.d. Replace the default ACI text with the following text:

(targetfilter="(secAuthority=domain_name)")(version 3.0; acl "PD Deny-Others";deny(all)groupdn != "ldap:///cn=SecurityGroup,secAuthority=Default||ldap:///cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains,secAuthority=Default||ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default||ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)



If there are further domains, repeat steps 21 on page 357 to 32. For each domain.When complete, continue with step 33.33. Click OK to close the Manage Access Control for c=fr window.34. Click Console → Exit to exit the console.


IBM z/OS Security Server: This procedure describes how to apply theappropriate Tivoli Access Manager access controls to the newly created suffix forIBM z/OS Security Server after the Tivoli Access Manager policy server isconfigured. Instead of using the manual process described below, you can use theivrgy_tool utility to update the ACLs on suffixes added after the initial policyserver configuration. For information about using this utility, see "ivrgy_tool" in theInstallation Guide.

These steps are specifically for the IBM z/OS Security Server LDAP Server version1.4, the IBM z/OS Integrated Security Services LDAP Server Version 1.6, and theIBM Tivoli Directory Server for z/OS Version 1.8. Hereafter, these LDAP serversare referred to as the IBM z/OS LDAP Server.

To add a suffix for the IBM z/OS LDAP Server manually:1. Add the new suffix to the LDAP server configuration file. See z/OS LDAP

Server Administration and Use for your version of z/OS LDAP for details onhow to update the server configuration file.

2. Restart the IBM z/OS LDAP Server.3. To add an entry to the newly created suffix, perform the following steps:

a. Create an LDIF file. This example assumes the newly created suffix iso=neworg,c=us:dn: o=neworg,c=usobjectClass: organizationobjectClass: topo: neworg

b. Use the appropriate LDIF file as input to the ldapadd command:ldapadd -h ldap_host -p ldap_port -D ldap_admin_dn -w ldap_admin_pwd-v -f ldif_filename

4. To apply the appropriate Tivoli Access Manager access controls to the newlycreated suffix (suffix), do either of the following tasks:v If no additional Access Manager domains were created other than the initial

management domain, complete the following steps:a. Create the following LDIF file:

dn: suffixaclpropagate: TRUEaclentry: group:cn=SecurityGroup,secAuthority=Default:object:ad:normal:\rwsc:sensitive:rwsc:critical:rwsc:restricted:rwscaclentry: group:cn=ivacld-servers,cn=SecurityGroups,secAuthority=Defaul\t:normal:rsc:at.secAcctValid:rwsc:at.secPwdFailCountTime:rwsc:at.secPwd\Failures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:at.sec\PwdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwscaclentry: group:cn=remote-acl-users,cn=SecurityGroups,secAuthority=Defau\lt:normal:rsc:at.secAcctValid:rwsc:at.secPwdFailCountTime:rwsc:at.secPwd\Failures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:at.secP\wdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwscentryowner: LDAP_admin_dnentryowner: group:cn=SecurityGroup,secAuthority=Defaultownerpropagate: TRUE

The backward slash ( \ ) at the end of a line indicates that this linecombines with the next line, without any spaces.

b. Apply the updates in the LDIF file by using it as input to the ldapmodifycommand:ldapmodify -h ldap_host -p ldap_port -D ldap_admin_dn-w ldap_admin_pwd -v -f ldif_file


v If a domain was created in addition to the initial management domain, and ifa new suffix is created, ACLs need to be applied for each added domain.Complete the following steps:a. Add ACLs to the default domain and added domain (added_domain) by

creating an LDIF file similar to the following one:dn: suffixaclentry: group:cn=SecurityGroup,secAuthority=Default:object:ad:normal\:rwsc:sensitive:rwsc:critical:rwsc:restricted:rwscaclentry: group:cn=ivacld-servers,cn=SecurityGroups,secAuthority=Defau\lt:normal:rsc:at.secAcctValid:rwsc:at.secPwdFailCountTime:rwsc:at.secP\wdFailures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:at.\secPwdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwscaclentry: group:cn=remote-acl-users,cn=SecurityGroups,secAuthority=Def\ault:normal:rsc:at.secAcctValid:rwsc:at.secPwdFailCountTime:rwsc:at.se\cPwdFailures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:a\t.secPwdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwscaclentry: group:cn=SecurityGroup,secAuthority=added_domain,cn=Subdomai\ns,secAuthority=Default:object:ad:normal:rwsc:sensitive:rwsc:critical:\rwsc:restricted:rwscaclentry: group:cn=ivacld-servers,cn=SecurityGroups,secAuthority=added\_domain,cn=Subdomains,secAuthority=Default:normal:rsc:at.secAcctValid:\rwsc:at.secPwdFailCountTime:rwsc:at.secPwdFailures:rwsc:at.secPwdLastC\hanged:rwsc:at.secPwdLastFailed:rwsc:at.secPwdLastUsed:rwsc:at.secPwdU\nlockTime:rwsc:at.secPwdValid:rwscaclentry: group:cn=remote-acl-users,cn=SecurityGroups,secAuthority=add\ed_domain,cn=Subdomains,secAuthority=Default:normal:rsc:at.secAcctVali\d:rwsc:at.secPwdFailCountTime:rwsc:at.secPwdFailures:rwsc:at.secPwdLas\tChanged:rwsc:at.secPwdLastFailed:rwsc:at.secPwdLastUsed:rwsc:at.secPw\dUnlockTime:rwsc:at.secPwdValid:rwscaclpropagate: TRUEentryowner: LDAP_admin_dnentryowner: group:cn=SecurityGroup,secAuthority=Defaultownerpropagate: TRUE

b. Apply the updates in the LDIF file by using it as input to the ldapmodifycommand:ldapmodify -h ldap_host -p ldap_port -D ldap_admin_dn -w ldap_admin_pwd-v -f ldif_file

Note: The ldapmodify command returns an error if the following attributes andvalues are set by default for the newly added suffix:aclpropagate: TRUEentryowner: LDAP_admin_dnownerpropagate: TRUE

If the ldapmodify command returns the following error, remove these threeattribute and value pairs from the LDIF file and run the ldapmodifycommand again:ldapmodify: additional info: R004086 Entry ’suffix’ already contains

attribute ’attribute’ with value ’value’

Setting the password history policyWhen using Tivoli Directory Server as your user registry, you can take advantageof its password history policy. To enable this policy, complete the following steps:1. Access the login page using a supported Web browser. The default login page

is the following URL:

http://server_name:12100/IDSWebApp/IDSjsp/Login.jspWhere server_name is the host name of the application server where the WebAdministration Tool is installed.


2. Select the LDAP Host name to be managed and log in as an LDAPadministrator (for example, cn=root). The Web Administration Tool starts.

3. In the navigation area, select Server administration � Manage securityproperties.

4. In the main window, select Password validation.5. Set the minimum number of passwords that must be used before a password

can be reused. Enter a number from 0 to 30. If you enter zero, a password canbe reused without restriction.

6. Click Apply.7. In the main window, click Password policy.8. If not already enabled, set the Password policy enabled check box to enable

password policy.9. Click OK.

For more information about setting the password policy that is used with TivoliDirectory Server, see the IBM Tivoli Directory Server: Administration Guide.

Active Directory-specific tasksMicrosoft Active Directory is an infrastructure supported by Windows 2003 thatincludes a network management of directory objects, and has the capability tocommunicate with other directory services.

This section contains the following topics:v “Setting up Microsoft Windows 2003 Domain Name System for Active

Directory”v “Updating the Tivoli Access Manager schema” on page 363v “Adding a Tivoli Access Manager user to the Active Directory system group” on

page 364v “Using valid characters for Active Directory user, group, and distinguished

names” on page 364v “Importing dynamic groups to Tivoli Access Manager” on page 366v “Enabling change user password requests to be performed using LDAP APIs”

on page 366

Setting up Microsoft Windows 2003 Domain Name System forActive Directory

Active Directory uses the Domain Name System (DNS) as a domain controllerlocation mechanism. DNS enables computers to find the IP addresses of thedomain controllers.

For multi-domain mode, at least two domains are required from these types ofdomains:v A primary domainv A child domain of the primary domainv A domain tree in the forest

For failover, at least two primary domain controllers are needed.

You can set up the DNS server before configuring the domain controllers or whenyou configure the primary Active Directory domain controller. There are two waysto set up DNS for Active Directory:


1. Configure DNS on the forest root2. Use a separate DNS server

If configuring DNS on the forest root, DNS is configured automatically on thathost if this is the first domain controller configured. This domain controller and itsreplicas serve as the DNS servers.

The DNS server is not necessary on the host that is the domain controller in theforest. You can use any DNS server. If you are not using a Windows-based DNSserver, contact your DNS administrator or a DNS server vendor to find outwhether your server supports the required standards. If the server does notsupport the required standards or the zone cannot be configured to allow dynamicupdates, you need to modify the existing DNS infrastructure.

Adding a new domain name to a DNSTo add a new domain name to a DNS, do the following:1. Click Start → Programs → Administrator Tools → DNS to open the DNS.2. Expand the host name, and expand Forward Lookup Zones.3. Create a new zone (new root domain) or child domain.4. If using a separate DNS, open the domain properties and change the Allow

dynamic updates field to Yes.

Updating the Tivoli Access Manager schemaTo perform all Tivoli Access Manager operations, you need to add a Tivoli AccessManager schema on Active Directory. TheTivoli Access Manager schema needs tobe added to the schema master. The master schema is a root domain controller inthe forest. The Tivoli Access Manager schema is updated to the schema masterduring the configuration of Tivoli Access Manager.

Note: Before updating the Tivoli Access Manager schema, verify that it is notalready on the schema master. The Tivoli Access Manager schema needs tobe updated only once in the forest.

To verify that the Tivoli Access Manager schema is updated on your system,complete the following steps:1. In your domain controller, go to Start → Programs → Administrative Tools →

Active Directory Users and Computers. The Active Directory Users andComputers window is displayed.

2. In this window, expand the domain that contains the Users folder.3. Right click the Users folder. A menu opens.4. Click New in the menu. Another menu opens.5. If a list of Tivoli Access Manager classes for Active Directory is displayed in the

menu in the URAF-xxx form, (for example, URAF-container), then the TivoliAccess Manager schema is already on the schema master. You do not need toupdate the Tivoli Access Manager schema.

To manually update the Tivoli Access Manager schema, complete the followingsteps:1. Install Tivoli Access Manager runtime on the root domain controller.2. Run the following command:

aminstall_dir\sbin\adschema_update –u AMConfID –p AMConfPWD

where:


v aminstall_dir is the directory that installs Tivoli Access Managerv AMConfID is the Tivoli Access Manager configuration login IDv AMConfPWD is the Tivoli Access Manager configuration login password

3. After you verify that the Tivoli Access Manager schema was added to theschema master, you can uninstall Tivoli Access Manager runtime from the rootdomain.

Note: The Tivoli Access Manager schema propagation takes approximately fiveminutes from the schema master to add to the non-root domain controller.

Adding a Tivoli Access Manager user to the Active Directorysystem group

To have sufficient access to modify user and group attributes, a Tivoli AccessManager user must be added to the appropriate Active Directory system group. Toadd a user to an Active Directory system group on a system where ActiveDirectory is configured as a Tivoli Access Manager user registry, and do thefollowing:1. Log in as Administrator.2. Go to Start → Programs → Administrative Tools.3. Click Active Directory Users and Computers from the menu. The Active

Directory Users and Computers window is displayed.4. On the left navigation panel, go to Tivoli PD Domains → default → system →

users, where the users container of the Tivoli Access Manager user registrycontainer is located.

5. From the list of users displayed, select the Tivoli Access Manager user thatyou want to add to the Active Directory system group.

6. Right-click the Tivoli Access Manager user, and click Properties. TheProperties window for the selected Tivoli Access Manager user is displayed.

7. Click the Member Of tab.8. Click Add. The Select Groups window is displayed.9. Select the appropriate group that you want the Tivoli Access Manager user to

become a member of, and click Add.10. Do one of the following:

v If the purpose is to modify user or group attributes for Active Directorysingle domain, select the Domain Admins group.

v If Tivoli Access Manager is configured using Active Directory multipledomain, select the Enterprise Admins group.

11. For each user you want to add to multiple groups, repeat theadd-user-to-group process.

12. Click OK to close all opened windows.

Using valid characters for Active Directory user, group, anddistinguished names

This section describes how to specify valid characters for Active Directory usernames, group names, and distinguished names (DNs). In version 6.0, Tivoli AccessManager added support to handle special characters for DNs, (as described in RFC1779 and RFC 2253).


Attention: If you upgraded the policy server to Tivoli Access Manager, version6.0, but did not upgrade the blade servers, you can create and import userscontaining special characters. However, these users cannot authenticate at theTivoli Access Manager blade level (version 3.9, 4.1, or 5.1).

User and group namesActive Directory user and group names can contain all Unicode characters exceptfor the following characters:v Forward slash (/)v Backward slash (\)v Left square bracket ([)v Right square bracket (])v Colon (:)v Semicolon (;)v Vertical bar (|)v Equal sign (=)v Plus sign (+)v Asterisk (*)v Question mark (?)v Left angle bracket (<)v Right angle bracket (>)v Double quote (")v At symbol (@)

Note: An "at" symbol (@) is not allowed unless it is used to specify the domain.For example, [email protected] is allowed; user@[email protected] isnot allowed.

If you use special characters when using the pdadmin utility, enclose eachargument of the user or group command with double quotation marks. The doublequotation marks allow the argument to be entered without being subject tointerpretation by the operating system shell command processor.

Due to the variability of special character handling in general, avoid using specialcharacters.

User and group distinguished namesThere are special characters that are not allowed in a distinguished name (DN)unless the character is preceded by an additional escape character or is encoded inhexadecimal. To encode in hexadecimal, replace the character with a backwardslash (\) followed by two hexadecimal digits.

The following characters must be escaped using the backward slash (\) characterbefore being used in a distinguished name:v Pound sign (#) at the beginning of the stringv A space at the end of the stringv Comma (,)v Plus sign (+)v Double quotation (")v Left angle bracket (<)v Right angle bracket (>)v Semicolon (;)


Note: Due to differences in registries and command shell processors, avoid usingthe backward slash character (\) in distinguished names. For moreinformation, see "Characters disallowed for distinguished names" inAppendix A of the IBM Tivoli Access Manager for e-business: CommandReference.

For other reserved characters, such as an equal sign (=), asterisk (*), or a nonUTF-8 character, the character must be encoded in hexadecimal.

Example 1To create a user with a DN that contains a comma next to the separator:pdadmin sec_master> user create "johndoe""cn=doe\,john,cn=users,dc=mydomain,dc=com" John Doe password1

Example 2To create a user with a DN that contains a carriage return, which is areserved character:pdadmin sec_master> user create "johndoe""cn=doe\ODJohn,cn=users,dc=mydomain,dc=com" John Doe password1

The hexadecimal representation of a carriage return is 0D.

Example 3To create a user with a distinguished name that contains a number sign:pdadmin sec_master>user create "#pounduser""cn=\#pounduser,cn=users,dc=mydomain,dc=com" "#pound" "user"password1

Importing dynamic groups to Tivoli Access ManagerWhen importing an Active Directory group to Tivoli Access Manager, the TivoliAccess Manager group short name/ID (not including the @domain suffix whenTivoli Access Manager was configured to use Active Directory multiple domain)must be the same as the dynamic group cn. This requirement is to ensure that onlyone dynamic group can be mapped to a Tivoli Access Manager group object at anygive time.

For example, if you have an Active Directory group with cn = dyngroup1 anddistinguishedName = cn=dyngroup1,cn=AzGroupObjectContainer-myAuthorizationStore,cn=myAuthorizationStore,cn=ProgramData,dc-=domain,dc=com, the import command would be similar to one of the following:v Tivoli Access Manager configured to an Active Directory registry single domain

environment:pdadmin sec_master> group import dyngroup1"cn=dyngroup1, cn=AzGroupObjectContainer-myAuthorizationStore,cn=myAuthorizationStore,cn=Program Data,dc=domain,dc=com"

v Tivoli Access Manager configured to an Active Directory registry multipledomain environment:pdadmin sec_master> group import [email protected]"cn=dyngroup1,cn=AzGroupObjectContainer-myAuthorizationStore,cn=myAuthorizationStore,cn=Program Data,dc=domain,dc=com"

Enabling change user password requests to be performedusing LDAP APIs

Tivoli Access Manager can be configured to use LDAP APIs for user passwordchange requests in an environment that meets all of the following criteria:v Tivoli Access Manager is configured to use an Active Directory user registry.


v Blade servers communicate directly with the Active Directory server usingLDAP APIs.

To enable this functionality, use the pdadmin config modify command to updatethe change-pwd-using-ldap-api property in the [uraf-registry] stanza of theactivedir_ldap.conf configuration file.

Note: After you enable this option, the Policy Server does not need to beup-and-running to handle user change password requests.

The following lines show an example of how to enable the change user passwordvia LDAP APIs on Windows using Active Directory LDAP:pdadmin> login localpdadmin local> config modify keyvalue set"c:\Program Files\Tivoli\Policy Director\etc\activedir_ldap.conf""uraf-registry" "change-pwd-using-ldap-api" yes

The following lines show an example of how to enable the change user passwordvia LDAP APIs on for Active Directory LDAP on AIX:pdadmin> login localpdadmin local> config modify keyvalue set"/opt/PolicyDirector/etc/activedir_ldap.conf""uraf-registry" "change-pwd-using-ldap-api" yes

For more information, see change-pwd-using-ldap-api on page 318.

Enabling support for the use of email address or otheralternate format as user identity

Tivoli Access Manager can be configured to support the use of email address orother alternate format of the userPrincipalName attribute of the Active Directoryregistry user object for Access Manager user identity. This is an optionalenhancement; when it is enabled, both the default and the alternate format of theuserPrincipalName can co-exist in the Tivoli Access Manager environment.

For an existing Tivoli Access Manager environment, enabling this support allowsonly new Access Manager user identities to use the alternate format. ExistingAccess Manager user identities should not be modified.

To enable this support, use the pdadmin command utility to modify the registryconfiguration file.

The following example demonstrates how to use the pdadmin utility to enablesupport of alternate userPrincipalName natively for an Active Directoryenvironment:pdadmin> login localpdadmin local> config modify keyvalue set"c:\Program Files\Tivoli\Policy Director\etc\activedir.conf""uraf-registry" "use-email-as-user-id" yes

The following example demonstrates how to use the pdadmin utility to enablesupport of alternate userPrincipalName when using LDAP APIs on an AIX system:pdadmin> login localpdadmin local> config modify keyvalue set"/opt/PolicyDirector/etc/activedir_ldap.conf""uraf-registry" "use-email-as-user-id" yes


pdadmin local> config modify keyvalue set"/opt/PolicyDirector/etc/activedir_ldap.conf""uraf-registry" "ad-gc-server" adgc.hostname.com

Note that the ad-gc-server entry in the previous example is a multi-value property;if there are multiple Global Catalog servers, append them using the pdadminutility. For each additional Global Catalog server, use the config modify commandas in the previous example, but replace the set operation with append. Forexample:pdadmin> login localpdadmin local> config modify keyvalue append"/opt/PolicyDirector/etc/activedir_ldap.conf" "uraf-registry""ad-gc-server" adgc.hostname2.com

Novell-specific tasksThe Novell eDirectory can be configured for use as a Tivoli Access Manager userregistry. This section describes a few steps that are unique to this configuration.

Tasks to be performed include:v Updating the eDirectory schemav Novell eDirectory maintenance activities that can damage schema modifications

applied by Tivoli Access Manager

Updating the eDirectory schemaIf you are installing a new Tivoli Access Manager secure domain, the Tivoli AccessManager schema is installed on the Novell eDirectory Server (NDS) automaticallywhen the Tivoli Access Manager policy server is configured. However, prior toconfiguring the policy server, there are several modifications to Novell eDirectorythat must first be performed using Novell’s ConsoleOne directory managementutility or iManager web-based administration console.

Note: The default Novell eDirectory schema assumes that the directory does notuse the X.500 object classes of inetOrgPerson or groupOfNames. By default,these classes are mapped into the eDirectory classes of User and Group,respectively. Because Tivoli Access Manager uses the inetOrgPerson andgroupOfNames object classes for creating its own users and groups,modifications to the default eDirectory schema are required.

To update the eDirectory schema using the Novell eDirectory ConsoleOnedirectory management utility, complete the following steps:1. Start the Novell ConsoleOne directory management utility.2. Select the organization object within your Novell eDirectory tree. A list of

objects is displayed on the right side of the ConsoleOne window.3. Right click the LDAP group object (not LDAP server), and click Properties

from the menu.4. Click the Class Map tab and the table of LDAP class names. The Novell

eDirectory class names are displayed.5. Delete the entries with LDAP classes of inetOrgPerson and groupOfNames.6. Click Apply, and then click Close.7. Click the Attribute Map tab and the table of LDAP attribute names. The

Novell eDirectory attribute names are displayed.8. Scroll through the table and find the Novell eDirectory attribute member. Check

the value of the corresponding LDAP attribute. If the LDAP attribute value is


member, then no change is needed. If the attribute is showing the default valueof uniqueMember, you need to modify it as follows.v Click Modify. The Attribute Mapping window is displayed.v Change the Primary LDAP Attribute field from uniqueMember to member.v Change the Secondary LDAP attribute field from member to uniqueMember.v In the Attribute window, click OK to accept the changes.

9. If you are using Solaris, proceed to the next step. If you are using WindowsNT®, you might have to add another mapping for the LDAP attributendsHomeDirectory as follows:v On the right hand side of the Attribute Mappings window, click Add . The

Attribute Mapping window repaints and is displayed again.v From the Novell eDirectory NDS Attribute field menu, click Home

Directory.v In the Primary LDAP Attribute field, click ndsHomeDirectory.v In the Attribute Mapping window, click OK to accept the changes.

10. In the Properties window, click OK.

To update the eDirectory schema using the Novell iManager Web-basedadministration console, complete the following steps1. Launch the iManager Web page and log in as the administrator for the Novell

eDirectory tree to be updated.2. Click the Roles and Tasks icon at the top of the iManager window to open

the Roles and Tasks view.3. In the Roles and Tasks navigation frame, expand the LDAP category.4. In the expanded list, click the LDAP Options task.5. On the LDAP Options page, click the LDAP Group listed.6. Click Class Map to display the Novell eDirectory class to LDAP class

mappings.7. Remove mappings to inetOrgPerson and groupOfNames.

v Scroll through the list and look for mappings of eDirectory classes to theLDAP class inetOrgPerson.

v If a mapping exists, select the row and click the Remove Mapping icon toremove the mapping.

v Click OK in the pop-up window to confirm the removal of the mapping.v Click Apply to apply the changes.v Repeat this step to remove a mapping for the LDAP class groupOfNames.

8. Click OK, to accept the changes that have been made.9. Repeat steps 3-5 to return to the LDAP Group page.

10. Click Attribute Map to access the Novell eDirectory attribute to LDAPattribute mappings.

11. Scroll through the table and find the Novell eDirectory attribute member.Check the value of the corresponding LDAP attribute. If the LDAP attributevalue is member, no change is needed. If the attribute is showing the defaultvalue of uniqueMember, you need to modify it as follows:v Select the row and click the View/Edit Mapping icon.v Change the Primary LDAP Attribute field from uniqueMember to member.v Change the Secondary LDAP attribute field from member to uniqueMember.v Click OK in the pop-up window to confirm the change.


v Click Apply to apply the changes.12. If you are using Solaris, proceed to the next step. If you are using Windows

NT, you might have to add another mapping for the LDAP attributendsHomeDirectory. To add another mapping for the LDAP attributendsHomeDirectory:v Click the Add Mapping icon in the right side of the window. A pop-up

window to define the mapping is displayed.v In the eDirectory Attribute field, select Home Directory.v In the Primary LDAP Attribute field, type ndsHomeDirectory.v Click OK to confirm the mapping and close the pop-up window.

13. Click OK in the Attribute Map window to accept the changes.

Novell eDirectory maintenance activities that can damageschema modifications applied by Tivoli Access Manager

Novell eDirectory defines the object classes User and Group as part of its baseschema. Instances of these object classes are created by an eDirectory administratorwhen defining a user or a group, respectively. Both of these object classes aredefined by eDirectory as leaf nodes. eDirectory adds an attributeX-NDS_NOT_CONTAINER ’1’ to each of these object class definitions that specifies theyare not container objects. Not being a container object means that the objectscannot be defined beneath instances of these object classes.

Tivoli Access Manager requires the ability to append its own objects beneathpre-existing eDirectory users and groups in order to import them and make themusable by Tivoli Access Manager. When Tivoli Access Manager adds its own objectclass definitions to the eDirectory schema, it also redefines the eDirectory User andGroup object classes to allow instances of these classes to be container objects.Novell eDirectory allows this change to its schema definition.

The following Novell eDirectory administrator actions cause Tivoli Access Managermodification to the User object class to be undone. The Group object class is notaffected.v Running the eDirectory database repair tool ndsrepair using the rebuild schema

option.v Running Basic Repair from the iManager console and running local database

repair with the rebuild operational schema option.v Applying a patch update to Novell eDirectory.v Upgrading Novell eDirectory to a more recent version.

Should it be necessary to perform any of these operations after Tivoli AccessManager was configured into the eDirectory server, run the following commandimmediately to ensure that the definition of the User object class is restored.ivrgy_tool(.exe) -h edir_server_name -p port -D edir_admin_dn-w edir_admin_password schema

The ivrgy_tool utility can be found in one of the following Tivoli Access Managerdirectories:

Linux and UNIX operating systems/opt/PolicyDirector/sbin

Windows operating systemsc:\program files\tivoli\policy director\sbin


Tivoli Access Manager does not add the /sbin directory to the system PATH. Youmust run the ivrgy_tool utility from the /sbin directory.


Appendix G. Support information

This section describes the following options for obtaining support for IBMproducts:v “Searching knowledge bases”v “Obtaining fixes”v “Registering with IBM Software Support” on page 374v “Receiving weekly software updates” on page 374v “Contacting IBM Software Support” on page 375

Searching knowledge basesIf you encounter a problem, you want it resolved quickly. You can search theavailable knowledge bases to determine whether the resolution to your problemwas already encountered and is already documented.

Searching information centersIBM provides extensive documentation in an information center that can beinstalled on your local computer or on an intranet server. You can use the searchfunction of this information center to query conceptual information, instructionsfor completing tasks, reference information, and support documents.

Searching the InternetIf you cannot find an answer to your question in the information center, search theInternet for the latest, most complete information that might help you resolve yourproblem. To search multiple Internet resources for your product, perform thefollowing steps:1. Expand the product folder in the navigation frame on the left.2. Expand Troubleshooting and support.3. Expand Searching knowledge bases.4. Click Web search.

From this topic, you can search a variety of resources, which includes thefollowing resources:v IBM Technotesv IBM downloadsv IBM Redbooks®

v IBM developerWorks®

v Forums and news groupsv Google

Obtaining fixesA product fix might be available to resolve your problem. To determine what fixesare available for your IBM software product, check the product support site byperforming the following steps:1. Go to the IBM Software Support site at the following Web address:


http://www.ibm.com/software/support2. Under Products A - Z, click the letter with which your product starts to open a

Software Product List.3. Click your product name to open the product-specific support page.4. Under Self help, follow the link to All Updates, where you will find a list of

fixes, fix packs, and other service updates for your product. For tips on refiningyour search, click Search tips.

5. Click the name of a fix to read the description.6. Optional, download the fix.

Registering with IBM Software SupportBefore you can receive weekly e-mail updates about fixes and other news aboutIBM products, you need to register with IBM Software Support. To register withIBM Software Support, follow these steps:1. Go to the IBM Software Support site at the following Web address:

http://www.ibm.com/software/support2. Click Register in the upper right-hand corner of the support page to establish

your user ID and password.3. Complete the form, and click Submit.

Receiving weekly software updatesAfter registering with IBM Software Support, you can receive weekly e-mailupdates about fixes and other news about IBM products. To receive weeklynotifications, follow these steps:1. Go to the IBM Software Support site at the following Web address

http://www.ibm.com/software/support2. Click the My support link to open the Sign in page.3. Provide your sign in information, and click Submit to open your support page.4. Click the Edit profile tab.5. For each product about which you want to receive updates, use the filters to

choose your exact interests, and click Add products.6. Repeat step 5 for each additional product.7. After choosing all your products, click the Subscribe to email link.8. For each product category, use the filters and choose which updates you want

to receive, and click Update.9. Repeat step 8 for each additional product category.

For more information about the types of fixes that are available, see the IBMSoftware Support Handbook at the following Web address:

http://techsupport.services.ibm.com/guides/handbook.html


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



http://techsupport.services.ibm.com/guides/handbook.html

Contacting IBM Software SupportIBM Software Support provides assistance with product defects. Before contactingIBM Software Support, the following criteria must be met:v Your company has an active IBM software maintenance contract.v You are authorized to submit problems to IBM Software Support.

The type of software maintenance contract that you need depends on the type ofproduct that you have. Product types are one of the following categories:v For IBM distributed software products (including, but not limited to, Tivoli,

Lotus, and Rational® products, as well as DB2 and WebSphere products that runon Windows, Linux, or UNIX operating systems), enroll in Passport Advantage®

in one of the following ways:

OnlineGo to the IBM Software Passport Advantage site at the following Webaddress and click How to Enroll:

http://www.lotus.com/services/passport.nsf/WebDocs/Passport_Advantage_Home

By phoneFor the phone number to call in your country, go to the IBM SoftwareSupport site at the following Web address and click the name of yourgeographic region:

http://techsupport.services.ibm.com/guides/contacts.htmlv For IBM eServer™ software products (including, but not limited to, DB2 and

WebSphere products that run in System z®, pSeries®, and iSeries® environments),you can purchase a software maintenance agreement by working directly withan IBM sales representative or an IBM Business Partner. For more informationabout support for eServer software products, go to the IBM eServer TechnicalSupport Advantage site at the following Web address:

http://www.ibm.com/servers/eserver/techsupport.html

If you are not sure what type of software maintenance contract you need, call1-800-IBMSERV (1-800-426-7378) in the United States or, from other countries, go tothe contacts page of the IBM Software Support Handbook at the following Webaddress and click the name of your geographic region for phone numbers ofpeople who provide support for your location:

http://techsupport.services.ibm.com/guides/contacts.html

To contact IBM Software support, follow these steps:1. “Determining the business impact”2. “Describing problems and gathering information” on page 3763. “Submitting problems” on page 376

Determining the business impactWhen you report a problem to IBM, you are asked to supply a severity level.Therefore, you need to understand and assess the business impact of the problemthat you are reporting. Use the following severity criteria:

Appendix G. Support information 375




http://www.ibm.com/servers/eserver/techsupport.html


Severity 1The problem has a critical business impact. You are unable to use theprogram, resulting in a critical impact on operations. This conditionrequires an immediate solution.

Severity 2The problem has a significant business impact. The program is usable, butit is severely limited.

Severity 3The problem has some business impact. The program is usable, but lesssignificant features that are not critical are unavailable.

Severity 4The problem has minimal business impact. The problem causes little impacton operations, or a reasonable circumvention to the problem wasimplemented.

Describing problems and gathering informationWhen explaining a problem to IBM, be as specific as possible. Include all relevantbackground information so that IBM Software Support specialists can help yousolve the problem efficiently. To save time, know the answers to these questions:v What software versions were you running when the problem occurred?v Do you have logs, traces, and messages that are related to the problem

symptoms? IBM Software Support is likely to ask for this information.v Can you create the problem again? If so, what steps were performed to

encounter the problem?v Was any change made to the system? For example, were there changes to the

hardware, operating system, networking software, and so on.v Are you currently using a workaround for this problem? If so, please be

prepared to explain it when you report the problem.

Submitting problemsYou can submit your problem to IBM Software Support in one of two ways:

OnlineGo to the Submit and track problems page on the IBM Software Supportsite at the following address, and provide your information into theappropriate problem submission tool:


By phoneFor the phone number to call in your country, go to the contacts page ofthe IBM Software Support Handbook at the following Web address and clickthe name of your geographic region:


If the problem you submit is for a software defect or for missing or inaccuratedocumentation, IBM Software Support creates an Authorized Program AnalysisReport (APAR). The APAR describes the problem in detail. Whenever possible,IBM Software Support provides a workaround that you can implement until theAPAR is resolved and a fix is delivered. IBM publishes resolved APARs on theIBM product support Web pages daily, so that other users who experience thesame problem can benefit from the same resolution.




For more information about problem resolution, see “Searching knowledge bases”on page 373 and “Obtaining fixes” on page 373.

Appendix G. Support information 377

Appendix H. 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 inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct 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 itbelieves appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which was exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

TrademarksIBM, IBM logo, AIX, DB2, DB2 Universal Database, developerWorks, Domino,eServer, iSeries, Lotus, Passport Advantage, pSeries, Redbooks, SecureWay™, Tivoli,Tivoli logo, WebSphere, zSeries®, and z/OS are trademarks or registeredtrademarks of International Business Machines Corporation in the United States,other countries, or both.

Lotus and Domino are trademarks of International Business Machines Corporationand Lotus Development Corporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.


Other company, product, or service names may be trademarks or service marks ofothers.

Appendix H. Notices 381

Glossary

This glossary defines the technical terms andabbreviations that are used in Tivoli AccessManager. If you do not find the term orabbreviation for which you are looking, refer tothe IBM Terminology Web site at the followingWeb address:

http://www.ibm.com/ibm/terminology

The following cross-references are used amongterms:

Contrast withRefers the reader to a term that has anopposed or substantively differentmeaning.

See Refers the reader to a term that is theexpanded form of an abbreviation oracronym or to a synonym or morepreferred term.

See alsoRefers the reader to a related term.

ObsoleteIndicates that the term should not be usedand refers the reader to the preferredterm.

Aaccess control. In computer security, the process ofensuring that only authorized users can access theresources of a computer system in authorized ways.

access control list (ACL). In computer security, a listwith an object that identifies all the subjects that canaccess the object and their access rights. For example,an access control list is a list that is associated with afile that identifies the users who can access the file andidentifies the users' access rights to that file.

access decision information (ADI). The data andattributes that are used by the authorization engine toevaluate a rule. Authorization API attributes arename-value pairs, form the basis of all ADI that can bereferenced in a rule or presented to the authorizationengine.

access permission. The access privilege that applies tothe entire object.

account. Information about an identity.

ACL. See access control list.

ACL entry. Data in an access control list that specifiesa set of permissions.

ACL policy. Part of the security policy that containsACL entries that control who can access which domainresources and perform which actions. See alsoauthorization rule and protected object policy.

action. An access control list (ACL) permissionattribute. See also access control list.

action group. A set of actions that are explicitlyassociated with a resource or set of resources.

ADI. See access decision information.

ADK. See application development kit

administration service. An authorization API runtimeplug-in that can be used to perform administrationrequests on a Tivoli Access Manager resource managerapplication. The administration service responds toremote requests from the pdadmin command toperform tasks, such as listing the objects under aparticular node in the protected object tree. Customersmay develop these services using the authorizationADK.

application development kit (ADK). A set of tools,APIs, and documentation to assist with thedevelopment of software in a specific computerlanguage or for a particular operating environment.

attribute. A characteristic or trait of an entity thatdescribes the entity. An attribute can have a type,which indicates the range of information given by theattribute, and a value, which is within a range. In XML,for example, an attribute consists of a name-value pairwithin a tagged element and modifies a feature of anelement.

attribute list. A linked list that contains extendedinformation that is used to make authorizationdecisions. Attribute lists consist of a set of name-valuepairs.

audit event. A record of an operation in the audit logor change history; for example, an audit entry iscreated when a resource is modified.

audit level. The types of user actions that arecurrently being audited for the entire system or forspecific users on the system. Actions that can beaudited include authority failures and restoring objects.A record of each action is written to the audit journal.

audit trail. A chronological record of events thatenables the user to examine and reconstruct a sequence


http://www.ibm.com/software/globalization/terminology

of events. Audit trails are useful for managing securityand for recovering lost transactions.

audit trail file. The file that contains the audit trail.

authentication. In computer security, the process thatverifies identity. Authentication is distinct fromauthorization; authorization is concerned with grantingand denying access to resources. See also multi-factorauthentication, network-based authentication, andstep-up authentication.

authorization. In computer security, the process thatgrants or denies access to resources. Security uses atwo-step process: after authentication has verified theidentity, authorization allows the resource or processaccess to various resources based on its identity.

authorization API. The Tivoli Access Managercomponent that passes requests for authorizationdecisions from the resource manager to theauthorization evaluator. See also authorization serverand authorization service.

authorization evaluator. The decision-making processthat determines whether a client can access a protectedresource based on the security policy. The evaluatormakes its recommendation to the resource manager,which, in turn, responds accordingly.

authorization rule. Part of the security policy thatdefine conditions that are contained in authorizationpolicy. An authorization rule is used to make accessdecisions based on attributes such as user, application,and environment context. See also ACL policy andprotected object policy.

authorization server. The Tivoli Access Managercomponent that runs the authorization service. See alsoauthorization service.

authorization service. A dynamic or shared librarythat can be loaded by the authorization API runtimeclient at initialization time to perform operations thatextend a service interface in the Authorization API.

BBA. See basic authentication.

basic authentication. An authentication method thatverifies identity using a user name and password.

bind. To relate an identifier to another object in aprogram; for example, to relate an identifier to a value,to an address, or to another identifier or to associateformal parameters to actual parameters.

blade. A component that provides application-specificservices and components.

Boolean. A binary numbering system that is namedafter mathematician George Boole in which zero and

one are the only two values that can be returned; avalue of zero represents false while a value of onerepresents true.

business entitlement. The supplemental attribute of auser credential that describes the fine-grainedconditions that can be used in the authorizationprocess.

CCA. See certificate authority.

CDAS. Obsolete. See external authentication C API.

CDMF. See cross domain mapping framework.

certificate. In computer security, a digital documentthat binds a public key to the identity of the certificateowner, thereby enabling the certificate owner to beauthenticated. A certificate is issued by a certificateauthority.

certificate authority (CA). An organization that issuescertificates. A CA creates digital signatures andpublic-private key pairs. The CA guarantees theidentity of the individual who is granted the uniquecertificate and guarantees the services that the owner isauthorized to use, to issue new certificates, and torevoke certificates that belong to users andorganizations who are no longer authorized to use theservices. The role of the CA s to authenticate theentities (users and organizations) involved in electronictransactions. Because the CA guarantees that the twoparties that are exchanging information are really whothey claim to be, the CA is a critical component in datasecurity and electronic commerce.

CGI. See common gateway interface.

cipher. A cryptographic algorithm that is used toencrypt data that is unreadable until it is converted intoplain data (decrypted) with a predefined key.

common gateway interface (CGI). An Internetstandard for defining scripts that pass information froma Web server to an application program, through anHTTP request, and vice versa. A CGI script is a CGIprogram that is written in a scripting language, such asPerl.

configuration. The manner in which the hardwareand software of a system, subsystem, or network areorganized and interconnected.

connection. (1) In data communication, an associationestablished between functional units for conveyinginformation. (2) In TCP/IP, the path between twoprotocol applications that provides reliable data streamdelivery service. In the Internet, a connection extendsfrom a TCP application on one system to a TCPapplication on another system. (3) In system


communication, a line over which data can be passedbetween two systems or between a system and adevice.

console log agent. A log agent that writes events tostandard error or standard output. See also file logagent, pipe log agent, and remote log agent.

container object. A structural designation thatorganizes the object space into distinct functionalregions.

cookie. Information that a server stores on a clientmachine and accesses during subsequent sessions.Cookies allow servers to remember specific informationabout clients.

credentials. Detailed information, acquired duringauthentication, that describes the user, any groupassociations, and other security-related identityattributes. Credentials can be used to perform amultitude of services, such as authorization, auditing,and delegation.

credentials modification service. An authorizationAPI runtime plug-in which can be used to modify aTivoli Access Manager credential. Credentialsmodification services developed externally bycustomers are limited to performing operation to addand remove from the credentials attribute list and onlyto those attributes that are considered modifiable.

cross domain authentication service (CDAS).Obsolete. See external authentication C API.

cross domain mapping framework (CDMF). Aprogramming interface that allows a developer tocustomize the mapping of user identities and thehandling of user attributes when WebSEALe-Community SSO function are used.

Ddaemon. A system process that runs unattended toperform continuous or periodic system-wide functions,such as network control. See also service.

data store. A storage area for data, such as a databasesystem, directory, or file.

delegate. A user who is authorized to work foranother user. The authorization can be made by a useror by an administrator.

demilitarized zone (DMZ). In network security, acomputer or network that uses a firewall to be isolatedfrom, and to serve as a neutral zone between, a trustednetwork (for example, a private intranet) and anuntrusted network (for example, the Internet). One ormore secure gateways usually control access to theDMZ from the trusted or the untrusted network.

digital signature. Information that is encrypted with aprivate key and is appended to a message to assure therecipient of the authenticity and integrity of themessage. The digital signature proves that the messagewas signed by the entity that owns, or has access to,the private key or shared secret symmetric key.

directory schema. The valid attribute types and objectclasses that can appear in a directory. The attributetypes and object classes define the syntax of theattribute values, which attributes are required, andwhich attributes are optional.

distinguished name (DN). (1) The name that uniquelyidentifies an entry in a directory. A distinguished nameis made up of an attribute-value pairs, separated bycommas. (2) A set of name-value pairs (such ascn=common name and c=country) that uniquelyidentifies an entry in a digital certificate.

DMZ. See demilitarized zone.

DN. See distinguished name.

domain. (1) A logical grouping of resources in anetwork that share common administration andmanagement. (2) A part of a network that isadministered with a common protocol. See also domainname.

domain administrator. The administrator for adomain who can assign any of the roles in that domainto subdomains. After assigning roles to subdomains,administrators in that subdomain can assignsubdomain users these roles.

domain name. In the Internet suite of protocols, thename of a host system. A domain name consists of asequence of subnames that are separated by a delimitercharacter. For example, if austin.ibm.com is the fullyqualified domain name (FQDN) of a host system, bothaustin.ibm.com and ibm.com® are domain names.

dynamic group. A group that is defined using asearch expression. When an attribute is added to adirectory entry that causes it to match the searchexpression, the entry automatically becomes a memberof the group.

EEAS. See external authorization service.

encryption. In computer security, the process oftransforming data into a cipher.

entitlement. A data structure that containsexternalized security policy information. Entitlementscontain policy data or capabilities that are formatted ina way that is understandable to a specific application.

entitlement service. An authorization API runtimeplug-in which can be used to return entitlements from

Glossary 385

an external source for a principal or set of conditions.Entitlements are normally application specific data thatwill be consumed by the resource manager applicationin some way or added to the principal's credentials foruse further on in the authorization process. Customersmay develop these services using the authorizationADK.

entity. In object-oriented design, an item that can betreated as a unit and, often, as a member of a particularcategory or type. An entity can be concrete or abstract.

event. Any significant change in the state of a systemresource, network resource, or network application. Anevent can be generated for a problem, for the resolutionto a problem, or for the successful completion of a task.

event pool. A set of events recognized by an activity.Each activity has its own event pool. The event pool isinitialized when the activity is created and is deletedwhen the activity is deleted.

extended attribute. Additional information that thesystem or a program associates with an object. Anextended attribute can be any format, such as text, abitmap, or binary data.

external authentication C API. A C API that enablesyou to write custom authentication modules thatreplace or extend the functionality of the built–inauthentication process. The identity information isreturned through the authentication module interface.Contrast with external authentication HTTP interface.

external authentication HTTP interface. An interfacethat enables you to extend the functionality of thebuilt-in authentication process to allow a remote serviceto handle the authentication process. The identityinformation in the HTTP response headers is used togenerate user credentials. Contrast with externalauthentication C API.

external authorization service (EAS). Anauthorization API runtime plug-in that can be used tomake application- or environment-specific authorizationdecisions as part of the authorization decision chain.Customers can develop these services using theauthorization ADK.

Extensible Markup Language (XML). A standardmeta-language for defining markup languages that isbased on Standard Generalized Markup Language(SGML).

Extensible Stylesheet Language (XSL). A language forspecifying style sheets for XML documents. XSLTransformation (XSLT) is used with XSL to describehow an XML document is transformed into anotherdocument. See also Extensible Stylesheet LanguageTransformation.

Extensible Stylesheet Language Transformation(XSLT). An XML processing language that is used toconvert an XML document into another document inXML, PDF, HTML, or other format. See also ExtensibleStylesheet Language.

Ffile log agent. A log agent that writes events to a file.See also console log agent, pipe log agent, and remotelog agent.

file transfer protocol (FTP). In the Internet suite ofprotocols, a protocol that can use Transmission ControlProtocol (TCP) and Telnet services to transfer filesbetween machines.

FTP. See file transfer protocol

Gglobal sign-on (GSO). A flexible single sign-onsolution that enables the user to provide alternativeuser names and passwords to the back-end Webapplication server. Through a single login, globalsign-on grants users access to the computing resourcesthey are authorized to use. Designed for largeenterprises consisting of multiple systems andapplications within heterogeneous, distributedcomputing environments, GSO eliminates the need forusers to manage multiple user names and passwords.See also single sign-on.

group. A named list of users by which access levels tocorporate directories, databases, and servers areassigned. Two or more individual users who arecategorized for the purpose of assigning databasesecurity settings; for example, administrators mustassign individuals to groups before assigning roles.

GSO. See global sign-on.

Hhost. A computer that is connected to a network andprovides an access point to that network. The host canbe a client, a server, or both a client and a serversimultaneously.

HTTP. See hypertext transfer protocol.

hypertext transfer protocol (HTTP). In the Internetsuite of protocols, the protocol that is used to transferand display documents.

Iinheritance. An object-oriented programmingtechnique that allows the use of existing classes as abasis for creating other classes.


Internet protocol (IP). In the Internet suite ofprotocols, a connectionless protocol that routes datathrough a network or interconnected networks. IP actsas an intermediary between the higher protocol layersand the physical network.

Internet suite of protocols. A set of protocolsdeveloped for use on the Internet and publishedthrough the Internet Engineering Task Force (IETF).

interprocess communication (IPC). (1) The process bywhich programs communicate data to each other andsynchronize their activities. Semaphores, signals, andinternal message queues are common methods ofinterprocess communication. (2) A mechanism of anoperating system that allows processes to communicatewith each other within the same computer or over anetwork.

IP. See Internet protocol.

IPC. See interprocess communication.

Jjunction. A logical connection that is created toestablish a path from one server to another.

KKDC. See key distribution center.

Kerberos. An authentication system that enables twoparties to exchange private information over anotherwise open network. It works by assigning aunique key, called a ticket, to each user that logs on tothe network. The ticket is then embedded in messagesthat are sent over the network. The receiver of amessage uses the ticket to authenticate the sender.

Kerberos ticket. A transparent application mechanismthat transmits the identity of an initiating principal toits target. A simple ticket contains the identity, a sessionkey, a timestamp, and other information that is sealedusing a secret key.

key. In computer security, a sequence of symbols thatis used with a cryptographic algorithm for encryptingor decrypting data. See private key and public key.

key database file (KDC). See key file.

key distribution center. In the Kerberos protocol, thecentral server, which includes the authentication serverand the ticket-granting server. The KDC is sometimesreferred to as the Kerberos server.

key file. In computer security, a file that containspublic keys, private keys, trusted roots, and certificates.

key pair. In computer security, a public key and aprivate key. When the key pair is used for encryption,

the sender uses the public key to encrypt the message,and the recipient uses the private key to decrypt themessage. When the key pair is used for signing, thesigner uses the private key to encrypt a representationof the message, and the recipient uses the public key todecrypt the representation of the message for signatureverification. Because the private key holds more of theencryption pattern than the public key, the key pair iscalled asymmetric.

key ring. See key file.

keystore file. A key file that contains both public keysstored as signer certificates and private keys stored inpersonal certificates.

keytab file. See key table.

key table. In the Kerberos protocol, a file that containsservice principal names and secret keys. The secret keysshould be known only to the services that use the keytable file and the key distribution center (KDC).

key-value pair. Information that is expressed as apaired set.

LLDAP. See lightweight directory access protocol.

leaf node. A node that has no children before it in thedirectory tree.

lightweight directory access protocol (LDAP). Anopen protocol that uses TCP/IP to provide access todirectories that support an X.500 model and that doesnot incur the resource requirements of the morecomplex X.500 Directory Access Protocol (DAP). Forexample, LDAP can be used to locate people,organizations, and other resources in an Internet orintranet directory.

lightweight third party authentication (LTPA). Anauthentication protocol that users cryptography tosupport security across a set of Web servers in adistributed environment.

LTPA. See lightweight third party authentication.

Mmanagement domain. The default domain in whichTivoli Access Manager enforces security policies forauthentication, authorization, and access control. Thisdomain is created when the policy server is configured.See also domain.

management interface. The interface that a domainadministrator can use to manage security policy. InTivoli Access Manager, an administrator can use WebPortal Manager or the pdadmin commands to applysecurity policy to resources.

Glossary 387

management server. Obsolete. See policy server.

master server. In a network environment, the serverthat has permissions to run commands on all othermachines in the environment. The master server isdesigned to manage the network, clients, and resourceobjects in the network database. Contrast with replicaserver

metadata. Data that describes the characteristics ofstored data.

migration. The installation of a new version or releaseof a program to replace an earlier version or release.

MPA. See multiplexing proxy agent.

multi-factor authentication. A protected object policy(POP) that forces a user to authenticate using two ormore levels of authentication. For example, the accesscontrol on a protected resource can require that theusers authenticate with both user name/password anduser name/token passcode.

multiple tenancy server. A server that permits thehosting of multiple customers on a single server insteadof multiple client machines. See also protected objectpolicy.

multiplexing proxy agent (MPA). A gateway thataccommodates multiple client access. These gatewaysare sometimes known as Wireless Access Protocol(WAP) gateways when clients access a secure domainusing a WAP. Gateways establish a single authenticatedchannel to the originating server and tunnel all clientrequests and responses through this channel.

Nnamespace. (1) In XML, a uniform resource identifier(URI) that provides a unique name to associate with allthe elements and type definitions in a schema. (2)Space reserved by a file system to contain the names ofits objects.

network-based authentication. A protected objectpolicy (POP) that controls access to objects based on theInternet protocol (IP) address of the user. See alsoprotected object policy.

notification thread. The synchronization mechanismthat the policy server uses to inform all databasereplicas of a change to the master policy database.

Oobject. (1) In object-oriented design or programming,a concrete realization (instance) of a class that consistsof data and the operations associated with that data.An object contains the instance data that is defined bythe class, but the class owns the operations that areassociated with the data. (2) Any digital content that a

user can manipulate as a single unit and perform atask. An object can appear as text, an icon, or both. (3)A named storage space that consists of a set ofcharacteristics that describe the space and, in somecases, data. An object is anything that occupies space instorage, can be located in a library or directory, can besecured, and on which defined operations can beperformed. Some examples of objects are programs,files, libraries, and stream files.

object space. A virtual representation of the resourcesto be protected. See also namespace.

object type. A categorization or group of objectinstances that share similar behavior and characteristics.

PPAC. See privilege attribute certificate.

PDCA. See Policy Director Certificate Authority

permission. The ability to access a protected object,such as a file or directory. The number and meaning ofpermissions for an object are defined by the accesscontrol list (ACL). See also access control list.

pipe log agent. A log agent that writes events asstandard input to another program. See also console logagent, file log agent, and remote log agent.

policy. A set of rules that are applied to managedresources.

policy database. The database that contains thesecurity policy information for all resources in thedomain. Each domain has its own policy database.

Policy Director Certificate Authority (PDCA). Atrusted certificate that is created during theconfiguration of the policy server and that is used tosign all other Tivoli Access Manager certificates. APDCA certificate is stored in the master policydatabase.

policy enforcer. A component of a resource managerthat directs requests to the authorization service forprocessing after authorization is granted. Traditionalapplications bundle the policy enforcer and theresource manager as one process.

policy server. The Tivoli Access Manager componentthat maintains the master policy database, replicatesthis policy information throughout the secure domain,and updates database replicas whenever a change ismade to the master policy database. The policy serveralso maintains location information about other TivoliAccess Manager and non-Tivoli Access Managerresource managers that are operating in the securedomain.


polling. The process by which databases areinterrogated at regular intervals to determine if dataneeds to be transmitted.

POP. See protected object policy.

portal. A single point of access to diverse informationand applications. Users can customize and personalizea portal.

principal. (1) An entity that can communicate securelywith another entity. (2) An authenticated user. Aprincipal is identified by its associated security context,which defines its access rights.

private key. In computer security, a key that is knownonly to its owner. Contrast with public key.

privilege attribute certificate (PAC). A digitaldocument that contains a principal's authentication andauthorization attributes and a principal's capabilities.

privilege attribute certificate service. Anauthorization API runtime client plug-in whichtranslates a PAC of a predetermined format in to aTivoli Access Manager credential, and vice-versa. Theseservices could also be used to package or marshall aTivoli Access Manager credential for transmission toother members of the secure domain. Customers maydevelop these services using the authorization ADK.See also privilege attribute certificate.

protected object. The logical representation of anactual system resource that is used for applying ACLsand POPs and for authorizing user access. See alsoprotected object policy and protected object space.

protected object policy (POP). A type of securitypolicy that imposes additional conditions on theoperation permitted by the ACL policy to access aprotected object. It is the responsibility of the resourcemanager to enforce the POP conditions. See also ACLpolicy, authorization rule, protected object, andprotected object space.

protected object space. The virtual objectrepresentation of actual system resources that is usedfor applying ACLs and POPs and for authorizing useraccess. See also protected object and protected objectpolicy.

proxy server. A server that receives requests intendedfor another server and that acts on behalf of a client toobtain the requested service. A proxy server is oftenused when the client and the server are incompatiblefor direct connection. For example, a client cannot meetthe security authentication requirements of the serverbut should be permitted some services.

public key. In computer security, a key that is madeavailable to everyone. Contrast with private key.

Qquality of protection. The level of data security,determined by a combination of authentication,integrity, and privacy conditions.

Rrecord. (1) The storage representation of a single rowof a table or other data in a database. (2) A group ofrelated data, words, or fields treated as a unit.

registry. The datastore that contains access andconfiguration information for users, systems, andsoftware.

remote cache mode. An operational mode in which aresource manager uses the functions that are providedby the authorization API to communicate to the remoteauthorization server.

remote log agent. A log agent that sends events to aremote server for recording. See also console log agent,file log agent, and pipe log agent.

replica server. A server that contains a copy of thedirectory or directories of another server. Replicas backup master servers or other replica servers to enhanceperformance or response times and to ensure dataintegrity. Contrast with master server.

resource. A hardware, software, or data entity that ismanaged.

resource group. A group of resources that can includebusiness objects such as contracts or a set of relatedcommands. In access control policies, resource groupsspecify the resource to which the policy authorizesaccess.

resource manager. (1) An application, program, ortransaction that manages and controls access to sharedresources, such as memory buffers and data sets. (2)Any server or application that uses the authorizationAPI to process client requests for access to resources.

resource object. The representation of an actualnetwork resource, such as a service, file, and program.

response file. An ASCII file that can be customizedwith the setup and configuration data that automatesan installation. The setup and configuration data has tobe entered during an interactive installation, but withthe response file, the installation can proceed withoutuser interaction. See also silent installation.

role. A definition of the access permissions that a useror process has and the specific resources that the useror process can modify at those levels. Users andprocesses are limited in how they can access resourceswhen that user or process does not have theappropriate role.

Glossary 389

role activation. The process of applying accesspermissions to a role.

role assignment. The process of assigning a role to auser, such that the user has the appropriate accesspermissions for the object defined for that role.

root container object. The top-level container object inthe hierarchy or resource objects.

root domain. Name servers that have authoritativecontrol of all the top-level domains.

routing file. An ASCII file that contains commandsthat control the configuration of messages.

routing table. A collection of path informationthrough which hosts or networks can communicatewith each other.

RSA. A public-key encryption technology that wasdeveloped by RSA Data Security, Inc., and used byGSKit. The acronym stands for Rivest, Shamir, andAdleman, the inventors of this encryption technique.

RSA encryption. A system for public-keycryptography used for encryption and authentication.The security of the system depends on the difficulty offactoring the product of two large prime numbers.

rule. A set of logical statements that enable a server torecognize relationships among events and to performautomated responses accordingly.

rules evaluator. The component responsible forevaluating an authorization rule.

run time. The time period during which a computerprogram is running.

runtime environment. A subset of an applicationdevelopment kit (ADK) that contains the executablefiles and other supporting files that comprise theoperational environment of the platform.

Sscalability. The ability of hardware, software, or adistributed system to maintain performance levels as itincreases in size and increases in the number of userswho access resources.

schema. The set of statements, expressed in a datadefinition language, that completely describes thestructure of data that is stored in a database, directory,or file.

Secure Sockets Layer (SSL). A security protocol thatprovides communication privacy. SSL enablesclient/server applications to communicate in a way thatis designed to prevent eavesdropping, tampering, andmessage forgery.

security context. The digitally signed token thatidentifies a principal, lists the roles and access rightsfor the principal, and contains information about whenthe token expires.

security management. The software discipline thataddresses how an organization can control access tomission critical applications and data.

security policy. (1) A written document that definesthe security controls that you institute for yourcomputer systems. A security policy describes the risksthat you intend to minimize and the actions thatshould be taken if someone breaches your securitycontrols. (2) In Tivoli Access Manager, the combinationof ACL policies, authorization rules, and protectedobject policies attached to objects to make themprotected objects. See also ACL policy, authorizationrule, and protected object policy.

self-registration. The process by which a user canenter required data and become a registered userwithout the involvement of an administrator.

service. Work performed by a server. A service can bea simple request for data to be sent or stored (as withfile servers, HTTP servers, or e-mail servers), or it canbe for more complex requests (as with print servers orprocess servers). See also daemon.

session. A series of requests to a server or applicationthat originate from the same user at the same browser.

silent installation. An installation that does not sendmessages to the console but instead stores messagesand errors in log files. Also, a silent installation can useresponse files for data input. See also response file.

single sign-on (SSO). The mechanism that allows auser to logon once and access multiple applicationsthrough a single authorization challenge. Using SSO, auser does not need to log on to each applicationseparately. See also global sign-on.

SSL. See Secure Socket Layer.

SSO. See single sign-on.

stanza. A group of lines in an ASCII file that togetherhave a common function or define a part of a system.Stanzas are usually separated by blank lines or colons,and each stanza has a name.

stash file. The local copy of the master key file thatresides in an encrypted format on the local disk.

step-up authentication. A protected object policy(POP) that relies on a preconfigured hierarchy ofauthentication levels and enforces a specific level ofauthentication according to the policy set on a resource.The step-up authentication POP does not force the userto authenticate using multiple levels of authenticationto access any given resource, but it requires the user to


authenticate at a level at least as high as that requiredby the policy protecting a resource. See also protectedobject policy.

suffix. A distinguished name that identifies the topentry in a locally held directory hierarchy. Because ofthe relative naming scheme used in LightweightDirectory Access Protocol (LDAP), this suffix applies toevery other entry within that directory hierarchy. Adirectory server can have multiple suffixes, eachidentifying a locally held directory hierarchy.

Tticket. See Kerberos ticket.

token. A sequence of bits (symbol of authority) that ispassed successively along a transmission medium fromone device to another to indicate the device that istemporarily in control of the transmission medium.Each device can acquire and use the token to controlthe medium.

trusted root. In the Secure Sockets Layer (SSL), thepublic key and associated distinguished name of acertificate authority (CA). See also Secure Socket Layer.

Uuniform resource identifier (URI). The characterstring used to identify an abstract or physical resourceon the Internet. A URI typically describes how to accessthe resource, the computer that contains the resource,and the name of the resource. The most common formof URI is the Web page address, which is a particularsubset or URI called uniform resource locator (URL).See also uniform resource locator.

uniform resource locator (URL). A character stringthat represent resources on a computer or in a network,such as the Internet. The URL includes the abbreviatedname of the protocol used to access the informationresource and the information used by the protocol tolocate the resource.

URI. See uniform resource identifier.

URL. See uniform resource locator.

user. Any person, organization, process, device,program, protocol, or system that uses a serviceprovided by others.

user registry. See registry.

Vvirtual hosting. The capability of a Web server thatallows it to appear as more than one host to theInternet.

WWeb Portal Manager (WPM). A Web-based graphicalapplication used to manage Tivoli Access Managersecurity policy in a secure domain. An alternative tothe pdadmin command line interface, this GUI enablesremote administrator access and enables administratorsto create delegated user domains and assign delegateadministrators to these domains.

Web resource. Any one of the resources that arecreated during the development of a Web application;for example, Web projects, HTML pages, JSP files,servlets, custom tag libraries, and archive files.

WebSEAL. A high performance, multi-threaded Webserver that applies a security policy to a protectedobject space. WebSEAL can provide single sign-onsolutions and incorporate back-end Web applicationserver resources into its security policy.

Web session. See session.

WPM. See Web Portal Manager.

XXML. See Extensible Markup Language.

XML transform. A standard that uses XSL stylesheetsto transform XML documents into other XMLdocuments or fragments or to transform XMLdocuments into HTML documents.

XSL. See Extensible Stylesheet Language.

XSL stylesheet. Code that describes how an XMLdocument should be rendered (displayed or printed).

XSLT. See Extensible Stylesheet LanguageTransformation.

Glossary 391

Index

Special charactersAttributeName entry 327policy-trigger entry 230service-id entry

aznapi-admin-services stanza 215service-id entry

aznapi-cred-modification-services stanza 227aznapi-entitlement-services stanza 229aznapi-pac-services stanza 232

Aaccess control list

See ACLsaccess control lists

See ACLsaccess decision information

See ADIaccessibility xiiiaccessmanager.gif file 28accountability 4accounts, user and group 145acl commands

attach 88create 84delete 90detach 89find 89list 85list attribute 94modify 85, 90, 91, 92modify delete attribute 95modify set attribute

creating extended attributes 93modifying extended attributes 93

show 85, 86, 90, 91, 92show attribute 94

ACL entriescreating for ACL policy 90custom permissions 81default permissions 80definition 78ID attribute 79modifying permissions 91permissions attribute 79removing from ACL policy 91representation of custom permissions 82type attribute 79

ACL policiesattaching 88cloning 86creating 84creating ACL entries 90definition 77definition of 37deleting 89detaching 88evaluating 39explicit 50

ACL policies (continued)exporting

all 86multiple 87one 87

extended attributescreating 92deleting 94deleting values 95listing 93modifying 93

finding 89importing 86inheritance 50listing 85management tasks 83modifying description 84modifying entry permissions 91operations on an object 38policies 38purpose

security considerations 77removing ACL entries 91versus authorization rules 40viewing 85viewing extended attributes 94

ACL policies, defining 11ACL policy

definition of 12ACL policy administrator 43aclMembership entry 297ACLs 45

ACL entries 78ACL policies 77applying policies to different object types 50control permission 48default administration ACL 51default config ACL 52default domain ACL 53default GSO ACL 52default management ACL 52default policy ACL 52default proxy ACL 53default replica ACL 52default root ACL 51explicit versus inherited 47group management policies 191management permissions 53managing 77managing ACL permissions 53resolving request 49user management policies 192

action bitsSee permissions

action commandscreate 98delete 98group create 96group delete 97group list 96list 98


action create command 98action delete command 98action group commands

create 96delete 97list 96

action group create command 96action group delete command 97action group list command 96action groups

creating 96creating new permissions 97custom 81custom scenario 82deleting 97deleting permissions 98guidelines 95listing 96listing permissions 98management tasks 95primary group 80when to create 81

action list command 98actions

See also permissionsmanaging Action permissions 54

Active Directoryenabling dynamic groups 158

Active Directory serveractivedir.conf 207configuration file with LDAP client 207

activedir_ldap.conf configuration file 207activedir.conf configuration file 207, 208ad-gc-port entry 325ad-gc-server entry 325ADI

containers and container names 123definition of 119determining what is missing 136dynamic retrieval entitlement services 136name/value pair attributes 124request from the resource manager 133, 135retrieval entitlements service 121source 121XML document model 122XML document model restriction 123

administrationdelegate role 185enterprise domain 183multiple domains 184roles 185superdomain 183

administration ACL (default) 51administration API 4administration groups 187administration users

creating 43administration users and groups

defaults 43administrator

multiple domains 184superdomain 183tasks 186

administratorsadministrator 184domain 184enterprise domain 183

administrators (continued)predefined 184sec_master 183senior 184support 185Tivoli Access Manager 184types 184

algorithm, network-based authorization 110allowed registry substring 181allowed-registry-substrings entry 248amconf.properties configuration file 208any-authenticated type attribute

See any-otherany-other

adding ACL entry to ACL policy 90authenticated requests 39modifying permissions 91removing ACL entries from ACL policies 91type attribute 79unauthenticated requests 39

any-other user 38app_context attribute list 120application context information 120applying ACL policies 50attribute lists

app_context 120permission_info-returned 135

attribute name, XML 124attribute pairs (name/value) 119attributes

ACL ID 79ACL permissions 79ACL type 79azn_cred_groups 131azn_cred_principal_name 131azn_cred_registry_id 131azn_engine_requested_actions attribute 120azn_engine_target_resource 120azn_init_set_perminfo_attrs 133azn_perminfo_reason_rule_failed 135azn_perminfo_rules_adi_request 133, 136POPs 101

audit-attribute entry 217auditevent entry 244auditing

disabling, common audit service 234enabling, common audit service 234

auditing events 197auth-using-compare entry 265authenticated

authenticated requests 39unauthenticated requests 39

authenticated requests 39authentication

applying step-up policy 115configuring levels of step-up 115introduction 2levels 114multi-factor authentication 116step-up 114

authentication-mechanisms stanzacert-ldap entry 212cert-uraf entry 213description 211passwd-ldap entry 213passwd-uraf entry 214

authMethod entry 297


authn-timeout entry 266authorization

evaluation process 18introduction 2step-by-step process 13

authorization APIintroducing 14local cache mode 16remote cache mode 15standard 5

authorization API attributes 119authorization database

replicating 174authorization evaluator

overview 9authorization model

conceptual model 6authorization policy database 9Authorization rule language

languages 122authorization rules 13

attaching to an object 142changing 139cloning 140creating 138definition of 37deleting 144delimiters 128detaching 143differing from ACL policies and POPs 40evaluator 128examples

ADI from dynamic ADI retrieval services 132ADI from entitlement data 131ADI from resource manager 131

exportingall 141multiple 141one 141

finding 143Format and constraints 129importing 140listing 140management tasks 119, 137managing rule permissions 58modifying 139overview 119policies 40policies for 46when to use 41

authorization serverconfiguration file 205ivacld.conf 205key and stash files 161pdacld server process 167preventing automating startup 173starting 170

authorization service 6authorization API 10benefits 7extending 17interfaces 10overview 8, 9

authorize-group-list entry 247authzrule attach command 142authzrule commands

attach 142

authzrule commands (continued)create 139delete 144detach 143find 143list 140modify 139

authzrule create command 139authzrule delete command 144authzrule detach command 143authzrule find command 143authzrule list command 140authzrule modify command 139auto-database-update-notify entry 174, 255automatic certificate and password refresh 161azn_cred_groups attribute 131azn_cred_principal_name attribute 131azn_cred_registry_id attribute 131azn_decision_access_allowed_ext () method 120azn_decision_access_allowed_ext() method 135azn_decision_access_allowed() method 133azn_engine_requested_actions attribute 120azn_engine_target_resource attribute 120azn_entitlement_get_entitlements() call 136azn_entitlement_get_entitlements() method 129azn_init_set_perminfo_attrs attribute 133azn_init_set_perminfo_attrs initialization parameter 135azn_perminfo_reason_rule_failed attribute 135azn_perminfo_rules_adi_request attribute 133, 136azn-app-host entry 218azn-server-name entry 218aznapi-admin-services stanza

service-id entry 215description 215

aznapi-configuration stanzaaudit-attribute entry 217azn-app-host entry 218azn-server-name entry 218cache-refresh-interval entry 219cred-attributes-entitlement-services entry 219db-file entry 220description 217dynamic-adi-entitlement-services entry 221input-adi-xml-prolog entry 221listen-flags entry 222logcfg entry 222mode entry 223pd-user-name entry 224pd-user-pwd entry 224permission-info-returned entry 224policy-cache-size entry 225resource-manager-provided-adi entry 225xsl-stylesheet-prolog entry 226

aznapi-cred-modification-services stanzaservice-id entry 227description 227

aznapi-entitlement-services stanzaservice-id entry 229description 228

aznapi-external-authzn-services stanzapolicy-trigger entry 230description 230

aznapi-pac-services stanzaservice-id entry 232description 231

aznAPI.conf configuration file 209

Index 395

BbannerFile entry 298bassslcfg -config command 165benefits of authorization service 7bind-dn entry 266bind-id entry 309books

see publications ix, xiiboot-start-ivacld command 173boot-start-ivacld entry 294boot-start-ivmgrd command 173boot-start-ivmgrd entry 294boot-start-pdmgrproxyd command 174boot-start-pdproxyd entry 295

CCA

See certificate authorityca-cert-download-enabled entry 256cache-database entry 290cache-enabled entry

ldap stanza, ivacld.conf 267ldap stanza, ivmgrd.conf 267ldap stanza, ldap.conf 278ldap stanza, pdmgrproxyd.conf 267

cache-group-expire-time entry 267cache-group-membership entry 268cache-group-size entry 268cache-lifetime entry 309cache-mode entry 309cache-policy-expire-time entry 269cache-policy-size entry 269cache-refresh-interval entry 219cache-return-registry-id entry 270cache-size entry 310cache-use-user-cache entry 270cache-user-expire-time entry 271cache-user-size entry 271CARS

See common audit servicecars-client stanza

clientPassword entry 235clientUserName entry 235compress entry 233description 233diskCachePath entry 233doAudit entry 234errorFilePath entry 235flushInterval entry 236hiWater entry 237keyFilePath entry 236lowWater entry 237maxCacheFiles entry 237maxCacheFileSize entry 238maxErrorFiles entry 238maxErrorFileSize entry 238maxTraceFiles entry 239maxTraceFileSize entry 239numberCMThreads entry 239numberEQThreads entry 240numberRetries entry 240queueSize entry 240rebindInterval entry 241retryInterval entry 241serverURL entry 241

cars-client stanza (continued)stashFilePath entry 242traceFilePath entry 242traceLevel entry 242transferSize entry 243useDiskCache entry 243

cars-filterdescription 244

cars-filter stanzaauditevent entry 244

centralized management 4cert-ldap entry 212cert-uraf entry 213certificate authority

See also CAdefinition 159determining trust 162

certificatesautomatic refresh 161FTP 164initial configuration 160management tasks 159revocation 164update utilities 161

change-pwd-using-ldap-api entryuraf-registry stanza, activedir_ldap.conf 318

changePassword entry 298chgcert option of svrsslcfg command 164clientPassword entry 235clientUserName entry 235cloning

POPs 106commands

acl attach 88acl create 84acl delete 90acl detach 89acl find 89acl list 85acl list attribute 94acl modify 85, 90, 91, 92acl modify delete attribute 95acl modify set attribute

creating extended attributes 93modifying extended attributes 93

acl show 85, 86, 90, 91, 92acl show attribute 94action create 98action delete 98action group create 96action group delete 97action group list 96action list 98authzrule attach 142authzrule create 139authzrule delete 144authzrule detach 143authzrule find 143authzrule list 140authzrule modify 139bassslcfg -config 165config modify 158domain create 62domain delete 64domain list 63domain modify 63group create 155, 157


commands (continued)group create command 190group import 157group list 156, 193group list-dn 193login 61object create 72object create command 189object delete 75object list 73objectspace create 66objectspace delete 69objectspace list 67pdadmin group import 156policy set

all users 153single user 151

pop attach 108pop create 104pop delete 109pop detach 109pop find 109pop list 105pop modify set ipauth 113pop modify set ipauth add 113pop modify set ipauth remove 114pop show 104, 105server replicate 175svrsslcfg -unconfig 164user create 147, 154user import 154user list 148, 193user list-dn 193user modify password 149user show groups 193

common audit servicedisabling audit 234enabling audit 234

common problemsreporting

describing problem 376determining business impact 375gathering information 376

submitting problems 376communication

FIPS mode 2SSL 2TLS 2

compress entry 233config ACL (default) 52config option

bassslcfg command 165configuration

server files 172configuration entries

dynamic-adi-entitlement-services 136input-adi-xml-prolog 136resource-manager-provided-adi 136xsl-stylesheet-prolog 136

configuration filesActive Directory server 207activedir_ldap.conf 207activedir.conf 207amconf.properties 208authorization server 205aznAPI.conf 209Boolean values 201

configuration files (continued)common audit service 208default location 204default values 200defined strings 200Domino server 208domino.conf 208file names 200general guidelines 199integer values 201ivacld.conf 205ivmgrd.conf 206LDAP client with Active Directory server 207LDAP server 207ldap.conf 207pd.conf 205pdaudit.conf 208pdmgrproxyd.conf 206policy proxy server 206policy server 206resource managers 209runtime 205string values 200Web Portal Manager 208

configuration stanzasSee stanzas

configuration-database stanzadescription 246file entry 246

configurationsmanaging Config permissions 55

configured entry 295configuring

initialization attributes 135levels for step-up authentication 115

connection-inactivity entryldap stanza, ldap.conf 278

constraints, authorization rules 129container names

for ADI containers 123limitations of 123

container objects 34, 189security considerations 77

containers for ADI 123context information

application 120authorization engine 120

control permission 48conventions

typeface xivcore technologies 1count() function 132creating

group container objects 189cred-attributes-entitlement-services entry 219credential entitlements 120custom action groups

representation in ACL entries 82scenario 82

custom permissionsrepresented in ACL entries 82

customer supportcontacting 375obtaining fixes 373receiving updates from 374registering with 374searching information centers 373

Index 397

customer support (continued)searching knowledge bases 373searching the Internet 373submitting problems 376

Ddata integrity or redundancy 177database

path for user registry 181database-path entry

domain=domain_name stanza 249domains stanza 249ivmgrd stanza 256

db-file entry 220debug entry 299default

administration ACL 51administration users and groups 187config ACL 52domain ACL 53GSO ACL 52management ACL 52policy ACL 52proxy ACL 53replica ACL 52root ACL 48, 51security policy 43

default proxy ACL 53default-policy-override-support entry 271defining

security policy 45delegate administrator, illustrated 184delegate role

administration 185delegated administration

administration users and groups 43group ACL permissions 192group container objects 189managing policy 193object space management 186user management 192

delegated managementadministration users and groups 187group management 188

delegated-admin stanzaauthorize-group-list entry 247description 247

delimiters, authorization rules evaluator 128dependencies

server 169Deployment Administrator 43diagnostic events 197directory names, notation xivdiskCachePath entry 233dnforpd entry

uraf-registry stanza, activedir_ldap.conf 318uraf-registry stanza, activedir.conf 314

doAudit entry 234document model for ADI 122domain

administrator (sec_master) 36administrators 184changing description 62creating 61deleting 64enterprise 183

domain (continued)listing 63logging in 61modifying 62multiple 184subdomain, described 183superdomain 183

domain ACL (default) 53domain administrator 145domain commands

create command 62delete command 64list command 63modify command 63

domain entrydomain=domain_name stanza 249domains stanza 249uraf-registry stanza, activedir_ldap.conf 319uraf-registry stanza, activedir.conf 315

domain=domain_name stanzaallowed-registry-substrings entry 248database-path entry 249description 248domain entry 249

domainsdefinition of 33managing domain permissions 59

domains stanzaallowed-registry-substrings entry 248database-path entry 249description 248domain entry 249

Domino serverdomino.conf 208

domino.conf configuration file 208dynamic ADI 121dynamic ADI retrieval entitlement services 136dynamic group support 36, 156dynamic groups

Active Directory 158enabling 158LDAP registry 158

dynamic-adi-entitlement-services 136dynamic-adi-entitlement-services configuration entry 136dynamic-adi-entitlement-services entry 221dynamic-groups-enabled entry

ldap stanza, ldap.conf 279uraf-registry stanza, activedir_ldap.conf 320uraf-registry stanza, activedir.conf 315

Eeducation

see Tivoli technical training xiiienable-last-login entry 265enabled entry

ldap stanza, ldap.conf 279uraf-registry stanza, activedir_ldap.conf 320uraf-registry stanza, activedir.conf 315uraf-registry stanza, domino.conf 312

encryptionsupported ciphers 2

enhanced-pwd-policyTivoli Directory Server 263

enhanced-pwd-policy entry 262enterprise domain 183entitlement example, XML 125


entitlementsretrieval entitlement services 121user credential 120

entriesAttributeName 327policy-trigger 230service-id

aznapi-admin-services stanza 215aznapi-cred-modification-services stanza 227aznapi-entitlement-services stanza 229aznapi-pac-services stanza 232

aclMembership 297ad-gc-port 325ad-gc-server 325allowed-registry-substrings 248audit-attribute 217auditevent 244auth-using-compare 265authMethod 297authn-timeout 266authorize-group-list 247auto-database-update-notify 255azn-app-host 218azn-server-name 218bannerFile 298bind-dn 266bind-id 309boot-start-ivacld 294boot-start-ivmgrd 294boot-start-pdproxyd 295ca-cert-download-enabled 256cache-database 290cache-enabled


cache-group-expire-time 267cache-group-membership 268cache-group-size 268cache-lifetime 309cache-mode 309cache-policy-expire-time 269cache-policy-size 269cache-refresh-interval 219cache-return-registry-id 270cache-size 310cache-use-user-cache 270cache-user-expire-time 271cache-user-size 271cert-ldap 212cert-uraf 213change-pwd-using-ldap-api

uraf-registry stanza, activedir_ldap.conf 318changePassword 298clientPassword 235clientUserName 235compress 233configured 295connection-inactivity

ldap stanza, ldap.conf 278cred-attributes-entitlement-services 219database-path

domain=domain_name stanza 249domains stanza 249ivmgrd stanza 256

db-file 220

entries (continued)debug 299default-policy-override-support 271diskCachePath 233dnforpd


doAudit 234domain

domain=domain_name stanza 249domains stanza 249uraf-registry stanza, activedir_ldap.conf 319uraf-registry stanza, activedir.conf 315

dynamic-adi-entitlement-services 221dynamic-groups-enabled

ldap stanza, ldap.conf 279uraf-registry stanza, activedir_ldap.conf 320uraf-registry stanza, activedir.conf 315

enable-last-login 265enabled

ldap stanza, ldap.conf 279uraf-registry stanza, activedir_ldap.conf 320uraf-registry stanza, activedir.conf 315uraf-registry stanza, domino.conf 312

enhanced-pwd-policy 262errorFilePath 235file 246flushInterval 236hiWater 237host 280hostname 316ignore-suffix 280infoBarGif 299input-adi-xml-prolog 221jrteHost 300jrteProps 300keyFilePath 236ldap-client-timeout 321ldap-server-config 272LdapSSL 287LdapSSLKeyFile 288LdapSSLKeyFileDn 288LdapSSLKeyFilePwd 289listen-flags 222log-file

ivacld stanza 250ivmgrd stanza 257pdmgrproxyd stanza 291

logcfgaznapi-configuration stanza 222ivacld stanza 251ivmgrd stanza 257pdaudit-filter stanza 289

login-failures-persistent 273loginGif 300lowWater 237management-domain 285master-host 286master-port 286max-connections-per-ad-domain

uraf-registry stanza, activedir.conf 321max-notifier-threads 258max-search-size


Index 399

entries (continued)max-server-connections

ldap stanza, ldap.conf 281maxCacheFiles 237maxCacheFileSize 238maxErrorFiles 238maxErrorFileSize 238maxTraceFiles 239maxTraceFileSize 239mode 223multi-domain


NAB 312notifier-wait-time 259novell-suffix-search-enabled

ldap stanza, ldap.conf 282numberCMThreads 239numberEQThreads 240numberRetries 240passwd-ldap 213passwd-uraf 214pd-user-name 224pd-user-pwd 224PDM 313permission-info-returned 224permit-unauth-remote-caller 252pid-file


policy-cache-size 225port


prefer-readwrite-server 274primary-domain 322provide-last-login 254provide-last-pwd-change 255queueSize 240rebindInterval 241replica 283resource-manager-provided-adi 225retryInterval 241search-timeout 274secauthority-suffix 284server 313serverURL 241splashGif 300ssl-authn-type 302ssl-auto-refresh 302ssl-cert-life 302ssl-enable-fips 303ssl-enabled 275ssl-io-inactivity-timeout 303ssl-keyfile

ldap stanza 276ssl stanza 304uraf-registry stanza, activedir_ldap.conf 322

ssl-keyfile-dn 276ssl-keyfile-label

ssl stanza 304uraf-registry stanza, activedir_ldap.conf 323

ssl-keyfile-pwd 324ldap stanza 277

entries (continued)ssl-keyfile-stash 305ssl-listening-port 305ssl-local-domain

ssl stanza, ivacld.conf 306ssl stanza, ivmgrd.conf 306ssl stanza, ldap.conf 308ssl stanza, pd.conf 306ssl stanza, pdmgrproxyd.conf 306

ssl-maximum-worker-threads 306ssl-port 284ssl-pwd-life 307ssl-v3-timeout 307standby 260stashFilePath 242tcp-req-port


tivoli_common_dir 295traceFilePath 242traceLevel 242transferSize 243unix-group


unix-userivacld stanza 253ivmgrd stanza 261pdmgrproxyd stanza 293

uraf-registry-config 311uraf-return-registry-id 314


use-email-as-user-iduraf-registry stanza, activedir.conf 317, 324

useDiskCache 243useEncryption 317user-and-group-in-same-suffix 277user-reg-host 296user-reg-hostport 296user-reg-server 296user-reg-type 296UseSSL 326version 287wasEmbedded 301xsl-stylesheet-prolog 226

environment variables, notation xiverrorFilePath entry 235evaluation process, authorization 18evaluator, authorization rules 128events

auditing 197diagnostic 197messages 197statistics 197trace 197

examplescustom permissions 81external authorization service 18

explicit ACL 47explicit policy 12extended attributes

ACL policiescreating 92deleting 94


extended attributes (continued)ACL policies (continued)

deleting values 95listing 93modifying 93viewing 94

Extensible Markup LanguageSee XML

Extensible Style LanguageSee XSL

external authorization servicedeploying 20implementing 20introduction 17

Ffailover configuration 345Federal Information Processing Standards

See FIPSfile entry 246files

accessmanager.gif 28configuration 205

Active Directory server 207activedir_ldap.conf 207activedir.conf 207amconf.properties 208authorization server 205aznAPI.conf 209common audit service 208default location 204Domino server 208domino.conf 208ivacld.conf 205ivmgrd.conf 206LDAP client with Active Directory server 207LDAP server 207ldap.conf 207pdaudit.conf 208pdmgrproxyd.conf 206policy proxy server 206policy server 206resource managers 209Web Portal Manager 208

keyrenewal guidelines 165renewing 161

regAdmin.jsp 29regControl.jsp 29regProp.jsp 29runtime 205stash

renewal guidelines 165FIPS

communication 2fixes, obtaining 373flushInterval entry 236format, authorization rules 129FTP 164

GGIF files

accessmanager.gif 28

Global Sign-OnSee GSO

groupdynamic 156importing 156

group accounts 145group commands

create 155, 190delete 157import 157import command 156list 156

group container objectscreating 189

group create command 190group list command 193group list-dn command 193group management 191groups

accounts 145adding ACL entry to ACL policy 90creating 155, 190definition 145delegating management 188deleting 157dynamic 36enabling dynamic 158iv-admin 36iv-admin group 43ivmgrd-servers 43listing 155management tasks 145managing groups permissions 57modifying permissions 91removing ACL entries from ACL policies 91searching 155type attribute 79

GSOmanaging GSO permissions 58

GSO ACL (default) 52guidelines

for secure object space 41key file renewal 165stash file renewal 165

HHACMP

environment 177guidelines for cluster 177

hacmp.log file 179high availability

log files 179management 178policy server setup 178standby policy server 178

High Availability Cluster MultiprocessingSee HACMP

hiWater entry 237host entry 280hostname entry 316

IIBM Directory 345

Index 401

IBM Directory Server user registrySee LDAP server

ID attribute 79ignore-suffix entry 280infoBarGif entry 299information centers, searching 373inherited ACL 47, 50inherited policy 12initialization attributes 135

dynamic-adi-entitlement-services 136input-adi-xml-prolog 136resource-manager-provided-adi 136xsl-stylesheet-prolog 136

input-adi-xml-prolog configuration entry 136input-adi-xml-prolog entry 221integrity of data 177Internet, searching 373introduction 1IP addresses

adding network-based authorization for POPs 113deleting network-based authorization for POPs 114forbidding network-based authorization for POPs 113specifying for POPs 113

iPlanetSee Sun ONE

iv-admin group 36, 43ivacld stanza

description 250log-file entry 250logcfg entry 251permit-unauth-remote-caller entry 252pid-file entry 252tcp-req-port entry 253unix-group entry 254unix-user entry 253

ivacld.conf configuration file 205ivacld.kdb key file 161ivacld.sth stash file 161ivmgrd stanza

auto-database-update-notify entry 255ca-cert-download-enabled entry 256database-path 256description 254log-file entry 257logcfg entry 257max-notifier-threads entry 258notifier-wait-time entry 259pid-file entry 259provide-last-login entry 254provide-last-pwd-change entry 255standby entry 260tcp-req-port entry 261unix-group entry 261unix-user entry 261

ivmgrd-servers group 43ivmgrd.conf configuration file 206ivmgrd.kdb key file 161ivmgrd.sth stash file 161

JjrteHost entry 300jrteProps entry 300JSP files

regAdmin.jsp 29regControl.jsp 29regProp.jsp 29

Kkey files

definition 159ivacld.kdb 161ivmgrd.kdb 161pd.kdb 161pdmgrproxyd.kdb 161renewal guidelines 165renewing 161

keyFilePath entry 236keystores, definition 159knowledge bases

information centers 373searching 373the Internet 373

LLDAP

configurationldap.conf 278

failover configuration 345LDAP client

activedir_ldap.conf 207LDAP failover

preference values 348LDAP registry

enabling dynamic groups 158LDAP server

ldap.conf 207LDAP servers

failover 177ldap stanza

auth-using-compare entry 265authn-timeout entry 266bind-dn entry 266cache-enabled entry

ldap stanza, ivacld.conf 267ldap stanza, ivmgrd.conf 267ldap stanza, pdmgrproxyd.conf 267ldap.conf 278

cache-group-expire-time entry 267cache-group-membership entry 268cache-group-size entry 268cache-policy-expire-time entry 269cache-policy-size entry 269cache-return-registry-id entry 270cache-use-user-cache entry 270cache-user-expire-time entry 271cache-user-size entry 271connection-inactivity entry

ldap.conf 278default-policy-override-support entry 271description

ivacld.conf 262ivmgrd.conf 262ldap.conf 278pdmgrproxyd.conf 262

dynamic-groups-enabled entryldap.conf 279

enable-last-login entry 265enabled entry

ldap.conf 279enhanced-pwd-policy entry 262host entry 280ignore-suffix entry 280


ldap stanza (continued)ldap-server-config entry 272login-failures-persistent entry 273max-search-size entry

ivacld.conf 273ivmgrd.conf 273ldap stanza, ldap.conf 281pdmgrproxyd.conf 273

max-server-connections entryldap stanza, ldap.conf 281

novell-suffix-search-enabled entryldap stanza, ldap.conf 282

port entryldap stanza, ivacld.conf 274ldap stanza, ivmgrd.conf 274ldap stanza, ldap.conf 283ldap stanza, pdmgrproxyd.conf 274

prefer-readwrite-server entry 274replica entry 283search-timeout entry 274secauthority-suffix entry 284ssl-enabled entry 275ssl-keyfile entry 276ssl-keyfile-dn entry 276ssl-keyfile-pwd entry 277ssl-port entry 284user-and-group-in-same-suffix entry 277

LDAP_ADMINLIMIT_EXCEEDED 330ldap-client-timeout entry 321ldap-generic-acls (internal use) 207ldap-generic-general (internal use) 207ldap-generic-pwd-change-error-map (internal use) 207ldap-server-config entry 272ldap.conf 347ldap.conf configuration file 207LdapSSL entry 287LdapSSLKeyFile entry 288LdapSSLKeyFileDn entry 288LdapSSLKeyFilePwd entry 289legal

notices 379trademarks 380

levels for step-up authentication 115limitations, container names 123limitations, network-based authorization 110Linux servers

See UNIX serverslisten-flags entry 222local cache mode 14, 16log files

hacmp.log 179high availability 179

log-file entryivacld stanza 250ivmgrd stanza 257pdmgrproxyd stanza 291

logcfg entryaznapi-configuration stanza 222ivacld stanza 251ivmgrd stanza 257pdaudit-filter stanza 289

login-failures-persistent entry 273loginGif entry 300look-through limit 330Lotus Domino server

See Domino serverlowWater entry 237

Mmanagement ACL (default) 52management delegation 186, 188management domain 33management interface 10management region

permissions 53management tasks

authorization rules 137management-domain entry 285Management/ACL permissions 53management/Action permissions 54Management/Config permissions 55Management/Domain permissions 59Management/Groups permissions 57Management/GSO permissions 58Management/Policy permissions 56Management/POP permissions 55Management/Proxy permissions 59Management/Replica permissions 56Management/Rule permissions 58Management/Server permissions 55Management/Users permissions 56manager stanza

description 285management-domain entry 285master-host entry 286master-host port entry 286

managingACL permissions 53Action permissions 54Config permissions 55delegated administration policy 193domain permissions 59groups permissions 57GSO permissions 58object space 65policy permissions 56POP permissions 55proxy permissions 59replica permissions 56rule permissions 58server permissions 55servers 167users permissions 56

manualssee publications ix, xii

mapping, pdadmin CLI to WPM 337master authorization policy database 9master-host entry 286master-port entry 286max-connections-per-ad-domain entry

uraf-registry stanza, activedir.conf 321max-notifier-threads entry 175, 258max-search-size entry


max-server-connections entryldap stanza, ldap.conf 281

maxCacheFiles entry 237maxCacheFileSize entry 238maxErrorFiles entry 238maxErrorFileSize entry 238maxTraceFiles entry 239maxTraceFileSize entry 239

Index 403

messages 197meta-info stanza

description 287version entry 287

mode entry 223model of authorization 6model, document 122modes

authorization API local cache 16authorization API remote cache 15

multi-domain entryuraf-registry stanza, activedir_ldap.conf 321uraf-registry stanza, activedir.conf 316

multi-factor authentication 116multiple domain 184

example 184illustrated 184

multiple-tenancy policy server 181

NNAB entry 312network-based authorization

adding for POPs 113algorithm 110deleting for POPs 114forbidding or POPs 113limitations 110specifying IP addresses and ranges 113

notationenvironment variables xivpath names xivtypeface xiv

notices 379notification delay time 176notifier-wait-time entry 176, 259novell-suffix-search-enabled entry

ldap stanza, ldap.conf 282numberCMThreads entry 239numberEQThreads entry 240numberRetries entry 240

Oobject commands

create 72, 189delete 75list 73

object create command 72, 189object delete command 75object list command 73object space

definition of 34delegating management 186management tasks 65

object spacesbrowsing 67copying 67creating 65deleting 69exporting 68importing 68listing 67

objectscreating 71deleting 74

objects (continued)exporting 74importing 73listing 73management tasks 71

objectspace commandscreate 66delete 69list 67

objectspace create command 66objectspace delete 69objectspace list 67online publications

accessing xiiordering publications xiioverview 1

Ppasswd-ldap entry 213passwd-uraf entry 214password

troubleshooting 185Password policy

LDAP 329passwords

automatic refresh 161changing 148management tasks 159

path names, notation xivpd_start utility

displaying server status 171restarting servers 171starting servers 170stopping servers 171

pd-user-name entry 224pd-user-pwd entry 224pd.conf configuration file 205pd.kdb key file 161pd.sth stash file 161pdacld server process

authorization server 167starting 170

pdadmin command interface 4pdaudit-filter stanza

description 289logcfg entry 289

pdaudit.conf configuration file 208PDCA

reconfiguring policy server 163PDCA certificate

See certificatespdconfig stanza

descriptionldap.conf 287

LdapSSL entry 287LdapSSLKeyFile entry 288LdapSSLKeyFileDn entry 288LdapSSLKeyFilePwd entry 289

PDM entry 313pdmgr

See policy serverpdmgrd server process

policy server 167starting 170

pdmgrproxyd server processpolicy proxy server 167


pdmgrproxyd server process (continued)starting 170

pdmgrproxyd stanzacache-database entry 290description 290log-file entry 291pid-file entry 292tcp-req-port entry 292unix-group entry 293unix-user entry 293

pdmgrproxyd.conf configuration file 206pdmgrproxyd.kdb key file 161pdmgrproxyd.sth stash file 161pdrte stanza

boot-start-ivacld entry 294boot-start-ivmgrd entry 294boot-start-pdproxyd entry 295configured entry 295description 294tivoli_common_dir entry 295user-reg-host entry 296user-reg-hostport entry 296user-reg-server entry 296user-reg-type entry 296

pdwpm stanzaaclMembership entry 297authMethod entry 297bannerFile entry 298changePassword entry 298debug entry 299description 296infoBarGif entry 299jrteHost entry 300jrteProps entry 300loginGif entry 300splashGif entry 300wasEmbedded entry 301

permission_info attribute list 135permission-info-returned entry 224permissions

/Management/ACL permissions 53/management/Action permissions 54/Management/Config permissions 55/Management/Domain permissions 59/Management/Groups permissions 57/Management/GSO permissions 58/Management/Policy permissions 56/Management/POP permissions 55/Management/Proxy permissions 59/Management/Replica permissions 56/Management/Rule permissions 58/Management/Server permissions 55/Management/Users permissions 56ACL entries

modifying 91adding ACL entry to ACL policy 90administration users 43control (c) 48creating in action group 97custom 81custom, example 81defaults 80deleting from action group 98iv-admin group 43listing for action group 98roles 185sec_master 43

permissions (continued)traverse (T) 48

permissions attribute 79permissions attrribute

represented in ACL entries 82permit-unauth-remote-caller entry 252pid-file entry


policiesauthorization rules 40, 46managing policy permissions 56POPs 40

policy ACL (default) 52policy commands

setall users 153single user 151

policy database 9policy enforcer 6policy proxy server

configuration file 206introducing 168key and stash files 161pdmgrproxyd server process 167pdmgrproxyd.conf 206preventing automating startup 174starting 170

policy serverconfiguration file 206high availability setup 178ivmgrd.conf 206key and stash files 161overview 9pdmgrd server process 167preventing automating startup 173reconfiguring PDCA 163standby server 178starting 170

policy-cache-size entry 225pop attach command 108POP attributes 45, 101

audit level 111configuring 111management tasks 102setting 111time of day 112warning mode 111

pop commandsattach 108create 104delete 109detach 109find 109list 105show 104, 105

pop create command 104pop delete command 109pop detach command 109pop find command 109pop list command 105pop modify set ipauth add command 113pop modify set ipauth command 113pop modify set ipauth remove command 114POP policies, defining 11pop show command 104, 105

Index 405

POPsadding network-based authorization 113attaching to object 108attributes of 45cloning 106configuring attributes 111creating 102definition of 13, 37deleting 109deleting network-based authorization 114detaching from object 108exporting

all 107multiple 107one 107

finding where attached 109forbidding network-based authorization 113importing 106introducing 101listing 105management tasks 102managing POP permissions 55modifying 104network-based authorization 110policies 40Quality of Protection 114showing 105specifying IP addresses and ranges 113versus authorization rules 40

port entryldap stanza, ivacld.conf 274ldap stanza, ivmgrd.conf 274ldap stanza, ldap.conf 283ldap stanza, pdmgrproxyd.conf 274

prefer-readwrite-server entry 274preference values (LDAP failover) 348preventing automating startup

authorization server 173policy proxy server 174policy server 173

primary groupdefault permissions 80

primary-domain entry 322prolog statements 136protected object policies

See POPsprotected object policy

See POPsprotected object space 34

guidelines 41protected objects

management tasks 71Protected Resource Administrator 43provide-last-login entry 254provide-last-pwd-change entry 255proxies

managing proxy permissions 59proxy ACL (default) 53publications ix

accessing online xiiordering xii

QQoP

See Quality of Protection

Quality of Protectionintroduction 2setting 114

queueSize entry 240

RRAID

See Redundant Array of Independent Disksreason codes

rule failure 135rebindInterval entry 241redundancy of data 177Redundant Array of Independent Disks 177refresh, certificates and passwords 161regAdmin.jsp file 29regControl.jsp file 29regProp.jsp file 29remote cache mode 14, 15renewals

key files 161stash files 161

replica 347replica ACL (default) 52replica entry 283replicas

managing replica permissions 56replicate authorization database 174replication 10resolving ACL request 49resource manager 6

requesting ADI 133resource managers

aznAPI.conf 209configuration file 209

resource objects 34resource requests 18resource-manager-provided-adi configuration entry 136resource-manager-provided-adi entry 225responsibilities

Deployment Administrator 43Protected Resource Administrator 43Security Policy Administrator 43

restarting servers 171restriction, ADI XML document model 123retrieval entitlement services 136retrieval entitlements service 120, 121retryInterval entry 241roles

assigning role assignment 186defined 185delegate 185permissions 185role activation 186role assignment 186role creation 186

root ACL (default) 48, 51rule failure reason code 135runtime

configuration file 205pd.conf 205reconfiguring secure communication 163


Sscalability 3, 10search-timeout entry 274sec_master 183sec_master domain administrator 36sec_master user 36, 43secauthority-suffix entry 284secure communication

reconfiguring runtime 163Secure Socket Layer

See SSLsecurity

policy 185security considerations

ACL policies 77container objects 77

security policy 37default 43defining 45implementing 11overview 5

Security Policy Administrator 43server

replicating 175server entry 313server replicate command 175servers

automating startup 173configuration files 172dependencies for 169displaying status 171HACMP cluster 177LDAP servers 177management of 167managing server permissions 55primary and standby 177restarting using the pd_start utility 171starting and stopping for UNIX 170starting and stopping for Windows 171starting manually 170starting using the pd_start utility 170stopping using the pd_start utility 171

serverURL entry 241shared disk arrays 177software updates, receiving 374sources for ADI 121sparse ACL model 47splashGif entry 300SSL

communication 2reconfiguring runtime 163

ssl stanzadescription

ivacld.conf 301ivmgrd.conf 301ldap.conf 308pd.conf 301pdmgrproxyd.conf 301

ssl-authn-type entry 302ssl-auto-refresh entry 302ssl-cert-life entry 302ssl-enable-fips entry 303ssl-io-inactivity-timeout entry 303ssl-keyfile entry 304ssl-keyfile-label entry 304ssl-keyfile-stash entry 305ssl-listening-port entry 305

ssl stanza (continued)ssl-local-domain entry

ldap.conf 308ssl stanza, ivacld.conf 306ssl stanza, ivmgrd.conf 306ssl stanza, pd.conf 306ssl stanza, pdmgrproxyd.conf 306

ssl-maximum-worker-threads entry 306ssl-pwd-life entry 307ssl-v3-timeout entry 307

ssl-authn-type entry 302ssl-auto-refresh entry 302ssl-cert-life entry 302ssl-enable-fips entry 303ssl-enabled entry 275ssl-io-inactivity-timeout entry 303ssl-keyfile entry

ldap stanza 276ssl stanza 304uraf-registry stanza, activedir_ldap.conf 322

ssl-keyfile-dn entry 276ssl-keyfile-label entry

ssl stanza 304uraf-registry stanza, activedir_ldap.conf 323

ssl-keyfile-pwd entry 324ldap stanza 277

ssl-keyfile-stash entry 305ssl-listening-port entry 305ssl-local-domain entry

ssl stanza, ivacld.conf 306ssl stanza, ivmgrd.conf 306ssl stanza, ldap.conf 308ssl stanza, pd.conf 306ssl stanza, pdmgrproxyd.conf 306

ssl-maximum-worker-threads entry 306ssl-port entry 284ssl-pwd-life entry 307ssl-v3-timeout entry 307standby entry 260stanza entries

See entriesstanzas

authentication-mechanisms 211aznapi-admin-services 215aznapi-configuration 217aznapi-cred-modification-services 227aznapi-entitlement-services 228aznapi-external-authzn-services 230aznapi-pac-services 231cars-client 233cars-filter 244configuration-database 246delegated-admin 247domain=domain_name 248domains 248general format 211ivacld 250ivmgrd 254ldap

ivacld.conf 262ivmgrd.conf 262ldap.conf 278pdmgrproxyd.conf 262

ldap-generic-acls (internal use) 207ldap-generic-general (internal use) 207ldap-generic-pwd-change-error-map (internal use) 207manager 285

Index 407

stanzas (continued)meta-info 287pdaudit-filter 289pdconfig

ldap.conf 287pdmgrproxyd 290pdrte 294pdwpm 296ssl

ivacld.conf 301ivmgrd.conf 301ldap.conf 308pd.conf 301pdmgrproxyd.conf 301

uraf-registryactivedir_ldap.conf 318activedir.conf 314domino.conf 312ivacld.conf 308ivmgrd.conf 308pdmgrproxyd.conf 308

xmladi-attribute-definition 326starting servers

UNIX 170using the pd_start utility 170using the Windows Services Control Panel 172Windows 171

stash filesdefinition 160ivacld.sth 161ivmgrd.sth 161pd.sth 161pdmgrproxyd.sth 161renewal guidelines 165renewing 161

stashFilePath entry 242statistics 197status, server 171step-up authentication

applying 115configuring 115versus multi-factor authentication 116

stopping serversUNIX 170using the pd_start utility 171using the Windows Services Control Panel 172Windows 171

string identifiers 129subdomain 183sum() function 132Sun Java System Directory Server

LDAP_ADMINLIMIT_EXCEEDED 330look-through limit 330

superdomain 183support

See customer supportsvrsslcfg -unconfig command 164

Ttasks

role activation 186role administration 186role assignment 186role creation 186roles 185types 186

tcp-req-port entryivacld stanza 253ivmgrd stanza 261pdmgrproxyd stanza 292

Tivoli Access Manager runtime package 161Tivoli Information Center xiiTivoli technical training xiiiTivoli user groups xiiitivoli_common_dir entry 295TLS

communication 2reconfiguring runtime 163

trace data 197traceFilePath entry 242traceLevel entry 242trademarks 380training, Tivoli technical xiiitransferSize entry 243Transport Layer Security

See TLStraverse permission 48trust determination, certificates 162type attribute

any-authenticated 79any-other 79categories 79group 79unauthenticated 79user 79

typeface conventions xivtypes of

Tivoli Access Manager servers 167Tivoli Access Manager utilities 170

Uunauthenticated

adding ACL entry to ACL policy 90modifying permissions 91removing ACL entries from ACL policies 91type attribute 79

unauthenticated requests 39unauthenticated user 38UNIX servers

starting and stopping 170unix-group entry


unix-user entryivacld stanza 253ivmgrd stanza 261pdmgrproxyd stanza 293

update-notifier threads 175uraf-registry stanza

ad-gc-port entry 325ad-gc-server entry 325bind-id entry 309cache-lifetime entry 309cache-mode entry 309cache-size entry 310change-pwd-using-ldap-api entry

activedir_ldap.conf 318description

activedir_ldap.conf 318activedir.conf 314domino.conf 312


uraf-registry stanza (continued)description (continued)

ivacld.conf 308ivmgrd.conf 308pdmgrproxyd.conf 308

dnforpd entryactivedir_ldap.conf 318activedir.conf 314

domain entryactivedir_ldap.conf 319activedir.conf 315

dynamic-groups-enabled entryactivedir_ldap.conf 320activedir.conf 315

enabled entry 312activedir_ldap.conf 320activedir.conf 315

hostname entry 316ldap-client-timeout entry 321max-connections-per-ad-domain entry

activedir.conf 321multi-domain entry

activedir_ldap.conf 321activedir.conf 316

NAB entry 312PDM entry 313primary-domain entry 322server entry 313ssl-keyfile entry

activedir_ldap.conf 322ssl-keyfile-label entry

activedir_ldap.conf 323ssl-keyfile-pwd entry 324uraf-registry-config entry 311uraf-return-registry-id entry 314

activedir_ldap.conf 324activedir.conf 316

use-email-as-user-id entryactivedir.conf 317, 324

useEncryption entry 317UseSSL entry 326

uraf-registry-config entry 311uraf-return-registry-id entry 314


use-email-as-user-id entryuraf-registry stanza, activedir.conf 317, 324

useDiskCache entry 243useEncryption entry 317user

credential entitlements 120listing 147searching 147

user accounts 145user commands

create 147delete 154import 154list 148modify password 149

user groups, Tivoli xiiiuser list command 193user list-dn command 193user management 192user policies

modifying for a user 149setting for a user 149

user registriesActive Directory server 207Active Directory with LDAP client 207Domino server 208LDAP server 207

user registrydifferences 329maximum values 334

user show groups command 193user-and-group-in-same-suffix entry 277user-reg-host entry 296user-reg-hostport entry 296user-reg-server entry 296user-reg-type entry 296users

accounts 145adding ACL entry to ACL policy 90administrator 36administrator, administrator 184administrator, domain 184administrator, sec_master 183administrator, senior 184administrator, support 185administrator, Tivoli Access Manager 184changing passwords 148creating 146definition 145delegate 185deleting 154importing 153management tasks 145managing users permissions 56modifying permissions 91removing ACL entries from ACL policies 91sec_master 36, 43setting user policy

modify user policy 149type attribute 79

UseSSL entry 326utilities 170

manual certificate updates 161

Vvariables, notation for xivversion entry 287

WwasEmbedded entry 301Web Portal Manager 4

accessing online help 27amconf.properties 208common tasks 26configuration file 208customizing 28customizing images 28logging in 27rebranding 28signing off 27starting for administration 26

Windowsstarting and stopping servers 171

Index 409

XXML

ADI containers and container names 123ADI document model 122ADI document model restriction 123ADI name/value pair attributes 124authorization rules 122entitlement document example 125prolog statements 136

xmladi-attribute-definition stanzaAttributeName entry 327definition 326

XSLauthorization rules 122prolog statements 136xsl:template statement 129xsl:when statement 131

xsl-stylesheet-prolog configuration entry 136xsl-stylesheet-prolog entry 226xsl:template statement 129xsl:when statement 131


��

Printed in USA

SC23-6504-01

administration guide - ibm - united states server., access manager., , administration guide

Documents