Base Administrator’s Guide - IBMpublib.boulder.ibm.com/tividd/td/ITAME/GC23-4684-00/en... · 2005-04-12 · The IBM Tivoli Access Manager Base Administrator’s Guide provides a

IBM Tivoli Access Manager

Base Administrator’s GuideVersion 3.9

GC23-4684-00

IBM Tivoli Access Manager

Base Administrator’s GuideVersion 3.9

GC23-4684-00

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

First Edition (April 2002)

©Copyright Sun Microsystems, Inc. 1999

© Copyright International Business Machines Corporation 2002. All rights reserved. Note to U.S. Government UsersRestricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWho should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWhat this book contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiProviding feedback about publications . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiContacting customer support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiConventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Chapter 1. Access Manager overview . . . . . . . . . . . . . . . . . . . . . . . 1Securing the enterprise network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Network security — common concerns . . . . . . . . . . . . . . . . . . . . . . . . . 2Introducing Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Access Manager — core technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Quality of (data) protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Accountability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Centralized management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Understanding authorization: conceptual model . . . . . . . . . . . . . . . . . . . . . . . 5The benefits of a standard authorization service . . . . . . . . . . . . . . . . . . . . . . 6Introducing the Access Manager authorization service . . . . . . . . . . . . . . . . . . . . 7

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

Implementing a network security policy . . . . . . . . . . . . . . . . . . . . . . . . . . 11Defining the network security policy . . . . . . . . . . . . . . . . . . . . . . . . . . 11The protected object space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Defining and applying ACL and POP policies . . . . . . . . . . . . . . . . . . . . . . . 12Policy administration: The Web portal manager . . . . . . . . . . . . . . . . . . . . . . 14The authorization process: step-by-step . . . . . . . . . . . . . . . . . . . . . . . . . 15

The Access Manager authorization API . . . . . . . . . . . . . . . . . . . . . . . . . . 16Using the authorization API: two examples . . . . . . . . . . . . . . . . . . . . . . . . 17Authorization API: remote cache mode . . . . . . . . . . . . . . . . . . . . . . . . . 18Authorization API: local cache mode . . . . . . . . . . . . . . . . . . . . . . . . . . 19

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

Access Manager Base certificate and password management . . . . . . . . . . . . . . . . . . . 24Initial configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Keyring database file and stash file renewal information . . . . . . . . . . . . . . . . . . . 25Determining trust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Certificate Revocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Additional considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

iii

Chapter 2. Managing the protected object space. . . . . . . . . . . . . . . . . . 29Understanding the protected object space . . . . . . . . . . . . . . . . . . . . . . . . . 29

Elements of the protected object space . . . . . . . . . . . . . . . . . . . . . . . . . 29Protected object space hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . 30User-defined object space for third-party applications . . . . . . . . . . . . . . . . . . . . 31

Defining a database object space . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Creating a new user-defined container object . . . . . . . . . . . . . . . . . . . . . . . 32Creating and deleting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 3. Using access control policies . . . . . . . . . . . . . . . . . . . . . 35Introducing the ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

ACL policy entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Creating and naming ACL policies . . . . . . . . . . . . . . . . . . . . . . . . . . 36

ACL entry syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Type attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37ID attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Permissions (actions) attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Default Access Manager permissions (actions) . . . . . . . . . . . . . . . . . . . . . . . 39

How the authorizations service uses ACL policies . . . . . . . . . . . . . . . . . . . . . . 39Performing operations on an object . . . . . . . . . . . . . . . . . . . . . . . . . . 39Requirements for custom permissions . . . . . . . . . . . . . . . . . . . . . . . . . 40Custom action example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Evaluating an ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Evaluating authenticated requests . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Evaluating unauthenticated requests . . . . . . . . . . . . . . . . . . . . . . . . . . 41Example ACL entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Sparse ACL model: ACL inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Understanding the sparse ACL model . . . . . . . . . . . . . . . . . . . . . . . . . 42The default root ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Traverse permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Resolving an access request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Applying ACL policies to different object types . . . . . . . . . . . . . . . . . . . . . . 45ACL policy inheritance example . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Guidelines for a secure object space . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Creating extended ACL actions and action groups . . . . . . . . . . . . . . . . . . . . . . 46Creating a new action group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Creating new actions in an action group. . . . . . . . . . . . . . . . . . . . . . . . . 48Entering custom actions into ACL entries . . . . . . . . . . . . . . . . . . . . . . . . 48

ACL policies and the protected object space . . . . . . . . . . . . . . . . . . . . . . . . 49Root ( / ) container object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49The traverse permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

WebSEAL permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50/WebSEAL/host. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50/WebSEAL/host/file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50WebSEAL permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Management permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51/Management/ACL permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 51/Management/Action permissions . . . . . . . . . . . . . . . . . . . . . . . . . . 52/Management/POP permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 53/Management/Server permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . 53/Management/Config permissions . . . . . . . . . . . . . . . . . . . . . . . . . . 54/Management/Policy permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 54/Management/Replica permissions . . . . . . . . . . . . . . . . . . . . . . . . . . 54/Management/Users permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 55/Management/Groups permissions . . . . . . . . . . . . . . . . . . . . . . . . . . 56/Management/GSO permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Object and object space permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Default administration ACL policies . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Default root ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Default /WebSEAL ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Default /Management ACL policy. . . . . . . . . . . . . . . . . . . . . . . . . . . 58

iv IBM Tivoli Access Manager: Base Administrator’s Guide

Default /Replica ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Default /Config ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Default /GSO ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Default /Policy ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 4. Using protected object policies . . . . . . . . . . . . . . . . . . . . 61Introducing protected object policies (POP) . . . . . . . . . . . . . . . . . . . . . . . . . 62

POP notes:. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Creating and deleting protected object policies . . . . . . . . . . . . . . . . . . . . . . 62Applying POP attributes to protected objects . . . . . . . . . . . . . . . . . . . . . . . 63

Configuring the POP attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Warning mode attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Audit level attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Time-of-day attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Authentication strength POP policy (step-up) . . . . . . . . . . . . . . . . . . . . . . . . 65Configuring levels for step-up authentication . . . . . . . . . . . . . . . . . . . . . . . 65Applying step-up authentication policy . . . . . . . . . . . . . . . . . . . . . . . . . 66Step-up authentication algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Distinguishing step-up from multi-factor authentication . . . . . . . . . . . . . . . . . . . 67

Network-based authentication POP policy . . . . . . . . . . . . . . . . . . . . . . . . . 68Specifying IP addresses and ranges . . . . . . . . . . . . . . . . . . . . . . . . . . 68Disabling step-up authentication by IP address . . . . . . . . . . . . . . . . . . . . . . 69Network-based authentication algorithm . . . . . . . . . . . . . . . . . . . . . . . . 69Network-based authentication notes and limitations . . . . . . . . . . . . . . . . . . . . . 69

Quality of protection POP policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Chapter 5. Using Web portal manager . . . . . . . . . . . . . . . . . . . . . . 71Delegating administration using Web portal manager . . . . . . . . . . . . . . . . . . . . . 71

Delegating role administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Self-registration sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Chapter 6. Delegating administration tasks . . . . . . . . . . . . . . . . . . . . 77Delegating object space management . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Structuring the object space for management delegation . . . . . . . . . . . . . . . . . . . 78Default administration users and groups . . . . . . . . . . . . . . . . . . . . . . . . 78Creating administration users . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Example administration ACL templates . . . . . . . . . . . . . . . . . . . . . . . . . 80Example: Management delegation . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Delegating group management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Creating group container objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Creating groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83ACL policies affecting group management . . . . . . . . . . . . . . . . . . . . . . . . 84ACL policies affecting user management . . . . . . . . . . . . . . . . . . . . . . . . 85

Managing delegated administration policy . . . . . . . . . . . . . . . . . . . . . . . . . 86

Chapter 7. Managing Access Manager servers. . . . . . . . . . . . . . . . . . . 89Introducing the Access Manager servers . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Server dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Introducing server administration tools . . . . . . . . . . . . . . . . . . . . . . . . . 90Server configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Starting and stopping Access Manager servers. . . . . . . . . . . . . . . . . . . . . . . . 97Starting and stopping servers on UNIX systems . . . . . . . . . . . . . . . . . . . . . . 97Starting and stopping servers on Windows systems . . . . . . . . . . . . . . . . . . . . . 98

Automating server startup at boot time . . . . . . . . . . . . . . . . . . . . . . . . . . 99Policy server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Authorization server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Policy server administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Replicating the authorization database . . . . . . . . . . . . . . . . . . . . . . . . . 100Setting the number of update notifier threads . . . . . . . . . . . . . . . . . . . . . . 101Setting the notification delay time . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Contents v

Chapter 8. Using the LDAP registry . . . . . . . . . . . . . . . . . . . . . . . 103LDAP overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

LDAP: A protocol for directory services . . . . . . . . . . . . . . . . . . . . . . . . 103LDAP directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104The LDAP information model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105LDAP features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

LDAP fail-over configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106The master-slave replication model . . . . . . . . . . . . . . . . . . . . . . . . . . 106Access Manager fail-over capability for LDAP servers . . . . . . . . . . . . . . . . . . . . 107Master server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Replica server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Setting preference values for replica LDAP servers . . . . . . . . . . . . . . . . . . . . . 109Server polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Applying Access Manager ACLs to new LDAP suffixes . . . . . . . . . . . . . . . . . . . . 109Procedures for the IBM SecureWay Directory server . . . . . . . . . . . . . . . . . . . . 111Procedures for iPlanet Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . 112

Chapter 9. Logging and auditing server activity. . . . . . . . . . . . . . . . . . 115Introduction to logging and auditing . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Audit trail files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Documentation convention: install_path . . . . . . . . . . . . . . . . . . . . . . . . 115

Logging Base serviceability messages . . . . . . . . . . . . . . . . . . . . . . . . . . 116Access Manager audit trail files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Enabling and disabling auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Specifying the log file location . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Specifying audit file rollover thresholds . . . . . . . . . . . . . . . . . . . . . . . . 118Specifying the frequency for flushing audit file buffers . . . . . . . . . . . . . . . . . . . 119Specifying audit events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Audit trail file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Status attribute of the outcome field . . . . . . . . . . . . . . . . . . . . . . . . . . 121Resource attribute of the target field. . . . . . . . . . . . . . . . . . . . . . . . . . 121

Audit trail file contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Authorization audit records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Authentication audit records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122WebSEAL audit records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Management Audit Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Chapter 10. Using event logging . . . . . . . . . . . . . . . . . . . . . . . . 129Understanding Access Manager events . . . . . . . . . . . . . . . . . . . . . . . . . . 129Configuring event logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Configuring the central event propagation queue . . . . . . . . . . . . . . . . . . . . . 132Specifying the maximum number of events to queue in memory . . . . . . . . . . . . . . . . 132Specifying the event queue high water mark . . . . . . . . . . . . . . . . . . . . . . . 133Specifying the frequency for flushing log file buffers . . . . . . . . . . . . . . . . . . . . 133

Console logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133File logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Specifying the log file location. . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Specifying the log file ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Specifying the maximum log file size . . . . . . . . . . . . . . . . . . . . . . . . . 135Specifying the maximum buffer size . . . . . . . . . . . . . . . . . . . . . . . . . . 135Specifying the maximum number of events to queue in memory . . . . . . . . . . . . . . . . 136Specifying the event queue high water mark . . . . . . . . . . . . . . . . . . . . . . . 136Specifying the frequency for flushing log file buffers . . . . . . . . . . . . . . . . . . . . 136Specifying the file mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Pipe logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Specifying the program to run. . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Specifying the event queuing profile. . . . . . . . . . . . . . . . . . . . . . . . . . 138

Remote logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Specifying the maximum buffer size . . . . . . . . . . . . . . . . . . . . . . . . . . 138Specifying the frequency for flushing the consolidation buffer . . . . . . . . . . . . . . . . . 139

vi IBM Tivoli Access Manager: Base Administrator’s Guide

Specifying the queue sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Specifying compression of messages . . . . . . . . . . . . . . . . . . . . . . . . . . 139Specifying the error retry timeout . . . . . . . . . . . . . . . . . . . . . . . . . . 139Specifying the cache file location . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Specifying the rebind retry timeout . . . . . . . . . . . . . . . . . . . . . . . . . . 140Specifying the remote server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Specifying the remote server port. . . . . . . . . . . . . . . . . . . . . . . . . . . 140Specifying the remote server distinguished name . . . . . . . . . . . . . . . . . . . . . 140

Legacy configuration support and other defaults . . . . . . . . . . . . . . . . . . . . . . 140Compatibility with Authorization API configuration . . . . . . . . . . . . . . . . . . . . 141WebSEAL HTTP request logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Finding out what event categories exist . . . . . . . . . . . . . . . . . . . . . . . . . 141Monitoring log queue performance . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Appendix A. pdadmin commands. . . . . . . . . . . . . . . . . . . . . . . . 143Introducing the pdadmin utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Starting the pdadmin utility (login command) . . . . . . . . . . . . . . . . . . . . . . 143Help information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Exiting the pdadmin utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Special characters disallowed for GSO commands . . . . . . . . . . . . . . . . . . . . . 144

Command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145acl attach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146acl create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147acl delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148acl detach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149acl find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150acl list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151acl list attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152acl modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153acl show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156acl show attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157action create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158action delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159action group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160action list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161admin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162errtext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164group create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165group delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166group import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167group list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168group modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169group show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173object create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174object delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175object list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176object list attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177object listandshow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178object modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179object show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180object show attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181objectspace create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182objectspace delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183objectspace list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184policy get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185policy set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187pop attach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Contents vii

pop create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190pop delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191pop detach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192pop find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193pop list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194pop list attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195pop modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196pop show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198pop show attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200rsrc create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201rsrc delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202rsrc list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203rsrc show. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204rsrccred create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205rsrccred delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206rsrccred list user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207rsrccred modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208rsrccred show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209rsrcgroup create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210rsrcgroup delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211rsrcgroup list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212rsrcgroup modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213rsrcgroup show. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214server list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215server listtasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216server replicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217server show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218server task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219user create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220user delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221user import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222user list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223user modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224user show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Appendix B. ivmgrd.conf reference . . . . . . . . . . . . . . . . . . . . . . . 227

Appendix C. ivacld.conf reference . . . . . . . . . . . . . . . . . . . . . . . 231

Appendix D. ldap.conf reference . . . . . . . . . . . . . . . . . . . . . . . . 235

Appendix E. pd.conf reference . . . . . . . . . . . . . . . . . . . . . . . . . 237

Appendix F. SSL configuration commands . . . . . . . . . . . . . . . . . . . . 239Command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239bassslcfg –chgpwd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240bassslcfg –config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241bassslcfg –getcacert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242bassslcfg –modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243bassslcfg –ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244mgrsslcfg –chgcert. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245mgrsslcfg –chgpwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246mgrsslcfg –config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247mgrsslcfg –modify. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248svrsslcfg –add_replica . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249svrsslcfg –chg_replica . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250svrsslcfg –chgcert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251svrsslcfg –chgport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252svrsslcfg –chgpwd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

viii IBM Tivoli Access Manager: Base Administrator’s Guide

svrsslcfg –config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254svrsslcfg –modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256svrsslcfg –rmv_replica . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257svrsslcfg –unconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Appendix G. User registry differences. . . . . . . . . . . . . . . . . . . . . . 259

Appendix H. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Contents ix

x IBM Tivoli Access Manager: Base Administrator’s Guide

Preface

IBM® Tivoli® Access Manager (Access Manager) is the base software that isrequired to run applications in the product suite. It enables the integration ofAccess Manager applications that provide a wide range of authorization andmanagement solutions. Sold as an integrated solution, these products provide anaccess control management solution that centralizes network and applicationsecurity policy for e-business applications.

Note: IBM Tivoli Access Manager is the new name of the previously releasedsoftware entitled Tivoli SecureWay® Policy Director. Also, for users familiarwith the Tivoli SecureWay Policy Director software and documentation, theterm management server is now referred to as policy server.

The IBM Tivoli Access Manager Base Administrator’s Guide provides a comprehensiveset of procedures and reference information for managing Access Manager serversand resources. This guide also provides you with valuable background andconcept information for the wide range of Access Manager functionality.

Who should read this bookThis guide is for system administrators responsible for the deployment andadministration of base Access Manager software.

Readers should be familiar with the following:v PC and UNIX® operating systemsv Database architecture and conceptsv Security managementv Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and

Telnetv Lightweight Directory Access Protocol (LDAP) and directory servicesv Authentication and authorization

What this book containsThis guide contains the following sections:v Chapter 1, “Access Manager overview” on page 1

Introduces you to important Access Manager concepts and functionality such as:Access Manager core technologies and components, the authorization servicemodel, and implementing a security policy.

v Chapter 2, “Managing the protected object space” on page 29Discusses how Access Manager uses a virtual representation of resources in aprotected object space. Two types of object spaces are supported: flat file anddatabase.

v Chapter 3, “Using access control policies” on page 35Provides a complete reference to access control list (ACL) policies.

v Chapter 4, “Using protected object policies” on page 61Provides a complete reference to protected object policies (POP).

v Chapter 5, “Using Web portal manager” on page 71

xi

Provides supplemental information to tasks provided in the online help system,including delegating administration and self-registration. This Web-based userinterface is shipped separately on the IBM Tivoli Access Manager Web PortalManager CD for AIX, Solaris, and Windows platforms.

v Chapter 6, “Delegating administration tasks” on page 77Explains how Access Manager supports delegated management of the objectspace and group management.

v Chapter 7, “Managing Access Manager servers” on page 89Provides a technical reference to managing and customizing the operation of theAccess Manager servers.

v Chapter 8, “Using the LDAP registry” on page 103Introduces the LDAP protocol / directory and provides detailed information onLDAP fail-over configuration.

v Chapter 9, “Logging and auditing server activity” on page 115Provides a complete reference to the Access Manager logging and auditingcapabilities.

v Appendix A, “pdadmin commands” on page 143v Appendix B, “ivmgrd.conf reference” on page 227v Appendix C, “ivacld.conf reference” on page 231v Appendix D, “ldap.conf reference” on page 235v Appendix E, “pd.conf reference” on page 237

PublicationsThis section lists publications in the Access Manager library and any other relateddocuments. It also describes how to access Tivoli publications online, how to orderTivoli publications, and how to make comments on Tivoli publications.

IBM Tivoli Access ManagerThe Access Manager library is organized into the following categories:v Release informationv Base informationv WebSEAL informationv Web security informationv Developer reference informationv Supplemental technical information

Publications in the product library are included in Portable Document Format(PDF) on the product CD. To access these publications using a Web browser, openthe infocenter.html file, which is located in the /doc directory on the product CD.

For additional sources of information about Access Manager and related topics, seethe following Web sites:

http://www.ibm.com/redbookshttps://www.tivoli.com/secure/support/documents/fieldguides

Release informationv IBM Tivoli Access Manager for e-business Read Me First

GI11-0918 (am39_readme.pdf)

xii IBM Tivoli Access Manager: Base Administrator’s Guide

Provides information for installing and getting started using Access Manager.v IBM Tivoli Access Manager for e-business Release Notes

GI11-0919 (am39_relnotes.pdf)Provides late-breaking information, such as software limitations, workarounds,and documentation updates.

Base informationv IBM Tivoli Access Manager Base Installation Guide

GC32-0844 (am39_install.pdf)Provides installation, configuration, and upgrade instructions for AccessManager base software, including the Web portal manager interface.

v IBM Tivoli Access Manager Base Administrator’s Guide

GC23-4684 (am39_admin.pdf)Describes the concepts and procedures for using Access Manager services.Provides instructions for performing tasks from the Web portal managerinterface and by using the pdadmin command.

v IBM Tivoli Access Manager Base for Linux on zSeries™ Installation Guide

GC23-4796 (am39_zinstall.pdf)Explains how to install and configure Access Manager Base for Linux on thezSeries platform.

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

GC32-0848 (amweb39_install.pdf)Provides installation, configuration, and upgrade instructions for the WebSEALserver and the WebSEAL application development kit.

v IBM Tivoli Access Manager WebSEAL Administrator’s Guide

GC23-4682 (amweb39_admin.pdf)Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

GC23-4683 (amweb39_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

v IBM Tivoli Access Manager WebSEAL for Linux on zSeries Installation Guide

GC23-4797 (amweb39_zinstall.pdf)Provides installation, configuration, and removal instructions for WebSEALserver and the WebSEAL application development kit for Linux on the zSeriesplatform.

Web security informationv IBM Tivoli Access Manager for WebSphere Application Server User’s Guide

GC32-0850 (amwas39_user.pdf)Provides installation, configuration, and administration instructions for AccessManager for IBM WebSphere® Application Server.

v IBM Tivoli Access Manager for WebLogic Server User’s Guide

GC32-0851 (amwls39_user.pdf)

Preface xiii

Provides installation, configuration, and administration instructions for AccessManager for BEA WebLogic Server.

v IBM Tivoli Access Manager Plug-in for Edge Server User’s Guide

GC23-4685 (amedge39_user.pdf)Provides installation, configuration, and administration instructions for theplug-in for Edge Server application.

v IBM Tivoli Access Manager Plug-in for Web Servers User’s Guide

GC23-4686 (amws39_user.pdf)Provides installation, configuration, and administration instructions for securingyour Web domain using the plug-in for Web servers application.

Developer referencesv IBM Tivoli Access Manager Authorization C API Developer’s Reference

GC32-0849 (am39_authC_devref.pdf)Provides reference material that describes how to use the Access Managerauthorization C API and the Access Manager service plug-in interface to addAccess Manager security to applications.

v IBM Tivoli Access Manager Authorization Java Classes Developer’s Reference

GC23-4688 (am39_authJ_devref.pdf)Provides reference information for using the Java™ language implementation ofthe authorization API to enable an application to use Access Manager security.

v IBM Tivoli Access Manager Administration C API Developer’s Reference

GC32-0843 (am39_adminC_devref.pdf)Provides reference information about using the administration API to enable anapplication to perform Access Manager administration tasks. This documentdescribes the C implementation of the administration API.

v IBM Tivoli Access Manager Administration Java Classes Developer’s Reference

SC32-0842 (am39_adminJ_devref.pdf)Provides reference information for using the Java language implementation ofthe administration API to enable an application to perform Access Manageradministration tasks.

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

GC23-4683 (amweb39_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

Technical supplementsv IBM Tivoli Access Manager Performance Tuning Guide

GC43-0846 (am39_perftune.pdf)Provides performance tuning information for an environment consisting ofAccess Manager with IBM SecureWay Directory defined as the user registry.

v IBM Tivoli Access Manager Capacity Planning Guide

GC32-0847 (am39_capplan.pdf)Assists planners in determining the number of WebSEAL, LDAP, and backendWeb servers needed to achieve a required workload.

v IBM Tivoli Access Manager Error Message Reference

SC32-0845 (am39_error_ref.pdf)

xiv IBM Tivoli Access Manager: Base Administrator’s Guide

Provides explanations and recommended actions for the messages produced byAccess Manager.

The Tivoli Glossary includes definitions for many of the technical terms related toTivoli software. The Tivoli Glossary is available, in English only, at the followingWeb site:

http://www.tivoli.com/support/documents/glossary/termsm03.htm

Related publicationsThis section lists publications related to the Access Manager library.

IBM DB2® Universal Database™

IBM DB2 Universal Database is required when installing IBM SecureWay Directory,z/OS™, and OS/390® SecureWay LDAP servers. DB2 information is available atthe following Web site:

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

IBM Global Security ToolkitAccess Manager provides data encryption through the use of IBM Global SecurityToolkit (GSKit). GSKit is shipped on the IBM Tivoli Access Manager Base CD foryour particular platform.

The GSKit package installs the iKeyman key management utility (gsk5ikm), whichenables you to create key databases, public-private key pairs, and certificaterequests. The following document is available in the /doc/GSKit directory:v SSL Introduction and iKeyman User’s Guide (gskikm5c.pdf)

Provides information for network or system security administrators who plan toenable SSL communication in their Access Manager secure domain.

IBM SecureWay DirectoryIBM SecureWay Directory, Version 3.2.2, is shipped on the IBM Tivoli AccessManager Base CD for your particular platform. If you plan to install the IBMSecureWay Directory server as your user registry, the following documents areavailable in the /doc/Directory path on the IBM Tivoli Access Manager Base CDfor your particular platform:v IBM SecureWay Directory Installation and Configuration Guide

(aparent.pdf, lparent.pdf, sparent.pdf, wparent.pdf)Provides installation, configuration, and migration information for IBMSecureWay Directory components on AIX®, Linux, Solaris, and Microsoft®

Windows® operating systems.v IBM SecureWay Directory Release Notes

(relnote.pdf)Supplements IBM SecureWay Directory, Version 3.2.2, product documentationand describes features and functions made available to you in this release.

v IBM SecureWay Directory Readme Addendum

(addendum322.pdf)Provides information about changes and fixes that occurred after the IBMSecureWay Directory documentation had been translated. This file is in Englishonly.

v IBM SecureWay Directory Server Readme

(server.pdf)

Preface xv

Provides a description of the IBM SecureWay Directory Server, Version 3.2.2.v IBM SecureWay Directory Client Readme

(client.pdf)Provides a description of the IBM SecureWay Directory Client SDK, Version3.2.2. This software development kit (SDK) provides LDAP applicationdevelopment support.

v IBM SecureWay Directory Configuration Schema

(scparent.pdf)Describes the directory information tree (DIT) and the attributes that are used toconfigure the slapd32.conf file. In IBM SecureWay Directory Version 3.2, thedirectory settings are stored using the LDAP Directory Interchange Format(LDIF) in the slapd32.conf file.

v IBM SecureWay Directory Tuning Guide

(tuning.pdf)Provides performance tuning information for IBM SecureWay Directory. Tuningconsiderations for directory sizes ranging from a few thousand entries tomillions of entries are given where applicable.

For more information about IBM SecureWay Directory, see the following Web site:

http://www.software.ibm.com/network/directory/library/

IBM WebSphere Application ServerIBM WebSphere Application Server, Advanced Single Server Edition 4.0.2, isinstalled with the Web portal manager interface. For information about IBMWebSphere Application Server, see the following Web site:

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

Accessing publications onlinePublications in the product library are included in Portable Document Format(PDF) on the product CD. To access these publications using a Web browser, openthe infocenter.html file, which is located in the /doc directory on the product CD.

When IBM publishes an updated version of one or more online or hardcopypublications, they are posted to the Tivoli Information Center. The TivoliInformation Center contains the most recent version of the publications in theproduct library in PDF or HTML format, or both. Translated documents are alsoavailable for some products.

You can access the Tivoli Information Center and other sources of technicalinformation from the following Web site:

http://www.tivoli.com/support/documents/

Information is organized by product, including release notes, installation guides,user’s guides, administrator’s guides, and developer’s references.

Note: If you print PDF documents on other than letter-sized paper, select the Fit topage check box in the Adobe Acrobat Print dialog (which is available whenyou click File → Print) to ensure that the full dimensions of a letter-sizedpage are printed on the paper that you are using.

xvi IBM Tivoli Access Manager: Base Administrator’s Guide

Ordering publicationsYou can order many Tivoli publications online at the following Web site:

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

You can also order by telephone by calling one of these numbers:v In the United States: 800-879-2755v In Canada: 800-426-4968v In other countries, for a list of telephone numbers, see the following Web site:

http://www.tivoli.com/inside/store/lit_order.html

Providing feedback about publicationsWe are very interested in hearing about your experience with Tivoli products anddocumentation, and we welcome your suggestions for improvements. If you havecomments or suggestions about our products and documentation, contact us in oneof the following ways:v Send an e-mail to [email protected] Complete our customer feedback survey at the following Web site:

http://www.tivoli.com/support/survey/

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

Contacting customer supportIf you have a problem with any Tivoli product, you can contact Tivoli CustomerSupport. See the Tivoli Customer Support Handbook at the following Web site:

http://www.tivoli.com/support/handbook/

The handbook provides information about how to contact Tivoli CustomerSupport, depending on the severity of your problem, and the followinginformation:v Registration and eligibilityv Telephone numbers and e-mail addresses, depending on the country in which

you are locatedv What information you should gather before contacting support

Conventions used in this bookThis guide uses several conventions for special terms and actions, operatingsystem-dependent commands and paths, and margin graphics.

Typeface conventionsThe following typeface conventions are used in this book:

Preface xvii

Bold Command names and options, keywords, and other informationthat you must use literally appear in bold.

Italic Variables, command options, and values you must provide appearin italics. Titles of publications and special words or phrases thatare emphasized also appear in italics.

Monospace Code examples, command lines, screen output, file and directorynames, and system messages appear in monospace font.

xviii IBM Tivoli Access Manager: Base Administrator’s Guide

Chapter 1. Access Manager overview

Access Manager is a complete authorization solution for corporate Web,client/server, IBM Tivoli Access Manager Access Manager applications, and legacy(pre-existing) applications. Access Manager authorization allows an organization tosecurely control user access to protected information and resources. By providing acentralized, flexible, and scalable access control solution, Access Manager allowsyou to build highly secure and well-managed network-based applications ande-business infrastructure.

This chapter contains the following sections:v “Securing the enterprise network” on page 1v “Access Manager — core technologies” on page 3v “Understanding authorization: conceptual model” on page 5v “The Access Manager authorization service” on page 8v “Implementing a network security policy” on page 11v “The Access Manager authorization API” on page 16v “External authorization capability” on page 20v “Access Manager Base certificate and password management” on page 24

Securing the enterprise networkMany organizations now value the public Internet and private intranets as effectiveand vital mediums for global communication. Electronic commerce, or e-business,has rapidly become an essential component of many business marketing strategies.Educational institutions rely on the Internet for long-distance learning. Onlineservices allow individuals to send electronic mail and to tap the Web’s vastencyclopedia of resources. Traditional applications, such as TELNET and POP3,still prevail as important network services.

Businesses are realizing that they can use Internet technologies to enhance supplychain relationships, facilitate collaboration with business partners, and provideincreased customer connectivity—provided they can expose corporate resourceswith a high degree of security. Businesses want to use the Internet as a globalcommercial and distribution vehicle, but have been hindered by the lack of provensecurity policy mechanisms and management systems.

Access Manager is an information policy management solution that providesorganizations with centralized network security services—where you canconsistently implement and maintain corporate security policy.

Access Manager provides the three primary requirements for balanced securitysolution:v Provides a variety of solutions for creating a highly secure network environmentv Provides convenient and intuitive management tools for secure centralized

administrationv Provides security mechanisms that do not hinder permitted client activity on the

network

1

Network security — common concernsBoth the world-wide public Internet and company-private intranets connect toheterogeneous computer systems, applications, and networks. This mixture ofdissimilar hardware and software usually impacts a network in the followingways:v No centralized control of security for applicationsv No unified resource location naming conventionv No common support for high availability of applicationsv No common support for scalable growth

New business models require organizations to expose their information resourcesto a previously unthought of degree. These businesses need to know that they cansecurely control access to those resources.

Managing policy and users across distributed networks has proven difficult forInformation Technology (IT) managers, especially since individual application andsystem vendors implement authorization in their own proprietary fashion.

Companies realize that developing new authorization services for each enterpriseapplication is an expensive process that leads to a difficult-to-manageinfrastructure. A centralized authorization service that is accessed by developersvia a standardized API could greatly speed time to market and reducetotal-cost-of-ownership.

A centralized network security management system needs to fulfill requirementsthat include:v Co-exist with and/or leverage existing firewall and authenticator architecturesv Integrate or co-exist with network and application management frameworksv Be application-independent

Introducing Access ManagerAccess Manager is a complete authorization and network security policymanagement solution that provides unsurpassed end-to-end protection of resourcesover geographically dispersed intranets and extranets.

In addition to its state-of-the-art security policy management feature, AccessManager supports authentication, authorization, data security, and resourcemanagement capabilities. You use Access Manager in conjunction with standardInternet-based applications to build highly secure and well-managed intranets.

At its core, Access Manager provides:v Authentication framework

Access Manager provides a wide range of built-in authenticators and supportsexternal authenticators.

v Authorization frameworkThe Access Manager authorization service, accessed via a standard authorizationAPI, provides permit and deny decisions on access requests for native AccessManager servers and third-party applications.

With Access Manager, businesses can now securely manage access to privateinternal network-based resources and leverage the public Internet’s broad

2 IBM Tivoli Access Manager: Base Administrator’s Guide

connectivity and ease of use. Access Manager, in combination with a corporatefirewall system, can fully protect the Enterprise intranet from unauthorized accessand intrusion.

The authorization service API standardAuthorization services are a critical part of an application’s security architecture.After a user passes the authentication process, authorization services proceed toenforce the business policy by determining what services and information the usercan access.

For example, a user accessing a Web-based retirement fund would be able to viewpersonal account information after an authorization server verifies the identity,credentials, and privilege attributes of that user.

The standards-based authorization API allows applications to make calls to 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.

Access Manager — core technologiesThe Access Manager network security management solution provides and supportsthe following core technologies:v Authenticationv Authorizationv Quality of Protectionv Scalabilityv Accountabilityv Centralized Management

AuthenticationAuthentication is the first step a client must take when making a request for aresource from a network protected by Access Manager. The authentication processis usually dependent on the specific requirements of the service-providingapplication. Access Manager allows a highly flexible approach to authenticationthrough the use of the authorization API.

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

Authorizationv Access Manager authorization servicev ACL and POP policies for fine-grained access controlv Standards-based authorization APIv External authorization service capability

Chapter 1. Access Manager overview 3

Quality of (data) protectionQuality of Protection is the degree to which Access Manager protects anyinformation transmitted between client and server. Quality of Protection isdetermined by the combined effect of encryption standards andmodification-detection algorithms.

Quality of Protection levels include:v Standard 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 StandardsAccess Manager supports the following encryption ciphers over SSL:v 40-bit RC2v 128-bit RC2v 40-bit RC4v 128-bit RC4v 40-bit DESv 56-bit DESv 168-bit triple DES

Secure communicationAccess Manager supports the data integrity and data privacy provided by theSecure Socket Layer communication protocol.

The Secure Socket Layer (SSL) handshake protocol was developed by NetscapeCommunications Corporation to provide security and privacy over the Internet.SSL works by using public key for authentication and secret key to encrypt datathat is transferred over the SSL connection.

Access Manager supports SSL versions 2 and 3.

ScalabilityScalability is the ability to respond to increasing numbers of users who accessresources in the secure domain. 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 (WebSEAL)– Mirrored resources for high availability– Load balancing client requests

v Back-end replicated servers (WebSEAL)– Back-end servers can be WebSEAL or third-party application servers– Mirrored resources (unified object space) for high availability


– Additional content and resources– Load balancing of incoming requests through junctions

v Optimized performance by allowing the off-loading of authentication andauthorization services to separate servers

v Scaled deployment of services without increasing management overhead

AccountabilityAccess Manager provides a number of logging and auditing capabilities. There arelog files that capture any error and warning messages generated by AccessManager servers. There are also audit trail files that monitor Access Managerserver activity.

Log files:v Access Manager server log filesv Serviceability messagesv Standard HTTP log files

Audit trail files:v Access Manager server audit trail files

Centralized managementv Web portal managerv pdadmin command line utility

Understanding authorization: conceptual modelWhen servers enforce security in a secure domain, each client must provide proofof its identity. In turn, security policy determines whether that client is permittedto perform an operation on a requested resource. Because access to every resourcein a secure domain is controlled by a server, the server’s demands forauthentication and 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 secure domain. Authentication ensures that theindividual is who he claims to be, but says nothing about the rights to performoperations on a protected resource.

In the Access Manager authorization model, authorization policy is implementedindependently of the mechanism used for user authentication. Users canauthenticate 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 secure domain receive a level of protection as dictated by thesecurity policy for the domain. The security policy defines the legitimateparticipants of the secure domain and the degree of protection surrounding eachresource requiring protection.


The basic components of the authorization process, as shown in Figure 1, include:v A resource manager responsible for implementing the requested operation when

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

v An 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 Access Manager WebSEAL andthird-party applications.

The independent functionality of these authorization components allows muchflexibility in 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 legacy 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 would include:

ResourceManager

AuthenticatedClient

AuthorizationCheck

Yes / No

Request forResource

AuthorizationService

PolicyEnforcer

Resources

ApplicationServer

Figure 1. General authorization model


v Reduced cost of developing and managing access to applicationsv Reduced total cost of ownership and management of separate authorization

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

Introducing the Access Manager authorization serviceAccess Manager integrates into existing legacy and emerging infrastructures andprovides secure, centralized policy management capability. The Access Managerauthorization service—together with resource managers (such asWebSEAL)—provides a standard authorization mechanism for business networksystems.

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 (See “The Access Manager authorization API” on page 16)allows existing applications to make calls to the authorization service which inturn makes decisions based on the corporate security policy.

The Access Manager authorization service is also extensible and can be configuredto call on other authorization services for additional processing using the externalauthorization service plug-in interface.

Access Manager authorization service benefitsThe 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 privilegedatabase in one 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-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.

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.


The Access Manager authorization serviceThe Access Manager authorization service is responsible for the authorizationdecision-making process that helps to enforce a network security policy.Authorization decisions made by the authorization service result in the approval ordenial of client requests to perform operations on protected resources in the securedomain.

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

Master authorization policy databaseThe master authorization policy database contains the security policy informationfor all resources in the secure domain. The database also contains all necessarycredential information associated with the participants of the secure domain.

You use the Web portal manager to enter and modify the contents of this database.

Policy server (pdmgrd)The policy server maintains the master authorization policy database, replicatesthis policy information throughout the secure domain, and updates the databasereplicas whenever a change is made to the master.

The policy server also maintains location information about the other AccessManager and non-Access Manager servers operating in the secure domain.

Note: There must be only one instance of the policy server in any secure domain.

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

Registry database replication parameters are configurable for each evaluator.

Figure 2 on page 9 illustrates the main components of the authorization service:


Authorization service interfacesThe authorization service has two interfaces where interaction takes place:v Management interface — The security administrator manages the security

policy of the network by using the Web portal manager (and/or the pdadminutility) to apply policy rules (templates) on network resources and register thecredentials of participants in the secure domain.The Web portal manager applies this security policy data to the masterauthorization policy database via the policy server.This interface is complex and involves detailed knowledge of the object space,policy templates, and credentials.

v Authorization API — The authorization API passes requests for authorizationdecisions from the resource manager to the authorization evaluator which thenpasses back a recommendation. The Access Manager Authorization ADK DeveloperReference contains the details of this API.

Authorization Service

PolicyServer

( )pdmgrdMaster

AuthorizationPolicy

AuthorizationEvaluator

AuthAPI

ResourceManager

Web PortalManager

ReplicaAuthorization

Policy

ManagementInterface

Figure 2. Authorization service components


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. Applications that call theauthorization service have two options for referencing this database information:v The application — when configured to work seamlessly with the authorization

evaluator — uses a local cache of the databaseThe database is replicated for each application that uses the authorization servicein 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.

Update notification from the policy server (whenever a change has been made tothe master authorization policy database) triggers the caching process to update allreplicas.


PolicyServer

( )pdmgrdMaster

AuthorizationPolicy


AuthAPI

ResourceManager

Web PortalManager


Policy

ManagementInterface

Figure 3. Authorization service: interfaces


Performance notesv In addition to update notifications direct from the policy server, the application

servers also check the version of the master authorization policy database everyfew minutes to ensure they have not missed an update notification.If an update notification fails to reach a server, a log entry is created. In bothcases a retry mechanism also ensures 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 policytemplate in its own cached version of the database. WebSEAL does not have toaccess the network to obtain this information from the master database. Theresult is very fast response 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 secure domain is determined by controlling user andgroup participation in the domain and applying rules, known as access control list(ACL) policies and protected object policies (POP), to resources requiringprotection. The authorization service enforces these policies by matching a user’scredentials with the permissions in the policy assigned to the requested resource.The resulting recommendation is passed to the resource manager which completesthe response to the original request.

Defining the network security policyThe authorization service uses a central database that lists all resources in thesecure domain and the ACL and POP policies assigned to each resource. Thismaster authorization policy database and the user registry (containing user andgroup accounts) are the key components that help define a network security policy.

In summary, a network security policy controls:1. Users and groups allowed to participate in the secure domain

The user registry maintains this information.


Policy


Policy


PolicyServer

(pdmgrd)Master

AuthorizationPolicy

Web PortalManager


AuthAPI

ResourceManager


Policy

Figure 4. Replicated authorization service components


2. The level of protection on all objects in the secure domainThe master authorization policy database maintains this information.

The protected object spaceThe protected object space is a hierarchical portrayal of resources belonging to asecure domain. The objects that appear in the hierarchical object space representthe actual network resources.v System resource — the actual physical file or application.v Protected object — the logical representation of an actual system resource used

by the authorization service, the Web portal manager, and other Access Managermanagement utilities.

Policy templates can be attached to objects in the object space to provide protectionof the resource. The authorization service makes authorization decisions basedthese templates.

The following object space categories are used by Access Manager:v Web objects

These objects represent anything that can be addressed by an HTTP URL. Thisincludes static Web pages and dynamic URLs that are converted to databasequeries or some other type of application.

v Access Manager management objects

These objects represent the management activities that can be performed via theWeb portal manager. The objects represent the tasks necessary to define usersand set security policy. Access Manager supports delegation of managementactivities and can restrict an administrator’s ability to set security policy to asubset of the object space.

v User-defined objects

These objects represent customer-defined tasks or network resources protectedby applications using the authorization service via the authorization API.

Defining and applying ACL and POP policiesSecurity administrators protect system resources by defining rules, known as ACLand POP policies, and applying these policies to the object representations of thoseresources in the object space.

ManagementObjects

WebObjects

User-DefinedObjects

Figure 5. Access Manager protected object space


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

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

Explicit and inherited policyPolicy can be explicitly applied or inherited. The Access Manager protected objectspace supports inheritance of ACL and POP attributes. This is an importantconsideration for the security administrator who manages the object space. Theadministrator only needs to apply explicit policies at points in the hierarchy wherethe rules must change.

Examples of types of policy include:v Hard-coded rulesv External authorization capabilityv Special secure labelingv Access control lists (ACLs)

The access control list (ACL)An access control list policy, or ACL policy, is the set of controls (permissions) thatspecifies the conditions necessary to perform certain operations on that resource.ACL policy definitions are important components of the security policy establishedfor the secure domain. ACL policies, like all policies, are used to stamp anorganization’s security standards onto the resources represented in the protectedobject space.

An ACL policy specifically controls the following:1. What operations can be performed on the resource2. Who can perform these operations

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

ManagementObjects

WebObjects

User-DefinedObjects

Explicit RuleInherited

Rule

Figure 6. Explicit and inherited policies


Protected object policies (POP)ACL policies provide the authorization service with information to make a yes orno answer on a request to access a protected object and perform some operation onthat object.

POP policies contain additional conditions on the request that are passed back toAccess Manager Base and the Resource Manager (such as WebSEAL) along withthe yes ACL policy decision from the authorization service. It is the responsibilityof Access Manager and the Resource Manager to enforce the POP conditions.

Available attributes for a POP are listed as follows:

Enforced by Access Manager Base

POP attribute Description

Name Name of the policy. This becomes the pop_name in thepdadmin pop commands.

Description Descriptive text for the policy. This appears in the popshow command.

Warning Mode Provides administrators a means to test ACL and POPpolicies.

Audit Level Specifies type of auditing: all, none, successful access,denied access, errors.

Time-of-Day Access Day and time restrictions for successful access to theprotected object.

Enforced by Resource Manager (such as WebSEAL)

POP attribute Description

Quality of Protection Specifies degree of data protection: none, integrity,privacy.

IP Endpoint AuthenticationMethod Policy

Specifies authentication requirements for access frommembers of external networks.

Policy administration: The Web portal managerThe Web portal manager is a Web-based graphical application used to managesecurity policy in a secure domain. The pdadmin command line utility providesthe same user and group administration capabilities as the Web portal manager,plus many commands not supported by the Web portal manager.

Figure 7. ACL policy


From the Web portal manager (or pdadmin), you can manage the user registry, themaster authorization policy database, and the Access Manager servers. You canalso add and delete users / groups and apply ACL and POP policies to networkobjects.

The authorization process: step-by-stepFigure 9 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.

SecurityServer

Web PortalManager

Windows NT

Workstation

MasterAuthorization

Policy

UserRegistry

PolicyServer

Apply policies on theprotected object space

Create, modify, anddelete user and group

accounts

Figure 8. Web portal manager: Administration of the security policy

Client


Secure Domain

AuthorizationPolicy

Protected ObjectSpace

2. Request forAuthorization

(AuthAPI)

5. AuthorizedOperation

1. Request

6. Response

3. AuthorizationCheck

4. AuthorizationDecision(AuthAPI)

Resources

/

ResourceManager

PolicyEnforcer

Figure 9. The Access Manager authorization process


The resource manager can be WebSEAL (for HTTP, HTTPS access) or athird-party application.

2. The policy enforcer process uses the authorization API (See “The AccessManager authorization API”) to call the authorization service for anauthorization decision.

3. The authorization service performs an authorization check on the resource,represented as an object in the protected object space. Base POP policies arechecked first. Next the ACL policy attached to the object is checked against theclient’s credentials. Then, POP policies enforced by the resource manager arechecked.

4. The decision to accept or deny the request is returned as a recommendation tothe resource manager (via 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.

The Access Manager authorization APIThe Access Manager Authorization Application Programming Interface (API)allows Access Manager applications and third-party 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 the policy-enforcing application to ask for an authorization decision, butshields the application from the complexities of 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 legacyor newly developed application.

The authorization API can be used in one of two modes:v Remote cache mode

In this mode, the API is initialized to call the (remote) authorization server(pdacld) to perform authorization decisions on behalf of the application. Theauthorization server maintains its own cache of the replica authorization policydatabase. This mode is recommended for handling authorization requests fromapplication clients.(See “Authorization API: remote cache mode” on page 18)

v Local cache mode

In this mode, the API is initialized to download and maintain a local replica ofthe authorization database for the application. Local cache mode provides betterperformance because the application performs all authorization decisions locallyinstead of across a network. However, the overhead of database replication andthe security implications of using this mode make it best suited for use bytrusted application servers, such as WebSEAL.(See “Authorization API: local cache mode” on page 19)

One of the primary values and benefits of the authorization API is its ability toshield the user from the complexities of the authorization service mechanism itself.Issues of management, storage, caching, replication, credential formats, andauthentication 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: two examplesThird-party applications can use the authorization API to perform access control onvery specific and specialized processes.

Example 1:

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

Example 2:

Another use of the authorization API is demonstrated in the following figure,illustrating a request for a CGI transaction by a Web application.

The lowest level of authorization, as illustrated in Figure A of Figure 10 on page 18,involves an “all-or-nothing” access control on the URL. This coarse-grained level ofauthorization only determines if the client can run the CGI program. If access isallowed to the CGI application, no further control is available to resourcesmanipulated by the CGI application.

As illustrated in Figure B of Figure 10 on page 18, access controls have been set onresources that the CGI program manipulates. The Web application is configured touse the authorization API. Now the CGI program can call the authorization serviceto make authorization decisions on the resources it manipulates — based on theidentity of the requesting client.


Authorization API: remote cache modeIn remote cache mode, applications use the function calls provided by theauthorization API to communicate to the (remote) authorization server (pdacld).The authorization server functions as the authorization decision-making evaluatorand maintains its own replica authorization policy database.

The authorization server makes the decision and returns a recommendation to theapplication via the API. The server can also write an audit record containing thedetails of the authorization decision request.

There must be an authorization server running somewhere in the secure domain.The authorization server can reside on the same machine as the application, or onanother machine. You can also install the authorization server on more than onemachine in a secure domain to allow for high availability. The authorization APIwill transparently fail-over when a particular authorization server fails.

WebSEAL

Client

WebApplication

ObjectsManipulated

by CGI


WebSEAL

Client

WebApplication

ObjectsManipulated

by CGI


Figure A

Figure B

Fine-grainedAuthorized

AccessRequest

Response

Request

Response

Coarse-grainedAccess

API

Function Call

Figure 10. Example use of the authorization API


Authorization API: local cache modeIn local cache mode, the API downloads and maintains a replica of theauthorization policy database on the application’s local file system. It performs allauthorization decisions in-memory, which results in higher performance and betterreliability.

You must manually register any application using the authorization API in localcache mode with the authorization service. The policy server must know thelocation of any local cache mode authorization API application so it can update thereplica authorization policy database associated with it.

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

Third-PartyApplication


Policy

AuthenticatedClient

Resources

pdacld

Figure 11. authorization API: remote cache mode


External authorization capabilityIn some situations, the standard Access Manager policy implementations—AccessControl Lists and Protected Object Policies—might not be able to express all theauthorization rules required by an organization’s security policy. Access Managerprovides optional external authorization capability to accommodate any additionalauthorization 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 Access Managerauthorization service. If you configure an external authorization service, the AccessManager authorization service simply incorporates the access decision paths intoits evaluation process.

Applications 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 anorganization’s existing security service. An external authorization service preservesa company’s initial investment in security mechanisms by allowing legacy serversto be incorporated into the Access Manager authorization decision-making process.


PolicyServer

(pdmgrd)Master

AuthorizationPolicy


AuthAPI

WebSEALor

Third-Party


Policy

AuthenticatedClient

Resources

Figure 12. Authorization API: local cache mode


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 Cause an external auditing mechanism to record the successful or unsuccessful

access attemptv Actively monitor the access attempt and cause an alert or alarm whenever

unacceptable behavior is detectedv Billing / micro-payment transactionsv Impose 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 the course of an access decision, the

external authorization services that have been configured for that condition areeach called in turn to evaluate their own external authorization constraints.Invocation of the external authorization service occurs regardless of whether ornot the necessary permission is granted to the user by the 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 Access Manager authorization service. The resulting decision isreturned to the caller.

ExampleFigure 13 on page 22 illustrates an authorization decision involving a WebSEALserver and an external authorization service.


In this example, the purpose of the external authorization service is to impose aquota restriction on how often the 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 has been attached to the photo printer resource so that theexternal authorization service is invoked anytime that the photo printer isaccessed.

The external authorization service has been loaded with the default decisionweighting of 101, which overrides any decision made by the Access Managerauthorization service, should it need to do so.1. The WebSEAL 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 WebSEAL server first consults the Access Manager authorization service todetermine whether the requesting user has permission to submit jobs to theprinter.

3. The authorization service checks the access permissions on the target requestedobject and compares these with the capabilities of the requesting user: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 authorization servicegrants the user permission to submit the job.

4. Since the photo printer resource is being accessed and an external authorizationservice trigger condition was attached to this object, a request is also made tothe 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 AuthorizationResult (denied -101)

4. ExternalAuthorization

Check

Authzn API

Figure 13. External authorization service with WebSEAL


The external authorization service receives all of the Access DecisionInformation (ADI) that was passed in with the original access decision check byWebSEAL.

5. The external authorization service consults the record of previous accessesmade by this user. If the requesting user has not exceeded their quota for theweek, it returns 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 their quota, then the external authorizationservice returns a decision of “access denied”.For this example, it is assumed that the requester has exceeded their quota andthat the external authorization service detects this and returns an “accessdenied” decision.

6. The Access Manager authorization service receives the “access denied” resultfrom the external authorization service. It then takes this decision and weightsit with the default external authorizations service weighting value of 101.The results of the external authorizations service decision and the decisionmade by the Access Manager authorizations service are combined. The result is“access denied” because the result of the external authorizations service (-101)outweighs that of the Access Manager authorization service (100).

7. The WebSEAL server rejects the job submission to the photo printer resource.8. The WebSEAL server returns a response to the caller to indicate that the job

was rejected.

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

interface that can be referenced during authorization decisions.2. Register the external authorizations service with Access Manager so that Access

Manager authorization clients can load the plug-in service at initialization time.

Registering the service sets a trigger condition for the invocation of the externalauthorizations service. When the trigger condition is encountered during anauthorization check, the external authorizations service interface is invoked tomake an additional authorization decision.

Refer to the Access Manager Authorization API Developer Reference for advanceddetails on implementing an external authorizations service.

Deployment strategiesAccess Manager allows you to implement an external authorizations service inseveral ways:v Any number of external authorization servers can be added to your secure

domain to perform a variety of authorization evaluations. Each externalauthorizations service is loaded into the individual local-mode authorization APIclient application. Applications that can load external authorizations servicesinclude WebSEAL (webseald), the authorization server (PDAcld), other AccessManager servers, and any authorization applications written by the customer.

v Remote-mode authorization API clients, which make requests to theauthorization server for authorization decisions, automatically make use of anyexternal authorizations service that are loaded by the authorization server.


v More than one external authorizations service can be called for any single triggercondition. In this case, the results of each external authorizations service isweighted accordingly and then the results are combined with the result of theAccess Manager authorizations service.

v Trigger conditions can be placed upon objects, using a Protected Object Policy(POP) trigger, such that any request to an object, regardless of the operation thatis being requested, triggers a call to the external authorizations services that areconfigured for the trigger.

v Trigger conditions can also be placed upon the operations requested by a user.For example an external authorizations service can be triggered specificallywhen a user requests a write operation to a protected resource, but not for anyother operation. It is then possible to develop sets of operations for which one ormore external authorizations services in combination are triggered according theset of operations requested.

v The external authorizations services are implemented as dynamically loadablelibrary (DLL) modules. This greatly simplifies the task of external authorizationsservice development. There is no requirement to make remote requests to theexternal authorizations service and the overhead of making the call is equivalentto the overhead of a function call.

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

Access Manager Base certificate and password managementThe Access Manager Base components use SSL for encryption, systemauthentication, and application-level authentication. SSL uses certificates foroperation. In the secure environment, pdmgrd acts as the certificate authority (CA)and is responsible for the creation and renewal of certificates. The Access Managerruntime (pdrte) only relies upon SSL server side authentication and as such, doesnot require a client-side certificate. However, all of the Access Manager serverssuch as pdmgrd, pdacld, and aznAPI servers (like WebSEAL) rely on client-sidecertificates to operate.

The servers use certificates to authenticate themselves. For example, when pdacldis communicating with pdmgrd, it presents its client-side certificate. In thisexample, pdmgrd can be considered the server and pdacld as the client. Thepdmgrd server verifies that the certificate is valid and is signed by a trusted signer(in this case pdmgrd itself, using the PDCA certificate). The pdacld server does thesame for the certificate presented by pdmgrd. As part of the Access Managerapplication-level authentication, after pdmgrd determines that the pdacldcertificate is good, it tries to map that certificate to an Access Manager principal. Ifthe authentication succeeds, then the servers can begin communicating.

The certificates used by Access Manager are kept in keyring database files (thesehave a .kdb extension). These files should be secured and protected by the strictestoperating system controls available because they contain the private keys for thecertificates in question. For example, the keyring database file for pdmgrd isivmgrd.kdb and by default it is only readable and write-able by the ivmgr user andthe ivmgr group.

Furthermore, to facilitate unattended server operation, there are files that containan obfuscated (not encrypted) version of the password to the keyring databasefiles. These are called stash files which are denoted by a .sth file extension. Again,


these files should be secured using OS measures. For pdmgrd, the stash file isivmgrd.sth and its permissions are the same as ivmgrd.kdb.

For security reasons, both the certificates and the keyring database file passwordscan be set to expire after a configurable amount of time. The default lifetime for acertificate is 365 days. The default lifetime for a keyring database file password is183 days. The fixed lifetime for the PDCA certificate is 20 years. Also by default,the Access Manager components perform self-care; that is, they refresh thecertificates and passwords automatically while they are running.

However, if the servers are not running within a specified window of time, theircertificates or passwords can expire. If this is the case, a manual refresh isnecessary. Furthermore, if a certificate, password, or entire keyring database file iscorrupted, then to keep the Access Manager domain secure, a manual refresh isalso warranted.

Initial configurationThe certificates used by the Access Manager components are created as part oftheir initial configurations. In a brand new Access Manager installation, thepdmgrd server is the first server configured. As part of its configuration, thePDCA certificate is created and a personal certificate used by pdmgrd is createdand signed by the PDCA certificate. Both of these certificates reside in theivmgrd.kdb keyring database file. Also, as part of the pdmgrd configuration, theruntime keyring database file, pd.kdb, is created and the PDCA certificate isinserted into it as a trusted certificate.

When new systems are added to the Access Manager domain, pdrte is configuredfirst. Again, as part of this configuration, the system pd.kdb and pd.sth files arecreated and the PDCA certificate is included in the keyring database file as atrusted certificate.

When new aznAPI servers (such as pdacld or WebSEAL) are configured, the runthe svrsslcfg command. This tool creates a keyring database file (such aspdacld.kdb) and places a personal certificate for the server in it. The tool alsoinserts the PDCA certificate as a trusted certificate in the keyring database file.These two certificates are obtained from pdmgrd and are transported to the clientmachine over SSL using the runtime keyring database file.

Keyring database file and stash file renewal informationThe following table lists the components and their associated keyring and stashfiles. It also describes how they get created and refreshed.

Component Keyring/StashFile

How it getscreated

Processes thatautomaticallyupdates thekeyring fileand/or password

Tool for manualupdate

pdrte pd.kdb pd.sth(does notcontain aclient-sidecertificate)

During the pdrteconfiguration

Invocations ofpdadmin1

bassslcfg-chgpwd


Component Keyring/StashFile

How it getscreated

Processes thatautomaticallyupdates thekeyring fileand/or password

Tool for manualupdate

pdmgrd ivmgrd.kdbivmgrd.sth

During pdmgrdconfiguration

Runningpdmgrd1,2

mgrsslcfg-chgpwd3andmgrsslcfg-chgcert3

pdacld ivacld.kdbivacld.sth

During pdacldconfiguration

Running pdacld1 svrsslcfg-chgpwd4 andsvrsslcfg-chgcert5

aznAPI server(such asWebSEAL)

aznAPI.kdbaznAPI.sth(name isconfigurable)

Runningsvrsslcfg -config

Runninginstance of theaznAPI server1

svrsslcfg-chgpwd6andsvrsslcfg-chgcert7

Notes:v 1 - Automatic certificate and password refresh can be turned off by setting the

attribute [ssl], ssl-auto-refresh to no in the respective configuration (.conf) file.v 2 - Because pdmgrd also acts as the CA for the secure domain, it must be

recycled after a refresh. It continues to operate normally until it is recycled,except it is not be able to issue or renew certificates for other servers until it isrecycled. The pdmgrd.log file contains a message stating when the server needsto be restarted.

v 3 - Before running this command, the pdmgrd server must be stopped.v 4 - Before running this command, the pdacld server must be stopped.v 5 - Before running this command, the pdmgrd server must be running and the

pdacld server must be stopped.v 6 - Before running this command, the aznAPI server must be stopped.v 7 - Before running this command, the pdmgrd server must be running and the

aznAPI server must be stopped.

Determining trustEach of the keyring database files also contains a list of trusted CAs. For AccessManager, every keyring database file (except ivmgrd.kdb) has the PDCA certificateas a trusted CA. The CA is the certificate that is used to sign all of the other AccessManager certificates. This CA is created during pdmgrd configuration and isplaced in the ivmgrd.kdb file. It is extremely important to protect the ivmgrd.kdbfile to keep the PDCA certificate’s private key from being compromised. If it iscompromised, then it must be regenerated. It this happens, then every keyringdatabase file and every certificate in the secure domain needs to be regenerated aswell. The steps for performing this action are:1. Regenerate the PDCA certificate (and pdmgrd server certificate) by generating a

new ivmgrd.kdb file using mgrsslcfg -unconfig and then mgrsslcfg -config(pdmgrd must be stopped).

2. Regenerate all pdrte runtimes within the domain by first running bassslcfg-unconfig. Next, obtain the CA certificate. If auto-download of the CAcertificate is on and pdmgrd is running, then the CA certificate is obtained byrunning bassslcfg -getcacert -h pdmgrd hostname -c certificate file name. Ifauto-download is off, then the base-64 DER encoded version of the PDCA


certificate must be hand copied to the machine. This file is stored aspdcacert.b64 on the pdmgrd machine. Finally, run bassslcfg -config tocomplete the pdrte configuration.

3. Regenerate any pdacld keyring files within the domain by running svrsslcfg-chgpwd and svrsslcfg -chgcert (pdmgrd must be running). These commandsupdate both the server certificate for pdacld and its trusted certificate (the newPDCA certificate).

4. Regenerate any other aznAPI server keyring files within the domain byrunning svrsslcfg -chgpwd and svrsslcfg -chgcert (pdmgrd must be running).These commands update both the server certificate for the server and itstrusted certificate (the new PDCA certificate).

Certificate RevocationIf a server’s keyring database file or certificate is compromised, it can be revokedby running the appropriate chgcert command. This effectively generates a newcertificate making the old certificate invalid. For example, if a pdacld has itscertificate compromised then running svrsslcfg -chgcert generates a new certificatefor that file and makes the compromised certificate invalid. Also, by running theappropriate sslcfg -unconfig command, a certificate no longer authenticates withinAccess Manager.

Additional considerationsAdditional considerations for keyring database file and stash file renewal are asfollows:v If a certificate and the password to the keyring database file containing that

certificate are both expired, then the password must be refreshed first. Forexample, for pdacld, run svrsslcfg -chgpwd and then svrsslcfg -chgcert. This isnecessary because a valid password is needed to open the keyring database fileto get to the certificate.

v The value for the lifetime of a certificate is controlled by the value of theivmgrd.conf, [ssl], ssl-cert-life attribute when pdmgrd is started. Any certificatesissued or renewed uses this value. To increase or decrease this value, change thevalue and restart pdmgrd. The new value is only in effect for certificates issuedor renewed from that point on.

v For automatic password renewal, the value for the lifetime of a password iscontrolled by the value of the [ssl], ssl-pwd-life attribute in effect when the serveris started. For manual password renewal, the value is dictated by the valuesupplied to the chgpwd command. This value is also written into theappropriate configuration file.

v Access Manager servers can also communicate with LDAP using SSL. In thestandard configuration, this communication uses server-side authentication only.Therefore, the Access Manager server only needs the CA certificate that signedthe LDAP server certificate or the LDAP server certificate itself. The expirationand management of these certificates is not handled by Access Manager.However, it is possible to include the LDAP certificate in the keyring databasefile for an aznAPI server by running svrsslcfg -config and using the -C option.

v After running bassslcfg -config, it may be necessary to change the permissionsof pd.kdb and pd.sth.

v The configuration files mentioned are generally found in thepd-install-directory/etc directory. For example, on AIX the pdmgrd, pdacld,and runtime configuration files are found in/opt/PolicyDirector/etc/ivmgrd.conf, /opt/PolicyDirector/etc/ivacld.conf,


and /opt/PolicyDirector/etc/pd.conf respectively. Similarly, the keyringdatabase files and stash files can be found in the pd-install-directory/keytabsdirectory.


Chapter 2. Managing the protected object space

A secure domain contains physical resources that usually need some level ofprotection. Resources can include files, directories, and printer services. AccessManager uses a virtual representation of these resources called the protected objectspace.

Resources can be protected by attaching ACL and POP policies to the objectrepresentations of these resources. This chapter discusses the protected object spaceand how you can create extensions to the object space to support customapplication requirements.

This chapter contains the following sections:v “Understanding the protected object space” on page 29v “Defining a database object space” on page 31

Understanding the protected object spaceThe Access Manager security model depends on ACL and POP policies to providefine-grained protection for these resources. A corporate security policy isimplemented by the strategically applying custom ACL and POP policies to thoseresources requiring protection. The Access Manager authorizations service makesdecisions to permit or deny access to resources based on user credentials and thespecific permissions and conditions set in the ACL and POP policies.

In order to apply ACL and POP policies and allow the authorizations service toperform its security checks, Access Manager uses a virtual object representation ofsecure domain resources called the protected object space.

As a Access Manager security administrator, you can use the Web portal manageror the pdadmin utility to attach ACL and POP policies to the logical objects in theobject space.

Elements of the protected object spaceThe Access Manager protected object space is the logical and hierarchical portrayalof resources belonging to a secure domain. Objects that appear in the hierarchicalobject space represent actual physical network resources.v System Resource – the actual physical file, network service, or applicationv Protected Object – the logical representation of an actual system resource used

by the authorizations service, the Web portal manager, and other AccessManager management utilities

The protected object space uses two types of objects:v Container objects

Container objects are structural designations that allow you to organize theobject space hierarchically into distinct functional regions. Container objectscontain resource objects.

v Resource objects

29

Resource objects are the representations of actual network resources (such asservices, files, and programs) in your secure domain.

Protected object space hierarchyThe structural top, or start, of the protected object space is the root containerobject. The symbol for root is the forward slash ( / ).

The following object space categories follow the root object:v Web objects ( /WebSEAL container)

The WebSEAL container object is the root of the logical Web space of the securedomain. All HTTP operations are authorized against some object in this sub-tree.Web objects represent anything that can be addressed by a URL. This includesstatic Web pages and dynamic URLs that are converted to database queries orsome other type of application invocation by a Web-to-application gateway.

v Access Manager management objects ( /Management container)

The Management container object is the root of the logical space controlling allAccess Manager management operations. Management objects represent theservices required to define users and groups, and set security policy. These taskscan be performed using the Web portal manager or the pdadmin utility.Subdivisions of the /Management region include:– User management (/Users)– Group management (/Groups)– GSO management (/GSO)– Server management (/Server)– ACL policy (/ACL)– POP (/POP)– Configuration authorization control (/Config)– Third-party authorization control (/Action)– Authorization database replication control (/Replica)

Access Manager supports delegation of certain management activities and canrestrict an administrator’s ability to set security policy to a subset of the objectspace.

v User-defined objects

container objects

resource objects

Figure 14. Access Manager protected object space


These objects represent customer-defined tasks or network resources protectedby third-party applications that use the authorization API to make calls to theAccess Manager authorizations service.

User-defined object space for third-party applicationsAccess Manager can provide authorization services to any third-party applicationobject defined by the protected object space.

A region of the object space needs to be defined for each application that is usingAccess Manager. WebSEAL, for example, has its own object space (/WebSEAL).Access Manager stores management objects in the /Management object space.

These object spaces appear in a pdadmin objectspace list command:pdadmin> objectspace list

/WebSEAL/Management

Access Manager and third-party applications make calls to the authorizationsservice through the authorization API. Two necessary steps are required tointegrate a third-party application with the authorizations service:v Describe the third-party application object space.v Apply permissions on any objects requiring protection.

Optional “user-defined object” containers are regions of the protected object spacewhere you can create objects for third-party application. Before you can add newobjects, you must define a new object space container.

Defining a database object spaceAccess Manager allows you to extend its authorization services to objectsbelonging to a user-defined third-party object space. Two necessary steps arerequired to integrate a third-party object space with Access Manager:v Describe the third-party application’s object space to Access Manager.v Apply ACL and POP policies to any objects requiring protection.

WebSEAL Management

/ (root)

server1 server2

Web Objects

Action

Server Replica

User-Defined

ManagementObjects

User-DefinedObjects

Users

Groups

POP

GSO

Config

ACL

Figure 15. Regions of the Access Manager protected object space

Chapter 2. Managing the protected object space 31

The pdadmin objectspace commands allow you to easily create user-defined objectspace regions and manage the objects contained in these spaces. User-definedobject spaces created with these commands are dynamic because they can beupdated while Access Manager is running.

Creating a new user-defined container objectUse the pdadmin objectspace and object commands to manage user-defined objectspaces. The objectspace command creates a container type object.

Note: The default Access Manager object spaces (/WebSEAL and /Management)cannot be controlled with the pdadmin objectspace commands.

Syntax:pdadmin> objectspace create name description type

The object space name must begin with a forward slash (/).

The description appears in the Web portal manager.

The type can be one of the following categories:

Object Types

0 – unknown1 – secure domain2 – file3 – executable program4 – directory5 – junction6 – WebSEAL server7 – unused8 – unused

9 – HTTP server10 – nonexistent object11 – container object12 – leaf object13 – port14 – application container object15 – application leaf object16 – management object17 – unused

The type category is only used by the Web portal manager to display anappropriate icon with the object.

When creating an object, a type must be specified. You can select an appropriatecategory, or use type 0 for “unknown”.

For example:pdadmin> objectspace create /Test-Space “New Object Space” 14pdadmin> objectspace list

/WebSEAL/Management/Management/Users/Management/Groups/Test-Space

Administration notes:v It is best to create a separate object space for each third-party application.v You must define the new object space before you can add objects.v The root of the object space—created at the same time the object space is

defined—automatically has the ispolicyattachable attribute set.


Creating and deleting objectsOnce an object space has been created, you can populate it with objects.

Use the pdadmin objects commands to manage user-defined objects.pdadmin> object create name description type ispolicyattachable {yes|no}

An object has the following fields:

Argument Description

Name This is the fully qualified location of the object in the objectspace, beginning with an existing object space name.

Description The text description of the object.

Type The type of the object to be created. Used by the Web portalmanager to display an appropriate icon.

ispolicyattachable Indicates if a POP can be attached to the object. If set to “no”,the object inherits policy from above. Used to force childobjects to use the same policy as the parent.

For example:pdadmin> object create /Test-Space/folder1 “Folder 1” 14ispolicyattachable yes

pdadmin> object list /Test-Spacefolder1

pdadmin> object show /Test-Space/folder1Name: /Test-Space/folder1

Description: Folder 1Type: (Application Container Object) : 14Is Policy Attachable: yes

pdadmin> object create /Test-Space/folder2 “Folder 2” 14ispolicyattachable no

pdadmin> object listandshow /Test-SpaceName: folder1

Description: Folder 1Type: (Application Container Object) : 14Is Policy Attachable: yes

Name: folder2Description: Folder 2Type: (Application Container Object) : 14Is Policy Attachable: no

pdadmin> object delete /Test-Space/folder1pdadmin> object list /Test-Space

folder2

Administration notes:v Child objects are not moved when you change the name of a parent object.

Child objects can therefore be left without parent objects. You must move allchild objects when you change the name of a parent object.

v If the ispolicyattachable field is left out in the pdadmin object create command,the utility assumes that you intended to use the objectspace create command.An objectspace is created rather than an object.

Chapter 2. Managing the protected object space 33


Chapter 3. Using access control policies

Access Manager uses a virtual representation of the resources in the securedomain—called the protected object space. Resources can be protected by definingspecial security policies (rules) and attaching these policies to the objectrepresentation of this resource in the protected object space.

The policy type that defines who has access to an object, and what operations canbe performed on the object, is known as an access control list policy or ACLpolicy. ACL policies are used to help stamp an organization’s security policy ontothe resources belonging to the secure domain.

This chapter contains the following sections:v “Introducing the ACL policy” on page 35v “ACL entry syntax” on page 37v “How the authorizations service uses ACL policies” on page 39v “Evaluating an ACL” on page 41v “Sparse ACL model: ACL inheritance” on page 42v “Creating extended ACL actions and action groups” on page 46v “ACL policies and the protected object space” on page 49v “WebSEAL permissions” on page 50v “Management permissions” on page 51v “Object and object space permissions” on page 57v “Default administration ACL policies” on page 57

Introducing the ACL policyAn access control list policy (ACL) is a method used by Access Manager to providefine-grained protection to resources in the secure domain.

An ACL policy is a set of rules, or permissions, that specify the conditionsnecessary to perform an operation on a protected object. An ACL policy identifiesthe operations permitted on a protected object and lists the identities (users andgroups) who can perform those operations.v User and group identities are defined in the Access Manager registry.v The protected object space and ACL policies are defined in the master

authorization database.

Each ACL policy has a unique name, or label. Each ACL policy can be applied toone or more objects.

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

ACL policy entriesAn ACL policy consists of one or more entries describing:v The names of users and groups whose access to the object is explicitly controlledv The specific operations permitted to each user, group, or role

35

v The specific operations permitted to the special any-other and unauthenticateduser categories

A user represents any authenticated Access Manager identity. Typically, usersrepresent network users or application servers.

A group is a collection of one or more users. A network administrator can usegroup ACL entries to easily assign the same permissions to multiple users. Newusers to the secure domain gain access to objects by becoming members ofappropriate groups. This eliminates the need to create new ACL entries for everynew user. Groups can represent organizational divisions or departments within asecure domain. Groups are also useful in defining roles or functional associations.

Users and groups are collectively referred to as entities.

User and group entries in ACLs are actually stored using a universally uniqueidentifier (UUID). The UUID provides extra security in the case where a user orgroup 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, AccessManager allocates a new UUID to this user. Since the UUID is new, any existingACLs that reference the old user name do not grant any rights to the new user.Stale UUIDs in ACLs (from deleted users and groups) are silently removed by thepolicy server (pdmgrd).

You can use the pdadmin utility or the Web portal manager to create, modify, anddelete ACL entries.

Creating and naming ACL policiesYou can use the Web portal manager, or the pdadmin acl create command, tocreate a unique ACL policy and save it with a name. You can then apply securitypolicy by attaching the ACL to objects in the protected object space.

The ACL becomes a single source policy (like a formula or recipe) containing thespecific entries that provide the correct level of protection for all objects associatedwith it. If the security policy requirements change, you only edit the single ACL.The new security definition is instantly implemented for all objects affected by thatACL.

Figure 16. Access control list for a Web page object


ACL entry syntaxAn ACL entry contains either two or three attributes, depending on the ACL entrytype, and appears in the following format:

v Type – the entity category (user or group) for which the ACL was createdv ID (Identity) – the unique identifier (name) of the entity

The ID attribute is not required for the any-other and unauthenticated ACLentry types

v Permissions (or actions) – the set of operations permitted on the object by thisuser or group

Most permissions dictate the client’s ability to perform a specific operation on theresource.

In the above example, the user adam (type = user, ID = adam) has permission toread (view) the object protected by this ACL policy. The r permission allows theread operation. The T permission enforces the traverse rule.

Type attributeAn ACL entry type identifies the user, group, or special entity for a specific ACLentry. There are four ACL entry types.

Type Description

user Sets permissions for a specific user in the secure domain. The user must be a memberof the secure domain with an account in the registry. The user entry type requires auser name (ID). The entry format is: user ID permissions

For example:

user anthony -------T-----r-

group Sets permissions for all members of a specific group in the secure domain. The groupentry type requires a group name (ID). The entry format is: group ID permissions

For example:

group engineering -------T-----r-

any-other(also known asany-authenticated)

Sets permissions for all authenticated users. No ID designation is required. The entryformat is: any-other permissions

For example:

any-other -------T-----r-

ACL Entry user adam ---------T---r-

Type ID Permissions

Figure 17. ACL entry attributes

Chapter 3. Using access control policies 37

Type Description

unauthenticated Sets permissions for those users who have not been authenticated by the securityserver. No ID designation is required. The entry format is: unauthenticatedpermissions

For example:

unauthenticated -------T-----r-

This ACL entry is a mask (a bit-wise “and” operation) against the any-other ACL entryto determine the permission set. A permission for unauthenticated is granted only ifthe permission also appears in the any-other entry. For example, the followingunauthenticated ACL entry:

unauthenticated -------------rw

masked against this any-other ACL entry:

any-other -------T-----r-

results in these permissions:

-------------r- (read only).

ID attributeThe ACL entry ID is the unique identifier, or name, for a user or group entry type.IDs must represent valid users and/or groups created for the secure domain andstored in the registry database.

Examples:user michael

user anthony

group engineering

group documentation

group accounting

Note: The ID attribute is not used for the any-other and unauthenticated ACLentry types.

Permissions (actions) attributeEach ACL entry contains a set of permissions (or actions) that describe the specificoperations permitted on the object by the user or group

ACL policies control protected resources in the following ways:v A user’s ability to perform operations on protected objectsv An administrator’s ability to change access control rules on the object and any

sub-objectsv Access Manager’s ability to delegate user’s credentials

Note: ACL permissions are context-sensitive — the behavior of certain permissionsvaries according to the region of the protected object space in which they areapplied. For example, the m permission has a different meaning on aWebSEAL object than on a Management object.


Default Access Manager permissions (actions)Access Manager defines seventeen default permissions (actions). The Web portalmanager divides these permissions into three categories.

Base Generic WebSEALa A b B c g N t T W d m s v l r x

Action Bit Description Category

a Attach Base

A Add Base

b Browse Base

B Bypass Time-of-Day Base

c Control Base

d Delete Generic

g Delegation Base

l List Directory WebSEAL

m Modify Generic

N Create Base

r Read WebSEAL

s Server Administration Generic

t Trace Base

T Traverse Base

v View Generic

W Password Base

x Execute WebSEAL

Access Manager provides the capability to define many more additionalpermissions (actions) for use by third-party applications. See “Creating extendedACL actions and action groups” on page 46.

How the authorizations service uses ACL policiesAccess Manager relies on ACL policies to specify the conditions necessary toperform an operation on a protected object.

When an ACL is attached to an object, entries in the ACL specify what operationsare allowed on this object and who can perform those operations.

Access Manager uses a default set of permissions that cover a wide range ofoperations. Permissions are represented by single printable ASCII characters (a-z,A-Z). Each permission is displayed (by pdadmin or the Web portal manager) witha label describing the operation it governs. In addition, the Web portal managergroups the ACLs according to their use in a particular part of the object space(such as WebSEAL) or their use across the entire object space (Base, Generic).

Performing operations on an objectApplication software typically contains one or more operations that are performedon protected objects. Access Manager requires these applications to make calls into


the authorizations service before the requested operation is allowed to progress.This call is made via the authorization API for both Access Manager services (forexample, WebSEAL) and third-party applications.

The authorizations service uses the information contained in the ACL to make asimple yes or no response to the question: Does this user (group) have the rpermission (for example) to ‘view’ the requested object?

It is important to note that the authorizations service knows nothing about theoperation requiring the r permission. All it cares about is the presence, or not, ofthe r permission in the ACL entry of the requesting user or group.

This is actually a very powerful feature of the authorizations service. The service iscompletely independent of the operations being requested. This is why it is easy toextend the benefits of the authorizations service to third-party applications.

Requirements for custom permissionsDefault Access Manager permissions (actions) are available to third-partyapplications. If a third-party application makes use of a default Access Managerpermission, the associated operation should very closely match that of the actualoperation normally performed by Access Manager. For example, r should only beused by an operation that requires a read-only access to a protected object.

Note: Of course, a third-party application can use a default Access Managerpermission for a completely unrelated operation—because the authorizationsservice does not know or care about the operation. However, this situationwould cause difficulty for an administrator who would have to distinguishbetween two dissimilar uses of the same permission.

If a third-party application uses an operation that is not well represented by anythe default permissions, Access Manager allows you to define a new permission(action) that can be used by this application and recognized by the authorizationsservice.

See “Creating extended ACL actions and action groups” on page 46.

Custom action exampleIn this example, there is a requirement to protect a certain printer device fromunauthorized use. A third-party print spooling service is written with theauthorization API so that it can call the authorizations service to perform ACLchecks on requests made to the printer.

The standard Access Manager permissions do not include an obvious permissionfor protecting printers. However, the printer can be protected by a newly createdpermission (p in this example).

An ACL policy is attached to the printer object. If a user requests the use of theprotected printer, that user must have an ACL entry containing the p permission.The authorizations service returns a favorable response if the p permission ispresent and the printing operation proceeds. If the authorizations service finds noexistence of an p permission for that user, the printing operation is not allowed toproceed.


Evaluating an ACLAccess Manager follows a specific evaluation process to determine the permissionsgranted to a particular user by an ACL. When you understand this process, youcan determine how best to keep unwanted users from gaining access to resources.

Evaluating authenticated requestsAccess Manager evaluates an authenticated user request in the following order:1. Match the user ID with the ACL’s user entries. The permissions granted are

those in the matching entry.Successful match: evaluation stops here. Unsuccessful match: continue to the next step.

2. Determine the group(s) to which the user belongs and match with the ACL’sgroup entries:If more than one group entry is matched, the resulting permissions are a logical“or” (most permissive) of the permissions granted 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 match: evaluation stops here. Unsuccessful match: continue 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 requestsAccess Manager evaluates an unauthenticated user by granting the permissionsfrom the ACL’s unauthenticated entry.

The unauthenticated entry is a mask (a bitwise “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.

Since unauthenticated depends on any-other, it makes little sense for an ACL tocontain unauthenticated without any-other. If an ACL does containunauthenticated without any-other, the default response is to grant no permissionsto unauthenticated.

PrintSpoolerService


Printer ACL

AuthznPolicy

Database

API

user michael p

Can I use thisprinter?

"YES"

Figure 18. Custom print spooler action


Example ACL entriesYou set permissions for specific users and groups by specifying the appropriateACL entry type. In the following example, the group documentation has fullaccess privileges:group documentation --bcg--Tdmsv--lrx

You can restrict access to other authenticated users in the secure domain (notbelonging to the documentation group) by using the any-other entry type:any-other -------T-------rx

You can further restrict access to the unauthenticated entry type for users who arenot members of the secure domain.unauthenticated -------T-------r-

Note: Without an unauthenticated ACL entry, unauthenticated users cannot accessany secure documents within the secure domain.

Sparse ACL model: ACL inheritanceTo secure network resources in a protected object space, each object must beprotected by an access control list (ACL) policy.

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

the hierarchy.

Adopting an inherited ACL scheme can greatly reduce the administration tasks fora secure domain. This section discusses the concepts of inherited, or sparse ACLs.

Understanding the sparse ACL modelThe power of ACL inheritance is based on the following principle: any objectwithout an explicitly attached ACL policy inherits the policy of its nearestcontainer object with an explicitly set ACL. In other words, all objects withoutexplicitly attached ACLs inherit ACLs from container objects with explicitlyattached ACLs. A particular chain of inheritance is broken when you attach anexplicit ACL on an object.

ACL inheritance simplifies the task of setting and maintaining access controls on alarge protected object space. In a typical object space, you only need to attach afew ACLs at key locations to secure the entire object space — hence, a sparse ACLmodel.

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

When a region or sub-tree in the object space requires different access controlrestrictions, you attach an explicit ACL at the root of that sub-tree. This interruptsthe flow of inherited ACLs from the primary object space root to that sub-tree. Anew chain of inheritance begins from this newly created explicit ACL.


The default root ACL policyAccess Manager checks inheritance beginning with the root of the protected objectspace. If you do not explicitly set ACLs on any other objects in the tree, the entiretree inherits this root ACL.

There is always an explicit ACL policy set at the root of the protected object space.An administrator can replace this ACL with another ACL containing differententries and permission settings. But the root ACL can never be completelyremoved.

The root ACL policy is explicitly set during the initial Access Manager installationand configuration.

Core entries for the default root ACL — default-root — include:Group iv-admin TcmdbvaAny-other TUnauthenticated T

Traverse permissionAccess Manager access control depends on two conditions.1. The ACL that controls the requested object must contain appropriate access

permissions for the requesting user.2. 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 only applied to container objects in the protected objectspace. The traverse permission specifies that a user, group, any-other, orunauthenticated identified in the ACL entry has permission to pass through thiscontainer object in order to gain access to a protected resource object below in thehierarchy.

A protected object is accessible to a requester if the requester possess the traversepermission on each ACL attached to container objects above the requested resourceon the path towards root and including root.

The following example illustrates how the traverse permission works. Within theACME Corporation, there is an Engineering container object (directory), which alsocontains a TechPubs container object (subdirectory). User kate, a member of theSales department, requires traverse to the Engineering/TechPubs directory toreview a release note file. The administrator provides traverse for any-other at theroot. The administrator provides traverse for group sales on the Engineeringdirectory. The TechPubs directory inherits the ACL from the Engineering directory.Although Kate has no other permissions in these two directories, she can pass(traverse) through these directories in order to access the release_note file.Because this file has read permission for user kate, she can view the file.


You can easily restrict access to the hierarchy below a given container object —without resetting individual permissions on these objects. Simply remove thetraverse permission from the appropriate ACL entry. Removing traverse permissionon a directory object protects all objects lower in the hierarchy, even if those objectscontain other less restrictive ACLs.

For example, if group sales did not have the traverse permission on theEngineering directory, Kate could not access the release note file, even though shehas read permission for the file.

Resolving an access requestInheritance begins with the root ACL and impacts all objects in the object spaceuntil it reaches an object with an explicit ACL. At this point, a new chain ofinheritance begins.

Objects below an explicitly set ACL inherit the new access controls. If you deletean explicit ACL, access control for all objects reverts back to the nearest directoryor container object with an explicitly set ACL.

When a user tries to access a secure object (such as a Web document), AccessManagerchecks whether the user has the permissions to access the object. It doesthis by checking every object along the object hierarchy for the proper inherited orexplicitly set permissions.

A user is denied access to an object if any directory or container object in thehierarchy above does not include the traverse permission for that user. Access isalso denied if the target object does not contain sufficient permissions to performthe requested operation.

In order to succeed an access check, the requestor must have both:1. Permission to traverse the path to the requested object.2. Appropriate permissions on the requested object.

Engineering/Sales/

TechPubs/

release_note

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

(ACL inherited)

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

ACME Corporation

root

any-authenticated -------T---------

Figure 19. Traverse permission


The following example illustrates the process of resolving whether a user can read(view) an object:/acme/engineering/project_Y/current/report.html

Access Manager checks for the following:1. Traverse permission on the explicitly set root ACL (/).2. Traverse permission on any explicit ACLs attached to the directories:

acme,engineering, project_Y, and current.3. Read permission on the file itself (report.html).

The user is denied access if the user fails the access check at any of these pointsalong the object hierarchy.

Applying ACL policies to different object typesPermissions for a variety of operations can be set in an ACL policy. Only a subsetof these possible operations might be relevant for a specific object to which theACL is attached.

The reason for this behavior is related to the two features of Access Manager thatare designed to make administration easier:v ACL policiesv ACL inheritance

ACL policies allow you to attach the same ACL definition to multiple objects in theprotected object space. The ACL definition consists of enough entries to meet therequirements of all objects to which the ACL is applied; however, each individualobject might only be affected by a few of the entries.

In the ACL inheritance model, any object without an attached explicit ACL policy“inherits” the policy definitions from the nearest ACL applied to an object above itin the hierarchy.

In summary, an ACL policy has to describe the necessary permissions for all objecttypes that it is applied to — and not just the object that it is attached to.

ACL policy inheritance exampleThe following figure illustrates the impact of a mixture of inherited and explicitACLs in a 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 departmentalsub-trees.

In this example, the sales group is given ownership of their departmental sub-tree.Note that the ACL on this sub-tree no longer acknowledges the unauthenticated orany-other entry types.

The Year-to-Date sales file (ytd.html) has an explicit ACL that grants readpermission to members of the sales-vp group (who are also members of the salesgroup).


Note: This ACL scheme need not be changed with the addition or subtraction ofusers within the secure domain. New users are simply added to theappropriate group(s). Likewise, users can be removed from those groups.

Guidelines for a secure object spacev Set high-level security policy on container objects at the top of the object space.

Set exceptions to this policy with explicit ACL on objects lower in the hierarchy.v Arrange your protected object space so that most objects are protected by

inherited, rather than explicit, ACLs.Inherited ACLs simplify the maintenance of your tree because they reduce thenumber of ACLs you must maintain. This lower maintenance reduces the risk ofan error which could compromise your network.

v Position new objects in the tree where they inherit the appropriate permissions.Arrange your object tree into a set of sub-trees, where each sub-tree is governedby a specific access policy. You determine the access policy for an entire sub-treeby setting an explicit ACL at the root of the sub-tree.

v Create a core set of ACL policies and re-use these ACLs wherever necessary.Since an ACL policy is a single source definition, any modifications to the policyimpacts all objects associated with this ACL.

v Control user access through the use of groups.It is possible for an ACL to consist of only group entries. Access to an object byindividual users can be efficiently controlled by adding users to or removingusers from these groups.

Creating extended ACL actions and action groupsIn this section, the word “action” has the same meaning as the word“permissions,” used in previous sections.

staff.html manager.htmltele.html president.html

products.htmlclientA.html ytd.htmlsales.html

WebSEAL Server( www.acme.com/ )

Departments/

group iv-admin -abc---Tdm----lrxgroup ivmgrd-servers -------T------l--group webseal-servers -a--g--Tdm----lrxunauthenticated -----------------any_authenticated -------T-------r-

Sales/

Note: Group "sales" includes membersof group "sales-vp".

Personnel/

Production/ Inventory/

group iv-admin -abc---Tdm----lrxgroup ivmgrd-servers -------T------l--group webseal-servers -a--g--Tdm----lrxgroup sales -------T------lrx

group iv-admin -abc---Tdm----lrxgroup ivmgrd-servers -------T------l--group webseal-servers -a--g--Tdm----lrxgroup sales-vp -------T-------r-

Figure 20. ACL inheritance example


Every Access Manager permission is defined as an action. Seventeen actions arepredefined for immediate functionality (see “Default Access Manager permissions(actions)” on page 39). You can also define new actions for use by third-partyapplications.

This section describes how to define action groups that serve as containers for anexpanded set of custom actions:v Each action group is capable of holding up to 32 action bits.v An action bit is made up of a letter: a-z, A-Z.v Each action bit character can only be used once within an action groupv You can re-use the same action bit in other action groups.v The default Access Manager actions are stored in an initial predefined action

group called “primary”.

Access Manager supports a total of 32 action groups (including the primary actiongroup) for a total of 1024 individual actions.

Creating a new action groupUse the pdadmin action group create command to create a new action group:pdadmin> action group create test-grouppdadmin> action group list

primarytest-group

pdadmin> action group delete test-grouppdadmin> action group list primary

The default primary action group always appears in a group listing and cannot bedeleted.

a A b B c g N T W

...

32

primary action group

Bits set for:group sales abNT

Figure 21. Primary action group

a A b B c g N T W

...

32

multiple action groups

Figure 22. Multiple action groups


You must have an entry in an ACL on the /Management/ACL object with the modify(m) permission to create action groups and the delete (d) permission to deleteaction groups.

Creating new actions in an action groupUse the pdadmin action create command to create a new action within an actiongroup.pdadmin> action create action_name action_label action_type action_group_name

Option Description

action_name Letter representing the action (permission).

action_label Descriptive label for this action. Appears in a pdadmin actionlist command and the Web portal manager.

action_type Action category (used by Web portal manager to groupcommon action bits together). Default categories include Base,Generic, and WebSEAL.

action_group_name Action group where this new action belongs. If this argumentis not specified, the action is assigned to the “primary” actiongroup.

For example:pdadmin> action create P Test-Action Special test-grouppdadmin> action list test-group P Test-Action Specialpdadmin> action delete P test-grouppdadmin> action list test-grouppdadmin>

Entering custom actions into ACL entriesAs discussed in “ACL entry syntax” on page 37, ACL entries contain an entry type,a type ID (for user and group types), and the set of permitted action bits.

You must use a special syntax to identify custom action bits belonging to actiongroups other than the “primary” action group. Action strings that represent theaction bits from multiple action groups are presented in the following format:<action>...<action>[<action-group>]<action>...<action>,,,

For example:

abgTr[groupA]Pq[groupB]Rsy[groupC]abv The first set of action bits (abgTr) represent permissions from the “primary”

(Access Manager default) action group.v Action group A contains actions P and q.v Action group B contains actions R, s, and y.v Action group C contains actions a and b.v Note that action group C contains action bits that use the same letters as action

bits in the “primary” group.Because the action bits are associated with a specific action group (C), the a andb action bits have unique identities and can represent very different permissionsfrom the a and b action bits in the “primary” action group.

ExampleShow action groups


pdadmin>pdadmin> action group list

primarytest-group

List actions in action group “test-group”pdadmin> action list test-group

P Test-Action SpecialS Test-Action2 Special

List ACL policiespdadmin> acl list

default-websealdefault-roottestdefault-replicadefault-management

Show details of ACL “test”pdadmin> acl show test

ACL Name: testDescription:Entries:

User sec_master TcmdbvaGroup ivmgrd-servers TlAny-other r

Add ACL entry for user Kate containing actions from action groups “primary”and “test-group”pdadmin> acl modify test set user kathy brT[test-group]PSpdadmin> acl show test

ACL Name: testDescription:Entries:User sec_master TcmdbvaGroup ivmgrd-servers TlAny-other rUser kathy Tbr[test-group]PS

ACL policies and the protected object spaceContainer objects represent specific regions of the protected object space and servetwo important security functions:1. You can use the container object’s ACL to define high level policy for all

sub-objects within the region when no other explicit ACLs are applied.2. You can quickly deny access to all objects in a region by removing the traverse

permission from the container object’s ACL.

Root ( / ) container objectThe following security considerations apply for the Root object:v The root object begins the chain of ACL inheritance for the entire protected

object space.v If you do not apply any other explicit ACLs, the root object defines (through

inheritance) the security policy for the entire object space.v Traverse permission is required for access to any object below root.


The traverse permissionThe traverse permission is a generic permission that applies throughout theprotected object space.

Operation Description

T traverse When applied to a container object, allows the requester tohierarchically pass through the container object on the wayto the requested resource object. It does not allow any othertype of access to the container object. Traverse is notrequired on the requested resource object itself.

WebSEAL permissionsThe following security considerations apply for the /WebSEAL container in theprotected object space:v The WebSEAL object begins the chain of ACL inheritance for the WebSEAL

region of the object space.v If you do not apply any other explicit ACLs, this object defines (through

inheritance) the security policy for the entire Web space.v The traverse permission is required for access to this object and any object below

this point.

/WebSEAL/hostThis subtree contains the Web space of a particular WebSEAL server. The followingsecurity considerations apply for this object:v The traverse permission is required for access to any object below this pointv If you do not apply any other explicit ACLs, this object defines (through

inheritance) the security policy for the entire object space on this machine

/WebSEAL/host/fileThis is the resource object checked for HTTP access. The permissions checkeddepend on the operation being requested.

WebSEAL permissionsThe following table describes the permissions applicable for the WebSEAL regionof the object space.


r read View the Web object.

x execute Run the CGI program.

d delete Remove the Web object from the Web space.

m modify PUT an HTTP object. (Place - publish - an HTTP object inthe WebSEAL object space.)

l list Required by the policy server to generate a directoryauto-list of the Web space.

g delegation Assigns trust to a WebSEAL server to act on behalf of aclient, and pass that request to a junctioned WebSEALserver.


Management permissionsThe Management region of the protected object space contains severalsub-management container objects that require specific sets of permissions:v “/Management/ACL permissions” on page 51v “/Management/Action permissions” on page 52v “/Management/POP permissions” on page 53v “/Management/Server permissions” on page 53v “/Management/Config permissions” on page 54v “/Management/Policy permissions” on page 54v “/Management/Replica permissions” on page 54v “/Management/Users permissions” on page 55v “/Management/Groups permissions” on page 56v “/Management/GSO permissions” on page 56

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

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

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

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


a attach Attach ACL policies to objects; remove ACL policies fromobjects.

acl attachacl detach

c control Ownership of the ACL policy; allowed to create, delete andmodify entries for this ACL.

acl modify

d delete Delete an existing ACL policy. The ACL entry for this usermust also contain the control (c) permission.

acl delete

m modify Create a new ACL policy.

acl create

v view List and find view ACLs; show ACL details. This permissionmust be in an entry of an ACL attached to /Management/ACL.

acl findacl listacl show

You must create ACL administrator entries in the default ACL policy for the/Management/ACL object. The administrator’s ACL entry can contain any of theabove permissions. These permissions give the administrator powers to create newACL policies, attach ACLs to objects, 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.

Note that the creator of a new ACL policy (m on /Management/ACL) becomes thefirst entry in that ACL—with the TcmdbsvaBlNWA permissions set by default.

For example, if sec_master is an administrator entry in the default-managementACL, with m permission, sec_master can create a new ACL policy. Usersec_master becomes the first entry in the new ACL, with TcmdbsvaBlNWApermissions.

The control permission (c) gives sec_master ownership of the ACL and allowssec_master to modify the ACL. User sec_master could then grant administrationpermissions to other user entries in that ACL.

Ownership of the default-management ACL itself is given to both user sec_masterand group iv-admin by default.

The Control Permission (c)The control permission is a powerful permission that gives you ownership of anACL policy. Control allows you to modify the entries in the ACL. This means youhave the power to create entries, delete entries, grant permissions, and take awaypermissions.

The administrator who wants to delete an ACL from the list of ACL policies musthave an entry in that ACL and must have the control permission set in that entry.

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

The control permission is only important in the /Management/ACL space.

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

action deleteaction group delete

m modify Create a new action or action group.

action createaction group create

Note: The following commands do not require special permissions:v action list

v action group list

Access Manager provides authorization services to applications. Applications thatare part of the Access Manager family include, for example, WebSEAL (for Webapplications) and Access Manager for Business Integration (for messagingapplications).


Third-party applications can make calls to the authorizations service through theauthorization API. Two necessary steps required to integrate a third-partyapplication with the authorizations service include:v Define the application’s object spacev Apply permissions on objects (resources) needing protection

The administrator of a third-party application object space can use the pdadminutility to define new permissions and actions. The administrator must have the mand d Management/Action permissions to create and delete thesepermissions/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:


a attach Attach a POP to an object.

pop attachpop detach

d delete Delete a POP.

pop delete

m modify Create POPs and modify POP attributes.

pop createpop modify

v view Find and list POPs and show POP details.

pop findpop listpop show

B Bypass TOD Override the time-of-day POP attribute on an object.

/Management/Server permissionsThe /Management/Server container object of the protected object space allowsadministrators to perform server management tasks (when appropriate permissionsare set).

Server management controls are used to determine if a user has permission tocreate, modify, or delete a server definition. Server definitions contain informationthat allows other Access Managerservers, particularly the policy server (pdmgrd),to locate and communicate with that server.

A server definition is created for a particular Resource Manager (such asWebSEAL) or authorization server (pdacld) as part of the installation process. Thedefinition for a server is also deleted when the server is uninstalled.


s server Replicate authorization database.

server replicate

v view List registered servers and display server properties.

server listserver show



t trace Enable dynamic trace or statistics administration.

server task server_name traceserver task server_name stats

/Management/Config permissionsThe /Management/Config container object of the protected object space allowsadministrators to perform configuration management tasks (when appropriatepermissions are set).

The creation and deletion of server definitions happens automatically—theinstallation administrator does not have to perform any special steps to create adefinition. However, the administrator must be granted modify (m) permission onthe /Management/Config object in order to create the definition during installation.

In addition, the administrator must have delete (d) permission on the/Management/Config object in order to delete the definition during uninstallation.


m modify Configuration into a secure domain.

svrsslcfg -configsvrsslcfg -modify

d delete Unconfiguration.

svrsslcfg -unconfig

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


v view Required for policy get operations.

m modify Required for policy set operations.

/Management/Replica permissionsThe /Management/Replica container object of the protected object space controls thereplication of the authorization database. High-level controls on this object affectthe operation of the policy server and the Security Manager(s) in the securedomain.

Replica management controls are used to determine what processes are allowed toread or update the master authorization policy database in order for replication totake place properly.

Controls and associated permissions include:


v view Read the master authorization database.

m modify Authorize modification of the replica database(s).


All Access Manager servers which maintain a local replica of the authorizationdatabase — this includes all resource managers and 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 authorization policy database. The Access Manager installationautomatically grants read permission to any server requiring access to theauthorization policy database.

Access Manager currently does not use the modify (m) permission. The only wayto modify the master policy authorization database is through the Web portalmanager or the pdadmin utility. These tools are subject to other finer-grainedchecks. The modify permission is intended to be used in the future when it ispossible to replicate the policy server.

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


d delete Delete a user account.

user delete

m modify Modify user account details.

user modify authentication-mechanismuser modify account-validuser modify gsouseruser modify description

N create Create a new user and optionally assign that user to one ormore groups. Import group data from the user registry.

user createuser import

v view List user accounts and show user account details.

user listuser list-dnuser list-gsouseruser showuser show-dnuser show-groups

W password Reset and validate a user password.

user modify passworduser modify password-valid

The W permission allows password resets and is appropriate to give to helpdeskadministrators so they can assist users who have forgotten their passwords. Thispermission allows an administrator to reset the forgotten password and then usethe user modify password-valid command to set a value of “no”. This actionallows the user to log and then forces the user to immediately apply a newpassword.

Access granted by the /Management/Users object overrides any access restrictionsimposed by “delegated administration” policy ACLs under/Management/Groups/group_name.


/Management/Groups permissionsThis object allows administration users to manage groups and group membership.Action tasks and associated permissions include:

Permission Operation Description

d delete Delete a group.

group delete

m modify Modify group descriptions. Remove one or more usermembers of a group.

group modify descriptiongroup modify remove

N create Create a new group. Import group data from the userregistry.

group creategroup import

v view List groups and show group details.

group listgroup list-dngroup showgroup show-dngroup show-members

A add Add one or more users to a group.

group modify add

The A permission is required on your entry in the ACL on a group to allow you toadd existing users to your group. Use the user create command (which requires Npermission) to create new users and, optionally, place them in one or more existinggroups.

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 delete (d) permission, you can delete this user fromthe entire secure domain.

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


m modify rsrcgroup modifyrsrccred modify

v view rsrc listrsrcgroup listrsrccred listrsrc showrsrcgroup showrsrccred show

N create rsrc creatersrcgroup creatersrccred create(all the above commands also require m)



d delete rsrc deletersrcgroup deletersrccred delete(all the above commands also require m)

Object and object space permissionsThese commands allows administration users to manage new objects and objectspaces. Action tasks and associated permissions include:


b browse objectspace listobjectspace writefileobject listobject listandshow(additionally requires v)

d delete objectspace deleteobject deleteobject modify set name(additionally requires m)

m modify objectspace createobjectspace readfileobject createobject modify

v view object listandshow(additionally requires b)object show

Default administration ACL policiesThe following default administration ACL policies are suggested starting points forsecuring specific regions of the secure domain.

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

Note the user(s) and group(s) in each ACL that contain the control (c) permission.Users and groups with the control permission “own” the ACL and have the powerto modify the ACL entries.

Default root ACL policyCore entries for the default root ACL, default-root, include:Group iv-admin TcmdbvaAny-other TUnauthenticated T

The root ACL is very basic—everyone can traverse the object space, but cannotperform any other actions. Typically, you would not need to change this. However,one useful function of the root ACL is to quickly deny access to the entire objectspace for an individual user or group.


Consider the following entry in the root ACL:user john -----------------

The consequence of this entry (no permissions) is that user john cannot eventraverse the root container object. This user cannot gain access at all to theprotected object space — regardless of any permissions granted lower down in thetree.

You can apply this same approach to the WebSEAL object space. For example, ifyou take away the traverse permission from a particular user at the /WebSEALcontainer objects, that user cannot gain entry to the WebSEAL object space at all —regardless of any permissions granted on objects within those regions.

Default /WebSEAL ACL policyCore entries for the WebSEAL ACL, default-webseal, include:Group iv-admin TcmdbsvarxlGroup webseal-servers TgmdbsrxlUser sec_master TcmdbsvarxlAny-other TrxUnauthenticated T

At installation, this default ACL is attached to the /WebSEAL container object in theobject space.

The group, webseal-servers, contains an entry for each WebSEAL server in thesecure domain. The default permissions allow the servers to respond to browserrequests.

The traverse permission allows expansion of the Web space as represented in theWeb portal manager. The list permission allows the Web portal manager to displaythe contents of the Web space.

Default /Management ACL policyCore entries for the Management ACL, default-management, include:Group iv-admin TcmdbsvatNWAGroup ivmgrd-servers TsAny-other Tv

At installation, this ACL is attached to the /Management container object in theobject space.

Default /Replica ACL policyCore entries for the Replica management ACL, default-replica, include:Group iv-admin TcbvaGroup ivmgrd-servers mGroup secmgrd-servers mdvGroup ivacld-servers mdv

Default /Config ACL policyCore entries for the Config management ACL, default-config, include:Group iv-admin TcmdbsvaNAny-other TvUnauthenticated Tv


Default /GSO ACL policyCore entries for the GSO management ACL, default-gso, include:Group iv-admin TcmdbvaNAny-other TvUnauthenticated Tv

Default /Policy ACL policyCore entries for the Policy management ACL, default-policy, include:Group iv-admin TcmdbvaNAny-other TvUnauthenticated Tv



Chapter 4. Using protected object policies

The Access Manager authorizations service makes decisions on requests for accessto protected objects in the secure domain. The decision can be based on two typesof policies:v Access control list (ACL) policiesv Protected object polices (POP)

The purpose of a POP is to impose additional conditions on the operationpermitted by the ACL policy.

Examples of access conditions can include:v Writing a report record to the auditing servicev Restricting access to a specific time period

This chapter discusses how protected object policies are configured and applied toobjects.

This chapter contains the following sections:v “Introducing protected object policies (POP)” on page 61v “Configuring the POP attributes” on page 63v “Authentication strength POP policy (step-up)” on page 65v “Network-based authentication POP policy” on page 68v “Quality of protection POP policy” on page 70

Introducing protected object policies (POP)ACL policies provide the authorizations service with information to make a yes orno answer on a request to access a protected object and perform some operation onthat object.

POP policies contain additional conditions on the request that are passed back tothe Resource Manager (such as WebSEAL) along with the yes ACL policy decisionfrom the authorizations service. It is the responsibility of the Resource Manager toenforce the POP conditions.

The following table lists the available attributes for an Access Manager POP:


POP attribute Description pdadmin pop commands

Name Name of the policy. This becomes thepop_name in the pdadmin popcommands.

createdelete

Description Descriptive text for the policy. Thisappears in the pop show command.

modify set description

Warning Mode Provides administrators a means to testACL and POP policies.

modify set warning

Audit Level Specifies type of auditing: all, none,successful access, denied access, errors.

modify set audit-level

61



Time-of-Day Access Day and time restrictions for successfulaccess to the protected object.

modify set tod-access

Extended attributes Specifies supplemental data fields. modify set attributemodify delete attributelist attributeshow attribute

Enforced by Resource Manager (such as WebSEAL)


Quality of Protection Specifies degree of data protection:none, integrity, privacy.

modify set qop

IP EndpointAuthentication MethodPolicy

Specifies authentication requirementsfor access from members of externalnetworks.

modify set ipauth addmodify set ipauth removemodify set ipauth anyotherw

POP notes:v The time-of-day access and the IP endpoint authentication method access place

restrictions on the access to the object.v Audit level and quality of protection inform the authorizations service that extra

services are required when permitting access to the object.v Warning mode provides a way to test ACL and POP policies before they are

made active.

Note: The quality of protection and auditing rules specified by the P, I, and Apermissions in previous versions of Access Manager are now specified inPOP policies.

Creating and deleting protected object policiesProtected Object Policies (POP) operate in a similar way to ACL policies—youcreate and configure a POP and then attach the POP to objects in the protectedobject space.

POP policies are inherited in the same way as ACL policies. Both POP policies andACL policies are placed in the master authorization database which is controlledby the policy server.

Create and list a POPpdadmin> pop create pop_name

For example:pdadmin> pop create testpdadmin> pop list test

The new POP contains the following default settings:pdadmin> pop show test

Protected object policy: testDescription:Warning: noAudit level: noneQuality of protection: none


Time of day access: sun, mon, tue, wed, thu, fri, sat:anytime:local

IP Endpoint Authentication Method PolicyAny Other Network 0

Delete a POPpdadmin> pop delete pop_name

For example:pdadmin> pop delete testpdadmin> pop listpdadmin>

Modify and show a POP descriptionpdadmin> pop modify pop_name set description description

Note: Always enclose the description with double quotation marks when you usemore than one word.

For example:pdadmin> pop modify test set description “Test POP”pdadmin> pop show test

Protected object policy: testDescription: Test POPWarning: 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

Applying POP attributes to protected objectsPOP policies are applied to objects in the same manner as ACL policies.

Attach a POP to an objectThe syntax for attaching a POP to an object is:pdadmin> pop attach object_name pop_name

For example:pdadmin> pop attach /WebSEAL/serverA/index.html test

Find where a POP is attachedpdadmin> pop find test /WebSEAL/serverA/index.html

Delete a POPThe syntax for detaching a POP from an object is:pdadmin> pop detach object_name

For example:pdadmin> pop detach /WebSEAL/serverA/index.html

Configuring the POP attributesv Warning mode attributev Audit level attributev Time-of-day attribute

Chapter 4. Using protected object policies 63

Warning mode attributeThe purpose of the warning attribute is to allow a security administrator to debugor troubleshoot the accuracy of the authorization policy set on the protected objectspace.

When you set the warning attribute to yes, any action is possible by any user onthe object where the POP is attached. Any access to an object is permitted even ifthe ACL policy attached to the object is set to deny this access.

Audit records are generated that capture the results of all ACL policies withwarning mode set throughout the object space. The audit log shows the outcomeof an authorization decision as it would have been made if the warning attributehas been set to “no”. The administrator can, therefore, determine if policy is setand enforced correctly.pdadmin> pop modify pop_name set warning {yes|no}

For example:pdadmin> pop modify test set warning yes

Audit level attributeThe audit level POP attribute is the replacement for the A ACL permission thatactivated auditing in previous versions of Access Manager. The POP audit levelhas the expanded ability to specify a level of auditing.

For example, if auditing is set to record unsuccessful events, you can use theresults to detect an unusual number of failed access attempts on a particularresource.

Auditing records are written in a standard XML format that allows easy parsing toextract whatever information is required.

See “Audit trail files” on page 115.pdadmin> pop modify pop_name set audit-level {all|none|audit_level_list}

Audit-Level-List

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 three values. Use a comma as a separatorcharacter when you specify more than one value.

For example:pdadmin> pop modify test set audit-level permit, deny

Time-of-day attributeThe time-of-day (TOD) POP attribute allows you to place specific day and timeconditions on the access to a protected object. This type of condition might beuseful to limit access to information that regularly requires periods of inactivity formodification and updates.


There is an ACL policy permission (B) that overrides the time-of-day conditions onan object. This permission should only be used by a high level administrator whoneeds full access of the protected object space all the time.pop modify pop_name set tod-access time_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:mon, tue, wed, thu, fri, sat, sun

The time-spec range variable must be expressed (using 24 hour time) as:hhmm-hhmm

For example:0700-1945

The optional time zone for the server (not the client) is local by default.

For example:pdadmin> pop modify test set tod-access mon,tue,fri:1315-1730

Authentication strength POP policy (step-up)You can use protected object policies (POP) to enforce certain access conditions onspecific resources. The authentication strength POP policy makes it possible tocontrol access 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 securedomain.

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 should be considered stronger.

Any client accessing a resource manager has an authentication level, such as“unauthenticated” or “password”, which indicates the method by which the clientlast authenticated with the resource manager.

In some situations it may be necessary to enforce minimum “safe” levels ofauthentication required to access certain resources. For example, in one


environment, authentication by token passcode may be considered more securethan authentication by username 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 reauthenticate using the requiredmethod (level).

Step-up authentication allows resource managers to control the method in whichusers access a protected resource. If step-up authentication is required because theuser has not authenticated with the sufficient method, then the access decision isstill permitted by the authorization engine but the resource manager is presentedwith a required ″authentication level″ as an output of the authorization decision.The resource manager can then decide how to further authenticate the user so asto gain the required level of authentication needed for the user to access the object.

How a particular authentication method is mapped to an authentication level isentirely determined by the resource manager application. For all cases, the absoluteminimum acceptable method of authentication should be set as level 0 with moresecure methods being mapped to integral numbers in ascending order (1.x) fromthere. In the WebSEAL implementation of step-up authentication, level 0 ismapped to an unauthenticated user. Other authentication methods for WebSEALinclude password authentication and token card authentication. How theseauthentication methods are mapped to an authentication level is configured by youin the WebSEAL configuration file.

Refer to the IBM Tivoli Access Manager for e-business Release Notes for a discussion ofhow to develop a resource manager that is enabled for step-up authenticationpolicy.

Applying step-up authentication policyStep-up authentication is implemented via a POP policy placed on the objectsrequiring authentication-sensitive authorization. You use the IP EndpointAuthentication Method attribute of a POP policy.

The pdadmin pop modify set ipauth command specifies both the allowednetworks and the required authentication level in the IP Endpoint AuthenticationMethod attribute.

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 will affect all accessing users, regardless of IP address, andrequire them to authenticate at the specified level. This is the most commonmethod for implementing step-up authentication.

Syntax:pdadmin> pop modify pop-name set ipauth anyothernw level-index

The anyothernw entry is used as a network range that will match any network nototherwise specified in the POP. This method used to create a default entry whichcould 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 pop show command:pdadmin> pop show test



Any Other Network0

The following authentication levels and their corresponding authenticationmethods have been defined by the resource manager:v authentication level 0 = unauthenticatedv authentication level 1 = user name/passwordv authentication level 2 = user name/token passcode

Step-up authentication algorithmWebSEAL uses the following algorithm to process the conditions in a POP:1. Check the IP endpoint authentication method policy on the POP.2. Check ACL permissions.3. Check time-of-day policy on the POP.4. Check the audit level policy on the POP.

Distinguishing step-up from multi-factor authenticationAccess Manager step-up authentication and multi-factor authentication are twodifferent and distinct mechanisms for controlling access to resources. AccessManager only provides step-up authentication functionality, as described in thischapter.

Multi-factor authentication forces a user to authenticate using two or more levelsof authentication. For example, the access control on a protected resource canrequire that the user authenticate with both user name/password and username/token passcode.

Access Manager step-up authentication relies on a preconfigured hierarchy ofauthentication levels and enforces a specific level of authentication according to thepolicy 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 that required by the policy protecting the resource.

Step-up authentication example:

Configured authentication levels:v authentication level 1 = user name/passwordv authentication level 2 = user name/token passcode

The following object is protected by a POP requiring authentication level 1:/WebSEAL/hostA/junction

The following object is protected by a POP requiring authentication level 2:


/WebSEAL/hostA/junction/applicationA

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 logs in toWebSEAL with user name and token passcode, access to applicationA isimmediate (assuming a positive ACL check).

Multi-factor authentication would require both level 1 and level 2 authenticationfor access to applicationA.

Network-based authentication POP policyThe network-based authentication POP policy makes it possible to control access toobjects based on the IP address of the user. You can use this functionality toprevent specific IP addresses (or IP address ranges) from accessing any resources inyour secure domain.

You can also apply step-up authentication configuration to this policy and requirea specific authentication method for each specified IP address range.

Network-based authentication policy is set in the IP Endpoint AuthenticationMethod attribute of a POP policy. You must specify two requirements in thisattribute:v Authentication levels

For more information on authentication levels, see “Authentication strength POPpolicy (step-up)” on page 65.

v Allowed networks

Specifying IP addresses and rangesNow you must specify the IP addresses and IP address ranges permitted by thisPOP policy.

The pdadmin pop modify set ipauth add command specifies both the network (ornetwork range) and the required authentication level in the IP EndpointAuthentication Method attribute.

Syntax:pdadmin> pop modify pop-name set ipauth add network netmask level-index

The configured authentication levels are linked to IP address ranges. This methodis intended to provide flexibility. If filtering users by IP address is not important,you can set a single entry for anyothernw (any other network).This setting affectsall accessing users, regardless of IP address, and require them to authenticate at thespecified level.

Syntax:pdadmin> pop modify pop-name set ipauth anyothernw level-index


Conversely, if you wish to ignore the authentication level and only want to allowor deny access based on IP address, you can use level 0 for ranges that you wantto allow in and “forbidden” for ranges you want to deny.

The anyothernw entry is used as a network range that matches any network nototherwise specified in the POP. This method used to create a default entry whichcould either deny all unmatched IP addresses or allow anyone access who meetthe authentication level requirement.

By default, anyothernw appears in a POP with an authentication level index of0.The entry appears as “Any Other Network” in the pop show command:pdadmin> pop show test



Any Other Network0

ExamplesRequire users from IP address range 9.0.0.0 and netmask 255.0.0.0 to use level 1authentication (“password” by default):pdadmin> pop modify test set ipauth add 9.0.0.0 255.0.0.0 1

Require a specific user to use level 0 authentication:pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.255 0

Prevent all users (other than those specified as in the examples above) fromaccessing the object:pdadmin> pop modify test set ipauth anyothernw forbidden

Disabling step-up authentication by IP addressSyntax:pdadmin> pop modify pop-name set ipauth remove network netmask

For example:pdadmin> pop modify test set ipauth remove 9.0.0.0 255.0.0.0

Network-based authentication algorithmThe authorization engine uses the following algorithm to process the conditions ina a POP:1. Check the IP endpoint authentication method policy on the POP.2. Check ACL permissions.3. Check time-of-day policy on the POP.4. Check the audit level policy on the POP.

Network-based authentication notes and limitationsThe IP address used by the resource manager for enforcing the network-basedauthentication policy should be the IP address of the originator of the connection.If your network topology uses proxies, the address that appears to the resourcemanager might be the IP address of the proxy server.


In this case, the resource manager is not able to definitively identify the true clientIP address. You must be careful when setting a network-based authenticationpolicy that network clients can directly connect to the resource manager.

Quality of protection POP policyThe 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 is the replacement for the “P” and “I” ACLpermission bits that activated privacy and integrity requirements in previousversions of Access Manager. This older implementation of quality of protection wasinefficient and impacted system performance.

The quality of protection POP attribute permits a single transaction where the“yes” response to the ACL decision also includes the required quality of protectionlevel. If the resource manager (such as WebSEAL) cannot guarantee the requiredlevel of protection, the request is denied.pdadmin> pop modify pop-name set qop {none|integrity|privacy}

QOP level Description

Privacy Data encryption is required (SSL).

Integrity Use some mechanism to ensure that the data has not changed.

For example:pdadmin> pop modify test set qop privacy


Chapter 5. Using Web portal manager

The Web portal manager is a Web-based interface used to manage security policyfor the secure domain. The Web portal manager provides management andadministration of users, groups, roles, permissions, policies, and application accessprovisioning. The tasks that can be completed using the Web portal manager aredocumented in the online help system. Use the help system as your first point ofreference when looking for Web portal manager task-based information. Thefeatures outlined in this chapter include delegate administration andself-registration.

This chapter contains the following sections:v “Delegating administration using Web portal manager”v “Delegating role administration” on page 73v “Self-registration sample” on page 74

Delegating administration using Web portal managerOne of the most powerful features of the Web portal manager is a rich set ofdelegated management services that enables a business to delegate useradministration, group and role administration, security administration, andapplication access provisioning to participants (sub-domains) in the businesssystem. These sub-domains can further delegate management and administrationto trusted sub-domains under their control, thereby supporting multi-leveldelegation and management hierarchy based on roles.

Delegate administration using Web portal manager provides an Access Manageradministrator the capability to create delegate user domains, create new users, addexisting users to additional domains, and assign various types of administrators tothe domains. These delegate administrators can then perform a subset ofadministration functions, depending on their type, on the users in their assigneddomain. This concept of delegate user administration can be applied to all AccessManager users so that a hierarchy of user domains is formed. In this hierarchicalarrangement, each Access Manager user can be managed only by theadministrators for the domain of which the user is member or by theadministrators for the super domains (explained later in this chapter). The actualfunctions that administrators can perform depend on their assigned administratortype.

An 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 Access Manager users to the domain.

In addition to this user-related function, Access Manager administrators can createnew domains below the enterprise domain level (subdomains) and assign users tobe the administrators for these new domains (domain administrators).Administrators of the new domains can then create new users in their owndomain.

The Access Manager administrator for the enterprise domain (the domain’ssuperdomain) also has authority to administer the domain. Access Manager

71

administrators 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 23, anAccess 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, Q. An Access Manager administrator can create domainsC and D below the enterprise domains A and B, and assign domain administratorsto C and D. The Access Manager administrator can then create domain E belowdomain D, and assign a domain administrator to E. The domain administrator fordomain E can then create new users X, Y, and Z within domain E. Because adomain administrator for a domain can also administer that domain’s subdomains,both the domain administrators for domain D and the domain administrator forenterprise domain B can create users (or perform other administrative functions)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 functions that can be performedby administrators assigned to each of these types:v Access Manager Administrator. The Access Manager administrator is a member

of the iv-admin group. The Access Manager administrator can perform alldelegate administration functions.

v Domain Administrator. The domain administrator can perform administrativefunctions for the users in their domain. Domain administrators can create newusers/administrators in their own domain, and assign existing domain users tobe an administrator (of any type except domain administrator) for the domain.

Secure Domain

Enterprise Domain A Enterprise Domain B …(Users P, Q, ...)

Domain C Domain D

Domain E(Users X, Y, Z, ...)

…

Figure 23. Delegate administrators


v Senior Administrator. A senior administrator has the same authority as adomain administrator, except that a senior administrator cannot assignadditional administrators.

v Administrator. An administrator has the same authority as a senioradministrator, except that an administrator cannot create new domain users. Anadministrator can modify an existing user’s properties.

v Support Administrator. A support administrator serves the user in a help-deskrole and is able to view users’ properties, change users’ passwords, and modifyIs Password Valid? flags for users.

The delegate user administration tool enforces the administrative functions that canbe performed with each administrator type. When an administrator logs in,administrative functions become available in accordance with that user’sadministrator type.

Delegating role administrationAnother part of the delegate administration system of the Web portal manager isrole administration. To successfully deploy Access Manager, a security policy thatregulates access to, and the actions that can be performed on, objects must bedefined. Execution of this policy is usually difficult because the security policy isoften defined by high-level members of an organization with an emphasis onglobal security issues. The policy then must be put into action by local members ofthe organization, who see the lower-level details and implementation concerns.Often these two groups have similar goals for overall organizational security, butinterconnecting these two disparate points of view is challenging. Role-basedadministration provides an enhanced ability for organizational security to meet therequirements of today’s complex security requirements 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 to the accesscontrol list (ACL) model of Access Manager, a role becomes a list of one or morepairs of objects and one or more access permissions that applied to the object. Forexample:v object 1: permission 1v object 2: permission 2, 3, and 4v object 3: permission 5

In order for a role to be used it must be activated. A role is activated when anAccess Manager administrator enables its definition in the Access Managernamespace. After a role is activated and a user is assigned to the role, the user haspermission 1 for object 1, permission 2, 3, and 4 for object 2, 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 pairsof objects 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 is able to create, modify, or delete a payrollcheck and approve a reimbursement request, thus performing the job that anaccountant is expected to perform.

Chapter 5. Using Web portal manager 73

To successfully administer roles, an administrator must be able to perform threetypes of tasks:v Role creationv Role assignmentv Role activation

Role creation involves defining a role so that it has a list of one or more pairs ofAccess Manager objects and permissions that can be applied to the objects. When arole is created in Web portal manager, an Access Manager group is created torepresent the role. A corresponding group object in the management object space isalso created. The object/permissions pair information for the role is stored in theextended attributes associated with the group object. Only an Access Manageradministrator is able to create a role.

Role assignment consists of assigning a user to a role that has already been created.The purpose behind assigning users to roles is to let those users have the accesspermissions on the objects defined in the role. This function reduces the workloadinvolved in maintaining user-permission-object relationships, because roleassignment is separated from object/access permission management. When a useris assigned to a role in Web portal manager, the user is added as a member of thegroup that represents the role. Domain administrators, senior administrators, andadministrators of a domain can assign users in their domains to a role.

Role activation enables a newly created role to function. After a role is created and auser is assigned to that role, the user does not have access permissions for theobjects defined in the role until the role is activated. When a role is activated inWeb portal manager, an ACL entry that contains the group that represents the roleand the access permissions defined in the role are added to the ACL for each objectdefined in the role. Because a user has been added to the group when the user isassigned to the role, that user has permissions to access the objects only after a roleis activated. Only an Access Manager administrator is able to activate a role.

A role is an entity that can be delegated and administered like users by assigning arole to a domain. When a role is created, it can be assigned to an enterprisedomain. Domain administrators can in turn assign any of the roles within thatdomain to any subdomain. Once a role is assigned to a subdomain, anadministrator for that subdomain can assign any subdomain users to that role. Thisprocess of assigning roles to subdomains can be repeated as needed so that rolescan be made available to the appropriate users. Role assignment to an enterprisedomain can be performed only by the Access Manager administrator. Domainadministrators can assign a role to their subdomains.

Self-registration sampleYou can customize the Web portal manager to allow end-users to perform selfregistration. Self registration is the process by which a user can enter in requireddata and become a registered Access Manager user, without the involvement of anadministrator. One possible scenario for implementing self registration, is whereusers use a Web browser to view a self-registration Web Page. On this Web page,the user enters specific identification information (either company-specific oruser-specific) with an Access Manager user ID and password. The identificationinformation provided by the user is then validated and the user is created in theAccess Manager registry.


Access Manager provides a self-registration sample to demonstrate how it works.Note that this sample is only supported on an LDAP registry, not Domino orActive Directory.

Follow these steps to install and use the self-registration sample:

Note: You are only required to perform the configurations steps one time.1. Install the Access Manager Java Runtime Environment for your particular

platform. For installation instructions, see the IBM Tivoli Access Manager BaseInstallation Guide.

2. Use the pdjrtecfg utility to configure the JRE. Enter the following from acommand line: (This command is displayed in Windows format)cd pd_home\sbin

.\pdjrtecfg -action config -java_home java_home_path

where java_home path is the Java Developer’s Kit used by WebSphere. Forexample, on a Windows system, this path is as follows:C:\WebSphere\AppServer\java\jre

3. To set up configuration information to use the Access Manager Java RuntimeEnvironment, use the Java SvrSslCfg utility as follows:

Note: For more information about the Java SvrSslCfg utility, see the IBM TivoliAccess Manager Authorization Java Classes Developer’s Reference.

java com.tivoli.mts.SvrSslCfg\pdjrteuser\sec_master_password\

pdmgrd_host\pdacld_host\pdmgrd_port\pdacld_port\

configFile_URL\keystoreFile_URL\replace

where:

pdjrteuser Indicates is a unique, user-created Access Manager usershortname.

sec_master_passwordIdentifies the sec_master password.

pdmgrd_host Identifies the Access Manager policy server host system.

pdacld_host Identifies the Access Manager authorization server hostmachine.

pdmgrd_port Identifies the Access Manager policy server port.

pdacld_port Identifies the Access Manager authorization server port.

configFile_URL Identifies the location of the configuration file URL. The defaultlocation of the configuration file URL is as follows:

temporary_directory/pdjrte/pdjrte.properties

The default location of the configuration file URL is specified inthe pdwpm.conf file, located in the Access Manager etcdirectory.

Note: You must edit the pdwpm.conf file to change theconfiguration file URL and restart the WebSphereApplication Server.

Chapter 5. Using Web portal manager 75

keystoreFile_URLIndicates the location of the keystore file URL. The defaultlocation of the keystore file URL is as follows:

temporary_directory/pdjrte/pdjrte.ks4. The self-registration sample can be accessed from the following URL:

https://localhost/registerwhere localhost is the machine where IBM HTTP Server and WebSphere arerunning.


Chapter 6. Delegating administration tasks

Access Manager allows high-level administrators to delegate responsibilities formanaging the secure domain to lower-level administrators. This capability is vitalto successfully managing very large domains composed of numerous departments,and therefore contain high numbers of groups, users, and resources.

Access Manager supports two types of delegated administration: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 “Delegating object space management” on page 78v “Delegating group management” on page 81v “Managing delegated administration policy” on page 86

77

Delegating object space managementThe distribution of administration responsibilities within a secure domain is calledmanagement delegation. The need for management delegation generally arisesfrom the growing demands of a large site containing many distinct departmentalor resource 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.

In a secure domain, the sec_master account for LDAP is initially the only accountwith administration permission. As sec_master, you can create managementaccounts and assign to these accounts appropriate controls for specific regions ofthe object space.

Structuring the object space for management delegationStructure your object space to contain distinct regions, or branches, wheresub-management responsibilities—specific to that branch—can be carried out.

In the example below, both the Engineering and Publications regions of the objectspace require separate management control. Control of these regions begins withthe root of each region and extends to all objects below.

Default administration users and groupsAt installation, Access Manager provides several important administration groups.By default, these users and groups are given special permissions to control andmanage all operations in the secure domain. (This default security policy is definedby the ACLs created during installation.)

The following sections detail the specific roles assigned to each of these users andgroups at installation time. The administrator can customize these privileges at alater time to accommodate changing management policies.

user sec_master (LDAP)This user represents the administrator of the secure domain who is grantedcomplete rights for all operations within the secure domain.

Object Space

/WebSEAL

Engineering Server

Publications

Marketing Server

Resources

Figure 24. Structuring the object space for management delegation


This policy can be modified as the object space grows by delegating managementpermissions to other users and possibly revoking certain (or all) permissions fromsec_master.

group iv-adminThis group represents the administrator group. Like sec_master, all members ofthis group are considered administrators of the secure domain by the defaultpolicy. All default ACLs grant user sec_master and group iv-admin exactly thesame permissions.

You can easily place users into an administration role by adding them to theiv-admin group. The danger with this procedure is that once a user becomes amember of this group (with the default ACLs), that user has full rights to doeverything on any object in the entire namespace.

The default policy for this group can be changed by delegating managementpermissions to other users and revoking some or all management permissions fromgroup iv-admin.

group ivmgrd-serversThis group contains the policy server. Access Manager requires that exactly onepolicy server exist in the secure domain. Therefore, this group only contains thatone entry.

Since most management requests made by the console are executed via the policyserver to the target server, the policy server must have permission to perform therequest at the target server. For this reason, this group is granted serveradministration permission (s) in the default management ACL, and list (l)permission throughout the Web space.

group webseal-serversThis group contains all the WebSEAL servers in the secure domain. The defaultWebSEAL ACL grants these servers the complete set of HTTP-specific permissionsand the delegation permission. This policy allows all WebSEAL servers to junctionto all other WebSEAL servers. A modification of this policy could grant thesepermissions on a server-by-server basis.

Creating administration usersYou can create administration accounts with varying degrees of responsibility.Responsibility is delegated to administrators through strategically placeadministration ACLs. The following list illustrates possible administration roles:v ACL administration responsibilities

The ACL administrator can control all, or part, of a protected object namespaceregion, depending on where the administration ACL is placed. Theadministrator’s ACL entry could contain the b, a, and T permissions, plus anyother permissions appropriate for operations on objects in that region.The administrator can use the Web portal manager to attach (a) ACLs to objectsin the designated namespace using the existing set of ACL templates. Thisadministrator does not have permissions to create, modify, or delete ACLtemplates.

v ACL policy responsibilities

The ACL policy administrator should be responsible for controlling the creationand modification of all ACL templates used in the secure domain. The ACLpolicy administrator should be granted d, b, m, and v permission on the/Management or /Management/ACL object.

Chapter 6. Delegating administration tasks 79

This ACL policy administrator can create new ACL templates (m). As the creatorof a new template, the administrator becomes, by default, the first entry in thenew ACL template, with abcT permissions. The control permission (c) effectivelygives the administrator ownership of the ACL, and therefore the ability tomodify the ACL.As owner of the ACL, the administrator is able to use the delete (d) permission(granted in the management ACL) to remove the ACL from the list of templates.You cannot delete an ACL template unless you are the owner of that ACL.

v Server management responsibilities

This administrator is granted d, m, s, and v permissions on the/Management/Server object. This administrator can perform operations affectingthe Access Manager servers.

v Authorization Action responsibilities

This administrator is granted d and m permissions on the /Management/Actionobject. This administrator can create or delete all permissions created forthird-party applications.

Example administration ACL templatesThe following example illustrates how a user gains administration rights.v The following ACL on /WebSEAL gives administration rights to user adam:

user sec_master abcTdmlrxgroup iv-admin abcTdmlrxgroup webseal-servers gTdmlrxgroup ivmgrd-servers Tluser adam abcTdmlrxany-other Trxunauthenticated Trx

Example: Management delegationA large object space might require many administration users to manage a varietyof sub-branches. In this scenario, the ACLs for the directories on the path to eachof these branches must contain entries for each account, with traverse permission.For a site with many administration users, these ACLs could contain a long list ofentries 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 sub-branch requiring management delegation.4. At each branch root ACL, add the appropriate administration user entry (with

b, c, T, plus other appropriate permissions).5. The administrator can now remove the administration group ACL entry (and

any other entry) from the root.Now only that user has control over the root and all objects below.

In the example below, the group iv-admin contains all administration users. Userpub-manager is a member of this group and therefore, has the necessary traversepermission required to navigate to the Publications directory.


The Publications directory includes the user pub-manager entry in its ACL. Sincepub-manager is the delegated administrator of this branch (with the appropriatepermissions), pub-manager can remove the iv-admin group account (and anyother ACL entries) from the Publications ACL to gain total control over thatbranch of the Web space.

Delegating group managementAccess Manager allows high-level administrators to delegate responsibilities formanaging the secure domain to lower-level administrators. This capability is vitalto successful management of very large domains composed of numerousdepartments that contain high numbers of groups, users, and resources.

In 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 The level of group and user control given to this administrator

In this discussion, the term “administrator” refers to the responsibilities andcontrols granted to an otherwise typical user. An administrator of delegated dutiesis a normal user with additional powers to perform certain management tasks.

Setting up delegated group management requires the following conditions:1. Determine a logical and practical hierarchy of the users and user types who are

members of the secure domain.2. Create group container objects that reflect this hierarchy.

/WebSEAL/server

/Resources

/Marketing

group iv-admin --b----T---------...user pub-manager -abc---Tdm----lrx

/Publications

user sec_master -abc---Tdm----lrxgroup iv-admin --b----T---------

user sec_master -abc---Tdm----lrxgroup iv-admin --b----T---------

= explicit ACL

= inherited ACL

Figure 25. Management Delegation Example


3. Create appropriate groups within these container objects.4. Strategically attach ACL policies that include the administrator-user entry.5. Assign, to this administrator-user entry, the specific permissions needed to

perform the required tasks.

Creating group container objectsBy default, the /Management region of the Access Manager object space has aGroups container object that you can use to organize the hierarchy of groups inyour secure domain.

Container objects are structural designations that allow you to organize the objectspace into distinct and hierarchical functional regions. Group container objectsallow you to define distinct categories of group types. You create actual groupswithin each specific group container object.

Use the pdadmin object create command to create a new group container object:pdadmin> object create obj-name description type ispolicyattachable {yes|no}


obj-name Full path and name of the new group container object. Path mustbegin with /Management/Groups.

description Any text string describing the object. This information appears in theobject show command.

type The type argument identifies the specific graphical icon associatedwith this object and displayed by the Web portal manager. Types

range from 0-17 (see table below). Type 14 is appropriate forcontainer objects.

ispolicyattachable

Determines whether you can attach an ACL policy to this object.

Object types

0 – unknown1 – secure domain2 – file3 – executable program4 – directory5 – junction6 – WebSEAL server7 – unused8 – unused

9 – HTTP server10 – non-existent object11 – container object12 – leaf object13 – port14 – application container object15 – application leaf object16 – management object17 – unused

For example:pdadmin> object create /Management/Groups/Travel “TravelContainer Object” 14 ispolicyattachable yes


You can also use the pdadmin group create command to create a group containerobject. See “Creating groups”.

Creating groupsUse the pdadmin group create command to create a new group and, optionally,place this group in a group container object. If the container object does notcurrently exist, it is automatically created:pdadmin> group create group_name dn cn [group_container]


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, thegroup is placed under /Management/Groups.

v All new group container objects that you create appear under the default/Management/Groups container. To create a container at another sub-level, use arelative path name for the group_container variable.

v The group create command does not allow you to create a group containerobject without a group.

v To add a new group to the object space, the administrator must have createpermission (N) 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)—attached to/Management—defines the permissions on all groups and group containers. Youmust add appropriate explicit ACLs to customize this control.

v You can add multiple groups to a single group container.The ACL on the group container object controls (through inheritance) all groupsthat reside under the container object. The container object and its groups arenow the domain of the administrator with the delegated responsibilities.

v The placement of a new group in the object space is fixed on creation.Once a group is created, you can only move its position by deleting the groupfrom the object space (but not LDAP) and then import the group to a newlocation (users in the group are maintained).

For example:

–

–

+

/Management

/Management/Groups

/Management/Groups/Travel

Figure 26. Group container object


pdadmin> group create group1 “cn=travel,c=us” Group1 Travel

pdadmin> group create group2 “cn=travel,c=us” Group2 Travel

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 resides under the /Management/Groups section of the object space, theACL must be attached to /Management/Groups or the group itself.

If the group resides 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 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

For example, in Figure 27, an ACL on /Management/Groups/Travel definespermissions to control both group1 and group2.

The following operations and ACL permissions are appropriate for groupmanagement:

Operation Permission

create (a new group) import (group data from the user registry) 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)

–

–

–

/Management

/Management/Groups

/Management/Groups/Travel

+ /Management/Groups/Travel/group1

+ /Management/Groups/Travel/group2

Figure 27. Creating new groups under a specific group container


You can use the appropriate pdadmin utility commands, or the Web portalmanager, to perform these operations.

Notes:v The create (N) permission must reside in an ACL that is attached to

/Management/Groups or on a group container object.v All other permissions listed can reside in an ACL attached to

/Management/Groups, a group container object, or the group object itself.v The add (A) permission is powerful because it allows you to add any existing

user to your groups.If an outside user is placed into a group, the administrator of that group nowhas control of that user (and might share control of the user with administratorsof other groups where that user is a member).This permission is best granted only to high-level administrators who areresponsible for user and group organization and corporate policy.

ACL policies affecting user managementThe group administrator can perform an action on a user if they have theappropriate permission defined on any of the groups where that user is a member.

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 commands, or the Web portalmanager, to perform these operations.

Notes:v The create (N) permission (in the group ACL or group container ACL) allows

you 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

v You can also create a user without designating a group. In this case, however,the create (N) permission must reside 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).

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


v If a user is not a member of any group, an administrator must have appropriatepermissions in an ACL on /Management/Users to perform operations on thatuser.

v The password (W) permission is appropriate for helpdesk operators who mustassist users who have lost their passwords.The operator can reset the lost password to some known value, and then setuser modify password-valid (pdadmin) to “no”. This action would force theuser to change the password at the next login.

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

Managing delegated administration policyThe previous two sections described separately how to delegate administration ofsecurity policy for protecting resources in your secure domain and also how todelegate management of the users who access those resources. These twoindividual aspects of delegated administration often need to be combined toestablish a complete delegated administration security policy.

Great care, however, must be taken when doing this. In particular, you must becareful which permissions you grant in combination with each other.

For example the A permission should never be granted together with the m or Wpermissions except to the most powerful and trusted administrators (and maybenot at all). The consequence of granting both A and W to an administrator is thatthe administrator can add any user to the group for which they have thesepermissions and then change that user’s password. Any user can be chosen,including a more senior administrator or even sec_master. In this way, a maliciousadministrator could gain full access to the system by logging on as that senior user.

The consequence of granting the A and m permissions together are similar exceptthat an administrator with both of these permissions can only use this combinationto disable any account.

When defining a complete delegated administration policy, these constraints implya certain structure and use to your user groups.

You must establish groups that you use to delegate user management tasks—suchas creating new users, deleting users and resetting users’ 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 and should not be used forprotecting other resources in the secure domain.

You must also establish groups that you use to delegate management of securitypolicy for protected resources within the secure 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 to the realresources that need protecting.

Example:


Suppose 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:/WebSEAL/

www.company_xyz.com/customers/sales/

An ACL at the root of www.company_xyz.com’s Web space allows public access toeverything in the Web space. An ACL at customers allows access to customers andsales people and another ACL at sales allows access only to sales people. TheseACLs might look like:public-access

user sec_master -abc---Tdm----lrxany-other -------T------lrxunauthenticated -------T------lrx

customer-accessuser sec_master -abc---Tdm----lrxgroup customers -------T------lrxgroup sales -------T------lrxany-other -----------------unauthenticated -----------------

sales-accessuser sec_master -abc---Tdm----lrxgroup sales -------T------lrxany-other -----------------unauthenticated -----------------

These ACLs would be attached respectively at:/WebSEAL/www.compan_xyz.com/WebSEAL/www.company_xyz.com/customers/WebSEAL/www.company_xyz.com/sales

Suppose you have the following delegated user administration policy. Sales people(members of the “sales” group) are allowed to create new accounts for customersand 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 which,in turn, is used to control access to the sales-people-only portion of the Web space.The only permission required is for the “sales-admin” group to be able to add andremove users from this group. The view (v) permission is also useful toadministrators to allow them to view the group membership and the users in thegroup.


sales-admingroup 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 the“sales-admin” group again).sales-users-admin

group super-admin Tabcgroup admin TNWdmv

Similarly the customers-admin ACL is used to administer membership of 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 the salesgroup again). We also allow members of the “sales-admin” group to managecustomers.customers-users-admin

group super-admin Tabcgroup sales TNWdmvgroup admin TNWdmv

Notice in each ACL, a super-admin group entry is granted attach, browse, andcontrol permission. Members of the super-admin group are responsible foradministering these ACLs.


Chapter 7. Managing Access Manager servers

This chapter provides detailed information for performing general administrationand configuration tasks on the Access Manager servers. The configuration files thatsupport each server are also discussed.

This chapter contains the following sections:v “Introducing the Access Manager servers” on page 89v “Starting and stopping Access Manager servers” on page 97v “Starting and stopping servers on Windows systems” on page 98v “Automating server startup at boot time” on page 99v “Policy server administration” on page 99

Introducing the Access Manager serversAccess Manager consists of the following server processes (daemons):v policy server (pdmgrd)v authorization server (pdacld)v WebSEAL (webseald)

The policy server (pdmgrd) manages the master authorization (ACL) database andmaintains location information about other Access Manager servers in a securedomain. The policy server typically requires very little administration orconfiguration.

The authorization server (pdacld) allows third-party applications to makeauthorization calls (via the authorization API) to the Access Manager securityservice. The authorization server typically requires very little administration orconfiguration.

WebSEAL (webseald) is a high performance, multi-threaded Web server thatapplies fine-grained security policy to the protected Web object space. WebSEALcan provide single signon solutions and incorporate back-end Web applicationserver resources into its security policy.

Server dependenciesImportant Access Manager server dependencies include the following:v There can be only one instance of the policy server and the master authorization

(ACL) database in any secure domain.v The policy server replicates the authorization database to all other Access

Manager servers in the secure domain.v Each resource manager (for example, WebSEAL and the authorization server)

applies access control policy based on information from the replicatedauthorization database.

89

Introducing server administration toolsThe following interfaces are available for performing certain administration tasks:v “Using the pd_start utility to start and stop servers”v “Using the pdacld_dump utility to dump file content”v “Using the pdinfo utility to report system information” on page 91v “Using the trace utility to capture Base actions” on page 94

When troubleshooting, these command line utilities can provide status informationand control of individual servers.

Using the pd_start utility to start and stop serversAdministrators can use the pd_start utility to manually stop, start, restart servers,and to display server status. For more information, see “Starting and stoppingAccess Manager servers” on page 97.

Using the pdacld_dump utility to dump file contentThe pdacld_dump allows you to dump the content of a policy database file(master_authzn.db for pdmgrd and pdacld.db for pdacld). While dumping thedatabase file, pdacld_dump examines the content and attempts to ensure that thedatabase is valid. After examining the database, the utility displays a shortsummary of the database file.

The pdacld_dump utility can also be used to copy and construct a new databasefile. While pdacld_dump is examining the content of the database file, it canconstruct a new database file, skipping database entries that it believes are corruptor invalid. This can help to restore an environment with a corrupt database.

Note: The name pdacld_dump is a misnomer. It has nothing to do with thePDAcld authorization server except that it can dump the content of a pdaclddatabase file.

Running the pdacld_dump utility: The pdacld_dump utility is located in thefollowing directory of the Access Manager Base installation:

Web PortalManager

ReplicaAuthzn

Database

MasterAuthorization

Database

UserRegistry

Policy Server(pdmgrd)

WebSEAL(webseald)

Authzn Server(pdacld)

ReplicaAuthzn

Database

Figure 28. Access Manager server components


UNIX:/opt/PolicyDirector/sbin/

Windows:C:\Program Files\Tivoli\Policy Director\sbin\

You must be located in this directory to run the pdacld_dump utility.

Basic pdacld_dump command syntax: You can perform the following tasks withthe pdacld_dump utility:pdacld_dump command

pdacld_dump[–v]

Returns the version of the utility

pdacld_dump[–f]

Outputs db_filename

pdacld_dump[–s]

Displays only the summary which includes the sequence number of thedatabase

pdacld_dump[–r]

Constructs a new database with the path and db_filename containing validentries from the source database (specified by the–f option)

pdacld_dump[–l]

Specifies the level of validation checking with validation_level_# as 1 or 2,where 2 is the default and highest level of validation

pdacld_dump[–t]

Displays objects of ID_type (used with the –s option)

Examples:

v To return the version of the pdacld_dump utility, enter the following command:pdacld_dump -v

This command returns the following:Policy Director ACL Database Viewer v3.9.0 (Build 020311)Copyright (C) IBM Corporation 1994-2002. All Rights Reserved.

v To display the master_authzn.db file, enter the following command:pdacld_dump -f /var/PolicyDirector/db/master_authzn.db

Using the pdinfo utility to report system informationThe purpose of the pdinfo utility is to gather and store current information aboutyour Access Manager computer system. You can send the resulting tar file totechnical support personnel to help them assist you in a problem-solving ortroubleshooting situation. The pdinfo utility operates in an Access Managerenvironment on the following platforms: HP-UX, Solaris, AIX, Linux, andWindows NT/2000.

The pdinfo utility is part of the Access Manager Base (PDRTE) installation. OtherAccess Manager components, such as WebSEAL, contain embedded Perl scriptsthat are executed automatically when you run the pdinfo utility, and provide theappropriate system information for that component.

The pdinfo.cfg configuration file allows you to customize the operation of thepdinfo utility.

Running the pdinfo utility: The pdinfo utility is located in the followingdirectory of the Access Manager Base installation:

Chapter 7. Managing Access Manager servers 91

UNIX:/opt/PolicyDirector/sbin/

Windows:C:\Program Files\Tivoli\Policy Director\sbin\

You must be located in this directory to run the pdinfo utility or, alternatively, usea full path name. When you run the pdinfo utility, you are prompted to providethe full path name for the system information output file. For example (UNIX):# cd /opt/PolicyDirector/sbin# ./pdinfoPlease enter the name (full path) of the desired output fileeg. /tmp/output.tar.gz:

Technical notes:

v In a UNIX environment, you must be logged in as root to successfully run thepdinfo utility.

v The directory containing the output file must have write access.v Ensure there is adequate hard disk space available.v In a Windows environment, a limitation of the pdinfo utility does not allow a

full path name expression for the output file. You must indicate a file name only.This file is then located in the current directory where you are running thepdinfo utility.

v In a Windows environment, the example output file in the pdinfo prompt is:eg. /tmp/output.tar

Contents of the tar file: The tar file resulting from the pdinfo utility contains thefollowing files:v System information output file

This output file name is specified in the pdinfo.cfg configuration file.v Error log file

This file logs errors produced when running the pdinfo utility to. The pdinfoutility invokes other system commands to gather information. This file collectsany errors resulting from these system commands.

v Access Manager configuration, audit, and log filesAll standard Access Manager configuration, audit, and log files are collected inthe tar file.

v Access Manager server core dumpsThe final task of the pdinfo utility is to kill the Access Manager servers (exceptPDRTE) and log the resulting core dump files. Refer to the discussion of$EXECUTE_BLADES below for further information.

Note: You should not run the pdinfo utility in a production environment. Bydefault, the pdinfo utility kills all Access Manager servers in order torecord core dump files. Refer to the discussion of $EXECUTE_BLADESbelow for further information.

Using the pdinfo.cfg configuration file: You can customize the informationgathered by the pdinfo utility using the pdinfo.cfg configuration file.

The pdinfo.cfg configuration file is located in the following directory:

UNIX:


/opt/PolicyDirector/etc/pdinfo/

Windows:C:\Program Files\Tivoli\Policy Director\etc\pdinfo\

The configuration file contains the following information:

Output and error file names: You can specify the default names of the systeminformation output file and the pdinfo-specific error file. The default file namesinclude:$OUTPUT_FILE = "systeminfo.txt";$ERROR_FILE = "error.log";

Access Manager component reporting scripts: This section specifies the location ofreporting scripts for other Access Manager components:$PDMGR_BLADE = "etc/pdinfo_pdmgr_blade.pl";$PDACLD_BLADE = "etc/pdinfo_pdacld_blade.pl";$PDWEB_BLADE = "etc/pdinfo_pdweb_blade.pl";

Note: The current version of the pdinfo tool automatically executes any additionalreporting scripts (written in Perl 5.6) placed in the /etc/pdinfo/ directory ofany Access Manager component (“blade”). The parameters described aboveare no longer used by the utility.

Information types: You can specify the type of information gathered by the pdinfoutility. To enable specific information gathering, set the appropriate parameterequal to “1”. To disable specific information gathering, set the appropriateparameter equal to “0” or, alternatively, comment out the parameter line.

For example:$GATHER_MACHINE_INFO = 1;$GATHER_NETWORK_INFO = 1;$GATHER_PROCESS_INFO = 1;$GATHER_INSTALLED_INFO = 1;$GATHER_PD_INFO = 1;$EXECUTE_BLADES = 1;

Parameter descriptions:

v Machine information ($GATHER_MACHINE_INFO) gathers the machine name,operating system version, system architecture, processors, RAM, virtual memorystatistics, and disk space.

v Network information ($GATHER_NETWORK_INFO) gathers information aboutinterfaces, ARP cache, routing, and open sockets.

v Current processes information ($GATHER_PROCESS_INFO) gathers informationabout current processes running on the system.

v Installed software information ($GATHER_INSTALLED_INFO) gathersinformation about software currently installed on the system.

v Access Manager information ($GATHER_PD_INFO) gathers information aboutthe current state of Access Manager Base.

v Access Manager component information ($EXECUTE_BLADES) runs thereporting scripts for other configured Access Manager components.This is the section of the pdinfo utility where the Access Manager servers arekilled in order to record the resulting core dump files. The kill operation occurs


within the Perl script for each server/”blade”. You can therefore control the killoperation on a per-server basis by modifying the appropriate script for thatserver.Alternatively, you can disable the running of all Perl scripts by setting$EXECUTE_BLADES=0.

Example configuration file:#### Constant definitions$OUTPUT_FILE = "systeminfo.txt";$ERROR_FILE = "error.log";

$PDMGR_BLADE = "etc/pdinfo_pdmgr_blade.pl";$PDACLD_BLADE = "etc/pdinfo_pdacld_blade.pl";$PDWEB_BLADE = "etc/pdinfo_pdweb_blade.pl";

### CHANGE VARIABLES HERE TO DETERMINE WHAT INFORMATION IS GATHERED### BY DEFAULT ALL INFORMATION IS GATHERED - TO PREVENT INFORMATION BEINGGATHERED, COMMENT OUT THE APPROPRIATE VARIABLE, OR SET IT TO 0

### MACHINE INFORMATION: Machine Name, O/S Version, System Architecture,Processors, RAM, VM Stats, Disk Space$GATHER_MACHINE_INFO = 1;

### NETWORK INFORMATION: interfaces, arp cache, routing, open sockets$GATHER_NETWORK_INFO = 1;

### CURRENT PROCESSES: Current processes running on the system$GATHER_PROCESS_INFO = 1;

### INSTALLED SOFTWARE: Current installed software on the system$GATHER_INSTALLED_INFO = 1;

### PD INFORMATION: information regarding the current state of PD$GATHER_PD_INFO = 1;

### EXECUTE PDWEB, ACLD, MGR, AND OTHER BLADES$EXECUTE_BLADES = 1;

Using the trace utility to capture Base actionsThe trace utility allows you to capture information about error conditions andprogram control flow in Access Manager Base. This information is stored in a fileand used for debugging purposes. The trace utility is provided primarily to assistsupport personnel in diagnosing problems occurring with the functioning of theAccess Manager software.

As a user, you might find some of the Base tracing components useful. However,the majority are of little benefit unless you are diagnosing complex problems withthe assistance of technical support personnel.

Note: Use trace with caution. It is intended as a tool to use under the direction oftechnical support personnel. Messages from trace are sometimes cryptic, arenot translated, and can severely degrade system performance.

Basic trace command syntax:pdadmin> server task webseald-instance trace command

You can perform the following tasks with the pdadmin trace command:

trace set Enable the trace level and trace message destination for a component andits subordinates


trace show Show the name and level for all enabled trace components or for thespecified component

trace list List all available trace components

Enable trace: Use the pdadmin trace set command to enable the gathering of traceinformation for the specified component and level.trace set component level [log-agent]


component The trace component name. Required. WebSEAL-specific componentsare prefixed with “pdweb”.

level Reporting level. Required. The level argument specifies the amount ofdetail gathered by the trace utility. The range is 1 to 9. Level 1 specifiesthe most detailed output and level 9 specifies the least detailed output.

logagent Optionally specifies a destination for the trace information gathered forthe specified component. Refer to the “Using event logging” chapter ofthe IBM Tivoli Access Manager Base Administrator’s Guide for completeconfiguration details.

Show enabled trace components: List all enabled trace components or a specificenabled component. If a specified component is not enabled, no output isdisplayed.trace show [component]

Example:pdadmin> server task webseald-instance trace set pdweb.debug 2pdadmin> server task webseald-instance trace showpdweb.debug 2

List all available trace components: List the specified component or all componentsavailable to gather and report trace information.trace list [component]

WebSEAL trace components:

pdweb.debug: Note: The pdweb.debug component only operates at level 2.

The following command invokes the trace utility for the pdweb.debug componentat level 2, and directs the output to a file, using the event logging mechanism tospecify a file log agent.pdadmin> server task webseald-<instance> trace set pdweb.debug 2 \file path=/opt/pdweb/log/debug.log

The sample output of this command as it appears in the debug.log file:/src/wand/wand/log.c:277: -------------- Browser ===> PD --------------Thread_ID:17GET /test/index.html HTTP/1.1Host: bevanUser-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:0.9.4)Gecko/20011128 Netscape6/6.2.1Accept: text/xml, application/xml, application/xhtml+xml, text/html;q=0.9,image/png, image/jpeg, image/gif;q=0.2, text/plain;q=0.8, text/css,*/*;q=0.1Accept-Language: en-usAccept-Encoding: gzip, deflate, compress;q=0.9


Accept-Charset: ISO-8859-1, utf-8;q=0.66, *;q=0.66Keep-Alive: 300Connection: keep-alive---------------------------------------------------

/src/wand/wand/log.c:277: -------------- PD ===> BackEnd --------------Thread_ID:17GET /index.html HTTP/1.1via: HTTP/1.1 bevan:443host: mokum.santacruz.na.tivoli.comuser-agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:0.9.4)Gecko/20011128 Netscape6/6.2.1accept: text/xml, application/xml, application/xhtml+xml, text/html;q=0.9,image/png, image/jpeg, image/gif;q=0.2, text/plain;q=0.8, text/css,*/*;q=0.1accept-language: en-usaccept-charset: ISO-8859-1, utf-8;q=0.66, *;q=0.66accept-encoding: gzip, deflate, compress;q=0.9keep-alive: 300connection: close---------------------------------------------------

/src/wand/wand/log.c:277: -------------- PD <=== BackEnd --------------Thread_ID:17content-type: text/htmldate: Mon, 25 Mar 2002 19:48:32 GMTcontent-length: 7017etag: "0-1b69-3b688e48"last-modified: Thu, 02 Aug 2001 00:18:32 GMTserver: IBM_HTTP_SERVER/1.3.19 Apache/1.3.20 (Win32)connection: closeaccept-ranges: bytes---------------------------------------------------

/src/wand/wand/log.c:277: -------------- Browser <=== PD --------------Thread_ID:17HTTP/1.1 200 Document followscontent-type: text/htmldate: Mon, 25 Mar 2002 19:48:32 GMTcontent-length: 7017etag: "0-1b69-3b688e48"last-modified: Thu, 02 Aug 2001 00:18:32 GMTserver: IBM_HTTP_SERVER/1.3.19 Apache/1.3.20 (Win32)connection: closeaccept-ranges: bytes---------------------------------------------------

Server configuration filesYou can use the server configuration files to customize the operation of eachAccess Manager server:

Server Name Configuration File Configuration File Location

Policy server ivmgrd.conf UNIX: install_path/etc/ivmgrd.confWindows: install_path\etc\ivmgrd.conf

Authorization server ivacld.conf UNIX: install_path/etc/ivacld.confWindows: install_path\etc\ivacld.conf

WebSEAL webseald.conf UNIX: /opt/pdweb/etc/webseald.confWindows: C:\Program Files\Tivoli\PDWeb\etc\webseald.conf


Access Manager Base program files are installed in the following defaultdirectories:

UNIX: /opt/PolicyDirector/Windows: C:\Program Files\Tivoli\Policy Director\

This guide uses the install_path variable to represent this root directory. All relativepath names expressed in the Access Manager configuration files are relative to thisroot directory.

Configuration files are ASCII text-based and can be edited using a common texteditor. The configuration files contain parameter entries in the following format:parameter=value

The initial installation of Access Manager establishes default values for mostparameters. Some parameters are static and never change; others can be modifiedto customize server functionality and performance.

Note: After editing a configuration file, you must stop and restart the AccessManager server before the changes take effect.

Each file contains sections, or stanzas, containing one or more parameters for aparticular configuration category. The stanza labels appear within brackets[stanza-name].

For example, the [ssl] stanza in ivmgrd.conf defines the SSL configurationsettings for the policy server. The stanza [ldap] defines configuration required bythe policy server to communicate with the LDAP registry server.

The files contain comments that explain the use of each parameter.

If you find that you must change any configuration settings, carefully edit the filesto ensure their integrity.

Starting and stopping Access Manager servers

Starting and stopping servers on UNIX systemsServer processes are normally enabled and disabled through automated scripts thatrun at system startup and shutdown.

In a UNIX environment, you can also use the pd_start script to manually start andstop the server processes. This technique is useful when you need to customize aninstallation or when you need to perform troubleshooting tasks. You can only runscripts on the local machine. Use the Web portal manager to stop and start serversremotely.

The general syntax for pd_start is as follows:# pd_start {start|restart|stop|status}

You can run the pd_start utility from any directory. The script resides in thefollowing directory:/opt/PolicyDirector/bin/


Start the Access Manager Servers using the pd_start utilityUse the pd_start utility to start all Access Manager servers not currently runningon a particular machine:# pd_start start

This script waits until all servers have started before returning the prompt.

Start individual servers manuallyYou can manually start the servers individually by executing the server directly.

You must perform the startup commands as an administration user, such as root.

Start the Access Manager servers in the following order:1. For the policy server (pdmgrd), enter the following:

install_path/bin/pdmgrd

2. For the authorization server (pdacld), enter the following:install_path/bin/pdacld

Restart the Access Manager servers using the pd_start utilityUse the pd_start utility to stop all Access Manager servers on a particular machineand then restart the servers:pd_start restart

This script waits until all servers have started before returning the prompt.

Stop the Access Manager servers using the pd_start utilityUse the pd_start utility to stop all Access Manager servers on a particular machinein the correct order:pd_start stop

This script 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

Access Manager Servers:Server Enabled Running

pdmgrd yes yeswebseald no nopdacld yes no

Starting and stopping servers on Windows systemsUse the Windows NT Services Control Panel to start and stop the server processesmanually. This can be useful when customizing an installation or whentroubleshooting. Administrative privileges are required to use this utility.

You can start and stop the Access Manager servers all at once or individually. Theservers generally must be stopped and started in the correct order.

Using the Services Control Panel to stop and start serversThe AutoStart Service automatically starts each of the Access Manager serverswhenever the Startup configuration is set to “Automatic”. After the servers start,the AutoStart Service exits.


You can also use the Services Control Panel to manually start and stop theindividual servers:1. Open the Windows Control Panel.2. Double-click the Services icon.

The Services dialog box appears.3. From the list box, select the Access Manager servers according to the sequence

indicated in Steps 4 and 5.4. Stop the Access Manager servers in the following order:

v authorization serverv policy server

5. Start the Access Manager servers in the following order:v policy serverv authorization server

6. Click the appropriate control option button (Start, Stop, Startup) from theright-hand side of the box.

7. To prevent automatic starting of a Access Manager server by the AutoStartService, use the Startup... button to set that server to Disabled.

Automating server startup at boot timeParameters for automating server startup are located in the [pdrte] stanza of thepd.conf configuration file.

Policy serverWhen the PDMgr package is installed, the policy server automatically starts aftereach system reboot:[pdrte]boot-start-ivmgrd = yes

To prevent automatic pdmgrd startup, set:boot-start-ivmgrd = no

Note: Each secure domain must contain only one. Do not install and run pdmgrdon more than one server per secure domain.

Authorization serverWhen the PDAcld package is installed, the authorization server daemonautomatically starts after each system reboot:[pdrte]boot-start-ivacld = yes

To prevent automatic pdacld startup, set:boot-start-ivacld = no

Policy server administrationThe policy server manages the master authorization policy database and maintainslocation information about other Access Manager servers in the secure domain. Thepolicy server typically requires very little administration or configuration. Thissection describes configuration tasks available to the administrator.v “Replicating the authorization database” on page 100


v “Setting the number of update notifier threads” on page 101v “Setting the notification delay time” on page 101

Replicating the authorization databaseAn Access Manager administrator can make security policy changes to the securedomain at any time. A primary responsibility of the policy server is to make thenecessary adjustments to the master authorization database to reflect thesechanges.

When the policy server makes a change to the master authorization database, itcan send out notification of this change to all authorization servers (with replicadatabases). The authorization servers must then request a database update fromthe master authorization database.

Note: Additionally, client servers can check for database updates by polling thepolicy server at regular intervals. Polling configuration for a WebSEALclient, for example, is explained in the IBM Tivoli Access Manager WebSEALAdministrator’s Guide.

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 parameter is located in the [ivmgrd] stanza of theivmgrd.conf configuration file. By default, the parameter is set to yes (updatenotification 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-timeparameters. See “Setting the number of update notifier threads” on page 101 and“Setting the notification delay time” on page 101.

When you configure update notification to be manual, manual application of thepdadmin server 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 which soon become obsoletebecause of the continuing changes to the master database. These obsoletenotifications cause unnecessary network traffic.

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 parameter setting. See “Setting the number of update notifierthreads” on page 101.


Using the pdadmin server replicate commandWhen you configure update notification to be manual, manual application of thepdadmin server replicate command controls this event. The command has thefollowing syntax:pdadmin> server replicate [-server <server-name>]

If the optional server-name argument is specified, only that server is notified ofchanges to the master authorization database. A response is returned indicating thesuccess or failure of the notification and the replication.

If the server-name argument is not specified, all configured authorization serversreceive update notifications. A successful response only indicates 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 execute this command is “s” on the/Management/Server object.

Setting the number of update notifier threadsThe policy server is responsible for synchronizing all database replicas in thesecure domain. When a change is made to the master database, notification threadsdo the work of announcing this change to all replicas. Each replica then has theresponsibility to download the new information from the master.

The policy server configuration file, ivmgrd.conf, contains a parameter 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 should be set to at least 30. If there are more than 30 replicas, another roundof notifications occurs (in this example, 30 at a time). All replicas are guaranteed tobe notified, regardless of the value of this parameter.

The performance goal of the update notifier threads value is to announce adatabase change as quickly as possible. Generally the value should be set to equalthe 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:[ivmgrd]max-notifier-threads = 10

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 of a series of database changes. The timedelay helps to ensure optimal performance of the Access Manager system.


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 have been made.

You can override this default notification time delay by changing thenotifier-wait-time parameter value (in seconds), located in the [ivmgrd] stanza ofthe ivmgrd.conf configuration file. For example:[ivmgrd]notifier-wait-time = 20

By default, the value is set to 15 seconds.


Chapter 8. Using the LDAP registry

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

The default installation of Access Manager uses the LDAP directory to store userinformation. IBM’s implementation of LDAP is known as IBM SecureWayDirectory. iPlanet’s implementation of LDAP is known as iPlanet Directory Server.This chapter discusses configuration features of the Access ManagerLDAP registry.

This chapter contains the following sections:v “LDAP overview” on page 103v “LDAP fail-over configuration” on page 106v “Applying Access Manager ACLs to new LDAP suffixes” on page 109

LDAP overviewIn 1988, the CCITT (Consultative International Telephonique et Telegraphique,which is now ITU-T, International Telecommunications Union -TelecommunicationStandardization Sector) created a standard for directory services known as X.500.The X.500 directory service soon became ISO standard 9594 (Data CommunicationsNetwork Directory, Recommendations X.500-X.521) in 1990.

The ISO set of standards is still commonly referred to as X.500. X.500 defines adirectory that can be universally used for large amounts of data. Today, X.500directories are used by national telephone organizations for large, online telephonedirectories.

To access an X.500 directory, a client uses the Directory Access Protocol (DAP) thatwas defined along with the X.500 standard. Unfortunately, DAP is a rathercomplex protocol that cannot be easily supported on thin clients, such as desktopcomputers.

X.500 was therefore limited to powerful computers and large-scaleimplementations. The requirement to access centralized directories from slimclients, however, became important to support the obvious cost-effectiveness ofcentralized directories.

Work performed at the University of Michigan and at Netscape CommunicationsCorporation led to a simplified version of DAP, called the Lightweight DirectoryAccess Protocol (LDAP). LDAP supports most of the features of DAP, but lackssome of the complex and seldom used functions. The LDAP implementation isrelatively simple and can be used by desktop applications.

LDAP: A protocol for directory servicesLDAP 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.

103

Note: The LDAP standard does not define how the data is stored in the directory.

Initially, LDAP was designed to allow thin clients to access an X.500 directorythrough a gateway server that did translation between LDAP and DAP.

Soon, directories were developed that could handle the LDAP protocol nativelyrather than performing a translation between LDAP and DAP.

The IBM implementation of an LDAP directory is the SecureWay Directory, whichis available on AIX, Windows NT, Sun Solaris, OS/400, and OS/390.

An LDAP directory can use any storage implementation for the directory data.While most implementations use flat file databases, the IBM SecureWay Directoryuses the high-performance, highly-scalable DB2 relational database as its storageimplementation.

LDAP directoriesMost directories store information similar to the structure of a printed phone book.The entries are usually organized in a hierarchical way that allows efficient andflexible management and searching.

LDAP directories are much more powerful and are not limited to name, phonenumber, and address entries. In fact, an LDAP directory can store (andsubsequently retrieve) almost any kind of data. The type of data that can be storedin an LDAP directory is defined by the directory schema, which can be extendedand adapted to meet your requirements.

The task of defining a directory schema and the hierarchical directory informationtree can be compared to the design of a relational database. Thorough analysis ofapplication requirements, corporate standards, and data definitions is necessary todesign a directory schema and the directory information tree (DIT).

LDAPClient Directory

LDAPGatewayServer

X.500Server

TCP

LDAP

OSI

DAP

Figure 29. LDAP access to X.500

LDAPClient Directory

LDAPServer

TCP

LDAP

Figure 30. Stand-alone LDAP server


LDAP server products, such as the IBM SecureWay Directory, provide acomprehensive schema that can be used, unless requirements dictate specificmodifications.

IBM supports current and evolving standards and proposals for data definitions byactively participating in the standards process and by implementing the results inthe IBM SecureWay Directory. The most important standards body for LDAP is theInternet Engineering Task Force (IETF), where representatives of IBM and otherkey industry leaders actively support these activities.

Every organization uses directories. For example, most modern operating systems,such as UNIX or Windows 9x/NT, store user account information either locally oron departmental servers. Network operating systems, such as NetWare (Novell),also require user databases. Departments can maintain a local employee database,while at the corporate level, there are large human resource databases. In addition,operating systems store large amounts of data about system configuration andother network resources, such as printers and servers.

Information is often stored across multiple locations, making administration andmaintenance unnecessarily difficult. A major reason why LDAP has quicklygathered so much interest is the potential for a single, standards based directoryfor distributed information.

The LDAP information modelThe LDAP information model is based on a subset of the X.500 information model.Data in an LDAP directory is stored in entries that contain attributes. Attributes aretyped in the form:type = value

where the type is defined by an object identifier (OID), and the value has a definedsyntax. Attributes can be single-valued (for example, a person can only have onedate-of-birth) or multi-valued (a person can have multiple phone numbers).

Each entry in an LDAP directory has a unique distinguished name (DN). Thedirectory schema defines rules for DNs and what attributes an entry must contain.To organize the information stored in directory entries, the schema defines objectclasses. An object class consists of mandatory and optional attributes.

Object classes can be inherited from other object classes, which provides a methodfor easy extensibility (for example, new object classes can be defined by justadding new attributes to existing object classes).

LDAP features

ScalabilityLDAP directories, particularly when they are backed up by a relational database asin the IBM SecureWay Directory, are highly scalable. Large directories with millionsof entries are possible with excellent performance.

Due to the common standard base, another scalability factor is the easy step-uppossibility to more powerful hardware and software. LDAP does not rely on aspecific operating system and is vendor-independent.

Chapter 8. Using the LDAP registry 105

AvailabilityLDAP supports replication and splitting of namespaces. Replication allowsmultiple LDAP servers to store the same directory contents. Clients benefit fromthese additional servers available whenever one fails.

Splitting allows sections of the whole directory to be stored on different servers atdifferent locations. This not only increases availability (no single point of failure)but also offers an easy way for distributed management.

SecurityLDAP supports security features that prevent unauthorized access to data. Securecommunication protocols, such as SSL and authentication mechanisms, along withaccess control lists (ACL) policies for data entries, guarantee a maximum level ofsecurity.

ManageabilityCurrent versions of LDAP, such as the IBM SecureWay Directory, provide agraphical user interface for both system administration and directory dataadministration. Dynamically extensible schema allows you to extend the directoryschema without interrupting the service.

StandardizationThe LDAP protocol—and many related client/server capabilities, applicationprogramming interfaces (APIs), and data definitions—are defined by either officialstandards or corresponding RFCs (Request for Comments).

Lightweight Directory Access Protocol (v3), RFC 2251, for example, defines thebasic LDAP protocol. Other features, that are widely accepted and implemented,are defined in Internet drafts. Much of this work is done by the IETF (InternetEngineering Task Force) and the DMTF (Distributed Management Task Force).

LDAP fail-over 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 implements theLDAP protocol is an LDAP directory server.

The LDAP distributed architecture supports scalable directory services with serverreplication capabilities. Server replication improves the availability of a directoryservice. IBM SecureWay Directory replication is based on a master-slave model.iPlanet Directory Server replication is based on a supplier/consumer model. AccessManager still treats this as a master/slave relationship.

The combination of a master server and multiple replicated servers helps ensurethat directory data is always available when needed. If any server fails, thedirectory service continues to be available from another replicated server. AccessManager supports this replication capability.

The master-slave replication modelReplication involves two types of directories: master and replica. LDAP refers tothe master as master server and to the replica as replica server. All updates aremade on the master server and these updates are subsequently propagated to thereplica servers. Each replica server database contains an exact copy of the masterserver’s directory data.


Changes to the directory can be made only to the master server, which is alwaysused for write operations to the directory. Either the master or the replicas can beused for read operations. When the original master server is out of service for anextended period of time, a replica server can be promoted as a master server toallow write operations to the directory.

Access Manager fail-over capability for LDAP serversAccess Manager connects to the LDAP master server when it starts up. If theLDAP master server is down for any reason, the Access Manager server must beable to connect to an available LDAP replica server for any read operations.

Many operations, especially those from regular users, are read operations. Theseinclude such operations as user authentication and signon to back-end junctionedWeb servers. After proper configuration, Access Manager will fail-over to a replicaserver when it cannot connect to the master server.

You can find the configuration parameters for LDAP fail-over in the [ldap] stanzaof the ldap.conf configuration file:

UNIX: /opt/PolicyDirector/etc/ldap.confWindows: install_path\etc\ldap.conf

Master server configurationIBM SecureWay Directory (LDAP) supports the existence of a single read-writemaster LDAP server. iPlanet Directory Server supports multiple read-write LDAPservers. Access Manager treats the iPlanet “supplier” server as the master serverfor 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 AccessManager configuration. For example:[ldap]enabled = yeshost = outbackport = 389ssl-port = 636max-search-size = 2048

Parameter Description

enabled Access Manager uses an LDAP user registry. Values are “yes”and “no”.

host The network name of the machine where the LDAP masterserver is located.

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 Access Manager limit for an LDAP client search of databaseitems - such as a request for the Web portal manager to list usersfrom the LDAP database.

If you make a change to the LDAP database, such as adding a new user accountthrough the Web portal manager, Access Manager always uses the read-write(master) LDAP server.


Replica server configurationIBM SecureWay Directory (LDAP) supports the existence of one or more read-onlyreplica LDAP servers. iPlanet Directory Server (LDAP) supports the existence ofone or more read-only replica LDAP servers referred to as “consumers”.

You must add lines to the [ldap] stanza that identify any replica servers availableto Access Manager. Use the following syntax for each replica:replica = ldap_server,port,type,preference


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 - either “read-only” or“read-write”. Normally, use “read-only”. A “read-write” typewould represent a master server.

preference A number from 1 - 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,5replica = replica2.ldap.tivoli.com,389,readonly,5

Changes to the ldap.conf file do not take effect until you restart Access Manager.

Setting preference values for replica LDAP serversEach replica LDAP server must have a preference value (1-10) that determines itspriority for selection as:v The primary read-only access server, orv A backup read-only server during a fail-over

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 hard-coded defaultpreference setting of 5. This allows you to set replica servers at values higher orlower than the master to obtain the required performance. For example, withappropriate preference settings, you could prevent the master server from handlingeveryday read operations.

You can set hierarchical preference values to allow access to a single LDAP server(with fail-over to the other servers), or set equal preferences for all servers andallow load balancing to dictate server selection.

The following table illustrates some possible preference scenarios. “M” refers to themaster (read-only/read-write) LDAP server; “R1, R2, R3” refer to the replica(readonly) LDAP servers.


M R1 R2 R3 Fail-over Preference

5 5 5 5 All servers have the same preference values. Loadbalancing determines which server is selected for eachaccess operation.

5 6 6 6 The three replica servers have the same preferencevalue. This value is higher than the master servervalue. Load balancing determines server selectionamong the three replicas. The master is only used ifall three replica servers become unavailable.

5 6 7 8 Server 3 (with the highest preference value) becomesthe primary server. If server3 fails, server 2 becomesthe primary server because it has the next highestpreference value.

Preference values only affect read-only access to the LDAP database. AccessManager always uses the master (read-write) server when you need to make achange to the LDAP database.

Also note that some Access Managerdaemons (such as the policy server) overridethe preference settings in their configuration files to indicate that the read-writeserver is preferred. This is because those daemons usually make update operationswhich should go to the master LDAP server.

Server pollingIf an LDAP server does fail, Access Manager continuously polls the server to checkfor its return to active duty. The poll time is 10 seconds.

Applying Access Manager ACLs to new LDAP suffixes

Note: The following information applies to both IBM SecureWay Directory Serverand iPlanet Directory Server.

When an LDAP administrator adds LDAP suffixes after the initial configuration ofAccess Manager, the administrator must apply the appropriate Access Control Lists(ACLs) to allow Access Manager to manage users and groups defined in these newsuffixes.

For IBM SecureWay Directory, use the Directory Management Tool to apply ACLs.For Netscape LDAP server, use the iPlanet Console 5.0.

Use the appropriate LDAP administration interface to apply the following ACLs toevery new Access Manager suffix:

LDAP Group Access Control

cn=SecurityGroup,secAuthority=Default

v full access

cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default

v read

v search

v compare

cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default


LDAP Group Access Control

v read

v search

v compare

These controls apply when the administrator has selected LDAP for the AccessManager user registry and a new LDAP suffix has been created after AccessManager is initially configured. It is assumed that you are the Access Manageradministrator and are familiar with both Access Manager and LDAP. It is furtherassumed that, as administrator, you have the proper authority to update the LDAPDirectory Information Tree.

When Access Manager is configured, it attempts to apply appropriate ACLs toevery LDAP suffix that exists at that time in the LDAP server. This access controlallows Access Manager to create and manage user and group information withinthese LDAP suffixes.

However, if a suffix is created after Access Manager has been configured, andAccess Manager must later be able to create and manage user and groupinformation within this new suffix, then the appropriate access controls need to beapplied manually. Without these access controls, Access Manager does not have theappropriate LDAP permission to create and manage user and group informationspecified to be within this new suffix.

To apply the appropriate access controls to the newly created LDAP suffix, performthe following steps for either the IBM SecureWay Directory or the iPlanet DirectoryServer, depending on the LDAP server type being used.

Note that the procedures assume that the newly created suffix is called“o=neworg,c=us”. You should substitute the actual newly created suffix for thisvalue in the following descriptions.

Procedures for the IBM SecureWay Directory serverThe following steps describe how to apply the appropriate Access Manager accesscontrols to the newly created suffix for the IBM SecureWay Directory Server.1. Start the LDAP Directory Management Tool (DMT) with one of the following

commands:On Windows systems: Start →Programs → IBM SecureWay Directory →Directory Management Tool

On UNIX systems:# /usr/bin/dmt

2. The following warning might appear:Warning: Entry o=neworg,c=us does not contain any data.

Dismiss the warning. In step 8 on page 111, you will need to recall if you haveseen this warning.

3. Click the Add Server button in the left pane. The Add Server windowappears.

4. Enter these values for each of the following fields:


Field Value Comment

Server Name: ldap://hostname For example, ibm007.ibm.com

Port: 389 389 is the default port

User DN: cn=root DN of the LDAP administrator

User Password: abc123 Password of the LDAPadministrator

5. Click OK. The Directory Management Tool page appears.6. Verify the server name in the upper part of the left frame. For example,

ldap://ibm007.ibm.com:389

7. From the tree structure on the left, select Directory Tree → Browse Tree. Thefollowing warning might appear:Warning: Entry o=neworg,c=us does not contain any data.

8. Skip to step 9 if you have not seen the following message:Warning: Entry o=neworg,c=us does not contain any data.

If you have seen this message, you must create an entry for the suffix. Accesscontrol cannot be applied to the suffix until an entry exists. Follow these stepsto create an entry:a. Click the Add button in right pane. The Add an LDAP Entry dialog box is

displayed.b. Set the entry type to Organization. Set the parent DN to c=us. Set the

entry DN to o=neworg. Click OK. The entry page for organization isdisplayed within the Add an LDAP dialog box.

c. Enter the organization name (neworg) in the Attributes section at the o:label.

d. Click Add. The Browse Directory Tree page is displayed.9. Click Directory Tree → Refresh Tree in the left pane.

10. Highlight the newly created suffix in the Browse Tree pane on the right.11. Click the ACL button in the right pane. The current access control list settings

for the suffix are displayed in the Edit an LDAP ACL window.12. In the Subject area of the Edit an LDAP ACL window, enter the following

Distinguished Name:cn=SecurityGroup,secAuthority=Default

Check the group type and click Add.13. When the window is displayed, make the following selections:

v In the DN entry box, select Descendant directory tree entries inherit fromthis entry.

v In the Rights box, for Add child and Delete entry, select Grant.v In the Security class box, for each security class (Normal, Sensitive, and

Critical), select Grant for each permission (Read, Write, Search, andCompare).

Click OK.14. Highlight the newly created suffix in the Browse Tree pane on the right.15. Click the ACL button in the right pane. Verify that the

cn=SecurityGroup,secAuthority=Default group is listed and the settings forthe group are correct. Group names are not case-sensitive.


16. In the subject area of the Edit an LDAP ACL window, enter the followingDistinguished Name:cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default

Select the group Type and click Add.17. When the window is displayed, make the following selections:


v In the Rights box, for Add child and Delete entry, select Unspecified.v In the Security class box, for the Normal security class, select Grant for the

Read, Search and Compare permissions.v In the Security class box, for the Normal security class, select Unspecified

for the Write permissions.v In the Security class box, for the Sensitive and Critical security classes,

select Unspecified for all permissions.

Click OK.18. Highlight the newly created suffix in the Browse Tree pane on the right. Click

the ACL button in the right pane. Verify that the cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default group is listed and thesettings for the group are correct. Group names are not case-sensitive.

19. In the Subject area of the Edit an LDAP ACL window, enter the followingDistinguished Name:cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default

Select the group Type and click Add.20. When the window is displayed, make the following selections:


v In the Rights box, select Unspecified for Add child and Delete entry.v In the Security class box, for the Normal security class, select Grant for the

Read, Search, and Compare permissions.v In the Security class box, for the Normal security class, select Unspecified

for the Write permission.v In the Security class box, for the Sensitive and Critical security classes,

select Unspecified for each permission (Read, Write, Search, andCompare).

Click OK.21. Click Exit to close the Directory Management Tool.

Procedures for iPlanet Directory ServerNote that these procedures describe the creation of ACLs for suffixes using theiPlanet Console 5.0.1. Start the iPlanet Console 5.0 with one of the following commands:

v On UNIX systems, enter the following from the iPlanet Directory serverinstall directory:# ./startconsole

v On Windows systems, click: Start → Programs → iPlanet Server Products →iPlanet Console 5.0


2. Enter the User ID for the LDAP administrator. This is usually cn=DirectoryManager. Enter the password and the Administration URL. Click OK.

3. Select the Domain to be used by Access Manager.4. Expand the server name and Server Group.5. Select the entry labeled Directory Server. Configuration information about the

iPlanet Directory server is displayed.6. Click the Open button. The iPlanet Directory server is accessed.7. Click the Directory tab. If the newly created suffix is displayed in the left

pane, skip to step 8If the newly created suffix does not appear in the left pane, you must createan entry for the new suffix before applying access controls to the suffix.Follow these steps to create the entry:a. Highlight the name of the server at the top of the directory tree. Click

Object → New Root Object. A list of root suffixes is displayed.b. Select o=neworg,c=us from the list of root suffixes. The New Object

selection window is displayed.c. In the New Object selection window, scroll down and select Organization

as the new object entry type.d. Click OK. The Property Editor window is displayed.e. Fill in the Organization field as neworg and click OK.

Note: These instructions assume an example suffix. Create the entry typeand name which corresponds to your actual suffix.

f. Click View → Refresh. The new suffix entry appears in the left pane.8. Highlight the neworg entry in the left pane. Click Object → Set Access

Permissions. The Manage Access Control for o=neworg,c=us window isdisplayed.

9. Click New to display the Edit ACI for o=neworg, c=us window.10. Specify the ACI name as SECURITY GROUP - ALLOW ALL.11. Highlight the All Users name and click Remove.12. Click Edit Manually. The Edit ACI for o=neworg,c=us window is displayed.13. Replace the default ACI text with the following:

(target="ldap:///o=neworg,c=us")(targetattr="*")(version 3.0; acl "SECURITY GROUP - ALLOW ALL";allow (all)groupdn = "ldap:///cn=SecurityGroup,secAuthority=Default";)

Click Check Syntax to ensure that you have entered the text correctly. Correctany errors until the syntax passes the check.

14. Click OK. The Manage Access Control for o=neworg,c=us window isdisplayed.

15. Click New. Specify the ACI name asPD Servers GROUP - ALLOW READ

16. Highlight the All Users name and click Remove.17. Click Edit Manually. The Edit ACI for o=neworg,c=us window is displayed.18. Replace the default ACI text with the following:

(target="ldap:///o=neworg,c=us")(targetattr="*")(version 3.0; acl "SECURITY GROUP - ALLOW READ";allow(read, search, compare)groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default";)




20. Click New. Specify the ACI name as PD Remote ACL Users GROUP -ALLOW READ.21. Highlight the All Users name and click Remove.22. Click Edit Manually. The Edit ACI for o=neworg,c=us window is displayed.23. Replace the default ACI text with the following:

(target="ldap:///o=neworg,c=us")(targetattr="*")(version 3.0; acl "SECURITY GROUP - ALLOW READ";allow (read, search, compare)groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default";)



25. Click New. Specify the ACI name as PD Deny-Others1.26. Highlight the All Users name and click Remove.27. Click Edit Manually. The Edit ACI for o=neworg,c=us window is displayed.28. Replace the default ACI text with the following:

(targetfilter="(|(objectclass=secUser)(objectclass=secGroup))")(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";)



30. Click New. Specify the ACI name as PD Deny-Others2.31. Highlight the All Users name and click Remove.32. Click Edit Manually. The Edit ACI for o=neworg,c=us window is displayed.33. Replace the default ACI text with the following:

(targetfilter="(|(objectclass=secPolicyData)(objectclass=secPolicy))")(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";)



35. Click OK to close the Manage Access Control for o=neworg,c=us window.36. Click Console → Exit to exit the console.


Chapter 9. Logging and auditing server activity

Access Manager provides a number of logging and auditing capabilities. Log filescan capture any error and warning messages generated by Access Manager servers.Audit trail files can capture authorization, authentication, management, and HTTPevents occurring on the Access Manager servers.

This chapter contains the following sections:v “Introduction to logging and auditing” on page 115v “Audit trail files”v “Logging Base serviceability messages” on page 116v “Access Manager audit trail files” on page 117v “Audit trail file format” on page 120v “Audit trail file contents” on page 121

Introduction to logging and auditingThe contents of log and audit trail files can be a useful source of information whenmonitoring and troubleshooting the activity of Access Manager servers.

Audit trail filesAudit trail files are used by the Access Manager servers to store records of serveractivity. The output of a specific server event is called a record. An audit trail is acollection of multiple records that document the server activity. All AccessManager audit trail files are in ASCII format.

Access Manager audit trail files record events for the following servers:v policy server (pdmgrd)v authorization server (pdacld)v WebSEAL (webseald)

See “Access Manager audit trail files” on page 117.

See “Audit trail file format” on page 120.

See “Audit trail file contents” on page 121.

Documentation convention: install_pathThe install_path variable used throughout this chapter has the followinginterpretations, according to operating system platform:

UNIX: /opt/PolicyDirector/Windows: \Program Files\Tivoli\Policy Director

This pathname is fixed in UNIX and cannot be modified.

The Windows platform allows you to define install_path during the installation ofthe Access Manager software.

115

Logging Base serviceability messagesAccess Manager Base serviceability messages are controlled by the Access ManagerBase routing file. The routing file is located in the following directory:

UNIX:/opt/PolicyDirector/etc/

Windows:C:\Program Files\Tivoli\Policy Director\etc\

The routing file is an ASCII file that contains additional documentation in theform of comment lines. Entries in this configuration file determine the types ofserviceability messages that are logged. Enable any entry by removing thecomment character (#). The routing file includes the following default entries:

UNIX:FATAL:STDOUT:-;FILE:/var/PolicyDirector/log/fatal.logERROR:STDOUT:-;FILE:/var/PolicyDirector/log/error.logWARNING:STDOUT:-;FILE:/var/PolicyDirector/log/warning.logNOTICE:FILE.10.100:/var/PolicyDirector/log/notice.log#NOTICE_VERBOSE:STDOUT:-;FILE:/var/PolicyDirector/log/verbose.log

Windows:FATAL:STDERR:-;FILE:%PDDIR%/log/fatal.logERROR:STDERR:-;FILE:%PDDIR%/log/error.logWARNING:STDERR:-;FILE:%PDDIR%/log/warning.logNOTICE:FILE.10.100:%PDDIR%/log/notice.log

Note: On a Windows system, the special environment variable PDDIR is set at runtime to the Access Manager installation directory.

By default, when Access Manager Base runs in the foreground, messages arehandled in the following manner:1. Messages are sent to the screen (STDOUT, STDERR).2. Messages are sent to the appropriate configured log file entries in the log

directory (fatal.log, error.log, warning.log, notice.log).

By default, when Access Manager Base runs in the background, messages arehandled in the following manner:1. Messages are redirected from STDOUT and STDERR and sent to the

appropriate server log file as defined in the [logging] stanza of the appropriateserver configuration file.

Server ConfigurationFile

Log File Location

Policy server

(pdmgrd)

ivmgrd.conf UNIX:[logging]log-file=/var/PolicyDirector/log/ivmgrd.log

Windows:[logging]log-file=install_path\log\ivmgrd.log


Server ConfigurationFile

Log File Location

Authorization server

(pdacld)

ivacld.conf UNIX:[logging]log-file=/var/PolicyDirector/log/ivacld.log

Windows:[logging]log-file=install_path\log\ivacld.log

2. Messages are also sent to the appropriate configured log file entries in the logdirectory (fatal.log, error.log, warning.log, notice.log).

To enable verbose.log, uncomment the NOTICE_VERBOSE line.

The FILE syntax for the NOTICE message controls log roll over and file recycling:FILE.max_files.max_records

The max_file value specifies the number of files that are used.

The max_records value specifies the maximum number of entries per file.

In the default example above, FILE.10.100 means there are 10 files created, eachwith a maximum of 100 entries. The files are named:notice.log.1notice.log.2...notice.log.10

The messages “wrap around” to the first file after the last file has reached its limitor when the server is stopped and restarted. When a log file is reused, the existingrecords are written over (erased).

Access Manager audit trail filesAuditing is defined as the collection of data about system activities that affect thesecure operation of the Access Manager authorization process. Each AccessManager server can capture audit events whenever any security related auditableactivity occurs.

Audit events are saved as audit records that document the specific activity of thatserver. Each audited activity is referred to as an audit event. A collection of auditevent records stored in a file is referred to as an audit trail.

Each Access Manager server maintains its own audit trail file. The Access Managerservers include:v policy server (pdmgrd)v authorization server (pdacld)v WebSEAL (webseald)v User-developed applications using Authorization ADK (Refer to the Access

Manager Authorization ADK Developer Reference)

Chapter 9. Logging and auditing server activity 117

Parameters for configuring Access Manager server audit trail files are located inthe [aznapi-configuration] stanza of each of the <server-name>.conf files.

Server server-name Configuration File

policy server pdmgrd ivmgrd.conf

authorization server pdacld ivacld.conf

WebSEAL webseald webseald.conf

Enabling and disabling auditingAudit trail recording is enabled on a server-by-server basis by setting the logauditvalue in the [aznapi-configuration] stanza of the configuration file for the specificserver.

By default auditing is disabled:[aznapi-configuration]logaudit = no

A value of yes enables auditing for that server. For example:[aznapi-configuration]logaudit = yes

Specifying the log file locationBy default the audit trail file for each server is called audit.log and is held in thespecific server’s log directory. The auditlog parameter in each server’sconfiguration file specifies the location of the audit trail file.

Server Log File Location

policy server

(pdmgrd)

UNIX:auditlog=/var/PolicyDirector/audit/pdmgrd.log

Windows:auditlog=C:\pd\audit\pdmgrd.log

authorization server

(pdacld)

UNIX:auditlog=/var/PolicyDirector/audit/pdacld.log

Windows:auditlog=C:\pd\audit\pdacld.log

Specifying audit file rollover thresholdsThe logsize parameter specifies the maximum size to which each of the audit trailfiles can grow and has the following default value (in bytes):[aznapi-configuration]logsize = 2000000

When an audit trail file reaches the specified value—known as its rolloverthreshold—the existing file is backed up to a file of the same name with anappended current date and timestamp. A new audit trail file is then started.

The various possible logsize values are interpreted as follows:v If the logsize value is less than zero (< 0), then a new audit trail file is created

with each invocation of the auditing process and every 24 hours from thatinstance.


v If the logsize value is equal to zero (= 0), then no rollovers are performed andthe audit trail file grows indefinitely. If an audit trail file already exists, new datais appended to it.

v If the logsize value is greater than zero (> 0), then a rollover is performed whenan audit trail file reaches the configured threshold value. If an audit trail filealready exists at startup, new data is appended to it.

Specifying the frequency for flushing audit file buffersAudit trail files are written to buffered data streams. If you are monitoring theaudit trail files in real time, you might want to alter the frequency with which theserver forces a flush of the audit trail file buffers.

By default, audit trail files are flushed every 20 seconds:[aznapi-configuration]logflush = 20

If you specify a negative value, a flush is forced after every record is written.

Specifying audit eventsAudit events are categorized by the server functionality that generates them. Somefunctionality is common across Access Manager servers while other functionality isserver-specific. Each type of server functionality is associated with an audit tag:

Audit tag Server functionality

authn Credential acquisition authentication auditing

azn Authorization event auditing.

mgmt Management command auditing

http Webseal HTTP request auditing

You can configure each Access Manager server to selectively capture audit eventson a category by category basis. For example the following configuration capturesonly authentication events and disable the capture all other events, includingoverriding any authorization auditing enabled in POP settings.[aznapi-configuration]auditcfg = authn

The following settings enable WebSEAL HTTP request and authorization auditing,but disable all other audit categories for the WebSEAL server:[aznapi-configuration]auditcfg = httpauditcfg = authn

By default, when auditing is enabled for a process with no configured audit tags,all auditable events are captured.

The following table indicates the auditing events (indicated by the audit tag) thatcan be captured for each specific Access Manager server.

Audit Tag webseald pdmgrd pdacld authadk

authn X X X X

azn X X X X

mgmt X


Audit Tag webseald pdmgrd pdacld authadk

http X

Audit trail file formatAudit events are captured in the audit trail in a standard format using XML-styletags. Although XML is only an intermediary step to delivering a presentation viewof the data, the XML file is in ASCII format and can be read directly or passed toother external parsing engines for further analysis.

An entire audit trail does not represent a single XML document. Each audit eventwithin the file is written as an isolated XML data block. Each data block conformsto the rules of standard XML syntax.

As an audit administrator, you are expected to select and extract events accordingto your own criteria. This might include reformatting each event by applying anappropriate DTD (Document Type definition) or schema for the analysis tool youare using. The DTD is an intermediate format that provides a description of thedata that can be captured.

A suggested DTD is shown below.<!ELEMENT event (date, outcome, originator, accessor, target, data*)><!ATTLIST event

rev CDATA "1.1"link CDATA #IMPLIED >

<!ELEMENT date (#PCDATA)><!ELEMENT outcome (#PCDATA)><!ATTLIST outcome

status CDATA #IMPLIED><!ELEMENT originator (component, event, location)><!ATTLIST originator

blade CDATA #REQUIRED><!ELEMENT component rev CDATA “1.0”><!ELEMENT action (#PCDATA)><!ELEMENT location (#PCDATA)><!ELEMENT accessor (principal*)><!ATTLIST accessor

name CDATA #REQUIRED><!ELEMENT principal (#PCDATA)><!ATTLIST principal

auth CDATA #REQUIRED><!ELEMENT target (object, process?, azn?)><!ATTLIST target

resource CDATA #REQUIRED><!ELEMENT object (#PCDATA)><!ELEMENT process (pid, rid, eid, uid, gid)><!ATTLIST process

architecture (unix | nt) ’unix’><!ELEMENT pid #PCDATA><!ELEMENT rid #PCDATA><!ELEMENT eid #PCDATA><!ELEMENT uid #PCDATA><!ELEMENT gid #PCDATA><!ELEMENT azn (perm, result, qualifier)><!ELEMENT perm #PCDATA><!ELEMENT result #PCDATA><!ELEMENT qualifier #PCDATA><!ELEMENT data #PCDATA><!ATTLIST data

tag CDATA #REQUIRED>


Because Access Manager auditing uses a standard record format, not all fields arerelevant to every event recorded. Generally each event captures the result of anaction that a principal attempts on a target object.

Information about the action, the principal’s credentials, the target object, and theoutcome are captured in a common format header of the audit record. Fields thatare not relevant for a particular event might contain a default value. Additionalevent-specific information can also be recorded in a free format data area at theend of the record.

Decoding the meaning of certain data values in the records might require anadvanced knowledge of the Access Manager code and architecture.

Status attribute of the outcome fieldThe outcome field always includes a Access Manager status code and an outcomevalue. The possible outcome values include:0 = SUCCESS1 = FAILURE2 = PENDING3 = UNKNOWN

You can use the pdadmin errtext command to provide interpretation for the policyDirector status code (412668954 in the following example).<outcome status=”412668954”>1</outcome>

Resource attribute of the target fieldThe resource attribute of the target field represents a broad categorization of thetarget object:0 = AUTHORISATION1 = PROCESS2 = TCB3 = CREDENTIAL5 = GENERAL

Audit trail file contents

Authorization audit recordsAuthorization is the primary function of the Access Manager servers.Authorization audit records can be captured when a target object in the AccessManager authorization policy database (protected object space) has a POP attachedto it that enables audit functionality.

See Chapter 4, “Using protected object policies” on page 61.

You can configure auditing for a particular server by adding “azn” to the auditconfiguration list in the [aznapi-configuration] stanza of the server’s configurationfile:[aznapi-configuration]auditcfg = azn

The following record is a sample audit record for the following event:pdadmin> pop modify pop1 set audit-level all


<event rev="1.1"><date>2001-08-05-16:25:08.341+00:00I-----</date><outcome status="0">0</outcome><originator blade="pdmgrd"><component rev=”1.1”>mgmt</component><action>13702</action><location>phaedrus</location></originator><accessor name=""><principal auth="IV_LDAP_V3.0">sec_master</principal></accessor><target resource="5"><object></object></target><data>“13702”“pop1”“pop1”“false”“15”“0”“““0”“0”“0”“127”“1”“0”“0”“0”</data></event>

Authentication audit recordsAuthentication of a principal is performed externally to Access Manager duringcredential acquisition. Audit records can be captured by Access Manager to recordthe success or failure of such authentication attempts.

You can configure auditing of authentication attempts by adding “authn” to theaudit configuration list in the [aznapi-configuration] stanza of the server’sconfiguration file:[aznapi-configuration]auditcfg = authn

The following is a sample authentication event logged from WebSEAL for anunauthenticated user.<event rev="1.1"><date>2001-08-05-23:04:26.630+00:00I-----</date><outcome status="0">0</outcome><originator blade="webseald"><component>authn</component><event rev="1">0</event><location>location not specified</location></originator><accessor name="unknown"><principal auth="invalid"></principal></accessor><target resource="5"><object></object></target><data></data></event>

WebSEAL audit recordsWeb server activity can be optionally recorded in the audit trail file in addition to,or in place of, the standard HTTP Common Log format files described in the IBMTivoli Access Manager WebSEAL Administrator’s Guide.


You can configure auditing of WebSEAL activity by adding “http” to the auditconfiguration list in the [aznapi-configuration] stanza of the WebSEAL server’sconfiguration file (webseald.conf):[aznapi-configuration]auditcfg = http

The following is a sample HTTP access audit record:<event rev="1.1"><date>2001-08-05-23:04:26.931+00:00I-----</date><outcome status="412668954">1</outcome><originator blade="webseald"><component>http</component><event rev="1">2</event><location>146.84.251.70</location></originator><accessor name="user not specified"><principal auth="IV_DCE_V3.0">cell_admin</principal></accessor><target resource="5"><object>/pics/pd30.gif</object></target><data></data></event>

Management Audit RecordsThe responsibilities of the policy server include maintaining the masterauthorization policy database. This database includes the description of theprotected object space for the secure domain, ACL and POP policies, and whereACLs and POPs are attached to objects.

You can configure auditing of the policy server activity by adding “mgmt” to theaudit configuration list in the [aznapi-configuration] stanza of the policy server’sconfiguration file (ivmgrd.conf):[aznapi-configuration]auditcfg = mgmt

The following is a sample event record of the following pdadmin command:pdadmin> pop modify pop1 set audit-level all<event rev="1.1"><date>2001-08-05-23:01:37.078+00:00I-----</date><outcome status="0">0</outcome><originator blade="ivmgrd"><component>mgmt</component><event rev="1">3702</event><location>location not specified</location></originator><accessor name="user not specified"><principal auth="IV_DCE_V3.0">cell_admin</principal></accessor><target resource="5"><object></object></target><data>"2019""1002""pop1""0"""</data></event>

Event field ID codes for management commandsThe audit records for management commands contains an event ID code thatidentifies one of the Access Manager management (pdadmin) commands.Command arguments are listed in the data section of the event record in theirinternal format.


Note that commands which do not result in an effective change of state of thedatabase (such as list and show) are never captured.

ACL Management Commands

ACL_LIST 13000

ACL_GET 13001

ACL_SET 13002

ACL_DELETE 13003

ACL_FIND 13005

ACTION_LIST 13006

ACTION_SET 13007

ACTION_DELETE 13008

ACTION_GROUPLIST 13009

ACTION_GROUPCREATE 13010

ACTION_GROUPDELETE 13011

ACTION_LISTGROUP 13012

ACTION_CREATEGROUP 13013

ACTION_DELETEGROUP 13014

Object Management Commands

OBJSPC_CREATE 13103

OBJSPC_DELETE 13104

OBJSPC_LIST 13105

OBJ_CREATE 13106

OBJ_DELETE 13107

OBJ_MOD_SET_NAME 13110

OBJ_MOD_SET_DESC 13111

OBJ_MOD_SET_TYPE 13112

OBJ_MOD_SET_ISLF 13113

OBJ_MOD_SET_ISPOL 13114

OBJ_MOD_SET_ATTR 13115

OBJ_MOD_DEL_ATTR 13116

OBJ_MOD_DEL_ATTRVAL 13117

OBJ_SHOW_ATTR 13118

OBJ_LIST_ATTR 13119

ACL_ATTACH 13120

ACL_DETACH 13121

ACL_MOD_SET_ATTR 13123

ACL_MOD_DEL_ATTR 13124

ACL_MOD_DEL_ATTRVAL 13125

ACL_SHOW_ATTR 13126

ACL_LIST_ATTR 13127

POP_MOD_SET_ATTR 13128

POP_MOD_DEL_ATTR 13129


POP_MOD_DEL_ATTRVAL 13130

POP_SHOW_ATTR 13131

POP_LIST_ATTR 13132

OBJ_SHOW_ATTRS 13133

ACL_SHOW_ATTRS 13134

POP_SHOW_ATTRS 13135

OBJ_SHOW 13136

OBJ_LIST 13137

OBJ_LISTANDSHOW 13138

Server Management Commands

SERVER_GET 13200

SERVER_LIST 13203

SERVER_PERFORMTASK 13204

SERVER_GETTASKLIST 13205

SERVER_REPLICATE 13206

Admin, User, and Group Management Commands

ADMIN_SHOWCONF 13400

USER_CREATE 13401

USER_IMPORT 13402

USER_MODDESC 13403

USER_MODPWD 13404

USER_MODAUTHMECH 13405

USER_MODACCVALID 13406

USER_MODPWDVALID 13407

USER_DELETE 13408

USER_SHOWGROUPS 13409

USER_SHOW 13410

USER_SHOWDN 13411

USER_LIST 13412

USER_LISTDN 13413

GROUP_CREATE 13414

GROUP_IMPORT 13415

GROUP_MODDESC 13416

GROUP_MODADD 13417

GROUP_MODREMOVE 13418

GROUP_DELETE 13419

GROUP_SHOW 13420

GROUP_SHOWDN 13421

GROUP_LIST 13422

GROUP_LISTDN 13423

GROUP_SHOWMEMB 13424

USER_MODGSOUSER 13425


USER_SET 13426

GROUP_SET 13427

13500 →13599 are used by GSO

GSO_RESOURCE_CREATE 13500

GSO_RESOURCE_DELETE 13501

GSO_RESOURCE_LIST 13502

GSO_RESOURCE_SHOW 13503

GSO Resource Credential Commands

GSO_RESOURCE_CRED_CREATE 13504

GSO_RESOURCE_CRED_DELETE 13505

GSO_RESOURCE_CRED_MODIFY 13506

GSO_RESOURCE_CRED_LIST 13507

GSO_RESOURCE_CRED_SHOW 13508

GSO Resource Group Commands

GSO_RESOURCE_GROUP_CREATE 13509

GSO_RESOURCE_GROUP_DELETE 13510

GSO_RESOURCE_GROUP_ADD 13511

GSO_RESOURCE_GROUP_REMOVE 13512

GSO_RESOURCE_GROUP_LIST 13513

GSO_RESOURCE_GROUP_SHOW 13514

Policy Commands

POLICY_SET_MAX_LOGIN_FAILURES 13600

POLICY_GET_MAX_LOGIN_FAILURES 13601

POLICY_SET_DISABLE_TIME_INTERVAL 13602

POLICY_GET_DISABLE_TIME_INTERVAL 13603

POLICY_SET_MAX_ACCOUNT_AGE 13604

POLICY_GET_MAX_ACCOUNT_AGE 13605

POLICY_SET_ACCOUNT_EXPIRY_DATE 13606

POLICY_GET_ACCOUNT_EXPIRY_DATE 13607

POLICY_SET_MAX_INACTIVITY_TIME 13608

POLICY_GET_MAX_INACTIVITY_TIME 13609

POLICY_GET_ACCOUNT_CREATION_DATE 13610

POLICY_GET_LAST_LOGIN_ATTEMPT_DATE 13611

POLICY_SET_MAX_PASSWORD_AGE 13612

POLICY_GET_MAX_PASSWORD_AGE 13613

POLICY_SET_MIN_PASSWORD_AGE 13614

POLICY_GET_MIN_PASSWORD_AGE 13615

POLICY_SET_MAX_PASSWORD_REPEATED_CHARS 13616

POLICY_GET_MAX_PASSWORD_REPEATED_CHARS 13617

POLICY_SET_MIN_PASSWORD_ALPHAS 13618

POLICY_GET_MIN_PASSWORD_ALPHAS 13619

POLICY_SET_MIN_PASSWORD_NON_ALPHAS 13620


POLICY_GET_MIN_PASSWORD_NON_ALPHAS 13621

POLICY_SET_MIN_PASSWORD_DIFFERENT_CHARS 13622

POLICY_GET_MIN_PASSWORD_DIFFERENT_CHARS 13623

POLICY_SET_PASSWORD_SPACES 13624

POLICY_GET_PASSWORD_SPACES 13625

POLICY_SET_MIN_PASSWORD_LENGTH 13626

POLICY_GET_MIN_PASSWORD_LENGTH 13627

POLICY_SET_MIN_PASSWORD_REUSE_TIME 13628

POLICY_GET_MIN_PASSWORD_REUSE_TIME 13629

POLICY_GET_PASSWORD_FAILURES 13630

POLICY_GET_LAST_PASSWORD_CHANGE_DATE 13631

POLICY_SET_NUMBER_WARN_DAYS 13632

POLICY_GET_NUMBER_WARN_DAYS 13633

POLICY_SET_PASSWORD_REUSE_NUM 13634

POLICY_GET_PASSWORD_REUSE_NUM 13635

POLICY_SET_TOD_ACCESS 13636

POLICY_GET_TOD_ACCESS 13637

POP Commands

POP_CREATE 13700

POP_DELETE 13701

POP_MODIFY 13702

POP_SHOW 13703

POP_LIST 13704

POP_ATTACH 13705

POP_DETACH 13706

POP_FIND 13707

Configuration Commands 13800 → 13899

CFG_CONFIG 13800

CFG_UNCONFIG 13801

CFG_REBNEWCERT 13802

CFG_CHGPORT 13803



Chapter 10. Using event logging

This chapter describes enhancements to the recording of Access Manager log files.Prior versions of Access Manager recorded events in several unrelated log files,usually with each log file having a different method to configure the capture ofinformation to disk.

The concept of the information-to-capture has now been abstracted from the actionof recording that information to a file. This loose coupling was introduced tosupport centralized collection and recording of audit trails. The new functionalityalso offers greater flexibility for the configuration and capture of other AccessManager event data.

Understanding Access Manager eventsApart from some messages produced when starting a program, all messagesgenerated by Access Manager for auditing and other serviceability purposes arenow created in a structured hierarchy of Access Manager events.

The orderly categorization of events within this hierarchy allows runtimeassociations to be made between classes of events and the log agents to be used torecord those events. Additionally the concept of a log agent has been expanded toinclude recording of events to destinations other than the local file system. Theevent hierarchy is built up dynamically during program execution. While somewell known event categories can be expected to be present when running anAccess Manager program, other categories are program specific and some might betransient.

The purpose of this chapter is to describe how you can associate log agents with apoint in the event pool hierarchy to record events. This chapter does not provide adescription of the characteristics of all possible events within the hierarchy. Fordescriptions of well-known events such as those generated for auditing, refer tothe appropriate product-specific documentation.

Generally, the event pool hierarchy is similar to the following:

129

A specific event category is identified by a dot-separated list of names. The firstlevel of name within the category has special significance. This top-level categoryname also might correspond to events previously associated with legacy log filesdescribed in prior releases of Access Manager.

For example, assume the event category name is constructed as follows:domain_category.sub_category.sub_category...

Event domains of audit, http and messages correspond respectively to the eventsrecorded for Tivoli SecureWay Policy Director, Version 3.7, in the audit trail, theWebSEAL http request logs, and the Distributed Computing Environment (DCE)serviceability message logs. Several new event domains were introduced in Version3.8, including trace, statistics and remote. Trace and statistics events gatherserviceability information about program execution. Remote events implement thecentralized collection and recording of log files.

Implementation note: For efficiency, an event is not generally created if there areno log agents subscribed to record events of that category. In the case that an eventis generated and there are no log agents subscribed to record it, the event isdiscarded.

Configuring event loggingIn addition to the backward-compatible method of configuring log files, you canspecify line items in the [aznapi-configuration] stanza of a program’sconfiguration (.conf) file to configure the capture of Access Manager events.

To enable the recording of Access Manager events using the new interface, youmust associate a logging destination with a category of events in the event pool.Currently four types of destinations are supported for the capture of events:v Console log agentv File log agentv Pipe log agentv Remote log agent

Event Pool

audit

httpmgmtauthnazn

remote trace

pd

http

clf

ras bas bas

ref agent

Figure 31. Event pool hierarchy


The format of a log agent configuration line is as follows:logcfg =<category>:{stdout|stderr|file|pipe|remote} \[[<param>[=<value>]][<param>[=<value>]]]

Options for these log agent types can be specified in any order and are generallyoptional. Valid options for each log agent type are described below. In aconfiguration entry, the option names are case insensitive and can be abbreviatedto any shortened length of the full option name that remains unique.

For example, consider the following simplified form:logcfg = <category>:<log-agent>

The category name can point to any node in the event pool hierarchy. Capture ofevents for a category is inclusive of all subcomponents in the hierarchy. That is, afoo.bar.fred event also is captured at the foo.bar category.

You can attach multiple log agents to the same category. For example, thefollowing configuration copies authorization audit events to a file and relays themto a program listening on a pipe:logcfg = audit.azn:file path=/var/PolicyDirector/log/audit.aznlogcfg = audit.azn:pipe path=/bin/analyse.exe

The following diagram depicts the relationships between steps in the loggingprocess. The top third of the diagram represents the code of an Access Managerserver. The programmer added probe points to the code where events of specifictypes might be generated. Generated events are then submitted to the server’sevent pool for possible recording through a point of capture (the sink), whichdefines the events category.

At runtime, a user can subscribe a log agent at any point in the event poolhierarchy to selectively record events generated at the programs probe points. Thisis depicted in the middle band of the diagram.

One log agent that you can subscribe to capture events is a remote log client. Thisclient forwards the selected events to a remote pdacld server. The bottom band ofthe diagram depicts this remote server. Note that the bottom band is essentially thesame as the top band with the relayed events placed in the event pool at pdacld’s

Chapter 10. Using event logging 131

remote probe points.

TraceEventSink

AuditEventSink

Event Pool

ApplicationSpecific Probe

Points

Standard PolicyDirector Server

Remote Loggingpdacld server

Multiple OtherNetworkedLog Clients

Subscribed log agent

ConsoleFile

Adaptor

FileAdaptor

PipeAdaptor

ConsoleLog Log

File

LogFile

RemoteLog

Server

EventSink

EventPool

Subscribed LogAgents

RemoteLog

Client

OtherAdaptorEvent

Cache

Configuring the central event propagation queueEvents are passed to subscribed log agents asynchronously to the application-levelrequests that construct the events for recording. Events initially pass through acommon propagation queue before they are fanned out to the variously subscribedlog agents.

The servicing profile of this propagation queue is configurable. To configure thepropagation queue, you must specify an abridged format logcfg entry. Theshortened configuration entry uses EventPool as the category name and specifiesqueuing options without giving a log destination type. For example:logcfg = EventPool:queue_size=number,hi_water=number,flush_interval=number

Specifying the maximum number of events to queue inmemory

To control the amount of memory that can be consumed by events on thepropagation queue, you can set a limit for the maximum size the queue is allowedto grow to. If the maximum size is reached when a new event is generated, the


thread attempting to queue it is blocked until space is available in the queue. Thishas the effect of throttling back performance of the event producing thread to thespeed of the logging threads, if it cannot keep up.

The default value for queue_size is 0. A zero queue size indicates that no limit isenforced on the growth of the event queue. Keep in mind that using the defaultcan allow the unprocessed event queue to grow to an unmanageable size whenevents are produced at a faster rate than the subscribed log agents can clear them.

Specifying the event queue high water markProcessing of the event queue is scheduled regularly at the configured flushinterval. It is also triggered asynchronously by the queue size reaching a highwater mark.

The default value for hi_water is 1024. If you specify a value for queue_size, butno hi_water value, the default hi_water is calculated as two-thirds the maximumconfigured queue size. If the maximum queue size is 0, the high water mark is setto a default of 100.

If the event queue high water mark is set to 1, every event queued is relayed toany subscribed log agents as soon as possible. Note that setting a low value forhi_water can have an adverse effect on overall performance.

Specifying the frequency for flushing log file buffersUse the flush_interval option to specify a limit on the time an event waits in thepropagation queue before it is forwarded to the log agents. If events are beinggenerated at a slow rate that does not trigger handling by reaching the high watermark in a timely manner, events are flushed from the propagation queue at thisfrequency.flush_interval=<seconds>

The flush_interval default value is 10 seconds. A flush_interval of 0 is notallowed. Specifying a value of 0 results in the queue being flushed every 600seconds.

Console loggingLogging to the console is the easiest option to configure. Simply associate anoutput destination of standard out or standard error with the category of events inthe Event Pool to capture:logcfg = <category>:{stdout|stderr}

Example configurations are as follows:v To capture all audit output to standard out, specify the following:

logcfg = audit:stdout

v To capture only authorization audit events to standard error, specify thefollowing:logcfg = audit.azn:stderr

Logging to the console does not itself use any queuing. The events are written tothe console as they are received from the propagation queue. Note however thatevents might be delayed in the propagation queue depending on its queue settings.


If you are using console output and running a server in foreground for debuggingpurposes, you might want to set the propagation queue settings accordingly. Forexample, set the hi_water option to a low value.

File loggingTo record events in a file, specify a log file configuration as follows:logcfg = category:file path=file_pathname, \flush_interval=seconds, \rollover_size=number, \log_id=logid, \queue_size=number, \hi_water=number, \buffer_size=number, \mode={text|binary}

A file is only opened once. If multiple configuration entries exist to selectivelycapture events at different points of the event pool hierarchy to the same file, thefile opens according to the options found in the first configuration entry processed.

Once a file has been opened, further file configurations can simply use theshorthand notation:logcfg = <category>:file log_id=<logid>

to record events to the same file.

Because writing to file can be a slow operation relative to the tasks generatingevents, events are posted to a file log agent through a second level of queuing.This second level of event queuing is configured in a similar manner to the centralevent propagation queue, but has different default values.

Specifying the log file locationUse the path option to specify the location of a log file. There is no default valuefor the file pathname because the log_id value takes precedence. An example pathvalue for the WebSEAL audit trail file on UNIX is as follows:path=/var/pdweb/log/audit.log

The directory portion of this pathname must exist. The log file is created if it doesnot already exist.

Specifying the log file IDAn open log file is associated with a short name identifier to facilitate therecording of events from different categories to the same file.

Use the log_id option to set the log file ID explicitly; otherwise, it is given adefault value. If the path option is specified, the default value is the configuredpath name. If path is not specified, the log ID defaults to the domain component ofthe event category being captured. For example:logcfg = audit.azn:file

implieslog_id=audit.


To capture events to a common file, set the log file ID to a suitable value in afully-optioned file configuration. Subsequently, use the shorthand configurationvariant to capture events from additional categories as shown:logcfg = audit.azn:file path=/opt/PolicyDirector/log/audit.log, \rollover_size=-1,flush=20,log_id=audit

logcfg = audit.authn:file log_id=audit

Because of the defaulting rules, this configuration is also equivalent to thefollowing specification:logcfg = audit.azn:file \path=/opt/PolicyDirector/log/audit.log,rollover_size=-1

logcfg = audit.authn:file

If you construct a configuration where the log_id value does not match any openlog file, no events are captured. For example, the following configuration does notrecord any events because the configuration line that initializes the log file hasbeen commented out:#logcfg = audit.azn:file path=/tmp/azn.log,log_id=aznlogcfg = audit.authn:file log_id=azn

Specifying the maximum log file sizeUse the rollover_size option to specify the maximum size to which a log file cangrow. This option has the following default value (in bytes):rollover_size=2000000

When a log files size reaches the specified value, known as its rollover threshold,the existing file is backed up to a file of the same name with an appended currentdate and time stamp. A new log file is then started.

The various possible rollover_size values are interpreted as follows:v If the rollover_size value is less than zero (< 0), a new log file is created with

each invocation of the process and every 24 hours from that instance.v If the rollover_size value is equal to zero (= 0), no rollovers are performed and

the log file grows indefinitely. If a log file already exists, new data is appendedto it.

v If the rollover_size value is greater than zero (> 0), a rollover is performed whena log file reaches the configured threshold value. If a log file already exists atstartup, new data is appended to it.

Specifying the maximum buffer sizeTo reduce memory fragmentation and improve the performance of writing to file,rather than queuing many small events individually to the file log agent, eventscan be buffered into blocks of a nominated size before queuing for writing. Thebuffer_size option specifies the maximum size message the program attempts toconstruct by combining smaller events into a large buffer.

Buffers only consist of an integral number of events; events are not split acrossbuffers. If any individual event exceeds that maximum configured size, the largeevent is recorded in a buffer of its own, exceeding the configured value.buffer_size=number_of_bytes

The default buffer size for logging to file is 0 bytes. This value prevents bufferingand each event is handled individually.


If a value is specified for the buffer_size, events are packed into buffers of thatsize before queuing to the file log agent.

For example if the buffer_size value is set to 2 KB and events are assumed to beabout 256 bytes, around 10 are packed into each buffer written to file. This reducesthe number of disk I/Os made while logging to 10% of the equivalent nonbuffering case.

Note that a default queue size of 200 with a buffer_size of 2 KB also consumesaround 10 times the memory of a default configuration that did no buffering(assuming an event size of around 200 bytes). This is because the maximum queuesize value has not been changed, but the size of events being queued has increasedtenfold.

Specifying the maximum number of events to queue inmemory

There is a delay between events being placed on the queue and the file log agentremoving them. The queue_size option specifies the maximum size to which thequeue is allowed to grow. If the maximum size is reached when a new event isready to be placed on the queue, the requesting thread is blocked until space isavailable in the queue. This has the effect of throttling back performance of theevent propagation thread to the speed of the file logging thread, if it cannot keepup.

The default value for queue_size is 0. A zero queue size means that no limit isenforced on the growth of the unprocessed event queue. Correspondingly, theevent propagation thread is not constrained by the speed of the logging thread.Keep in mind that using the default can result in the unrecorded event queuegrowing to an unmanageable size, if events are being generated faster than theycan be recorded to file.

Specifying the event queue high water markProcessing of the event queue is scheduled regularly at the configured flushinterval. It also is triggered asynchronously by the queue size reaching a highwater mark on the event queue.

The default value for hi_water is two-thirds of the maximum configured queuesize. If the maximum queue size is zero, the high water mark is set to a default of100.

The transaction rates and the values of these options determine the maximumamount of memory that is consumed by enabling event logging to file.

If the event queue high water mark is set to 1, every event queued is relayed tothe log agent as soon as possible. This setting is not recommended, although youmight want to use it if you want to ensure events get to disk as fast as possible, atthe expense of overall performance.

Specifying the frequency for flushing log file buffersThe flush_interval option is a multi use option.

The logging to file flush_interval option has the following default value inseconds.flush_interval=20


A flush interval of 0 is not allowed. Specifying a value of 0 results in the value 600being used.

Log files are written to buffered data streams. To ensure stream buffers are flushedto disk regularly, the frequency with which the server asynchronously forces aflush of the file stream to disk is configurable using this option.

If you specify a negative value, the absolute value is used as the asynchronousflush frequency, but a stream flush is also forced synchronously after every recordis written.

If events are being consolidated into large buffers by specifying a buffer_sizeoption, the flush_interval parameter also might affect the size of buffer written. Ifthere is a partially filled buffer in memory when a flush is scheduled, that buffer isalso queued for writing before it completes the buffer fill.

Lastly, the event queue is triggered for processing at the flush interval rate. Thisprevents events waiting to be processed for longer than the scheduled flush timewhen the queue high water mark is not reached between scheduled flushes.

Specifying the file modeUse the mode option to open a file in either text or binary mode. For example:mode={text|binary}

Text mode is deprecated on UNIX platforms and has no effect. On WIN32platforms, opening a file in text mode enables end-of-line character translations inthe log file. Binary mode on a windows platform writes the log file in a UNIXcompatible format.

Pipe loggingUse the pipe option to write output to the standard input of another program. Forexample:logcfg=<category>:pipe path=<program_pathname>, \queue_size=<number>, \hi_water=<number>, \flush_interval=<number>

The named program must exist and be executable. The administrator is responsiblefor ensuring the security of the program that is to be run.

Each occurrence of a pipe agent in the configuration file invokes a new copy of thepipe program. Unlike logging to file, piped events are not multiplexed fromdifferent category capture points to a single copy of the program.

Specifying the program to runUse the path option to specify the location of the program, which receives the logoutput on standard input. For example:path=/opt/risk_analyser/bin/my_log_watcher

Note that there is no default value for the path name.


Specifying the event queuing profileConfigure the pipe logging event queue management in the same way that youconfigure logging to file. The queue_size, hi_water, and flush_interval optionshave similar meaning to the options described for file logging.

Remote loggingUse the remote option to send events to a remote server for recording. Forexample:logcfg = category:remote \buffer_size=size, \compress={yes|no}, \error_retry=timeout, \path=name, \flush_interval=number, \rebind_retry=timeout, \server=hostname, \port=number, \dn=identity, \queue_size=number,hi_water=number

Requests to log an event remotely are accepted on a best effort basis only. If theremote server is not available, captured events are cached locally and relayed at alater date, if and when the remote server becomes available.

Only one remote logging connection is established to a remote server. If multipleconfiguration entries are made to selectively capture events at different points ofthe event pool hierarchy to the same remote server, the remote connection isestablished according to the options of the first remote configuration entryprocessed. Multiple remote connections can be configured to log to differentremote servers.

Events received at the remote server are placed in that servers event pool in adifferent location to where they were originally captured on the client system. Allevents entering a host through the remote logging service are placed in a categoryconstructed in the following manner:remote.<client-category-domain>.<hostname>.<program>

For example, all audit events logged remotely from program pdmgrd on hostamazon appear on the remote log server under pool remote.audit.amazon.pdmgrd.This allows for the remote server to selectively record events in a variety ofdestinations using standard configurations. For example, all audit events from hostamazon can be recorded centrally on host timelord by a configuration such as:

On host amazon to relay events remotely:logcfg = audit:remote buffer=2000,compress=y,error=2, \path=/opt/PolicyDirector/log/remote.cache,rebind=600,server=timelord,port=7136

On host timelord to record events to file:logcfg = remote.audit:file path=consolidated_audit.log

logcfg = remote.audit.amazon.pdmgrd:file path=amazon_pdmgrd_audit.log

Specifying the maximum buffer sizeTo reduce network traffic, events are buffered into blocks of the nominated sizebefore relaying to the remote server. The buffer_size option specifies the maximum


size message the local program attempts to construct by combining smaller eventsinto a large buffer. Buffers only consist of an integral number of events; events arenot split across buffers. If any individual event exceeds that maximum configuredsize, the large event is sent in a buffer of its own, exceeding the configured value.buffer_size=number_of_bytes

The default buffer size is 1024 bytes.

Specifying the frequency for flushing the consolidation bufferIf events are being consolidated into very large buffers and there is not muchlogging activity, events can sit in memory for a long time before being forwardedto the remote server or being written to the cache file. The flush_interval optionlimits the time a process waits to fill a consolidation buffer. For example:flush_interval=<seconds>

The default flush interval is 20 seconds. A flush interval of 0 is not allowed.Specifying a value of 0 results in the buffer being flushed every 600 seconds.

Specifying the queue sizesThe queue_size and hi_water values for a remote logging connection are similar tothose specified for logging to file. The default values are as follows:queue_size=0hi_water=100

Specifying compression of messagesAccess Manager events are principally text messages. To reduce network traffic usethe compress option to compress buffers prior to transmission and expand onreception. For example:compress={yes|no}

The default compress value is no.

Specifying the error retry timeoutIf a send to a remote service fails, it is retried after a wait of this period in seconds.If the retry also fails the link is marked down and this event and future events aresaved in the local event cache file until the remote service is rebound.error=seconds

The default error retry timeout is 2 seconds.

Specifying the cache file locationThe path option specifies the location of a cache file on the local host. The cachefile name defaults to ./server.cache, where server is the name of the remoteserver being logged to.

If the running process cannot establish communication with the remote server, orthe link fails during operation, event recording switches to storing events in thespecified file until the server again becomes available. When the server is available,events are drained from the disk cache and relayed to the remote server.

For example, suppose the path value for pdmgrd on UNIX is as follows:path=/var/PolicyDirector/log/pdmgrd_remote.cache


The directory portion of this pathname must exist. The log file is created if it doesnot already exist. The size of this file is not bound and it does not have anyrollover capability. If a remote server is not accessible for sufficient time, you couldrun out of disk space.

Specifying the rebind retry timeoutIf the remote server is unavailable, the log agent attempts to rebind to the server atthis frequency in number of seconds (default 300).rebind_interval=60

Specifying the remote serverThe remote logging services are offered by the pdacld program. Remote loggingpiggy-backs on the certificates set up for the authorization service as initialized bya call to azn_initialize(). This option nominates which hosts pdacld process shallbe bound to for event recording.server=<hostname>

Specifying the remote server portUse the port option to specify the port that the remote pdacld listens on for remotelogging requests.port=<number>

The default value is 7136.

Specifying the remote server distinguished nameTo establish mutual authentication of the remote server, a distinguished name (DN)must be configured that can be checked against the name returned in the remoteservers certificate. The default value for the DN is a null string.

A DN must be specified as a string enclosed by double quotes. Using the defaultvalue or explicitly specifying an empty string enables the logging client topromiscuously establish a remote server connection. Specifying a value for the DNlimits successful connection to a specific server:dn="cn=ivacld/timelord.testnet.tivoli.com,o=policy director,c=us"

Legacy configuration support and other defaultsTivoli SecureWay Policy Director, Version 3.7, configuration entries are recognizedfor the configuration of audit trail recording.

An audit log file set up using the Version 3.7 logaudit and auditlog configurationentries can be logged to from a file configuration by using the shorthand filelogging syntax, specifying audit as the log ID name. For example:logaudit = yesauditlog = /var/PolicyDircetor/pdmgrd/log/audit.loglogcfg = audit.azn:file log_id=audit

The default location for recording events depends on the domain component of theevent category name. Events for the audit domain default to be recorded in theaudit trail. Thus the previous example also can be written as the following:logaudit = yesauditlog = /var/PolicyDircetor/pdmgrd/log/audit.loglogcfg = audit.azn


The default recording location for other components is stderr on the console.

Compatibility with Authorization API configurationTivoli SecureWay Policy Director, Version 3.7, allowed the capture-to-file of eventsauditing authorization activities by either adding entries to the[aznapi-configuration] stanza of the configuration file or by loading acorresponding azn initialize attribute list.

The following list summarizes the Authorization API configuration file entries andattributes and their corresponding support in this release of Access Manager:

Configuration File Entry Attribute List Entry V3.9 Support

logclientid azn_init_logging_client ignored

logaudit n/a recognized

auditlog azn_init_audit_file recognized

auditcfg azn_init_auditcfg recognized

logdebug n/a ignored

debuglog azn_init_debug_file ignored

debugcfg azn_init_debugcfg ignored

logsize azn_init_log_size recognized

logflush azn_init_log_flush_interval recognized

WebSEAL HTTP request logsThe logcfg configurations that correspond to the log agents enabled using thedefault WebSEAL logging configurations described in the webseald.confconfiguration file template are as follows:

Common Log Format request log:logcfg = http.clf:file path=requests_file,flush=flush_time, \rollover=max_size,log=clf,buffer_size=8192,queue_size=48

Referrer log:logcfg = http.ref:file path=referers_file,flush=flush_time, \rollover=max_size,log=ref,buffer_size=8192,queue_size=48

User agent log:logcfg = http.agent:file path=agents_file,flush=flush_time, \rollover=max_size,log=agent,buffer_size=8192,queue_size=48

Additionally, it is now possible to record the request log in NCSA Combinedformat by capturing events sent to the http.cof pool. The NCSA combined formatappends the quoted referer and agent strings to the standard common log formatrecord.

Finding out what event categories existThe name of each event category is written to a trace event as it is instantiated. Toview trace records, enable trace during start up by adding the following line to therouting file:*:*.9:TEXTFILE:/var/PolicyDirector/log/%ld.trace.log 3.9


Monitoring log queue performanceThe queuing profiles configured for the main propagation queue and each file,remote, and pipe log agent are all instrumented for monitoring using the statisticsinterface.

Each queue is implemented by instantiating an EventQueue object that registersitself with the statistics subsystem using a category name constructed from thelogging agent type and the string pd.log.

An event queues statistics can be interrogated by using pdadmin server taskcommands. To establish what queues are implemented on a server, issue the servertask server_name stats list command. A report similar to the following is returned:pdadmin> server task ivacld-barra.surf.ap.tivoli.com stats listpd.ras.stats.monitorpd.log.EventPool.queue // Main event propagation queuepd.log.file.audit // Audit log queuepdadmin

To examine the statistics for a queue enter the stats get command as follows:pdadmin> server task ivacld-barra.surf.ap.tivoli.com \

stats get pd.log.EventPool.queue

A report similar to the following is displayed:dispatcher wakes on timeout(20) : 3617dispatcher wakes by notify : 0

notifies above highwater (100) : 0notifies below highwater : 0spurious notifies : 0

total events processed : 24average number of events handled per activation : 1greatest number of events handled per activation : 7blocks in queue requests : 0pdadmin>

The queues flush frequency is listed in parentheses after the word timeout. Thequeue’s high water setting is listed in parentheses after the word highwater.

The settings chosen for the various queue configuration options should attempt tobalance the maximum amount of memory consumed between queue activationswith the rate a particular log agent can consume events.

Optimally you should set the queue high water mark such that the number ofevents processed during a queue activation fills a processing time slice. This avoidsunnecessary thread context switching. Note however, that simply setting theseoptions to high values is unlikely to be productive since event log processing mustbe done at some point and cannot be deferred indefinitely. Consuming largeamounts of memory also has its own drawbacks.


Appendix A. pdadmin commands

The pdadmin utility is a command line utility that you can use to perform mostAccess Manager user and group administration tasks. The Web portal managerprovides many of these same commands through its graphical user interface. Thisappendix lists, in alphabetical order, the commands available from the pdadmincommand prompt.

Introducing the pdadmin utilityThe pdadmin utility is a command line utility that you can use to perform mostAccess Manager user and group administration tasks. The Web portal managerduplicates many pdadmin commands. However, pdadmin provides severaladvanced management functions that are not available through the Web portalmanager.

You can automate certain management functions by writing scripts that usepdadmin. The communication between the pdadmin utility and the policy server(pdmgrd) is secured over SSL. The utility is installed as part of the AccessManager runtime package.

Starting the pdadmin utility (login command)v Interactive modev Single command line modev Multiple command execution

Interactive modeTo start pdadmin in interactive mode, you must enter the pdadmin commandfollowed by a login command with username (administrator) and passwordoptions and arguments. The admin-user must be a registered user in an LDAPregistry.

UNIX:# pdadmin# login –a admin-user –p <password>pdadmin>

Windows:MSDOS> pdadminMSDOS> login –a admin-user –p passwordpdadmin>

At the pdadmin prompt, enter appropriate commands, options, and arguments.Refer to the command reference tables in this appendix.

Single command line modeYou can execute a single pdadmin command from the operating system commandprompt:

UNIX:# pdadmin [–a admin-user] [–p password] [command]

143

Windows:MSDOS> pdadmin [–a admin-user] [–p password] [command]

v If you specify the admin-user (–a) and password (–p), you are logged in as thatuser.

v If you do not specify the admin-user (–a), you are logged in as anunauthenticated user.

v If you specify the admin-user (–a), but do not specify a password (–p), you areprompted for a password.

The optional command argument allows you to run one-time commands. Forexample, the user “test” is created if you type following command.pdadmin –a sec_master –p pwd user create testcn=test,ou=austin,o=ibm,c=us test test test1234

Multiple command executionYou can create a special file that contains multiple pdadmin commands thattogether perform a complete task or series of tasks. The pdadmin utility accepts afilename argument that identifies the location of such a file.

UNIX:# pdadmin [–a admin-user] [–p password] file-pathname

Windows:MSDOS> pdadmin [–a admin-user] [–p password] file-pathname

Help informationFor a list of available commands by category, enter:pdadmin> help category

Command categories include: acl, action, object, server, rsrc, rsrccred, rsrcgroup,admin, login, user, group, policy, pop, errtext.

For information on specific command syntax, enter:pdadmin> help command

Exiting the pdadmin utilityTo exit pdadmin and return to the command prompt, enter the exit or quitcommand. For example:pdadmin> exit

Special characters disallowed for GSO commandsYou cannot use the following characters to create a GSO user name, GSO resourcename, or GSO resource group name:!”#&()*+,;:<>=@\|

Although it is possible to use most of these characters for other LDAP-relatedAccess Manager data (such as the CN, DN, and SN of a user), these charactershave special meaning in LDAP DN syntax and filters. Before using any of thesecharacters in Access Manager user and group names, consult the documentationfor your LDAP server to determine the effect of special characters in LDAP.


Command syntaxThe commands in this appendix use the following special characters to definecommand syntax:

[ ] Identifies elements that are optional. Those not enclosed in brackets arerequired.

... Indicates that you can specify multiple values for the previous element.Separate multiple values by a space, unless otherwise directed by acommand’s information.

If the ellipsis for an element follows a closing bracket, use the syntaxwithin the brackets to specify multiple values. For example, to specify twoadministrators for the option [–a admin]..., use –a admin1 –a admin2.

If the ellipsis for an element is within the brackets, use the syntax of thelast element to specify multiple values. For example, to specify two hostsfor the option [–h host...], use –h host1 host2.

| Indicates mutually exclusive information. You can use the element oneither the left or right of the vertical bar.

{ } Delimits a set of mutually exclusive elements when one of them isrequired. If the elements are optional, they are enclosed in brackets ([ ]).

In addition to the special characters, the typeface conventions described in“Typeface conventions” on page xvii are used.

Appendix A. pdadmin commands 145

acl attach

PurposeAttaches the specified access control list (ACL) to the specified protected object.

Syntaxacl attach object_name acl_name

Optionsobject_name Specifies the object to which to apply the named ACL policy.

acl_name Specifies the ACL policy that will be applied to the named object.

DescriptionAttaches the specified access control list to the specified protected object. If thespecified protected object already has an ACL attached, this function replaces thatACL with the new one. At most one ACL can be attached to a given protectedobject. The same ACL can be attached to multiple protected objects. UnderstandACLs before using this function.


acl create

PurposeCreates a new access control list (ACL).

Syntaxacl create acl_name

Optionsacl_name Specifies the name of the ACL policy being created. Note that this

command does not create the specific ACL entries.

DescriptionCreates a new access control list. This function creates a new ACL policy in theACL database. It does not create the specific ACL entries.


acl delete

PurposeDeletes the specified access control list (ACL).

Syntaxacl delete acl_name

Optionsacl_name Specifies the name of the ACL policy being deleted from the ACL

database.

DescriptionDeletes the specified access control list.


acl detach

PurposeDetaches the access control list (ACL) from the specified protected object.

Syntaxacl detach object_name

Optionsobject_name Specifies the object from which the current ACL policy is being

removed. Note that this command does not delete the ACL policyfrom the ACL database.

DescriptionDetaches the access control list from the specified protected object. Because onlyone access control list at a time can be attached to an object, the currently attachedaccess control list is detached. Understand ACLs before using this function.


acl find

PurposeReturns a list of protected objects that have the specified access control list (ACL)attached.

Syntaxacl find acl_name

Optionsacl_name Specifies the ACL policy for which to search.

DescriptionReturns a list of protected objects which have the specified access control listattached.


acl list

PurposeReturns the names of all the defined access control lists.

Syntaxacl list

OptionsNone.

DescriptionReturns the names of all of the defined access control lists.


acl list attribute

PurposeLists the extended attribute keys associated with the specified access control list(ACL).

Syntaxacl list acl_name attribute

Optionsacl_name Specifies the ACL policy for which to list the attributes.

DescriptionLists the extended attribute keys associated with the specified access control list.


acl modify

PurposeModifies access control list (ACL) policies.

Syntaxacl modify acl_name delete attribute attribute_name

acl modify acl_name delete attribute attribute_name attribute_value

acl modify acl_name description description

acl modify acl_name remove any-other

acl modify acl_name remove group group_name

acl modify acl_name remove unauthenticated

acl modify acl_name remove user user_name

acl modify acl_name set any-other

acl modify acl_name set any-other permissions

acl modify acl_name set attribute attribute_name attribute_value

acl modify acl_name set description description

acl modify acl_name set group group_name

acl modify acl_name set group group_name permissions

acl modify acl_name set unauthenticated

acl modify acl_name set unauthenticated permissions

acl modify acl_name set user user_name

acl modify acl_name set user user_name permissions

Optionsacl_name Specifies the ACL policy which will be modified.

delete attribute attribute_nameDeletes the specified extended attribute key from the specifiedaccess control list.

delete attribute attribute_name attribute_valueDeletes the specified value from the specified extended attributekey in the specified access control list.

description descriptionSet or modify the description for the specified access control list.


remove any-otherRemoves the access control list entry for the user any-other fromthe specified access control list.

remove group group_nameRemoves the access control list entry for the specified group fromthe specified access control list.

remove unauthenticatedRemoves the access control list entry for the user unauthenticatedfrom the specified access control list.

remove user user_nameRemoves the access control list entry for the specified user fromthe specified access control list.

set any-other Sets or modifies the access control list entry for the user any-otherin the access control list.

set any-other permissionsSets or modifies the access control list entry for the user any-otherin the access control list.

set attribute attribute_name attribute_valueSets the extended attribute value for the specified extendedattribute key in the specified access control list. If the attributealready exists, the attribute value is added as an additional value ifthe same value does not exist for this attribute. If the same valueexists for this attribute, it does not get added again (duplicatevalues are not allowed), and no error is returned.

set description descriptionSets or modifies the description for the specified access control list.

set group group_nameSets or modifies the access control list (ACL) entry for the specifiedgroup in the specified access control list. The user registry mustcontain an entry for the specified group before you can call thisfunction to add an entry for the group to an ACL.

set group group_name permissionsSets or modifies the access control list (ACL) entry for the specifiedgroup in the specified access control list. The user registry mustcontain an entry for the specified group before you can call thisfunction to add an entry for the group to an ACL.

set unauthenticatedSets or modifies the access control list entry for the userunauthenticated in the specified access control list.

set unauthenticated permissionsSets or modifies the access control list entry for the userunauthenticated in the specified access control list.

set user user_nameCall this function to specify the permissions that the user ispermitted to perform. The user registry must contain an entry forthe specified user before you can use this function to add an entryfor the user to an access control list (ACL).

set user user_name permissionsCall this function to specify the permissions that the user is


permitted to perform. The user registry must contain an entry forthe specified user before you can use this function to add an entryfor the user to an access control list (ACL).

Examples1. The following example sets the any-other ACL entry in the indicated ACL

policy definition and sets permissions.pdadmin> acl modify pubs set any-other r

2. The following example sets a group ACL entry in the indicated ACL policydefinition and sets permissions.pdadmin> acl modify pubs set group sales Tr

3. The following example sets the unathenticated ACL entry in the indicated ACLpolicy definition and sets permissions.pdadmin> acl modify docs set unauthenticated r

4. The following example sets a user ACL entry in the indicated ACL policydefinition and sets permissions.pdadmin> acl modify pubs set user peter Tr


acl show

PurposeReturns the specified access control list (ACL).

Syntaxacl show acl_name

Optionsacl_name Specifies the ACL policy which needs to be displayed.

DescriptionReturns the specified access control list.


acl show attribute

PurposeGets the extended attribute values for the specified extended attribute key from thespecified access control list.

Syntaxacl show acl_name attribute attribute_name

Optionsacl_name Specifies the access control list for which the extended attribute

values will be displayed.

attribute_name Specifies the name of the extended attribute whose values need tobe displayed.

DescriptionGets the extended attribute values for the specified extended attribute key from thespecified access control list.


action create

PurposeDefines a new action (permission) code in an action group.

Syntaxaction create action_name action_label action_type

action create action_name action_label action_type action_group_name

Optionsaction_group_name

Defines a new action (permission) code in the specified actiongroup. Call this function to add an action code to a user-definedextended action group.

action_label Specifies the label or description for the action

action_name Specifies the new single-character permission being created.

action_type Specifies the organizational category for this action within a givenaction group

DescriptionDefines a new action (permission) code in an action group.

Actions codes consist of one alphabetic character (a–z or A–Z). Actions codes arecase-sensitive. Each action code only can be used once within an action group. Besure that you do not attempt to redefine the default action codes when adding newcodes to the primary group.

Examples1. The following example creates a new permission character for the specified

action_label and action_type.pdadmin> action create k time Ext-Authzn


action delete

PurposeDeletes an action (permission) code from an action group. A specific action groupfrom which to delete an action can be defined by using the action_group_nameoption.

Syntaxaction delete action_name

action delete action_name action_group_name

Optionsaction_name Specifies the name of the action to be deleted.

action_group_nameSpecifies the name of the action group from which the specifiedaction needs to be deleted

Examples1. The following command deletes action ″k″ from the primary action group.

pdadmin> action delete k

2. The following command deletes the action ″z″ from the action group ″agz″pdadmin> action delete z agz


action group

PurposeThe following commands are used to create, delete, or display action groups.

Syntaxaction group create action_group_name

action group delete action_group_name

action group list


Specifies the name of the action group that needs to be created ordeleted.

DescriptionFor the create command, creates a new action group with the specified name.Supports a maximum of 32 action groups.

For the delete command, deletes the specified action group and all of the actionsthat belong to the specified group.

For the list command, lists all the defined action group names.


action list

PurposeLists all the defined action (permission) codes from an action group. A specificaction group for which to list an action can be defined by using theaction_group_name option.

Syntaxaction list

action list action_group_name


Specifies the name of the action group for which all actions will bedisplayed. Omission of this parameter will display actions definedin the primary action group.

Examples1. The following example displays all existing actions in the primary action group:

pdadmin> action list

r read WebSEAL...

2. The following example displays the results of the action list action_group_namecommand after the creation of an action group:pdadmin> action group create agzpdadmin> action create z actionz type1 agzpdadmin> action list agz

z actionz type1


admin

PurposeDisplays the current server configuration information.

Syntaxadmin show configuration

OptionsNone.

DescriptionDisplays current server configuration information, such as:v The type of user registry (LDAP, Active Directory, Active Directory Multidomain

or Domino)v Whether Global Signon (GSO) capabilities are enabled or not

Examples1. The following example displays the current server configuration information:

pdadmin> admin show configuration

Output is similar to the following:LDAP: TRUESECAUTHORITY: DefaultGSO: TRUE


errtext

PurposeDisplays the error message of a given error number.

Syntaxerrtext error_number

Optionserror_number Specifies the number of the error for which to generate the error

text.

DescriptionDisplays the error message of a given error number. The error number may be ineither decimal or hexadecimal format.

Examples1. The following is an example of the errtext command:

pdadmin> errtext 0x132120c8

Login failed. You have used an invalid username, password or client certificate.


exit

PurposeExits from the pdadmin command line mode.

Syntaxexit

OptionsNone.


group create

PurposeCreates a group.

Syntaxgroup create groupname dn cn

group create groupname dn cn group_container

Optionsgroupname Specifies the name of the group being created. This name must be

unique.

dn Specifies the registry identifier assigned to the group being created.

cn Specifies the common name assigned to the group being created

group_containerSpecifies the group container object assigned to the group beingcreated. If you do not use this argument, the group by default isplaced in the object space under /Management/Groups.

DescriptionUsed without the group_container option, creates a new group by creating a newgroup in the user registry with the specified name, registry identifier, and commonname.

Examples1. The following example creates a group in the user registry.

pdadmin> group create credit “cn=credit,ou=Austin,o=Wesley Inc,c=US” Credit


group delete

PurposeDeletes the specified group.

Syntaxgroup delete [-registry] groupname

Options[-registry] Deletes the user registry contents.

groupname Specifies the name of the group to be deleted.

DescriptionDeletes the specified group. Deletes all information about the group and optionallydeletes the user registry contents.

Examples1. The following example deletes the existing specified group.

pdadmin> group delete engineering


group import

PurposeCreates an group by importing a group that already exists in the user registry.

Syntaxgroup import groupname dn

group import groupname dn group_container

Optionsgroupname The name of the group to create.

dn The registry identifier of the group to import.

group_containerSpecifies the group container object assigned to the group beingcreated. If you do not use this argument, the group by default isplaced in the object space under /Management/Groups.

Examples1. The following example creates an group by importing a group that already

exists in the user registry:pdadmin> group import engineering “cn=engineering,ou=Austin,o=Wesley Inc,c=US”


group list

PurposeLists the groups, listed by group names.

Syntaxgroup list pattern max_return

group list-dn pattern max_return

Optionspattern Specifies the pattern for the group name for which to be searched.

The pattern can include a mixture of wildcards and stringconstants, and is case insensitive (for example, *austin*).

max_return Specifies the limit of how many entries should be returned for asingle request (for example, 2). Note that the number returned isalso governed by the server configuration (which specifies themaximum number of results that can be returned as part of asearch operation). The actual maximum returned entries is theminimum of max_return and the configured value on the server.

list-dn pattern max_returnReturns the list of user registry identifiers whose user registrycommon name attribute matches the pattern specified. Thereturned list are groups which are defined in the user registry butare not necessarily Access Manager groups. Groups that are notAccess Manager groups may be imported into Access Manager byuse of the group import command.

DescriptionLists the groups, listed by group names.

The order returned is the order created.

Examples1. The following example lists groups matching the specified pattern:

pdadmin> group list *a* 3

Output would be similar to the following:salesmarketingAlex

2. The following example lists group information matching the specified commonname attribute pattern:pdadmin> group list-dn *t* 2

Output would be similar to the following:cn=credit,ou=Austin,o=Wesley Inc,c=US salescn=marketing,ou=Boston,o=Austin Sale,c=US marketing


group modify

PurposeModifies an existing group by adding a description, or adding or removing a listof users.

Syntaxgroup modify groupname add user_list

group modify groupname description description

group modify groupname remove user_list

Optionsgroupname Specifies the name of the group to be modified.

add user_list Adds the specified users to the specified group. The format of theuser list is a parenthesized list of user names, separated by spaces.

description descriptionChanges the description for the specified group.

remove user_listRemoves the specified users from the specified group. The formatof the user list is a parenthesized list of user names, separated byspaces.

Examples1. The following example adds a new user to the specified group.

pdadmin> group modify engineering add dlucas

2. The following example deletes existing users from the specified group.pdadmin> group modify engineering remove (user1 "john doe" user2 user3)

3. The following example changes the description of the specified group.pdadmin> group modify credit description "Credit, Dept HCUS"


group show

PurposeShows the properties of the specified group.

Syntaxgroup show groupname

group show-dn dn

group show-members groupname

Optionsgroupname Specifies the name of the group to show.

show-dn dn Show the group specified by the group’s identifier in the userregistry. The returned group is defined in the user registry but isnot necessarily an Access Manager group. Groups that are notAccess Manager groups may be imported into Access Manager byuse of the group import command.

show-members groupnameLists the user names of the members of the specified group.

Examples1. The following example displays properties of the specified group:

pdadmin> group show credit

Output would be similar to the following:Group ID: creditLDAP dn: cn=credit,ou=Austin,o=Wesley Inc,c=USDescription: Credit, Dept HCUSLDAP cn: creditIs SecGroup: true

2. The following example displays properties specified by the group’s identifier inthe user registry:pdadmin> group show-dn cn=credit,ou=Austin,o=Wesley Inc,c=US

Output would be similar to the following:Group ID: creditLDAP dn: cn=credit,ou=Austin,o=Wesley Inc,c=USDescription: Credit, Dept HCUSLDAP cn: creditIs SecGroup: true

3. The following example lists the user names of the members of the specifiedgroup:pdadmin> group show-members credit

Output would be similar to the following:dlucasmlucaser


help

PurposeObtain system help for the pdadmin commands and options.

Syntaxhelp topic

help command

Optionstopic Specifies the general command topic for which help is needed.

command Specifies the specific command for which help is needed.

Examples1. The following example lists commands specified by the topic:

help action

Output would be similar to the following:action createaction deleteaction group list...

2. The following example lists options available for the specified command:help action create

Output would be similar to the following:action create action_name action_label action_typeaction create action_name action_label action_type action_groupname...


login

PurposeEstablishes authentication credentials used when communicating with the policyserver.

Syntaxlogin [-a admin_id [-p password]]

Options[-a admin_id] Specifies the administrator’s ID. If this is the only the option is

specified, the user will be prompted for the password.

[-p password] Specifies the password.

DescriptionEstablishes authentication credentials used when communicating with the policyserver. These credentials are used to determine a user’s access privileges to policyserver data.

Credentials are not ″stacked″. That is, a login operation will completely replaceany existing credentials.


logout

PurposeDiscards any authentication credentials that are in effect.

Syntaxlogout

OptionsNone.

DescriptionDiscards any authentication credentials that are in effect.

Exiting the pdadmin command line utility will discard the credentials.


object create

PurposeCreates a new protected object.

Syntaxobject create object_name description type ispolicyattachable {yes|no}

Optionsobject_name Specifies the name for the object being created. This name must be

unique.

description Any text string describing the object being created.

type Specifies the graphical icon associated with this object anddisplayed by the Web portal manager. Types range from 0-13. Forexample, types 10 or 13 are appropriate for container objects.

ispolicyattachable {yes|no}Specifies whether an ACL or a protected object policy can beattached to this object.


object delete

PurposeDeletes the specified protected object.

Syntaxobject delete object_name

Optionsobject_name Specifies the protected object to be deleted.

DescriptionDeletes the specified protected object.


object list

PurposeLists any objects grouped under the specified protected object.

Syntaxobject list object_name

Optionsobject_name Specifies the protected object.

DescriptionLists any objects grouped under the specified protected object.


object list attribute

PurposeLists all the extended attributes associated with the specified protected object.

Syntaxobject list object_name attribute

Optionsobject_name Specifies the protected object.

DescriptionLists all the extended attributes associated with the specified protected object.


object listandshow

PurposeLists any child objects grouped under the specified protected object and displaysall values associated with each of those objects.

Syntaxobject listandshow object_name

Optionsobject_name Specifies the protected object for which the child objects and

associated values are to be displayed.


object modify

PurposeModifies an existing object.

Syntaxobject modify object_name delete attribute attribute_name

object modify object_name delete attribute attribute_name attribute_value

object modify object_name set attribute attribute_name attribute_value

object modify object_name set description description

object modify object_name set ispolicyattachable {yes|no}

object modify object_name set name new_object_name

object modify object_name set type type

Optionsobject_name Specifies the protected object to be modified.

delete attribute attribute_nameDeletes the specified extended attribute (name and value) from thespecified protected object.

delete attribute attribute_name attribute_valueDeletes the specified value from the specified extended attributekey in the specified protected object.

set attribute attribute_name attribute_valueCreates an extended attribute, with the specified name and value,and adds it to the specified protected object. If the attribute alreadyexists, the attribute value is added as an additional value if thesame value does not exist for this attribute. If the same value existsfor this attribute, it does not get added again (duplicate values arenot allowed), and no error is returned.

set description descriptionSets the description field of the specified protected object.

set ispolicyattachable {yes|no}Sets the isPolicyAttachable attribute of the specified protectedobject.

set name new_object_nameSets the name of the specified protected object.

set type type Sets the type field of the specified protected object.

Examples1. The following example, entered on one line, sets the ispolicyattachable option.

pdadmin> object create /Management/Groups/Travel "Travel Container Object" \14 ispolicyattachable yes


object show

PurposeReturns the specified protected object.

Syntaxobject show object_name

Optionsobject_name Returns the specified protected object.

DescriptionReturns the specified protected object.


object show attribute

PurposeReturns the value associated with the specified extended attribute for the specifiedprotected object.

Syntaxobject show object_name attribute attribute_name

Optionsobject_name Returns the specified protected object.

attribute_name Specifies the name of the extended attribute whose values are to bedisplayed.

DescriptionReturns the value associated with the specified extended attribute for the specifiedprotected object.


objectspace create

PurposeCreates an protected object space.

Syntaxobjectspace create objectspace_name description type

Optionsobjectspace_name

Specifies the name of the objectspace to be created.

description Specifies the description of the new objectspace.

type Specifies the type of the objectspace to be created.

DescriptionCreates an protected object space.

You must specify as the input parameter type, the object space type for each newobject space. The object space type is used by the Web portal manager to displayan appropriate icon with the object.

Note: The root of the new protected object space automatically has theispolicyattachable attribute set to true.


objectspace delete

PurposeDeletes the specified protected object space.

Syntaxobjectspace delete objectspace_name

Optionsobjectspace_name

Specifies the name of the objectspace to be deleted.

DescriptionDeletes the specified protected object space.


objectspace list

PurposeLists all the protected object spaces.

Syntaxobjectspace list

OptionsNone.

DescriptionLists all the protected object spaces.


policy get

PurposeThe policy get commands are a set of management commands that display specificuser password and account rules and conditions.

Syntaxpolicy get account-expiry-date [-user user_name]

policy get disable-time-interval [-user user_name]

policy get max-login-failures [-user user_name]

policy get max-password-age [-user user_name]

policy get max-password-repeated-chars [-user user_name]

policy get min-password-alphas [-user user_name]

policy get min-password-length [-user user_name]

policy get min-password-non-alphas [-user user_name]

policy get password-spaces [-user user_name]

policy get tod-access [-user user_name]

Options[-user user_name]

Specifies the user whose policy information is to be displayed. Ifthis option is not specified, the general policy is displayed. For anygiven policy, if a user has a specific policy applied, this specificpolicy takes precedence over any general policy that might also bedefined. The precedence applies regardless of whether the specificpolicy is more or less restrictive than the general policy.

account-expiry-dateDisplays the account expiration date for all user accounts.

disable-time-intervalDisplays the time to disable user accounts when the maximumnumber of login failures is exceeded. This setting applies to all useraccounts.

max-login-failuresDisplays the maximum number of login failures allowed for eachuser account.

max-password-ageDisplays the maximum time a password will be valid for useraccounts.

max-password-repeated-charsDisplays the maximum number of repeated characters allowed in apassword for each user account.


min-password-alphasDisplays the minimum number of alphabetic characters required ina password for each user account.

min-password-lengthDisplays the minimum password length for all user accounts.

min-password-non-alphasDisplays the minimum number of non-alphabetic charactersrequired in a password for each user account.

password-spacesDisplays whether spaces are allowed in passwords for all useraccounts.

tod-access Displays the global time of day access policy.

Examples1. The following example will return the account expiration date for the specified

user:pdadmin> policy get account-expiry-date –user dlucas

2. The following example will return the maximum time a password will be validfor the specified user:pdadmin> policy get max-password-age –user dlucas


policy set

PurposeThe policy set commands are a set of management commands that set specific userpassword and account rules and conditions.

Syntaxpolicy set account-expiry-date {unlimited|absolute_time|unset} [-user user_name]

policy set disable-time-interval {number|unset|disable} [-user user_name]

policy set max-login-failures number|unset [-user user_name]

policy set max-password-age {unset|relative_time} [-user user_name]

policy set max-password-repeated-chars number|unset [-user user_name]

policy set min-password-alphas {unset|number} [-user user_name]

policy set min-password-length {unset|number} [-user user_name]

policy set min-password-non-alphas {unset|number} [-user user_name]

policy set password-spaces {yes|no|unset} [-user user_name]

policy set tod-access {{anyday|weekday|day_list}:{time_spec-time_spec}[:{utc|local}]|unset} [-user user_name]

Options[-user user_name]

Specifies the user whose policy information is to be set. If thisoption is not specified, the general policy is set. For any givenpolicy, if a user has a specific policy applied, this specific policytakes precedence over any general policy that might also bedefined. The precedence applies regardless of whether the specificpolicy is more or less restrictive than the general policy.

account-expiry-date {unlimited|absolute_time|unset}Sets the account expiration date for all user accounts.

disable-time-interval {number|unset|disable}Sets the time to disable each user account when the maximumnumber of login failures is exceeded. The default setting is 180.

max-login-failures number|unsetSets the maximum number of login failures allowed for each useraccount. The default setting is 10.

max-password-age {unset|relative_time}Sets the maximum password age for all user accounts. Therelative_time option is relative to the last time the password waschanged.

max-password-repeated-chars number|unsetSets the maximum number of repeated characters allowed in apassword for each user account. The default setting is 2.


min-password-alphas {unset|number}Sets the minimum number of alphabetic characters required in apassword for each user account. The default setting is 4.

min-password-length {unset|number}Sets the minimum password length for each user account. Thedefault setting is 8.

min-password-non-alphas {unset|number}Sets the minimum number of non-alphabetic characters required ina password for each user account. The default setting is 1.

password-spaces {yes|no|unset}Sets whether spaces are allowed in passwords for all user accounts.The default setting is unset.

tod-access {{anyday|weekday|day_list}:{time_spec-time_spec}[:{utc|local}]|unset}Sets the global time of day access policy. The optional time zone islocal by default. (Note: utc=GMT)

Examples1. The following example sets the expiration date of the specified user:

pdadmin> policy set account-expiry-date 1999-12-30-23:30:00 –user dlucas

2. The following example sets the maximum password age for the specified user:pdadmin> policy set max-password-age 031-08:30:00 –user dlucas


pop attach

PurposeAttaches a protected object policy (POP) to the specified protected object.

Syntaxpop attach object_name pop_name

Optionsobject_name Specifies the name of the protected object for which the protected

object policy will be attached.

pop_name Specifies the name of the protected object policy to be attached.

DescriptionAttaches a protected object policy to the specified protected object. At most, onePOP can be attached to a given protected object. If the object already has a POPattached to it, the specified POP replaces the existing one. The same POP can beattached to multiple protected objects. Be sure that the protected object exists in theprotect object space before attempting to attach a POP.


pop create

PurposeCreates a protected object policy object.

Syntaxpop create pop_name

Optionspop_name Specifies the name of the protected object policy to be created.

DescriptionCreates a protected object policy object.


pop delete

PurposeDeletes the specified protected object policy.

Syntaxpop delete pop_name

Optionspop_name Specifies the name of the protected object policy to be deleted.

DescriptionDeletes the specified protected object policy.


pop detach

PurposeDetaches a protected object policy from the specified protected object.

Syntaxpop detach object_name

Optionsobject_name Specifies the protected object from which the protected object

policy is to be deleted.

DescriptionDetaches a protected object policy from the specified protected object.


pop find

PurposeFinds and lists all protected objects that have the specified protected object policyattached.

Syntaxpop find pop_name

Optionspop_name Specifies the name of the protected object policy for which to

search.

DescriptionFinds and lists all protected objects that have the specified protected object policyattached.


pop list

PurposeLists all protected object policy objects.

Syntaxpop list

OptionsNone.

DescriptionLists all protected object policy objects.


pop list attribute

PurposeLists all extended attributes associated with a protected object policy (POP).

Syntaxpop list pop_name attribute

Optionspop_name Specifies the POP for which to list the attributes.

DescriptionLists all extended attributes associated with a protected object policy.


pop modify

PurposeModifies protected object policies.

Syntaxpop modify pop_name delete attribute attribute_name

pop modify pop_name delete attribute attribute_name attribute_value

pop modify pop_name set attribute attribute_name attribute_value

pop modify pop_name set audit-level {all|none|permit|deny|audit_level_list}

pop modify pop_name set description description

pop modify pop_name set ipauth add network netmask authority_level

pop modify pop_name set ipauth anyothernw authority_level

pop modify pop_name set ipauth remove network netmask

pop modify pop_name set qop {none|integrity|privacy}

pop modify pop_name set tod-access{anyday|weekday|day_list}:{anytime|time_spec-time_spec}[:{utc|local}]

pop modify pop_name set warning {yes|no}

Optionspop_name Specifies the name of the protected object policy to be modified.

delete attribute attribute_nameDeletes the specified extended attribute from the specifiedprotected object policy.

delete attribute attribute_name attribute_valueDeletes the specified value from the specified extended attributekey in the specified protected object policy.

set attribute attribute_name attribute_valueSets or modifies the specified value from the specified extendedattribute key in the specified protected object policy. If the attributealready exists, the attribute value is added as an additional value ifthe same value does not exist for this attribute. If the same valueexists for this attribute, it does not get added again (duplicatevalues are not allowed), and no error is returned.

set audit-level {all|none|permit|deny|audit_level_list}Sets the Audit Level for the specified protected object policy.

set description descriptionSets the description of the specified protected object policy.


set ipauth add network netmask authority_levelSets the IP endpoint authentication settings in the specifiedprotected object policy.

set ipauth anyothernw authority_levelSets the anyothernw, or any other network, setting for the IPauthentication level from the specified protected object policy(POP). If controlling access by IP address is not important, use theanyothernw setting to set the authentication level for all IPaddresses and IP address ranges not listed explicitly in the POP.

set ipauth remove network netmaskRemoves the IP endpoint authentication settings from the specifiedprotected object policy.

set qop {none|integrity|privacy}

Sets the quality of protection level for the specified protected objectpolicy. The following string values are supported:v nonev integrityv privacy

set tod-access {anyday|weekday|day_list}:{anytime|time_spec-time_spec}[:{utc|local}]

Sets the time of day range for the specified protected object policy.The optional time zone is local by default.

set warning {yes|no}Sets the warning mode for the specified protected object policy.


pop show

PurposeShow details of the protected object policy (POP).

Syntaxpop show pop_name

Optionspop_name Specifies the POP which needs to be displayed.

DescriptionShow details of the protected object policy.


pop show attribute

PurposeDisplays the values for the specified extended attribute from the specifiedprotected object policy (POP).

Syntaxpop show pop_name attribute attribute_name

Optionspop_name Specifies the POP whose attribute needs to be displayed.

attribute_name Specifies the name of the extended attribute whose values need tobe displayed.

DescriptionDisplays the values for the specified extended attribute from the specifiedprotected object policy.


quit

PurposeExits from the pdadmin command line mode.

Syntaxquit

OptionsNone.


rsrc create

PurposeCreates a single signon Web resource

Syntaxrsrc create resource_name [–desc description]

Optionsresource_name Specifies the name of the resource to be created.

[–desc description]Specifies a description for the resource. Descriptions containing aspace must be enclosed in double quotes.

DescriptionCreates a single signon Web resource. A Web resource is a Web server that servesas the backend of an WebSEAL junction.

Examples1. The following example, entered as one line, creates and names a Web resource

with an associated description:pdadmin> rsrc create engwebs01 –desc \“Engineering Web server – Room 4807”


rsrc delete

PurposeDeletes the specified single signon Web resource.

Syntaxrsrc delete resource_name

Optionsresource_name Specifies the name of the resource to be deleted. The resource must

exist or an error is displayed.

DescriptionDeletes the specified single signon Web resource.

Examples1. The following example deletes the named resource with its associated

description:pdadmin> rsrc delete engwebs01


rsrc list

PurposeReturns a list of all the single signon Web resource names.

Syntaxrsrc list

OptionsNone.

DescriptionReturns a list of all the single signon Web resource names.

Examples1. The following example returns a list of all the single signon Web resource

names:pdadmin> rsrc list

Output is similar to the following:engwebs01engwebs02engwebs03


rsrc show

PurposeReturns information for the specified single signon Web resource.

Syntaxrsrc show resource_name

Optionsresource_name Specifies the name of the resource for which information will be

shown. The resource must exist or an error is displayed.

DescriptionReturns information for the specified single signon Web resource.

Examples1. The following example returns information for the specified resource:

pdadmin> rsrc show engwebs01

Output would be similar to:Web Resource Name: engwebs01Description: Engineering Web server - Room 4807


rsrccred create

PurposeCreates a single signon credential.

Syntaxrsrccred create resource_name rsrcuser resource_userid rsrcpwd resource_passwordrsrctype {web|group} user username

Optionsresource_name Specifies the name given to the resource when the resource was

created. The resource (or resource group) must already exist inorder to create the resource credential. If the resource (or resourcegroup) does not exist or is not specified, an error message isdisplayed.

rsrcuser resource_useridSpecifies the unique user identification (user ID) for the user at theWeb server.

rsrcpwd resource_passwordSpecifies the password for a user at the Web server.

rsrctype {web|group}Specifies whether the resource type is web or group.

user username Specifies the name of the user for whom the resource credentialinformation applies. If the user does not exist or is not specified,an error message is displayed.

DescriptionCreates a single signon credential.

Examples1. The following example, entered as one line, creates the resource credential for

the given user:pdadmin> rsrccred create engwebs01 rsrcuser \4807ws01 rsrcpwd resrcpwd rsrctype web user dlucas


rsrccred delete

PurposeDeletes a single signon credential.

Syntaxrsrccred delete resource_name rsrctype {web|group} user username


created.

rsrctype {web|group}Specifies the resource type. The type of resource must match theresource type assigned when the resource was first created.

user username Specifies the name of the user for whom the resource credentialinformation applies.

DescriptionDeletes a single signon credential.

Examples1. The following example deletes the resource credential information for the

given resource, resource type, and username:pdadmin> rsrccred delete engwebs01 rsrctype web user dlucas


rsrccred list user

PurposeReturns the list of single signon credentials for the specified user.

Syntaxrsrccred list user username

Optionsusername Specifies the name of the user for whom the resource credential

information applies.

DescriptionReturns the list of single signon credentials for the specified user.

Examples1. The following example returns the list of single signon credentials for the

specified user:pdadmin> rsrccred list user dlucas

Output would be similar to the following:Resource name: engwebs01Resource Type: groupResource name: engwebs02Resource Type: web


rsrccred modify

PurposeCreates or modifies a single signon credential.

Syntaxrsrccred modify resource_name rsrctype {web|group} set [–rsrcuser resource_userid][– rsrcpwd resource_password] user username


created.

rsrctype {web|group}Specifies the resource type. The type of resource must match theresource type assigned when the resource was first created.

[–rsrcuser resource_userid]Specifies the unique user identification (user ID) for the user at theWeb server. To change or reset the resource user ID of the user orpassword information, these optional commands must be precededby a dash ( – ).

[– rsrcpwd resource_password]Specifies the password for a user at the Web server. Specifying thisparameter without specifying the -rsrcuser parameter will clearboth the resource user ID and the resource password. To simply setthe resource password, you must specify both the resource user IDand the resource password.

user username Specifies the name of the user for whom the resource credentialinformation applies.

DescriptionCreates or modifies a single signon credential.

Examples1. The following example, entered as one line, modifies the specified resource:

pdadmin> rsrccred modify engwebs01 rsrctype web \set –rsrcuser 4807ws01 –rsrcpwd newrsrpw user dlucas


rsrccred show

PurposeReturns the specified single signon credential. The credential identifier is composedof a resource name, a resource type, and an user name.

Syntaxrsrccred show resource_name rsrctype {web|group} user username

Optionsresource_name Specifies the name of the single signon resource associated with the

credential.

rsrctype {web|group}Specifies the type of the single signon resource associated with thecredential.

user username Specifies the name of the user associated with this credential.

DescriptionReturns the single signon credential specified by the given resource, resource type,and user.

Examples1. The following example returns the specified single signon credential.:

pdadmin> rsrccred show webs4807 rsrctype group user dlucas

Output would be similar to the following:Resource Name: engwebs01Resource Type: groupResource User Id: dlucas


rsrcgroup create

PurposeCreates a single signon group resource.

Syntaxrsrcgroup create resource_group_name [–desc description]

Optionsresource_group_name

Specifies the name of the resource group.

[–desc description]The description argument is an optional description that can beadded to identify this resource group. The optional –descparameter must be preceded with a dash ( – ). Descriptions thathave spaces need to be enclosed in double quotes.

DescriptionCreates a single signon group resource.

Examples1. The following example creates and names a Web resource group and provides a

description for that resource:pdadmin> rsrcgroup create webs4807 –desc “Web servers, Room 4807”


rsrcgroup delete

PurposeDeletes a single signon group resource.

Syntaxrsrcgroup delete resource_group_name


Specifies the name of the resource group. The resource group mustexist.

DescriptionDeletes a single signon group resource, including any description information.

Examples1. The following example deletes the named resource group and its associated

description information:pdadmin> rsrcgroup delete webs4807


rsrcgroup list

PurposeReturns a list of all of the single signon group resource names.

Syntaxrsrcgroup list

OptionsNone.

DescriptionReturns a list of all of the single signon group resource names.

Examples1. The following example returns a list of all of the single signon group resource

names:pdadmin> rsrcgroup list

Output would be similar to the following:webs4807websbld3


rsrcgroup modify

PurposeAdds or removes a single signon resource to or from a single signon resourcegroup.

Syntaxrsrcgroup modify resource_group_name add rsrcname resource_name

rsrcgroup modify resource_group_name remove rsrcname resource_name


Specifies the name of the resource group to be modified.

add rsrcname resource_nameAdds a single signon resource to the specified single signonresource group.

remove rsrcname resource_nameRemoves a single signon resource from the specified single signonresource group.

DescriptionAdds or removes a single signon resource to or from a single signon resourcegroup.

Examples1. The following example adds the named resource to the existing Web resource

group:pdadmin> rsrcgroup modify webs4807 add rsrcname engwebs02

2. The following example deletes the named resource from the existing Webresource group:pdadmin> rsrcgroup modify webs4807 remove rsrcname engwebs02


rsrcgroup show

PurposeReturns the specified single signon group resource.

Syntaxrsrcgroup show resource_group_name


Specifies the name of the resource group. The resource group mustexist or an error message displays.

DescriptionReturns the specified single signon group resource. The resource group name, theresource group description, and a list of the names of the resource group membersare displayed. The resource group members are the individual Web resources(servers).

Examples1. The following example returns the specified single signon group resource:

pdadmin> rsrcgroup show webs4807

Output would be similar to the following:Resource Group Name: webs4807Description: Web servers, Room 4807Resource Members:engwebs01engwebs02engwebs03


server list

PurposeLists all registered servers.

Syntaxserver list

OptionsNone.

DescriptionLists all registered servers. Note that the server name format displayed by thiscommand should be used for the server_name argument in the other pdadminserver commands.

Examples1. The following example lists all registered servers:

pdadmin> server list

Output would be similar to the following:ivacld-topserverivacld-server2ivacld-server3ivacld-server4


server listtasks

PurposeDisplays the list of available tasks from the server.

Syntaxserver listtasks server_name

Optionsserver_name Specifies the name of the server for which available tasks

(commands) will be listed.

DescriptionDisplays the list of available tasks from the server.

Examples1. The following example displays the list of available tasks from the server:

pdadmin> server listtasks ivacld-mogman.admogman.com

Output would be similar to the following:trace set component level [file path=file|other-log-agent-config]trace show [component]trace list [component]stats show [component]stats liststats on [component] [interval] [count] [file path= file|other-log-agent-config]stats off [component]stats reset [component]stats get [component]


server replicate

PurposeNotify authorization servers to receive database updates.

Syntaxserver replicate [–server server_name]

Options[–server server_name]

Specifies the name of the server to receive database updates. If thisoption is not specified, all servers configured to receive updates arenotified.

DescriptionNotify authorization servers to receive database updates. If a server name isspecified, but is not configured to receive database updates, an error messagedisplays. If no server name is specified, the process of notifying all configuredservers is initiated, but error messages are not displayed for individual servers.

Examples1. The following is an example of this command when specifying the server_name:

pdadmin> server replicate -server ivacld-topserver


server show

PurposeDisplays the specified server’s properties.

Syntaxserver show server_name

Optionsserver_name Specifies the name of the server whose properties are to be

displayed.

DescriptionDisplays the specified server’s properties.

Examples1. The following example displays the specified server’s properties:

pdadmin> server show ivacld-topserver

Output would be similar to the following:ivacld-topserver

Description: ivacld/topserverHostname: topserverPrincipal: ivacld/topserverPort: 7137Listening for authorization database update notifications: yesAZN Administration Services:

AZN_ADMIN_SVC_TRACE


server task

PurposeSends a command to an authorization server.

Syntaxserver task server_name server_task

Optionsserver_name Specifies the name of the server to which the server_task will be

sent.

server_task Specifies the task (command) being sent.

DescriptionSends a command to an authorization server.

Examples1. The following is an example of the output after sending the stats list task to

the authorization server:pdadmin> server task ivacld-mogman.admogman.com stats list

pd.ras.stats.monitorpd.log.EventPool.queue


user create

PurposeCreates a user in the user registry used by the policy server and initially associatesthat user with one or more groups.

Syntaxuser create [–gsouser] [–no-password-policy] username dn cn sn password

user create [–gsouser] [–no-password-policy] username dn cn sn password [groups]

Options[–gsouser] When this optional argument is specified, the user’s global signon

(GSO) capabilities are enabled.

[–no-password-policy]applies the password policy in any case. As the exception to thisrule, the –no-password-policy option is provided only for creatinga user with an initial password. It is recommended that the initialpassword be changed.

username Specifies the name for the user being created. This name must beunique.

dn Specifies the registry identifier assigned to the user being created.The registry identifier must be known before a new user accountcan be created. The registry identifier must be unique within theuser registry.

cn Specifies the common name assigned to the user being created.

sn Specifies the surname of the user being created.

password Specifies the password set for the new user. Passwords mustadhere to the password policies set by the administrator.

[groups] This optional argument specifies a list of groups to which the newuser is assigned. The format of the group list is a parenthesized listof group names, separated by spaces.

DescriptionCreates a user in the user registry used by the policy server and initially associatesthat user with one or more groups. Accounts are created invalid by default.

Examples1. The following example, entered as one line, creates a new user:

pdadmin> user create –gsouser dlucas “cn=Diana \Lucas,ou=Austin,o=Wesley Inc,c=US” “Diana Lucas” Lucas mypasswd

To make the user account valid, you must use the user modify command to setthe account-valid flag to yes.


user delete

PurposeDeletes the user and optionally deletes the user from the user registry.

Syntaxuser delete [–registry] username

Options[–registry] Use of this option causes the entire user object to be deleted from

the user registry.

username Specifies the name of the account to be deleted. Any resourcecredentials associated with a user account are automaticallyremoved at the same time the user account is deleted.

DescriptionDeletes information about the user from the user registry. The optional -registryparameter causes the entire user object to be deleted from the user registry. If the-registry parameter is not used, the registry user information may be used to createan user with the user import command.

Examples1. The following example deletes the account of the specified user:

pdadmin> user delete dlucas


user import

PurposeCreates an user by importing an existing user from the user registry.

Syntaxuser import [–gsouser] username dn

user import [–gsouser] username dn [group_name]

Options[–gsouser] When this optional argument is specified, the user is also made a

GSO user (gsoUser).

username A unique user name. This user will be created from informationthat already exists in the user registry.

dn The registry identifier of the user being imported. This identifiermust exist in the user registry and must not be associated with anexisting user.

[group_name] Specifies the group to which the imported user is being assigned.

DescriptionCreates an user by importing an existing user in the user registry. Imported useraccounts are created invalid by default. To make the user account valid, you mustuse the user modify command to set the account-valid flag to yes.

Examples1. The following example, entered on one line, creates the user ″mlucas″ by

importing information from the registry user ″cn=MikeLucaser,ou=Austin,o=Wesley Inc, c=US″:pdadmin> user import –gsouser mlucaser “cn=Mike \Lucaser,ou=Austin,o=Wesley Inc,c=US”


user list

PurposeLists the users, listed by user names.

Syntaxuser list pattern max_return

user list-dn pattern max_return

Optionslist-dn Specifies the pattern for the principal name. The pattern can

include a mixture of wildcards and string constants, and is casesensitive (for example, *luca*). The returned list are users whichare defined in the user registry but are not necessarily AccessManager users. Users that are not Access Manager users may beimported into Access Manager by use of the user importcommand.

pattern Specifies the pattern for the principal name. The pattern caninclude a mixture of wildcards and string constants, and is casesensitive (for example, *luca*). When used with the list-dncommand, the argument specifies the pattern for the commonname (CN) portion of the user’s registry identifier (excluding the″cn=″ component).

max_return Specifies the maximum number of entries that are found andreturned for a single request. Note that the number returned is alsogoverned by the server configuration (which specifies themaximum number of results that can be returned as part of asearch operation). The actual maximum returned entries is theminimum of max_return and the configured value on the server.

DescriptionLists the users, listed by user names.

Examples1. The following example lists the users matching the specified pattern:

pdadmin> user list *luca* 2

Output would be similar to the following:dlucasmlucaser

2. The following example lists the users matching the specified registry identifier:pdadmin> user list-dn *luca* 2

Output would be similar to the following:cn=Diana Lucas,ou=Austin,o=Wesley, Inc,c=UScn=Mike Lucaser,ou=Austin,o=Wesley, Inc,c=US


user modify

PurposeModifies various user account parameters

Syntaxuser modify username account-valid {yes|no}

user modify username description description

user modify username gsouser {yes|no}

user modify username password password

user modify username password-valid {yes|no}

Optionsusername Specifies the name of the account to be modified.

account-valid {yes|no}Enables or disables the specified user account.

description descriptionModifies the user description.

gsouser {yes|no}Enables or disables the single signon capabilities of an user.

password passwordModifies the user password. The new password must comply withpassword policies in effect.

password-valid {yes|no}Validates or invalidates the user’s account password. Setting thepassword-valid flag to no forces the user to change the passwordat the next login attempt.

Examples1. The following example enables the specified user account:

pdadmin> user modify dlucas account-valid yes

2. The following example modifies the description of a user account:pdadmin> user modify dlucas description “Diana Lucas, Credit Dept HCUS”

3. The following example removes the user as a GSO user.pdadmin> user modify dlucas gsouser no

4. The following example changes the password for a user account:pdadmin> user modify dlucas password newpasswd

5. The following example inactivates the user password forcing the user to changethe password at the next login.pdadmin> user modify dlucas password-valid no


user show

PurposeDisplays the properties of the specified user.

Syntaxuser show username

user show-groups username

user show-dn dn

Optionsusername Specifies the name of the user to display.

show-groups usernameDisplays the groups in which the specified user is a member.

show-dn dn Display the user specified by the user’s identifier in the userregistry. The returned user is defined in the user registry but is notnecessarily an Access Manager user. Users that are not AccessManager users may be imported into Access Manager by use of theuser import command.

Examples1. The following example displays the user account information for the specified

user:pdadmin> user show dlucas

Output would be similar to the following:Login ID: dlucasLDAP dn: cn=Diana Lucas,ou=Austin,o=Wesley Inc,c=USLDAP cn: Diana LucasLDAP sn: LucasDescription: Diana Lucas, Credit Dept HCUSIS SecUser: trueIS GSO user: falseAccount valid: truePassword valid: trueAuthentication mechanism: Default:LDAP

2. The following example displays the groups of which the specified user is amember:pdadmin> user show-groups dlucas

Output would be similar to the following:salescreditengineering

3. The following example provides additional information about the user whenspecifying the registry identifier:pdadmin> user show-dn “cn=Diana Lucas,ou=Austin,o=Wesley Inc,c=US”

Output would be similar to the following:


Login ID: dlucasLDAP dn: cn=Diana Lucas,ou=Austin,o=WesleyInc,c=USLDAP cn: Diana LucasLDAP sn: LucasDescription: Diana Lucas, Credit Dept HCUSIS SecUser: trueIS GSO user: falseAccount valid: truePassword valid: trueAuthentication mechanism: Default:LDAP


Appendix B. ivmgrd.conf reference

ivmgrd.conf configuration file for the policy server (pdmgrd).

Stanzas:v [ivmgrd]

v [ldap]

v [ssl]

v [authentication-mechanisms]

v [object-spaces]

v [aznapi-configuration]

v [aznapi-entitlement-services]

v [aznapi-pac-services]

v [aznapi-cred-modification-services]

v [aznapi-external-authzn-services]

v [delegated-admin]


[ivmrgd] stanza

unix-user UNIX user account for this server.

unix-group UNIX group account for this server.

database-path Location of master authorization database.

tcp-req-port TCP listening port for incoming requests.

max-notifier-threads Maximum number of event notifier threads.

auto-database-update-notify Enable automatic or manual update notification forauthorization database replicas.

notifier-wait-time Time (in seconds) the authorization policy database isidle before notification is sent to replicas.

pid-file Location of PID file.

log-file Location of log file.

ca-cert-download-enabled Allow clients to download the root CA certificate.

[ldap] stanza

ldap-server-config Location of the ldap.conf configuration file.

prefer-readwrite-server Enable and disable the choice for the client to querythe read/write LDAP server before querying anyreplica read-only servers configured in the domain.

bind-dn The LDAP user DN used when binding to the LDAPserver.

bind-pwd The LDAP user password.

ssl-enabled Enable and disable SSL communication with the LDAPserver.

ssl-keyfile Location of SSL key file used to handle certificates usedin LDAP communication.

ssl-keyfile-dn Certificate label in the SSL key file.

227


ssl-keyfile-pwd SSL key file password.

auth-using-compare Choose whether ldap_compare() is used instead of theldap_bind() call to authenticate LDAP users.

[ssl] stanza

ssl-keyfile Location of the SSL key file.

ssl-keyfile-pwd Password used to protect private keys in the key file.

ssl-keyfile-stash Location of SSL password stashfile.

ssl-keyfile-label Label of key to use other than the default.

ssl-v3-timeout Session timeout for SSL v3 connections.

ssl-listening-port TCP port to listen on for incoming MTS requests.

ssl-io-inactivity-timeout The duration (in seconds) that an SSL connection waitsfor a response before timing out

ssl-maximum-worker-threads Maximum number of threads created by the server tohandle incoming requests.

ssl-pwd-life SSL password lifetime - in days.

ssl-cert-life SSL certificate lifetime - in days.

ssl-auto-refresh Enable and disable automatic refresh of the SSLcertificate and the key database file password. Ifenabled, the certificate and password are regeneratedwhen either is near expiration.

[authentication-mechanisms] stanza

passwd-uraf Library to use for authentication.

cert-uraf Library to use for authentication.

passwd-ldap Library to use for authentication.

cert-ldap Library to use for authentication.

[aznapi-configuration] stanza

logsize Log file rollover threshold for audit logs.

logflush Frequency for flushing log file buffers for audit logs.

logaudit Enable and disable auditing.

auditlog Location of audit trail file.

auditcfg = azn Capture authorization events.

auditcfg = authn Capture authentication events.

auditcfg = mgmt Capture authentication events.

[aznapi-entitlement-services] stanza

[aznapi-pac-services] stanza

[aznapi-cred-modification-services] stanza

[aznapi-external-authzn-services] stanza

[delegated-admin] stanza



authorize-group-list Enable and disable authorization checks on the grouplist and group list-dn commands.

Appendix B. ivmgrd.conf reference 229


Appendix C. ivacld.conf reference

ivacld.conf configuration file for the authorization server (pdacld).

Stanzas:v [ivacld]v [ldap]v [ssl]v [manager]v [authentication-mechanisms]v [aznapi-configuration]v [aznapi-entitlement-services]v [aznapi-pac-services]v [aznapi-cred-modification-services]v [aznapi-admin-services]


[ivacld] stanza

tcp-req-port TCP listening port for incoming requests.

pid-file Location of PID file.

log-file Location of log file.

unix-user UNIX user account for this server.

unix-group UNIX group account for this server.

permit-unauth-remote-caller Specifies whether authorization API clientsshould be authorized by the authorizationserver before their requests are processed.

[ldap] stanza

enabled Enable and disable LDAP user registrysupport.

host LDAP server host name.

port The IP port used when binding to the LDAPserver.

bind-dn The LDAP user DN used when binding to theLDAP server.

bind-pwd The LDAP user password.

cache-enabled Enable and disable LDAP client-side caching toimprove performance for similar LDAPqueries.

prefer-readwrite-server Enable and disable the choice for the client toquery the read/write LDAP server beforequerying any replica read-only serversconfigured in the domain.

ssl-enabled Enable and disable SSL communication withthe LDAP server.

231


ssl-keyfile Location of SSL key file used to handlecertificates used in LDAP communication.

ssl-keyfile-dn Certificate label in the SSL key file.

ssl-keyfile-pwd SSL key file password.

max-search-size Maximum search buffer size returned from theLDAP server in entries.

ssl-port SSL port to listen on for LDAP communication.

auth-using-compare Choose whether ldap_compare() is usedinstead of the ldap_bind() call to authenticateLDAP users.

ldap-replica Define the LDAP user registry replicas in thedomain.

[ssl] stanza

ssl-keyfile Location of the SSL keyfile.

ssl-keyfile-pwd Password used to protect private keys in thekey file.

ssl-keyfile-stash Location of SSL password stashfile.

ssl-keyfile-label Label of key to use other than the default.

ssl-v3-timeout Session timeout for SSL v3 connections.

ssl-listening-port TCP port to listen on for incoming MTSrequests.

ssl-io-inactivity-timeout The duration (in seconds) that an SSLconnection waits for a response before timingout

ssl-maximum-worker-threads Maximum number of threads created by theserver to handle incoming requests.


ssl-cert-life SSL certificate lifetime - in days.

ssl-auto-refresh Enable and disable automatic refresh of the SSLcertificate and the key database file password.If enabled, the certificate and password areregenerated when either is near expiration.

ssl-authn-type Authentication type.

[manager] stanza

manager-host Host name of the MTS server.

master-port TCP port on which the server is listening forrequests.

master-dn The expected Distinguished Name of thecertificate presented by the MTS server.

[authentication-mechanisms] stanza

passwd-uraf Library to use for authentication.

cert-uraf Library to use for authentication.

passwd-ldap Library to use for authentication.

cert-ldap Library to use for authentication.

[aznapi-configuration] stanza



logsize Log file rollover threshold for audit logs.

logflush Frequency for flushing log file buffers for auditlogs.

logaudit Enable and disable auditing.

auditlog Location of the local client’s audit trail file.

auditcfg = azn Capture authorization events.

auditcfg = authn Capture authentication events.

db-file The location of the pdacld database cache file.

cache-refresh-interval The interval between checks for updates to themaster authorization server.

permission-info-returned

max-handle-groups Maximum number of handle groups toallocate.

listen-flags Enable and disable the receiving of policycache update notifications.

[aznapi-entitlement-services] stanza

Defines authorization API services.

[aznapi-pac-services] stanza

AZN_V37CRED_SVC A service to convert between Tivoli SecureWayPolicy Director, Version 3.7 credentials andTivoli SecureWay Policy Director, Version 3.8credentials. Allows support of remoteauthorization requests from Tivoli SecureWayPolicy Director, Version 3.7 authorization APIapplications.

[aznapi-cred-modification-services] stanza

AZN_MOD_SVC_RAD_2AB A credential modification service that allowsgroups to be dynamically appended to anexisting credential. This action can give theowner of the credential additionalauthorization capability.

[aznapi-admin-services] stanza

AZN_ADMIN_SVC_TRACE Enable and disable (using pdadmin) traceadministration for an authorization APIapplication.

Appendix C. ivacld.conf reference 233


Appendix D. ldap.conf reference

Stanzas:v [ldap]


[ldap] stanza

enabled Access Manager uses an LDAP user registry. Values are yes and no.

host The network name of the machine where the LDAP master server islocated.

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 Access Manager limit for an LDAP client search of database items- such as a request for the Web portal manager to list users from theLDAP database.

replica Replica LDAP server entry.

235


Appendix E. pd.conf reference

pd.conf configuration file

Stanzas:v [pdrte]v [ssl]v [manager]v [ldap-ext-cred-tags]


[pdrte] stanza

configured Indicates whether the Access Manager runtimepackage has been configured.

user-reg-type User registry type. (Currently only LDAP issupported.)

user-reg-server User registry server name.

user-reg-host User registry host name.

user-reg-hostport User registry server port number.

boot-start-ivmgrd Start the policy server (pdmgrd) at systemboot.

boot-start-ivacld Start the authorization server (pdacld) atsystem boot.

[ssl] stanza

ssl-keyfile Location on the local system of the SSL keyfile.

ssl-keyfile-pwd Key file password.

ssl-keyfile-stash Location of the SSL password stashfile.

ssl-keyfile-label Name of certificate to use other than thedefault.

ssl-v3-timeout Session ID timeout for SSL v3 connections.


ssl-io-inactivity-timeout The duration (in seconds) that an SSLconnection waits for a response before timingout.

ssl-auto-refresh Enable or disable automatic refresh of the keydatabase certificates and passwords.

[manager] stanza

master-host Host name of the MTS server.

master-port TCP port number on which the server islistening for requests.

replica Authorization server replicas.

[ldap-ext-cred-tags] stanza

237


credential-field-name =ldap-inetOrgPerson-field

Mechanism to add extended attributes to theAccess Manager credential from existing fieldsin the inetOrgPerson LDAP object class.


Appendix F. SSL configuration commands

This appendix lists, in alphabetical order, the commands related to Secure SocketsLayer (SSL) configuration.

Command parameters are dependent upon the action being taken. Parameters maybe specified in any order.

Command syntaxThe commands in this appendix use the following special characters to definecommand syntax:

[ ] Identifies elements that are optional. Those not enclosed in brackets arerequired.

... Indicates that you can specify multiple values for the previous element.Separate multiple values by a space, unless otherwise directed by acommand’s information.

If the ellipsis for an element follows a closing bracket, use the syntaxwithin the brackets to specify multiple values. For example, to specify twoadministrators for the option [–a admin]..., use –a admin1 –a admin2.

If the ellipsis for an element is within the brackets, use the syntax of thelast element to specify multiple values. For example, to specify two hostsfor the option [–h host...], use –h host1 host2.

| Indicates mutually exclusive information. You can use the element oneither the left or right of the vertical bar.

{ } Delimits a set of mutually exclusive elements when one of them isrequired. If the elements are optional, they are enclosed in brackets ([ ]).

239

bassslcfg –chgpwd

PurposeChanges the key database password. A new random password is generated andsaved in the stash file.

Syntaxbassslcfg –chgpwd –e pwd_life

Options–e pwd_life Sets the keyring file password expiration time in days. You can

specify a pwd_life value from 1 to 7200 (days). To use the currentlyconfigured value, specify 0. If you cannot determine the currentlyconfigured value, specify 183.


bassslcfg –config

PurposeConfigures the Access Manager runtime so as to allow the pdadmin utility tocommunicate with the policy server. Also creates new key and stash files.

Syntaxbassslcfg –config –c cert_file –h host_name [–p server_port] [–e pwd_life] [–tssl_timeout]

Options–c cert_file Specifies the name of the policy server base64-encoded, self-signed

certificate.

–h host_name Specifies the TCP host name of the policy server.

[–p server_port]Specifies the listening port number of policy server. The defaultvalue is 7135.

[–e pwd_life] Sets the keyring file password expiration time in days. You canspecify a pwd_life value from 1 to 7200 (days). The default value is183. To use the currently configured value, specify 0.

[–t ssl_timeout] Specifies the SSL session timeout in seconds. You can specify anssl_timeout value from 1 to 86400 (seconds). The default value is7200.

Appendix F. SSL configuration commands 241

bassslcfg –getcacert

PurposeDownloads the root CA certificate to a file.

Syntaxbassslcfg –getcacert –c cert_file –h host_name [–p server_port]

Options–c cert_file Specifies the name of the policy server base-64 encoded, self-signed

certificate.

–h host_name Specifies the TCP host name of the policy server.

[–p server_port]Specifies the listening port number of the policy server. The defaultvalue is 7135.


bassslcfg –modify

PurposeModifies the Access Manager policy server configuration.

Syntaxbassslcfg –modify [–h host_name] [–e pwd_life] [–p server_port] [–t ssl_timeout]

Options[–h host_name] Specifies the TCP host name of the policy server.

[–e pwd_life] Sets the keyring file password expiration time in days. You canspecify a pwd_life value from 1 to 7200 (days). The default value is183. To use the currently configured value, specify 0.

[–p server_port]Specifies the listening port number of the policy server.



bassslcfg –ping

PurposePings an Access Manager server.

Syntaxbassslcfg –ping –h host_name [–p server_port]

Options–h host_name Specifies the TCP host name of the policy server.

[–p server_port]Specifies the listening port number of the Access Manager serverthat you want to ping. The default value is 7135.


mgrsslcfg –chgcert

PurposeRenews the manager’s SSL certificate. A new public-private key pair and certificateis created and stored in the key database.

Syntaxmgrsslcfg –chgcert –l cert_life

Options–l cert_life Sets the certificate expiration time in days. You can specify a

cert_life value from 1 to 7300 (days). The default value is 365. Touse the currently configured value, specify 0.


mgrsslcfg –chgpwd

PurposeChanges the key database password. A new random password is generated andsaved in the stash file.

Syntaxmgrsslcfg –chgpwd –e pwd_life

Options–e pwd_life Sets the keyring file password expiration time in days. You can

specify a pwd_life value from 1 to 7200 (days). To use the currentlyconfigured value, specify 0. If you cannot determine the currentlyconfigured value, specify 183.


mgrsslcfg –config

PurposePerforms full configuration, creating new key and stash files and generating newcertificates.

Syntaxmgrsslcfg –config [–e pwd_life] [–l cert_life] [–t ssl_timeout] [–D {yes|no}]

Options[–e pwd_life] Sets the keyring file password expiration time in days. The pwd_life

value is 1 to 7200 (days). To use the currently configured value,specify 0. If you cannot determine the currently configured value,specify 183.

[–l cert_life] Sets the certificate expiration time in days. You can specify acert_life value from 1 to 7300 (days). The default value is 365.


[–D {yes|no}] Specify yes to enable downloading of the secure domain’s CAcertificate. If you specify no, you must manually transfer thepdcacert.b64 file to subsequent hosts to configure an AccessManager runtime. The default value is no.


mgrsslcfg –modify

PurposeModifies the current configuration.

Syntaxmgrsslcfg –modify [–e pwd_life] [–l cert_life] [–t ssl_timeout] [–D {yes|no}]

Options–e pwd_life Sets the keyring file password expiration time in days. The pwd_life

value is 1 to 7200 (days). To use the currently configured value,specify 0. If you cannot determine the currently configured value,specify 183.

[–l cert_life] Sets the certificate expiration time in days. This option is notrequired with the –config action and defaults to 365 days if notspecified.

[–t ssl_timeout] Specifies the SSL session timeout in seconds. The ssl_timeout valuemust be in the range 1–86400. The default value is 7200.

[–D {yes|no}] Enables downloading of the secure domain’s CA certificate. Ifenable download is no, you must transfer the pdcacert.b64 file tosubsequent hosts in order to configure Access Manager runtime onthem. On initial configuration, the default value is no.


svrsslcfg –add_replica

PurposeAdds a database replica.

Syntaxsvrsslcfg –add_replica –f cfg_file –h host_name [–p server_port] [–k replica_rank]

Options–f cfg_file Specifies the configuration file path and name.

–h host_name Specifies the TCP host name of an ivacld replica server.

[–p server_port]Specifies the listening port number of the ivacld replica server.This is the port number on which ivacld listens for requests. Thedefault value is 7136.

[–k replica_rank]Specifies the replica order of preference among other replicas. Thedefault value is 10.


svrsslcfg –chg_replica

PurposeChanges replica options. The replica host name is used to identify the replica andcannot be changed by this action.

Syntaxsvrsslcfg –chg_replica –f cfg_file –h host_name [–p server_port] [–k replica_rank]



[–p server_port]Specifies the listening port number of the ivacld replica server.This is the port number on which ivacld listens for requests. If notspecified on an –add_replica action, a default of 7136 is used.

[–k replica_rank]Specifies the replica order of preference among other replicas. Thedefault value is 10.


svrsslcfg –chgcert

PurposeRenews the server’s SSL certificate.

Syntaxsvrsslcfg –chgcert –f cfg_file –n server_name [–P admin_pwd] [–A admin_id]


–n server_name Specifies the name of the server. The name may be specified aseither server_name/host name or server_name, in which case thelocal host name is appended to form name/host name. Note thatthe names ivacld, secmgrd, ivnet, and ivweb are reserved forAccess Manager servers.

[–P admin_pwd]Specifies the Access Manager administrator password. If thisoption is not specified, the password is read from standard input.

[–A admin_id] Specifies the Access Manager administrator name. The default issec_master.


svrsslcfg –chgport

PurposeChanges the listening port number.

Syntaxsvrsslcfg –chgport –f cfg_file –r port_number


–r port_number Sets the listening port number for the server. A value of 0 may bespecified only if the [aznapi-admin-services] stanza in theconfiguration file is empty.


svrsslcfg –chgpwd

PurposeChanges the keyring file password.

Syntaxsvrsslcfg –chgpwd –f cfg_file –e pwd_life


–e pwd_life Sets the keyring file password expiration time in days. The pwd_lifevalue is 1 to 7200 (days). The default value is 183. To use thecurrently configured value, specify 0.


svrsslcfg –config

PurposeChanges the keyring file password.

Syntaxsvrsslcfg –config –f cfg_file –d kdb_dir –n server_name –s server_type –r port_number–P admin_pwd [–S server_pwd] [–A admin_id] [–t ssl_timeout] [–e pwd_life] [–llistening_mode] [–a refresh_mode] [–C cert_file] [–h host_name]


–d kdb_dir Specifies the directory that is to contain the keyring database filesfor the server.

–n server_name Specifies the name of the server. The name may be specified aseither server_name/host name or server_name, in which case thelocal host name is appended to form name/host name. Note thatthe names ivacld, secmgrd, ivnet, and ivweb are reserved forAccess Manager servers.

–s server_type Specifies the type of server being configured. The value must beeither local or remote.

–r port_number Sets the listening port number for the server. This is a requiredoption. A value of 0 may be specified only if the[aznapi-admin-services] stanza in the configuration file is empty.

–P admin_pwd Specifies the Access Manager administrator password. This is arequired option. If this option is not specified, the password is readfrom standard input.

[–S server_pwd]Specifies the server’s password. This option is required. However,you can request that a password be created by the system byspecifying a dash (-) for the password. If this option is used, theconfiguration file is updated with the password created by thesystem. If the user registry type is LDAP and a password isspecified, it is saved in the configuration file. If this option isabsent, the server password is read from standard input.

[–A admin_id] Specifies the Access Manager administrator name. If this option isnot specified, sec_master is the default.


[–e pwd_life] Sets the keyring file password expiration time in days. The pwd_lifevalue is 1 to 7200 (days). To use the currently configured value,specify 0. If you cannot determine the currently configured value,specify 183.

[–l listening_mode]Sets the listening-enabled flag in the configuration file. The valueof this option must be yes or no. If not specified, the default is no.When used with the –config action, a value of yes requires that the–r option must have a non zero value. When used with the


–modify action, a value of yes requires that the listening portnumber in the configuration file be non zero.

[–a refresh_mode]Sets the certificate and keyring file password auto-refresh enabledflag in the configuration file. The value of this option must be yesor no. If not specified, the default is yes.

[–C cert_file] Specify the fully qualified name of the file containing the base-64encoded SSL certificate used when the server authenticates directlywith the user registry.

[–h host_name] Specifies the TCP host name of the policy server. When used withthe –config action, this name is saved in the configuration fileusing the azn-app-host key. It is not used to name server objects.


svrsslcfg –modify

PurposeModifies the current configuration.

Syntaxsvrsslcfg –config –f cfg_file [–t ssl_timeout] [–C cert_file] [–l listening_mode]



[–C cert_file] Specify the fully qualified name of the file containing the base-64encoded SSL certificate used when the server authenticates directlywith the user registry.

[–l listening_mode]Sets the listening-enabled flag in the configuration file. Values areyes and no. The default value is no. A value of yes requires thatthe listening port number in the configuration file be non zero.


svrsslcfg –rmv_replica

PurposeRemoves a replica configuration.

Syntaxsvrsslcfg –rmv_replica –f cfg_file –h host_name




svrsslcfg –unconfig

PurposeUnconfigures the server. The key ring files are deleted and the server is removedfrom the user registry and Access Manager database.

Syntaxsvrsslcfg –unconfig –f cfg_file –n server_name [–P admin_pwd] [–A admin_id]

Options–f cfg_file Specifies the configuration path and file name.

–n server_name Specifies the name of the server. You can specify the name as eitherserver_name/host name or server_name, in which case the localhost name is appended to form name/host name. Note that ivacld,secmgrd, ivnet, and ivweb server names are reserved for AccessManager servers.

[–P admin_pwd]Specifies the Access Manager administrator password. If thisoption is not specified, the password is read from standard in(stdin).

[–A admin_id] Specifies the Access Manager administrator name. The default issec_master.


Appendix G. User registry differences

The following user registry differences are known to exist in this version of IBMTivoli Access Manager (Access Manager.)1. Leading and trailing blanks in user names and group names are ignored when

using LDAP or Microsoft Active Directory as the user registry in an AccessManager for e-business secure domain. However, when using a Lotus Dominoserver as a user registry, leading and trailing blanks are significant. To ensurethat processing is consistent regardless of what user registry is being used,define users and groups in the user registry without leading or trailing blanksin their names.

2. The forward slash character (/) should be avoided in user and group namesdefined using distinguished name strings. The forward slash character istreated differently in different user registries:

Lotus Domino serverUsers and groups can not be created with names using a distinguishedname string containing a forward slash character. To avoid the problem,either do not use a forward slash character or define the user withoutusing the distinguished name designation:pdadmin user create myuser username/locinfo test test testpwd

instead of using this one:pdadmin user create myuser cn=username/o=locinfo test test testpwd

Microsoft Active DirectoryUsers and groups can be created with names using a distinguishedname string containing a forward slash character. However, subsequentoperations on the object might fail as some Active Directory functionsinterpret the forward slash character as a separator between the objectname and the host name. To avoid the problem, do not use a forwardslash character to define the user.

3. When using a multi-domain Microsoft Active Directory user registry, multipleusers and groups can be defined with the same short name as long as theyreside in different domains. To query information associated with a specificuser or group, use the full name, including the domain, of the user or group toensure that you are getting the correct information. If the domain informationis omitted, information about the user or group defined in the default domainis returned, which might not be the expected user or group. The sole use of ashort name to identify a user or group should be avoided for the same reason.

4. When using iPlanet Version 5.0 as the user registry, a user that is created,added to a group, and then deleted from the user registry retains its groupmembership. If a user with the same name is created at some later time, thenew user automatically inherits the old group membership and might be giveninappropriate permissions. It is strongly recommended that the user be removedfrom all groups before the user is deleted. This problem does not occur whenusing the other supported user registries.

5. Attempting to add a duplicate user to a group produces different results basedon the user registry being used. Table 1 on page 260 outlines the differences.

259

Table 1. User registry differences when adding a duplicate user to a group

Operation LDAP Lotus Domino server Microsoft ActiveDirectory

Add one user andthat user is duplicate

Error No error Error

Add multiple users,first user is duplicate

Error for all users No error Error for all users

Add multiple users, auser other than thefirst is a duplicate

Error for all users No error Partial completionmessage

6. Attempting to remove a user from a group who is not a member of the groupproduces different results based on the user registry being used. Table 2outlines the differences.

Table 2. User registry differences when removing a user from a group who is not a memberof the group

Operation LDAP Lotus Domino server Microsoft ActiveDirectory

Remove one user,user is not in thegroup

Error Error Error

Remove multipleusers, first user notin the group

Error for all users Error Error for all users

Remove multipleusers, a user otherthan the first is not inthe group

Error for all users Partial completionmessage

Partial completionmessage

7. The maximum lengths of various names associated with a user vary dependingon the user registry being used. See Table 3 for a comparison of the maximumlengths allowed and the recommended maximum length to use to ensurecompatibility with all the user registries supported by Access Manager fore-business.

Table 3. Maximum lengths for names based on user registry

Maximumlength of:

LDAP Microsoft ActiveDirectory

Lotus Dominoserver

Recommendedmaximum value

First name(LDAP CN)

256 64 960 64

Middle name 128 64 65535 64

Last name 128 64 960 64

Registry UID(LDAP DN)

1024 2048 255 This value isuser

registry-specificand must be

changed whenchanging user

registries.


Table 3. Maximum lengths for names based on user registry (continued)

Maximumlength of:

LDAP Microsoft ActiveDirectory

Lotus Dominoserver

Recommendedmaximum value

Access Managerfor e-businessuser identity

256 2048 - 1 -length_of_

domain_name

200 - 4 -length_of_

domain_name

This value isuser

registry-specificand must be

changed whenchanging user

registries.

8. Users created in a Lotus Domino server or Microsoft Active Directory userregistry are automatically given the capability to own single signon credentialsand this capability can not be removed. When using an LDAP user registry, thiscapability must be explicitly granted to a user and subsequently can beremoved.

9. When the Access Manager for e-business policy server is using either MicrosoftActive Directory or a Lotus Domino server as its user registry, existing TivoliSecureWay Policy Director, Version 3.8 clients are not able to connect to thepolicy server. Either use a different user registry or upgrade the clients toAccess Manager for e-business.

Appendix G. User registry differences 261


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.

263

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 has been 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.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrates programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.


If you are viewing this information softcopy, the photographs and colorillustrations may not appear.

TrademarksThe following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States, other countries, or both:

AIXDB2IBMIBM logoOS/390SecureWayTivoliTivoli logoUniversal DatabaseWebSpherezSeriesz/OS

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. Java and all Java-based trademarks and logos aretrademarks or registered trademarks of Sun Microsystems, Inc. in the United Statesand other countries.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, or service names may be trademarks or service marks ofothers.

Appendix H. Notices 265


Glossary

Aaccess control. In computer security, the process ofensuring that the resources of a computer system canbe accessed only by authorized users in authorizedways.

access control groups. Groups to be used for accesscontrol. Each group contains a multivalued attributeconsisting of member distinguished names. Accesscontrol groups have an object class of AccessGroup.

access control list. (1) In computer security, acollection of all access rights for one object. (2) Incomputer security, a list associated with an object thatidentifies all the subjects that can access the object andtheir access rights; for example, a list associated with afile that identifies users who can access the file andidentifies their access rights to that file.

access permissions. Permissions that apply to theentire object or permissions that apply to attributeaccess classes.

actions. ACL permission attributes.

ACL. See access control list.

authentication. (1) In computer security, verification ofthe identity of a user or the user’s eligibility to accessan object. (2) In computer security, verification that amessage has not been altered or corrupted. (3) Incomputer security, a process used to verify the user ofan information system or protected resources.

authorization. (1) In computer security, the rightgranted to a user to communicate with or make use ofa computer system. (2) An access right. (3) The processof granting a user either complete or restricted accessto an object, resource, or function.

Bbind. To relate an identifier to another object in aprogram; for example, to relate an identifier to a value,an address or another identifier, or to associate formalparameters and actual parameters.

Ccertificate. In e-commerce, a digital document thatbinds 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. In e-commerce, an organizationthat issues certificates. The certificate authorityauthenticates the certificate owner’s identity and theservices that the owner is authorized to use, issues newcertificates, renews existing certificates, and revokescertificates belonging to users who are no longerauthorized to use them.

cipher. Encrypted data that is unreadable until it hasbeen converted into plain data (decrypted) with a key.

configuration. (1) The manner in which the hardwareand software of an information processing system areorganized and interconnected. (2) The devices andprograms that make up a system, subsystem, ornetwork

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 systemcommunications, a line over which data can be passedbetween two systems or between a system and adevice.

credentials. Detailed information, acquired duringauthentication, that describes the user, any groupassociations, and other security-related identityattributes. Credentials can be used by any AccessManager service that requires information about theuser. Credentials allow Access Manager to securelyperform a multitude of services, such as authorization,auditing, and delegation. For example, the AccessManager authorization service uses the user credentialto determine whether the user is authorized to performspecific operations on a protected resource.

Ddaemon. A program that runs unattended to performa standard service. Some daemons are triggeredautomatically to perform their task; others operateperiodically.

DCE. See distributed computing environment.

directory schema. Entries in a directory are made upof a collection of attributes and their associated values.Attributes may have one or multiple values. In order toidentify a particular value in an entry, the attribute typename is specified along with the value, as in cn=JohnDoe. This is referred to as an attribute:value pair. Everyentry contains an objectClass attribute that identifies

267

what type of information the entry contains. In fact, theobject class dictates which other attributes may bepresent in an entry. The directory schema defines thevalid attribute types and object classes that may appearin the directory. Attribute type definitions define themaximum length and syntax of its values. Object classdefinitions specify which attributes must be present inan object of that class, as well as attributes that may bepresent.

distinguished name (DN). Every entry in a directoryhas a distinguished name. The distinguished name isthe name that uniquely identifies an entry in thedirectory. A distinguished name is made up ofattribute:value pairs, separated by commas.

distributed computing environment (DCE). The OpenSoftware Foundation specification (or a product derivedfrom this specification) that assists in networking. Thedistributed computing environment provides suchfunctions as authentication, directory service, andremote procedure call.

digital signature. Data that is appended to, or is acryptographic transformation of, a data unit and thatenables the recipient of the data unit to verify thesource and integrity of the unit and to recognizepotential forgery.

DN. See distinguished name.

domain. (1) That part of a computer network in whichthe data processing resources are under commoncontrol. (2) In a database, all the possible values of anattribute or a data element. (3) See domain name.

domain name. In the Internet suite of protocols, aname of a host system. A domain name consists of asequence of subnames separated by a delimitercharacter. For example, if the fully qualified domainname (FQDN) of a host system is ralvm7.vnet.ibm.com,each of the following is a domain name:

v ralvm7.vnet.ibm.com

v vnet.ibm.com

v ibm.com

Eencryption. The process of transforming data into anunintelligible form in such a way that the original dataeither cannot be obtained or can be obtained only byusing a decryption process.

FFile Transfer Protocol (FTP). In the Internet suite ofprotocols, an application layer protocol that uses TCPand Telnet services to transfer bulk-data files betweenmachines or hosts.

Hhost. A computer that is connected to a network (suchas the Internet or an SNA network) and provides anaccess point to that network. Also, depending on theenvironment, the host may provide centralized controlof the network. The host can be a client, a server, orboth a client and a server simultaneously.

Hypertext Transfer Protocol (HTTP). In the Internetsuite of protocols, the protocol that is used to transferand display hypertext documents.

IInternet Protocol (IP). In the Internet suite ofprotocols, a connectionless protocol that routes datathrough a network or interconnected networks and 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 published asRequests for Comments (RFCs) through the InternetEngineering Task Force (IETF).

IP. See Internet Protocol.

Kkey. A sequence of symbols that is used with acryptographic algorithm for encrypting or decryptingdata. See private key and public key.

key database file. See key ring.

key file. See key ring.

key pairs. A public key and a private key. When thekey pair is used for encryption, the sender uses thepublic key to encrypt the message, and the recipientuses the private key to decrypt the message. When thekey pair is used for signing, the signer uses the privatekey to encrypt a representation of the message, and therecipient uses the public key to decrypt therepresentation of the message for signature verification.

key ring. A file that contains public keys, private keys,trusted roots, and certificates.

LLDAP. See Lightweight Directory Access Protocol.

ldif2db. This program is used to load entries specifiedin text LDAP Directory Interchange Format (LDIF) intoa directory stored in a relational database. The databasemust already exist. ldif2db may be used to add entriesto an empty directory database or to a database thatalready contains entries.


Lightweight Directory Access Protocol (LDAP). Anopen protocol that (a) uses TCP/IP to provide access todirectories that support an X.500 model and (b) doesnot incur the resource requirements of the morecomplex X.500 Directory Access Protocol (DAP).Applications that use LDAP (known asdirectory-enabled applications) can use the directory asa common data store and for retrieving informationabout people or services, such as e-mail addresses,public keys, or service-specific configurationparameters. LDAP was originally specified in RFC1777. LDAP version 3 is specified in RFC 2251, and theIETF continues work on additional standard functions.Some of the IETF-defined standard schemas for LDAPare found in RFC 2256.

Mmanagement server. See policy server.

metadata. Data that describes the characteristics ofstored data; descriptive data.

migration. The installation of a new version or releaseof a program to replace an earlier version or release.

Oobject class definitions. Every entry contains anobjectClass attribute that identifies what type ofinformation the entry contains. In fact, the object classdictates which other attributes may be present in anentry. The directory schema defines the valid attributetypes and object classes that may appear in thedirectory. Attribute type definitions define themaximum length and syntax of its values. Object classdefinitions specify which attributes must be present inan object of that class, as well as attributes that may bepresent.

Ppolicy. A set of rules that are applied to managedresources.

policy data. Includes both password strength policydata and login data.

policy server. Maintains location information aboutother Access Manager servers in the secure domain.When policy changes affect the master authorizationpolicy database, the policy server is responsible forupdating all authorization database replicas in thedomain.

POP. See protected object policy.

protected object policy (POP). A type of AccessManager security policy that dictates additionalconditions for accessing a protected resource after a

successful ACL policy check. Examples of POPs includetime-of-day access and quality of protection level.

protected object space. The virtual objectrepresentation of actual system resources that is usedfor applying ACLs and POPs and used by theauthorization service.

private key. A key that is known only to its owner.Contrast with public key.

public key. A key that is made available to everyone.Contrast with private key.

Qquality of protection. The level of data security,determined by a combination of authentication,integrity, and privacy conditions.

Rregistry. (1) The datastore that maintains the accountinformation for users and groups that are allowed toparticipate in the secure domain. (2) A database thatcontains system configuration information regardingthe user, the hardware, and the programs andapplications that are installed.

replica. A replica is a server that runs a copy of thedirectory. This replicated server can keep a copy of theentire directory or just one tree of that directory. Anyupdate to a replica server is referred to the masterserver. If the master server fails, you always have acopy of the directory trees on the replica server. Usingthe replica server also improves the response time.

response file. A file that contains a set of predefinedanswers to questions asked by a program and that isused in place of user dialog.

RSA. A system for public-key cryptography used forencryption and authentication. It was invented in 1977by Ron Rivest, Adi Shamir, and Leonard Adleman. Thesystem’s security depends on the difficulty of factoringthe product of two large prime numbers.

run time. The time period during which a computerprogram is executing. A runtime environment is anexecution environment.

Sscalability. The ability of a network system to respondto increasing numbers of users who access resources.

schema. The set of statements, expressed in a datadefinition language, that completely describe thestructure of a database.

Glossary 269

secure domain. The group of users, systems, andresources that share common services and usuallyfunction with a common purpose.

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. SSL was developed by NetscapeCommunications Corp. and RSA Data Security, Inc.

security management. The management disciplinethat addresses an organization’s ability to control accessto applications and data that are critical to its success.

service. Work performed by a server. This may meanserving simple requests for data to be sent or stored (aswith file servers, HTTP servers, e-mail servers, andfinger servers), or it may be more complex work suchas that of print servers or process servers.

silent installation. An installation that does not sendmessages to the console but instead stores messagesand errors in log files. Also, can indicate that theinstallation uses response files instead of user dialogs.

SSL. See Secure Sockets Layer.

suffixes. A suffix is a distinguished name thatidentifies the top entry in a locally held directoryhierarchy. Because of the relative naming scheme usedin Lightweight Directory Access Protocol (LDAP), thisdistinguished name is also the suffix of every otherentry within that directory hierarchy. A directory servermay have multiple suffixes, each identifying a locallyheld directory hierarchy.

Ttoken. (1) In a local area network, the symbol ofauthority passed successively from one data station toanother to indicate the station temporarily in control ofthe transmission medium. Each data station has anopportunity to acquire and use the token to control themedium. A token is a particular message or bit patternthat signifies permission to transmit. (2) In local areanetworks (LANs), a sequence of bits passed from onedevice to another along the transmission medium.When the token has data appended to it, it becomes aframe.

transport selector. The Open Systems Interconnection(OSI) equivalent of port numbers in TCP/IP. Alsocalled a TSEL number.

trusted root. In the Secure Sockets Layer (SSL), thepublic key and associated distinguished name of acertificate authority (CA).

TSEL. See transport selector.

Uuser. Any person, organization, process, device,program, protocol, or system that uses a serviceprovided by others.


Index

Aaccess control list (ACL) 13accountability 5ACL 13

apply to new LDAP suffixes 109control permission 52create 36custom permissions 40custom permissions example 40default administration policies 57default root 57entries 35entry syntax 37evaluation 41extended action groups 46extended actions 46ID attribute 38inheritance 42management permissions 51operations on an object 39permissions attribute 38resolving request 44traverse 43, 50type attribute 37WebSEAL permissions 50

ACL permissions 39ACL policies, defining 12action

enter into ACL entries 48action group, create new 47action, create new 48actions 39activating

roles 74administration

delegate role 73enterprise domain 71multiple domains 72roles 73superdomain 71

administration policies (default) 57administrator

multiple domains 72superdomain 71tasks 74

administratorsadministrator 73domain 72enterprise domain 71Policy Director 72predefined 72sec_master 71senior 73support 73types 72

any-other 37, 41audit event 117audit trail 117audit trail files 115, 117auditcfg 119

auditingoverview 115

auditlog 118authentication 3authorization 3, 5authorization API 16authorization API standard 3authorization database, replicate 100authorization evaluator 8authorization model 5authorization policy database 8authorization process 15authorization server 89authorization service 6, 7, 8

authorization API 9benefits 7management interface 9

auto-database-update-notify 100

Bbooks

feedback xiionline xiiordering xii

boot-start-ivacld 99boot-start-ivmgrd 99

Ccentralized management 5configuration files 96container object 29

management 30user-defined 30WebSEAL 30

control permission 52creating

roles 74Customer Support xvii

Ddefault administration policies 57default config ACL 58default GSO ACL 59default management ACL 58default Policy ACL 59default replica ACL 58default root ACL 43, 57default WebSEAL ACL 58delegate administrator, illustrated 72delegate role

administration 73delegated administration

administration users and groups 78group ACL permissions 84group and user management 81group container objects 82managing policy 86

271

delegated administration (continued)object space management 78user ACL permissions 85

domainadministrators 72enterprise 71multiple 72subdomain, described 71superdomain 71

Ee-mail contact xviiencryption

supported standards 4enterprise domain 71error.log 116evaluating an ACL 41event field ID codes 123explicit ACL 42explicit ACL policy 13extended action groups 46extended actions 46external authorization service 20

Ffail-over configuration 106fatal.log 116feedback about publications xviifield ID codes 123

Ggroup 36group container objects 82

IIBM SecureWay Directory 106iKeyman key management utility

description xvinheritance 42inherited ACL 42inherited ACL policy 13iPlanet 106iv-admin group 79ivmgrd-servers group 79

LLDAP

fail-over configuration 106overview 103suffixes, new 109

LDAP fail-overpreference values 108

ldap.conf 107local cache mode 16, 19logaudit 118logflush 119logging

overview 115logsize 118

Mmanagement objects 12management server 8, 89management/ACL permissions 51management/Action permissions 52management/Config permissions 54management/Groups permissions 56management/GSO permissions 56management/Policy permissions 54management/POP permissions 53management/Replica permissions 54management/Server permissions 53management/Users permissions 55manuals

feedback xiionline xiiordering xii

master authorization policy database 8max-notifier-threads 100, 101messages

error.log 116fatal.log 116notice.log 116warning.log 116

multiple domain 72illustrated 72

multiple domanexample 72

Nnotice.log 116notification delay time 101notifier-wait-time 100, 102

Oobject permissions 57object space permissions 57object space, user-defined 31

creating new 32object types 32, 82objects, create and delete 33online publications xviordering publications xvii

Ppassword

troubleshooting 73pd_start 90pdacld 89pdadmin 90pdadmin server replicate 101pdmgrd 8, 89permissions 39

custom 40custom, example 40roles 73

Policy Directoradministrators 72authorization service 7, 8core technologies 3introducing 2securing enterprise networks 1


policy enforcer 6POP 14, 61

apply to objects 63configure attributes 63create 62

POP attributeaudit level 64time of day 64warning mode 64

POP policies, defining 12preference values (LDAP fail-over) 108protected object 12, 29protected object policies 14protected object policy (POP) 61

apply to objects 63configure attributes 63create 62

protected object space 12, 29guidelines 46management objects 12protected object 12system resource 12user-defined objects 12web objects 12

publicationsfeedback xiionline xiiordering xii

Qquality of protection 4

Rremote cache mode 16, 18replica 108replicate authorization database 100replication 10resolving ACL request 44resource manager 6resource object 29roles

defined 73delegate 73permissions 73role activation 74role assignment 74

assigning 74role creation 74

rollover threshold 118root ACL (default) 43, 57

Sscalability 4, 10sec_master 71sec_master user 78securing enterprise networks 1security

common concerns 2implementing policy 11policy 73

serverautomating startup 99

server replicate 101

server status 98serviceability messages

error.log 116fatal.log 116notice.log 116warning.log 116

sparce ACL model 42status, server 98subdomain 71superdomain 71system resource 12, 29

Ttasks

role activation 74role adminstration 74role assignment 74role creation 74roles 73types 74

Tivoli Customer Support xviitraverse 50traverse permission 43, 50

Uunauthenticated 41update notifier threads 101user 36user registry

differences 259user-defined object space 31

creating new 32user-defined objects 12users

administrator, administrator 73administrator, domain 72administrator, Policy Director 72administrator, sec_master 71administrator, senior 73administrator, support 73delegate 73

Wwarning.log 116web objects 12Web Portal Manager 14, 90

security policy 73WebSEAL 89webseal-servers group 79webseald 89

Index 273


Printed in U.S.A.

GC23-4684-00

Documents

Base Administrator’s Guide - IBMpublib.boulder.ibm.com/tividd/td/ITAME/GC23-4684-00/en... · 2005-04-12 · The IBM Tivoli Access Manager Base Administrator’s Guide provides a