IBM Tivoli Access Manager: Base Administrator™s Guide

IBM Tivoli Access Manager
Base Administrator’s Guide
Version 3.9
GC23-4684-00
IBM Tivoli Access Manager
Base Administrator’s Guide
Version 3.9
GC23-4684-00
Note
Before 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 Users
Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Who should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
What this book contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Accessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Ordering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Providing feedback about publications . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Contacting customer support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Conventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Chapter 1. Access Manager overview . . . . . . . . . . . . . . . . . . . . . . . 1
Securing the enterprise network . . . . . . . . . .
Network security — common concerns . . . . . .
Introducing Access Manager . . . . . . . . . .
Access Manager — core technologies . . . . . . . .
Authentication. . . . . . . . . . . . . . .
Authorization . . . . . . . . . . . . . . .
Quality of (data) protection . . . . . . . . . .
Scalability . . . . . . . . . . . . . . . .
Accountability . . . . . . . . . . . . . . .
Centralized management . . . . . . . . . . .
Understanding authorization: conceptual model . . . .
The benefits of a standard authorization service . . .
Introducing the Access Manager authorization service .
The Access Manager authorization service . . . . . .
Components . . . . . . . . . . . . . . .
Authorization service interfaces . . . . . . . . .
Replication for scalability and performance . . . . .
Implementing a network security policy . . . . . . .
Defining the network security policy . . . . . . .
The protected object space . . . . . . . . . .
Defining and applying ACL and POP policies . . . .
Policy administration: The Web portal manager . . .
The authorization process: step-by-step . . . . . .
The Access Manager authorization API . . . . . . .
Using the authorization API: two examples . . . . .
Authorization API: remote cache mode . . . . . .
Authorization API: local cache mode . . . . . . .
External authorization capability . . . . . . . . .
Extending the authorization service . . . . . . .
Imposing conditions on resource requests . . . . .
The authorization evaluation process . . . . . . .
Implementing an external authorization service . . .
Deployment strategies . . . . . . . . . . . .
Access Manager Base certificate and password management
Initial configuration . . . . . . . . . . . .
Keyring database file and stash file renewal information
Determining trust . . . . . . . . . . . . .
Certificate Revocation . . . . . . . . . . . .
Additional considerations . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 1
. 2
. 2
. 3
. 3
. 3
. 4
. 4
. 5
. 5
. 5
. 6
. 7
. 8
. 8
. 9
. 10
. 11
. 11
. 12
. 12
. 14
. 15
. 16
. 17
. 18
. 19
. 20
. 20
. 21
. 21
. 23
. 23
. 24
. 25
. 25
. 26
. 27
. 27
iii
Chapter 2. Managing the protected object space. . . . . . . . . . . . . . . . . . 29
Understanding the protected object space . . . . .
Elements of the protected object space . . . . .
Protected object space hierarchy . . . . . . .
User-defined object space for third-party applications
Defining a database object space . . . . . . . .
Creating a new user-defined container object . . .
Creating and deleting objects . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
29
29
30
31
31
32
33
Chapter 3. Using access control policies . . . . . . . . . . . . . . . . . . . . . 35
Introducing the ACL policy . . . . . . . .
ACL policy entries . . . . . . . . . .
Creating and naming ACL policies . . . .
ACL entry syntax . . . . . . . . . . .
Type attribute . . . . . . . . . . .
ID attribute . . . . . . . . . . . .
Permissions (actions) attribute . . . . . .
Default Access Manager permissions (actions) .
How the authorizations service uses ACL policies
Performing operations on an object . . . .
Requirements for custom permissions . . .
Custom action example . . . . . . . .
Evaluating an ACL . . . . . . . . . . .
Evaluating authenticated requests . . . . .
Evaluating unauthenticated requests . . . .
Example ACL entries . . . . . . . . .
Sparse ACL model: ACL inheritance . . . . .
Understanding the sparse ACL model . . .
The default root ACL policy . . . . . . .
Traverse permission . . . . . . . . .
Resolving an access request . . . . . . .
Applying ACL policies to different object types
ACL policy inheritance example . . . . .
Guidelines for a secure object space . . . .
Creating extended ACL actions and action groups
Creating a new action group. . . . . . .
Creating new actions in an action group . . .
Entering custom actions into ACL entries . .
ACL policies and the protected object space . .
Root ( / ) container object . . . . . . .
The traverse permission . . . . . . . .
WebSEAL permissions . . . . . . . . . .
/WebSEAL/host. . . . . . . . . . .
/WebSEAL/host/file . . . . . . . . .
WebSEAL permissions . . . . . . . . .
Management permissions. . . . . . . . .
/Management/ACL permissions . . . . .
/Management/Action permissions . . . .
/Management/POP permissions . . . . .
/Management/Server permissions. . . . .
/Management/Config permissions . . . .
/Management/Policy permissions . . . . .
/Management/Replica permissions . . . .
/Management/Users permissions . . . . .
/Management/Groups permissions . . . .
/Management/GSO permissions . . . . .
Object and object space permissions . . . . .
Default administration ACL policies . . . . .
Default root ACL policy . . . . . . . .
Default /WebSEAL ACL policy . . . . . .
Default /Management ACL policy. . . . .
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
IBM Tivoli Access Manager: Base Administrator’s Guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
35
35
36
37
37
38
38
39
39
39
40
40
41
41
41
42
42
42
43
43
44
45
45
46
46
47
48
48
49
49
50
50
50
50
50
51
51
52
53
53
54
54
54
55
56
56
57
57
57
58
58
Default
Default
Default
Default
/Replica ACL policy
/Config ACL policy .
/GSO ACL policy .
/Policy ACL policy .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
58
58
59
59
Chapter 4. Using protected object policies . . . . . . . . . . . . . . . . . . . . 61
Introducing protected object policies (POP) . . . . . .
POP notes:. . . . . . . . . . . . . . . .
Creating and deleting protected object policies . . .
Applying POP attributes to protected objects . . . .
Configuring the POP attributes . . . . . . . . . .
Warning mode attribute . . . . . . . . . . .
Audit level attribute . . . . . . . . . . . .
Time-of-day attribute . . . . . . . . . . . .
Authentication strength POP policy (step-up) . . . . .
Configuring levels for step-up authentication . . . .
Applying step-up authentication policy . . . . . .
Step-up authentication algorithm . . . . . . . .
Distinguishing step-up from multi-factor authentication
Network-based authentication POP policy . . . . . .
Specifying IP addresses and ranges . . . . . . .
Disabling step-up authentication by IP address . . .
Network-based authentication algorithm . . . . .
Network-based authentication notes and limitations . .
Quality of protection POP policy . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
62
62
62
63
63
64
64
64
65
65
66
67
67
68
68
69
69
69
70
Chapter 5. Using Web portal manager . . . . . . . . . . . . . . . . . . . . . . 71
Delegating administration using Web portal manager .
Delegating role administration . . . . . . . .
Self-registration sample . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 71
. 73
. 74
Chapter 6. Delegating administration tasks . . . . . . . . . . . . . . . . . . . . 77
Delegating object space management . . . .
Structuring the object space for management
Default administration users and groups .
Creating administration users . . . . .
Example administration ACL templates . .
Example: Management delegation . . . .
Delegating group management . . . . . .
Creating group container objects . . . .
Creating groups . . . . . . . . . .
ACL policies affecting group management .
ACL policies affecting user management .
Managing delegated administration policy . .
. . . .
delegation
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
78
78
78
79
80
80
81
82
83
84
85
86
Chapter 7. Managing Access Manager servers. . . . . . . . . . . . . . . . . . . 89
Introducing the Access Manager servers . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Server dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Introducing server administration tools . . . . . . . . . . . . . . . . . . . . . . . . . 90
Server configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Starting and stopping Access Manager servers. . . . . . . . . . . . . . . . . . . . . . . . 97
Starting and stopping servers on UNIX systems . . . . . . . . . . . . . . . . . . . . . . 97
Starting and stopping servers on Windows systems . . . . . . . . . . . . . . . . . . . . . 98
Automating server startup at boot time . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Policy server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Authorization server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Policy server administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Replicating the authorization database . . . . . . . . . . . . . . . . . . . . . . . . . 100
Setting the number of update notifier threads . . . . . . . . . . . . . . . . . . . . . . 101
Setting the notification delay time . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Contents
v
Chapter 8. Using the LDAP registry . . . . . . . . . . . . . . . . . . . . . . . 103
LDAP overview . . . . . . . . . . . . . .
LDAP: A protocol for directory services . . . . .
LDAP directories . . . . . . . . . . . . .
The LDAP information model . . . . . . . . .
LDAP features . . . . . . . . . . . . . .
LDAP fail-over configuration . . . . . . . . . .
The master-slave replication model . . . . . . .
Access Manager fail-over capability for LDAP servers .
Master server configuration . . . . . . . . .
Replica server configuration . . . . . . . . .
Setting preference values for replica LDAP servers . .
Server polling . . . . . . . . . . . . . .
Applying Access Manager ACLs to new LDAP suffixes .
Procedures for the IBM SecureWay Directory server .
Procedures for iPlanet Directory Server . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
103
103
104
105
105
106
106
107
107
108
109
109
109
111
112
Chapter 9. Logging and auditing server activity. . . . . . . . . . . . . . . . . . 115
Introduction to logging and auditing . . . . . . .
Audit trail files . . . . . . . . . . . . . .
Documentation convention: install_path . . . . .
Logging Base serviceability messages . . . . . . .
Access Manager audit trail files . . . . . . . . .
Enabling and disabling auditing . . . . . . . .
Specifying the log file location . . . . . . . . .
Specifying audit file rollover thresholds . . . . .
Specifying the frequency for flushing audit file buffers
Specifying audit events . . . . . . . . . . .
Audit trail file format . . . . . . . . . . . .
Status attribute of the outcome field . . . . . . .
Resource attribute of the target field . . . . . . .
Audit trail file contents . . . . . . . . . . . .
Authorization audit records . . . . . . . . .
Authentication audit records . . . . . . . . .
WebSEAL audit records . . . . . . . . . . .
Management Audit Records . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
115
115
115
116
118
118
118
118
119
119
120
121
121
121
121
122
122
123
Chapter 10. Using event logging . . . . . . . . . . . . . . . . . . . . . . . . 129
Understanding Access Manager events . . . . . . . . . .
Configuring event logging . . . . . . . . . . . . . .
Configuring the central event propagation queue . . . . .
Specifying the maximum number of events to queue in memory
Specifying the event queue high water mark . . . . . . .
Specifying the frequency for flushing log file buffers . . . .
Console logging . . . . . . . . . . . . . . . . .
File logging . . . . . . . . . . . . . . . . . . .
Specifying the log file location. . . . . . . . . . . .
Specifying the log file ID . . . . . . . . . . . . .
Specifying the maximum log file size . . . . . . . . .
Specifying the maximum buffer size . . . . . . . . . .
Specifying the maximum number of events to queue in memory
Specifying the event queue high water mark . . . . . . .
Specifying the frequency for flushing log file buffers . . . .
Specifying the file mode . . . . . . . . . . . . . .
Pipe logging. . . . . . . . . . . . . . . . . . .
Specifying the program to run. . . . . . . . . . . .
Specifying the event queuing profile. . . . . . . . . .
Remote logging . . . . . . . . . . . . . . . . .
Specifying the maximum buffer size . . . . . . . . . .
Specifying the frequency for flushing the consolidation buffer .
vi
IBM Tivoli Access Manager: Base Administrator’s Guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
129
130
132
132
133
133
133
134
134
134
135
135
136
136
136
137
137
137
138
138
138
139
Specifying the queue sizes . . . . . . . . .
Specifying compression of messages . . . . . .
Specifying the error retry timeout . . . . . .
Specifying the cache file location . . . . . . .
Specifying the rebind retry timeout . . . . . .
Specifying the remote server . . . . . . . .
Specifying the remote server port. . . . . . .
Specifying the remote server distinguished name .
Legacy configuration support and other defaults . .
Compatibility with Authorization API configuration
WebSEAL HTTP request logs . . . . . . . .
Finding out what event categories exist . . . . .
Monitoring log queue performance . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
139
139
139
139
140
140
140
140
140
141
141
141
142
Appendix A. pdadmin commands . . . . . . . . . . . . . . . . . . . . . . . . 143
Introducing the pdadmin utility . . . . . . .
Starting the pdadmin utility (login command) .
Help information . . . . . . . . . . .
Exiting the pdadmin utility. . . . . . . .
Special characters disallowed for GSO commands
Command syntax . . . . . . . . . . . .
acl attach . . . . . . . . . . . . . . .
acl create . . . . . . . . . . . . . . .
acl delete . . . . . . . . . . . . . . .
acl detach . . . . . . . . . . . . . .
acl find . . . . . . . . . . . . . . .
acl list . . . . . . . . . . . . . . . .
acl list attribute. . . . . . . . . . . . .
acl modify . . . . . . . . . . . . . .
acl show . . . . . . . . . . . . . . .
acl show attribute . . . . . . . . . . . .
action create . . . . . . . . . . . . . .
action delete. . . . . . . . . . . . . .
action group. . . . . . . . . . . . . .
action list. . . . . . . . . . . . . . .
admin . . . . . . . . . . . . . . . .
errtext . . . . . . . . . . . . . . . .
exit . . . . . . . . . . . . . . . . .
group create . . . . . . . . . . . . . .
group delete. . . . . . . . . . . . . .
group import . . . . . . . . . . . . .
group list. . . . . . . . . . . . . . .
group modify . . . . . . . . . . . . .
group show . . . . . . . . . . . . . .
help . . . . . . . . . . . . . . . .
login . . . . . . . . . . . . . . . .
logout . . . . . . . . . . . . . . . .
object create . . . . . . . . . . . . . .
object delete . . . . . . . . . . . . . .
object list . . . . . . . . . . . . . . .
object list attribute. . . . . . . . . . . .
object listandshow. . . . . . . . . . . .
object modify . . . . . . . . . . . . .
object show . . . . . . . . . . . . . .
object show attribute . . . . . . . . . . .
objectspace create . . . . . . . . . . . .
objectspace delete . . . . . . . . . . . .
objectspace list . . . . . . . . . . . . .
policy get . . . . . . . . . . . . . .
policy set . . . . . . . . . . . . . . .
pop attach . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
143
143
144
144
144
145
146
147
148
149
150
151
152
153
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
187
189
vii
pop create . . .
pop delete . . .
pop detach . . .
pop find . . . .
pop list . . . .
pop list attribute .
pop modify . . .
pop show . . .
pop show attribute
quit . . . . .
rsrc create . . .
rsrc delete . . .
rsrc list . . . .
rsrc show. . . .
rsrccred create . .
rsrccred delete . .
rsrccred list user .
rsrccred modify .
rsrccred show . .
rsrcgroup create .
rsrcgroup delete .
rsrcgroup list . .
rsrcgroup modify .
rsrcgroup show. .
server list. . . .
server listtasks . .
server replicate . .
server show . . .
server task . . .
user create . . .
user delete . . .
user import . . .
user list . . . .
user modify . . .
user show . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
190
191
192
193
194
195
196
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
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 . . . . . . . . . . . . . . . . . . . . 239
Command syntax . .
bassslcfg –chgpwd. .
bassslcfg –config . .
bassslcfg –getcacert .
bassslcfg –modify . .
bassslcfg –ping . . .
mgrsslcfg –chgcert. .
mgrsslcfg –chgpwd .
mgrsslcfg –config . .
mgrsslcfg –modify. .
svrsslcfg –add_replica
svrsslcfg –chg_replica
svrsslcfg –chgcert . .
svrsslcfg –chgport . .
svrsslcfg –chgpwd . .
viii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
IBM Tivoli Access Manager: Base Administrator’s Guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
svrsslcfg
svrsslcfg
svrsslcfg
svrsslcfg
–config . .
–modify . .
–rmv_replica
–unconfig .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
254
256
257
258
Appendix G. User registry differences . . . . . . . . . . . . . . . . . . . . . . 259
Appendix H. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Trademarks .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 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 is
required to run applications in the product suite. It enables the integration of
Access Manager applications that provide a wide range of authorization and
management solutions. Sold as an integrated solution, these products provide an
access control management solution that centralizes network and application
security policy for e-business applications.
Note: IBM Tivoli Access Manager is the new name of the previously released
software entitled Tivoli SecureWay® Policy Director. Also, for users familiar
with the Tivoli SecureWay Policy Director software and documentation, the
term management server is now referred to as policy server.
The IBM Tivoli Access Manager Base Administrator’s Guide provides a comprehensive
set of procedures and reference information for managing Access Manager servers
and resources. This guide also provides you with valuable background and
concept information for the wide range of Access Manager functionality.
Who should read this book
This guide is for system administrators responsible for the deployment and
administration of base Access Manager software.
Readers should be familiar with the following:
v PC and UNIX® operating systems
v Database architecture and concepts
v Security management
v Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and
Telnet
v Lightweight Directory Access Protocol (LDAP) and directory services
v Authentication and authorization
What this book contains
This 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 service
model, and implementing a security policy.
v Chapter 2, “Managing the protected object space” on page 29
Discusses how Access Manager uses a virtual representation of resources in a
protected object space. Two types of object spaces are supported: flat file and
database.
v Chapter 3, “Using access control policies” on page 35
Provides a complete reference to access control list (ACL) policies.
v Chapter 4, “Using protected object policies” on page 61
Provides a complete reference to protected object policies (POP).
v Chapter 5, “Using Web portal manager” on page 71
xi
v
v
v
v
v
v
v
Provides supplemental information to tasks provided in the online help system,
including delegating administration and self-registration. This Web-based user
interface is shipped separately on the IBM Tivoli Access Manager Web Portal
Manager CD for AIX, Solaris, and Windows platforms.
Chapter 6, “Delegating administration tasks” on page 77
Explains how Access Manager supports delegated management of the object
space and group management.
Chapter 7, “Managing Access Manager servers” on page 89
Provides a technical reference to managing and customizing the operation of the
Access Manager servers.
Chapter 8, “Using the LDAP registry” on page 103
Introduces the LDAP protocol / directory and provides detailed information on
LDAP fail-over configuration.
Chapter 9, “Logging and auditing server activity” on page 115
Provides a complete reference to the Access Manager logging and auditing
capabilities.
Appendix A, “pdadmin commands” on page 143
Appendix B, “ivmgrd.conf reference” on page 227
Appendix C, “ivacld.conf reference” on page 231
v Appendix D, “ldap.conf reference” on page 235
v Appendix E, “pd.conf reference” on page 237
Publications
This section lists publications in the Access Manager library and any other related
documents. It also describes how to access Tivoli publications online, how to order
Tivoli publications, and how to make comments on Tivoli publications.
IBM Tivoli Access Manager
The Access Manager library is organized into the following categories:
v Release information
v Base information
v WebSEAL information
v Web security information
v Developer reference information
v 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, open
the 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, see
the following Web sites:
http://www.ibm.com/redbooks
https://www.tivoli.com/secure/support/documents/fieldguides
Release information
v 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 information
v IBM Tivoli Access Manager Base Installation Guide
GC32-0844 (am39_install.pdf)
Provides installation, configuration, and upgrade instructions for Access
Manager 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 manager
interface 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 the
zSeries platform.
WebSEAL information
v IBM Tivoli Access Manager WebSEAL Installation Guide
GC32-0848 (amweb39_install.pdf)
Provides installation, configuration, and upgrade instructions for the WebSEAL
server 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 technical
reference information for using WebSEAL to manage the resources of your
secure Web domain.
v IBM Tivoli Access Manager WebSEAL Developer’s Reference
GC23-4683 (amweb39_devref.pdf)
Provides administration and programming information for the Cross-domain
Authentication 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 WebSEAL
server and the WebSEAL application development kit for Linux on the zSeries
platform.
Web security information
v IBM Tivoli Access Manager for WebSphere Application Server User’s Guide
GC32-0850 (amwas39_user.pdf)
Provides installation, configuration, and administration instructions for Access
Manager 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 Access
Manager 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 the
plug-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 securing
your Web domain using the plug-in for Web servers application.
Developer references
v 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 Manager
authorization C API and the Access Manager service plug-in interface to add
Access 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 of
the 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 an
application to perform Access Manager administration tasks. This document
describes 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 of
the administration API to enable an application to perform Access Manager
administration tasks.
v IBM Tivoli Access Manager WebSEAL Developer’s Reference
GC23-4683 (amweb39_devref.pdf)
Provides administration and programming information for the Cross-domain
Authentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),
and the Password Strength Module.
Technical supplements
v IBM Tivoli Access Manager Performance Tuning Guide
GC43-0846 (am39_perftune.pdf)
Provides performance tuning information for an environment consisting of
Access 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 backend
Web 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 by
Access Manager.
The Tivoli Glossary includes definitions for many of the technical terms related to
Tivoli software. The Tivoli Glossary is available, in English only, at the following
Web site:
http://www.tivoli.com/support/documents/glossary/termsm03.htm
Related publications
This 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 at
the following Web site:
http://www.ibm.com/software/data/db2/
IBM Global Security Toolkit
Access Manager provides data encryption through the use of IBM Global Security
Toolkit (GSKit). GSKit is shipped on the IBM Tivoli Access Manager Base CD for
your particular platform.
The GSKit package installs the iKeyman key management utility (gsk5ikm), which
enables you to create key databases, public-private key pairs, and certificate
requests. 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 to
enable SSL communication in their Access Manager secure domain.
IBM SecureWay Directory
IBM SecureWay Directory, Version 3.2.2, is shipped on the IBM Tivoli Access
Manager Base CD for your particular platform. If you plan to install the IBM
SecureWay Directory server as your user registry, the following documents are
available in the /doc/Directory path on the IBM Tivoli Access Manager Base CD
for 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 IBM
SecureWay 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 documentation
and 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 IBM
SecureWay Directory documentation had been translated. This file is in English
only.
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, Version
3.2.2. This software development kit (SDK) provides LDAP application
development support.
v IBM SecureWay Directory Configuration Schema
(scparent.pdf)
Describes the directory information tree (DIT) and the attributes that are used to
configure the slapd32.conf file. In IBM SecureWay Directory Version 3.2, the
directory 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. Tuning
considerations for directory sizes ranging from a few thousand entries to
millions 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 Server
IBM WebSphere Application Server, Advanced Single Server Edition 4.0.2, is
installed with the Web portal manager interface. For information about IBM
WebSphere Application Server, see the following Web site:
http://www.ibm.com/software/webservers/appserv/infocenter.html
Accessing publications online
Publications in the product library are included in Portable Document Format
(PDF) on the product CD. To access these publications using a Web browser, open
the 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 hardcopy
publications, they are posted to the Tivoli Information Center. The Tivoli
Information Center contains the most recent version of the publications in the
product library in PDF or HTML format, or both. Translated documents are also
available for some products.
You can access the Tivoli Information Center and other sources of technical
information 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 to
page check box in the Adobe Acrobat Print dialog (which is available when
you click File → Print) to ensure that the full dimensions of a letter-sized
page are printed on the paper that you are using.
xvi
IBM Tivoli Access Manager: Base Administrator’s Guide
Ordering publications
You 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-2755
v In Canada: 800-426-4968
v 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 publications
We are very interested in hearing about your experience with Tivoli products and
documentation, and we welcome your suggestions for improvements. If you have
comments or suggestions about our products and documentation, contact us in one
of the following ways:
v Send an e-mail to pubs@tivoli.com.
v Complete our customer feedback survey at the following Web site:
http://www.tivoli.com/support/survey/
Accessibility
Accessibility features help a user who has a physical disability, such as restricted
mobility or limited vision, to use software products successfully. With this product,
you can use assistive technologies to hear and navigate the interface. You can also
use the keyboard instead of the mouse to operate all features of the graphical user
interface.
Contacting customer support
If you have a problem with any Tivoli product, you can contact Tivoli Customer
Support. 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 Customer
Support, depending on the severity of your problem, and the following
information:
v Registration and eligibility
v Telephone numbers and e-mail addresses, depending on the country in which
you are located
v What information you should gather before contacting support
Conventions used in this book
This guide uses several conventions for special terms and actions, operating
system-dependent commands and paths, and margin graphics.
Typeface conventions
The following typeface conventions are used in this book:
Preface
xvii
xviii
Bold
Command names and options, keywords, and other information
that you must use literally appear in bold.
Italic
Variables, command options, and values you must provide appear
in italics. Titles of publications and special words or phrases that
are emphasized also appear in italics.
Monospace
Code examples, command lines, screen output, file and directory
names, and system messages appear in monospace font.
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 to
securely control user access to protected information and resources. By providing a
centralized, flexible, and scalable access control solution, Access Manager allows
you to build highly secure and well-managed network-based applications and
e-business infrastructure.
This chapter contains the following sections:
v “Securing the enterprise network” on page 1
v “Access Manager — core technologies” on page 3
v “Understanding authorization: conceptual model” on page 5
v “The Access Manager authorization service” on page 8
v “Implementing a network security policy” on page 11
v “The Access Manager authorization API” on page 16
v “External authorization capability” on page 20
v “Access Manager Base certificate and password management” on page 24
Securing the enterprise network
Many organizations now value the public Internet and private intranets as effective
and 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. Online
services allow individuals to send electronic mail and to tap the Web’s vast
encyclopedia 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 supply
chain relationships, facilitate collaboration with business partners, and provide
increased customer connectivity—provided they can expose corporate resources
with a high degree of security. Businesses want to use the Internet as a global
commercial and distribution vehicle, but have been hindered by the lack of proven
security policy mechanisms and management systems.
Access Manager is an information policy management solution that provides
organizations with centralized network security services—where you can
consistently implement and maintain corporate security policy.
Access Manager provides the three primary requirements for balanced security
solution:
v Provides a variety of solutions for creating a highly secure network environment
v Provides convenient and intuitive management tools for secure centralized
administration
v Provides security mechanisms that do not hinder permitted client activity on the
network
1
Network security — common concerns
Both the world-wide public Internet and company-private intranets connect to
heterogeneous computer systems, applications, and networks. This mixture of
dissimilar hardware and software usually impacts a network in the following
ways:
v No centralized control of security for applications
v No unified resource location naming convention
v No common support for high availability of applications
v No common support for scalable growth
New business models require organizations to expose their information resources
to a previously unthought of degree. These businesses need to know that they can
securely control access to those resources.
Managing policy and users across distributed networks has proven difficult for
Information Technology (IT) managers, especially since individual application and
system vendors implement authorization in their own proprietary fashion.
Companies realize that developing new authorization services for each enterprise
application is an expensive process that leads to a difficult-to-manage
infrastructure. A centralized authorization service that is accessed by developers
via a standardized API could greatly speed time to market and reduce
total-cost-of-ownership.
A centralized network security management system needs to fulfill requirements
that include:
v Co-exist with and/or leverage existing firewall and authenticator architectures
v Integrate or co-exist with network and application management frameworks
v Be application-independent
Introducing Access Manager
Access Manager is a complete authorization and network security policy
management solution that provides unsurpassed end-to-end protection of resources
over geographically dispersed intranets and extranets.
In addition to its state-of-the-art security policy management feature, Access
Manager supports authentication, authorization, data security, and resource
management capabilities. You use Access Manager in conjunction with standard
Internet-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 supports
external authenticators.
v Authorization framework
The Access Manager authorization service, accessed via a standard authorization
API, provides permit and deny decisions on access requests for native Access
Manager servers and third-party applications.
With Access Manager, businesses can now securely manage access to private
internal 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 corporate
firewall system, can fully protect the Enterprise intranet from unauthorized access
and intrusion.
The authorization service API standard
Authorization services are a critical part of an application’s security architecture.
After a user passes the authentication process, authorization services proceed to
enforce the business policy by determining what services and information the user
can access.
For example, a user accessing a Web-based retirement fund would be able to view
personal 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 the
centralized authorization service, thus eliminating the necessity for developers to
write authorization code for each new application.
The authorization API allows businesses to standardize all applications on a
trusted authorization framework. With the authorization API, businesses can
provide more control over access to resources on their networks.
Access Manager — core technologies
The Access Manager network security management solution provides and supports
the following core technologies:
v Authentication
v Authorization
v Quality of Protection
v Scalability
v Accountability
v Centralized Management
Authentication
Authentication is the first step a client must take when making a request for a
resource from a network protected by Access Manager. The authentication process
is usually dependent on the specific requirements of the service-providing
application. Access Manager allows a highly flexible approach to authentication
through the use of the authorization API.
Access Manager Base provides built-in support of user name and password
authentication through the authorization API. Developers can build any custom
authentication mechanism that uses the authorization API.
Authorization
v
v
v
v
Access Manager authorization service
ACL and POP policies for fine-grained access control
Standards-based authorization API
External authorization service capability
Chapter 1. Access Manager overview
3
Quality of (data) protection
Quality of Protection is the degree to which Access Manager protects any
information transmitted between client and server. Quality of Protection is
determined by the combined effect of encryption standards and
modification-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 communication
v Data privacy – protects messages from being modified or inspected during
network communication
Supported Encryption Standards
Access Manager supports the following encryption ciphers over SSL:
v 40-bit RC2
v 128-bit RC2
v 40-bit RC4
v 128-bit RC4
v 40-bit DES
v 56-bit DES
v 168-bit triple DES
Secure communication
Access Manager supports the data integrity and data privacy provided by the
Secure Socket Layer communication protocol.
The Secure Socket Layer (SSL) handshake protocol was developed by Netscape
Communications Corporation to provide security and privacy over the Internet.
SSL works by using public key for authentication and secret key to encrypt data
that is transferred over the SSL connection.
Access Manager supports SSL versions 2 and 3.
Scalability
Scalability is the ability to respond to increasing numbers of users who access
resources in the secure domain. Access Manager uses the following techniques to
provide 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
4
IBM Tivoli Access Manager: Base Administrator’s Guide
– Additional content and resources
– Load balancing of incoming requests through junctions
v Optimized performance by allowing the off-loading of authentication and
authorization services to separate servers
v Scaled deployment of services without increasing management overhead
Accountability
Access Manager provides a number of logging and auditing capabilities. There are
log files that capture any error and warning messages generated by Access
Manager servers. There are also audit trail files that monitor Access Manager
server activity.
Log files:
v Access Manager server log files
v Serviceability messages
v Standard HTTP log files
Audit trail files:
v Access Manager server audit trail files
Centralized management
v Web portal manager
v pdadmin command line utility
Understanding authorization: conceptual model
When servers enforce security in a secure domain, each client must provide proof
of its identity. In turn, security policy determines whether that client is permitted
to perform an operation on a requested resource. Because access to every resource
in a secure domain is controlled by a server, the server’s demands for
authentication and authorization can provide comprehensive network security.
In security systems, authorization is distinct from authentication. Authorization
determines whether an authenticated client has the right to perform an operation
on a specific resource in a secure domain. Authentication ensures that the
individual is who he claims to be, but says nothing about the rights to perform
operations on a protected resource.
In the Access Manager authorization model, authorization policy is implemented
independently of the mechanism used for user authentication. Users can
authenticate their identity using either public/private key, secret key, or
customer-defined mechanisms.
Part of the authentication process involves the creation of a credential that
describes the identity of the client. Authorization decisions made by an
authorization service are based on user credentials.
The resources in a
security policy for
participants of the
resource requiring
secure domain receive a level of protection as dictated by the
the domain. The security policy defines the legitimate
secure domain and the degree of protection surrounding each
protection.
Chapter 1. Access Manager overview
5
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 the
request to the authorization service for processing.
v An authorization service that performs the decision-making action on the
request.
Authorization
Service
Authorization
Check
Request for
Resource
Authenticated
Client
Application
Server
Yes / No
Policy
Enforcer
Resources
Resource
Manager
Figure 1. General authorization model
Traditional applications bundle the policy enforcer and resource manager into one
process. Examples of this structure include Access Manager WebSEAL and
third-party applications.
The independent functionality of these authorization components allows much
flexibility in the design of the security enforcement strategy.
For example, such independence allows the security administrator to control:
v Where the processes are located
v Who writes the code for the processes
v How the processes perform their tasks
The benefits of a standard authorization service
Authorization in most systems, both legacy and new, is tightly coupled to
individual applications. Companies typically build applications over time to serve
their business needs. Many of these applications require some specific form of
authorization.
The result is often a wide variety of applications with differing authorization
implementations. These proprietary authorization implementations require separate
administration, are difficult to integrate, and result in higher costs of ownership.
A distributed authorization service can provide these independent applications
with a standard authorization decision-making mechanism. Benefits of such a
standard authorization service would include:
6
IBM Tivoli Access Manager: Base Administrator’s Guide
v Reduced cost of developing and managing access to applications
v Reduced total cost of ownership and management of separate authorization
systems
v Leverage of existing security infrastructure
v Allow new businesses to open more securely
v Enable newer and different kinds of applications
v Allow shorter development cycles
v Share information securely
Introducing the Access Manager authorization service
Access Manager integrates into existing legacy and emerging infrastructures and
provides secure, centralized policy management capability. The Access Manager
authorization service—together with resource managers (such as
WebSEAL)—provides a standard authorization mechanism for business network
systems.
Existing applications can take advantage of the authorization service. Authorization
policy 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 in
turn makes decisions based on the corporate security policy.
The Access Manager authorization service is also extensible and can be configured
to call on other authorization services for additional processing using the external
authorization service plug-in interface.
Access Manager authorization service benefits
The authorization service provides the following benefits:
v The service is application independent.
v The service uses a standard authorization coding style that is language
independent (the authorization API).
v The service is centrally managed and therefore easy to administer — the
addition of a new employee, for example, requires modifying the privilege
database in one central location, rather than across multiple systems.
v The service addresses the application of security services in a heterogeneous
cross-platform environment.
v The service integrates existing non-Access Manager authorization systems
through an external authorization service capability.
v The service has a scalable and flexible architecture that can be easily integrated
with existing infrastructure.
v The service enables multi-tiered authorization — a credentials packet can be
passed 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.
Chapter 1. Access Manager overview
7
The Access Manager authorization service
The Access Manager authorization service is responsible for the authorization
decision-making process that helps to enforce a network security policy.
Authorization decisions made by the authorization service result in the approval or
denial of client requests to perform operations on protected resources in the secure
domain.
Components
The authorization service is made up of three basic components:
v Master authorization policy database
v Policy server
v The authorization decision-making evaluator
Master authorization policy database
The master authorization policy database contains the security policy information
for all resources in the secure domain. The database also contains all necessary
credential 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, replicates
this policy information throughout the secure domain, and updates the database
replicas whenever a change is made to the master.
The policy server also maintains location information about the other Access
Manager 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 evaluator
The authorization evaluator is the decision-making process that determines a
client’s ability to access a protected resource based on the security policy. The
evaluator 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:
8
IBM Tivoli Access Manager: Base Administrator’s Guide
Authorization Service
Web Portal
Manager
Management
Interface
Policy
Server
(pdmgrd)
Authorization
Evaluator
Master
Authorization
Policy
Replica
Authorization
Policy
AuthAPI
Resource
Manager
Figure 2. Authorization service components
Authorization service interfaces
The 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 pdadmin
utility) to apply policy rules (templates) on network resources and register the
credentials of participants in the secure domain.
The Web portal manager applies this security policy data to the master
authorization 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 authorization
decisions from the resource manager to the authorization evaluator which then
passes back a recommendation. The Access Manager Authorization ADK Developer
Reference contains the details of this API.
Chapter 1. Access Manager overview
9
Authorization Service
Web Portal
Manager
Management
Interface
Policy
Server
(pdmgrd)
Authorization
Evaluator
Master
Authorization
Policy
Replica
Authorization
Policy
AuthAPI
Resource
Manager
Figure 3. Authorization service: interfaces
Replication for scalability and performance
Authorization service components can be replicated to increase availability in a
heavy-demand environment.
You can configure the master authorization policy database, containing policy rules
and credential information, to automatically replicate. Applications that call the
authorization 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 database
The database is replicated for each application that uses the authorization service
in local cache mode.
v The application uses a shared replica cached by the remote authorization server
component
The database is replicated for each instance of the authorization server. Many
applications can access a single authorization server.
Update notification from the policy server (whenever a change has been made to
the master authorization policy database) triggers the caching process to update all
replicas.
10
IBM Tivoli Access Manager: Base Administrator’s Guide
Authorization Service
Web Portal
Manager
Policy
Server
(pdmgrd )
Master
Authorization
Policy
Replica
Authorization
Policy
Replica
Authorization
Policy
Authorization
Evaluator
Replica
Authorization
Policy
AuthAPI
Resource
Manager
Figure 4. Replicated authorization service components
Performance notes
v In addition to update notifications direct from the policy server, the application
servers also check the version of the master authorization policy database every
few 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 both
cases 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 policy
template in its own cached version of the database. WebSEAL does not have to
access the network to obtain this information from the master database. The
result 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 policy
The security policy for a secure domain is determined by controlling user and
group participation in the domain and applying rules, known as access control list
(ACL) policies and protected object policies (POP), to resources requiring
protection. The authorization service enforces these policies by matching a user’s
credentials with the permissions in the policy assigned to the requested resource.
The resulting recommendation is passed to the resource manager which completes
the response to the original request.
Defining the network security policy
The authorization service uses a central database that lists all resources in the
secure domain and the ACL and POP policies assigned to each resource. This
master authorization policy database and the user registry (containing user and
group 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.
Chapter 1. Access Manager overview
11
2. The level of protection on all objects in the secure domain
The master authorization policy database maintains this information.
The protected object space
The protected object space is a hierarchical portrayal of resources belonging to a
secure domain. The objects that appear in the hierarchical object space represent
the 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 Manager
management utilities.
Policy templates can be attached to objects in the object space to provide protection
of the resource. The authorization service makes authorization decisions based
these 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. This
includes static Web pages and dynamic URLs that are converted to database
queries or some other type of application.
v Access Manager management objects
These objects represent the management activities that can be performed via the
Web portal manager. The objects represent the tasks necessary to define users
and set security policy. Access Manager supports delegation of management
activities and can restrict an administrator’s ability to set security policy to a
subset of the object space.
v User-defined objects
These objects represent customer-defined tasks or network resources protected
by applications using the authorization service via the authorization API.
Management
Objects
Web
Objects
User-Defined
Objects
Figure 5. Access Manager protected object space
Defining and applying ACL and POP policies
Security administrators protect system resources by defining rules, known as ACL
and POP policies, and applying these policies to the object representations of those
resources in the object space.
12
IBM Tivoli Access Manager: Base Administrator’s Guide
The authorization service performs authorization decisions based on the policies
applied to these objects. When a requested operation on a protected object is
permitted, the application responsible for the resource implements this operation.
One policy can dictate the protection parameters of many objects. Any change to
the rule affects all objects to which the template is attached.
Explicit and inherited policy
Policy can be explicitly applied or inherited. The Access Manager protected object
space supports inheritance of ACL and POP attributes. This is an important
consideration for the security administrator who manages the object space. The
administrator only needs to apply explicit policies at points in the hierarchy where
the rules must change.
Explicit Rule
Inherited
Rule
Management
Objects
Web
Objects
User-Defined
Objects
Figure 6. Explicit and inherited policies
Examples of types of policy include:
v Hard-coded rules
v External authorization capability
v Special secure labeling
v Access control lists (ACLs)
The access control list (ACL)
An access control list policy, or ACL policy, is the set of controls (permissions) that
specifies the conditions necessary to perform certain operations on that resource.
ACL policy definitions are important components of the security policy established
for the secure domain. ACL policies, like all policies, are used to stamp an
organization’s security standards onto the resources represented in the protected
object space.
An ACL policy specifically controls the following:
1. What operations can be performed on the resource
2. Who can perform these operations
An ACL policy is made up of one or more entries that include user and group
designations and their specific permissions or rights.
Chapter 1. Access Manager overview
13
Figure 7. ACL policy
Protected object policies (POP)
ACL policies provide the authorization service with information to make a yes or
no answer on a request to access a protected object and perform some operation on
that object.
POP policies contain additional conditions on the request that are passed back to
Access Manager Base and the Resource Manager (such as WebSEAL) along with
the yes ACL policy decision from the authorization service. It is the responsibility
of 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 the
pdadmin pop commands.
Description
Descriptive text for the policy. This appears in the pop
show command.
Warning Mode
Provides administrators a means to test ACL and POP
policies.
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 the
protected object.
Enforced by Resource Manager (such as WebSEAL)
POP attribute
Description
Quality of Protection
Specifies degree of data protection: none, integrity,
privacy.
IP Endpoint Authentication
Method Policy
Specifies authentication requirements for access from
members of external networks.
Policy administration: The Web portal manager
The Web portal manager is a Web-based graphical application used to manage
security policy in a secure domain. The pdadmin command line utility provides
the same user and group administration capabilities as the Web portal manager,
plus many commands not supported by the Web portal manager.
14
IBM Tivoli Access Manager: Base Administrator’s Guide
From the Web portal manager (or pdadmin), you can manage the user registry, the
master authorization policy database, and the Access Manager servers. You can
also add and delete users / groups and apply ACL and POP policies to network
objects.
Create, modify, and
delete user and group
accounts
Windows NT
Workstation
Apply policies on the
protected object space
Web Portal
Manager
Security
Server
Policy
Server
User
Registry
Master
Authorization
Policy
Figure 8. Web portal manager: Administration of the security policy
The authorization process: step-by-step
Figure 9 illustrates the complete authorization process:
Secure Domain
Authorization
Service
2. Request for
Authorization
(AuthAPI)
3. Authorization
Check
4. Authorization
Decision
(AuthAPI)
1. Request
Policy
Enforcer
Client
6. Response
Authorization
Policy
/
Protected Object
Space
5. Authorized
Operation
Resources
Resource
Manager
Figure 9. The Access Manager authorization process
1. An authenticated client request for a resource is directed to the resource
manager server and intercepted by the policy enforcer process.
Chapter 1. Access Manager overview
15
2.
3.
4.
5.
6.
The resource manager can be WebSEAL (for HTTP, HTTPS access) or a
third-party application.
The policy enforcer process uses the authorization API (See “The Access
Manager authorization API”) to call the authorization service for an
authorization decision.
The authorization service performs an authorization check on the resource,
represented as an object in the protected object space. Base POP policies are
checked first. Next the ACL policy attached to the object is checked against the
client’s credentials. Then, POP policies enforced by the resource manager are
checked.
The decision to accept or deny the request is returned as a recommendation to
the resource manager (via the policy enforcer).
If the request is finally approved, the resource manager passes the request on to
the application responsible for the resource.
The client receives the results of the requested operation.
The Access Manager authorization API
The Access Manager Authorization Application Programming Interface (API)
allows Access Manager applications and third-party applications to query the
authorization service to make authorization decisions.
The authorization API is the interface between the resource manager (requesting
the authorization check) and the authorization service itself. The authorization API
allows the policy-enforcing application to ask for an authorization decision, but
shields the application from the complexities of the actual decision-making process.
The authorization API provides a standard programming model for coding
authorization requests and decisions. The authorization API lets you make
standardized calls to the centrally managed authorization service from any legacy
or 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. The
authorization server maintains its own cache of the replica authorization policy
database. This mode is recommended for handling authorization requests from
application 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 of
the authorization database for the application. Local cache mode provides better
performance because the application performs all authorization decisions locally
instead of across a network. However, the overhead of database replication and
the security implications of using this mode make it best suited for use by
trusted 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 to
shield the user from the complexities of the authorization service mechanism itself.
Issues of management, storage, caching, replication, credential formats, and
authentication methods are all hidden behind the authorization API.
16
IBM Tivoli Access Manager: Base Administrator’s Guide
The authorization API also works independently from the underlying security
infrastructure, the credential format, and the evaluating mechanism. The
authorization API makes it possible to request an authorization check and get a
simple yes or no recommendation in return. The details of the authorization check
mechanism are invisible to the user.
Using the authorization API: two examples
Third-party applications can use the authorization API to perform access control on
very specific and specialized processes.
Example 1:
A graphical user interface can be designed to dynamically show task buttons as
active 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 of
authorization only determines if the client can run the CGI program. If access is
allowed to the CGI application, no further control is available to resources
manipulated by the CGI application.
As illustrated in Figure B of Figure 10 on page 18, access controls have been set on
resources that the CGI program manipulates. The Web application is configured to
use the authorization API. Now the CGI program can call the authorization service
to make authorization decisions on the resources it manipulates — based on the
identity of the requesting client.
Chapter 1. Access Manager overview
17
Figure A
Authorization
Service
Coarse-grained
Access
Request
WebSEAL
Client
Response
Web
Application
Objects
Manipulated
by CGI
Figure B
Authorization
Service
Request
WebSEAL
Client
Response
Function Call
A
Web
P
Application
I
Fine-grained
Authorized
Access
Objects
Manipulated
by CGI
Figure 10. Example use of the authorization API
Authorization API: remote cache mode
In remote cache mode, applications use the function calls provided by the
authorization API to communicate to the (remote) authorization server (pdacld).
The authorization server functions as the authorization decision-making evaluator
and maintains its own replica authorization policy database.
The authorization server makes the decision and returns a recommendation to the
application via the API. The server can also write an audit record containing the
details 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 on
another machine. You can also install the authorization server on more than one
machine in a secure domain to allow for high availability. The authorization API
will transparently fail-over when a particular authorization server fails.
18
IBM Tivoli Access Manager: Base Administrator’s Guide
Authorization Service
Policy
Server
(pdmgrd )
pdacld
Authorization
Evaluator
Master
Authorization
Policy
Replica
Authorization
Policy
AuthAPI
AuthAPI
Third-Party
Application
Resources
Authenticated
Client
Figure 11. authorization API: remote cache mode
Authorization API: local cache mode
In local cache mode, the API downloads and maintains a replica of the
authorization policy database on the application’s local file system. It performs all
authorization decisions in-memory, which results in higher performance and better
reliability.
You must manually register any application using the authorization API in local
cache mode with the authorization service. The policy server must know the
location of any local cache mode authorization API application so it can update the
replica authorization policy database associated with it.
The local replica is persistent across invocations of the application. When the API
starts in replica mode, it checks for any updates to the master authorization policy
database that might have occurred since the local replica was built.
Chapter 1. Access Manager overview
19
Authorization Service
Policy
Server
(pdmgrd )
Authorization
Evaluator
Master
Authorization
Policy
Replica
Authorization
Policy
AuthAPI
WebSEAL
or
Third-Party
Resources
Authenticated
Client
Figure 12. Authorization API: local cache mode
External authorization capability
In some situations, the standard Access Manager policy implementations—Access
Control Lists and Protected Object Policies—might not be able to express all the
authorization rules required by an organization’s security policy. Access Manager
provides optional external authorization capability to accommodate any additional
authorization requirements.
The external authorization service allows you to impose additional authorization
controls and conditions that are dictated by a separate (external) authorization
service module.
Extending the authorization service
External authorization capability is automatically built into the Access Manager
authorization service. If you configure an external authorization service, the Access
Manager authorization service simply incorporates the access decision paths into
its evaluation process.
Applications that use the authorization service—such as WebSEAL and any
application using the authorization API—benefit from the additional, but seamless,
contribution of a configured external authorization service. Any addition to the
security policy through the use of an external authorization service is transparent
to these applications and requires no change to the applications.
The external authorization service architecture allows the full integration of an
organization’s existing security service. An external authorization service preserves
a company’s initial investment in security mechanisms by allowing legacy servers
to be incorporated into the Access Manager authorization decision-making process.
20
IBM Tivoli Access Manager: Base Administrator’s Guide
Imposing conditions on resource requests
An external authorization service can be used to impose more specific conditions
or 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 attempt
v Actively monitor the access attempt and cause an alert or alarm whenever
unacceptable behavior is detected
v Billing / micro-payment transactions
v Impose access quotas on a protected resource
The authorization evaluation process
An authorization decision that incorporates an external authorization server takes
place 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 are
each called in turn to evaluate their own external authorization constraints.
Invocation of the external authorization service occurs regardless of whether or
not the necessary permission is granted to the user by the Access Manager
authorization service.
2. Each external authorization service returns a decision of permitted, denied, or
indifferent.
When “indifferent” is returned, the external authorization service has
determined that its functionality is not required for the decision process and
that it does not participate.
3. Each external authorization service decision is weighted according to the level
of importance that its decision carries in the process.
The weighting of individual external authorization services is configured when
the service plug-in is loaded.
4. All authorization decision results are summed and combined with the decision
made by the Access Manager authorization service. The resulting decision is
returned to the caller.
Example
Figure 13 on page 22 illustrates an authorization decision involving a WebSEAL
server and an external authorization service.
Chapter 1. Access Manager overview
21
Secure Domain
External
Authorization
Service
4. External
Authorization
Check
5. External Authorization
Result (denied -101)
Authorization
Policy
Authorization
Service
2. Request for
Authorization
3. Authorization
Check
(allowed +100)
6. Combined Authorization
Decision (denied -1)
/
Protected Object
Space
Authzn API
1. Request
7. Denied Access
Client
8. Response:
"Denied"
Third-Party
Resource Manager
Resources
Figure 13. External authorization service with WebSEAL
In this example, the purpose of the external authorization service is to impose a
quota restriction on how often the photo-quality printer resource can be accessed.
The service implementation imposes a limit on the number of job submissions that
any one person can make to this printer in one week. An external authorization
service trigger condition has been attached to the photo printer resource so that the
external authorization service is invoked anytime that the photo printer is
accessed.
The external authorization service has been loaded with the default decision
weighting of 101, which overrides any decision made by the Access Manager
authorization 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 group
GraphicArtists and so is normally permitted to submit jobs to the printer.
2. The WebSEAL server first consults the Access Manager authorization service to
determine whether the requesting user has permission to submit jobs to the
printer.
3. The authorization service checks the access permissions on the target requested
object 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 the
GraphicArtists group access to the resource. Therefore, the authorization service
grants the user permission to submit the job.
4. Since the photo printer resource is being accessed and an external authorization
service trigger condition was attached to this object, a request is also made to
the external authorization service configured for that trigger condition.
22
IBM Tivoli Access Manager: Base Administrator’s Guide
The external authorization service receives all of the Access Decision
Information (ADI) that was passed in with the original access decision check by
WebSEAL.
5. The external authorization service consults the record of previous accesses
made by this user. If the requesting user has not exceeded their quota for the
week, it returns an access decision of “indifferent”.
The implication is that the external authorization service is indifferent to the
request and has no intention of participating in the access decision because its
conditions for denying access have not been met.
However, if the user has exceeded their quota, then the external authorization
service returns a decision of “access denied”.
For this example, it is assumed that the requester has exceeded their quota and
that the external authorization service detects this and returns an “access
denied” decision.
6. The Access Manager authorization service receives the “access denied” result
from the external authorization service. It then takes this decision and weights
it with the default external authorizations service weighting value of 101.
The results of the external authorizations service decision and the decision
made 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 service
Two 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 external
authorizations service. When the trigger condition is encountered during an
authorization check, the external authorizations service interface is invoked to
make an additional authorization decision.
Refer to the Access Manager Authorization API Developer Reference for advanced
details on implementing an external authorizations service.
Deployment strategies
Access Manager allows you to implement an external authorizations service in
several ways:
v Any number of external authorization servers can be added to your secure
domain to perform a variety of authorization evaluations. Each external
authorizations service is loaded into the individual local-mode authorization API
client application. Applications that can load external authorizations services
include WebSEAL (webseald), the authorization server (PDAcld), other Access
Manager servers, and any authorization applications written by the customer.
v Remote-mode authorization API clients, which make requests to the
authorization server for authorization decisions, automatically make use of any
external authorizations service that are loaded by the authorization server.
Chapter 1. Access Manager overview
23
v More than one external authorizations service can be called for any single trigger
condition. In this case, the results of each external authorizations service is
weighted accordingly and then the results are combined with the result of the
Access 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 that
is being requested, triggers a call to the external authorizations services that are
configured 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 specifically
when a user requests a write operation to a protected resource, but not for any
other operation. It is then possible to develop sets of operations for which one or
more external authorizations services in combination are triggered according the
set of operations requested.
v The external authorizations services are implemented as dynamically loadable
library (DLL) modules. This greatly simplifies the task of external authorizations
service development. There is no requirement to make remote requests to the
external authorizations service and the overhead of making the call is equivalent
to the overhead of a function call.
v The combination of the authorization API and an external authorizations service
provides a highly extensible and flexible solution for implementing complex
security policy.
Access Manager Base certificate and password management
The Access Manager Base components use SSL for encryption, system
authentication, and application-level authentication. SSL uses certificates for
operation. In the secure environment, pdmgrd acts as the certificate authority (CA)
and is responsible for the creation and renewal of certificates. The Access Manager
runtime (pdrte) only relies upon SSL server side authentication and as such, does
not require a client-side certificate. However, all of the Access Manager servers
such as pdmgrd, pdacld, and aznAPI servers (like WebSEAL) rely on client-side
certificates to operate.
The servers use certificates to authenticate themselves. For example, when pdacld
is communicating with pdmgrd, it presents its client-side certificate. In this
example, pdmgrd can be considered the server and pdacld as the client. The
pdmgrd 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 the
same for the certificate presented by pdmgrd. As part of the Access Manager
application-level authentication, after pdmgrd determines that the pdacld
certificate is good, it tries to map that certificate to an Access Manager principal. If
the authentication succeeds, then the servers can begin communicating.
The certificates used by Access Manager are kept in keyring database files (these
have a .kdb extension). These files should be secured and protected by the strictest
operating system controls available because they contain the private keys for the
certificates in question. For example, the keyring database file for pdmgrd is
ivmgrd.kdb and by default it is only readable and write-able by the ivmgr user and
the ivmgr group.
Furthermore, to facilitate unattended server operation, there are files that contain
an obfuscated (not encrypted) version of the password to the keyring database
files. These are called stash files which are denoted by a .sth file extension. Again,
24
IBM Tivoli Access Manager: Base Administrator’s Guide
these files should be secured using OS measures. For pdmgrd, the stash file is
ivmgrd.sth and its permissions are the same as ivmgrd.kdb.
For security reasons, both the certificates and the keyring database file passwords
can be set to expire after a configurable amount of time. The default lifetime for a
certificate is 365 days. The default lifetime for a keyring database file password is
183 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 the
certificates and passwords automatically while they are running.
However, if the servers are not running within a specified window of time, their
certificates or passwords can expire. If this is the case, a manual refresh is
necessary. Furthermore, if a certificate, password, or entire keyring database file is
corrupted, then to keep the Access Manager domain secure, a manual refresh is
also warranted.
Initial configuration
The certificates used by the Access Manager components are created as part of
their initial configurations. In a brand new Access Manager installation, the
pdmgrd server is the first server configured. As part of its configuration, the
PDCA certificate is created and a personal certificate used by pdmgrd is created
and signed by the PDCA certificate. Both of these certificates reside in the
ivmgrd.kdb keyring database file. Also, as part of the pdmgrd configuration, the
runtime keyring database file, pd.kdb, is created and the PDCA certificate is
inserted into it as a trusted certificate.
When new systems are added to the Access Manager domain, pdrte is configured
first. Again, as part of this configuration, the system pd.kdb and pd.sth files are
created and the PDCA certificate is included in the keyring database file as a
trusted certificate.
When new aznAPI servers (such as pdacld or WebSEAL) are configured, the run
the svrsslcfg command. This tool creates a keyring database file (such as
pdacld.kdb) and places a personal certificate for the server in it. The tool also
inserts the PDCA certificate as a trusted certificate in the keyring database file.
These two certificates are obtained from pdmgrd and are transported to the client
machine over SSL using the runtime keyring database file.
Keyring database file and stash file renewal information
The following table lists the components and their associated keyring and stash
files. It also describes how they get created and refreshed.
Component
pdrte
Keyring/Stash
File
pd.kdb pd.sth
(does not
contain a
client-side
certificate)
How it gets
created
Processes that
Tool for manual
automatically
update
updates the
keyring file
and/or password
During the pdrte Invocations of
configuration
pdadmin1
bassslcfg
-chgpwd
Chapter 1. Access Manager overview
25
Component
Keyring/Stash
File
How it gets
created
Processes that
Tool for manual
automatically
update
updates the
keyring file
and/or password
pdmgrd
ivmgrd.kdb
ivmgrd.sth
During pdmgrd
configuration
Running
pdmgrd1,2
pdacld
ivacld.kdb
ivacld.sth
During pdacld
configuration
Running pdacld1 svrsslcfg
-chgpwd4 and
svrsslcfg
-chgcert5
aznAPI server
(such as
WebSEAL)
aznAPI.kdb
aznAPI.sth
(name is
configurable)
Running
Running
svrsslcfg -config instance of the
aznAPI server1
mgrsslcfg
-chgpwd3and
mgrsslcfg
-chgcert3
svrsslcfg
-chgpwd6and
svrsslcfg
-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 is
recycled. The pdmgrd.log file contains a message stating when the server needs
to 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 trust
Each of the keyring database files also contains a list of trusted CAs. For Access
Manager, every keyring database file (except ivmgrd.kdb) has the PDCA certificate
as a trusted CA. The CA is the certificate that is used to sign all of the other Access
Manager certificates. This CA is created during pdmgrd configuration and is
placed in the ivmgrd.kdb file. It is extremely important to protect the ivmgrd.kdb
file to keep the PDCA certificate’s private key from being compromised. If it is
compromised, then it must be regenerated. It this happens, then every keyring
database file and every certificate in the secure domain needs to be regenerated as
well. 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 CA
certificate is on and pdmgrd is running, then the CA certificate is obtained by
running bassslcfg -getcacert -h pdmgrd hostname -c certificate file name. If
auto-download is off, then the base-64 DER encoded version of the PDCA
26
IBM Tivoli Access Manager: Base Administrator’s Guide
certificate must be hand copied to the machine. This file is stored as
pdcacert.b64 on the pdmgrd machine. Finally, run bassslcfg -config to
complete the pdrte configuration.
3. Regenerate any pdacld keyring files within the domain by running svrsslcfg
-chgpwd and svrsslcfg -chgcert (pdmgrd must be running). These commands
update both the server certificate for pdacld and its trusted certificate (the new
PDCA certificate).
4. Regenerate any other aznAPI server keyring files within the domain by
running svrsslcfg -chgpwd and svrsslcfg -chgcert (pdmgrd must be running).
These commands update both the server certificate for the server and its
trusted certificate (the new PDCA certificate).
Certificate Revocation
If a server’s keyring database file or certificate is compromised, it can be revoked
by running the appropriate chgcert command. This effectively generates a new
certificate making the old certificate invalid. For example, if a pdacld has its
certificate compromised then running svrsslcfg -chgcert generates a new certificate
for that file and makes the compromised certificate invalid. Also, by running the
appropriate sslcfg -unconfig command, a certificate no longer authenticates within
Access Manager.
Additional considerations
Additional considerations for keyring database file and stash file renewal are as
follows:
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. For
example, for pdacld, run svrsslcfg -chgpwd and then svrsslcfg -chgcert. This is
necessary because a valid password is needed to open the keyring database file
to get to the certificate.
v The value for the lifetime of a certificate is controlled by the value of the
ivmgrd.conf, [ssl], ssl-cert-life attribute when pdmgrd is started. Any certificates
issued or renewed uses this value. To increase or decrease this value, change the
value and restart pdmgrd. The new value is only in effect for certificates issued
or renewed from that point on.
v For automatic password renewal, the value for the lifetime of a password is
controlled by the value of the [ssl], ssl-pwd-life attribute in effect when the server
is started. For manual password renewal, the value is dictated by the value
supplied to the chgpwd command. This value is also written into the
appropriate configuration file.
v Access Manager servers can also communicate with LDAP using SSL. In the
standard configuration, this communication uses server-side authentication only.
Therefore, the Access Manager server only needs the CA certificate that signed
the LDAP server certificate or the LDAP server certificate itself. The expiration
and management of these certificates is not handled by Access Manager.
However, it is possible to include the LDAP certificate in the keyring database
file 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 permissions
of pd.kdb and pd.sth.
v The configuration files mentioned are generally found in the
pd-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,
Chapter 1. Access Manager overview
27
and /opt/PolicyDirector/etc/pd.conf respectively. Similarly, the keyring
database files and stash files can be found in the pd-install-directory/keytabs
directory.
28
IBM Tivoli Access Manager: Base Administrator’s Guide
Chapter 2. Managing the protected object space
A secure domain contains physical resources that usually need some level of
protection. Resources can include files, directories, and printer services. Access
Manager uses a virtual representation of these resources called the protected object
space.
Resources can be protected by attaching ACL and POP policies to the object
representations of these resources. This chapter discusses the protected object space
and how you can create extensions to the object space to support custom
application requirements.
This chapter contains the following sections:
v “Understanding the protected object space” on page 29
v “Defining a database object space” on page 31
Understanding the protected object space
The Access Manager security model depends on ACL and POP policies to provide
fine-grained protection for these resources. A corporate security policy is
implemented by the strategically applying custom ACL and POP policies to those
resources requiring protection. The Access Manager authorizations service makes
decisions to permit or deny access to resources based on user credentials and the
specific permissions and conditions set in the ACL and POP policies.
In order to apply ACL and POP policies and allow the authorizations service to
perform its security checks, Access Manager uses a virtual object representation of
secure domain resources called the protected object space.
As a Access Manager security administrator, you can use the Web portal manager
or the pdadmin utility to attach ACL and POP policies to the logical objects in the
object space.
Elements of the protected object space
The Access Manager protected object space is the logical and hierarchical portrayal
of resources belonging to a secure domain. Objects that appear in the hierarchical
object space represent actual physical network resources.
v System Resource – the actual physical file, network service, or application
v Protected Object – the logical representation of an actual system resource used
by the authorizations service, the Web portal manager, and other Access
Manager management utilities
The protected object space uses two types of objects:
v Container objects
Container objects are structural designations that allow you to organize the
object space hierarchically into distinct functional regions. Container objects
contain resource objects.
v Resource objects
29
Resource objects are the representations of actual network resources (such as
services, files, and programs) in your secure domain.
container objects
resource objects
Figure 14. Access Manager protected object space
Protected object space hierarchy
The structural top, or start, of the protected object space is the root container
object. 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 secure
domain. All HTTP operations are authorized against some object in this sub-tree.
Web objects represent anything that can be addressed by a URL. This includes
static Web pages and dynamic URLs that are converted to database queries or
some 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 all
Access Manager management operations. Management objects represent the
services required to define users and groups, and set security policy. These tasks
can 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 can
restrict an administrator’s ability to set security policy to a subset of the object
space.
v User-defined objects
30
IBM Tivoli Access Manager: Base Administrator’s Guide
These objects represent customer-defined tasks or network resources protected
by third-party applications that use the authorization API to make calls to the
Access Manager authorizations service.
/ (root)
WebSEAL
server1
Management
User-Defined
server2
Users
POP
Groups
Server
Web Objects
ACL
Action
Config
Management
Objects
GSO
Replica
User-Defined
Objects
Figure 15. Regions of the Access Manager protected object space
User-defined object space for third-party applications
Access Manager can provide authorization services to any third-party application
object defined by the protected object space.
A region of the object space needs to be defined for each application that is using
Access 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 authorizations
service through the authorization API. Two necessary steps are required to
integrate 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 space
where you can create objects for third-party application. Before you can add new
objects, you must define a new object space container.
Defining a database object space
Access Manager allows you to extend its authorization services to objects
belonging to a user-defined third-party object space. Two necessary steps are
required 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.
Chapter 2. Managing the protected object space
31
The pdadmin objectspace commands allow you to easily create user-defined object
space regions and manage the objects contained in these spaces. User-defined
object spaces created with these commands are dynamic because they can be
updated while Access Manager is running.
Creating a new user-defined container object
Use the pdadmin objectspace and object commands to manage user-defined object
spaces. 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
1
2
3
4
5
6
7
8
–
–
–
–
–
–
–
–
–
unknown
secure domain
file
executable program
directory
junction
WebSEAL server
unused
unused
9 – HTTP server
10 – nonexistent object
11 – container object
12 – leaf object
13 – port
14 – application container object
15 – application leaf object
16 – management object
17 – unused
The type category is only used by the Web portal manager to display an
appropriate icon with the object.
When creating an object, a type must be specified. You can select an appropriate
category, or use type 0 for “unknown”.
For example:
pdadmin> objectspace create /Test-Space “New Object Space” 14
pdadmin> 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.
32
IBM Tivoli Access Manager: Base Administrator’s Guide
Creating and deleting objects
Once 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 object
space, 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 portal
manager 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 child
objects to use the same policy as the parent.
For example:
pdadmin> object create /Test-Space/folder1 “Folder 1” 14
ispolicyattachable yes
pdadmin> object list /Test-Space
folder1
pdadmin> object show /Test-Space/folder1
Name: /Test-Space/folder1
Description: Folder 1
Type: (Application Container Object) : 14
Is Policy Attachable: yes
pdadmin> object create /Test-Space/folder2 “Folder 2” 14
ispolicyattachable no
pdadmin> object listandshow /Test-Space
Name: folder1
Description: Folder 1
Type: (Application Container Object) : 14
Is Policy Attachable: yes
Name: folder2
Description: Folder 2
Type: (Application Container Object) : 14
Is Policy Attachable: no
pdadmin> object delete /Test-Space/folder1
pdadmin> 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 all
child 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
34
IBM Tivoli Access Manager: Base Administrator’s Guide
Chapter 3. Using access control policies
Access Manager uses a virtual representation of the resources in the secure
domain—called the protected object space. Resources can be protected by defining
special security policies (rules) and attaching these policies to the object
representation of this resource in the protected object space.
The policy type that defines who has access to an object, and what operations can
be performed on the object, is known as an access control list policy or ACL
policy. ACL policies are used to help stamp an organization’s security policy onto
the resources belonging to the secure domain.
This chapter contains the following sections:
v “Introducing the ACL policy” on page 35
v “ACL entry syntax” on page 37
v “How the authorizations service uses ACL policies” on page 39
v “Evaluating an ACL” on page 41
v
v
v
v
v
“Sparse ACL model: ACL inheritance” on page 42
“Creating extended ACL actions and action groups” on page 46
“ACL policies and the protected object space” on page 49
“WebSEAL permissions” on page 50
“Management permissions” on page 51
v “Object and object space permissions” on page 57
v “Default administration ACL policies” on page 57
Introducing the ACL policy
An access control list policy (ACL) is a method used by Access Manager to provide
fine-grained protection to resources in the secure domain.
An ACL policy is a set of rules, or permissions, that specify the conditions
necessary to perform an operation on a protected object. An ACL policy identifies
the operations permitted on a protected object and lists the identities (users and
groups) 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 to
one or more objects.
An ACL policy consists of one or more entries that include user and group
designations and their specific permissions.
ACL policy entries
An ACL policy consists of one or more entries describing:
v The names of users and groups whose access to the object is explicitly controlled
v The specific operations permitted to each user, group, or role
35
v The specific operations permitted to the special any-other and unauthenticated
user categories
A user represents any authenticated Access Manager identity. Typically, users
represent network users or application servers.
A group is a collection of one or more users. A network administrator can use
group ACL entries to easily assign the same permissions to multiple users. New
users to the secure domain gain access to objects by becoming members of
appropriate groups. This eliminates the need to create new ACL entries for every
new user. Groups can represent organizational divisions or departments within a
secure 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 unique
identifier (UUID). The UUID provides extra security in the case where a user or
group is deleted from the domain and then recreated with the same name. For
example, even though a new user has the same name as the deleted user, Access
Manager allocates a new UUID to this user. Since the UUID is new, any existing
ACLs 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 the
policy server (pdmgrd).
Figure 16. Access control list for a Web page object
You can use the pdadmin utility or the Web portal manager to create, modify, and
delete ACL entries.
Creating and naming ACL policies
You can use the Web portal manager, or the pdadmin acl create command, to
create a unique ACL policy and save it with a name. You can then apply security
policy by attaching the ACL to objects in the protected object space.
The ACL becomes a single source policy (like a formula or recipe) containing the
specific entries that provide the correct level of protection for all objects associated
with 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 that
ACL.
36
IBM Tivoli Access Manager: Base Administrator’s Guide
ACL entry syntax
An ACL entry contains either two or three attributes, depending on the ACL entry
type, and appears in the following format:
ACL Entry
user
adam
---------T---r-
Type
ID
Permissions
Figure 17. ACL entry attributes
v Type – the entity category (user or group) for which the ACL was created
v ID (Identity) – the unique identifier (name) of the entity
The ID attribute is not required for the any-other and unauthenticated ACL
entry types
v Permissions (or actions) – the set of operations permitted on the object by this
user or group
Most permissions dictate the client’s ability to perform a specific operation on the
resource.
In the above example, the user adam (type = user, ID = adam) has permission to
read (view) the object protected by this ACL policy. The r permission allows the
read operation. The T permission enforces the traverse rule.
Type attribute
An ACL entry type identifies the user, group, or special entity for a specific ACL
entry. There are four ACL entry types.
Type
user
Description
Sets permissions for a specific user in the secure domain. The user must be a member
of the secure domain with an account in the registry. The user entry type requires a
user 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 group
entry type requires a group name (ID). The entry format is: group ID permissions
For example:
group engineering -------T-----r-
any-other
(also known as
any-authenticated)
Sets permissions for all authenticated users. No ID designation is required. The entry
format is: any-other permissions
For example:
any-other -------T-----r-
Chapter 3. Using access control policies
37
Type
unauthenticated
Description
Sets permissions for those users who have not been authenticated by the security
server. No ID designation is required. The entry format is: unauthenticated
permissions
For example:
unauthenticated -------T-----rThis ACL entry is a mask (a bit-wise “and” operation) against the any-other ACL entry
to determine the permission set. A permission for unauthenticated is granted only if
the permission also appears in the any-other entry. For example, the following
unauthenticated ACL entry:
unauthenticated -------------rw
masked against this any-other ACL entry:
any-other -------T-----rresults in these permissions:
-------------r- (read only).
ID attribute
The 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 and
stored 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 ACL
entry types.
Permissions (actions) attribute
Each ACL entry contains a set of permissions (or actions) that describe the specific
operations 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 objects
v An administrator’s ability to change access control rules on the object and any
sub-objects
v Access Manager’s ability to delegate user’s credentials
Note: ACL permissions are context-sensitive — the behavior of certain permissions
varies according to the region of the protected object space in which they are
applied. For example, the m permission has a different meaning on a
WebSEAL object than on a Management object.
38
IBM Tivoli Access Manager: Base Administrator’s Guide
Default Access Manager permissions (actions)
Access Manager defines seventeen default permissions (actions). The Web portal
manager divides these permissions into three categories.
Base
a A b B c g N t T W
Action Bit
Generic
d m s v
WebSEAL
l r x
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 additional
permissions (actions) for use by third-party applications. See “Creating extended
ACL actions and action groups” on page 46.
How the authorizations service uses ACL policies
Access Manager relies on ACL policies to specify the conditions necessary to
perform an operation on a protected object.
When an ACL is attached to an object, entries in the ACL specify what operations
are allowed on this object and who can perform those operations.
Access Manager uses a default set of permissions that cover a wide range of
operations. Permissions are represented by single printable ASCII characters (a-z,
A-Z). Each permission is displayed (by pdadmin or the Web portal manager) with
a label describing the operation it governs. In addition, the Web portal manager
groups 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 object
Application software typically contains one or more operations that are performed
on protected objects. Access Manager requires these applications to make calls into
Chapter 3. Using access control policies
39
the authorizations service before the requested operation is allowed to progress.
This call is made via the authorization API for both Access Manager services (for
example, WebSEAL) and third-party applications.
The authorizations service uses the information contained in the ACL to make a
simple yes or no response to the question: Does this user (group) have the r
permission (for example) to ‘view’ the requested object?
It is important to note that the authorizations service knows nothing about the
operation requiring the r permission. All it cares about is the presence, or not, of
the 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 is
completely independent of the operations being requested. This is why it is easy to
extend the benefits of the authorizations service to third-party applications.
Requirements for custom permissions
Default Access Manager permissions (actions) are available to third-party
applications. If a third-party application makes use of a default Access Manager
permission, the associated operation should very closely match that of the actual
operation normally performed by Access Manager. For example, r should only be
used 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 Manager
permission for a completely unrelated operation—because the authorizations
service does not know or care about the operation. However, this situation
would cause difficulty for an administrator who would have to distinguish
between two dissimilar uses of the same permission.
If a third-party application uses an operation that is not well represented by any
the default permissions, Access Manager allows you to define a new permission
(action) that can be used by this application and recognized by the authorizations
service.
See “Creating extended ACL actions and action groups” on page 46.
Custom action example
In this example, there is a requirement to protect a certain printer device from
unauthorized use. A third-party print spooling service is written with the
authorization API so that it can call the authorizations service to perform ACL
checks on requests made to the printer.
The standard Access Manager permissions do not include an obvious permission
for protecting printers. However, the printer can be protected by a newly created
permission (p in this example).
An ACL policy is attached to the printer object. If a user requests the use of the
protected printer, that user must have an ACL entry containing the p permission.
The authorizations service returns a favorable response if the p permission is
present and the printing operation proceeds. If the authorizations service finds no
existence of an p permission for that user, the printing operation is not allowed to
proceed.
40
IBM Tivoli Access Manager: Base Administrator’s Guide
Print
Spooler
Service
A
P
I
Can I use this
printer?
Authorization
Service
Authzn
Policy
Database
"YES"
Printer ACL
user michael p
Figure 18. Custom print spooler action
Evaluating an ACL
Access Manager follows a specific evaluation process to determine the permissions
granted to a particular user by an ACL. When you understand this process, you
can determine how best to keep unwanted users from gaining access to resources.
Evaluating authenticated requests
Access 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’s
group 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. This
implicit entry grants no permissions.
Successful match: no permissions granted. End of evaluation process.
Evaluating unauthenticated requests
Access Manager evaluates an unauthenticated user by granting the permissions
from the ACL’s unauthenticated entry.
The unauthenticated entry is a mask (a bitwise “and” operation) against the
any-other entry when permissions are determined. A permission for
unauthenticated is granted only if the permission also appears in the any-other
entry.
Since unauthenticated depends on any-other, it makes little sense for an ACL to
contain unauthenticated without any-other. If an ACL does contain
unauthenticated without any-other, the default response is to grant no permissions
to unauthenticated.
Chapter 3. Using access control policies
41
Example ACL entries
You set permissions for specific users and groups by specifying the appropriate
ACL entry type. In the following example, the group documentation has full
access privileges:
group documentation --bcg--Tdmsv--lrx
You can restrict access to other authenticated users in the secure domain (not
belonging 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 are
not members of the secure domain.
unauthenticated -------T-------r-
Note: Without an unauthenticated ACL entry, unauthenticated users cannot access
any secure documents within the secure domain.
Sparse ACL model: ACL inheritance
To secure network resources in a protected object space, each object must be
protected 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 for
a secure domain. This section discusses the concepts of inherited, or sparse ACLs.
Understanding the sparse ACL model
The power of ACL inheritance is based on the following principle: any object
without an explicitly attached ACL policy inherits the policy of its nearest
container object with an explicitly set ACL. In other words, all objects without
explicitly attached ACLs inherit ACLs from container objects with explicitly
attached ACLs. A particular chain of inheritance is broken when you attach an
explicit ACL on an object.
ACL inheritance simplifies the task of setting and maintaining access controls on a
large protected object space. In a typical object space, you only need to attach a
few ACLs at key locations to secure the entire object space — hence, a sparse ACL
model.
A typical object space begins with a single explicit ACL attached to the root
container 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 object
space below inherit this ACL.
When a region or sub-tree in the object space requires different access control
restrictions, you attach an explicit ACL at the root of that sub-tree. This interrupts
the flow of inherited ACLs from the primary object space root to that sub-tree. A
new chain of inheritance begins from this newly created explicit ACL.
42
IBM Tivoli Access Manager: Base Administrator’s Guide
The default root ACL policy
Access Manager checks inheritance beginning with the root of the protected object
space. If you do not explicitly set ACLs on any other objects in the tree, the entire
tree 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 different
entries and permission settings. But the root ACL can never be completely
removed.
The root ACL policy is explicitly set during the initial Access Manager installation
and configuration.
Core entries for the default root ACL — default-root — include:
Group iv-admin
Any-other
Unauthenticated
Tcmdbva
T
T
Traverse permission
Access 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 object
space. The traverse permission specifies that a user, group, any-other, or
unauthenticated identified in the ACL entry has permission to pass through this
container object in order to gain access to a protected resource object below in the
hierarchy.
A protected object is accessible to a requester if the requester possess the traverse
permission on each ACL attached to container objects above the requested resource
on the path towards root and including root.
The following example illustrates how the traverse permission works. Within the
ACME Corporation, there is an Engineering container object (directory), which also
contains a TechPubs container object (subdirectory). User kate, a member of the
Sales department, requires traverse to the Engineering/TechPubs directory to
review a release note file. The administrator provides traverse for any-other at the
root. The administrator provides traverse for group sales on the Engineering
directory. 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.
Chapter 3. Using access control policies
43
ACME Corporation
root
any-authenticated -------T---------
Sales/
Engineering/
group sales -------T---------
TechPubs/
(ACL inherited)
release_note
user kate ---------------r-
Figure 19. Traverse permission
You can easily restrict access to the hierarchy below a given container object —
without resetting individual permissions on these objects. Simply remove the
traverse permission from the appropriate ACL entry. Removing traverse permission
on a directory object protects all objects lower in the hierarchy, even if those objects
contain other less restrictive ACLs.
For example, if group sales did not have the traverse permission on the
Engineering directory, Kate could not access the release note file, even though she
has read permission for the file.
Resolving an access request
Inheritance begins with the root ACL and impacts all objects in the object space
until it reaches an object with an explicit ACL. At this point, a new chain of
inheritance begins.
Objects below an explicitly set ACL inherit the new access controls. If you delete
an explicit ACL, access control for all objects reverts back to the nearest directory
or container object with an explicitly set ACL.
When a user tries to access a secure object (such as a Web document), Access
Managerchecks whether the user has the permissions to access the object. It does
this by checking every object along the object hierarchy for the proper inherited or
explicitly set permissions.
A user is denied access to an object if any directory or container object in the
hierarchy above does not include the traverse permission for that user. Access is
also denied if the target object does not contain sufficient permissions to perform
the 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.
44
IBM Tivoli Access Manager: Base Administrator’s Guide
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 points
along the object hierarchy.
Applying ACL policies to different object types
Permissions for a variety of operations can be set in an ACL policy. Only a subset
of these possible operations might be relevant for a specific object to which the
ACL is attached.
The reason for this behavior is related to the two features of Access Manager that
are designed to make administration easier:
v ACL policies
v ACL inheritance
ACL policies allow you to attach the same ACL definition to multiple objects in the
protected object space. The ACL definition consists of enough entries to meet the
requirements of all objects to which the ACL is applied; however, each individual
object 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 it
in the hierarchy.
In summary, an ACL policy has to describe the necessary permissions for all object
types that it is applied to — and not just the object that it is attached to.
ACL policy inheritance example
The following figure illustrates the impact of a mixture of inherited and explicit
ACLs in a corporate object space.
A corporate object space has a general security policy set at the root object. Root is
followed by the /WebSEAL container object and individually controlled departmental
sub-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 or
any-other entry types.
The Year-to-Date sales file (ytd.html) has an explicit ACL that grants read
permission to members of the sales-vp group (who are also members of the sales
group).
Chapter 3. Using access control policies
45
Note: This ACL scheme need not be changed with the addition or subtraction of
users within the secure domain. New users are simply added to the
appropriate group(s). Likewise, users can be removed from those groups.
group iv-admin
-abc---Tdm----lrx
group ivmgrd-servers -------T------l-group webseal-servers -a--g--Tdm----lrx
unauthenticated
----------------any_authenticated
-------T-------r-
WebSEAL Server
( www.acme.com/ )
Production/
Departments/
Inventory/
Personnel/
staff.html
tele.html
group
group
group
group
Sales/
president.html
clientA.html
Note: Group "sales" includes members
of group "sales-vp".
manager.html
products.html
sales.html
iv-admin
-abc---Tdm----lrx
ivmgrd-servers -------T------l-webseal-servers -a--g--Tdm----lrx
sales
-------T------lrx
ytd.html
group
group
group
group
iv-admin
-abc---Tdm----lrx
ivmgrd-servers -------T------l-webseal-servers -a--g--Tdm----lrx
sales-vp
-------T-------r-
Figure 20. ACL inheritance example
Guidelines for a secure object space
v Set high-level security policy on container objects at the top of the object space.
Set exceptions to this policy with explicit ACL 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 the
number of ACLs you must maintain. This lower maintenance reduces the risk of
an 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 governed
by a specific access policy. You determine the access policy for an entire sub-tree
by 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 policy
impacts 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 by
individual users can be efficiently controlled by adding users to or removing
users from these groups.
Creating extended ACL actions and action groups
In this section, the word “action” has the same meaning as the word
“permissions,” used in previous sections.
46
IBM Tivoli Access Manager: Base Administrator’s Guide
Every Access Manager permission is defined as an action. Seventeen actions are
predefined for immediate functionality (see “Default Access Manager permissions
(actions)” on page 39). You can also define new actions for use by third-party
applications.
This section describes how to define action groups that serve as containers for an
expanded 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 group
v 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”.
primary action group
a A b B c gN TW
...
32
Bits set for:
group sales abNT
Figure 21. Primary action group
Access Manager supports a total of 32 action groups (including the primary action
group) for a total of 1024 individual actions.
multiple action groups
a A b B c gN TW
...
32
Figure 22. Multiple action groups
Creating a new action group
Use the pdadmin action group create command to create a new action group:
pdadmin> action group
pdadmin> action group
primary
test-group
pdadmin> action group
pdadmin> action group
create test-group
list
delete test-group
list primary
The default primary action group always appears in a group listing and cannot be
deleted.
Chapter 3. Using access control policies
47
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 delete
action groups.
Creating new actions in an action group
Use the pdadmin action create command to create a new action within an action
group.
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 action
list command and the Web portal manager.
action_type
Action category (used by Web portal manager to group
common action bits together). Default categories include Base,
Generic, and WebSEAL.
action_group_name
Action group where this new action belongs. If this argument
is not specified, the action is assigned to the “primary” action
group.
For example:
pdadmin>
pdadmin>
pdadmin>
pdadmin>
pdadmin>
action
action
action
action
create P Test-Action Special test-group
list test-group P Test-Action Special
delete P test-group
list test-group
Entering custom actions into ACL entries
As 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 action
groups other than the “primary” action group. Action strings that represent the
action 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]ab
v 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 and
b action bits have unique identities and can represent very different permissions
from the a and b action bits in the “primary” action group.
Example
Show action groups
48
IBM Tivoli Access Manager: Base Administrator’s Guide
pdadmin>
pdadmin> action group list
primary
test-group
List actions in action group “test-group”
pdadmin> action list test-group
P Test-Action Special
S Test-Action2 Special
List ACL policies
pdadmin> acl list
default-webseal
default-root
test
default-replica
default-management
Show details of ACL “test”
pdadmin> acl show test
ACL Name: test
Description:
Entries:
User sec_master Tcmdbva
Group ivmgrd-servers Tl
Any-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]PS
pdadmin> acl show test
ACL Name: test
Description:
Entries:
User sec_master Tcmdbva
Group ivmgrd-servers Tl
Any-other r
User kathy Tbr[test-group]PS
ACL policies and the protected object space
Container objects represent specific regions of the protected object space and serve
two 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 object
The 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.
Chapter 3. Using access control policies
49
The traverse permission
The traverse permission is a generic permission that applies throughout the
protected object space.
Operation
T
traverse
Description
When applied to a container object, allows the requester to
hierarchically pass through the container object on the way
to the requested resource object. It does not allow any other
type of access to the container object. Traverse is not
required on the requested resource object itself.
WebSEAL permissions
The following security considerations apply for the /WebSEAL container in the
protected 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/host
This subtree contains the Web space of a particular WebSEAL server. The following
security considerations apply for this object:
v The traverse permission is required for access to any object below this point
v 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/file
This is the resource object checked for HTTP access. The permissions checked
depend on the operation being requested.
WebSEAL permissions
The following table describes the permissions applicable for the WebSEAL region
of the object space.
Operation
50
Description
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 in
the WebSEAL object space.)
l
list
Required by the policy server to generate a directory
auto-list of the Web space.
g
delegation
Assigns trust to a WebSEAL server to act on behalf of a
client, and pass that request to a junctioned WebSEAL
server.
IBM Tivoli Access Manager: Base Administrator’s Guide
Management permissions
The Management region of the protected object space contains several
sub-management container objects that require specific sets of permissions:
v “/Management/ACL permissions” on page 51
v “/Management/Action permissions” on page 52
v “/Management/POP permissions” on page 53
v “/Management/Server permissions” on page 53
v “/Management/Config permissions” on page 54
v
v
v
v
v
“/Management/Policy permissions” on page 54
“/Management/Replica permissions” on page 54
“/Management/Users permissions” on page 55
“/Management/Groups permissions” on page 56
“/Management/GSO permissions” on page 56
The following security considerations apply for the /Management region of the
protected 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 permissions
This object allows administration users to perform high-level ACL management
tasks that can impact the security policy for the secure domain.
Operation
a
attach
Description
Attach ACL policies to objects; remove ACL policies from
objects.
acl attach
acl detach
c
control
Ownership of the ACL policy; allowed to create, delete and
modify entries for this ACL.
acl modify
d
delete
Delete an existing ACL policy. The ACL entry for this user
must 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 permission
must be in an entry of an ACL attached to /Management/ACL.
acl find
acl list
acl 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 the
above permissions. These permissions give the administrator powers to create new
ACL policies, attach ACLs to objects, and delete ACL policies.
Chapter 3. Using access control policies
51
An ACL administrator cannot modify an existing ACL unless there is an entry in
that ACL for the administrator containing the control (c) permission. Only the
owner of an ACL can modify its entries.
Note that the creator of a new ACL policy (m on /Management/ACL) becomes the
first entry in that ACL—with the TcmdbsvaBlNWA permissions set by default.
For example, if sec_master is an administrator entry in the default-management
ACL, with m permission, sec_master can create a new ACL policy. User
sec_master becomes the first entry in the new ACL, with TcmdbsvaBlNWA
permissions.
The control permission (c) gives sec_master ownership of the ACL and allows
sec_master to modify the ACL. User sec_master could then grant administration
permissions to other user entries in that ACL.
Ownership of the default-management ACL itself is given to both user sec_master
and group iv-admin by default.
The Control Permission (c)
The control permission is a powerful permission that gives you ownership of an
ACL policy. Control allows you to modify the entries in the ACL. This means you
have the power to create entries, delete entries, grant permissions, and take away
permissions.
The administrator who wants to delete an ACL from the list of ACL policies must
have 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 control
permission with great care because of its powerful ownership properties.
The control permission is only important in the /Management/ACL space.
/Management/Action permissions
This object allows administration users to manage custom actions and action
groups. Action tasks and associated permissions include:
Operation
d
delete
Description
Delete an existing action or action group.
action delete
action group delete
m
modify
Create a new action or action group.
action create
action 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 that
are part of the Access Manager family include, for example, WebSEAL (for Web
applications) and Access Manager for Business Integration (for messaging
applications).
52
IBM Tivoli Access Manager: Base Administrator’s Guide
Third-party applications can make calls to the authorizations service through the
authorization API. Two necessary steps required to integrate a third-party
application with the authorizations service include:
v Define the application’s object space
v Apply permissions on objects (resources) needing protection
The administrator of a third-party application object space can use the pdadmin
utility to define new permissions and actions. The administrator must have the m
and d Management/Action permissions to create and delete these
permissions/actions.
/Management/POP permissions
This object allows administration users to manage protected object policies. All
permissions must appear in entries for ACLs on /Management/POP. Action tasks and
associated permissions include:
Operation
a
attach
Description
Attach a POP to an object.
pop attach
pop detach
d
delete
Delete a POP.
pop delete
m
modify
Create POPs and modify POP attributes.
pop create
pop modify
v
view
Find and list POPs and show POP details.
pop find
pop list
pop show
B
Bypass TOD
Override the time-of-day POP attribute on an object.
/Management/Server permissions
The /Management/Server container object of the protected object space allows
administrators to perform server management tasks (when appropriate permissions
are set).
Server management controls are used to determine if a user has permission to
create, modify, or delete a server definition. Server definitions contain information
that 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 as
WebSEAL) or authorization server (pdacld) as part of the installation process. The
definition for a server is also deleted when the server is uninstalled.
Operation
s
server
Description
Replicate authorization database.
server replicate
v
view
List registered servers and display server properties.
server list
server show
Chapter 3. Using access control policies
53
Operation
t
trace
Description
Enable dynamic trace or statistics administration.
server task server_name trace
server task server_name stats
/Management/Config permissions
The /Management/Config container object of the protected object space allows
administrators to perform configuration management tasks (when appropriate
permissions are set).
The creation and deletion of server definitions happens automatically—the
installation administrator does not have to perform any special steps to create a
definition. However, the administrator must be granted modify (m) permission on
the /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.
Operation
m
modify
Description
Configuration into a secure domain.
svrsslcfg -config
svrsslcfg -modify
d
delete
Unconfiguration.
svrsslcfg -unconfig
/Management/Policy permissions
The /Management/Policy container object of the protected object space allows
administrators to authorize the policy get and policy set commands (when
appropriate permissions are set).
Operation
Description
v
view
Required for policy get operations.
m
modify
Required for policy set operations.
/Management/Replica permissions
The /Management/Replica container object of the protected object space controls the
replication of the authorization database. High-level controls on this object affect
the operation of the policy server and the Security Manager(s) in the secure
domain.
Replica management controls are used to determine what processes are allowed to
read or update the master authorization policy database in order for replication to
take place properly.
Controls and associated permissions include:
Operation
54
Description
v
view
Read the master authorization database.
m
modify
Authorize modification of the replica database(s).
IBM Tivoli Access Manager: Base Administrator’s Guide
All Access Manager servers which maintain a local replica of the authorization
database — this includes all resource managers and authorization servers — must
be granted view (v) permission on the /Management/Replica object. The replication
process requires that these processes be allowed to view and access entries out of
the master authorization policy database. The Access Manager installation
automatically grants read permission to any server requiring access to the
authorization policy database.
Access Manager currently does not use the modify (m) permission. The only way
to modify the master policy authorization database is through the Web portal
manager or the pdadmin utility. These tools are subject to other finer-grained
checks. The modify permission is intended to be used in the future when it is
possible to replicate the policy server.
/Management/Users permissions
This object allows administration users to manage user accounts. Action tasks and
associated permissions include:
Operation
d
delete
Description
Delete a user account.
user delete
m
modify
Modify user account details.
user
user
user
user
N
create
modify
modify
modify
modify
authentication-mechanism
account-valid
gsouser
description
Create a new user and optionally assign that user to one or
more groups. Import group data from the user registry.
user create
user import
v
view
List user accounts and show user account details.
user
user
user
user
user
user
W
password
list
list-dn
list-gsouser
show
show-dn
show-groups
Reset and validate a user password.
user modify password
user modify password-valid
The W permission allows password resets and is appropriate to give to helpdesk
administrators so they can assist users who have forgotten their passwords. This
permission allows an administrator to reset the forgotten password and then use
the user modify password-valid command to set a value of “no”. This action
allows the user to log and then forces the user to immediately apply a new
password.
Access granted by the /Management/Users object overrides any access restrictions
imposed by “delegated administration” policy ACLs under
/Management/Groups/group_name.
Chapter 3. Using access control policies
55
/Management/Groups permissions
This object allows administration users to manage groups and group membership.
Action tasks and associated permissions include:
Permission
Operation
delete
d
Description
Delete a group.
group delete
modify
m
Modify group descriptions. Remove one or more user
members of a group.
group modify description
group modify remove
create
N
Create a new group. Import group data from the user
registry.
group create
group import
view
v
List groups and show group details.
group
group
group
group
group
add
A
list
list-dn
show
show-dn
show-members
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 to
add existing users to your group. Use the user create command (which requires N
permission) to create new users and, optionally, place them in one or more existing
groups.
The capability of adding existing users to your group is powerful because the
owner of a group has control over all user members of the group. If you, as the
owner of the group, also have delete (d) permission, you can delete this user from
the entire secure domain.
/Management/GSO permissions
The /Management/GSO container object of the protected object space allows
administrators to perform Global Sign-On (GSO) management tasks (when
appropriate permissions are set).
Operation
56
Description
m
modify
rsrcgroup modify
rsrccred modify
v
view
rsrc list
rsrcgroup list
rsrccred list
rsrc show
rsrcgroup show
rsrccred show
N
create
rsrc create
rsrcgroup create
rsrccred create
(all the above commands also require m)
IBM Tivoli Access Manager: Base Administrator’s Guide
Operation
d
delete
Description
rsrc delete
rsrcgroup delete
rsrccred delete
(all the above commands also require m)
Object and object space permissions
These commands allows administration users to manage new objects and object
spaces. Action tasks and associated permissions include:
Operation
Description
b
browse
objectspace list
objectspace writefile
object list
object listandshow
(additionally requires v)
d
delete
objectspace delete
object delete
object modify set name
(additionally requires m)
m
modify
objectspace create
objectspace readfile
object create
object modify
v
view
object listandshow
(additionally requires b)
object show
Default administration ACL policies
The following default administration ACL policies are suggested starting points for
securing specific regions of the secure domain.
You can add entries for users, groups, any-other (any-authenticated), and
unauthenticated to provide a broader range of control and better meet the
requirements 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 power
to modify the ACL entries.
Default root ACL policy
Core entries for the default root ACL, default-root, include:
Group iv-admin
Any-other
Unauthenticated
Tcmdbva
T
T
The root ACL is very basic—everyone can traverse the object space, but cannot
perform 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 object
space for an individual user or group.
Chapter 3. Using access control policies
57
Consider the following entry in the root ACL:
user john -----------------
The consequence of this entry (no permissions) is that user john cannot even
traverse the root container object. This user cannot gain access at all to the
protected object space — regardless of any permissions granted lower down in the
tree.
You can apply this same approach to the WebSEAL object space. For example, if
you take away the traverse permission from a particular user at the /WebSEAL
container 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 policy
Core entries for the WebSEAL ACL, default-webseal, include:
Group iv-admin
Group webseal-servers
User sec_master
Any-other
Unauthenticated
Tcmdbsvarxl
Tgmdbsrxl
Tcmdbsvarxl
Trx
T
At installation, this default ACL is attached to the /WebSEAL container object in the
object space.
The group, webseal-servers, contains an entry for each WebSEAL server in the
secure domain. The default permissions allow the servers to respond to browser
requests.
The traverse permission allows expansion of the Web space as represented in the
Web portal manager. The list permission allows the Web portal manager to display
the contents of the Web space.
Default /Management ACL policy
Core entries for the Management ACL, default-management, include:
Group iv-admin
Group ivmgrd-servers
Any-other
TcmdbsvatNWA
Ts
Tv
At installation, this ACL is attached to the /Management container object in the
object space.
Default /Replica ACL policy
Core entries for the Replica management ACL, default-replica, include:
Group
Group
Group
Group
iv-admin
ivmgrd-servers
secmgrd-servers
ivacld-servers
Tcbva
m
mdv
mdv
Default /Config ACL policy
Core entries for the Config management ACL, default-config, include:
Group iv-admin
Any-other
Unauthenticated
58
IBM Tivoli Access Manager: Base Administrator’s Guide
TcmdbsvaN
Tv
Tv
Default /GSO ACL policy
Core entries for the GSO management ACL, default-gso, include:
Group iv-admin
Any-other
Unauthenticated
TcmdbvaN
Tv
Tv
Default /Policy ACL policy
Core entries for the Policy management ACL, default-policy, include:
Group iv-admin
Any-other
Unauthenticated
TcmdbvaN
Tv
Tv
Chapter 3. Using access control policies
59
60
IBM Tivoli Access Manager: Base Administrator’s Guide
Chapter 4. Using protected object policies
The Access Manager authorizations service makes decisions on requests for access
to protected objects in the secure domain. The decision can be based on two types
of policies:
v Access control list (ACL) policies
v Protected object polices (POP)
The purpose of a POP is to impose additional conditions on the operation
permitted by the ACL policy.
Examples of access conditions can include:
v Writing a report record to the auditing service
v Restricting access to a specific time period
This chapter discusses how protected object policies are configured and applied to
objects.
This chapter contains the following sections:
v “Introducing protected object policies (POP)” on page 61
v “Configuring the POP attributes” on page 63
v “Authentication strength POP policy (step-up)” on page 65
v “Network-based authentication POP policy” on page 68
v “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 or
no answer on a request to access a protected object and perform some operation on
that object.
POP policies contain additional conditions on the request that are passed back to
the Resource Manager (such as WebSEAL) along with the yes ACL policy decision
from the authorizations service. It is the responsibility of the Resource Manager to
enforce the POP conditions.
The following table lists the available attributes for an Access Manager POP:
Enforced by Access Manager Base
POP attribute
Description
pdadmin pop commands
Name
Name of the policy. This becomes the
pop_name in the pdadmin pop
commands.
create
delete
Description
Descriptive text for the policy. This
appears in the pop show command.
modify set description
Warning Mode
Provides administrators a means to test modify set warning
ACL and POP policies.
Audit Level
Specifies type of auditing: all, none,
successful access, denied access, errors.
modify set audit-level
61
Enforced by Access Manager Base
POP attribute
Description
pdadmin pop commands
Time-of-Day Access
Day and time restrictions for successful modify set tod-access
access to the protected object.
Extended attributes
Specifies supplemental data fields.
modify set attribute
modify delete attribute
list attribute
show attribute
Enforced by Resource Manager (such as WebSEAL)
POP attribute
Description
pdadmin pop commands
Quality of Protection
Specifies degree of data protection:
none, integrity, privacy.
modify set qop
IP Endpoint
Authentication Method
Policy
Specifies authentication requirements
for access from members of external
networks.
modify set ipauth add
modify set ipauth remove
modify 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 A
permissions in previous versions of Access Manager are now specified in
POP policies.
Creating and deleting protected object policies
Protected Object Policies (POP) operate in a similar way to ACL policies—you
create and configure a POP and then attach the POP to objects in the protected
object space.
POP policies are inherited in the same way as ACL policies. Both POP policies and
ACL policies are placed in the master authorization database which is controlled
by the policy server.
Create and list a POP
pdadmin> pop create pop_name
For example:
pdadmin> pop create test
pdadmin> pop list test
The new POP contains the following default settings:
pdadmin> pop show test
Protected object policy: test
Description:
Warning: no
Audit level: none
Quality of protection: none
62
IBM Tivoli Access Manager: Base Administrator’s Guide
Time of day access: sun, mon, tue, wed, thu, fri, sat:
anytime:local
IP Endpoint Authentication Method Policy
Any Other Network 0
Delete a POP
pdadmin> pop delete pop_name
For example:
pdadmin> pop delete test
pdadmin> pop list
pdadmin>
Modify and show a POP description
pdadmin> pop modify pop_name set description description
Note: Always enclose the description with double quotation marks when you use
more than one word.
For example:
pdadmin> pop modify test set description “Test POP”
pdadmin> pop show test
Protected object policy: test
Description: Test POP
Warning: no
Audit level: none
Quality of protection: none
Time of day access: sun, mon, tue, wed, thu, fri, sat:
anytime:local
IP Endpoint Authentication Method Policy
Any Other Network 0
Applying POP attributes to protected objects
POP policies are applied to objects in the same manner as ACL policies.
Attach a POP to an object
The 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 attached
pdadmin> pop find test /WebSEAL/serverA/index.html
Delete a POP
The 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 attributes
v Warning mode attribute
v Audit level attribute
v Time-of-day attribute
Chapter 4. Using protected object policies
63
Warning mode attribute
The purpose of the warning attribute is to allow a security administrator to debug
or troubleshoot the accuracy of the authorization policy set on the protected object
space.
When you set the warning attribute to yes, any action is possible by any user on
the object where the POP is attached. Any access to an object is permitted even if
the ACL policy attached to the object is set to deny this access.
Audit records are generated that capture the results of all ACL policies with
warning mode set throughout the object space. The audit log shows the outcome
of an authorization decision as it would have been made if the warning attribute
has been set to “no”. The administrator can, therefore, determine if policy is set
and enforced correctly.
pdadmin> pop modify pop_name set warning {yes|no}
For example:
pdadmin> pop modify test set warning yes
Audit level attribute
The audit level POP attribute is the replacement for the A ACL permission that
activated auditing in previous versions of Access Manager. The POP audit level
has the expanded ability to specify a level of auditing.
For example, if auditing is set to record unsuccessful events, you can use the
results to detect an unusual number of failed access attempts on a particular
resource.
Auditing records are written in a standard XML format that allows easy parsing to
extract 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 of
access to the protected object.
You can apply any combination of these three values. Use a comma as a separator
character when you specify more than one value.
For example:
pdadmin> pop modify test set audit-level permit, deny
Time-of-day attribute
The time-of-day (TOD) POP attribute allows you to place specific day and time
conditions on the access to a protected object. This type of condition might be
useful to limit access to information that regularly requires periods of inactivity for
modification and updates.
64
IBM Tivoli Access Manager: Base Administrator’s Guide
There is an ACL policy permission (B) that overrides the time-of-day conditions on
an object. This permission should only be used by a high level administrator who
needs 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 uses
the 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 on
specific resources. The authentication strength POP policy makes it possible to
control access to objects based on authentication method.
You can use this functionality, sometimes known as step-up authentication, to
ensure that users accessing more sensitive resources use a stronger authentication
mechanism. You might want this condition because of the greater threat of
improper access to certain resources.
For example, you can provide greater security to a junctioned region of the
protected object space by applying a step-up POP policy that requires a stronger
level of authentication than the client used when initially entering the secure
domain.
Authentication strength policy is set in the IP Endpoint Authentication Method
attribute of a POP policy.
Configuring levels for step-up authentication
The first step in configuring authentication-specific access is to configure the
supported authentication methods and determine the order in which these
authentication 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 client
last authenticated with the resource manager.
In some situations it may be necessary to enforce minimum “safe” levels of
authentication required to access certain resources. For example, in one
Chapter 4. Using protected object policies
65
environment, authentication by token passcode may be considered more secure
than authentication by username and password. Another environment might
require different standards.
Rather than forcing clients to restart their sessions with the resource manager when
they do not meet the required level of authentication, the step-up authentication
mechanism provides clients a second chance to reauthenticate using the required
method (level).
Step-up authentication allows resource managers to control the method in which
users access a protected resource. If step-up authentication is required because the
user has not authenticated with the sufficient method, then the access decision is
still permitted by the authorization engine but the resource manager is presented
with a required ″authentication level″ as an output of the authorization decision.
The resource manager can then decide how to further authenticate the user so as
to 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 is
entirely determined by the resource manager application. For all cases, the absolute
minimum acceptable method of authentication should be set as level 0 with more
secure methods being mapped to integral numbers in ascending order (1.x) from
there. In the WebSEAL implementation of step-up authentication, level 0 is
mapped to an unauthenticated user. Other authentication methods for WebSEAL
include password authentication and token card authentication. How these
authentication methods are mapped to an authentication level is configured by you
in the WebSEAL configuration file.
Refer to the IBM Tivoli Access Manager for e-business Release Notes for a discussion of
how to develop a resource manager that is enabled for step-up authentication
policy.
Applying step-up authentication policy
Step-up authentication is implemented via a POP policy placed on the objects
requiring authentication-sensitive authorization. You use the IP Endpoint
Authentication Method attribute of a POP policy.
The pdadmin pop modify set ipauth command specifies both the allowed
networks and the required authentication level in the IP Endpoint Authentication
Method attribute.
The configured authentication levels can be linked to IP address ranges. This
method is intended to provide management flexibility. If filtering users by IP
address is not important, you can set a single entry for anyothernw (any other
network).This setting will affect all accessing users, regardless of IP address, and
require them to authenticate at the specified level. This is the most common
method 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 not
otherwise specified in the POP. This method used to create a default entry which
could either deny all unmatched IP addresses or allow anyone access who can
meet the authentication level requirement.
66
IBM Tivoli Access Manager: Base Administrator’s Guide
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
Protected object policy: test
Description: Test POP
Warning: no
Audit level: none
Quality of protection: none
Time of day access: sun, mon, tue, wed, thu, fri, sat:
anytime:local
IP Endpoint Authentication Method Policy
Any Other Network0
The following authentication levels and their corresponding authentication
methods have been defined by the resource manager:
v authentication level 0 = unauthenticated
v authentication level 1 = user name/password
v authentication level 2 = user name/token passcode
Step-up authentication algorithm
WebSEAL 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 authentication
Access Manager step-up authentication and multi-factor authentication are two
different and distinct mechanisms for controlling access to resources. Access
Manager only provides step-up authentication functionality, as described in this
chapter.
Multi-factor authentication forces a user to authenticate using two or more levels
of authentication. For example, the access control on a protected resource can
require that the user authenticate with both user name/password and user
name/token passcode.
Access Manager step-up authentication relies on a preconfigured hierarchy of
authentication levels and enforces a specific level of authentication according to the
policy set on a resource. Step-up authentication does not force the user to
authenticate using multiple levels of authentication to access any given resource.
Instead, step-up authentication requires the user to authenticate at a level at least
as high as that required by the policy protecting the resource.
Step-up authentication example:
Configured authentication levels:
v authentication level 1 = user name/password
v 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:
Chapter 4. Using protected object policies
67
/WebSEAL/hostA/junction/applicationA
Under step-up authentication, user name/password (level 1) authentication is
required 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 a
user name and password, a prompt appears requesting user name and token
passcode information (the step-up). However, if the user initially logs in to
WebSEAL with user name and token passcode, access to applicationA is
immediate (assuming a positive ACL check).
Multi-factor authentication would require both level 1 and level 2 authentication
for access to applicationA.
Network-based authentication POP policy
The network-based authentication POP policy makes it possible to control access to
objects based on the IP address of the user. You can use this functionality to
prevent specific IP addresses (or IP address ranges) from accessing any resources in
your secure domain.
You can also apply step-up authentication configuration to this policy and require
a specific authentication method for each specified IP address range.
Network-based authentication policy is set in the IP Endpoint Authentication
Method attribute of a POP policy. You must specify two requirements in this
attribute:
v Authentication levels
For more information on authentication levels, see “Authentication strength POP
policy (step-up)” on page 65.
v Allowed networks
Specifying IP addresses and ranges
Now you must specify the IP addresses and IP address ranges permitted by this
POP policy.
The pdadmin pop modify set ipauth add command specifies both the network (or
network range) and the required authentication level in the IP Endpoint
Authentication 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 method
is 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 affects
all accessing users, regardless of IP address, and require them to authenticate at the
specified level.
Syntax:
pdadmin> pop modify pop-name set ipauth anyothernw level-index
68
IBM Tivoli Access Manager: Base Administrator’s Guide
Conversely, if you wish to ignore the authentication level and only want to allow
or deny access based on IP address, you can use level 0 for ranges that you want
to allow in and “forbidden” for ranges you want to deny.
The anyothernw entry is used as a network range that matches any network not
otherwise specified in the POP. This method used to create a default entry which
could either deny all unmatched IP addresses or allow anyone access who meet
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
Protected object policy: test
Description: Test POP
Warning: no
Audit level: none
Quality of protection: none
Time of day access: sun, mon, tue, wed, thu, fri, sat:
anytime:local
IP Endpoint Authentication Method Policy
Any Other Network0
Examples
Require users from IP address range 9.0.0.0 and netmask 255.0.0.0 to use level 1
authentication (“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) from
accessing the object:
pdadmin> pop modify test set ipauth anyothernw forbidden
Disabling step-up authentication by IP address
Syntax:
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 algorithm
The authorization engine uses the following algorithm to process the conditions in
a 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 limitations
The IP address used by the resource manager for enforcing the network-based
authentication policy should be the IP address of the originator of the connection.
If your network topology uses proxies, the address that appears to the resource
manager might be the IP address of the proxy server.
Chapter 4. Using protected object policies
69
In this case, the resource manager is not able to definitively identify the true client
IP address. You must be careful when setting a network-based authentication
policy that network clients can directly connect to the resource manager.
Quality of protection POP policy
The quality of protection POP attribute allows you to specify what level of data
protection is required when performing an operation on an object.
The quality of protection POP attribute is the replacement for the “P” and “I” ACL
permission bits that activated privacy and integrity requirements in previous
versions of Access Manager. This older implementation of quality of protection was
inefficient 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 protection
level. If the resource manager (such as WebSEAL) cannot guarantee the required
level 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
70
IBM Tivoli Access Manager: Base Administrator’s Guide
Chapter 5. Using Web portal manager
The Web portal manager is a Web-based interface used to manage security policy
for the secure domain. The Web portal manager provides management and
administration of users, groups, roles, permissions, policies, and application access
provisioning. The tasks that can be completed using the Web portal manager are
documented in the online help system. Use the help system as your first point of
reference when looking for Web portal manager task-based information. The
features outlined in this chapter include delegate administration and
self-registration.
This chapter contains the following sections:
v “Delegating administration using Web portal manager”
v “Delegating role administration” on page 73
v “Self-registration sample” on page 74
Delegating administration using Web portal manager
One of the most powerful features of the Web portal manager is a rich set of
delegated management services that enables a business to delegate user
administration, group and role administration, security administration, and
application access provisioning to participants (sub-domains) in the business
system. These sub-domains can further delegate management and administration
to trusted sub-domains under their control, thereby supporting multi-level
delegation and management hierarchy based on roles.
Delegate administration using Web portal manager provides an Access Manager
administrator the capability to create delegate user domains, create new users, add
existing users to additional domains, and assign various types of administrators to
the domains. These delegate administrators can then perform a subset of
administration functions, depending on their type, on the users in their assigned
domain. This concept of delegate user administration can be applied to all Access
Manager users so that a hierarchy of user domains is formed. In this hierarchical
arrangement, each Access Manager user can be managed only by the
administrators for the domain of which the user is member or by the
administrators for the super domains (explained later in this chapter). The actual
functions that administrators can perform depend on their assigned administrator
type.
An Access Manager administrator, such as sec_master, can create a number of
enterprise domains and assign one or multiple types of administrators to each
enterprise domain. The administrator for an enterprise domain can create new
users in the domain and add existing Access Manager users to the domain.
In addition to this user-related function, Access Manager administrators can create
new domains below the enterprise domain level (subdomains) and assign users to
be the administrators for these new domains (domain administrators).
Administrators of the new domains can then create new users in their own
domain.
The Access Manager administrator for the enterprise domain (the domain’s
superdomain) also has authority to administer the domain. Access Manager
71
administrators can create and manage as many domains under their authority as
necessary to fulfill their unique business needs
Note: An enterprise domain is basically the top-level domain, and any domain
created below an enterprise domain level is just called a domain.
As an example of this type of multiple domain administration in Figure 23, an
Access Manager administrator can create enterprise domains A and B and assign
an administrator for each domain. The domain administrator for enterprise domain
B can create new users P, Q. An Access Manager administrator can create domains
C and D below the enterprise domains A and B, and assign domain administrators
to C and D. The Access Manager administrator can then create domain E below
domain D, and assign a domain administrator to E. The domain administrator for
domain E can then create new users X, Y, and Z within domain E. Because a
domain administrator for a domain can also administer that domain’s subdomains,
both the domain administrators for domain D and the domain administrator for
enterprise domain B can create users (or perform other administrative functions)
for domain E.
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
For each delegate user domain (including the enterprise domain), predefined
administrator types can be assigned in that domain. The following are the various
administrator types and the set of administrative functions that can be performed
by 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 all
delegate administration functions.
v Domain Administrator. The domain administrator can perform administrative
functions for the users in their domain. Domain administrators can create new
users/administrators in their own domain, and assign existing domain users to
be an administrator (of any type except domain administrator) for the domain.
72
IBM Tivoli Access Manager: Base Administrator’s Guide
v Senior Administrator. A senior administrator has the same authority as a
domain administrator, except that a senior administrator cannot assign
additional administrators.
v Administrator. An administrator has the same authority as a senior
administrator, except that an administrator cannot create new domain users. An
administrator can modify an existing user’s properties.
v Support Administrator. A support administrator serves the user in a help-desk
role and is able to view users’ properties, change users’ passwords, and modify
Is Password Valid? flags for users.
The delegate user administration tool enforces the administrative functions that can
be performed with each administrator type. When an administrator logs in,
administrative functions become available in accordance with that user’s
administrator type.
Delegating role administration
Another part of the delegate administration system of the Web portal manager is
role administration. To successfully deploy Access Manager, a security policy that
regulates access to, and the actions that can be performed on, objects must be
defined. Execution of this policy is usually difficult because the security policy is
often defined by high-level members of an organization with an emphasis on
global security issues. The policy then must be put into action by local members of
the organization, who see the lower-level details and implementation concerns.
Often these two groups have similar goals for overall organizational security, but
interconnecting these two disparate points of view is challenging. Role-based
administration provides an enhanced ability for organizational security to meet the
requirements 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 a
specific job requirement. When this definition is contrasted against to the access
control list (ACL) model of Access Manager, a role becomes a list of one or more
pairs of objects and one or more access permissions that applied to the object. For
example:
v object 1: permission 1
v object 2: permission 2, 3, and 4
v object 3: permission 5
In order for a role to be used it must be activated. A role is activated when an
Access Manager administrator enables its definition in the Access Manager
namespace. After a role is activated and a user is assigned to the role, the user has
permission 1 for object 1, permission 2, 3, and 4 for object 2, permission 5 for
object 3. The access permissions for these objects allow the user to access the
objects, and therefore perform the job responsibility defined by the role. For
example, an “accountant role” can be defined to consist of the following two pairs
of objects and permissions:
v payroll check object: create/modify/delete
v reimbursement request object: approve
When this role is activated and an employee in the accounting department is
assigned to this role, that employee is able to create, modify, or delete a payroll
check and approve a reimbursement request, thus performing the job that an
accountant is expected to perform.
Chapter 5. Using Web portal manager
73
To successfully administer roles, an administrator must be able to perform three
types of tasks:
v Role creation
v Role assignment
v Role activation
Role creation involves defining a role so that it has a list of one or more pairs of
Access Manager objects and permissions that can be applied to the objects. When a
role is created in Web portal manager, an Access Manager group is created to
represent the role. A corresponding group object in the management object space is
also created. The object/permissions pair information for the role is stored in the
extended attributes associated with the group object. Only an Access Manager
administrator 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 access
permissions on the objects defined in the role. This function reduces the workload
involved in maintaining user-permission-object relationships, because role
assignment is separated from object/access permission management. When a user
is assigned to a role in Web portal manager, the user is added as a member of the
group that represents the role. Domain administrators, senior administrators, and
administrators 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 a
user is assigned to that role, the user does not have access permissions for the
objects defined in the role until the role is activated. When a role is activated in
Web portal manager, an ACL entry that contains the group that represents the role
and the access permissions defined in the role are added to the ACL for each object
defined in the role. Because a user has been added to the group when the user is
assigned to the role, that user has permissions to access the objects only after a role
is 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 a
role to a domain. When a role is created, it can be assigned to an enterprise
domain. Domain administrators can in turn assign any of the roles within that
domain to any subdomain. Once a role is assigned to a subdomain, an
administrator for that subdomain can assign any subdomain users to that role. This
process of assigning roles to subdomains can be repeated as needed so that roles
can be made available to the appropriate users. Role assignment to an enterprise
domain can be performed only by the Access Manager administrator. Domain
administrators can assign a role to their subdomains.
Self-registration sample
You can customize the Web portal manager to allow end-users to perform self
registration. Self registration is the process by which a user can enter in required
data and become a registered Access Manager user, without the involvement of an
administrator. One possible scenario for implementing self registration, is where
users use a Web browser to view a self-registration Web Page. On this Web page,
the user enters specific identification information (either company-specific or
user-specific) with an Access Manager user ID and password. The identification
information provided by the user is then validated and the user is created in the
Access Manager registry.
74
IBM Tivoli Access Manager: Base Administrator’s Guide
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 or
Active 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 Base
Installation Guide.
2. Use the pdjrtecfg utility to configure the JRE. Enter the following from a
command 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. For
example, 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 Runtime
Environment, use the Java SvrSslCfg utility as follows:
Note: For more information about the Java SvrSslCfg utility, see the IBM Tivoli
Access 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 user
shortname.
sec_master_password
Identifies the sec_master password.
pdmgrd_host
Identifies the Access Manager policy server host system.
pdacld_host
Identifies the Access Manager authorization server host
machine.
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 default
location of the configuration file URL is as follows:
temporary_directory/pdjrte/pdjrte.properties
The default location of the configuration file URL is specified in
the pdwpm.conf file, located in the Access Manager etc
directory.
Note: You must edit the pdwpm.conf file to change the
configuration file URL and restart the WebSphere
Application Server.
Chapter 5. Using Web portal manager
75
keystoreFile_URL
Indicates the location of the keystore file URL. The default
location of the keystore file URL is as follows:
temporary_directory/pdjrte/pdjrte.ks
4. The self-registration sample can be accessed from the following URL:
https://localhost/register
where localhost is the machine where IBM HTTP Server and WebSphere are
running.
76
IBM Tivoli Access Manager: Base Administrator’s Guide
Chapter 6. Delegating administration tasks
Access Manager allows high-level administrators to delegate responsibilities for
managing the secure domain to lower-level administrators. This capability is vital
to 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 78
v “Delegating group management” on page 81
v “Managing delegated administration policy” on page 86
77
Delegating object space management
The distribution of administration responsibilities within a secure domain is called
management delegation. The need for management delegation generally arises
from the growing demands of a large site containing many distinct departmental
or resource divisions.
Typically, a large object space can be organized into regions representing these
departments or divisions. Each distinct region of the domain is usually better
organized and maintained by a manager who is more familiar with the issues and
needs of that branch.
In a secure domain, the sec_master account for LDAP is initially the only account
with administration permission. As sec_master, you can create management
accounts and assign to these accounts appropriate controls for specific regions of
the object space.
Structuring the object space for management delegation
Structure your object space to contain distinct regions, or branches, where
sub-management responsibilities—specific to that branch—can be carried out.
In the example below, both the Engineering and Publications regions of the object
space require separate management control. Control of these regions begins with
the root of each region and extends to all objects below.
/WebSEAL
Engineering Server
Marketing Server
Resources
Publications
Object Space
Figure 24. Structuring the object space for management delegation
Default administration users and groups
At installation, Access Manager provides several important administration groups.
By default, these users and groups are given special permissions to control and
manage all operations in the secure domain. (This default security policy is defined
by the ACLs created during installation.)
The following sections detail the specific roles assigned to each of these users and
groups at installation time. The administrator can customize these privileges at a
later time to accommodate changing management policies.
user sec_master (LDAP)
This user represents the administrator of the secure domain who is granted
complete rights for all operations within the secure domain.
78
IBM Tivoli Access Manager: Base Administrator’s Guide
This policy can be modified as the object space grows by delegating management
permissions to other users and possibly revoking certain (or all) permissions from
sec_master.
group iv-admin
This group represents the administrator group. Like sec_master, all members of
this group are considered administrators of the secure domain by the default
policy. All default ACLs grant user sec_master and group iv-admin exactly the
same permissions.
You can easily place users into an administration role by adding them to the
iv-admin group. The danger with this procedure is that once a user becomes a
member of this group (with the default ACLs), that user has full rights to do
everything on any object in the entire namespace.
The default policy for this group can be changed by delegating management
permissions to other users and revoking some or all management permissions from
group iv-admin.
group ivmgrd-servers
This group contains the policy server. Access Manager requires that exactly one
policy server exist in the secure domain. Therefore, this group only contains that
one entry.
Since most management requests made by the console are executed via the policy
server to the target server, the policy server must have permission to perform the
request at the target server. For this reason, this group is granted server
administration permission (s) in the default management ACL, and list (l)
permission throughout the Web space.
group webseal-servers
This group contains all the WebSEAL servers in the secure domain. The default
WebSEAL ACL grants these servers the complete set of HTTP-specific permissions
and the delegation permission. This policy allows all WebSEAL servers to junction
to all other WebSEAL servers. A modification of this policy could grant these
permissions on a server-by-server basis.
Creating administration users
You can create administration accounts with varying degrees of responsibility.
Responsibility is delegated to administrators through strategically place
administration ACLs. The following list illustrates possible administration roles:
v ACL administration responsibilities
The ACL administrator can control all, or part, of a protected object namespace
region, depending on where the administration ACL is placed. The
administrator’s ACL entry could contain the b, a, and T permissions, plus any
other permissions appropriate for operations on objects in that region.
The administrator can use the Web portal manager to attach (a) ACLs to objects
in the designated namespace using the existing set of ACL templates. This
administrator does not have permissions to create, modify, or delete ACL
templates.
v ACL policy responsibilities
The ACL policy administrator should be responsible for controlling the creation
and modification of all ACL templates used in the secure domain. The ACL
policy 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 creator
of a new template, the administrator becomes, by default, the first entry in the
new ACL template, with abcT permissions. The control permission (c) effectively
gives the administrator ownership of the ACL, and therefore the ability to
modify 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 affecting
the Access Manager servers.
v Authorization Action responsibilities
This administrator is granted d and m permissions on the /Management/Action
object. This administrator can create or delete all permissions created for
third-party applications.
Example administration ACL templates
The following example illustrates how a user gains administration rights.
v The following ACL on /WebSEAL gives administration rights to user adam:
user sec_master
group iv-admin
group webseal-servers
group ivmgrd-servers
user adam
any-other
unauthenticated
abcTdmlrx
abcTdmlrx
gTdmlrx
Tl
abcTdmlrx
Trx
Trx
Example: Management delegation
A large object space might require many administration users to manage a variety
of sub-branches. In this scenario, the ACLs for the directories on the path to each
of 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 of
entries representing all these administration accounts.
The following technique resolves the problem of numerous ACL entries for
administrators:
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. User
pub-manager is a member of this group and therefore, has the necessary traverse
permission required to navigate to the Publications directory.
80
IBM Tivoli Access Manager: Base Administrator’s Guide
The Publications directory includes the user pub-manager entry in its ACL. Since
pub-manager is the delegated administrator of this branch (with the appropriate
permissions), pub-manager can remove the iv-admin group account (and any
other ACL entries) from the Publications ACL to gain total control over that
branch of the Web space.
/WebSEAL/
server
user sec_master
group iv-admin
-abc---Tdm----lrx
--b----T---------
/Marketing
user sec_master
group iv-admin
-abc---Tdm----lrx
--b----T---------
= explicit ACL
/Resources
= inherited ACL
/Publications
group iv-admin
...
user pub-manager
--b----T---------abc---Tdm----lrx
Figure 25. Management Delegation Example
Delegating group management
Access Manager allows high-level administrators to delegate responsibilities for
managing the secure domain to lower-level administrators. This capability is vital
to successful management of very large domains composed of numerous
departments that contain high numbers of groups, users, and resources.
In order to manage a large or complex set of users, you can delegate the
management of specific groups of users to lower-level administrators. When an
administrator is given policy management control of a group, that administrator
has 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 and
controls granted to an otherwise typical user. An administrator of delegated duties
is 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.
Chapter 6. Delegating administration tasks
81
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 objects
By default, the /Management region of the Access Manager object space has a
Groups container object that you can use to organize the hierarchy of groups in
your secure domain.
Container objects are structural designations that allow you to organize the object
space into distinct and hierarchical functional regions. Group container objects
allow you to define distinct categories of group types. You create actual groups
within 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}
Argument
Description
obj-name
Full path and name of the new group container object. Path must
begin with /Management/Groups.
description
Any text string describing the object. This information appears in the
object show command.
type
The type argument identifies the specific graphical icon associated
with this object and displayed by the Web portal manager. Types
range from 0-17 (see table below). Type 14 is appropriate for
container objects.
ispolicyattachable
Determines whether you can attach an ACL policy to this object.
Object types
0
1
2
3
4
5
6
7
8
–
–
–
–
–
–
–
–
–
unknown
secure domain
file
executable program
directory
junction
WebSEAL server
unused
unused
9 – HTTP server
10 – non-existent object
11 – container object
12 – leaf object
13 – port
14 – application container object
15 – application leaf object
16 – management object
17 – unused
For example:
pdadmin> object create /Management/Groups/Travel “Travel
Container Object” 14 ispolicyattachable yes
82
IBM Tivoli Access Manager: Base Administrator’s Guide
/Management
–
–
/Management/Groups
+
/Management/Groups/Travel
Figure 26. Group container object
You can also use the pdadmin group create command to create a group container
object. See “Creating groups”.
Creating groups
Use 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 not
currently exist, it is automatically created:
pdadmin> group create group_name dn cn [group_container]
Argument
Description
group_name
Name of the new group object.
dn
Distinguished name for the new group.
cn
Common name for the new group.
group_container
Relative path name for the group container object where this new
group should be located. If no group container object is specified, the
group 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 a
relative path name for the group_container variable.
v The group create command does not allow you to create a group container
object without a group.
v To add a new group to the object space, the administrator must have create
permission (N) on the ACL governing the associated group container object.
If no group container object is specified, the administrator ACL entry (with the
create 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. You
must 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 groups
that reside under the container object. The container object and its groups are
now 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 group
from the object space (but not LDAP) and then import the group to a new
location (users in the group are maintained).
For example:
Chapter 6. Delegating administration tasks
83
pdadmin> group create group1 “cn=travel,c=us” Group1 Travel
pdadmin> group create group2 “cn=travel,c=us” Group2 Travel
/Management
–
–
/Management/Groups
–
/Management/Groups/Travel
+
/Management/Groups/Travel/group1
+
/Management/Groups/Travel/group2
Figure 27. Creating new groups under a specific group container
ACL policies affecting group management
Authorization to control a group of users is obtained by attaching an appropriate
ACL to the group object or group container object.
The ACL, constructed and attached by a higher-level administrator, should contain
the appropriate permissions for the actions that must be performed by the
delegated administrator of that group (or groups).
If the group resides under the /Management/Groups section of the object space, the
ACL must be attached to /Management/Groups or the group itself.
If the group resides under a group container object, the ACL must be attached to
the group container object or the group itself. If you attach the ACL to the
/Management/Groups container object, the ACL would impact all other group
container 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 group
v What actions can be performed on the group and its users
For example, in Figure 27, an ACL on /Management/Groups/Travel defines
permissions to control both group1 and group2.
The following operations and ACL permissions are appropriate for group
management:
Operation
Permission
create (a new group) import (group data from the user registry) N (create)
84
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)
IBM Tivoli Access Manager: Base Administrator’s Guide
You can use the appropriate pdadmin utility commands, or the Web portal
manager, 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 now
has control of that user (and might share control of the user with administrators
of other groups where that user is a member).
This permission is best granted only to high-level administrators who are
responsible for user and group organization and corporate policy.
ACL policies affecting user management
The group administrator can perform an action on a user if they have the
appropriate permission defined on any of the groups where that user is a member.
The following operations and ACL permissions are appropriate for user
management:
Operation
Permission
create (a new user within one or more specified
groups) 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 portal
manager, 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 group1
user 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/Users
container 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 administrator
has the appropriate permission defined in any group where that user is a
member.
Chapter 6. Delegating administration tasks
85
v If a user is not a member of any group, an administrator must have appropriate
permissions in an ACL on /Management/Users to perform operations on that
user.
v The password (W) permission is appropriate for helpdesk operators who must
assist users who have lost their passwords.
The operator can reset the lost password to some known value, and then set
user modify password-valid (pdadmin) to “no”. This action would force the
user 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 view
permission is used to filter the output of these commands. If the user does not
have view permission on a group or user that is being returned by the
command, that group or user is filtered from the output.
Managing delegated administration policy
The previous two sections described separately how to delegate administration of
security policy for protecting resources in your secure domain and also how to
delegate management of the users who access those resources. These two
individual aspects of delegated administration often need to be combined to
establish a complete delegated administration security policy.
Great care, however, must be taken when doing this. In particular, you must be
careful which permissions you grant in combination with each other.
For example the A permission should never be granted together with the m or W
permissions except to the most powerful and trusted administrators (and maybe
not at all). The consequence of granting both A and W to an administrator is that
the administrator can add any user to the group for which they have these
permissions 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 malicious
administrator 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 except
that an administrator with both of these permissions can only use this combination
to disable any account.
When defining a complete delegated administration policy, these constraints imply
a certain structure and use to your user groups.
You must establish groups that you use to delegate user management tasks—such
as 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 or
invalidate passwords, and view users they are responsible for managing. These
groups are used only for delegating user management and should not be used for
protecting other resources in the secure domain.
You must also establish groups that you use to delegate management of security
policy for protected resources within the secure domain. Administrators controlling
security policy for these groups should have the A and v permissions but none of
the N, d, m or W permissions. These groups are used to control access to the real
resources that need protecting.
Example:
86
IBM Tivoli Access Manager: Base Administrator’s Guide
Suppose you have a Web space accessible to the internet with resources that
should be:
v publicly accessible
v accessible only to customers and employees
v 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 to
everything in the Web space. An ACL at customers allows access to customers and
sales people and another ACL at sales allows access only to sales people. These
ACLs might look like:
public-access
user sec_master
any-other
unauthenticated
customer-access
user sec_master
group customers
group sales
any-other
unauthenticated
sales-access
user sec_master
group sales
any-other
unauthenticated
-abc---Tdm----lrx
-------T------lrx
-------T------lrx
-abc---Tdm----lrx
-------T------lrx
-------T------lrx
---------------------------------abc---Tdm----lrx
-------T------lrx
---------------------------------
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 customers
and grant them access to the customers portion of the Web space. Only
administrators (members of the “sales-admin” group) are allowed to manage
accounts for new sales people.
The following group structure implements this policy:
/Management/
Groups/
sales
<- ACL sales-admin
sales-users
<- ACL sales-users-admin
customers
<- ACL customers-admin
customers-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 and
remove users from this group. The view (v) permission is also useful to
administrators to allow them to view the group membership and the users in the
group.
Chapter 6. Delegating administration tasks
87
sales-admin
group super-admin Tabc
group admin
TAv
The sales-users-admin ACL. by attachment to the sales-users group, controls who
can manage users who are members of the sales-users group (this is the
“sales-admin” group again).
sales-users-admin
group super-admin Tabc
group admin
TNWdmv
Similarly the customers-admin ACL is used to administer membership of the
customers group which, in turn, is used to control access to the customers-only
portion of the Web space.
customers-admin
group super-admin Tabc
group 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 sales
group again). We also allow members of the “sales-admin” group to manage
customers.
customers-users-admin
group super-admin
group sales
group admin
Tabc
TNWdmv
TNWdmv
Notice in each ACL, a super-admin group entry is granted attach, browse, and
control permission. Members of the super-admin group are responsible for
administering these ACLs.
88
IBM Tivoli Access Manager: Base Administrator’s Guide
Chapter 7. Managing Access Manager servers
This chapter provides detailed information for performing general administration
and configuration tasks on the Access Manager servers. The configuration files that
support each server are also discussed.
This chapter contains the following sections:
v “Introducing the Access Manager servers” on page 89
v “Starting and stopping Access Manager servers” on page 97
v “Starting and stopping servers on Windows systems” on page 98
v “Automating server startup at boot time” on page 99
v “Policy server administration” on page 99
Introducing the Access Manager servers
Access 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 and
maintains location information about other Access Manager servers in a secure
domain. The policy server typically requires very little administration or
configuration.
The authorization server (pdacld) allows third-party applications to make
authorization calls (via the authorization API) to the Access Manager security
service. The authorization server typically requires very little administration or
configuration.
WebSEAL (webseald) is a high performance, multi-threaded Web server that
applies fine-grained security policy to the protected Web object space. WebSEAL
can provide single signon solutions and incorporate back-end Web application
server resources into its security policy.
Server dependencies
Important 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 replicated
authorization database.
89
Web Portal
Manager
Master
Authorization
Database
Policy Server
(pdmgrd)
WebSEAL
(webseald)
Replica
Authzn
Database
Authzn Server
(pdacld)
Replica
Authzn
Database
User
Registry
Figure 28. Access Manager server components
Introducing server administration tools
The 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 91
v “Using the trace utility to capture Base actions” on page 94
When troubleshooting, these command line utilities can provide status information
and control of individual servers.
Using the pd_start utility to start and stop servers
Administrators can use the pd_start utility to manually stop, start, restart servers,
and to display server status. For more information, see “Starting and stopping
Access Manager servers” on page 97.
Using the pdacld_dump utility to dump file content
The 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 the
database file, pdacld_dump examines the content and attempts to ensure that the
database is valid. After examining the database, the utility displays a short
summary of the database file.
The pdacld_dump utility can also be used to copy and construct a new database
file. While pdacld_dump is examining the content of the database file, it can
construct a new database file, skipping database entries that it believes are corrupt
or 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 the
PDAcld authorization server except that it can dump the content of a pdacld
database file.
Running the pdacld_dump utility: The pdacld_dump utility is located in the
following directory of the Access Manager Base installation:
90
IBM Tivoli Access Manager: Base Administrator’s Guide
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 with
the 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 the
database
pdacld_dump
[–r]
Constructs a new database with the path and db_filename containing valid
entries 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 information
The purpose of the pdinfo utility is to gather and store current information about
your Access Manager computer system. You can send the resulting tar file to
technical support personnel to help them assist you in a problem-solving or
troubleshooting situation. The pdinfo utility operates in an Access Manager
environment on the following platforms: HP-UX, Solaris, AIX, Linux, and
Windows NT/2000.
The pdinfo utility is part of the Access Manager Base (PDRTE) installation. Other
Access Manager components, such as WebSEAL, contain embedded Perl scripts
that are executed automatically when you run the pdinfo utility, and provide the
appropriate system information for that component.
The pdinfo.cfg configuration file allows you to customize the operation of the
pdinfo utility.
Running the pdinfo utility: The pdinfo utility is located in the following
directory 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, use
a full path name. When you run the pdinfo utility, you are prompted to provide
the full path name for the system information output file. For example (UNIX):
# cd /opt/PolicyDirector/sbin
# ./pdinfo
Please enter the name (full path) of the desired output file
eg. /tmp/output.tar.gz:
Technical notes:
v In a UNIX environment, you must be logged in as root to successfully run the
pdinfo 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 the
pdinfo 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 the
following 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 pdinfo
utility invokes other system commands to gather information. This file collects
any errors resulting from these system commands.
v Access Manager configuration, audit, and log files
All standard Access Manager configuration, audit, and log files are collected in
the tar file.
v Access Manager server core dumps
The final task of the pdinfo utility is to kill the Access Manager servers (except
PDRTE) 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. By
default, the pdinfo utility kills all Access Manager servers in order to
record core dump files. Refer to the discussion of $EXECUTE_BLADES
below for further information.
Using the pdinfo.cfg configuration file: You can customize the information
gathered by the pdinfo utility using the pdinfo.cfg configuration file.
The pdinfo.cfg configuration file is located in the following directory:
UNIX:
92
IBM Tivoli Access Manager: Base Administrator’s Guide
/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 system
information output file and the pdinfo-specific error file. The default file names
include:
$OUTPUT_FILE = "systeminfo.txt";
$ERROR_FILE = "error.log";
Access Manager component reporting scripts: This section specifies the location of
reporting 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 additional
reporting scripts (written in Perl 5.6) placed in the /etc/pdinfo/ directory of
any Access Manager component (“blade”). The parameters described above
are no longer used by the utility.
Information types: You can specify the type of information gathered by the pdinfo
utility. To enable specific information gathering, set the appropriate parameter
equal to “1”. To disable specific information gathering, set the appropriate
parameter equal to “0” or, alternatively, comment out the parameter line.
For example:
$GATHER_MACHINE_INFO =
$GATHER_NETWORK_INFO =
$GATHER_PROCESS_INFO =
$GATHER_INSTALLED_INFO
$GATHER_PD_INFO = 1;
$EXECUTE_BLADES = 1;
1;
1;
1;
= 1;
Parameter descriptions:
v Machine information ($GATHER_MACHINE_INFO) gathers the machine name,
operating system version, system architecture, processors, RAM, virtual memory
statistics, and disk space.
v Network information ($GATHER_NETWORK_INFO) gathers information about
interfaces, ARP cache, routing, and open sockets.
v Current processes information ($GATHER_PROCESS_INFO) gathers information
about current processes running on the system.
v Installed software information ($GATHER_INSTALLED_INFO) gathers
information about software currently installed on the system.
v Access Manager information ($GATHER_PD_INFO) gathers information about
the current state of Access Manager Base.
v Access Manager component information ($EXECUTE_BLADES) runs the
reporting scripts for other configured Access Manager components.
This is the section of the pdinfo utility where the Access Manager servers are
killed in order to record the resulting core dump files. The kill operation occurs
Chapter 7. Managing Access Manager servers
93
within the Perl script for each server/”blade”. You can therefore control the kill
operation on a per-server basis by modifying the appropriate script for that
server.
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 BEING
GATHERED, 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 actions
The trace utility allows you to capture information about error conditions and
program control flow in Access Manager Base. This information is stored in a file
and used for debugging purposes. The trace utility is provided primarily to assist
support personnel in diagnosing problems occurring with the functioning of the
Access 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 with
the assistance of technical support personnel.
Note: Use trace with caution. It is intended as a tool to use under the direction of
technical support personnel. Messages from trace are sometimes cryptic, are
not 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
94
Enable the trace level and trace message destination for a component and
its subordinates
IBM Tivoli Access Manager: Base Administrator’s Guide
trace show
Show the name and level for all enabled trace components or for the
specified component
trace list
List all available trace components
Enable trace: Use the pdadmin trace set command to enable the gathering of trace
information for the specified component and level.
trace set component level [log-agent]
Argument
Description
component
The trace component name. Required. WebSEAL-specific components
are prefixed with “pdweb”.
level
Reporting level. Required. The level argument specifies the amount of
detail gathered by the trace utility. The range is 1 to 9. Level 1 specifies
the most detailed output and level 9 specifies the least detailed output.
logagent
Optionally specifies a destination for the trace information gathered for
the specified component. Refer to the “Using event logging” chapter of
the IBM Tivoli Access Manager Base Administrator’s Guide for complete
configuration details.
Show enabled trace components: List all enabled trace components or a specific
enabled component. If a specified component is not enabled, no output is
displayed.
trace show [component]
Example:
pdadmin> server task webseald-instance trace set pdweb.debug 2
pdadmin> server task webseald-instance trace show
pdweb.debug 2
List all available trace components: List the specified component or all components
available 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 component
at level 2, and directs the output to a file, using the event logging mechanism to
specify 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:17
GET /test/index.html HTTP/1.1
Host: bevan
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:0.9.4)
Gecko/20011128 Netscape6/6.2.1
Accept: 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.1
Accept-Language: en-us
Accept-Encoding: gzip, deflate, compress;q=0.9
Chapter 7. Managing Access Manager servers
95
Accept-Charset: ISO-8859-1, utf-8;q=0.66, *;q=0.66
Keep-Alive: 300
Connection: keep-alive
--------------------------------------------------/src/wand/wand/log.c:277: -------------- PD ===> BackEnd -------------Thread_ID:17
GET /index.html HTTP/1.1
via: HTTP/1.1 bevan:443
host: mokum.santacruz.na.tivoli.com
user-agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:0.9.4)
Gecko/20011128 Netscape6/6.2.1
accept: 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.1
accept-language: en-us
accept-charset: ISO-8859-1, utf-8;q=0.66, *;q=0.66
accept-encoding: gzip, deflate, compress;q=0.9
keep-alive: 300
connection: close
--------------------------------------------------/src/wand/wand/log.c:277: -------------- PD <=== BackEnd -------------Thread_ID:17
content-type: text/html
date: Mon, 25 Mar 2002 19:48:32 GMT
content-length: 7017
etag: "0-1b69-3b688e48"
last-modified: Thu, 02 Aug 2001 00:18:32 GMT
server: IBM_HTTP_SERVER/1.3.19 Apache/1.3.20 (Win32)
connection: close
accept-ranges: bytes
--------------------------------------------------/src/wand/wand/log.c:277: -------------- Browser <=== PD -------------Thread_ID:17
HTTP/1.1 200 Document follows
content-type: text/html
date: Mon, 25 Mar 2002 19:48:32 GMT
content-length: 7017
etag: "0-1b69-3b688e48"
last-modified: Thu, 02 Aug 2001 00:18:32 GMT
server: IBM_HTTP_SERVER/1.3.19 Apache/1.3.20 (Win32)
connection: close
accept-ranges: bytes
---------------------------------------------------
Server configuration files
You can use the server configuration files to customize the operation of each
Access Manager server:
Server Name
Configuration File
Configuration File Location
Policy server
ivmgrd.conf
UNIX: install_path/etc/ivmgrd.conf
Windows: install_path\etc\ivmgrd.conf
Authorization server
ivacld.conf
UNIX: install_path/etc/ivacld.conf
Windows: install_path\etc\ivacld.conf
WebSEAL
webseald.conf
UNIX: /opt/pdweb/etc/webseald.conf
Windows: C:\Program Files\Tivoli\PDWeb\etc\webseald.conf
96
IBM Tivoli Access Manager: Base Administrator’s Guide
Access Manager Base program files are installed in the following default
directories:
UNIX: /opt/PolicyDirector/
Windows: C:\Program Files\Tivoli\Policy Director\
This guide uses the install_path variable to represent this root directory. All relative
path names expressed in the Access Manager configuration files are relative to this
root directory.
Configuration files are ASCII text-based and can be edited using a common text
editor. The configuration files contain parameter entries in the following format:
parameter=value
The initial installation of Access Manager establishes default values for most
parameters. Some parameters are static and never change; others can be modified
to customize server functionality and performance.
Note: After editing a configuration file, you must stop and restart the Access
Manager server before the changes take effect.
Each file contains sections, or stanzas, containing one or more parameters for a
particular configuration category. The stanza labels appear within brackets
[stanza-name].
For example, the [ssl] stanza in ivmgrd.conf defines the SSL configuration
settings for the policy server. The stanza [ldap] defines configuration required by
the 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 files
to ensure their integrity.
Starting and stopping Access Manager servers
Starting and stopping servers on UNIX systems
Server processes are normally enabled and disabled through automated scripts that
run at system startup and shutdown.
In a UNIX environment, you can also use the pd_start script to manually start and
stop the server processes. This technique is useful when you need to customize an
installation or when you need to perform troubleshooting tasks. You can only run
scripts on the local machine. Use the Web portal manager to stop and start servers
remotely.
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 the
following directory:
/opt/PolicyDirector/bin/
Chapter 7. Managing Access Manager servers
97
Start the Access Manager Servers using the pd_start utility
Use the pd_start utility to start all Access Manager servers not currently running
on a particular machine:
# pd_start start
This script waits until all servers have started before returning the prompt.
Start individual servers manually
You 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 utility
Use the pd_start utility to stop all Access Manager servers on a particular machine
and 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 utility
Use the pd_start utility to stop all Access Manager servers on a particular machine
in 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 utility
Use the pd_start command to display server status:
pd_start status
Access Manager Servers:
Server
Enabled
Running
pdmgrd
webseald
pdacld
yes
no
no
yes
no
yes
Starting and stopping servers on Windows systems
Use the Windows NT Services Control Panel to start and stop the server processes
manually. This can be useful when customizing an installation or when
troubleshooting. Administrative privileges are required to use this utility.
You can start and stop the Access Manager servers all at once or individually. The
servers generally must be stopped and started in the correct order.
Using the Services Control Panel to stop and start servers
The AutoStart Service automatically starts each of the Access Manager servers
whenever the Startup configuration is set to “Automatic”. After the servers start,
the AutoStart Service exits.
98
IBM Tivoli Access Manager: Base Administrator’s Guide
You can also use the Services Control Panel to manually start and stop the
individual 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 server
v policy server
5. Start the Access Manager servers in the following order:
v policy server
v authorization server
6. Click the appropriate control option button (Start, Stop, Startup) from the
right-hand side of the box.
7. To prevent automatic starting of a Access Manager server by the AutoStart
Service, use the Startup... button to set that server to Disabled.
Automating server startup at boot time
Parameters for automating server startup are located in the [pdrte] stanza of the
pd.conf configuration file.
Policy server
When the PDMgr package is installed, the policy server automatically starts after
each 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 pdmgrd
on more than one server per secure domain.
Authorization server
When the PDAcld package is installed, the authorization server daemon
automatically starts after each system reboot:
[pdrte]
boot-start-ivacld = yes
To prevent automatic pdacld startup, set:
boot-start-ivacld = no
Policy server administration
The policy server manages the master authorization policy database and maintains
location information about other Access Manager servers in the secure domain. The
policy server typically requires very little administration or configuration. This
section describes configuration tasks available to the administrator.
v “Replicating the authorization database” on page 100
Chapter 7. Managing Access Manager servers
99
v “Setting the number of update notifier threads” on page 101
v “Setting the notification delay time” on page 101
Replicating the authorization database
An Access Manager administrator can make security policy changes to the secure
domain at any time. A primary responsibility of the policy server is to make the
necessary adjustments to the master authorization database to reflect these
changes.
When the policy server makes a change to the master authorization database, it
can send out notification of this change to all authorization servers (with replica
databases). The authorization servers must then request a database update from
the master authorization database.
Note: Additionally, client servers can check for database updates by polling the
policy server at regular intervals. Polling configuration for a WebSEAL
client, for example, is explained in the IBM Tivoli Access Manager WebSEAL
Administrator’s Guide.
Access Manager allows you to configure update notifications from the policy
server to be an automatic process or a manually controlled task. The
auto-database-update-notify parameter is located in the [ivmgrd] stanza of the
ivmgrd.conf configuration file. By default, the parameter is set to yes (update
notification is automatically performed by the policy server):
[ivmgrd]
auto-database-update-notify = yes
This automatic setting is appropriate for environments where database changes are
few and infrequent. When you configure update notification to be automatic, you
must also correctly configure the max-notifier-threads and notifier-wait-time
parameters. 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 the
pdadmin server replicate command controls this event.
[ivmgrd]
auto-database-update-notify = no
This manual setting is appropriate for environments where database modifications
occur frequently and involve substantial changes. In some cases several database
modifications can generate many update notifications which soon become obsolete
because of the continuing changes to the master database. These obsolete
notifications cause unnecessary network traffic.
The manual control of update notification allows you to complete the process of
modifying the master authorization database before update notifications are sent
out to authorization servers with database replicas.
In manual mode, update notification uses the notifier thread pool (as it does in
automatic mode). Therefore, the manual mode setting is affected by the
max-notifier-threads parameter setting. See “Setting the number of update notifier
threads” on page 101.
100
IBM Tivoli Access Manager: Base Administrator’s Guide
Using the pdadmin server replicate command
When you configure update notification to be manual, manual application of the
pdadmin server replicate command controls this event. The command has the
following syntax:
pdadmin> server replicate [-server <server-name>]
If the optional server-name argument is specified, only that server is notified of
changes to the master authorization database. A response is returned indicating the
success or failure of the notification and the replication.
If the server-name argument is not specified, all configured authorization servers
receive update notifications. A successful response only indicates that the policy
server has begun sending out update notifications. The response does not indicate
success 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 threads
The policy server is responsible for synchronizing all database replicas in the
secure domain. When a change is made to the master database, notification threads
do the work of announcing this change to all replicas. Each replica then has the
responsibility to download the new information from the master.
The policy server configuration file, ivmgrd.conf, contains a parameter for setting
the maximum number of update notifier threads. This pool of threads allows
simultaneous (parallel) notification.
For example, to concurrently notify 30 replicas of a database change, the thread
pool should be set to at least 30. If there are more than 30 replicas, another round
of notifications occurs (in this example, 30 at a time). All replicas are guaranteed to
be notified, regardless of the value of this parameter.
The performance goal of the update notifier threads value is to announce a
database change as quickly as possible. Generally the value should be set to equal
the number of existing replicas. This results in the performance advantage of a
single pool of threads quickly accomplishing the notification task to all replicas at
once.
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 time
When the policy server is instructed to make a change to the master authorization
database, it waits for a default period of time before sending out notifications to
database replicas. The default time delay is set at 15 seconds. This time delay is
reset with each subsequent change to the database.
The purpose of the time delay is to prevent the policy server from sending
individual replica notifications for each of a series of database changes. The time
delay helps to ensure optimal performance of the Access Manager system.
Chapter 7. Managing Access Manager servers
101
This performance feature is particularly important for environments where batch
changes are made to the authorization database. It is not efficient for policy
changes to be sent to database replicas until all changes have been made.
You can override this default notification time delay by changing the
notifier-wait-time parameter value (in seconds), located in the [ivmgrd] stanza of
the ivmgrd.conf configuration file. For example:
[ivmgrd]
notifier-wait-time = 20
By default, the value is set to 15 seconds.
102
IBM Tivoli Access Manager: Base Administrator’s Guide
Chapter 8. Using the LDAP registry
LDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes
low-level network protocol definitions plus data representation and handling
functionality. A directory that is accessible through LDAP is commonly referred to
as an LDAP directory.
The default installation of Access Manager uses the LDAP directory to store user
information. IBM’s implementation of LDAP is known as IBM SecureWay
Directory. 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 103
v “LDAP fail-over configuration” on page 106
v “Applying Access Manager ACLs to new LDAP suffixes” on page 109
LDAP overview
In 1988, the CCITT (Consultative International Telephonique et Telegraphique,
which is now ITU-T, International Telecommunications Union -Telecommunication
Standardization Sector) created a standard for directory services known as X.500.
The X.500 directory service soon became ISO standard 9594 (Data Communications
Network Directory, Recommendations X.500-X.521) in 1990.
The ISO set of standards is still commonly referred to as X.500. X.500 defines a
directory that can be universally used for large amounts of data. Today, X.500
directories are used by national telephone organizations for large, online telephone
directories.
To access an X.500 directory, a client uses the Directory Access Protocol (DAP) that
was defined along with the X.500 standard. Unfortunately, DAP is a rather
complex protocol that cannot be easily supported on thin clients, such as desktop
computers.
X.500 was therefore limited to powerful computers and large-scale
implementations. The requirement to access centralized directories from slim
clients, however, became important to support the obvious cost-effectiveness of
centralized directories.
Work performed at the University of Michigan and at Netscape Communications
Corporation led to a simplified version of DAP, called the Lightweight Directory
Access Protocol (LDAP). LDAP supports most of the features of DAP, but lacks
some of the complex and seldom used functions. The LDAP implementation is
relatively simple and can be used by desktop applications.
LDAP: A protocol for directory services
LDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes
low-level network protocol definitions plus data representation and handling
functionality. A directory that is accessible through LDAP is commonly referred to
as 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 directory
through a gateway server that did translation between LDAP and DAP.
LDAP
Client
LDAP
Gateway
Server
TCP
LDAP
OSI
DAP
X.500
Server
Directory
Figure 29. LDAP access to X.500
Soon, directories were developed that could handle the LDAP protocol natively
rather than performing a translation between LDAP and DAP.
LDAP
Client
TCP
LDAP
LDAP
Server
Directory
Figure 30. Stand-alone LDAP server
The IBM implementation of an LDAP directory is the SecureWay Directory, which
is 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 Directory
uses the high-performance, highly-scalable DB2 relational database as its storage
implementation.
LDAP directories
Most directories store information similar to the structure of a printed phone book.
The entries are usually organized in a hierarchical way that allows efficient and
flexible management and searching.
LDAP directories are much more powerful and are not limited to name, phone
number, and address entries. In fact, an LDAP directory can store (and
subsequently retrieve) almost any kind of data. The type of data that can be stored
in an LDAP directory is defined by the directory schema, which can be extended
and adapted to meet your requirements.
The task of defining a directory schema and the hierarchical directory information
tree can be compared to the design of a relational database. Thorough analysis of
application requirements, corporate standards, and data definitions is necessary to
design a directory schema and the directory information tree (DIT).
104
IBM Tivoli Access Manager: Base Administrator’s Guide
LDAP server products, such as the IBM SecureWay Directory, provide a
comprehensive schema that can be used, unless requirements dictate specific
modifications.
IBM supports current and evolving standards and proposals for data definitions by
actively participating in the standards process and by implementing the results in
the IBM SecureWay Directory. The most important standards body for LDAP is the
Internet Engineering Task Force (IETF), where representatives of IBM and other
key 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 or
on 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 and
other network resources, such as printers and servers.
Information is often stored across multiple locations, making administration and
maintenance unnecessarily difficult. A major reason why LDAP has quickly
gathered so much interest is the potential for a single, standards based directory
for distributed information.
The LDAP information model
The 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 are
typed in the form:
type = value
where the type is defined by an object identifier (OID), and the value has a defined
syntax. Attributes can be single-valued (for example, a person can only have one
date-of-birth) or multi-valued (a person can have multiple phone numbers).
Each entry in an LDAP directory has a unique distinguished name (DN). The
directory schema defines rules for DNs and what attributes an entry must contain.
To organize the information stored in directory entries, the schema defines object
classes. An object class consists of mandatory and optional attributes.
Object classes can be inherited from other object classes, which provides a method
for easy extensibility (for example, new object classes can be defined by just
adding new attributes to existing object classes).
LDAP features
Scalability
LDAP directories, particularly when they are backed up by a relational database as
in the IBM SecureWay Directory, are highly scalable. Large directories with millions
of entries are possible with excellent performance.
Due to the common standard base, another scalability factor is the easy step-up
possibility to more powerful hardware and software. LDAP does not rely on a
specific operating system and is vendor-independent.
Chapter 8. Using the LDAP registry
105
Availability
LDAP supports replication and splitting of namespaces. Replication allows
multiple LDAP servers to store the same directory contents. Clients benefit from
these additional servers available whenever one fails.
Splitting allows sections of the whole directory to be stored on different servers at
different locations. This not only increases availability (no single point of failure)
but also offers an easy way for distributed management.
Security
LDAP supports security features that prevent unauthorized access to data. Secure
communication protocols, such as SSL and authentication mechanisms, along with
access control lists (ACL) policies for data entries, guarantee a maximum level of
security.
Manageability
Current versions of LDAP, such as the IBM SecureWay Directory, provide a
graphical user interface for both system administration and directory data
administration. Dynamically extensible schema allows you to extend the directory
schema without interrupting the service.
Standardization
The LDAP protocol—and many related client/server capabilities, application
programming interfaces (APIs), and data definitions—are defined by either official
standards or corresponding RFCs (Request for Comments).
Lightweight Directory Access Protocol (v3), RFC 2251, for example, defines the
basic LDAP protocol. Other features, that are widely accepted and implemented,
are defined in Internet drafts. Much of this work is done by the IETF (Internet
Engineering Task Force) and the DMTF (Distributed Management Task Force).
LDAP fail-over configuration
The Lightweight Directory Access Protocol (LDAP) defines a standard method for
accessing and updating information in a directory. Directories are usually accessed
using the client/server model of communication. Any server that implements the
LDAP protocol is an LDAP directory server.
The LDAP distributed architecture supports scalable directory services with server
replication capabilities. Server replication improves the availability of a directory
service. IBM SecureWay Directory replication is based on a master-slave model.
iPlanet Directory Server replication is based on a supplier/consumer model. Access
Manager still treats this as a master/slave relationship.
The combination of a master server and multiple replicated servers helps ensure
that directory data is always available when needed. If any server fails, the
directory service continues to be available from another replicated server. Access
Manager supports this replication capability.
The master-slave replication model
Replication involves two types of directories: master and replica. LDAP refers to
the master as master server and to the replica as replica server. All updates are
made on the master server and these updates are subsequently propagated to the
replica servers. Each replica server database contains an exact copy of the master
server’s directory data.
106
IBM Tivoli Access Manager: Base Administrator’s Guide
Changes to the directory can be made only to the master server, which is always
used for write operations to the directory. Either the master or the replicas can be
used for read operations. When the original master server is out of service for an
extended period of time, a replica server can be promoted as a master server to
allow write operations to the directory.
Access Manager fail-over capability for LDAP servers
Access Manager connects to the LDAP master server when it starts up. If the
LDAP master server is down for any reason, the Access Manager server must be
able to connect to an available LDAP replica server for any read operations.
Many operations, especially those from regular users, are read operations. These
include such operations as user authentication and signon to back-end junctioned
Web servers. After proper configuration, Access Manager will fail-over to a replica
server when it cannot connect to the master server.
You can find the configuration parameters for LDAP fail-over in the [ldap] stanza
of the ldap.conf configuration file:
UNIX: /opt/PolicyDirector/etc/ldap.conf
Windows: install_path\etc\ldap.conf
Master server configuration
IBM SecureWay Directory (LDAP) supports the existence of a single read-write
master LDAP server. iPlanet Directory Server supports multiple read-write LDAP
servers. Access Manager treats the iPlanet “supplier” server as the master server
for configuration purposes.
The active configuration lines in the ldap.conf file represent the parameters and
values for this master LDAP server. You determine these values during Access
Manager configuration. For example:
[ldap]
enabled = yes
host = outback
port = 389
ssl-port = 636
max-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 master
server 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 database
items - such as a request for the Web portal manager to list users
from the LDAP database.
If you make a change to the LDAP database, such as adding a new user account
through the Web portal manager, Access Manager always uses the read-write
(master) LDAP server.
Chapter 8. Using the LDAP registry
107
Replica server configuration
IBM SecureWay Directory (LDAP) supports the existence of one or more read-only
replica LDAP servers. iPlanet Directory Server (LDAP) supports the existence of
one or more read-only replica LDAP servers referred to as “consumers”.
You must add lines to the [ldap] stanza that identify any replica servers available
to Access Manager. Use the following syntax for each replica:
replica = ldap_server,port,type,preference
Parameter
Description
ldap-server
The network name of the LDAP replica server.
port
The port this server listens on. Generally, use 389 or 636.
type
The functionality of the replica server - either “read-only” or
“read-write”. Normally, use “read-only”. A “read-write” type
would represent a master server.
preference
A number from 1 - 10. The server with the highest preference
value is chosen for LDAP connections. See “Setting preference
values for replica LDAP servers”.
Example:
replica = replica1.ldap.tivoli.com,389,readonly,5
replica = 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 servers
Each replica LDAP server must have a preference value (1-10) that determines its
priority for selection as:
v The primary read-only access server, or
v A backup read-only server during a fail-over
The higher the number, the higher the priority. If the primary read-only server fails
for any reason, the server with the next highest preference value is used. If two or
more servers have the same preference value, a least-busy load balancing
algorithm determines which one is selected.
Remember that the master LDAP server can function as both a read-only and a
read-write server. For read-only access, the master server has a hard-coded default
preference setting of 5. This allows you to set replica servers at values higher or
lower than the master to obtain the required performance. For example, with
appropriate preference settings, you could prevent the master server from handling
everyday 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 and
allow load balancing to dictate server selection.
The following table illustrates some possible preference scenarios. “M” refers to the
master (read-only/read-write) LDAP server; “R1, R2, R3” refer to the replica
(readonly) LDAP servers.
108
IBM Tivoli Access Manager: Base Administrator’s Guide
M
R1
R2
R3
Fail-over Preference
5
5
5
5
All servers have the same preference values. Load
balancing determines which server is selected for each
access operation.
5
6
6
6
The three replica servers have the same preference
value. This value is higher than the master server
value. Load balancing determines server selection
among the three replicas. The master is only used if
all three replica servers become unavailable.
5
6
7
8
Server 3 (with the highest preference value) becomes
the primary server. If server3 fails, server 2 becomes
the primary server because it has the next highest
preference value.
Preference values only affect read-only access to the LDAP database. Access
Manager always uses the master (read-write) server when you need to make a
change to the LDAP database.
Also note that some Access Managerdaemons (such as the policy server) override
the preference settings in their configuration files to indicate that the read-write
server is preferred. This is because those daemons usually make update operations
which should go to the master LDAP server.
Server polling
If an LDAP server does fail, Access Manager continuously polls the server to check
for 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 Server
and iPlanet Directory Server.
When an LDAP administrator adds LDAP suffixes after the initial configuration of
Access Manager, the administrator must apply the appropriate Access Control Lists
(ACLs) to allow Access Manager to manage users and groups defined in these new
suffixes.
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 to
every 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
Chapter 8. Using the LDAP registry
109
LDAP Group
Access Control
v read
v search
v compare
These controls apply when the administrator has selected LDAP for the Access
Manager user registry and a new LDAP suffix has been created after Access
Manager is initially configured. It is assumed that you are the Access Manager
administrator and are familiar with both Access Manager and LDAP. It is further
assumed that, as administrator, you have the proper authority to update the LDAP
Directory Information Tree.
When Access Manager is configured, it attempts to apply appropriate ACLs to
every LDAP suffix that exists at that time in the LDAP server. This access control
allows Access Manager to create and manage user and group information within
these LDAP suffixes.
However, if a suffix is created after Access Manager has been configured, and
Access Manager must later be able to create and manage user and group
information within this new suffix, then the appropriate access controls need to be
applied manually. Without these access controls, Access Manager does not have the
appropriate LDAP permission to create and manage user and group information
specified to be within this new suffix.
To apply the appropriate access controls to the newly created LDAP suffix, perform
the following steps for either the IBM SecureWay Directory or the iPlanet Directory
Server, 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 this
value in the following descriptions.
Procedures for the IBM SecureWay Directory server
The following steps describe how to apply the appropriate Access Manager access
controls 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 have
seen this warning.
3. Click the Add Server button in the left pane. The Add Server window
appears.
4. Enter these values for each of the following fields:
110
IBM Tivoli Access Manager: Base Administrator’s Guide
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 LDAP
administrator
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. The
following 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. Access
control cannot be applied to the suffix until an entry exists. Follow these steps
to 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 is
displayed 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 from
this 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, and
Compare).
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 for
the group are correct. Group names are not case-sensitive.
Chapter 8. Using the LDAP registry
111
16. In the subject area of the Edit an LDAP ACL window, enter the following
Distinguished 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 DN entry box, select Descendant directory tree entries inherit from
this entry.
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=ivacldservers,cn=SecurityGroups,secAuthority=Default group is listed and the
settings 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 following
Distinguished 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 DN entry box, select Descendant directory tree entries inherit from
this entry.
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, and
Compare).
Click OK.
21. Click Exit to close the Directory Management Tool.
Procedures for iPlanet Directory Server
Note that these procedures describe the creation of ACLs for suffixes using the
iPlanet 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 server
install directory:
# ./startconsole
v On Windows systems, click: Start → Programs → iPlanet Server Products →
iPlanet Console 5.0
112
IBM Tivoli Access Manager: Base Administrator’s Guide
2. Enter the User ID for the LDAP administrator. This is usually cn=Directory
Manager. 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 8
If the newly created suffix does not appear in the left pane, you must create
an 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 type
and 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 is
displayed.
9. Click New to display the Edit ACI for o=neworg, c=us window.
10.
11.
12.
13.
Specify the ACI name as SECURITY GROUP - ALLOW ALL.
Highlight the All Users name and click Remove.
Click Edit Manually. The Edit ACI for o=neworg,c=us window is displayed.
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. Correct
any errors until the syntax passes the check.
14. Click OK. The Manage Access Control for o=neworg,c=us window is
displayed.
15. Click New. Specify the ACI name as
PD 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";)
Chapter 8. Using the LDAP registry
113
19.
20.
21.
22.
23.
Click Check Syntax to ensure that you have entered the text correctly. Correct
any errors until the syntax passes the check.
Click OK. The Manage Access Control for o=neworg,c=us window is
displayed.
Click New. Specify the ACI name as PD Remote ACL Users GROUP -ALLOW READ.
Highlight the All Users name and click Remove.
Click Edit Manually. The Edit ACI for o=neworg,c=us window is displayed.
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";)
Click Check Syntax to ensure that you have entered the text correctly. Correct
any errors until the syntax passes the check.
24. Click OK. The Manage Access Control for o=neworg,c=us window is
displayed.
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";)
Click Check Syntax to ensure that you have entered the text correctly. Correct
any errors until the syntax passes the check.
29. Click OK. The Manage Access Control for o=neworg,c=us window is
displayed.
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";)
Click Check Syntax to ensure that you have entered the text correctly. Correct
any errors until the syntax passes the check.
34. Click OK. The Manage Access Control for o=neworg,c=us window is
displayed.
35. Click OK to close the Manage Access Control for o=neworg,c=us window.
36. Click Console → Exit to exit the console.
114
IBM Tivoli Access Manager: Base Administrator’s Guide
Chapter 9. Logging and auditing server activity
Access Manager provides a number of logging and auditing capabilities. Log files
can capture any error and warning messages generated by Access Manager servers.
Audit trail files can capture authorization, authentication, management, and HTTP
events occurring on the Access Manager servers.
This chapter contains the following sections:
v “Introduction to logging and auditing” on page 115
v “Audit trail files”
v “Logging Base serviceability messages” on page 116
v “Access Manager audit trail files” on page 117
v “Audit trail file format” on page 120
v “Audit trail file contents” on page 121
Introduction to logging and auditing
The contents of log and audit trail files can be a useful source of information when
monitoring and troubleshooting the activity of Access Manager servers.
Audit trail files
Audit trail files are used by the Access Manager servers to store records of server
activity. The output of a specific server event is called a record. An audit trail is a
collection of multiple records that document the server activity. All Access
Manager 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_path
The install_path variable used throughout this chapter has the following
interpretations, 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 of
the Access Manager software.
115
Logging Base serviceability messages
Access Manager Base serviceability messages are controlled by the Access Manager
Base 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 the
form of comment lines. Entries in this configuration file determine the types of
serviceability messages that are logged. Enable any entry by removing the
comment character (#). The routing file includes the following default entries:
UNIX:
FATAL:STDOUT:-;FILE:/var/PolicyDirector/log/fatal.log
ERROR:STDOUT:-;FILE:/var/PolicyDirector/log/error.log
WARNING:STDOUT:-;FILE:/var/PolicyDirector/log/warning.log
NOTICE:FILE.10.100:/var/PolicyDirector/log/notice.log
#NOTICE_VERBOSE:STDOUT:-;FILE:/var/PolicyDirector/log/verbose.log
Windows:
FATAL:STDERR:-;FILE:%PDDIR%/log/fatal.log
ERROR:STDERR:-;FILE:%PDDIR%/log/error.log
WARNING:STDERR:-;FILE:%PDDIR%/log/warning.log
NOTICE:FILE.10.100:%PDDIR%/log/notice.log
Note: On a Windows system, the special environment variable PDDIR is set at run
time to the Access Manager installation directory.
By default, when Access Manager Base runs in the foreground, messages are
handled 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 are
handled 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 appropriate
server configuration file.
Server
Configuration
File
Log File Location
Policy server
ivmgrd.conf
UNIX:
[logging]
log-file=/var/PolicyDirector/log/
ivmgrd.log
(pdmgrd)
Windows:
[logging]
log-file=install_path\log\ivmgrd.log
116
IBM Tivoli Access Manager: Base Administrator’s Guide
Server
Configuration
File
Log File Location
Authorization server
ivacld.conf
UNIX:
[logging]
log-file=/var/PolicyDirector/log/ivacld.log
(pdacld)
Windows:
[logging]
log-file=install_path\log\ivacld.log
2. Messages are also sent to the appropriate configured log file entries in the log
directory (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, each
with a maximum of 100 entries. The files are named:
notice.log.1
notice.log.2
.
.
.
notice.log.10
The messages “wrap around” to the first file after the last file has reached its limit
or when the server is stopped and restarted. When a log file is reused, the existing
records are written over (erased).
Access Manager audit trail files
Auditing is defined as the collection of data about system activities that affect the
secure operation of the Access Manager authorization process. Each Access
Manager server can capture audit events whenever any security related auditable
activity occurs.
Audit events are saved as audit records that document the specific activity of that
server. Each audited activity is referred to as an audit event. A collection of audit
event records stored in a file is referred to as an audit trail.
Each Access Manager server maintains its own audit trail file. The Access Manager
servers 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 in
the [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 auditing
Audit trail recording is enabled on a server-by-server basis by setting the logaudit
value in the [aznapi-configuration] stanza of the configuration file for the specific
server.
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 location
By default the audit trail file for each server is called audit.log and is held in the
specific server’s log directory. The auditlog parameter in each server’s
configuration file specifies the location of the audit trail file.
Server
policy server
(pdmgrd)
Log File Location
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 thresholds
The logsize parameter specifies the maximum size to which each of the audit trail
files 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 rollover
threshold—the existing file is backed up to a file of the same name with an
appended 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 that
instance.
118
IBM Tivoli Access Manager: Base Administrator’s Guide
v If the logsize value is equal to zero (= 0), then no rollovers are performed and
the audit trail file grows indefinitely. If an audit trail file already exists, new data
is appended to it.
v If the logsize value is greater than zero (> 0), then a rollover is performed when
an audit trail file reaches the configured threshold value. If an audit trail file
already exists at startup, new data is appended to it.
Specifying the frequency for flushing audit file buffers
Audit trail files are written to buffered data streams. If you are monitoring the
audit trail files in real time, you might want to alter the frequency with which the
server 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 events
Audit events are categorized by the server functionality that generates them. Some
functionality is common across Access Manager servers while other functionality is
server-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 events
on a category by category basis. For example the following configuration captures
only authentication events and disable the capture all other events, including
overriding 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 = http
auditcfg = 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) that
can 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
Chapter 9. Logging and auditing server activity
119
Audit Tag
http
webseald
pdmgrd
pdacld
authadk
X
Audit trail file format
Audit events are captured in the audit trail in a standard format using XML-style
tags. Although XML is only an intermediary step to delivering a presentation view
of the data, the XML file is in ASCII format and can be read directly or passed to
other external parsing engines for further analysis.
An entire audit trail does not represent a single XML document. Each audit event
within the file is written as an isolated XML data block. Each data block conforms
to the rules of standard XML syntax.
As an audit administrator, you are expected to select and extract events according
to your own criteria. This might include reformatting each event by applying an
appropriate DTD (Document Type definition) or schema for the analysis tool you
are using. The DTD is an intermediate format that provides a description of the
data that can be captured.
A suggested DTD is shown below.
<!--audit_event.dtd -->
<!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>
120
IBM Tivoli Access Manager: Base Administrator’s Guide
Because Access Manager auditing uses a standard record format, not all fields are
relevant to every event recorded. Generally each event captures the result of an
action that a principal attempts on a target object.
Information about the action, the principal’s credentials, the target object, and the
outcome are captured in a common format header of the audit record. Fields that
are not relevant for a particular event might contain a default value. Additional
event-specific information can also be recorded in a free format data area at the
end of the record.
Decoding the meaning of certain data values in the records might require an
advanced knowledge of the Access Manager code and architecture.
Status attribute of the outcome field
The outcome field always includes a Access Manager status code and an outcome
value. The possible outcome values include:
0
1
2
3
=
=
=
=
SUCCESS
FAILURE
PENDING
UNKNOWN
You can use the pdadmin errtext command to provide interpretation for the policy
Director status code (412668954 in the following example).
<outcome status=”412668954”>1</outcome>
Resource attribute of the target field
The resource attribute of the target field represents a broad categorization of the
target object:
0
1
2
3
5
=
=
=
=
=
AUTHORISATION
PROCESS
TCB
CREDENTIAL
GENERAL
Audit trail file contents
Authorization audit records
Authorization is the primary function of the Access Manager servers.
Authorization audit records can be captured when a target object in the Access
Manager authorization policy database (protected object space) has a POP attached
to 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 audit
configuration list in the [aznapi-configuration] stanza of the server’s configuration
file:
[aznapi-configuration]
auditcfg = azn
The following record is a sample audit record for the following event:
pdadmin> pop modify pop1 set audit-level all
Chapter 9. Logging and auditing server activity
121
<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 records
Authentication of a principal is performed externally to Access Manager during
credential acquisition. Audit records can be captured by Access Manager to record
the success or failure of such authentication attempts.
You can configure auditing of authentication attempts by adding “authn” to the
audit configuration list in the [aznapi-configuration] stanza of the server’s
configuration file:
[aznapi-configuration]
auditcfg = authn
The following is a sample authentication event logged from WebSEAL for an
unauthenticated 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 records
Web 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 IBM
Tivoli Access Manager WebSEAL Administrator’s Guide.
122
IBM Tivoli Access Manager: Base Administrator’s Guide
You can configure auditing of WebSEAL activity by adding “http” to the audit
configuration list in the [aznapi-configuration] stanza of the WebSEAL server’s
configuration 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 Records
The responsibilities of the policy server include maintaining the master
authorization policy database. This database includes the description of the
protected object space for the secure domain, ACL and POP policies, and where
ACLs and POPs are attached to objects.
You can configure auditing of the policy server activity by adding “mgmt” to the
audit configuration list in the [aznapi-configuration] stanza of the policy server’s
configuration 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 commands
The audit records for management commands contains an event ID code that
identifies one of the Access Manager management (pdadmin) commands.
Command arguments are listed in the data section of the event record in their
internal format.
Chapter 9. Logging and auditing server activity
123
Note that commands which do not result in an effective change of state of the
database (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
124
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
IBM Tivoli Access Manager: Base Administrator’s Guide
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
Chapter 9. Logging and auditing server activity
125
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
126
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
IBM Tivoli Access Manager: Base Administrator’s Guide
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 9. Logging and auditing server activity
127
128
IBM Tivoli Access Manager: Base Administrator’s Guide
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 of
information to disk.
The concept of the information-to-capture has now been abstracted from the action
of recording that information to a file. This loose coupling was introduced to
support centralized collection and recording of audit trails. The new functionality
also offers greater flexibility for the configuration and capture of other Access
Manager event data.
Understanding Access Manager events
Apart from some messages produced when starting a program, all messages
generated by Access Manager for auditing and other serviceability purposes are
now created in a structured hierarchy of Access Manager events.
The orderly categorization of events within this hierarchy allows runtime
associations to be made between classes of events and the log agents to be used to
record those events. Additionally the concept of a log agent has been expanded to
include recording of events to destinations other than the local file system. The
event hierarchy is built up dynamically during program execution. While some
well known event categories can be expected to be present when running an
Access Manager program, other categories are program specific and some might be
transient.
The purpose of this chapter is to describe how you can associate log agents with a
point in the event pool hierarchy to record events. This chapter does not provide a
description of the characteristics of all possible events within the hierarchy. For
descriptions of well-known events such as those generated for auditing, refer to
the appropriate product-specific documentation.
Generally, the event pool hierarchy is similar to the following:
129
Event Pool
audit
azn
authn
mgmt
http
trace
remote
http
pd
ras
bas
clf
ref
agent
bas
Figure 31. Event pool hierarchy
A specific event category is identified by a dot-separated list of names. The first
level of name within the category has special significance. This top-level category
name also might correspond to events previously associated with legacy log files
described 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 events
recorded for Tivoli SecureWay Policy Director, Version 3.7, in the audit trail, the
WebSEAL http request logs, and the Distributed Computing Environment (DCE)
serviceability message logs. Several new event domains were introduced in Version
3.8, including trace, statistics and remote. Trace and statistics events gather
serviceability information about program execution. Remote events implement the
centralized collection and recording of log files.
Implementation note: For efficiency, an event is not generally created if there are
no log agents subscribed to record events of that category. In the case that an event
is generated and there are no log agents subscribed to record it, the event is
discarded.
Configuring event logging
In addition to the backward-compatible method of configuring log files, you can
specify line items in the [aznapi-configuration] stanza of a program’s
configuration (.conf) file to configure the capture of Access Manager events.
To enable the recording of Access Manager events using the new interface, you
must 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 agent
v File log agent
v Pipe log agent
v Remote log agent
130
IBM Tivoli Access Manager: Base Administrator’s Guide
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 generally
optional. Valid options for each log agent type are described below. In a
configuration entry, the option names are case insensitive and can be abbreviated
to 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 of
events for a category is inclusive of all subcomponents in the hierarchy. That is, a
foo.bar.fred event also is captured at the foo.bar category.
You can attach multiple log agents to the same category. For example, the
following configuration copies authorization audit events to a file and relays them
to a program listening on a pipe:
logcfg = audit.azn:file path=/var/PolicyDirector/log/audit.azn
logcfg = audit.azn:pipe path=/bin/analyse.exe
The following diagram depicts the relationships between steps in the logging
process. The top third of the diagram represents the code of an Access Manager
server. The programmer added probe points to the code where events of specific
types might be generated. Generated events are then submitted to the server’s
event pool for possible recording through a point of capture (the sink), which
defines the events category.
At runtime, a user can subscribe a log agent at any point in the event pool
hierarchy to selectively record events generated at the programs probe points. This
is depicted in the middle band of the diagram.
One log agent that you can subscribe to capture events is a remote log client. This
client forwards the selected events to a remote pdacld server. The bottom band of
the diagram depicts this remote server. Note that the bottom band is essentially the
same 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.
Trace
Event
Sink
Application
Specific Probe
Points
Audit
Event
Sink
Event Pool
Standard Policy
Director Server
Subscribed log agent
Console
Console
Log
File
Adaptor
Remote
Log
Client
Event
Cache
Other
Adaptor
Log
File
Remote Logging
pdacld server
Multiple Other
Networked
Log Clients
Remote
Log
Server
Log
File
Event
Sink
File
Adaptor
Event
Pool
Subscribed Log
Agents
Pipe
Adaptor
Configuring the central event propagation queue
Events are passed to subscribed log agents asynchronously to the application-level
requests that construct the events for recording. Events initially pass through a
common propagation queue before they are fanned out to the variously subscribed
log agents.
The servicing profile of this propagation queue is configurable. To configure the
propagation queue, you must specify an abridged format logcfg entry. The
shortened configuration entry uses EventPool as the category name and specifies
queuing 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 in
memory
To control the amount of memory that can be consumed by events on the
propagation queue, you can set a limit for the maximum size the queue is allowed
to grow to. If the maximum size is reached when a new event is generated, the
132
IBM Tivoli Access Manager: Base Administrator’s Guide
thread attempting to queue it is blocked until space is available in the queue. This
has the effect of throttling back performance of the event producing thread to the
speed 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 is
enforced on the growth of the event queue. Keep in mind that using the default
can allow the unprocessed event queue to grow to an unmanageable size when
events are produced at a faster rate than the subscribed log agents can clear them.
Specifying the event queue high water mark
Processing of the event queue is scheduled regularly at the configured flush
interval. It is also triggered asynchronously by the queue size reaching a high
water mark.
The default value for hi_water is 1024. If you specify a value for queue_size, but
no hi_water value, the default hi_water is calculated as two-thirds the maximum
configured queue size. If the maximum queue size is 0, the high water mark is set
to a default of 100.
If the event queue high water mark is set to 1, every event queued is relayed to
any subscribed log agents as soon as possible. Note that setting a low value for
hi_water can have an adverse effect on overall performance.
Specifying the frequency for flushing log file buffers
Use the flush_interval option to specify a limit on the time an event waits in the
propagation queue before it is forwarded to the log agents. If events are being
generated at a slow rate that does not trigger handling by reaching the high water
mark in a timely manner, events are flushed from the propagation queue at this
frequency.
flush_interval=<seconds>
The flush_interval default value is 10 seconds. A flush_interval of 0 is not
allowed. Specifying a value of 0 results in the queue being flushed every 600
seconds.
Console logging
Logging to the console is the easiest option to configure. Simply associate an
output destination of standard out or standard error with the category of events in
the 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 the
following:
logcfg = audit.azn:stderr
Logging to the console does not itself use any queuing. The events are written to
the console as they are received from the propagation queue. Note however that
events might be delayed in the propagation queue depending on its queue settings.
Chapter 10. Using event logging
133
If you are using console output and running a server in foreground for debugging
purposes, you might want to set the propagation queue settings accordingly. For
example, set the hi_water option to a low value.
File logging
To 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 selectively
capture events at different points of the event pool hierarchy to the same file, the
file opens according to the options found in the first configuration entry processed.
Once a file has been opened, further file configurations can simply use the
shorthand 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 generating
events, 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 central
event propagation queue, but has different default values.
Specifying the log file location
Use the path option to specify the location of a log file. There is no default value
for the file pathname because the log_id value takes precedence. An example path
value 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 does
not already exist.
Specifying the log file ID
An open log file is associated with a short name identifier to facilitate the
recording 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 a
default value. If the path option is specified, the default value is the configured
path name. If path is not specified, the log ID defaults to the domain component of
the event category being captured. For example:
logcfg = audit.azn:file
implies
log_id=audit.
134
IBM Tivoli Access Manager: Base Administrator’s Guide
To capture events to a common file, set the log file ID to a suitable value in a
fully-optioned file configuration. Subsequently, use the shorthand configuration
variant 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 the
following 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 open
log file, no events are captured. For example, the following configuration does not
record any events because the configuration line that initializes the log file has
been commented out:
#logcfg = audit.azn:file path=/tmp/azn.log,log_id=azn
logcfg = audit.authn:file log_id=azn
Specifying the maximum log file size
Use the rollover_size option to specify the maximum size to which a log file can
grow. 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 current
date 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 appended
to it.
v If the rollover_size value is greater than zero (> 0), a rollover is performed when
a log file reaches the configured threshold value. If a log file already exists at
startup, new data is appended to it.
Specifying the maximum buffer size
To reduce memory fragmentation and improve the performance of writing to file,
rather than queuing many small events individually to the file log agent, events
can be buffered into blocks of a nominated size before queuing for writing. The
buffer_size option specifies the maximum size message the program attempts to
construct by combining smaller events into a large buffer.
Buffers only consist of an integral number of events; events are not split across
buffers. If any individual event exceeds that maximum configured size, the large
event 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 buffering
and each event is handled individually.
Chapter 10. Using event logging
135
If a value is specified for the buffer_size, events are packed into buffers of that
size before queuing to the file log agent.
For example if the buffer_size value is set to 2 KB and events are assumed to be
about 256 bytes, around 10 are packed into each buffer written to file. This reduces
the number of disk I/Os made while logging to 10% of the equivalent non
buffering case.
Note that a default queue size of 200 with a buffer_size of 2 KB also consumes
around 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 queue
size value has not been changed, but the size of events being queued has increased
tenfold.
Specifying the maximum number of events to queue in
memory
There is a delay between events being placed on the queue and the file log agent
removing them. The queue_size option specifies the maximum size to which the
queue is allowed to grow. If the maximum size is reached when a new event is
ready to be placed on the queue, the requesting thread is blocked until space is
available in the queue. This has the effect of throttling back performance of the
event propagation thread to the speed of the file logging thread, if it cannot keep
up.
The default value for queue_size is 0. A zero queue size means that no limit is
enforced on the growth of the unprocessed event queue. Correspondingly, the
event 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 queue
growing to an unmanageable size, if events are being generated faster than they
can be recorded to file.
Specifying the event queue high water mark
Processing of the event queue is scheduled regularly at the configured flush
interval. It also is triggered asynchronously by the queue size reaching a high
water mark on the event queue.
The default value for hi_water is two-thirds of the maximum configured queue
size. If the maximum queue size is zero, the high water mark is set to a default of
100.
The transaction rates and the values of these options determine the maximum
amount 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 to
the log agent as soon as possible. This setting is not recommended, although you
might want to use it if you want to ensure events get to disk as fast as possible, at
the expense of overall performance.
Specifying the frequency for flushing log file buffers
The flush_interval option is a multi use option.
The logging to file flush_interval option has the following default value in
seconds.
flush_interval=20
136
IBM Tivoli Access Manager: Base Administrator’s Guide
A flush interval of 0 is not allowed. Specifying a value of 0 results in the value 600
being used.
Log files are written to buffered data streams. To ensure stream buffers are flushed
to disk regularly, the frequency with which the server asynchronously forces a
flush of the file stream to disk is configurable using this option.
If you specify a negative value, the absolute value is used as the asynchronous
flush frequency, but a stream flush is also forced synchronously after every record
is written.
If events are being consolidated into large buffers by specifying a buffer_size
option, the flush_interval parameter also might affect the size of buffer written. If
there is a partially filled buffer in memory when a flush is scheduled, that buffer is
also queued for writing before it completes the buffer fill.
Lastly, the event queue is triggered for processing at the flush interval rate. This
prevents events waiting to be processed for longer than the scheduled flush time
when the queue high water mark is not reached between scheduled flushes.
Specifying the file mode
Use 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 WIN32
platforms, opening a file in text mode enables end-of-line character translations in
the log file. Binary mode on a windows platform writes the log file in a UNIX
compatible format.
Pipe logging
Use the pipe option to write output to the standard input of another program. For
example:
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 responsible
for 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 the
pipe program. Unlike logging to file, piped events are not multiplexed from
different category capture points to a single copy of the program.
Specifying the program to run
Use the path option to specify the location of the program, which receives the log
output on standard input. For example:
path=/opt/risk_analyser/bin/my_log_watcher
Note that there is no default value for the path name.
Chapter 10. Using event logging
137
Specifying the event queuing profile
Configure the pipe logging event queue management in the same way that you
configure logging to file. The queue_size, hi_water, and flush_interval options
have similar meaning to the options described for file logging.
Remote logging
Use the remote option to send events to a remote server for recording. For
example:
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 the
remote server is not available, captured events are cached locally and relayed at a
later date, if and when the remote server becomes available.
Only one remote logging connection is established to a remote server. If multiple
configuration entries are made to selectively capture events at different points of
the event pool hierarchy to the same remote server, the remote connection is
established according to the options of the first remote configuration entry
processed. Multiple remote connections can be configured to log to different
remote servers.
Events received at the remote server are placed in that servers event pool in a
different location to where they were originally captured on the client system. All
events entering a host through the remote logging service are placed in a category
constructed in the following manner:
remote.<client-category-domain>.<hostname>.<program>
For example, all audit events logged remotely from program pdmgrd on host
amazon 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 of
destinations using standard configurations. For example, all audit events from host
amazon 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 size
To reduce network traffic, events are buffered into blocks of the nominated size
before relaying to the remote server. The buffer_size option specifies the maximum
138
IBM Tivoli Access Manager: Base Administrator’s Guide
size message the local program attempts to construct by combining smaller events
into a large buffer. Buffers only consist of an integral number of events; events are
not split across buffers. If any individual event exceeds that maximum configured
size, 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 buffer
If events are being consolidated into very large buffers and there is not much
logging activity, events can sit in memory for a long time before being forwarded
to the remote server or being written to the cache file. The flush_interval option
limits 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 sizes
The queue_size and hi_water values for a remote logging connection are similar to
those specified for logging to file. The default values are as follows:
queue_size=0
hi_water=100
Specifying compression of messages
Access Manager events are principally text messages. To reduce network traffic use
the compress option to compress buffers prior to transmission and expand on
reception. For example:
compress={yes|no}
The default compress value is no.
Specifying the error retry timeout
If 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 are
saved 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 location
The path option specifies the location of a cache file on the local host. The cache
file name defaults to ./server.cache, where server is the name of the remote
server being logged to.
If the running process cannot establish communication with the remote server, or
the link fails during operation, event recording switches to storing events in the
specified 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
Chapter 10. Using event logging
139
The directory portion of this pathname must exist. The log file is created if it does
not already exist. The size of this file is not bound and it does not have any
rollover capability. If a remote server is not accessible for sufficient time, you could
run out of disk space.
Specifying the rebind retry timeout
If the remote server is unavailable, the log agent attempts to rebind to the server at
this frequency in number of seconds (default 300).
rebind_interval=60
Specifying the remote server
The remote logging services are offered by the pdacld program. Remote logging
piggy-backs on the certificates set up for the authorization service as initialized by
a call to azn_initialize(). This option nominates which hosts pdacld process shall
be bound to for event recording.
server=<hostname>
Specifying the remote server port
Use the port option to specify the port that the remote pdacld listens on for remote
logging requests.
port=<number>
The default value is 7136.
Specifying the remote server distinguished name
To establish mutual authentication of the remote server, a distinguished name (DN)
must be configured that can be checked against the name returned in the remote
servers 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 default
value or explicitly specifying an empty string enables the logging client to
promiscuously establish a remote server connection. Specifying a value for the DN
limits successful connection to a specific server:
dn="cn=ivacld/timelord.testnet.tivoli.com,o=policy director,c=us"
Legacy configuration support and other defaults
Tivoli SecureWay Policy Director, Version 3.7, configuration entries are recognized
for the configuration of audit trail recording.
An audit log file set up using the Version 3.7 logaudit and auditlog configuration
entries can be logged to from a file configuration by using the shorthand file
logging syntax, specifying audit as the log ID name. For example:
logaudit = yes
auditlog = /var/PolicyDircetor/pdmgrd/log/audit.log
logcfg = audit.azn:file log_id=audit
The default location for recording events depends on the domain component of the
event category name. Events for the audit domain default to be recorded in the
audit trail. Thus the previous example also can be written as the following:
logaudit = yes
auditlog = /var/PolicyDircetor/pdmgrd/log/audit.log
logcfg = audit.azn
140
IBM Tivoli Access Manager: Base Administrator’s Guide
The default recording location for other components is stderr on the console.
Compatibility with Authorization API configuration
Tivoli SecureWay Policy Director, Version 3.7, allowed the capture-to-file of events
auditing authorization activities by either adding entries to the
[aznapi-configuration] stanza of the configuration file or by loading a
corresponding azn initialize attribute list.
The following list summarizes the Authorization API configuration file entries and
attributes 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 logs
The logcfg configurations that correspond to the log agents enabled using the
default WebSEAL logging configurations described in the webseald.conf
configuration 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 Combined
format by capturing events sent to the http.cof pool. The NCSA combined format
appends the quoted referer and agent strings to the standard common log format
record.
Finding out what event categories exist
The name of each event category is written to a trace event as it is instantiated. To
view trace records, enable trace during start up by adding the following line to the
routing file:
*:*.9:TEXTFILE:/var/PolicyDirector/log/%ld.trace.log 3.9
Chapter 10. Using event logging
141
Monitoring log queue performance
The queuing profiles configured for the main propagation queue and each file,
remote, and pipe log agent are all instrumented for monitoring using the statistics
interface.
Each queue is implemented by instantiating an EventQueue object that registers
itself with the statistics subsystem using a category name constructed from the
logging agent type and the string pd.log.
An event queues statistics can be interrogated by using pdadmin server task
commands. To establish what queues are implemented on a server, issue the server
task server_name stats list command. A report similar to the following is returned:
pdadmin> server task ivacld-barra.surf.ap.tivoli.com stats list
pd.ras.stats.monitor
pd.log.EventPool.queue
// Main event propagation queue
pd.log.file.audit
// Audit log queue
pdadmin
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) : 3617
dispatcher wakes by notify : 0
notifies above highwater (100) : 0
notifies below highwater : 0
spurious notifies : 0
total events processed : 24
average number of events handled per activation : 1
greatest number of events handled per activation : 7
blocks in queue requests : 0
pdadmin>
The queues flush frequency is listed in parentheses after the word timeout. The
queue’s high water setting is listed in parentheses after the word highwater.
The settings chosen for the various queue configuration options should attempt to
balance the maximum amount of memory consumed between queue activations
with the rate a particular log agent can consume events.
Optimally you should set the queue high water mark such that the number of
events processed during a queue activation fills a processing time slice. This avoids
unnecessary thread context switching. Note however, that simply setting these
options to high values is unlikely to be productive since event log processing must
be done at some point and cannot be deferred indefinitely. Consuming large
amounts of memory also has its own drawbacks.
142
IBM Tivoli Access Manager: Base Administrator’s Guide
Appendix A. pdadmin commands
The pdadmin utility is a command line utility that you can use to perform most
Access Manager user and group administration tasks. The Web portal manager
provides many of these same commands through its graphical user interface. This
appendix lists, in alphabetical order, the commands available from the pdadmin
command prompt.
Introducing the pdadmin utility
The pdadmin utility is a command line utility that you can use to perform most
Access Manager user and group administration tasks. The Web portal manager
duplicates many pdadmin commands. However, pdadmin provides several
advanced management functions that are not available through the Web portal
manager.
You can automate certain management functions by writing scripts that use
pdadmin. The communication between the pdadmin utility and the policy server
(pdmgrd) is secured over SSL. The utility is installed as part of the Access
Manager runtime package.
Starting the pdadmin utility (login command)
v Interactive mode
v Single command line mode
v Multiple command execution
Interactive mode
To start pdadmin in interactive mode, you must enter the pdadmin command
followed by a login command with username (administrator) and password
options and arguments. The admin-user must be a registered user in an LDAP
registry.
UNIX:
# pdadmin
# login –a admin-user –p <password>
pdadmin>
Windows:
MSDOS> pdadmin
MSDOS> login –a admin-user –p password
pdadmin>
At the pdadmin prompt, enter appropriate commands, options, and arguments.
Refer to the command reference tables in this appendix.
Single command line mode
You can execute a single pdadmin command from the operating system command
prompt:
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 that
user.
v If you do not specify the admin-user (–a), you are logged in as an
unauthenticated user.
v If you specify the admin-user (–a), but do not specify a password (–p), you are
prompted for a password.
The optional command argument allows you to run one-time commands. For
example, the user “test” is created if you type following command.
pdadmin –a sec_master –p pwd user create test
cn=test,ou=austin,o=ibm,c=us test test test1234
Multiple command execution
You can create a special file that contains multiple pdadmin commands that
together perform a complete task or series of tasks. The pdadmin utility accepts a
filename 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 information
For 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 utility
To exit pdadmin and return to the command prompt, enter the exit or quit
command. For example:
pdadmin> exit
Special characters disallowed for GSO commands
You cannot use the following characters to create a GSO user name, GSO resource
name, or GSO resource group name:
!”#&()*+,;:<>=@\|
Although it is possible to use most of these characters for other LDAP-related
Access Manager data (such as the CN, DN, and SN of a user), these characters
have special meaning in LDAP DN syntax and filters. Before using any of these
characters in Access Manager user and group names, consult the documentation
for your LDAP server to determine the effect of special characters in LDAP.
144
IBM Tivoli Access Manager: Base Administrator’s Guide
Command syntax
The commands in this appendix use the following special characters to define
command syntax:
[]
Identifies elements that are optional. Those not enclosed in brackets are
required.
...
Indicates that you can specify multiple values for the previous element.
Separate multiple values by a space, unless otherwise directed by a
command’s information.
If the ellipsis for an element follows a closing bracket, use the syntax
within the brackets to specify multiple values. For example, to specify two
administrators for the option [–a admin]..., use –a admin1 –a admin2.
If the ellipsis for an element is within the brackets, use the syntax of the
last element to specify multiple values. For example, to specify two hosts
for the option [–h host...], use –h host1 host2.
|
Indicates mutually exclusive information. You can use the element on
either the left or right of the vertical bar.
{}
Delimits a set of mutually exclusive elements when one of them is
required. 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
Purpose
Attaches the specified access control list (ACL) to the specified protected object.
Syntax
acl attach object_name acl_name
Options
object_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.
Description
Attaches the specified access control list to the specified protected object. If the
specified protected object already has an ACL attached, this function replaces that
ACL with the new one. At most one ACL can be attached to a given protected
object. The same ACL can be attached to multiple protected objects. Understand
ACLs before using this function.
146
IBM Tivoli Access Manager: Base Administrator’s Guide
acl create
Purpose
Creates a new access control list (ACL).
Syntax
acl create acl_name
Options
acl_name
Specifies the name of the ACL policy being created. Note that this
command does not create the specific ACL entries.
Description
Creates a new access control list. This function creates a new ACL policy in the
ACL database. It does not create the specific ACL entries.
Appendix A. pdadmin commands
147
acl delete
Purpose
Deletes the specified access control list (ACL).
Syntax
acl delete acl_name
Options
acl_name
Specifies the name of the ACL policy being deleted from the ACL
database.
Description
Deletes the specified access control list.
148
IBM Tivoli Access Manager: Base Administrator’s Guide
acl detach
Purpose
Detaches the access control list (ACL) from the specified protected object.
Syntax
acl detach object_name
Options
object_name
Specifies the object from which the current ACL policy is being
removed. Note that this command does not delete the ACL policy
from the ACL database.
Description
Detaches the access control list from the specified protected object. Because only
one access control list at a time can be attached to an object, the currently attached
access control list is detached. Understand ACLs before using this function.
Appendix A. pdadmin commands
149
acl find
Purpose
Returns a list of protected objects that have the specified access control list (ACL)
attached.
Syntax
acl find acl_name
Options
acl_name
Specifies the ACL policy for which to search.
Description
Returns a list of protected objects which have the specified access control list
attached.
150
IBM Tivoli Access Manager: Base Administrator’s Guide
acl list
Purpose
Returns the names of all the defined access control lists.
Syntax
acl list
Options
None.
Description
Returns the names of all of the defined access control lists.
Appendix A. pdadmin commands
151
acl list attribute
Purpose
Lists the extended attribute keys associated with the specified access control list
(ACL).
Syntax
acl list acl_name attribute
Options
acl_name
Specifies the ACL policy for which to list the attributes.
Description
Lists the extended attribute keys associated with the specified access control list.
152
IBM Tivoli Access Manager: Base Administrator’s Guide
acl modify
Purpose
Modifies access control list (ACL) policies.
Syntax
acl 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
Options
acl_name
Specifies the ACL policy which will be modified.
delete attribute attribute_name
Deletes the specified extended attribute key from the specified
access control list.
delete attribute attribute_name attribute_value
Deletes the specified value from the specified extended attribute
key in the specified access control list.
description description
Set or modify the description for the specified access control list.
Appendix A. pdadmin commands
153
remove any-other
Removes the access control list entry for the user any-other from
the specified access control list.
remove group group_name
Removes the access control list entry for the specified group from
the specified access control list.
remove unauthenticated
Removes the access control list entry for the user unauthenticated
from the specified access control list.
remove user user_name
Removes the access control list entry for the specified user from
the specified access control list.
set any-other
Sets or modifies the access control list entry for the user any-other
in the access control list.
set any-other permissions
Sets or modifies the access control list entry for the user any-other
in the access control list.
set attribute attribute_name attribute_value
Sets the extended attribute value for the specified extended
attribute key in the specified access control list. If the attribute
already exists, the attribute value is added as an additional value if
the same value does not exist for this attribute. If the same value
exists for this attribute, it does not get added again (duplicate
values are not allowed), and no error is returned.
set description description
Sets or modifies the description for the specified access control list.
set group group_name
Sets or modifies the access control list (ACL) entry for the specified
group in the specified access control list. The user registry must
contain an entry for the specified group before you can call this
function to add an entry for the group to an ACL.
set group group_name permissions
Sets or modifies the access control list (ACL) entry for the specified
group in the specified access control list. The user registry must
contain an entry for the specified group before you can call this
function to add an entry for the group to an ACL.
set unauthenticated
Sets or modifies the access control list entry for the user
unauthenticated in the specified access control list.
set unauthenticated permissions
Sets or modifies the access control list entry for the user
unauthenticated in the specified access control list.
set user user_name
Call this function to specify the permissions that the user is
permitted to perform. The user registry must contain an entry for
the specified user before you can use this function to add an entry
for the user to an access control list (ACL).
set user user_name permissions
Call this function to specify the permissions that the user is
154
IBM Tivoli Access Manager: Base Administrator’s Guide
permitted to perform. The user registry must contain an entry for
the specified user before you can use this function to add an entry
for the user to an access control list (ACL).
Examples
1. 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 policy
definition and sets permissions.
pdadmin> acl modify pubs set group sales Tr
3. The following example sets the unathenticated ACL entry in the indicated ACL
policy definition and sets permissions.
pdadmin> acl modify docs set unauthenticated r
4. The following example sets a user ACL entry in the indicated ACL policy
definition and sets permissions.
pdadmin> acl modify pubs set user peter Tr
Appendix A. pdadmin commands
155
acl show
Purpose
Returns the specified access control list (ACL).
Syntax
acl show acl_name
Options
acl_name
Specifies the ACL policy which needs to be displayed.
Description
Returns the specified access control list.
156
IBM Tivoli Access Manager: Base Administrator’s Guide
acl show attribute
Purpose
Gets the extended attribute values for the specified extended attribute key from the
specified access control list.
Syntax
acl show acl_name attribute attribute_name
Options
acl_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 to
be displayed.
Description
Gets the extended attribute values for the specified extended attribute key from the
specified access control list.
Appendix A. pdadmin commands
157
action create
Purpose
Defines a new action (permission) code in an action group.
Syntax
action create action_name action_label action_type
action create action_name action_label action_type action_group_name
Options
action_group_name
Defines a new action (permission) code in the specified action
group. Call this function to add an action code to a user-defined
extended 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 given
action group
Description
Defines a new action (permission) code in an action group.
Actions codes consist of one alphabetic character (a–z or A–Z). Actions codes are
case-sensitive. Each action code only can be used once within an action group. Be
sure that you do not attempt to redefine the default action codes when adding new
codes to the primary group.
Examples
1. The following example creates a new permission character for the specified
action_label and action_type.
pdadmin> action create k time Ext-Authzn
158
IBM Tivoli Access Manager: Base Administrator’s Guide
action delete
Purpose
Deletes an action (permission) code from an action group. A specific action group
from which to delete an action can be defined by using the action_group_name
option.
Syntax
action delete action_name
action delete action_name action_group_name
Options
action_name
Specifies the name of the action to be deleted.
action_group_name
Specifies the name of the action group from which the specified
action needs to be deleted
Examples
1. 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
Appendix A. pdadmin commands
159
action group
Purpose
The following commands are used to create, delete, or display action groups.
Syntax
action group create action_group_name
action group delete action_group_name
action group list
Options
action_group_name
Specifies the name of the action group that needs to be created or
deleted.
Description
For 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 actions
that belong to the specified group.
For the list command, lists all the defined action group names.
160
IBM Tivoli Access Manager: Base Administrator’s Guide
action list
Purpose
Lists all the defined action (permission) codes from an action group. A specific
action group for which to list an action can be defined by using the
action_group_name option.
Syntax
action list
action list action_group_name
Options
action_group_name
Specifies the name of the action group for which all actions will be
displayed. Omission of this parameter will display actions defined
in the primary action group.
Examples
1. 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_name
command after the creation of an action group:
pdadmin> action group create agz
pdadmin> action create z actionz type1 agz
pdadmin> action list agz
z actionz type1
Appendix A. pdadmin commands
161
admin
Purpose
Displays the current server configuration information.
Syntax
admin show configuration
Options
None.
Description
Displays 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
Examples
1. The following example displays the current server configuration information:
pdadmin> admin show configuration
Output is similar to the following:
LDAP: TRUE
SECAUTHORITY: Default
GSO: TRUE
162
IBM Tivoli Access Manager: Base Administrator’s Guide
errtext
Purpose
Displays the error message of a given error number.
Syntax
errtext error_number
Options
error_number
Specifies the number of the error for which to generate the error
text.
Description
Displays the error message of a given error number. The error number may be in
either decimal or hexadecimal format.
Examples
1. The following is an example of the errtext command:
pdadmin> errtext 0x132120c8
Login failed. You have used an invalid username, password or client certificate.
Appendix A. pdadmin commands
163
exit
Purpose
Exits from the pdadmin command line mode.
Syntax
exit
Options
None.
164
IBM Tivoli Access Manager: Base Administrator’s Guide
group create
Purpose
Creates a group.
Syntax
group create groupname dn cn
group create groupname dn cn group_container
Options
groupname
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_container
Specifies the group container object assigned to the group being
created. If you do not use this argument, the group by default is
placed in the object space under /Management/Groups.
Description
Used without the group_container option, creates a new group by creating a new
group in the user registry with the specified name, registry identifier, and common
name.
Examples
1. The following example creates a group in the user registry.
pdadmin> group create credit “cn=credit,ou=Austin,o=Wesley Inc,c=US” Credit
Appendix A. pdadmin commands
165
group delete
Purpose
Deletes the specified group.
Syntax
group delete [-registry] groupname
Options
[-registry]
Deletes the user registry contents.
groupname
Specifies the name of the group to be deleted.
Description
Deletes the specified group. Deletes all information about the group and optionally
deletes the user registry contents.
Examples
1. The following example deletes the existing specified group.
pdadmin> group delete engineering
166
IBM Tivoli Access Manager: Base Administrator’s Guide
group import
Purpose
Creates an group by importing a group that already exists in the user registry.
Syntax
group import groupname dn
group import groupname dn group_container
Options
groupname
The name of the group to create.
dn
The registry identifier of the group to import.
group_container
Specifies the group container object assigned to the group being
created. If you do not use this argument, the group by default is
placed in the object space under /Management/Groups.
Examples
1. 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”
Appendix A. pdadmin commands
167
group list
Purpose
Lists the groups, listed by group names.
Syntax
group list pattern max_return
group list-dn pattern max_return
Options
pattern
Specifies the pattern for the group name for which to be searched.
The pattern can include a mixture of wildcards and string
constants, and is case insensitive (for example, *austin*).
max_return
Specifies the limit of how many entries should be returned for a
single request (for example, 2). Note that the number returned is
also governed by the server configuration (which specifies the
maximum number of results that can be returned as part of a
search operation). The actual maximum returned entries is the
minimum of max_return and the configured value on the server.
list-dn pattern max_return
Returns the list of user registry identifiers whose user registry
common name attribute matches the pattern specified. The
returned list are groups which are defined in the user registry but
are not necessarily Access Manager groups. Groups that are not
Access Manager groups may be imported into Access Manager by
use of the group import command.
Description
Lists the groups, listed by group names.
The order returned is the order created.
Examples
1. The following example lists groups matching the specified pattern:
pdadmin> group list *a* 3
Output would be similar to the following:
sales
marketing
Alex
2. The following example lists group information matching the specified common
name attribute pattern:
pdadmin> group list-dn *t* 2
Output would be similar to the following:
cn=credit,ou=Austin,o=Wesley Inc,c=US sales
cn=marketing,ou=Boston,o=Austin Sale,c=US marketing
168
IBM Tivoli Access Manager: Base Administrator’s Guide
group modify
Purpose
Modifies an existing group by adding a description, or adding or removing a list
of users.
Syntax
group modify groupname add user_list
group modify groupname description description
group modify groupname remove user_list
Options
groupname
Specifies the name of the group to be modified.
add user_list
Adds the specified users to the specified group. The format of the
user list is a parenthesized list of user names, separated by spaces.
description description
Changes the description for the specified group.
remove user_list
Removes the specified users from the specified group. The format
of the user list is a parenthesized list of user names, separated by
spaces.
Examples
1. 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"
Appendix A. pdadmin commands
169
group show
Purpose
Shows the properties of the specified group.
Syntax
group show groupname
group show-dn dn
group show-members groupname
Options
groupname
Specifies the name of the group to show.
show-dn dn
Show the group specified by the group’s identifier in the user
registry. The returned group is defined in the user registry but is
not necessarily an Access Manager group. Groups that are not
Access Manager groups may be imported into Access Manager by
use of the group import command.
show-members groupname
Lists the user names of the members of the specified group.
Examples
1. The following example displays properties of the specified group:
pdadmin> group show credit
Output would be similar to the following:
Group ID: credit
LDAP dn: cn=credit,ou=Austin,o=Wesley Inc,c=US
Description: Credit, Dept HCUS
LDAP cn: credit
Is SecGroup: true
2. The following example displays properties specified by the group’s identifier in
the user registry:
pdadmin> group show-dn cn=credit,ou=Austin,o=Wesley Inc,c=US
Output would be similar to the following:
Group ID: credit
LDAP dn: cn=credit,ou=Austin,o=Wesley Inc,c=US
Description: Credit, Dept HCUS
LDAP cn: credit
Is SecGroup: true
3. The following example lists the user names of the members of the specified
group:
pdadmin> group show-members credit
Output would be similar to the following:
dlucas
mlucaser
170
IBM Tivoli Access Manager: Base Administrator’s Guide
help
Purpose
Obtain system help for the pdadmin commands and options.
Syntax
help topic
help command
Options
topic
Specifies the general command topic for which help is needed.
command
Specifies the specific command for which help is needed.
Examples
1. The following example lists commands specified by the topic:
help action
Output would be similar to the following:
action create
action delete
action 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_type
action create action_name action_label action_type action_groupname
...
Appendix A. pdadmin commands
171
login
Purpose
Establishes authentication credentials used when communicating with the policy
server.
Syntax
login [-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.
Description
Establishes authentication credentials used when communicating with the policy
server. These credentials are used to determine a user’s access privileges to policy
server data.
Credentials are not ″stacked″. That is, a login operation will completely replace
any existing credentials.
172
IBM Tivoli Access Manager: Base Administrator’s Guide
logout
Purpose
Discards any authentication credentials that are in effect.
Syntax
logout
Options
None.
Description
Discards any authentication credentials that are in effect.
Exiting the pdadmin command line utility will discard the credentials.
Appendix A. pdadmin commands
173
object create
Purpose
Creates a new protected object.
Syntax
object create object_name description type ispolicyattachable {yes|no}
Options
object_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 and
displayed by the Web portal manager. Types range from 0-13. For
example, types 10 or 13 are appropriate for container objects.
ispolicyattachable {yes|no}
Specifies whether an ACL or a protected object policy can be
attached to this object.
174
IBM Tivoli Access Manager: Base Administrator’s Guide
object delete
Purpose
Deletes the specified protected object.
Syntax
object delete object_name
Options
object_name
Specifies the protected object to be deleted.
Description
Deletes the specified protected object.
Appendix A. pdadmin commands
175
object list
Purpose
Lists any objects grouped under the specified protected object.
Syntax
object list object_name
Options
object_name
Specifies the protected object.
Description
Lists any objects grouped under the specified protected object.
176
IBM Tivoli Access Manager: Base Administrator’s Guide
object list attribute
Purpose
Lists all the extended attributes associated with the specified protected object.
Syntax
object list object_name attribute
Options
object_name
Specifies the protected object.
Description
Lists all the extended attributes associated with the specified protected object.
Appendix A. pdadmin commands
177
object listandshow
Purpose
Lists any child objects grouped under the specified protected object and displays
all values associated with each of those objects.
Syntax
object listandshow object_name
Options
object_name
178
Specifies the protected object for which the child objects and
associated values are to be displayed.
IBM Tivoli Access Manager: Base Administrator’s Guide
object modify
Purpose
Modifies an existing object.
Syntax
object 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
Options
object_name
Specifies the protected object to be modified.
delete attribute attribute_name
Deletes the specified extended attribute (name and value) from the
specified protected object.
delete attribute attribute_name attribute_value
Deletes the specified value from the specified extended attribute
key in the specified protected object.
set attribute attribute_name attribute_value
Creates an extended attribute, with the specified name and value,
and adds it to the specified protected object. If the attribute already
exists, the attribute value is added as an additional value if the
same value does not exist for this attribute. If the same value exists
for this attribute, it does not get added again (duplicate values are
not allowed), and no error is returned.
set description description
Sets the description field of the specified protected object.
set ispolicyattachable {yes|no}
Sets the isPolicyAttachable attribute of the specified protected
object.
set name new_object_name
Sets the name of the specified protected object.
set type type
Sets the type field of the specified protected object.
Examples
1. The following example, entered on one line, sets the ispolicyattachable option.
pdadmin> object create /Management/Groups/Travel "Travel Container Object" \
14 ispolicyattachable yes
Appendix A. pdadmin commands
179
object show
Purpose
Returns the specified protected object.
Syntax
object show object_name
Options
object_name
Returns the specified protected object.
Description
Returns the specified protected object.
180
IBM Tivoli Access Manager: Base Administrator’s Guide
object show attribute
Purpose
Returns the value associated with the specified extended attribute for the specified
protected object.
Syntax
object show object_name attribute attribute_name
Options
object_name
Returns the specified protected object.
attribute_name
Specifies the name of the extended attribute whose values are to be
displayed.
Description
Returns the value associated with the specified extended attribute for the specified
protected object.
Appendix A. pdadmin commands
181
objectspace create
Purpose
Creates an protected object space.
Syntax
objectspace create objectspace_name description type
Options
objectspace_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.
Description
Creates an protected object space.
You must specify as the input parameter type, the object space type for each new
object space. The object space type is used by the Web portal manager to display
an appropriate icon with the object.
Note: The root of the new protected object space automatically has the
ispolicyattachable attribute set to true.
182
IBM Tivoli Access Manager: Base Administrator’s Guide
objectspace delete
Purpose
Deletes the specified protected object space.
Syntax
objectspace delete objectspace_name
Options
objectspace_name
Specifies the name of the objectspace to be deleted.
Description
Deletes the specified protected object space.
Appendix A. pdadmin commands
183
objectspace list
Purpose
Lists all the protected object spaces.
Syntax
objectspace list
Options
None.
Description
Lists all the protected object spaces.
184
IBM Tivoli Access Manager: Base Administrator’s Guide
policy get
Purpose
The policy get commands are a set of management commands that display specific
user password and account rules and conditions.
Syntax
policy 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. If
this option is not specified, the general policy is displayed. For any
given policy, if a user has a specific policy applied, this specific
policy takes precedence over any general policy that might also be
defined. The precedence applies regardless of whether the specific
policy is more or less restrictive than the general policy.
account-expiry-date
Displays the account expiration date for all user accounts.
disable-time-interval
Displays the time to disable user accounts when the maximum
number of login failures is exceeded. This setting applies to all user
accounts.
max-login-failures
Displays the maximum number of login failures allowed for each
user account.
max-password-age
Displays the maximum time a password will be valid for user
accounts.
max-password-repeated-chars
Displays the maximum number of repeated characters allowed in a
password for each user account.
Appendix A. pdadmin commands
185
min-password-alphas
Displays the minimum number of alphabetic characters required in
a password for each user account.
min-password-length
Displays the minimum password length for all user accounts.
min-password-non-alphas
Displays the minimum number of non-alphabetic characters
required in a password for each user account.
password-spaces
Displays whether spaces are allowed in passwords for all user
accounts.
tod-access
Displays the global time of day access policy.
Examples
1. 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 valid
for the specified user:
pdadmin> policy get max-password-age –user dlucas
186
IBM Tivoli Access Manager: Base Administrator’s Guide
policy set
Purpose
The policy set commands are a set of management commands that set specific user
password and account rules and conditions.
Syntax
policy 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_spectime_spec}[:{utc|local}]|unset} [-user user_name]
Options
[-user user_name]
Specifies the user whose policy information is to be set. If this
option is not specified, the general policy is set. For any given
policy, if a user has a specific policy applied, this specific policy
takes precedence over any general policy that might also be
defined. The precedence applies regardless of whether the specific
policy 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 maximum
number of login failures is exceeded. The default setting is 180.
max-login-failures number|unset
Sets the maximum number of login failures allowed for each user
account. The default setting is 10.
max-password-age {unset|relative_time}
Sets the maximum password age for all user accounts. The
relative_time option is relative to the last time the password was
changed.
max-password-repeated-chars number|unset
Sets the maximum number of repeated characters allowed in a
password for each user account. The default setting is 2.
Appendix A. pdadmin commands
187
min-password-alphas {unset|number}
Sets the minimum number of alphabetic characters required in a
password for each user account. The default setting is 4.
min-password-length {unset|number}
Sets the minimum password length for each user account. The
default setting is 8.
min-password-non-alphas {unset|number}
Sets the minimum number of non-alphabetic characters required in
a 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 is
local by default. (Note: utc=GMT)
Examples
1. 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
188
IBM Tivoli Access Manager: Base Administrator’s Guide
pop attach
Purpose
Attaches a protected object policy (POP) to the specified protected object.
Syntax
pop attach object_name pop_name
Options
object_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.
Description
Attaches a protected object policy to the specified protected object. At most, one
POP can be attached to a given protected object. If the object already has a POP
attached to it, the specified POP replaces the existing one. The same POP can be
attached to multiple protected objects. Be sure that the protected object exists in the
protect object space before attempting to attach a POP.
Appendix A. pdadmin commands
189
pop create
Purpose
Creates a protected object policy object.
Syntax
pop create pop_name
Options
pop_name
Specifies the name of the protected object policy to be created.
Description
Creates a protected object policy object.
190
IBM Tivoli Access Manager: Base Administrator’s Guide
pop delete
Purpose
Deletes the specified protected object policy.
Syntax
pop delete pop_name
Options
pop_name
Specifies the name of the protected object policy to be deleted.
Description
Deletes the specified protected object policy.
Appendix A. pdadmin commands
191
pop detach
Purpose
Detaches a protected object policy from the specified protected object.
Syntax
pop detach object_name
Options
object_name
Specifies the protected object from which the protected object
policy is to be deleted.
Description
Detaches a protected object policy from the specified protected object.
192
IBM Tivoli Access Manager: Base Administrator’s Guide
pop find
Purpose
Finds and lists all protected objects that have the specified protected object policy
attached.
Syntax
pop find pop_name
Options
pop_name
Specifies the name of the protected object policy for which to
search.
Description
Finds and lists all protected objects that have the specified protected object policy
attached.
Appendix A. pdadmin commands
193
pop list
Purpose
Lists all protected object policy objects.
Syntax
pop list
Options
None.
Description
Lists all protected object policy objects.
194
IBM Tivoli Access Manager: Base Administrator’s Guide
pop list attribute
Purpose
Lists all extended attributes associated with a protected object policy (POP).
Syntax
pop list pop_name attribute
Options
pop_name
Specifies the POP for which to list the attributes.
Description
Lists all extended attributes associated with a protected object policy.
Appendix A. pdadmin commands
195
pop modify
Purpose
Modifies protected object policies.
Syntax
pop 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}
Options
pop_name
Specifies the name of the protected object policy to be modified.
delete attribute attribute_name
Deletes the specified extended attribute from the specified
protected object policy.
delete attribute attribute_name attribute_value
Deletes the specified value from the specified extended attribute
key in the specified protected object policy.
set attribute attribute_name attribute_value
Sets or modifies the specified value from the specified extended
attribute key in the specified protected object policy. If the attribute
already exists, the attribute value is added as an additional value if
the same value does not exist for this attribute. If the same value
exists for this attribute, it does not get added again (duplicate
values 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 description
Sets the description of the specified protected object policy.
196
IBM Tivoli Access Manager: Base Administrator’s Guide
set ipauth add network netmask authority_level
Sets the IP endpoint authentication settings in the specified
protected object policy.
set ipauth anyothernw authority_level
Sets the anyothernw, or any other network, setting for the IP
authentication level from the specified protected object policy
(POP). If controlling access by IP address is not important, use the
anyothernw setting to set the authentication level for all IP
addresses and IP address ranges not listed explicitly in the POP.
set ipauth remove network netmask
Removes the IP endpoint authentication settings from the specified
protected object policy.
set qop {none|integrity|privacy}
Sets the quality of protection level for the specified protected object
policy. The following string values are supported:
v none
v integrity
v privacy
set tod-access {anyday|weekday|day_list}:{anytime|time_spectime_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.
Appendix A. pdadmin commands
197
pop show
Purpose
Show details of the protected object policy (POP).
Syntax
pop show pop_name
Options
pop_name
Specifies the POP which needs to be displayed.
Description
Show details of the protected object policy.
198
IBM Tivoli Access Manager: Base Administrator’s Guide
pop show attribute
Purpose
Displays the values for the specified extended attribute from the specified
protected object policy (POP).
Syntax
pop show pop_name attribute attribute_name
Options
pop_name
Specifies the POP whose attribute needs to be displayed.
attribute_name
Specifies the name of the extended attribute whose values need to
be displayed.
Description
Displays the values for the specified extended attribute from the specified
protected object policy.
Appendix A. pdadmin commands
199
quit
Purpose
Exits from the pdadmin command line mode.
Syntax
quit
Options
None.
200
IBM Tivoli Access Manager: Base Administrator’s Guide
rsrc create
Purpose
Creates a single signon Web resource
Syntax
rsrc create resource_name [–desc description]
Options
resource_name
Specifies the name of the resource to be created.
[–desc description]
Specifies a description for the resource. Descriptions containing a
space must be enclosed in double quotes.
Description
Creates a single signon Web resource. A Web resource is a Web server that serves
as the backend of an WebSEAL junction.
Examples
1. 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”
Appendix A. pdadmin commands
201
rsrc delete
Purpose
Deletes the specified single signon Web resource.
Syntax
rsrc delete resource_name
Options
resource_name
Specifies the name of the resource to be deleted. The resource must
exist or an error is displayed.
Description
Deletes the specified single signon Web resource.
Examples
1. The following example deletes the named resource with its associated
description:
pdadmin> rsrc delete engwebs01
202
IBM Tivoli Access Manager: Base Administrator’s Guide
rsrc list
Purpose
Returns a list of all the single signon Web resource names.
Syntax
rsrc list
Options
None.
Description
Returns a list of all the single signon Web resource names.
Examples
1. The following example returns a list of all the single signon Web resource
names:
pdadmin> rsrc list
Output is similar to the following:
engwebs01
engwebs02
engwebs03
Appendix A. pdadmin commands
203
rsrc show
Purpose
Returns information for the specified single signon Web resource.
Syntax
rsrc show resource_name
Options
resource_name
Specifies the name of the resource for which information will be
shown. The resource must exist or an error is displayed.
Description
Returns information for the specified single signon Web resource.
Examples
1. The following example returns information for the specified resource:
pdadmin> rsrc show engwebs01
Output would be similar to:
Web Resource Name: engwebs01
Description: Engineering Web server - Room 4807
204
IBM Tivoli Access Manager: Base Administrator’s Guide
rsrccred create
Purpose
Creates a single signon credential.
Syntax
rsrccred create resource_name rsrcuser resource_userid rsrcpwd resource_password
rsrctype {web|group} user username
Options
resource_name
Specifies the name given to the resource when the resource was
created. The resource (or resource group) must already exist in
order to create the resource credential. If the resource (or resource
group) does not exist or is not specified, an error message is
displayed.
rsrcuser resource_userid
Specifies the unique user identification (user ID) for the user at the
Web server.
rsrcpwd resource_password
Specifies 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 credential
information applies. If the user does not exist or is not specified,
an error message is displayed.
Description
Creates a single signon credential.
Examples
1. 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
Appendix A. pdadmin commands
205
rsrccred delete
Purpose
Deletes a single signon credential.
Syntax
rsrccred delete resource_name rsrctype {web|group} user username
Options
resource_name
Specifies the name given to the resource when the resource was
created.
rsrctype {web|group}
Specifies the resource type. The type of resource must match the
resource type assigned when the resource was first created.
user username
Specifies the name of the user for whom the resource credential
information applies.
Description
Deletes a single signon credential.
Examples
1.
The following example deletes the resource credential information for the
given resource, resource type, and username:
pdadmin> rsrccred delete engwebs01 rsrctype web user dlucas
206
IBM Tivoli Access Manager: Base Administrator’s Guide
rsrccred list user
Purpose
Returns the list of single signon credentials for the specified user.
Syntax
rsrccred list user username
Options
username
Specifies the name of the user for whom the resource credential
information applies.
Description
Returns the list of single signon credentials for the specified user.
Examples
1.
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
Resource
Resource
Resource
name:
Type:
name:
Type:
engwebs01
group
engwebs02
web
Appendix A. pdadmin commands
207
rsrccred modify
Purpose
Creates or modifies a single signon credential.
Syntax
rsrccred modify resource_name rsrctype {web|group} set [–rsrcuser resource_userid]
[– rsrcpwd resource_password] user username
Options
resource_name
Specifies the name given to the resource when the resource was
created.
rsrctype {web|group}
Specifies the resource type. The type of resource must match the
resource type assigned when the resource was first created.
[–rsrcuser resource_userid]
Specifies the unique user identification (user ID) for the user at the
Web server. To change or reset the resource user ID of the user or
password information, these optional commands must be preceded
by a dash ( – ).
[– rsrcpwd resource_password]
Specifies the password for a user at the Web server. Specifying this
parameter without specifying the -rsrcuser parameter will clear
both the resource user ID and the resource password. To simply set
the resource password, you must specify both the resource user ID
and the resource password.
user username
Specifies the name of the user for whom the resource credential
information applies.
Description
Creates or modifies a single signon credential.
Examples
1.
The following example, entered as one line, modifies the specified resource:
pdadmin> rsrccred modify engwebs01 rsrctype web \
set –rsrcuser 4807ws01 –rsrcpwd newrsrpw user dlucas
208
IBM Tivoli Access Manager: Base Administrator’s Guide
rsrccred show
Purpose
Returns the specified single signon credential. The credential identifier is composed
of a resource name, a resource type, and an user name.
Syntax
rsrccred show resource_name rsrctype {web|group} user username
Options
resource_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 the
credential.
user username
Specifies the name of the user associated with this credential.
Description
Returns the single signon credential specified by the given resource, resource type,
and user.
Examples
1.
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: engwebs01
Resource Type: group
Resource User Id: dlucas
Appendix A. pdadmin commands
209
rsrcgroup create
Purpose
Creates a single signon group resource.
Syntax
rsrcgroup create resource_group_name [–desc description]
Options
resource_group_name
Specifies the name of the resource group.
[–desc description]
The description argument is an optional description that can be
added to identify this resource group. The optional –desc
parameter must be preceded with a dash ( – ). Descriptions that
have spaces need to be enclosed in double quotes.
Description
Creates a single signon group resource.
Examples
1. 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”
210
IBM Tivoli Access Manager: Base Administrator’s Guide
rsrcgroup delete
Purpose
Deletes a single signon group resource.
Syntax
rsrcgroup delete resource_group_name
Options
resource_group_name
Specifies the name of the resource group. The resource group must
exist.
Description
Deletes a single signon group resource, including any description information.
Examples
1. The following example deletes the named resource group and its associated
description information:
pdadmin> rsrcgroup delete webs4807
Appendix A. pdadmin commands
211
rsrcgroup list
Purpose
Returns a list of all of the single signon group resource names.
Syntax
rsrcgroup list
Options
None.
Description
Returns a list of all of the single signon group resource names.
Examples
1. 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:
webs4807
websbld3
212
IBM Tivoli Access Manager: Base Administrator’s Guide
rsrcgroup modify
Purpose
Adds or removes a single signon resource to or from a single signon resource
group.
Syntax
rsrcgroup modify resource_group_name add rsrcname resource_name
rsrcgroup modify resource_group_name remove rsrcname resource_name
Options
resource_group_name
Specifies the name of the resource group to be modified.
add rsrcname resource_name
Adds a single signon resource to the specified single signon
resource group.
remove rsrcname resource_name
Removes a single signon resource from the specified single signon
resource group.
Description
Adds or removes a single signon resource to or from a single signon resource
group.
Examples
1. 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 Web
resource group:
pdadmin> rsrcgroup modify webs4807 remove rsrcname engwebs02
Appendix A. pdadmin commands
213
rsrcgroup show
Purpose
Returns the specified single signon group resource.
Syntax
rsrcgroup show resource_group_name
Options
resource_group_name
Specifies the name of the resource group. The resource group must
exist or an error message displays.
Description
Returns the specified single signon group resource. The resource group name, the
resource group description, and a list of the names of the resource group members
are displayed. The resource group members are the individual Web resources
(servers).
Examples
1. The following example returns the specified single signon group resource:
pdadmin> rsrcgroup show webs4807
Output would be similar to the following:
Resource Group Name: webs4807
Description: Web servers, Room 4807
Resource Members:
engwebs01
engwebs02
engwebs03
214
IBM Tivoli Access Manager: Base Administrator’s Guide
server list
Purpose
Lists all registered servers.
Syntax
server list
Options
None.
Description
Lists all registered servers. Note that the server name format displayed by this
command should be used for the server_name argument in the other pdadmin
server commands.
Examples
1. The following example lists all registered servers:
pdadmin> server list
Output would be similar to the following:
ivacld-topserver
ivacld-server2
ivacld-server3
ivacld-server4
Appendix A. pdadmin commands
215
server listtasks
Purpose
Displays the list of available tasks from the server.
Syntax
server listtasks server_name
Options
server_name
Specifies the name of the server for which available tasks
(commands) will be listed.
Description
Displays the list of available tasks from the server.
Examples
1. 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
trace
trace
stats
stats
stats
stats
stats
stats
216
set component level [file path=file|other-log-agent-config]
show [component]
list [component]
show [component]
list
on [component] [interval] [count] [file path= file|other-log-agent-config]
off [component]
reset [component]
get [component]
IBM Tivoli Access Manager: Base Administrator’s Guide
server replicate
Purpose
Notify authorization servers to receive database updates.
Syntax
server replicate [–server server_name]
Options
[–server server_name]
Specifies the name of the server to receive database updates. If this
option is not specified, all servers configured to receive updates are
notified.
Description
Notify authorization servers to receive database updates. If a server name is
specified, but is not configured to receive database updates, an error message
displays. If no server name is specified, the process of notifying all configured
servers is initiated, but error messages are not displayed for individual servers.
Examples
1. The following is an example of this command when specifying the server_name:
pdadmin> server replicate -server ivacld-topserver
Appendix A. pdadmin commands
217
server show
Purpose
Displays the specified server’s properties.
Syntax
server show server_name
Options
server_name
Specifies the name of the server whose properties are to be
displayed.
Description
Displays the specified server’s properties.
Examples
1. 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/topserver
Hostname: topserver
Principal: ivacld/topserver
Port: 7137
Listening for authorization database update notifications: yes
AZN Administration Services:
AZN_ADMIN_SVC_TRACE
218
IBM Tivoli Access Manager: Base Administrator’s Guide
server task
Purpose
Sends a command to an authorization server.
Syntax
server task server_name server_task
Options
server_name
Specifies the name of the server to which the server_task will be
sent.
server_task
Specifies the task (command) being sent.
Description
Sends a command to an authorization server.
Examples
1. 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.monitor
pd.log.EventPool.queue
Appendix A. pdadmin commands
219
user create
Purpose
Creates a user in the user registry used by the policy server and initially associates
that user with one or more groups.
Syntax
user 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 this
rule, the –no-password-policy option is provided only for creating
a user with an initial password. It is recommended that the initial
password be changed.
username
Specifies the name for the user being created. This name must be
unique.
dn
Specifies the registry identifier assigned to the user being created.
The registry identifier must be known before a new user account
can be created. The registry identifier must be unique within the
user 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 must
adhere to the password policies set by the administrator.
[groups]
This optional argument specifies a list of groups to which the new
user is assigned. The format of the group list is a parenthesized list
of group names, separated by spaces.
Description
Creates a user in the user registry used by the policy server and initially associates
that user with one or more groups. Accounts are created invalid by default.
Examples
1. 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 set
the account-valid flag to yes.
220
IBM Tivoli Access Manager: Base Administrator’s Guide
user delete
Purpose
Deletes the user and optionally deletes the user from the user registry.
Syntax
user 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 resource
credentials associated with a user account are automatically
removed at the same time the user account is deleted.
Description
Deletes information about the user from the user registry. The optional -registry
parameter 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 create
an user with the user import command.
Examples
1. The following example deletes the account of the specified user:
pdadmin> user delete dlucas
Appendix A. pdadmin commands
221
user import
Purpose
Creates an user by importing an existing user from the user registry.
Syntax
user 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 information
that already exists in the user registry.
dn
The registry identifier of the user being imported. This identifier
must exist in the user registry and must not be associated with an
existing user.
[group_name]
Specifies the group to which the imported user is being assigned.
Description
Creates an user by importing an existing user in the user registry. Imported user
accounts are created invalid by default. To make the user account valid, you must
use the user modify command to set the account-valid flag to yes.
Examples
1. The following example, entered on one line, creates the user ″mlucas″ by
importing information from the registry user ″cn=Mike
Lucaser,ou=Austin,o=Wesley Inc, c=US″:
pdadmin> user import –gsouser mlucaser “cn=Mike \
Lucaser,ou=Austin,o=Wesley Inc,c=US”
222
IBM Tivoli Access Manager: Base Administrator’s Guide
user list
Purpose
Lists the users, listed by user names.
Syntax
user list pattern max_return
user list-dn pattern max_return
Options
list-dn
Specifies the pattern for the principal name. The pattern can
include a mixture of wildcards and string constants, and is case
sensitive (for example, *luca*). The returned list are users which
are defined in the user registry but are not necessarily Access
Manager users. Users that are not Access Manager users may be
imported into Access Manager by use of the user import
command.
pattern
Specifies the pattern for the principal name. The pattern can
include a mixture of wildcards and string constants, and is case
sensitive (for example, *luca*). When used with the list-dn
command, the argument specifies the pattern for the common
name (CN) portion of the user’s registry identifier (excluding the
″cn=″ component).
max_return
Specifies the maximum number of entries that are found and
returned for a single request. Note that the number returned is also
governed by the server configuration (which specifies the
maximum number of results that can be returned as part of a
search operation). The actual maximum returned entries is the
minimum of max_return and the configured value on the server.
Description
Lists the users, listed by user names.
Examples
1. The following example lists the users matching the specified pattern:
pdadmin> user list *luca* 2
Output would be similar to the following:
dlucas
mlucaser
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=US
cn=Mike Lucaser,ou=Austin,o=Wesley, Inc,c=US
Appendix A. pdadmin commands
223
user modify
Purpose
Modifies various user account parameters
Syntax
user 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}
Options
username
Specifies the name of the account to be modified.
account-valid {yes|no}
Enables or disables the specified user account.
description description
Modifies the user description.
gsouser {yes|no}
Enables or disables the single signon capabilities of an user.
password password
Modifies the user password. The new password must comply with
password policies in effect.
password-valid {yes|no}
Validates or invalidates the user’s account password. Setting the
password-valid flag to no forces the user to change the password
at the next login attempt.
Examples
1. 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 change
the password at the next login.
pdadmin> user modify dlucas password-valid no
224
IBM Tivoli Access Manager: Base Administrator’s Guide
user show
Purpose
Displays the properties of the specified user.
Syntax
user show username
user show-groups username
user show-dn dn
Options
username
Specifies the name of the user to display.
show-groups username
Displays the groups in which the specified user is a member.
show-dn dn
Display the user specified by the user’s identifier in the user
registry. The returned user is defined in the user registry but is not
necessarily an Access Manager user. Users that are not Access
Manager users may be imported into Access Manager by use of the
user import command.
Examples
1. 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: dlucas
LDAP dn: cn=Diana Lucas,ou=Austin,o=Wesley Inc,c=US
LDAP cn: Diana Lucas
LDAP sn: Lucas
Description: Diana Lucas, Credit Dept HCUS
IS SecUser: true
IS GSO user: false
Account valid: true
Password valid: true
Authentication mechanism: Default:LDAP
2. The following example displays the groups of which the specified user is a
member:
pdadmin> user show-groups dlucas
Output would be similar to the following:
sales
credit
engineering
3. The following example provides additional information about the user when
specifying the registry identifier:
pdadmin> user show-dn “cn=Diana Lucas,ou=Austin,o=Wesley Inc,c=US”
Output would be similar to the following:
Appendix A. pdadmin commands
225
Login ID: dlucas
LDAP dn: cn=Diana Lucas,ou=Austin,o=Wesley
Inc,c=US
LDAP cn: Diana Lucas
LDAP sn: Lucas
Description: Diana Lucas, Credit Dept HCUS
IS SecUser: true
IS GSO user: false
Account valid: true
Password valid: true
Authentication mechanism: Default:LDAP
226
IBM Tivoli Access Manager: Base Administrator’s Guide
Appendix B. ivmgrd.conf reference
ivmgrd.conf configuration file for the policy server (pdmgrd).
Stanzas:
v
v
v
v
v
v
v
[ivmgrd]
[ldap]
[ssl]
[authentication-mechanisms]
[object-spaces]
[aznapi-configuration]
[aznapi-entitlement-services]
v [aznapi-pac-services]
v [aznapi-cred-modification-services]
v [aznapi-external-authzn-services]
v [delegated-admin]
Parameter
Description
[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 for
authorization database replicas.
notifier-wait-time
Time (in seconds) the authorization policy database is
idle 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 query
the read/write LDAP server before querying any
replica read-only servers configured in the domain.
bind-dn
The LDAP user DN used when binding to the LDAP
server.
bind-pwd
The LDAP user password.
ssl-enabled
Enable and disable SSL communication with the LDAP
server.
ssl-keyfile
Location of SSL key file used to handle certificates used
in LDAP communication.
ssl-keyfile-dn
Certificate label in the SSL key file.
227
Parameter
Description
ssl-keyfile-pwd
SSL key file password.
auth-using-compare
Choose whether ldap_compare() is used instead of the
ldap_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 waits
for a response before timing out
ssl-maximum-worker-threads
Maximum number of threads created by the server to
handle 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 SSL
certificate and the key database file password. If
enabled, the certificate and password are regenerated
when 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
228
IBM Tivoli Access Manager: Base Administrator’s Guide
Parameter
authorize-group-list
Description
Enable and disable authorization checks on the group
list and group list-dn commands.
Appendix B. ivmgrd.conf reference
229
230
IBM Tivoli Access Manager: Base Administrator’s Guide
Appendix C. ivacld.conf reference
ivacld.conf configuration file for the authorization server (pdacld).
Stanzas:
v
v
v
v
v
v
v
[ivacld]
[ldap]
[ssl]
[manager]
[authentication-mechanisms]
[aznapi-configuration]
[aznapi-entitlement-services]
v [aznapi-pac-services]
v [aznapi-cred-modification-services]
v [aznapi-admin-services]
Parameter
Description
[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 clients
should be authorized by the authorization
server before their requests are processed.
[ldap] stanza
enabled
Enable and disable LDAP user registry
support.
host
LDAP server host name.
port
The IP port used when binding to the LDAP
server.
bind-dn
The LDAP user DN used when binding to the
LDAP server.
bind-pwd
The LDAP user password.
cache-enabled
Enable and disable LDAP client-side caching to
improve performance for similar LDAP
queries.
prefer-readwrite-server
Enable and disable the choice for the client to
query the read/write LDAP server before
querying any replica read-only servers
configured in the domain.
ssl-enabled
Enable and disable SSL communication with
the LDAP server.
231
Parameter
Description
ssl-keyfile
Location of SSL key file used to handle
certificates 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 the
LDAP server in entries.
ssl-port
SSL port to listen on for LDAP communication.
auth-using-compare
Choose whether ldap_compare() is used
instead of the ldap_bind() call to authenticate
LDAP users.
ldap-replica
Define the LDAP user registry replicas in the
domain.
[ssl] stanza
ssl-keyfile
Location of the SSL keyfile.
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 waits for a response before timing
out
ssl-maximum-worker-threads
Maximum number of threads created by the
server to handle 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 SSL
certificate and the key database file password.
If enabled, the certificate and password are
regenerated 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 for
requests.
master-dn
The expected Distinguished Name of the
certificate 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
232
IBM Tivoli Access Manager: Base Administrator’s Guide
Parameter
Description
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 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 the
master authorization server.
permission-info-returned
max-handle-groups
Maximum number of handle groups to
allocate.
listen-flags
Enable and disable the receiving of policy
cache update notifications.
[aznapi-entitlement-services] stanza
Defines authorization API services.
[aznapi-pac-services] stanza
AZN_V37CRED_SVC
A service to convert between Tivoli SecureWay
Policy Director, Version 3.7 credentials and
Tivoli SecureWay Policy Director, Version 3.8
credentials. Allows support of remote
authorization requests from Tivoli SecureWay
Policy Director, Version 3.7 authorization API
applications.
[aznapi-cred-modification-services] stanza
AZN_MOD_SVC_RAD_2AB
A credential modification service that allows
groups to be dynamically appended to an
existing credential. This action can give the
owner of the credential additional
authorization capability.
[aznapi-admin-services] stanza
AZN_ADMIN_SVC_TRACE
Enable and disable (using pdadmin) trace
administration for an authorization API
application.
Appendix C. ivacld.conf reference
233
234
IBM Tivoli Access Manager: Base Administrator’s Guide
Appendix D. ldap.conf reference
Stanzas:
v [ldap]
Parameter
Description
[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 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 database items
- such as a request for the Web portal manager to list users from the
LDAP database.
replica
Replica LDAP server entry.
235
236
IBM Tivoli Access Manager: Base Administrator’s Guide
Appendix E. pd.conf reference
pd.conf configuration file
Stanzas:
v
v
v
v
[pdrte]
[ssl]
[manager]
[ldap-ext-cred-tags]
Parameter
Description
[pdrte] stanza
configured
Indicates whether the Access Manager runtime
package has been configured.
user-reg-type
User registry type. (Currently only LDAP is
supported.)
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 system
boot.
boot-start-ivacld
Start the authorization server (pdacld) at
system boot.
[ssl] stanza
ssl-keyfile
Location on the local system of the SSL key
file.
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 the
default.
ssl-v3-timeout
Session ID timeout for SSL v3 connections.
ssl-pwd-life
SSL password lifetime - in days.
ssl-io-inactivity-timeout
The duration (in seconds) that an SSL
connection waits for a response before timing
out.
ssl-auto-refresh
Enable or disable automatic refresh of the key
database certificates and passwords.
[manager] stanza
master-host
Host name of the MTS server.
master-port
TCP port number on which the server is
listening for requests.
replica
Authorization server replicas.
[ldap-ext-cred-tags] stanza
237
Parameter
credential-field-name =
ldap-inetOrgPerson-field
238
IBM Tivoli Access Manager: Base Administrator’s Guide
Description
Mechanism to add extended attributes to the
Access Manager credential from existing fields
in the inetOrgPerson LDAP object class.
Appendix F. SSL configuration commands
This appendix lists, in alphabetical order, the commands related to Secure Sockets
Layer (SSL) configuration.
Command parameters are dependent upon the action being taken. Parameters may
be specified in any order.
Command syntax
The commands in this appendix use the following special characters to define
command syntax:
[]
Identifies elements that are optional. Those not enclosed in brackets are
required.
...
Indicates that you can specify multiple values for the previous element.
Separate multiple values by a space, unless otherwise directed by a
command’s information.
If the ellipsis for an element follows a closing bracket, use the syntax
within the brackets to specify multiple values. For example, to specify two
administrators for the option [–a admin]..., use –a admin1 –a admin2.
If the ellipsis for an element is within the brackets, use the syntax of the
last element to specify multiple values. For example, to specify two hosts
for the option [–h host...], use –h host1 host2.
|
Indicates mutually exclusive information. You can use the element on
either the left or right of the vertical bar.
{}
Delimits a set of mutually exclusive elements when one of them is
required. If the elements are optional, they are enclosed in brackets ([ ]).
239
bassslcfg –chgpwd
Purpose
Changes the key database password. A new random password is generated and
saved in the stash file.
Syntax
bassslcfg –chgpwd –e pwd_life
Options
–e pwd_life
240
Sets the keyring file password expiration time in days. You can
specify a pwd_life value from 1 to 7200 (days). To use the currently
configured value, specify 0. If you cannot determine the currently
configured value, specify 183.
IBM Tivoli Access Manager: Base Administrator’s Guide
bassslcfg –config
Purpose
Configures the Access Manager runtime so as to allow the pdadmin utility to
communicate with the policy server. Also creates new key and stash files.
Syntax
bassslcfg –config –c cert_file –h host_name [–p server_port] [–e pwd_life] [–t
ssl_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 default
value is 7135.
[–e pwd_life]
Sets the keyring file password expiration time in days. You can
specify a pwd_life value from 1 to 7200 (days). The default value is
183. To use the currently configured value, specify 0.
[–t ssl_timeout] Specifies the SSL session timeout in seconds. You can specify an
ssl_timeout value from 1 to 86400 (seconds). The default value is
7200.
Appendix F. SSL configuration commands
241
bassslcfg –getcacert
Purpose
Downloads the root CA certificate to a file.
Syntax
bassslcfg –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 default
value is 7135.
242
IBM Tivoli Access Manager: Base Administrator’s Guide
bassslcfg –modify
Purpose
Modifies the Access Manager policy server configuration.
Syntax
bassslcfg –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 can
specify a pwd_life value from 1 to 7200 (days). The default value is
183. To use the currently configured value, specify 0.
[–p server_port]
Specifies the listening port number of the policy server.
[–t ssl_timeout] Specifies the SSL session timeout in seconds. You can specify an
ssl_timeout value from 1 to 86400 (seconds). The default value is
7200.
Appendix F. SSL configuration commands
243
bassslcfg –ping
Purpose
Pings an Access Manager server.
Syntax
bassslcfg –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 server
that you want to ping. The default value is 7135.
244
IBM Tivoli Access Manager: Base Administrator’s Guide
mgrsslcfg –chgcert
Purpose
Renews the manager’s SSL certificate. A new public-private key pair and certificate
is created and stored in the key database.
Syntax
mgrsslcfg –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. To
use the currently configured value, specify 0.
Appendix F. SSL configuration commands
245
mgrsslcfg –chgpwd
Purpose
Changes the key database password. A new random password is generated and
saved in the stash file.
Syntax
mgrsslcfg –chgpwd –e pwd_life
Options
–e pwd_life
246
Sets the keyring file password expiration time in days. You can
specify a pwd_life value from 1 to 7200 (days). To use the currently
configured value, specify 0. If you cannot determine the currently
configured value, specify 183.
IBM Tivoli Access Manager: Base Administrator’s Guide
mgrsslcfg –config
Purpose
Performs full configuration, creating new key and stash files and generating new
certificates.
Syntax
mgrsslcfg –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 a
cert_life value from 1 to 7300 (days). The default value is 365.
[–t ssl_timeout] Specifies the SSL session timeout in seconds. You can specify an
ssl_timeout value from 1 to 86400 (seconds). The default value is
7200.
[–D {yes|no}] Specify yes to enable downloading of the secure domain’s CA
certificate. If you specify no, you must manually transfer the
pdcacert.b64 file to subsequent hosts to configure an Access
Manager runtime. The default value is no.
Appendix F. SSL configuration commands
247
mgrsslcfg –modify
Purpose
Modifies the current configuration.
Syntax
mgrsslcfg –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 not
required with the –config action and defaults to 365 days if not
specified.
[–t ssl_timeout] Specifies the SSL session timeout in seconds. The ssl_timeout value
must be in the range 1–86400. The default value is 7200.
[–D {yes|no}] Enables downloading of the secure domain’s CA certificate. If
enable download is no, you must transfer the pdcacert.b64 file to
subsequent hosts in order to configure Access Manager runtime on
them. On initial configuration, the default value is no.
248
IBM Tivoli Access Manager: Base Administrator’s Guide
svrsslcfg –add_replica
Purpose
Adds a database replica.
Syntax
svrsslcfg –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. The
default value is 7136.
[–k replica_rank]
Specifies the replica order of preference among other replicas. The
default value is 10.
Appendix F. SSL configuration commands
249
svrsslcfg –chg_replica
Purpose
Changes replica options. The replica host name is used to identify the replica and
cannot be changed by this action.
Syntax
svrsslcfg –chg_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. If not
specified on an –add_replica action, a default of 7136 is used.
[–k replica_rank]
Specifies the replica order of preference among other replicas. The
default value is 10.
250
IBM Tivoli Access Manager: Base Administrator’s Guide
svrsslcfg –chgcert
Purpose
Renews the server’s SSL certificate.
Syntax
svrsslcfg –chgcert –f cfg_file –n server_name [–P admin_pwd] [–A admin_id]
Options
–f cfg_file
Specifies the configuration file path and name.
–n server_name Specifies the name of the server. The name may be specified as
either server_name/host name or server_name, in which case the
local host name is appended to form name/host name. Note that
the names ivacld, secmgrd, ivnet, and ivweb are reserved for
Access Manager servers.
[–P admin_pwd]
Specifies the Access Manager administrator password. If this
option is not specified, the password is read from standard input.
[–A admin_id]
Specifies the Access Manager administrator name. The default is
sec_master.
Appendix F. SSL configuration commands
251
svrsslcfg –chgport
Purpose
Changes the listening port number.
Syntax
svrsslcfg –chgport –f cfg_file –r port_number
Options
–f cfg_file
Specifies the configuration file path and name.
–r port_number Sets the listening port number for the server. A value of 0 may be
specified only if the [aznapi-admin-services] stanza in the
configuration file is empty.
252
IBM Tivoli Access Manager: Base Administrator’s Guide
svrsslcfg –chgpwd
Purpose
Changes the keyring file password.
Syntax
svrsslcfg –chgpwd –f cfg_file –e pwd_life
Options
–f cfg_file
Specifies the configuration file path and name.
–e pwd_life
Sets the keyring file password expiration time in days. The pwd_life
value is 1 to 7200 (days). The default value is 183. To use the
currently configured value, specify 0.
Appendix F. SSL configuration commands
253
svrsslcfg –config
Purpose
Changes the keyring file password.
Syntax
svrsslcfg –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] [–l
listening_mode] [–a refresh_mode] [–C cert_file] [–h host_name]
Options
–f cfg_file
Specifies the configuration file path and name.
–d kdb_dir
Specifies the directory that is to contain the keyring database files
for the server.
–n server_name Specifies the name of the server. The name may be specified as
either server_name/host name or server_name, in which case the
local host name is appended to form name/host name. Note that
the names ivacld, secmgrd, ivnet, and ivweb are reserved for
Access Manager servers.
–s server_type
Specifies the type of server being configured. The value must be
either local or remote.
–r port_number Sets the listening port number for the server. This is a required
option. 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 a
required option. If this option is not specified, the password is read
from 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 by
specifying a dash (-) for the password. If this option is used, the
configuration file is updated with the password created by the
system. If the user registry type is LDAP and a password is
specified, it is saved in the configuration file. If this option is
absent, the server password is read from standard input.
[–A admin_id]
Specifies the Access Manager administrator name. If this option is
not specified, sec_master is the default.
[–t ssl_timeout] Specifies the SSL session timeout in seconds. The ssl_timeout value
must be in the range 1–86400. The default value is 7200.
[–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 listening_mode]
Sets the listening-enabled flag in the configuration file. The value
of 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
254
IBM Tivoli Access Manager: Base Administrator’s Guide
–modify action, a value of yes requires that the listening port
number in the configuration file be non zero.
[–a refresh_mode]
Sets the certificate and keyring file password auto-refresh enabled
flag in the configuration file. The value of this option must be yes
or no. If not specified, the default is yes.
[–C cert_file]
Specify the fully qualified name of the file containing the base-64
encoded SSL certificate used when the server authenticates directly
with the user registry.
[–h host_name] Specifies the TCP host name of the policy server. When used with
the –config action, this name is saved in the configuration file
using the azn-app-host key. It is not used to name server objects.
Appendix F. SSL configuration commands
255
svrsslcfg –modify
Purpose
Modifies the current configuration.
Syntax
svrsslcfg –config –f cfg_file [–t ssl_timeout] [–C cert_file] [–l listening_mode]
Options
–f cfg_file
Specifies the configuration file path and name.
[–t ssl_timeout] Specifies the SSL session timeout in seconds. The ssl_timeout value
must be in the range 1–86400. The default value is 7200.
[–C cert_file]
Specify the fully qualified name of the file containing the base-64
encoded SSL certificate used when the server authenticates directly
with the user registry.
[–l listening_mode]
Sets the listening-enabled flag in the configuration file. Values are
yes and no. The default value is no. A value of yes requires that
the listening port number in the configuration file be non zero.
256
IBM Tivoli Access Manager: Base Administrator’s Guide
svrsslcfg –rmv_replica
Purpose
Removes a replica configuration.
Syntax
svrsslcfg –rmv_replica –f cfg_file –h host_name
Options
–f cfg_file
Specifies the configuration file path and name.
–h host_name
Specifies the TCP host name of an ivacld replica server.
Appendix F. SSL configuration commands
257
svrsslcfg –unconfig
Purpose
Unconfigures the server. The key ring files are deleted and the server is removed
from the user registry and Access Manager database.
Syntax
svrsslcfg –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 either
server_name/host name or server_name, in which case the local
host name is appended to form name/host name. Note that ivacld,
secmgrd, ivnet, and ivweb server names are reserved for Access
Manager servers.
[–P admin_pwd]
Specifies the Access Manager administrator password. If this
option is not specified, the password is read from standard in
(stdin).
[–A admin_id]
258
Specifies the Access Manager administrator name. The default is
sec_master.
IBM Tivoli Access Manager: Base Administrator’s Guide
Appendix G. User registry differences
The following user registry differences are known to exist in this version of IBM
Tivoli 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 Access
Manager for e-business secure domain. However, when using a Lotus Domino
server as a user registry, leading and trailing blanks are significant. To ensure
that processing is consistent regardless of what user registry is being used,
define users and groups in the user registry without leading or trailing blanks
in their names.
2. The forward slash character (/) should be avoided in user and group names
defined using distinguished name strings. The forward slash character is
treated differently in different user registries:
Lotus Domino server
Users and groups can not be created with names using a distinguished
name string containing a forward slash character. To avoid the problem,
either do not use a forward slash character or define the user without
using 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 Directory
Users and groups can be created with names using a distinguished
name string containing a forward slash character. However, subsequent
operations on the object might fail as some Active Directory functions
interpret the forward slash character as a separator between the object
name and the host name. To avoid the problem, do not use a forward
slash character to define the user.
3. When using a multi-domain Microsoft Active Directory user registry, multiple
users and groups can be defined with the same short name as long as they
reside in different domains. To query information associated with a specific
user or group, use the full name, including the domain, of the user or group to
ensure that you are getting the correct information. If the domain information
is omitted, information about the user or group defined in the default domain
is returned, which might not be the expected user or group. The sole use of a
short 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 group
membership. If a user with the same name is created at some later time, the
new user automatically inherits the old group membership and might be given
inappropriate permissions. It is strongly recommended that the user be removed
from all groups before the user is deleted. This problem does not occur when
using the other supported user registries.
5. Attempting to add a duplicate user to a group produces different results based
on 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
Add one user and
that user is duplicate
LDAP
Error
Lotus Domino server
Microsoft Active
Directory
No error
Error
Add multiple users,
Error for all users
first user is duplicate
No error
Error for all users
Add multiple users, a Error for all users
user other than the
first is a duplicate
No error
Partial completion
message
6. Attempting to remove a user from a group who is not a member of the group
produces different results based on the user registry being used. Table 2
outlines the differences.
Table 2. User registry differences when removing a user from a group who is not a member
of the group
Operation
LDAP
Lotus Domino server
Microsoft Active
Directory
Remove one user,
user is not in the
group
Error
Error
Error
Remove multiple
users, first user not
in the group
Error for all users
Error
Error for all users
Partial completion
message
Partial completion
message
Remove multiple
Error for all users
users, a user other
than the first is not in
the group
7. The maximum lengths of various names associated with a user vary depending
on the user registry being used. See Table 3 for a comparison of the maximum
lengths allowed and the recommended maximum length to use to ensure
compatibility with all the user registries supported by Access Manager for
e-business.
Table 3. Maximum lengths for names based on user registry
Maximum
length of:
260
LDAP
Microsoft Active
Directory
Lotus Domino
server
Recommended
maximum 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 is
user
registry-specific
and must be
changed when
changing user
registries.
IBM Tivoli Access Manager: Base Administrator’s Guide
Table 3. Maximum lengths for names based on user registry (continued)
Maximum
length of:
LDAP
Microsoft Active
Directory
Lotus Domino
server
Recommended
maximum value
Access Manager
for e-business
user identity
256
2048 - 1 length_of_
domain_name
200 - 4 length_of_
domain_name
This value is
user
registry-specific
and must be
changed when
changing user
registries.
8. Users created in a Lotus Domino server or Microsoft Active Directory user
registry are automatically given the capability to own single signon credentials
and this capability can not be removed. When using an LDAP user registry, this
capability must be explicitly granted to a user and subsequently can be
removed.
9. When the Access Manager for e-business policy server is using either Microsoft
Active Directory or a Lotus Domino server as its user registry, existing Tivoli
SecureWay Policy Director, Version 3.8 clients are not able to connect to the
policy server. Either use a different user registry or upgrade the clients to
Access Manager for e-business.
Appendix G. User registry differences
261
262
IBM Tivoli Access Manager: Base Administrator’s Guide
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 in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
263
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758
U.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 material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrates programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM for the purposes of developing, using, marketing, or distributing application
programs conforming to IBM’s application programming interfaces.
Each copy or any portion of these sample programs or any derivative work, must
include 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 rights
reserved.
264
IBM Tivoli Access Manager: Base Administrator’s Guide
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
Trademarks
The following terms are trademarks or registered trademarks of International
Business Machines Corporation in the United States, other countries, or both:
AIX
DB2
IBM
IBM logo
OS/390
SecureWay
Tivoli
Tivoli logo
Universal Database
WebSphere
zSeries
z/OS
Lotus and Domino are trademarks of International Business Machines Corporation
and Lotus Development Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and other countries.
Microsoft and Windows are trademarks of Microsoft Corporation in the United
States, other countries, or both. Java and all Java-based trademarks and logos are
trademarks or registered trademarks of Sun Microsystems, Inc. in the United States
and other countries.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product, or service names may be trademarks or service marks of
others.
Appendix H. Notices
265
266
IBM Tivoli Access Manager: Base Administrator’s Guide
Glossary
A
access control. In computer security, the process of
ensuring that the resources of a computer system can
be accessed only by authorized users in authorized
ways.
access control groups. Groups to be used for access
control. Each group contains a multivalued attribute
consisting of member distinguished names. Access
control groups have an object class of AccessGroup.
access control list. (1) In computer security, a
collection of all access rights for one object. (2) In
computer security, a list associated with an object that
identifies all the subjects that can access the object and
their access rights; for example, a list associated with a
file that identifies users who can access the file and
identifies their access rights to that file.
access permissions. Permissions that apply to the
entire object or permissions that apply to attribute
access classes.
actions. ACL permission attributes.
ACL. See access control list.
authentication. (1) In computer security, verification of
the identity of a user or the user’s eligibility to access
an object. (2) In computer security, verification that a
message has not been altered or corrupted. (3) In
computer security, a process used to verify the user of
an information system or protected resources.
authorization. (1) In computer security, the right
granted to a user to communicate with or make use of
a computer system. (2) An access right. (3) The process
of granting a user either complete or restricted access
to an object, resource, or function.
B
bind. To relate an identifier to another object in a
program; for example, to relate an identifier to a value,
an address or another identifier, or to associate formal
parameters and actual parameters.
certificate authority. In e-commerce, an organization
that issues certificates. The certificate authority
authenticates the certificate owner’s identity and the
services that the owner is authorized to use, issues new
certificates, renews existing certificates, and revokes
certificates belonging to users who are no longer
authorized to use them.
cipher. Encrypted data that is unreadable until it has
been converted into plain data (decrypted) with a key.
configuration. (1) The manner in which the hardware
and software of an information processing system are
organized and interconnected. (2) The devices and
programs that make up a system, subsystem, or
network
connection. (1) In data communication, an association
established between functional units for conveying
information. (2) In TCP/IP, the path between two
protocol applications that provides reliable data stream
delivery service. In the Internet, a connection extends
from a TCP application on one system to a TCP
application on another system. (3) In system
communications, a line over which data can be passed
between two systems or between a system and a
device.
credentials. Detailed information, acquired during
authentication, that describes the user, any group
associations, and other security-related identity
attributes. Credentials can be used by any Access
Manager service that requires information about the
user. Credentials allow Access Manager to securely
perform a multitude of services, such as authorization,
auditing, and delegation. For example, the Access
Manager authorization service uses the user credential
to determine whether the user is authorized to perform
specific operations on a protected resource.
D
daemon. A program that runs unattended to perform
a standard service. Some daemons are triggered
automatically to perform their task; others operate
periodically.
DCE. See distributed computing environment.
C
certificate. In e-commerce, a digital document that
binds a public key to the identity of the certificate
owner, thereby enabling the certificate owner to be
authenticated. A certificate is issued by a certificate
authority.
directory schema. Entries in a directory are made up
of a collection of attributes and their associated values.
Attributes may have one or multiple values. In order to
identify a particular value in an entry, the attribute type
name is specified along with the value, as in cn=John
Doe. This is referred to as an attribute:value pair. Every
entry contains an objectClass attribute that identifies
267
what type of information the entry contains. In fact, the
object class dictates which other attributes may be
present in an entry. The directory schema defines the
valid attribute types and object classes that may appear
in the directory. Attribute type definitions define the
maximum length and syntax of its values. Object class
definitions specify which attributes must be present in
an object of that class, as well as attributes that may be
present.
distinguished name (DN). Every entry in a directory
has a distinguished name. The distinguished name is
the name that uniquely identifies an entry in the
directory. A distinguished name is made up of
attribute:value pairs, separated by commas.
distributed computing environment (DCE). The Open
Software Foundation specification (or a product derived
from this specification) that assists in networking. The
distributed computing environment provides such
functions as authentication, directory service, and
remote procedure call.
digital signature. Data that is appended to, or is a
cryptographic transformation of, a data unit and that
enables the recipient of the data unit to verify the
source and integrity of the unit and to recognize
potential forgery.
DN. See distinguished name.
domain. (1) That part of a computer network in which
the data processing resources are under common
control. (2) In a database, all the possible values of an
attribute or a data element. (3) See domain name.
domain name. In the Internet suite of protocols, a
name of a host system. A domain name consists of a
sequence of subnames separated by a delimiter
character. For example, if the fully qualified domain
name (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
E
encryption. The process of transforming data into an
unintelligible form in such a way that the original data
either cannot be obtained or can be obtained only by
using a decryption process.
host. A computer that is connected to a network (such
as the Internet or an SNA network) and provides an
access point to that network. Also, depending on the
environment, the host may provide centralized control
of the network. The host can be a client, a server, or
both a client and a server simultaneously.
Hypertext Transfer Protocol (HTTP). In the Internet
suite of protocols, the protocol that is used to transfer
and display hypertext documents.
I
Internet Protocol (IP). In the Internet suite of
protocols, a connectionless protocol that routes data
through a network or interconnected networks and acts
as an intermediary between the higher protocol layers
and the physical network.
Internet suite of protocols. A set of protocols
developed for use on the Internet and published as
Requests for Comments (RFCs) through the Internet
Engineering Task Force (IETF).
IP. See Internet Protocol.
K
key. A sequence of symbols that is used with a
cryptographic algorithm for encrypting or decrypting
data. 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 the
key pair is used for encryption, the sender uses the
public key to encrypt the message, and the recipient
uses the private key to decrypt the message. When the
key pair is used for signing, the signer uses the private
key to encrypt a representation of the message, and the
recipient uses the public key to decrypt the
representation of the message for signature verification.
key ring. A file that contains public keys, private keys,
trusted roots, and certificates.
L
LDAP. See Lightweight Directory Access Protocol.
F
File Transfer Protocol (FTP). In the Internet suite of
protocols, an application layer protocol that uses TCP
and Telnet services to transfer bulk-data files between
machines or hosts.
268
H
IBM Tivoli Access Manager: Base Administrator’s Guide
ldif2db. This program is used to load entries specified
in text LDAP Directory Interchange Format (LDIF) into
a directory stored in a relational database. The database
must already exist. ldif2db may be used to add entries
to an empty directory database or to a database that
already contains entries.
Lightweight Directory Access Protocol (LDAP). An
open protocol that (a) uses TCP/IP to provide access to
directories that support an X.500 model and (b) does
not incur the resource requirements of the more
complex X.500 Directory Access Protocol (DAP).
Applications that use LDAP (known as
directory-enabled applications) can use the directory as
a common data store and for retrieving information
about people or services, such as e-mail addresses,
public keys, or service-specific configuration
parameters. LDAP was originally specified in RFC
1777. LDAP version 3 is specified in RFC 2251, and the
IETF continues work on additional standard functions.
Some of the IETF-defined standard schemas for LDAP
are found in RFC 2256.
M
management server. See policy server.
metadata. Data that describes the characteristics of
stored data; descriptive data.
migration. The installation of a new version or release
of a program to replace an earlier version or release.
O
object class definitions. Every entry contains an
objectClass attribute that identifies what type of
information the entry contains. In fact, the object class
dictates which other attributes may be present in an
entry. The directory schema defines the valid attribute
types and object classes that may appear in the
directory. Attribute type definitions define the
maximum length and syntax of its values. Object class
definitions specify which attributes must be present in
an object of that class, as well as attributes that may be
present.
P
policy. A set of rules that are applied to managed
resources.
policy data. Includes both password strength policy
data and login data.
policy server. Maintains location information about
other Access Manager servers in the secure domain.
When policy changes affect the master authorization
policy database, the policy server is responsible for
updating all authorization database replicas in the
domain.
POP. See protected object policy.
protected object policy (POP). A type of Access
Manager security policy that dictates additional
conditions for accessing a protected resource after a
successful ACL policy check. Examples of POPs include
time-of-day access and quality of protection level.
protected object space. The virtual object
representation of actual system resources that is used
for applying ACLs and POPs and used by the
authorization 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.
Q
quality of protection. The level of data security,
determined by a combination of authentication,
integrity, and privacy conditions.
R
registry. (1) The datastore that maintains the account
information for users and groups that are allowed to
participate in the secure domain. (2) A database that
contains system configuration information regarding
the user, the hardware, and the programs and
applications that are installed.
replica. A replica is a server that runs a copy of the
directory. This replicated server can keep a copy of the
entire directory or just one tree of that directory. Any
update to a replica server is referred to the master
server. If the master server fails, you always have a
copy of the directory trees on the replica server. Using
the replica server also improves the response time.
response file. A file that contains a set of predefined
answers to questions asked by a program and that is
used in place of user dialog.
RSA. A system for public-key cryptography used for
encryption and authentication. It was invented in 1977
by Ron Rivest, Adi Shamir, and Leonard Adleman. The
system’s security depends on the difficulty of factoring
the product of two large prime numbers.
run time. The time period during which a computer
program is executing. A runtime environment is an
execution environment.
S
scalability. The ability of a network system to respond
to increasing numbers of users who access resources.
schema. The set of statements, expressed in a data
definition language, that completely describe the
structure of a database.
Glossary
269
secure domain. The group of users, systems, and
resources that share common services and usually
function with a common purpose.
Secure Sockets Layer (SSL). A security protocol that
provides communication privacy. SSL enables
client/server applications to communicate in a way that
is designed to prevent eavesdropping, tampering, and
message forgery. SSL was developed by Netscape
Communications Corp. and RSA Data Security, Inc.
security management. The management discipline
that addresses an organization’s ability to control access
to applications and data that are critical to its success.
service. Work performed by a server. This may mean
serving simple requests for data to be sent or stored (as
with file servers, HTTP servers, e-mail servers, and
finger servers), or it may be more complex work such
as that of print servers or process servers.
silent installation. An installation that does not send
messages to the console but instead stores messages
and errors in log files. Also, can indicate that the
installation uses response files instead of user dialogs.
SSL. See Secure Sockets Layer.
suffixes. A suffix is a distinguished name that
identifies the top entry in a locally held directory
hierarchy. Because of the relative naming scheme used
in Lightweight Directory Access Protocol (LDAP), this
distinguished name is also the suffix of every other
entry within that directory hierarchy. A directory server
may have multiple suffixes, each identifying a locally
held directory hierarchy.
T
token. (1) In a local area network, the symbol of
authority passed successively from one data station to
another to indicate the station temporarily in control of
the transmission medium. Each data station has an
opportunity to acquire and use the token to control the
medium. A token is a particular message or bit pattern
that signifies permission to transmit. (2) In local area
networks (LANs), a sequence of bits passed from one
device to another along the transmission medium.
When the token has data appended to it, it becomes a
frame.
transport selector. The Open Systems Interconnection
(OSI) equivalent of port numbers in TCP/IP. Also
called a TSEL number.
trusted root. In the Secure Sockets Layer (SSL), the
public key and associated distinguished name of a
certificate authority (CA).
TSEL. See transport selector.
270
IBM Tivoli Access Manager: Base Administrator’s Guide
U
user. Any person, organization, process, device,
program, protocol, or system that uses a service
provided by others.
Index
A
access control list (ACL) 13
accountability 5
ACL 13
apply to new LDAP suffixes 109
control permission 52
create 36
custom permissions 40
custom permissions example 40
default administration policies 57
default root 57
entries 35
entry syntax 37
evaluation 41
extended action groups 46
extended actions 46
ID attribute 38
inheritance 42
management permissions 51
operations on an object 39
permissions attribute 38
resolving request 44
traverse 43, 50
type attribute 37
WebSEAL permissions 50
ACL permissions 39
ACL policies, defining 12
action
enter into ACL entries 48
action group, create new 47
action, create new 48
actions 39
activating
roles 74
administration
delegate role 73
enterprise domain 71
multiple domains 72
roles 73
superdomain 71
administration policies (default) 57
administrator
multiple domains 72
superdomain 71
tasks 74
administrators
administrator 73
domain 72
enterprise domain 71
Policy Director 72
predefined 72
sec_master 71
senior 73
support 73
types 72
any-other 37, 41
audit event 117
audit trail 117
audit trail files 115, 117
auditcfg 119
auditing
overview 115
auditlog 118
authentication 3
authorization 3, 5
authorization API 16
authorization API standard 3
authorization database, replicate 100
authorization evaluator 8
authorization model 5
authorization policy database 8
authorization process 15
authorization server 89
authorization service 6, 7, 8
authorization API 9
benefits 7
management interface 9
auto-database-update-notify 100
B
books
feedback xii
online xii
ordering xii
boot-start-ivacld 99
boot-start-ivmgrd 99
C
centralized management
configuration files 96
container object 29
management 30
user-defined 30
WebSEAL 30
control permission 52
creating
roles 74
Customer Support xvii
5
D
default administration policies 57
default config ACL 58
default GSO ACL 59
default management ACL 58
default Policy ACL 59
default replica ACL 58
default root ACL 43, 57
default WebSEAL ACL 58
delegate administrator, illustrated 72
delegate role
administration 73
delegated administration
administration users and groups 78
group ACL permissions 84
group and user management 81
group container objects 82
managing policy 86
271
delegated administration (continued)
object space management 78
user ACL permissions 85
domain
administrators 72
enterprise 71
multiple 72
subdomain, described 71
superdomain 71
E
e-mail contact xvii
encryption
supported standards 4
enterprise domain 71
error.log 116
evaluating an ACL 41
event field ID codes 123
explicit ACL 42
explicit ACL policy 13
extended action groups 46
extended actions 46
external authorization service 20
F
fail-over configuration 106
fatal.log 116
feedback about publications xvii
field ID codes 123
management objects 12
management server 8, 89
management/ACL permissions 51
management/Action permissions 52
management/Config permissions 54
management/Groups permissions 56
management/GSO permissions 56
management/Policy permissions 54
management/POP permissions 53
management/Replica permissions 54
management/Server permissions 53
management/Users permissions 55
manuals
feedback xii
online xii
ordering xii
master authorization policy database 8
max-notifier-threads 100, 101
messages
error.log 116
fatal.log 116
notice.log 116
warning.log 116
multiple domain 72
illustrated 72
multiple doman
example 72
N
notice.log 116
notification delay time 101
notifier-wait-time 100, 102
G
group 36
group container objects 82
I
IBM SecureWay Directory 106
iKeyman key management utility
description xv
inheritance 42
inherited ACL 42
inherited ACL policy 13
iPlanet 106
iv-admin group 79
ivmgrd-servers group 79
L
LDAP
fail-over configuration 106
overview 103
suffixes, new 109
LDAP fail-over
preference values 108
ldap.conf 107
local cache mode 16, 19
logaudit 118
logflush 119
logging
overview 115
logsize 118
272
M
IBM Tivoli Access Manager: Base Administrator’s Guide
O
object permissions 57
object space permissions 57
object space, user-defined 31
creating new 32
object types 32, 82
objects, create and delete 33
online publications xvi
ordering publications xvii
P
password
troubleshooting 73
pd_start 90
pdacld 89
pdadmin 90
pdadmin server replicate 101
pdmgrd 8, 89
permissions 39
custom 40
custom, example 40
roles 73
Policy Director
administrators 72
authorization service 7, 8
core technologies 3
introducing 2
securing enterprise networks 1
policy enforcer 6
POP 14, 61
apply to objects 63
configure attributes 63
create 62
POP attribute
audit level 64
time of day 64
warning mode 64
POP policies, defining 12
preference values (LDAP fail-over)
protected object 12, 29
protected object policies 14
protected object policy (POP) 61
apply to objects 63
configure attributes 63
create 62
protected object space 12, 29
guidelines 46
management objects 12
protected object 12
system resource 12
user-defined objects 12
web objects 12
publications
feedback xii
online xii
ordering xii
108
Q
quality of protection 4
R
remote cache mode 16, 18
replica 108
replicate authorization database 100
replication 10
resolving ACL request 44
resource manager 6
resource object 29
roles
defined 73
delegate 73
permissions 73
role activation 74
role assignment 74
assigning 74
role creation 74
rollover threshold 118
root ACL (default) 43, 57
server status 98
serviceability messages
error.log 116
fatal.log 116
notice.log 116
warning.log 116
sparce ACL model 42
status, server 98
subdomain 71
superdomain 71
system resource 12, 29
T
tasks
role activation 74
role adminstration 74
role assignment 74
role creation 74
roles 73
types 74
Tivoli Customer Support xvii
traverse 50
traverse permission 43, 50
U
unauthenticated 41
update notifier threads 101
user 36
user registry
differences 259
user-defined object space 31
creating new 32
user-defined objects 12
users
administrator, administrator 73
administrator, domain 72
administrator, Policy Director 72
administrator, sec_master 71
administrator, senior 73
administrator, support 73
delegate 73
W
warning.log 116
web objects 12
Web Portal Manager 14, 90
security policy 73
WebSEAL 89
webseal-servers group 79
webseald 89
S
scalability 4, 10
sec_master 71
sec_master user 78
securing enterprise networks 1
security
common concerns 2
implementing policy 11
policy 73
server
automating startup 99
server replicate 101
Index
273
274
IBM Tivoli Access Manager: Base Administrator’s Guide
Printed in U.S.A.
GC23-4684-00
Download PDF
Similar pages