Tivoli® Identity Manager
RACF Adapter Installation and Configuration Guide
Version 4.6
SC32-1490-08
���
Tivoli® Identity Manager
RACF Adapter Installation and Configuration Guide
Version 4.6
SC32-1490-08
���
Note:
Before using this information and the product it supports, read the information in Appendix D, “Notices,” on page 113.
Ninth Edition (June 2005)
This edition applies to version 4.6 of this adapter and to all subsequent releases and modifications until otherwise
indicated in new editions.
© Copyright International Business Machines Corporation 2003, 2005. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Preface . . . . . . . . . . . . . . . v
Who should read this book . . . . . . . . . v
Publications and related information . . . . . . v
Tivoli Identity Manager library . . . . . . . v
Prerequisite Product Publications . . . . . . vii
Related Publications . . . . . . . . . . viii
Accessing publications online . . . . . . . ix
Accessibility . . . . . . . . . . . . . . ix
Support information . . . . . . . . . . . ix
Conventions used in this book . . . . . . . . ix
Typeface conventions . . . . . . . . . . ix
Operating system differences . . . . . . . . x
Definitions for HOME and other directory
variables . . . . . . . . . . . . . . . x
Summary of changes made to the RACF adapter . . xii
Summary of changes for SC32-1490-08 Ninth
Edition (June 2004) . . . . . . . . . . . xii
Summary of changes for SC32-1490-07 Eighth
Edition (November 2004) . . . . . . . . . xii
Summary of changes for SC32-1490-06 Seventh
Edition (November 2004) . . . . . . . . xiii
Summary of changes for SC32-1490-05 Sixth
Edition (August 2004) . . . . . . . . . xiii
Chapter 1. Overview of the RACF
adapter . . . . . . . . . . . . . . . 1
RACF considerations . . . . . . . . . . . 3
Chapter 2. Adapter interactions with the
Tivoli Identity Manager Server . . . . . 7
Chapter 3. Installing and configuring the
RACF adapter . . . . . . . . . . . . 9
Basic installation . . . . . . . . . . . . . 9
Prerequisites . . . . . . . . . . . . . . 9
Installation worksheet . . . . . . . . . . . 10
RACF adapter activation checklist . . . . . . . 13
Step 1: Upload the adapter package . . . . . . 13
Step 2: Install the MVS executables . . . . . . 16
Step 3: Install the UNIX System Services executables 18
Step 4: Configure the UNIX System Services
Component . . . . . . . . . . . . . . 19
Step 5: Configure MVS Components . . . . . . 22
Modify and submit the APPCCMD job . . . . 22
Modify and submit the APPCRECO job . . . . 24
Modify and submit the ITIMVSAM job . . . . 27
Create started task . . . . . . . . . . . 29
Configure RACF access . . . . . . . . . 30
Step 6: Configure communication . . . . . . . 34
Importing the adapter profile into the Tivoli
Identity Manager Server . . . . . . . . . 34
Creating a RACF service . . . . . . . . . 35
Step 7: Starting and stopping the adapter . . . . 36
Chapter 4. Configuring the RACF
adapter in IBM Tivoli Identity Manager . 39
Starting the adapter configuration tool . . . . . 39
Viewing configuration settings . . . . . . . . 40
Changing protocol configuration settings . . . . 41
Configuring event notification . . . . . . . . 44
Required information . . . . . . . . . . 44
Example definition . . . . . . . . . . . 45
Setting attributes to be reconciled . . . . . . 58
Modifying an event notification context . . . . 59
Changing the configuration key . . . . . . . 61
Changing activity logging settings . . . . . . . 61
Changing registry settings . . . . . . . . . 63
Modifying non-encrypted registry settings . . . 64
Changing advanced settings . . . . . . . . . 64
Viewing statistics . . . . . . . . . . . . 66
Changing code page settings . . . . . . . . 66
Default adapter code page locale . . . . . . 66
Obtaining a list of valid code pages . . . . . 66
Setting the code page . . . . . . . . . . 67
Accessing help and additional options . . . . . 68
Chapter 5. Configuring SSL
authentication for the RACF adapter . . 71
Overview of SSL and digital certificates . . . . . 71
Private keys, public keys, and digital certificates 72
Self-signed certificates . . . . . . . . . . 72
Certificate and key formats . . . . . . . . 73
The use of SSL authentication . . . . . . . . 73
Configuring certificates for SSL authentication . . . 74
Configuring certificates for one-way SSL
authentication . . . . . . . . . . . . 74
Configuring certificates for two-way SSL
authentication . . . . . . . . . . . . 75
Configuring certificates when the adapter
operates as an SSL client . . . . . . . . . 76
Managing SSL certificates using CertTool . . . . 77
Starting CertTool . . . . . . . . . . . 77
Generating a private key and certificate request 79
Installing the certificate . . . . . . . . . 80
Installing the certificate and key from a PKCS12
file . . . . . . . . . . . . . . . . 80
Viewing the installed certificate . . . . . . . 81
Installing a CA certificate . . . . . . . . . 81
Viewing CA certificates . . . . . . . . . 81
Deleting a CA certificate . . . . . . . . . 81
Viewing registered certificates . . . . . . . 82
Registering a certificate . . . . . . . . . 82
Unregistering a certificate . . . . . . . . 82
Exporting a certificate and key to PKCS12 file . . 82
Chapter 6. Customizing the RACF
adapter . . . . . . . . . . . . . . 85
ITIMEXIT . . . . . . . . . . . . . . . 85
© Copyright IBM Corp. 2003, 2005 iii
ITIMEXEC . . . . . . . . . . . . . . . 86
Chapter 7. Troubleshooting the adapter 89
Adapter log files . . . . . . . . . . . . . 89
Appendix A. Agent attributes . . . . . 91
Agent attributes by object . . . . . . . . . 91
erRacUser . . . . . . . . . . . . . . 91
erRacConnect . . . . . . . . . . . . 104
erRacGroup . . . . . . . . . . . . . 105
Appendix B. Registry settings . . . . 107
Appendix C. Support information . . . 109
Searching knowledge bases . . . . . . . . . 109
Search the information center on your local
system or network . . . . . . . . . . . 109
Search the Internet . . . . . . . . . . 109
Obtaining fixes . . . . . . . . . . . . . 110
Contacting IBM Software Support . . . . . . 110
Determine the business impact of your problem 111
Describe your problem and gather background
information . . . . . . . . . . . . . 111
Submit your problem to IBM Software Support 111
Appendix D. Notices . . . . . . . . 113
Trademarks . . . . . . . . . . . . . . 114
Index . . . . . . . . . . . . . . . 117
iv IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Preface
The IBM® Tivoli® Identity Manager RACF® Adapter (RACF Adapter) enables
connectivity between the IBM Tivoli Identity Manager Server and a network of
systems running the MVS operating system. Once the adapter is installed and
configured, Tivoli Identity Manager manages access to MVS RACF resources with
your site’s security system. This book describes how to install and configure the
RACF Adapter.
Note: The program that is used to connect the managed resource to the Tivoli
Identity Manager Server is now called an adapter. The term adapter replaces
the previously used term agent. The user interface used to configure the
adapter still refers to an adapter as an agent.
Who should read this book
This book is intended for MVS system and security administrators responsible for
installing software on their site’s computer systems. Readers are expected to
understand MVS concepts. The person completing the installation procedure
should also be familiar with their site’s system standards and needs to have
appropriate MVS experience and knowledge. Readers must be able to perform
routine MVS system and security administration tasks.
To install and configure the RACF Adapter, you should possess the following skills
and experience:
v Administration of RACF
v Administration of APPC/MVS
v Administration of z/OS VTAM
v Usage and administration of z/OS TCP/IP
v Usage of TSO/ISPF
v Usage of UNIX System Services
v If SSL is enabled, understanding of the creation and installation of digital
certificates
Publications and related information
Read the descriptions of the Tivoli Identity Manager library. To determine which
additional publications you might find helpful, read the “Prerequisite Product
Publications” on page vii and the “Related Publications” on page viii. After you
determine the publications you need, refer to the instructions in “Accessing
publications online” on page ix.
Tivoli Identity Manager library
The publications in the Tivoli Identity Manager technical documentation library are
organized into the following categories:
v Release information
v Online user assistance
v Server installation and configuration
v Problem determination
© Copyright IBM Corp. 2003, 2005 v
v Technical supplements
v Adapter installation and configuration
Release Information:
v IBM Tivoli Identity Manager Release Notes
Provides software and hardware requirements for Tivoli Identity Manager, and
additional fix, patch, and other support information.
v IBM Tivoli Identity Manager Documentation Read This First Card
Lists the Tivoli Identity Manager publications.
Online user assistance:
Provides online help topics and an information center for all Tivoli Identity
Manager administrative tasks. The information center includes information that
was previously provided in the IBM Tivoli Identity Manager Configuration Guide and
the IBM Tivoli Identity Manager Policy and Organization Administration Guide.
Server installation and configuration:
IBM Tivoli Identity Manager Server Installation and Configuration Guide for WebSphere
Environments provides installation and configuration information for Tivoli Identity
Manager.
Configuration information that was previously provided in the IBM Tivoli Identity
Manager Configuration Guide is now included in either the installation guide or in
the IBM Tivoli Identity Manager Information Center.
Problem determination:
IBM Tivoli Identity Manager Problem Determination Guide provides problem
determination, logging, and message information for the Tivoli Identity Manager
product.
Technical supplements:
The following technical supplements are provided by developers or by other
groups who are interested in this product:
v IBM Tivoli Identity Manager Performance Tuning Guide
Provides information needed to tune Tivoli Identity Manager Server for a
production environment, available on the Web at:
http://publib.boulder.ibm.com/tividd/td/tdprodlist.html
Click the I character in the A-Z product list, and then, click the Tivoli Identity
Manager link. Browse the information center for the Technical Supplements
section.
v Redbooks and white papers are available on the Web at:
http://www.ibm.com/software/sysmgmt/products/support/IBMTivoliIdentityManager.html
Browse to the Self Help section, in the Learn category, and click the Redbooks
link.
v Technotes are available on the Web at:
http://www.redbooks.ibm.com/redbooks.nsf/tips/
v Field guides are available on the Web at:
vi IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
http://www.ibm.com/software/sysmgmt/products/support/Field_Guides.html
v For an extended list of other Tivoli Identity Manager resources, search the
following IBM developerWorks Web address:
http://www.ibm.com/developerworks/
Adapter installation and configuration:
The Tivoli Identity Manager Server technical documentation library also includes
an evolving set of platform-specific installation documents for the adapter
components of a Tivoli Identity Manager Server implementation. Locate adapters
on the Web at:
http://www.lotus.com/services/passport.nsf/WebDocs/Passport_Advantage_Home
Click Support & downloads. Browse to the Downloads and drivers. Click the link
for the current inventory of adapters.
Skills and training:
The following additional skills and technical training information were available at
the time that this manual was published:
v Virtual Skills Center for Tivoli Software on the Web at:
http://www.cgselearning.com/tivoliskills/
v Tivoli Education Software Training Roadmaps on the Web at:
http://www.ibm.com/software/tivoli/education/eduroad_prod.html
v Tivoli Technical Exchange on the Web at:
http://www.ibm.com/software/sysmgmt/products/support/supp_tech_exch.html
Prerequisite Product Publications
To use the information in this book effectively, you must have knowledge of the
products that are prerequisites for Tivoli Identity Manager Server. Publications are
available from the following locations:
v MVS RACF
– http://www-1.ibm.com/servers/eserver/zseries/zos/racf/v Operating systems
– z/OS
http://www-1.ibm.com/servers/eserver/zseries/zos/
– IBM AIX®
http://www16.boulder.ibm.com/pseries/en_US/infocenter/base/aix52.htm
– Sun Solaris
http://docs.sun.com/db?q=solaris+9
– Red Hat Linux®
http://www.redhat.com/docs/
– Microsoft® Windows Server 2003
http://www.microsoft.com/windowsserver2003/proddoc/default.mspxv Database servers
– IBM DB2®
Preface vii
- Support: http://www.ibm.com/software/data/db2/udb/support.html
- Information center:
http://publib.boulder.ibm.com/infocenter/db2help/index.jsp
- Documentation: http://www.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v8pubs.d2w/en_main
- DB2 product family: http://www.ibm.com/software/data/db2
- Fix packs:
http://www.ibm.com/software/data/db2/udb/support/downloadv8.html
- System requirements:
http://www.ibm.com/software/data/db2/udb/sysreqs.html– Oracle
http://www.oracle.com/technology/documentation/index.html
http://otn.oracle.com/tech/index.html
http://otn.oracle.com/tech/linux/index.html
– Microsoft SQL Server 2000
http://www.msdn.com/library/
http://www.microsoft.com/sql/v Directory server applications
– IBM Directory Server http://publib.boulder.ibm.com/tividd/td/IBMDS/IDSapinst52/en_US/HTML/ldapinst.htm http://www.ibm.com/software/network/directory
– Sun ONE Directory Server
http://docs.sun.com/app/docs/coll/S1_DirectoryServer_52v WebSphere Application Server
Additional information is available in the product directory or Web sites. http://publib.boulder.ibm.com/infocenter/ws51help/index.jsp http://www.redbooks.ibm.com/
v WebSphere embedded messaging
http://www.ibm.com/software/integration/wmq/
v IBM HTTP Server
http://www.ibm.com/software/webservers/httpservers/library.html
Related Publications
Information that is related to Tivoli Identity Manager Server is available in the
following publications:
v The Tivoli Software Library provides a variety of Tivoli publications such as
white papers, datasheets, demonstrations, redbooks, and announcement letters.
The Tivoli Software Library is available on the Web at:
http://www.ibm.com/software/tivoli/literature/
v The Tivoli Software Glossary includes definitions for many of the technical terms
related to Tivoli software. The Tivoli Software Glossary is available from the
Glossary link of the Tivoli Software Library Web page at:
http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm
viii IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Accessing publications online
IBM posts publications for this and all other Tivoli products, as they become
available and whenever they are updated, to the Tivoli software information center
Web site. Access the Tivoli software information center at the following Web
address:
http://publib.boulder.ibm.com/tividd/td/tdprodlist.html
Click the I character in the A-Z list, and then click the Tivoli Identity Manager
link to access the product library.
Note: If you print PDF documents on other than letter-sized paper, set the option
in the File → Print window that allows Adobe Reader to print letter-sized
pages on your paper.
Accessibility
The product documentation includes the following features to aid accessibility:
v Documentation is available in convertible PDF format to give the maximum
opportunity for users to apply screen-reader software.
v All images in the documentation are provided with alternative text so that users
with vision impairments can understand the contents of the images.
Support information
If you have a problem with your IBM software, you want to resolve it quickly. IBM
provides the following ways for you to obtain the support you need:
v Searching knowledge bases: You can search across a large collection of known
problems and workarounds, Technotes, and other information.
v Obtaining fixes: You can locate the latest fixes that are already available for your
product.
v Contacting IBM Software Support: If you still cannot solve your problem, and
you need to work with someone from IBM, you can use a variety of ways to
contact IBM Software Support.
For more information about these ways to resolve problems, see Appendix C,
“Support information,” on page 109.
Conventions used in this book
This reference uses several conventions for special terms and actions and for
operating system-dependent commands and paths.
Typeface conventions
This guide uses the following typeface conventions:
Bold
v Lowercase commands and mixed case commands that are otherwise
difficult to distinguish from surrounding text
v Interface controls (check boxes, push buttons, radio buttons, spin
buttons, fields, folders, icons, list boxes, items inside list boxes,
multicolumn lists, containers, menu choices, menu names, tabs, property
sheets), labels (such as Tip:, and Operating system considerations:)
Preface ix
v Keywords and parameters in text
Italic
v Words defined in text
v Emphasis of words (words as words)
v New terms in text (except in a definition list)
v Variables and values you must provide
Monospace
v Examples and code examples
v File names, programming keywords, and other elements that are difficult
to distinguish from surrounding text
v Message text and prompts addressed to the user
v Text that the user must type
v Values for arguments or command options
Operating system differences
This guide uses the UNIX® convention for specifying environment variables and
for directory notation.
When using the Windows command line, replace $variable with %variable% for
environment variables and replace each forward slash (/) with a backslash (\) in
directory paths. The names of environment variables are not always the same in
Windows and UNIX. For example, %TEMP% in the Windows operating system is
equivalent to $tmp in a UNIX operating system.
Note: If you are using the bash shell on a Windows system, you can use the UNIX
conventions.
Definitions for HOME and other directory variables
The following table contains the default definitions that are used in this guide to
represent the HOME directory level for various product installation paths. You can
customize the installation directory and HOME directory for your specific
implementation. If this is the case, you need to make the appropriate substitution
for the definition of each variable represented in this table.
The value of path varies for these operating systems:
v Windows: drive:\Program Files
v AIX: /usr
v Other UNIX: /opt
Path Variable Default Definition Description
DB_INSTANCE_HOME Windows:
path\IBM\SQLLIB
UNIX:
v AIX, Linux: /home/dbinstancename
v Solaris: /export/home/dbinstancename
The directory that
contains the
database for Tivoli
Identity Manager.
x IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Path Variable Default Definition Description
LDAP_HOME v For IBM Directory Server Version 5.2
Windows:
path\IBM\LDAP
UNIX:
– AIX, Linux: path/ldap
– Solaris: path/IBMldaps
path/IBM/LDAP
v For IBM Directory Server Version 6.0
Windows:
path\IBM\LDAP\V6.0
UNIX:
path/IBM/LDAP/V6.0
– AIX, Solaris
– Linux: opt/ibm/ldap/V6.0
v For Sun ONE Directory Server
Windows:
path\Sun\MPS
UNIX:
/var/Sun/mps
The directory that
contains the
directory server
code.
IDS_instance_HOME For IBM Directory Server Version 6.0
Windows:
drive\
ibmslapd-instance_owner_name
The value of drive might be C:\ on
Windows systems. An example of
instance_owner_name might be ldapdb2.
For example, the log file might be
C:\idsslapd-ldapdb2\logs\ibmslapd.log.
UNIX:
INSTANCE_HOME/idsslapd-instance_name
On Linux and AIX systems, the default
home directory is the
/home/instance_owner_name directory. On
Solaris systems, for example, the directory
is the /export/home/ldapdb2/idsslapd-ldapdb2 directory.
The directory that
contains the IBM
Directory Server
Version 6.0 instance.
HTTP_HOME Windows:
path\IBMHttpServer
UNIX:
path/IBMHttpServer
The directory that
contains the IBM
HTTP Server code.
Preface xi
Path Variable Default Definition Description
ITIM_HOME Windows:
path\IBM\itim
UNIX:
path/IBM/itim
The base directory
that contains the
Tivoli Identity
Manager code,
configuration, and
documentation.
WAS_HOME Windows:
path\WebSphere\AppServer
UNIX:
path/WebSphere/AppServer
The WebSphere
Application Server
home directory
WAS_MQ_HOME Windows:
path\ibm\WebSphere MQ
UNIX:
path/mqm
The directory that
contains the
WebSphere MQ
code.
WAS_NDM_HOME Windows:
path\WebSphere\DeploymentManager
UNIX:
path/WebSphere/DeploymentManager
The home directory
on the deployment
manager
Tivoli_Common_Directory Windows:
path\ibm\tivoli\common\CTGIM
UNIX:
path/ibm/tivoli/common/CTGIM
The central location
for all
serviceability-related
files, such as logs
and first-failure
capture data
Summary of changes made to the RACF adapter
Summary of changes for SC32-1490-08 Ninth Edition (June
2004)
This document contains information previously presented in the IBM Tivoli Identity
Manager RACF Adapter Installation and Configuration Guide, SC32-1490-07, which
supports the RACF Adapter, Eighth Edition (November 2004).
Changed information
v Changed the term agent to adapter.
v Updated the version from 4.5.1 to 4.6.
v Applied the new 4.6 updates to the document.
Summary of changes for SC32-1490-07 Eighth Edition
(November 2004)
This document contains information previously presented in the IBM Tivoli Identity
Manager RACF Adapter Installation and Configuration Guide, SC32-1490-06, which
supports the RACF Adapter, Seventh Edition (November 2004).
Changed information
v Minor changes.
xii IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Summary of changes for SC32-1490-06 Seventh Edition
(November 2004)
Changed information
v Event notification is now supported.
v Filtered reconciliation is now supported.
v Code page support has been implemented, using the default code page of
IBM-1047.
v Documentation changes from user requests:
– Improved documentation on implementing APPC/MVS and related
transactions.
– Improved documentation on utilization of surrogate user ID’s, for business
unit filtering
Summary of changes for SC32-1490-05 Sixth Edition (August
2004)
Changed information
v “ITIMEXIT” on page 85 includes updated information on zero and non-zero
return codes.
Preface xiii
xiv IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Chapter 1. Overview of the RACF adapter
An adapter is a program that provides an interface between a managed resource
and the Tivoli Identity Manager Server. Adapters might or might not reside on the
managed resource and the Tivoli Identity Manager Server manages access to the
resource by using your security system. Adapters function as trusted virtual
administrators on the target platform, performing such tasks as creating login IDs,
suspending IDs, and performing other functions administrators normally run
manually. The adapter runs as a service, independent of whether or not a user is
logged on to the Tivoli Identity Manager Server.
The IBM Tivoli Identity Manager RACF Adapter enables connectivity between the
Tivoli Identity Manager Server and a system running the MVS RACF server. This
installation guide provides the basic information that you need to install and
configure the RACF Adapter components. This chapter provides an overview of
the adapter and features of the adapter.
Tivoli Identity Manager works in conjunction with RACF security in an MVS
environment. The adapter coordinates communication between the Tivoli Identity
Manager Server and remote servers operating on other systems.
The RACF Adapter provides a method to receive provisioning requests issued from
Tivoli Identity Manager and process these requests to add, modify, delete, and
extract user information from an IBM RACF database. It does this by converting
Directory Access Markup Language (DAML) requests (using ERMA libraries for
movement of requests and information) issued from Tivoli Identity Manager to a
corresponding RACF command and then forwarding them through a series of
APPC requests to a command executor tasked to fulfill the command. The
command executor receives the formatted RACF command string, determines its
origin and scope of authority, and issues the command through TSO. Results of the
command execution are returned, including success or failure information.
The RACF Adapter is comprised of three components; the Adapter proper, the
Command Executor, and the Reconciliation Processor (refer to Figure 1 on page 2).
The RACF Adapter was designed in this manner because RACF commands must
be APF-authorized, which is not permitted from within the Unix System Services
environment. An additional benefit of this design is in the event of an APPC/MVS
transaction failure, there will be no cascading failure of the adapter process.
© Copyright IBM Corp. 2003, 2005 1
Note: Each instance of an APPC connection will correspond to a separate instance
of a command executor, allowing for multithreading from the adapter.
Adapter proper
The Adapter proper receives and processes requests from Tivoli Identity
Manager and then requests and receives acknowledgements through an
APPC connection to the Command Executor. The binaries of the Adapter
proper and related external files reside within the Unix System Services
environment of z/OS (OS/390).
Command Executor
The Command Executor, written in REXX, operates as an APPC/MVS
transaction that is triggered from an incoming request from the Adapter.
APPC requests will consist of a command to be executed, and, optionally, a
RACF user ID assumed as the identity or origin for the command. If a
RACF user ID is not provided with the request sent from the Adapter
proper, the command is sent under the default identity set for the adapter
after installation. The Command Executor executes completely within the
APPC/MVS environment.
Reconciliation Processor
The Reconciliation Processor is a series of programs, written in C, that
operate as an APPC/MVS transaction that is triggered by an incoming
request to the adapter. The APPC transaction may be accompanied with an
optional RACF user ID. The RACF user ID may be utilized (based upon
adapter configuration settings) for a scope-of-authority, or partial,
reconciliation. The Reconciliation Processor may either execute the RACF
database unload utility (IRRDBU00), or, may be provided with an existing
input file, produced by the RACF database unload utility.
The following procedure reviews the actions taken when a command is issued
against a RACF resource by proxy, using theTivoli Identity Manager RACF
Adapter.
1. A request is issued to alter one or more attributes on the Tivoli Identity
Manager user session or policy to the RACF Adapter to utilize the DAML
protocol.
ServiceProvider
Agent
CommandExecutor
ReconciliationProcessor
RACFDatabase
Z/OS HostDAML
Protocol
APPC (LU6.2)Protocol
RACF commands toIRRDBU00 to unload database
update.
UNIXSystemServices
Figure 1. The RACF Adapter
2 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
2. The Adapter proper residing within Unix System Services receives the
command and composes a TSO command string from the information.
Optionally, a RACF user ID accompanies the request, which will be the identity
of the issuer of the command. Authorization for commands issued through the
RACF Adapter is controlled through assignment of RACF user ID’s and RACF
resource profiles from within RACF.
3. The Adapter proper sends a series of APPC requests containing the command
to the Command Executor component.
4. The Command Executor executes the RACF command string it receives.
5. The Command Executor relays the results of the command execution back to
the Adapter.
6. The Adapter component relays the results of the altered attributes back to the
Tivoli Identity Manager that issued the request.
Note: When a Recon command is issued from Tivoli Identity Manager, the Recon
Processor component will execute IRRDBU00 to unload the RACF database.
This will create a file containing the entire contents of the RACF database.
The Recon Processor will then identify the Recon requestor’s scope of
authority and parse the file, discarding any information that is beyond the
requestor’s authority before returning the information to the Adapter proper
component.
RACF considerations
While this adapter does not require any APF authorization, there are RACF
environment issues to consider.
The RACF adapter operates in two basic modes.
If there is no operational RACF ID specified on the Tivoli Identity Manager service
form when a request is issued, the RACF user ID the adapter utilizes requires
specific privileges. For example, if the adapter administers all users within the
RACF database, it should operate with the SYSTEM SPECIAL RACF attribute. If
Tivoli Identity Manager performs operations against only a portion of the RACF
database, the adapter must be associated with a group assigned GROUP SPECIAL
privileges, for the portion of the RACF database it will administer. The following
figure depicts the above scenario:
Chapter 1. Overview of the RACF adapter 3
If operations carried out will be performed under a RACF ID specified on the
Tivoli Identity Manager service form, the RACF ID the adapter is started with does
not require any special privileged attributes. It does, however, require surrogate
authority to run functions under the identity of the RACF ID specified on the
Tivoli Identity Manager service form. The ID specified on the Tivoli Identity
Manager service form must have authority to perform the administration functions
requested by the Tivoli Identity Manager Server.
The following picture shows the above scenario:
Tivoli Identity
Manager ServerZ/OS Platform
RACF SSL
Service FormAgent operating
in UNIX System
Services
Command
Processor
Operating in
APPC/MVS
“RACF ID under which
requests will be
processed” field on
service form is .blank
RACF ID
assigned to
agent is
“ ”ITIAGNT
RACF ID used
for processing
requests will be
“ ”ITIAGNT
Figure 2. No operational RACF ID provided on the Tivoli Identity Manager service form
Tivoli Identity
Manager ServerZ/OS Platform
RACF SSL
Service FormAgent operating
in UNIX System
Services
Command
Processor
Operating in
APPC/MVS
“RACF ID under which
requests will be
processed” field on
service form is set to
“ ”.ADMINX
RACF ID
assigned to
agent is
“ ”ITIAGNT
RACF ID used
for processing
requests will be
“ ”ADMINX
ADMINX
Figure 3. Operational RACF ID provided on the Tivoli Identity Manager service form
4 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
RACF resources that require consideration are as follows:
FIELD class profile USER.segment.**, with UPDATE
FIELD class profiles are required when the adapter, or surrogate, does not
have the SYSTEM SPECIAL attribute.
FACILITY class profile STGADMIN.IGG.DEFDEL.UALIAS, with READ
The STGADMIN.IGG.DEFDEL.UALIAS may be required if catalog aliases
are created in the ITIMEXIT or ITIMEXEC adapter exit points.
FACILITY class profile IRR.PASSWORD.RESET, with UPDATE
IRR.PASSWORD.RESET is required if the effective RACF ID performing
password changes does not have the SYSTEM SPECIAL RACF attribute.
SURROGAT class profile ATBALLC.userid, with READ
The surrogate profile is required if the adapter RACF ID differs from the
RACF ID under which commands and reconciliations are executed.
APPCLU class profile vtamnode.appcname.appcname, with SESSION segment
The APPCLU profile is required.
FACILITY class profile BPX.NEXT.USER, with APPLDATA(’uid/’)
BPX.NEXT.USER is required if AUTOUID support is used.
UNIXPRIV class profile SHARED.IDS, with xxxx access
The adapter, or surrogate, will require access to this profile if the Tivoli
Identity Manager Server will be creating RACF ID’s with OMVS segments
where duplicate UID’s are created.
CLAUTH with class of USER
CLAUTH of USER will be required if the adapter, or surrogate, RACF ID
will create RACF users, when the creating ID does not have SYSTEM
SPECIAL.
Note: Details on the use of these RACF profiles are provided later in this
document.
APPC transactions must be registered. APPCCMD and APPCRECO jobstreams
must be customized and executed to register these transactions with APPC/MVS.
The VSAM file must be created for use by the reconciliation process. The RACF ID
specified on the service form or the default RACF ID configured for the adapter
must have UPDATE access to this file.
Chapter 1. Overview of the RACF adapter 5
6 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Chapter 2. Adapter interactions with the Tivoli Identity
Manager Server
By default, the RACF adapter does not enable SSL, nor does it install any digital
certificates. If you enable SSL, post configuration steps are required.
The RACF adapter is designed to perform functions as requested by the Tivoli
Identity Manager server. These basic functions are to add, modify or delete objects
in RACF, and to supply RACF data to Tivoli Identity Manager.
The communications path is established using TCP/IP. Additionally, SSL (Secure
Sockets Layer) is implemented to secure the communications between Tivoli
Identity Manager and the RACF adapter.
SSL requires the use of digital certificates and private keys to establish
communications between endpoints. The RACF endpoint is considered a server.
When the SSL protocol is utilized, the server endpoint must contain (as a
minimum) a digital certificate and private key. The client endpoint must have (as a
minimum) either a copy of the digital certificate of the server endpoint, or access
to the Certificate Authority that signed the RACF adapter’s certificate. SSL
communication is enabled by default, which requires the generation and
installation of a digital certificate and a private key on the adapter. If you are
generating a self-signed certificate, the certificate must be installed on the Tivoli
Identity Manager server. If you do not have a certificate/key pair to install, turn
SSL communications off until one is obtained and installed.
On the z/OS host, the default TCP/IP port utilized for adapter/server
communications is port 45580. This port number may be configured to utilize
another port of your choosing. This port number must be coded on an Tivoli
Identity Manager service form that references the z/OS host.
Additionally, the adapter requires the ability to be configured through a utility
called agentCfg. This utility communicates to the RACF adapter through TCP/IP.
The TCP/IP port number utilized for this purpose is dynamic; it is not a
configurable item. This allows for multiple instances of a RACF adapter to coexist
on the same z/OS platform. Although the port numbers utilized are dynamic, only
a specific range of port numbers may be utilized. Any instance of the RACF
adapter will attempt to listen on the lowest numbered port in the range, provided
it is not already in use by another instance of the adapter. The range of TCP/IP
port numbers utilized for adapter configuration is 44970 through 44994. This range
of port numbers is not configurable.
Depending upon your installation’s requirements, you may choose to restrict the
use of these ports for the use of the RACF adapter. The preferred method of
protecting the use of these ports is utilizing RACF protection, by defining profiles
in the RACF SERVAUTH resource class. For further information, please reference
z/OS Communications Server, IP Configuration Guide, (Document Number SC31-8775).
© Copyright IBM Corp. 2003, 2005 7
8 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Chapter 3. Installing and configuring the RACF adapter
Installing and configuring the RACF Adapter involves several steps that you must
complete in the appropriate sequence. Review the prerequisites before you begin
the installation process. You can also create an account on the managed resource
for the adapter to use.
Basic installation
The following lists the basic procedures necessary to install, configure, and run the
adapter:
1. Upload the distribution data set downloaded from IBM’s web site to the MVS
host.
2. Install MVS executables
3. Install UNIX executables
4. Configure UNIX component
5. Configure MVS backend component
a. Set up RACF environment specifics
b. Set up started task JCL6. Import the adapter profile into the Tivoli Identity Manager Server.
7. Configure server
8. Activate the RACF Adapter.
Prerequisites
Table 1 identifies hardware, software, and authorization prerequisites for installing
the RACF Adapter. Verify that all of the prerequisites have been met before
installing the RACF Adapter.
Table 1. Prerequisites to install the adapter
Operating System v z/OS version 1.4
v z/OS version 1.5
v z/OS version 1.6
Network Connectivity TCP/IP network
Server Communication Communication should be tested with a
low-level communications ping from the
Tivoli Identity Manager Server to the MVS
Server. This makes troubleshooting easier if
you encounter installation problems.
Tivoli Identity Manager Server Version 4.6
Organizations with multiple RACF databases should have an RACF Adapter
installed on an MVS host that manages the database.
A single RACF database can be managed by a single instance of the RACF adapter.
Support for Sysplex failover is not implemented. However, in the event a
participating image of the Sysplex is inoperative, an alternate instance of the
© Copyright IBM Corp. 2003, 2005 9
adapter may be started on a different image within the Sysplex. You must already
have this type of environment set up and the necessary resources available. The
related service instance on the Tivoli Identity Manager Server may require
updating, if the alternate image is known through a different IP address.
Installation worksheet
Use the following worksheet to document information required to install and
configure the RACF Adapter. Complete this worksheet before starting the
installation procedure. The worksheet identifies the information you need to
modify during the installation process.
Make a copy of the worksheet for each server where you are installing the RACF
Adapter. For example, if you have five Windows servers where you are installing
the Lotus Notes Agent, you need five copies of the worksheet.
Table 2. Installation worksheet
Option Description, default, note Value
MVS data set name The MVS data set high level qualifier
for upload and installation.
APPC/MVS logical
unit name
If APPC/MVS Logical Unit (LU)
names are left unspecified, the UNIX
System Services component will
utilize the APPC/MVS baselu value
that was declared while configuring
the APPC/MVS.
Your installation may wish to use a
separate set of LU’s for use with the
RACF adapter, to avoid interference
with your installation’s baselu
definitions. If this is the case, then you
must know these two LU names.
These LU’s must be defined and
activated, prior to execution of the
RACF Adapter.
v Originating LU name, if desired.
This LU must be configured into
APPC/MVS with NOSCHED.
v Destination LU name, if desired.
This LU must be configured into
APPC/MVS with SCHED(ASCH).
For additional information, please
refer to: z/OS MVS Planning:
APPC/MVS Management, Document
Number SA22-7599.
Adapter instance
name
The default is racfagent. There is no
maximum length, but the length
should be manageable. This value will
be specified in the config.sh UNIX
System Services shell script.
APPC/MVS
reconciliation
transaction name
The default is ITIMRECO. The
recommended length is eight
characters. The JCL member is
APPCRECO.
10 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 2. Installation worksheet (continued)
Option Description, default, note Value
APPC/MVS
command executor
transaction name
The default is ITIMCMD. The
recommended length is eight
characters. The JCL member is
APPCCMD.
VSAM file name This file was created with the JCL
ITIMVSAM and is referenced in the
JCL APPCRECO.
VSAM file size Size in cylinders. This file was created
with JCL ITIMVSAM.
Started task name There is a maximum of seven
characters, specified in the started JCL
ITIAGNT task.
Adapter port number The default is 45580. This value is
specified in the config.sh UNIX
System Services shell script.
Default certificate
and key
The default certificate and key are
provided in ./data/damlserver.pfx. A
certificate other than the default must
be created and installed manually. See
Chapter 5, “Configuring SSL
authentication for the RACF adapter,”
on page 71 for more information.
Installation path for
the adapter
The UNIX System Services file system
should have at least 80 megabytes of
space available. This path name is
specified in install.sh and config.sh
UNIX System Services shell script.
Data set size
adjustment
Temporary data set sizes in
reconciliation should be adjusted
according to the size of the RACF
database unload for your installation.
If the VSAM group file is utilized, its
size should be adjusted, following an
initial reconciliation.
For the UNIX System Services
components, it is recommended that
approximately 80 megabytes of space
be available in the file system. If a
separate file system is created for
these components, it should not be
shared with other systems.
Chapter 3. Installing and configuring the RACF adapter 11
Table 2. Installation worksheet (continued)
Option Description, default, note Value
APPC/MVS mode
name
For communication to be established
between two end points with
APPC/MVS, SNA (Systems Network
Architecture) requires a set of session
parameters, or a bind image to
accomplish this. This is referred to
through optional specification of a
Mode Name in the RACF adapter.
If left unspecified, APPC/MVS will
generate acceptable session
parameters, allowing communication
to occur.
Optionally, you may specify a named
set of session parameters that have
been predefined. These session
parameters are selected through
specification of a Mode Name, when
configuring the adapter. A Mode
Name is an 8 character string, that
represents a predefined set of session
parameters.
For additional information, please
refer to: z/OS MVS Planning:
APPC/MVS Management, Document
Number SA22-7599.
VSAM file name for
scoped reconciliation
If scoped reconciliation is to be
performed, a VSAM file is required
(job ITIMVSAM). You can name the
VSAM file to correspond to an
adapter instance name.
If scoped reconciliation is NOT
performed, a VSAM file is not
required, and reconciliation
transaction does not require program
steps that execute ITIMGSCP. Also, a
GROUP DD statement is not required
for the ITIMREC2 program step.
Started task name Specify a name for the started task for
an adapter instance. The ITIAGNT
member is the sample JCL provided
for the adapter startup. It is
recommended a component of the
started task name be indicative of the
adapter instance name. It is
recommended that the started task
name be limited to no more than 7
characters, to eliminate ambiguity
when shutting down the adapter.
12 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 2. Installation worksheet (continued)
Option Description, default, note Value
Adapter port number The TCP/IP port number to be
utilized by the adapter. This will be
entered when configuring the UNIX
System Services component. Each
adapter instance should have a unique
TCP/IP port number. If two adapters
have utilize the same port number,
only one of the adapters may be
active at any one time.
RACF adapter activation checklist
Complete the following checklist for activating the RACF Adapter.
1. Upload the adapter package.
2. Install the MVS executables.
3. Install the UNIX executables.
4. Configure the UNIX component.
5. Configure the MVS backend component.
a. Set up the RACF environment variables.
b. Set up the started task, JCL.6. Install the adapter profile on the Tivoli Identity Manager Server.
7. Configure the server.
8. Activate the RACF Adapter.
9. Run the adapter test to ensure end-to-end connectivity.
Step 1: Upload the adapter package
This procedure describes the process of uploading and receiving the installation
package on the MVS platform.
1. The Tivoli Identity Manager RACF Adapter installation package is available for
download from IBM’s Web site. Contact your IBM account representative for
the Web address and download instructions.
For reference, we will assume this file is named ITIM.UPLOAD.XMI.
2. On MVS, create a sequential file, with RECFM=FB, LRECL=80, with a primary
allocation of 30 megabytes (approximately 25 cylinders on a 3390).
Chapter 3. Installing and configuring the RACF adapter 13
Menu RefList Utilities Help
_____________________________________________________________________________
Data Set Utility
Option ===> A
A Allocate new data set C Catalog data set
R Rename entire data set U Uncatalog data set
D Delete entire data set S Short data set information
blank Data set information V VSAM Utilities
ISPF Library:
Project . . IBMUSER Enter "/" to select option
Group . . . PDS / Confirm Data Set Delete
Type . . . . CNTL
Other Partitioned, Sequential or VSAM Data Set:
Data Set Name . . . ITIM.UPLOAD.XMI
Volume Serial . . . (If not cataloged, required for option "C")
Data Set Password . . (If password protected)
Menu RefList Utilities Help
_____________________________________________________________________________
Allocate New Data Set
Command ===>
Data Set Name . . . : IBMUSER.ITIM.UPLOAD.XMI
Management class . . . (Blank for default management class)
Storage class . . . . (Blank for default storage class)
Volume serial . . . . (Blank for system default volume) **
Device type . . . . . (Generic unit or device address) **
Data class . . . . . . (Blank for default data class)
Space units . . . . . mb (BLKS, TRKS, CYLS, KB, MB, BYTES
or RECORDS)
Average record unit (M, K, or U)
Primary quantity . . 30 (In above units)
Secondary quantity 2 (In above units)
Directory blocks . . 0 (Zero for sequential data set) *
Record format . . . . FB
Record length . . . . 80
Block size . . . . .
Data set name type : (LIBRARY, HFS, PDS, or blank) *
(YY/MM/DD, YYYY/MM/DD
Expiration date . . . YY.DDD, YYYY.DDD in Julian form
Enter "/" to select option DDDD for retention period in days
Allocate Multiple Volumes or blank)
( * Specifying LIBRARY may override zero directory block)
( ** Only one of these fields may be specified)
3. From your workstation, upload, in BINARY, the ITIM.UPLOAD.XMI file from
your workstation to the MVS pre-allocated file you just created.
14 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
C:\temp>ftp mvs.mycompany.com
Connected to 192.168.1.1.
220-FTPD1 IBM FTP CS V1R4 at mvs.mycompany.com, 18:42:22 on 2003-11-10
220 Connection will close if idle for more than 5 minutes.
User (192.168.1.1:(none)): ibmuser
331 Send password please.
Password:
230 IBMUSER is logged on. Working directory is "IBMUSER.".
ftp> binary
200 Representation type is Image
ftp> put itim.upload.xmi
200 Port request OK.
125 Storing data set IBMUSER.ITIM.UPLOAD.XMI
250 Transfer completed successfully.
ftp: 19627440 bytes sent in 20.58Seconds 953.71Kbytes/sec.
ftp> quit
221 Quit command received. Goodbye.
C:\temp>
4. Execute the following command from the TSO shell command prompt:
RECEIVE INDATASET(ITIM.UPLOAD.XMI)
When prompted for parameters, accept the defaults by pressing Enter. This will
create a partitioned dataset named ITIM.UPLOAD.
In ITIM.UPLOAD will be four members:
Table 3. RACF Adapter package contents
INSTALL1 A REXX exec that generates JCL used to unpack and install the remainder of
the installables.
XCNTL XMIT format installation data set.
XEXEC XMIT format REXX execs.
XLOAD XMIT format MVS load library with executables.
XTAR XMIT format TAR file, to be installed in UNIX System Services.
The directories and files that will be created during the installation process are
show in the following table:
Chapter 3. Installing and configuring the RACF adapter 15
Table 4. Install directories and files
MVS load library
ITIMGSCP Group tree scoping build
program
ITIMRECO Stage 1 reconciliation,
reformatting and
transformation.
ITIMREC2 Stage 2 reconciliation,
scoping and conveyance to
adapter proper.
UNIX System Services directory
./lib ErmApiDaml.so DAML protocol DLL
libicudata26.1.dll ICU (International
Components for Unicode)
data DLL
libicui18n26.1.dll ICU DLL
libicuuc26.1.dll ICU DLL
libAdkApi.dll ADK (Agent Developer Kit)
library DLL
libErmApi.dll ERMA (Enrole Remote
Management API) library
DLL
./bin certTool Tool to create digital
certificates.
agentCfg Adapter configuration tool.
Can only be utilized once
adapter is initialized.
racfAgent Main RACF adapter
executable.
regis Registry creation tool.
ermtool Tool to test adapter, without
a server.
IsamTool Tool to debug problems with
Event Notification ISAM file.
./log Will contain the logs created
by adapter.
./data Will contain the Adapter
Registry (or registries)
Step 2: Install the MVS executables
Execute the REXX exec called INSTALL1 to create an MVS job to unpack the
remainder of the ITIM.UPLOAD file.
This REXX script allows for the generation of a batch job stream to unpack the
MVS components, or the files may be interactively unpacked. This script may be
run repeatedly. If the batch job stream is generated, it may also be re-executed.
Execute the exec from the TSO shell command prompt:
exec ’ibmuser.itim.upload(install1)’
16 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
You will be prompted for a high level qualifier for four MVS data sets to be
extracted. You will also be prompted for a UNIX System Services directory into
which two files will be placed. The UNIX System Services directory must exist,
and you must have permission to create these files in the directory.
This script will gives the option of creating a batch job stream or installing the files
during the execution of the script. The following scenario reflects the instream
installation of the files. If a batch job is chosen to be generated, the member
INSTALLB will be placed into the data set where INSTALL1 exists.
##########################################################
# #
# Tivoli Identity Manager RACF agent installation #
# ...step 1... #
# #
##########################################################
This is step 1 in the installation process which will
unpack the file you are executing this REXX exec from.
There will be 4 output files created from this exec,
and two files will be placed in the USS file system.
The default high level qualifier for these data sets will be
--------> IBMUSER.ITIM
Do you want to change this high level qualifier? (Y/N)
n
You must provide a Unix System Services directory into which
two files must be placed.
This directory must already exist.
The files transfered into Unix System Services will be:
1) ’IBMUSER.ITIM.CNTL(INSTALL2)’ as file ’install.sh’
2) ’IBMUSER.ITIM.CNTL(INSTALL3)’ as file ’config.sh’
3) ’IBMUSER.ITIM.TAR’ as file ’racf.tar’.
This directory name is CaSe SeNsItIvE!
Please enter a fully qualified Unix directory path:
/u/ibmuser/itim
The directory chosen is /u/ibmuser/itim.
Is this directory name correct? (Y/N)
y
The path used will be /u/ibmuser/itim.
Do you wish to create a batch job stream, or would you rather
complete the file extraction online?
Enter ’BATCH’ or ’ONLINE’ (case insensitive):
online
This exec will exit, and execute the following commands.
In the event there is an error, you may re-run this exec,
after having corrected the error.
Here are the commands:
RECEIVE INDA(’IBMUSER.ITIM.UPLOAD(XCNTL)’)
DATASET(’IBMUSER.ITIM.CNTL’)
RECEIVE INDA(’IBMUSER.ITIM.UPLOAD(XEXEC)’)
DATASET(’IBMUSER.ITIM.EXEC’)
RECEIVE INDA(’IBMUSER.ITIM.UPLOAD(XLOAD)’)
DATASET(’IBMUSER.ITIM.LOAD’)
RECEIVE INDA(’IBMUSER.ITIM.UPLOAD(XTAR)’)
DATASET(’IBMUSER.ITIM.TAR’)
OPUT ’IBMUSER.ITIM.CNTL(INSTALL2)’ ’/u/ibmuser/itim/install.sh’
OPUT ’IBMUSER.ITIM.CNTL(INSTALL3)’ ’/u/ibmuser/itim/config.sh’
OPUT ’IBMUSER.ITIM.TAR’ ’/u/ibmuser/itim/racf.tar’ BINARY
Now exiting and executing the above commands...
The results from executing the INSTALL1 exec will be the following four MVS data
sets:
v ITIM.CNTL
Chapter 3. Installing and configuring the RACF adapter 17
v ITIM.EXEC
v ITIM.LOAD
v ITIM.TAR
Three UNIX System Services files, placed into the specified directory, named:
v config.sh
v install.sh
v racf.tar
Step 3: Install the UNIX System Services executables
If the INSTALLB job ran successfully or the files were unpacked interactively, there
will be two files in the directory you chose (in this example /u/itim).
You must enter the UNIX System Services shell environment from TSO or a telnet
session with the following command:
omvs
Change to the directory where these files were placed. This will be the install path
entered in step 2 above. Execute the following command:
sh install.sh
When running the adapter UNIX System Services installation script, there are
several items which you must provide information for during the installation:
v The fully qualified adapter installation directory.
v Whether or not you want to install the executables. This only needs to be done
once. If configuring the adapter, it is not required to reinstall the executables.
The following is a sample UNIX System Services shell session, running the
installation script.
18 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
IBM
Licensed Material - Property of IBM
5694-A01 (C) Copyright IBM Corp. 1993, 2001
(C) Copyright Mortice Kern Systems, Inc., 1985, 1996.
(C) Copyright Software Development Group, University of Waterloo, 1989.
All Rights Reserved.
U.S. Government users - RESTRICTED RIGHTS - Use, Duplication, or
Disclosure restricted by GSA-ADP schedule contract with IBM Corp.
IBM is a registered trademark of the IBM Corp.
IBMUSER:/: >cd /u/ibmuser/itim
IBMUSER:/u/ibmuser/itim: >ls -l
total 82880
-rw------- 1 ZFS SYS1 34587 Oct 7 14:32 config.sh
-rw------- 1 ZFS SYS1 9558 Oct 7 14:32 install.sh
-rwx------ 1 ZFS SYS1 42384384 Oct 7 14:32 racf.tar
IBMUSER:/u/ibmuser/itim: >sh install.sh
***********************************************************************
* IBM Tivoli Identity Manager - RACF Agent Installation *
* ...step 2 *
***********************************************************************
Enter racf Agent absolute (or full) installation directory
/u/ibmuser/itim
--------------------------------------------------
Do you want to install the racf Agent now? (Y/N):
y
Installing racf Agent files
USTAR Version 00
x ., 0 bytes, 0 tape blocks
x ./bin, 0 bytes, 0 tape blocks
x ./bin/agentCfg, 1843200 bytes, 3600 tape blocks
x ./bin/ermtool, 1155072 bytes, 2256 tape blocks
x ./bin/racfAgent, 323584 bytes, 632 tape blocks
x ./bin/racfAgent, 323584 bytes, 632 tape blocks
x ./bin/regis, 1568768 bytes, 3064 tape blocks
x ./bin/CertTool, 5181440 bytes, 10120 tape blocks
x ./bin/IsamTool, 1077248 bytes, 2104 tape blocks
x ./data, 0 bytes, 0 tape blocks
x ./data/damlserver.pfx, 1581 bytes, 4 tape blocks
x ./lib, 0 bytes, 0 tape blocks
x ./lib/libicudata26.1.dll, 17031168 bytes, 33264 tape blocks
x ./lib/libicui18n26.1.dll, 4325376 bytes, 8448 tape blocks
x ./lib/libicuuc26.1.dll, 3174400 bytes, 6200 tape blocks
x ./lib/libAdkApi.dll, 1687552 bytes, 3296 tape blocks
x ./lib/libErmApi.dll, 1003520 bytes, 1960 tape blocks
x ./lib/ErmApiDamlO.so, 3997696 bytes, 7808 tape blocks
x ./log, 0 bytes, 0 tape blocks
Installation ended.
IBMUSER:/u/ibmuser/itim: >
In the above example, we have only installed the adapter executables.
Step 4: Configure the UNIX System Services Component
To configure the UNIX System Services component, you must get into the OMVS
shell. By default, SSL is not enabled, and will not be configured by using the
config.sh script. However, the following example does use the config.sh script.
Change into the directory where the config.sh shell script exists, and execute it.
sh config.sh
Chapter 3. Installing and configuring the RACF adapter 19
You will be prompted as to whether you wish to install or configure. Choose the
option to configure. This configuration process will create what is known as an
adapter registry file, which contains the adapter options, and a digital certificate.
There are many options that may be set within an adapter registry file, but this
initial process will configure those options to get the adapter up, running, and
connected to the server.
What follows is an example session with the config.sh script, navigating through
configuration:
IBMUSER:/u/ibmuser/itim: >ls -l
total 82944
drwxrwxr-x 2 ZFS SYS1 8192 Sep 30 11:57 bin
-rw------- 1 ZFS SYS1 34587 Oct 7 14:32 config.sh
drwxrwxr-x 2 ZFS SYS1 8192 Sep 24 15:00 data
-rw------- 1 ZFS SYS1 9558 Oct 7 14:32 install.sh
drwxrwxr-x 2 ZFS SYS1 8192 Sep 29 09:28 lib
drwxrwxr-x 2 ZFS SYS1 8192 Sep 21 12:00 log
-rwx------ 1 ZFS SYS1 42384384 Oct 7 14:32 racf.tar
IBMUSER:/u/ibmuser/itim: >sh config.sh
***********************************************************************
* IBM Tivoli Identity Manager - RACF Agent Configuration *
* ...step 3 *
***********************************************************************
Enter racf Agent absolute (or full) installation directory
/u/ibmuser/itim
--------------------------------------------------
No agent name has been chosen, and will default to
-----> racfAgent <-----
Do you wish to change the agent name? (Y/N):
n
Agent name will be racfAgent
--------------------------------------------------
Do you want to configure the racf Agent now? (Y/N):
y
Creating configuration data
--------------------------------------------------
The default TCP/IP port number used is 45580.
Do you wish to use a different port number? (Y/N):
n
--------------------------------------------------
The default APPC transaction name for the command executor
is ITIMCMD.
Do you wish to use a different the transaction name? (Y/N):
n
APPC command executor transaction name is set to ITIMCMD
--------------------------------------------------
The default APPC transaction name for reconciliation
is ITIMRECO.
Do you wish to use a different the transaction name? (Y/N):
n
APPC reconciliation transaction name is set to ITIMRECO
--------------------------------------------------
20 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
The APPC/MVS BASELU will be the originating Logical Unit (LU)
name.
Do you wish to set a specific originating LU name? (Y/N):
y
Enter a 1 to 8 character APPC/MVS originating LU name:
itimorig
APPC/MVS originating LU name is set to ITIMORIG
--------------------------------------------------
The APPC/MVS destination logical unit (LU) name will be the
same as the origination LU name, unless specified.
Do you wish to set a specific destination LU name? (Y/N):
y
Enter a 1 to 8 character APPC/MVS destination LU name:
itimdest
APPC/MVS destination LU name is set to ITIMDEST
--------------------------------------------------
The APPC/MVS ’mode name’ may be allowed to default, or you
may wish to utilize a specific mode name.
Do you wish to set a APPC/MVS mode name? (Y/N):
y
Enter a 1 to 8 character APPC/MVS mode name:
#intersc
APPC/MVS mode name is set to #INTERSC
--------------------------------------------------
By default, when this agent is requested to set a password,
they will be set as EXPIRED (password change forced at next
logon).
Do you wish the agent to set NON-EXPIRED passwords? (Y/N):
y
PASSEXPIRE agent option is set to FALSE
--------------------------------------------------
The full set of parameters set for the adapter are as follows:
/u/ibmuser/itim/bin/regis -reg /u/ibmuser/itim/data/RACFAGENT.dat -list -protocol DAML
Registry listing for Agent ’/u/ibmuser/itim/data/RACFAGENT.dat’
------------------------------------
Specific:ENROLE_VERSION ’4.0’
Specific:APPCCMD ’ITIMCMD’
Specific:APPCRECO ’ITIMRECO’
Specific:APPCOLU ’ITIMORIG’
Specific:APPCDLU ’ITIMDEST’
Specific:APPCMODE ’#INTERSC’
Specific:PASSEXPIRE ’FALSE’
Main:InstallPath ’/u/ibmuser/itim’
Main:Agent_LogDir ’/u/ibmuser/itim/log’
Main:Agent_LogFile ’racfagent.log’
Main:Agent_ConfiguredProt ’DAML’
--------------------------------------------------
The startup script, if it has not been created,
must exist for the MVS started task to be initiated
Create the racf Agent startup script? (Y/N):
y
Chapter 3. Installing and configuring the RACF adapter 21
Creating startup script
When you edit the started task JCL, on the line that has
the PARM= statement, you will enter the full path and
file name of the script, which is:
/u/ibmuser/itim/bin/racfagent.sh
Configuration ended.
IBMUSER:/u/ibmuser/itim: >
The result of running the USS installation script will be:
v A registry file, in the data/ subdirectory, with the adapter name. (for example,
TESTAGENT.dat)
v A startup script file, for use of the started task JCL, in the bin/ directory. (for
example, testagent.sh). The fully qualified name of this shell script must be
inserted into the started task JCL. For example, if the installation directory is
/u/itim, then the started task JCL will require /u/itim/bin/testagent.sh to be
inserted.
v If or when you wish to add, alter, or remove specific adapter options from a
particular adapter instance, you will have to utilize the agentCfg utility,
described in Chapter 4, “Configuring the RACF adapter in IBM Tivoli Identity
Manager,” on page 39.
For the valid RACF adapter registry options, their values and meanings, refer to
Appendix B, “Registry settings,” on page 107.
For more information on how to use agentCfg to modify registry settings, refer to
“Changing registry settings” on page 63.
Step 5: Configure MVS Components
There are several steps to complete when configuring the MVS components of the
RACF Adapter. The jobs that must be run are contained in the ITIM.CNTL data
set:
1. Register the command executor to APPC/MVS
2. Configure the APPC/MVS reconciliation transaction, and register to
APPC/MVS.
3. OPTIONAL: Create the VSAM file for reconciliation scoping function.
4. Create the started task JCL.
5. Establish a RACF user ID under which the adapter will operate.
OPTIONAL:Establish one or more RACF surrogate user ID’s, under which
requests will be processed.
Modify and submit the APPCCMD job
Modify the APPCCMD job in the ITIM.CNTL data set. You must set the TPNAME
field to a chosen APPC/MVS transaction name. It is highly recommended the
APPC transaction name NOT exceed 8 characters, as this will allow the job name
on the job card match the transaction name. A recommended transaction name is
ITIMCMD. This transaction JCL must reference the ITIM.EXEC library, where
REXX execs reside. It is suggested the job name match the transaction name.
22 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
If your installation stores messages in users’ individual message log data sets,
instead of storing user messages in the SYS1.BRODCAST data set, you should
remove the //SYSLBC DD statement from the job stream.
Follow the instructions detailed in the JCL for configuration, taking note of the
chosen APPC/MVS transaction name.
Submit the job. Ensure successful execution. First execution of the job will result in
the first step (transaction deletion) failing. This is expected.
//APPCCMD JOB ACCT,ITIMAGENT,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//******************************************************************
//*LICENSED MATERIALS - PROPERTY OF IBM
//*
//*SOURCE FILE NAME = APPCCMD
//*
//*(C) COPYRIGHT IBM CORP. 1999, 2003 ALL RIGHTS RESERVED
//*
//*US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION OR
//*DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE CONTRACT WITH IBM CORP.
//******************************************************************
//*
//* THIS JCL IS USED TO REGISTER THE APPC/MVS TRANSACTION
//* FOR THE TIVOLI IDENTITY MANAGER COMMAND TRANSACTION.
//*
//* YOU MUST HAVE RACF UPDATE ACCESS TO THE APPC TRANSACTION PROFILE
//* DATA SET TO EXECUTE THIS JOB. IF YOUR INSTALLATION HAS
//* UTILIZED THE PROGRAM CLASS TO PROTECT THE ATBSDFMU UTILITY,
//* THEN AN AUTHORIZED USER MUST HAVE ACCESS TO THIS UTILITY TO
//* EXECUTE THIS JOB.
//*
//* YOU MUST CUSTOMIZE THIS TRANSACTION, PRIOR TO SUBMITTING THIS
//* JCL TO REGISTER THE TRANSACTION.
//*
//* 1. CUSTOMIZE THE JOB CARD TO REFLECT YOUR INSTALLATION STANDARDS.
//*
//* 2. CHANGE THE ?SYSAPPCTP? TEXT TO REFLECT YOUR INSTALLATION’S
//* APPC/MVS TRANSACTION PROFILE DATA SET. IN MANY INSTALLATIONS,
//* THIS MAY BE "SYS1.APPCTP".
//*
//* 3. CHANGE ?ITIMEXEC? TO REFLECT THE TIVOLI IDENTITY MANAGER
//* AGENT EXEC DATA SET INSTALLED. THIS DATA SET SHOULD CONTAIN
//* ALL THE EXECS UTILIZED BY THE AGENT.
//*
//* 4. CHANGE ?APPCCMD? TO REFLECT THE APPC/MVS TRANSACTION NAME
//* CHOSEN FOR THE COMMAND TRANSACTION. THIS IS THE SAME
//* TRANSACTION NAME CONFIGURED INTO THE UNIX COMPONENT.
//*
//* 5. IF YOU ARE NOT UTILIZING THE SYS1.BRODCAST DATA SET FOR YOUR
//* INSTALLATION, YOU MAY REMOVE THE "SYSLBC" DD STATEMENT, THAT
//* REFERENCES SYS1.BRODCAST.
//*
//*
//* THE FIRST TIME THIS JOB IS RUN, THE "TPDELETE" WILL FAIL, AS
//* THE TRANSACTION DOES NOT EXIST. THIS IS NORMAL.
//*
//*
Chapter 3. Installing and configuring the RACF adapter 23
//TPDELETE EXEC PGM=ATBSDFMU,REGION=0K
//SYSPRINT DD SYSOUT=*
//SYSSDLIB DD DSN=?SYSAPPCTP?,DISP=SHR
//SYSSDOUT DD SYSOUT=*
//SYSIN DD *
TPDELETE
TPNAME(?APPCCMD?)
SYSTEM
//TPADD EXEC PGM=ATBSDFMU,REGION=0K
//SYSPRINT DD SYSOUT=*
//SYSSDLIB DD DSN=?SYSAPPCTP?,DISP=SHR
//SYSSDOUT DD SYSOUT=*
//SYSIN DD DATA,DLM=XX
TPADD
TPNAME(?APPCCMD?)
SYSTEM
ACTIVE(YES)
TPSCHED_DELIMITER(##)
TAILOR_SYSOUT(NO)
TAILOR_ACCOUNT(NO)
KEEP_MESSAGE_LOG(NEVER)
CLASS(A)
TPSCHED_TYPE(STANDARD)
JCL_DELIMITER(END_OF_JCL)
//?APPCCMD? JOB
//IKJEFT01 EXEC PGM=IKJEFT01,REGION=0K,PARM=’%ITIMCMD’
//SYSPROC DD DSN=?ITIMEXEC?,DISP=SHR
//SYSLBC DD DISP=SHR,DSN=SYS1.BRODCAST
//SYSTSPRT DD SYSOUT=*,FREE=CLOSE
//SYSTSIN DD DUMMY
END_OF_JCL
##
XX
Modify and submit the APPCRECO job
Modify the APPCRECO job stream in the ITIM.CNTL data set. You must set the
TPNAME field to a chosen APPC/MVS transaction name. It is highly
recommended the APPC transaction name NOT exceed 8 characters, as this will
allow the job name on the job card match the transaction name. A recommended
transaction name is ITIMRECO. This transaction JCL must be tailored for your
installation.
Sizes of the temporary data sets must reflect the amount of space consumed by the
output from the RACF IRRDBU00 program for your installation.
The execution step of IRRDBU00 must reference your RACF database properly. If
database updates are mirrored to the RACF backup database, then the execution of
the IRRDBU00 utility may reference the backup data set, for performance
considerations. UPDATE access to the RACF database is required, even though the
RACF utility IRRDBU00 does NOT update the database. This is restriction to the
use of the IRRDBU00 utility.
If partial, or ’scoped’ reconciliation is to be utilized, a VSAM file must be created
(in the ITIMVSAM job), and referenced in the ITIMGSCP program step, and the
ITIMREC2 step.
If only full reconciliation is to be utilized, the VSAM file is not required, the
ITIMGSCP step may be eliminated, and the GROUP dd statement in the ITIMREC2
program step may be eliminated.
Submit the job. Insure successful execution. First execution of the job will result in
the first step (transaction deletion) failing. This is expected.
24 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
//APPCRECO JOB ACCT,ITIMAGENT,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//******************************************************************
//*LICENSED MATERIALS - PROPERTY OF IBM
//*
//*SOURCE FILE NAME = APPCRECO
//*
//*(C) COPYRIGHT IBM CORP. 1999, 2003 ALL RIGHTS RESERVED
//*
//*US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION OR
//*DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE CONTRACT WITH IBM CORP.
//******************************************************************
//*
//* THIS JCL IS USED TO REGISTER THE APPC/MVS TRANSACTION
//* FOR THE TIVOLI IDENTITY MANAGER RECONCILIATION PROCESS.
//*
//* YOU MUST CUSTOMIZE THIS TRANSACTION, PRIOR TO SUBMITTING THIS
//* JCL TO REGISTER THE TRANSACTION.
//*
//* 1. CUSTOMIZE THE JOB CARD TO REFLECT YOUR INSTALLATION STANDARDS.
//*
//* 2. CHANGE THE ?SYSAPPCTP? TEXT TO REFLECT YOUR INSTALLATION’S
//* APPC/MVS TRANSACTION PROFILE DATA SET. IN MANY INSTALLATIONS,
//* THIS MAY BE "SYS1.APPCTP".
//*
//* 3. CHANGE ?ITIMLOADLIB? TO REFLECT YOUR INSTALLATION’S NAME OF
//* THE TIVOLI IDENTITY MANAGER AGENT LOAD LIBRARY.
//*
//* 4. CHANGE ?APPCRECO? TO REFLECT THE APPC/MVS TRANSACTION NAME
//* CHOSEN FOR THE COMMAND TRANSACTION. THIS IS THE SAME
//* TRANSACTION NAME CONFIGURED INTO THE UNIX COMPONENT.
//*
//* 5. FOR THE IRRDBU00 STEP:
//* THIS STEP MAY BE OMITTED, IF YOU WISH TO RUN THE IRRDBU00
//* PROGRAM OUTSIDE OF THIS APPC TRANSACTION.
//*
//* YOU MUST CODE IN ALL THE DATA SETS THAT COMPRISE YOUR
//* INSTALLATION’S RACF DATABASE.
//* THE ?RACFDB1?, AND POTENTIALLY, ?RACFDB2? THROUGH ?RACFDB"N"?
//* WILL HAVE TO BE CODED, TO INCLUDE ALL THE RACF DATA SETS
//* THAT COMPRISE YOUR ENTIRE RACF DATA BASE.
//*
//* THE USER ID THIS TRANSACTION RUNS AS MUST HAVE UPDATE ACCESS
//* TO THE RACF DATABASE, AS THE IRRDBU00 PROGRAM MUST HAVE
//* UPDATE UPDATE ACCESS TO THE FILES THAT COMPRISE THE RACF
//* DATABASE, EVEN THOUGH NO UPDATES OCCUR.
//*
//* IT IS -RECOMMENDED- THAT "NOLOCKINPUT" BE USED AS A
//* EXECUTION PARAMETER TO THE IRRDBU00 PROGRAM. IF "LOCKINPUT"
//* IS SPECIFIED, THEN ANOTHER INSTANCE OF IRRDBU00 MUST BE
//* EXECUTED, WITH THE "UNLOCKINPUT" PARAMETER SPECIFIED.
//*
//* IF YOUR INSTALLATION HAS SET THE ICHRDSNT OPTION TO
//* DUPLICATE ALL UPDATES TO THE BACKUP DATABASE, IT IS
//* SUGGESTED THE BACKUP DATABASE IS SPECIFIED FOR RUNNING
//* IRRDBU00. PLEASE REFER TO THE "RACF SECURITY
//* ADMINISTRATOR’S GUIDE" FOR MORE INFORMATION ABOUT THE RACF
//* DATABASE UNLOAD UTILITY.
//*
//* 6. FOR THE ITIMRECO STEP:
//* IF YOU HAVE CHOSEN NOT TO RUN THE IRRDBU00 UTILITY IN THIS
//* JOBSTREAM, THEN YOU MUST SPECIFY THE APPROPRIATE DATA SET AS
//* INPUT TO THIS PROGRAM ON THE RACFIN DD STATEMENT. INSURE
//* YOU CODE DISPOSITION APPROPRIATELY, AS THE DEFAULT IS TO
//* DELETE THE INPUT FILE.
//*
//* INSURE THE SPECIFICATIONS FOR SPACE REFLECT THE AMOUNT OF
//* SPACE REQUIRED BY YOUR INSTALLATION’S OUTPUT FROM THE RACF
//* DATABASE UNLOAD UTILITY.
//*
Chapter 3. Installing and configuring the RACF adapter 25
//*
//* DO NOT CHANGE ANY OF THE REFERBACKS SPECIFIED IN THIS STEP,
//* AS THEY ARE NECESSARY FOR PROPER OPERATION. YOU MAY CHANGE
//* THE SPECIFICATION OF UNIT=SYSALLDA, TO A PROPER SMS STORAGE
//* CLASS THAT IS INTENDED FOR TEMPORARY DATA SETS.
//*
//* 7. FOR THE ITIMGSCP STEP:
//* THIS IS NOT REQUIRED -ONLY- IF THE RECONCILIATION
//* PROCESS WILL -ALWAYS- BE A FULL RECONCILIATION.
//* IF A ONLY A PORTION OF THE RACF DATABASE IS TO BE
//* RECONCILED, BASED UPON RACF SCOPE-OF-AUTHORITY RULES, THEN
//* THIS STEP, AND THE VSAM FILE DEFINITION, ARE REQUIRED.
//*
//* IF THIS STEP IS USED, CHANGE ?HLQ? TO REFLECT THE
//* VSAM FILE NAME CREATED BY THE ITIMVSAM JOBSTREAM.
//*
//* 8. FOR THE ITIMREC2 STEP:
//* THE GROUP DD STATEMENT IS NOT REQUIRED, ONLY IF
//* RECONCILIATION IS TO -ALWAYS- BE A FULL RECONCILIATION.
//*
//* CHANGE ?HLQ? TO REFLECT THE VSAM FILE CREATED BY THE
//* ITIMVSAM JOBSTREAM.
//*
//* IF ITIMGSCP PROGRAM IS INCLUDED, THEN SPECIFY THE NAME OF
//* THE VSAM FILE PRODUCED BY THE ITIMGSCP, IN THE PRIOR STEP.
//*
//* IF THE ITIMGSCP PROGRAM IS EXCLUDED, THEN YOU MAY OMIT THE
//* GROUP DD STATEMENT FROM THIS STEP.
//*
//* IT IS RECOMMENDED THAT FOLLOWING A RECONCILIATION THAT UTILIZES
//* THE VSAM FILE, THAT A "LISTCAT ENTRY(XXXX) ALL" BE EXECUTED, TO
//* INSPECT THE NUMBER OF EXTENTS THE FILE HAS USED, AND RE-ALLOCATE
//* THE FILE TO REFLECT THE RESULTING AMOUNT OF SPACE IT HAS USED.
//*
//* THE FIRST TIME THIS JOB IS RUN, THE "TPDELETE" WILL FAIL, AS
//* THE TRANSACTION DOES NOT EXIST. THIS IS NORMAL.
//*
//******************************************************************
//TPDELETE EXEC PGM=ATBSDFMU,REGION=0K
//SYSPRINT DD SYSOUT=*
//SYSSDLIB DD DSN=?SYSAPPCTP?,DISP=SHR
//SYSSDOUT DD SYSOUT=*
//SYSIN DD *
TPDELETE
TPNAME(?APPCRECO?)
SYSTEM
//TPADD EXEC PGM=ATBSDFMU,REGION=0K
//SYSPRINT DD SYSOUT=*
//SYSSDLIB DD DSN=?SYSAPPCTP?,DISP=SHR
//SYSSDOUT DD SYSOUT=*
//SYSIN DD DATA,DLM=XX
TPADD
TPNAME(?APPCRECO?)
SYSTEM
ACTIVE(YES)
TPSCHED_DELIMITER(##)
TAILOR_SYSOUT(NO)
TAILOR_ACCOUNT(NO)
KEEP_MESSAGE_LOG(NEVER)
CLASS(A)
TPSCHED_TYPE(STANDARD)
JCL_DELIMITER(END_OF_JCL)
//?APPCRECO? JOB
//JOBLIB DD DISP=SHR,DSN=?ITIMLOADLIB?
26 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
//*
//IRRDBU00 EXEC PGM=IRRDBU00,PARM=’NOLOCKINPUT’,REGION=0K,COND=(0,NE)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//INDD1 DD DISP=SHR,DSN=?RACFDB1?
//*INDD2 DD DISP=SHR,DSN=?RACFDB2?
//*INDD3 DD DISP=SHR,DSN=?RACFDB3?
//OUTDD DD DISP=(,PASS,DELETE),LRECL=4096,RECFM=VB,
// SPACE=(CYL,(200,30),RLSE),
// UNIT=SYSALLDA
//*
//ITIMRECO EXEC PGM=ITIMRECO,REGION=0K,COND=(0,NE)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSOUT DD DUMMY
//RACFIN DD DSN=*.IRRDBU00.OUTDD,DISP=(OLD,DELETE)
//RACF01XX DD DISP=(,PASS,DELETE),
// UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)
//RACF02XX DD DISP=(,PASS,DELETE),
// UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)
//*
//TEMP0205 DD UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)
//TEMP1205 DD UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)
//*
//TEMP02XX DD UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)
//*
//SORTIN01 DD DSN=*.TEMP02XX,VOL=REF=*.TEMP02XX,UNIT=AFF=TEMP02XX,
// DISP=(OLD,PASS)
//SORTIN02 DD DSN=*.TEMP0205,VOL=REF=*.TEMP0205,UNIT=AFF=TEMP0205,
// DISP=(OLD,PASS)
//*
//ITIMGSCP EXEC PGM=ITIMGSCP,REGION=0K,COND=(0,NE),
// PARM=’DD:SYSPRINT DD:INPUT DD:OUTPUT’
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//INPUT DD DISP=(OLD,PASS),DSN=*.ITIMRECO.RACF01XX
//OUTPUT DD DISP=OLD,AMP=’BUFNI=10,BUFND=10’,DSN=?HLQ?.GROUPS
//*
//ITIMREC2 EXEC PGM=ITIMREC2,REGION=0K,COND=(0,NE)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//GROUP DD DISP=OLD,AMP=’BUFNI=10,BUFND=10’,DSN=?HLQ?.GROUPS
//RACF01XX DD DISP=(OLD,DELETE),DSN=*.ITIMRECO.RACF01XX
//RACF02XX DD DISP=(OLD,DELETE),DSN=*.ITIMRECO.RACF02XX
//*
END_OF_JCL
##
XX
Modify and submit the ITIMVSAM job
If partial, or scoped reconciliation is to be utilized, edit the ITIMVSAM job stream
in the ITIM.CNTL data set. Change the name of the VSAM file to reflect the name
chosen in the APPCRECO job stream. The size of this VSAM file should be
checked, following a reconciliation, to insure proper sizing of the VSAM data set.
This VSAM data set contains one record per group in the RACF database. The
records are variable length, and their length depends upon the level of depth
within the RACF group tree structure. Using the default maximum VSAM record
size of 512 will allow for a RACF group tree depth of 29 groups. The maximum
record length depends upon the maximum depth of the RACF group tree. The
default maximum record length of 512 will allow for a RACF database of group
tree depth of 29.
The specific calculation is as follows:
33 + ( 16 * "N" )
Chapter 3. Installing and configuring the RACF adapter 27
Where ’n’ is the maximum depth of the RACF group tree. You should set average
record length equal to the max record length chosen, which will lessen ci/ca split
activity. Maximum record length may be 32,767, where the maximum depth of the
RACF group tree is 2044. Utilize the smallest reasonable record size that is
representative of your installation’s RACF group tree structure.
This job may be run at any time, as long as a reconciliation process is not
executing. The VSAM file does not require initialization. The content is not
relevant beyond the life of execution of the reconciliation process, and therefore, is
not required to be backed up.
Submit the job.
//ITIMVSAM JOB ACCT,ITIMAGENT,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//******************************************************************
//*LICENSED MATERIALS - PROPERTY OF IBM
//*
//*SOURCE FILE NAME = APPCRECO
//*
//*(C) COPYRIGHT IBM CORP. 1999, 2003 ALL RIGHTS RESERVED
//*
//*US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION OR
//*DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE CONTRACT WITH IBM CORP.
//******************************************************************
//*
//* THIS JOB STREAM CREATES THE OPTIONAL VSAM FILE UTILIZED BY THE
//* ITIMRECO TRANSACTION. (THE APPCRECO JOB INSERTS THE ITIMRECO
//* TRANSACTION INTO APPC/MVS.)
//*
//* CHANGE ?HLQ? TO A HIGH LEVEL QUALIFIER OF YOUR CHOOSING.
//*
//* WHETHER THIS FILE WILL RESIDE UPON AN SMS MANAGED VOLUME WILL
//* DEPEND UPON YOUR INSTALLATION’S SMS STANDARDS. YOU MAY HAVE TO
//* SET A PROPER "VOLUME(XXXXXX)" PARAMETER, AND/OR A PROPER
//* "STORCLAS(YYYYYYYY)" PARAMETER.
//*
//* THIS FILE’S CONTENTS ARE BOTH CREATED AND USED WITHIN THE
//* RECONCILIATION PROCESS. ITS CONTENTS ARE NOT NEEDED EITHER PRIOR
//* TO, NOR FOLLOWING A RECONCILIATION. IT DOES NOT NEED TO BE
//* BACKED UP, NOR RESTORED. IT MAY BE RE-CREATED AT ANY TIME. IN
//* EFFECT, IT ITS USE IS TEMPORARY ONLY WITHIN THE RECONCILIATION
//* PROCESS.
//*
//* THIS JOB STREAM IS REQUIRED, ONLY IF THE ITIMGSCP AND ITIMREC2
//* PROGRAMS REQUIRE IT FOR A SCOPED RECONCILIATION PROCESS.
//*
//* PUT ANOTHER WAY, IF ONLY FULL RECONCILIATIONS ARE TO BE PERFORMED,
//* THEN THIS FILE, AND REFERENCES TO IT IN THE RECONCILIATION
//* TRANSACTION, ARE NOT REQUIRED.
//*
//* THIS FILE IS NOT SHARED AT ANY TIME WITH OTHER APPLICATIONS, SO
//* SHAREOPTIONS (1,3) IS APPROPRIATE.
//*
//* THIS FILE MUST HAVE THE "REUSE" ATTRIBUTE, AS IT IS REINITIALIZED
//* EVERYTIME THE ITIMGSCP PROGRAM IS EXECUTED.
//*
//* THERE IS NO NEED TO INITIALIZE THIS VSAM CLUSTER.
//*
//* IT IS RECOMMENDED THAT FOLLOWING A REPRESENTATIVE SIZE
//* RECONCILIATION PROCESS THAT UTILIZES THE VSAM FILE, THAT A
//* "LISTCAT ENTRY(DSN) ALL" BE EXECUTED, TO INSPECT THE NUMBER OF
//* EXTENTS THE FILE HAS USED, AND RE-ALLOCATE THE FILE TO REFLECT
//* THE RESULTING AMOUNT OF SPACE IT HAS USED. INSPECT THE
//* "HIGH-USED-RBA", THE NUMBER OF EXTENTS, NUMBER OF CONTROL AREA
//* AND CONTROL INTERVAL SPLITS.
//*
//* THE MAXIMUM RECORD LENGTH DEPENDS UPON THE MAXIUMU DEPTH OF THE
//* RACF GROUP TREE. THE DEFAULT MAXIUMUM RECORD LENGTH OF 512
//* WILL ALLOW FOR A RACF DATABASE OF GROUP TREE DEPTH OF 29.
28 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
//*
//* THE SPECIFIC CALCULATION IS AS FOLLOWS:
//* 33 + ( 16 * "N" )
//* WHERE "N" IS THE MAXIMUM DEPTH OF THE RACF GROUP TREE
//*
//* IT IS RECOMMENDED TO SET AVERAGE RECORD LENGTH EQUAL
//* TO MAX RECORD LENGTH CHOSEN, AS THIS WILL LESSEN CI/CA SPLIT
//* ACTIVITY.
//*
//* MAXIMUM RECORD LENGTH MAY BE 32767, WHERE THE MAXIMUM DEPTH
//* OF THE RACF GROUP TREE IS 2044. IT IS RECOMMENDED YOU UTILIZE
//* THE SMALLEST REASONABLE RECORD SIZE THAT IS REPRESENTATIVE OF
//* YOUR INSTALLATION’S RACF GROUP TREE STRUCTURE.
//*
//******************************************************************
//DEFINE EXEC PGM=IDCAMS,REGION=0K//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DELETE ?HLQ?.GROUPS CLUSTER
SET MAXCC = 0
SET LASTCC = 0
DEFINE CLUSTER(NAME(?HLQ?.GROUPS) -
INDEXED -
KEYS(12 0) -
VOLUME(XXXXXX) -
STORCLAS(YYYYYYYY) -
RECORDSIZE(512 512) -
FREESPACE(30 10) -
SHAREOPTIONS(1 3) -
CYLINDERS(25 5) -
NOIMBED -
NOREPLICATE -
REUSE -
SPEED) -
DATA(CONTROLINTERVALSIZE(4096)) -
INDEX(CONTROLINTERVALSIZE(4096))
Create started task
The member ITIAGNT is sample JCL supplied in the ITIM.CNTL data set. It is
highly recommended the member name of the started task JCL in the procedure
library be seven (7) characters or less, as it will facilitate a less complex method of
shutting down the adapter. It is also recommended the name of the started task
relate to the name of the adapter instance to which it relates.
In the ’PARM=’ component of the EXEC JCL statement is specified the full name of
the UNIX System Services shell script to start the adapter. This script name is
generated from the UNIX System Services configuration step. You must insert this
fully qualified script name into this JCL, once the USS component has been
configured.
Chapter 3. Installing and configuring the RACF adapter 29
//*ITIAGNT JOB ACCT,ITIM,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//******************************************************************
//*LICENSED MATERIALS - PROPERTY OF IBM
//*
//*SOURCE FILE NAME = ITIAGNT
//*
//*(C) COPYRIGHT IBM CORP. 1999, 2003 ALL RIGHTS RESERVED
//*
//*US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION OR
//*DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE CONTRACT WITH IBM CORP.
//******************************************************************
//RACFAGNT EXEC PGM=BPXBATCH,REGION=0K,
// PARM=’SH /u/itim/bin/racfagent.sh’
//STDOUT DD PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATH=’/dev/null’,
// PATHMODE=SIRWXU
//STDERR DD PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATH=’/dev/null’,
// PATHMODE=SIRWXU
Configure RACF access
Determine your needs and configure how the adapter will access RACF
information.
RACF user ID
The adapter must run under a valid RACF user ID, with an OMVS segment, and a
valid UID. This user’s default group must have an OMVS segment with a valid
GID. The adapter must be able to acquire sufficient storage for operation, using the
OMVS segment ASSIZEMAX parameter.
Unless surrogate user ID’s are being used, the adapter must at least be connected
GROUP SPECIAL over a group of users that will be managed. If the adapter has
GROUP SPECIAL, it will require CLASS AUTHORITY of USER to be able to create
and remove user ID’s from the system (CLAUTH(USER)). This user ID should be
defined as RACF ’PROTECTED’. This is accomplished with the NOPASSWORD
operand on the ADDUSER (or ALTUSER) command.
In the following commands, the use of SYS1 as owner and DFLTGRP may be
changed to a different group of your choosing. If the TIM adapter is to manage all
accounts on this RACF database, then the following definition would define this
user:
ADDUSER ITIAGNT OWNER(SYS1) DFLTGRP(SYS1) SPECIAL AUDITOR NOPASSWORD
ALTUSER ITIAGNT OMVS(UID(uu) PROG(’/bin/sh’) HOME(’/u/itim’) ASSIZEMAX(2147483647))
If the started task JCL is called ITIAGNT, then the following STARTED class profile
should be defined:
RDEFINE STARTED ITIAGNT.* STDATA(USER(ITIAGNT) GROUP(SYS1) TRACE(YES))
SETROPTS RACLIST(STARTED) REFRESH
The ″TRACE(YES)″ operand indicates to RACF that there will be a message
displayed upon the console, indicating that this STARTED class profile was utilized
in starting this adapter.
In the following example, group xxxx indicates the group which the ITIM adapter
will have RACF scope-of-authority over. To define the ITIM adapter as a GROUP
SPECIAL user, the following is an example of making this defintion:
30 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
ADDUSER ITIAGNT DFLTGRP(xxxx) OWNER(xxxx) CLAUTH(USER) NOPASSWORD
CONNECT ITIAGNT GROUP(xxxx) SPECIAL AUDITOR
RDEFINE STARTED ITIAGNT.* STDATA(USER(ITIAGNT) GROUP(xxxx) TRACE(YES))
SETROPTS RACLIST(STARTED) REFRESH
Additionally, if the GROUP SPECIAL attribute is utilized, then the adapter may
require the ability to manage non-RACF segment information. The adapter, or
surrogate, user ID(s), must have access to the appropriate FIELD class profile(s) to
manage these segments.
If the adapter RACF user ID is to be allowed to manage all non-RACF segments,
then you may define a FIELD class profile as follows:
RDEFINE FIELD USER.*.** UACC(NONE)
PE USER.*.** AC(ALTER) ID(ITIAGNT) CLASS(FIELD)
SETROPTS RACLIST(FIELD) REFRESH
If the adapter user ID has SYSTEM SPECIAL, it will be assumed the adapter will
be managing the entire RACF database. If this is the case, there is no issue with the
FIELD class profiles, or CLAUTH(USER).
You may have to create a RACF STARTED class profile, allowing the adapter
started task to run under this specific user id. An example of this definition is as
follows:
RDEFINE STARTED ITIAGNT.* STDATA(USER(ITIAGNT) TRACE(YES))
SETROPTS RACLIST(STARTED) REFRESH
User ID propagation
The adapter running in UNIX System Services must have the ability to propagate
the RACF user ID it is running as, to the APPC/MVS environment. This is
accomplished through the definition of one or more profiles in the RACF APPCLU
general resource class.
There are two ways this may be configured:
Use of a single APPC/MVS base logical unit:
By default, the APPC/MVS baselu will be utilized by the RACF adapter,
both for the originating and destination logical units.
If this method is utilized, only one RACF APPCLU profile needs to be
defined.
The form of the RACF command to define this profile could take two
forms.
1. If the APPC/MVS LUADD statement takes the default, or has specified
NONQN, then this command will take the following form:
RDEFINE APPCLU netid.baselu.baselu SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
2. If the APPC/MVS LUADD statement has specified NQN, then this
command will take the following form:
RDEFINE APPCLU netid.baselu.netid.baselu SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
In the above examples, netid is the VTAM NETID (Network ID) selected
for use for VTAM in your environment. The baselu specifies the VTAM
logical unit name for the BASELU defined to APPC/MVS. The xxxxxxxx in
the SESSKEY field is a session key, or password, utilized for security when
the APPC/MVS sessions are initiated.
Chapter 3. Installing and configuring the RACF adapter 31
Once this profile has been defined, an MVS console command must be
issued to VTAM to inform VTAM of this profile being defined or updated:
F VTAM,PROFILES,ID=baselu
For example, if your installation’s VTAM NETID is set to MYNET and
your APPC/MVS BASELU is configured as MVSLU01, and NONQN has
been specified or defaulted, the RACF APPCLU profile could be defined as
follows:
RDEFINE APPCLU MYNET.MVSLU01.MVSLU01 SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
Using the above example values, where the LUADD statement has
specified NQN, the RACF APPCLU profile could be defined as follows:
RDEFINE APPCLU MYNET.MVSLU01.MYNET.MVSLU01 SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
Use of a two APPC/MVS logical units:
Your installation may wish to use two separate logical units, not utilizing
the APPC/MVS BASELU definition.
If this method is utilized, two RACF APPCLU profiles need to be defined.
The form of the RACF command to define these profiles could take two
forms:
1. If the APPC/MVS LUADD statements have defaulted or specified
NONQN, then the commands will take the following form (this
example implies that NONQN is used for BOTH logical units):
RDEFINE APPCLU netid.origin.dest SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
RDEFINE APPCLU netid.dest.origin SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
2. If the APPC/MVS LUADD statements has specified NQN, then these
commands will take the following form (This example implies that
NQN is specified for both logical units):
RDEFINE APPCLU netid.origin.netid.dest SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
RDEFINE APPCLU netid.dest.netid.origin SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
Once these profiles have been defined, twoMVS console commands must
be issued to VTAM to inform VTAM of this profile being defined or
updated:
F VTAM,PROFILES,ID=origin
F VTAM,PROFILES,ID=dest
In the above examples, netid is the VTAM Network ID (NETID) selected
for use for VTAM in your environment. The origin and dest specify the
VTAM logical unit names utilized as the originating and destination logical
units defined to APPC/MVS. The xxxxxxxx in the SESSKEY field is a
session key, or password, utilized for security when the APPC/MVS
sessions are initiated.
For example, if your installation’s VTAM NETID is set to MYNET, your
APPC/MVS origin logical unit is named ITIMORIG, dest logical unit is
named ITIMDEST, and NONQN has been specified or defaulted, the
RACF APPCLU profiles will be defined as follows:
32 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
RDEFINE APPCLU MYNET.ITIMORIG.ITIMDEST SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
RDEFINE APPCLU MYNET.ITIMDEST.ITIMORIG SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
Using the above example values, where the LUADD statements have
specified NQN, the RACF APPCLU profiles would be defined as follows:
RDEFINE APPCLU MYNET.ITIMORIG.MYNET.ITIMDEST SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
RDEFINE APPCLU MYNET.ITIMDEST.MYNET.ITIMORIG SESSION(CONVSEC(ALREADYV)
SESSKEY(xxxxxxxx))
Surrogate user ID
If a single adapter will be performing requests for multiple Tivoli Identity Manager
service instances on the server, then surrogate user ID’s must be defined to RACF,
and filled in on the Tivoli Identity Manager service forms.
For the adapter to perform requests using these surrogate user ID’s, you must
define one or more RACF SURROGAT class profiles.
If the adapter RACF user ID is ITIAGNT, and the surrogate RACF user ID is
UNIT1, then the following commands would define the profile:
RDEFINE SURROGAT ATBALLC.UNIT1 UACC(NONE)
PERMIT ATBALLC.UNIT1 CLASS(SURROGAT) AC(READ) ID(ITIAGNT)
SETROPTS RACLIST(SURROGAT) REFRESH
In the above example, the RACF user ID UNIT1 will be the user ID utilized on the
Tivoli Identity Manager Server, in the service definition form, on the RACF User
with Scope-of-Authority over Business Unit field.
When surrogate user ID’s are utilized, the tasks of altering and fetching RACF data
is accomplished under the authority of the surrogate RACF user ID, NOT the
RACF user ID the adapter proper is running as. The SURROGAT class profile must
be permitted to be used by the RACF user ID for the adapter proper with read
access.
Authorization to set and reset passwords
When the adapter RACF user ID, or the surrogate RACF user ID(s) do not have
SYSTEM SPECIAL, then they must have the ability to set passwords over those
users it manages. This is accomplished through the FACILITY class profile named
IRR.PASSWORD.RESET.
The default for the PASSEXPIRE option is TRUE, which means all passwords set
from the Tivoli Identity Manager Server will be EXPIRED passwords, requiring the
user to change their password upon first use. In this instance, the adapter (or
surrogates) will only need READ access to the IRR.PASSWORD.RESET profile:
RDEFINE FACILITY IRR.PASSWORD.RESET UACC(NONE)
PERMIT IRR.PASSWORD.RESET CLASS(FACILITY) AC(READ) ID(ITIAGNT)
SETROPTS RACLIST(FACILITY) REFRESH
If the adapter option PASSEXPIRE is set to FALSE, the Tivoli Identity Manager
adapter will only be setting non-expired passwords. In this instance, the adapter
(or surrogates) may require UPDATE access to the IRR.PASSWORD.RESET profile,
if these users do not have RACF SYSTEM SPECIAL.
Chapter 3. Installing and configuring the RACF adapter 33
RDEFINE FACILITY IRR.PASSWORD.RESET UACC(NONE)
PERMIT IRR.PASSWORD.RESET AC(UPDATE) ID(ITIAGNT)
SETROPTS RACLIST(FACILITY) REFRESH
If surrogate RACF user ID’s are being utilized, the user ID specified in the above
PERMIT command will reflect the surrogate user ID, not the adapter RACF user
ID that starts the adapter.
Refer to the z/OS 1.4 RACF Security Administrator’s guide for more information.
AUTOUID support
If you are running on z/OS 1.4 or above, and wish to allow the Tivoli Identity
Manager Server to take advantage of AUTOUID support for OMVS segments, then
you must define the following profile:
RDEFINE FACILITY BPX.NEXT.USER APPLDATA(’nn/mm’) UACC(NONE)
SETROPTS RACLIST(FACILITY) REFRESH
Where ’nn’ is a starting OMVS UID to be assigned, and ’mm’ is the next OMVS
GID to be assigned. (The GID is shown here for completeness).
Refer to the z/OS 1.4 RACF Security Administrator’s guide for more information.
Shared UID support
If you wish the Tivoli Identity Manager Server to be able to provision a shared
OMVS UID number, the adapter, or surrogate user ID’s must have permission to
do so.
If your installation is running z/OS 1.4 or above, and the SHARED.IDS profile is
defined in the UNIXPRIV class, definition of duplicate UID’s for multiple users is
prevented. If you wish the Tivoli Identity Manager to define UID’s to multiple
users, you must permit it to do so, by adding the RACF user ID (representing the
adapter) to have read access to the resource profile:
PE SHARED.IDS CLASS(UNIXPRIV) AC(READ) ID(ITIAGNT)
SETROPTS CLASS(UNIXPRIV) REFRESH
Where the RACF user ID set in the permit command is either the adapter ID or the
surrogate ID that will effectively be utilizing executing the RACF command.
If surrogate RACF user ID’s are being utilized, the user ID specified in the above
PERMIT command will reflect the surrogate user ID, not the adapter RACF user
ID that starts the adapter.
Refer to the z/OS 1.4 RACF Security Administrator’s guide for more information.
Step 6: Configure communication
Configure the Tivoli Identity Manager Server to communicate with the RACF
adapter. The following steps must be performed on the host where the Tivoli
Identity Manager Server resides.
Importing the adapter profile into the Tivoli Identity Manager
Server
Before you can add an adapter as a service to the Tivoli Identity Manager Server,
the server must have an adapter profile to recognize the adapter as a service. The
files that are packaged with the RACF Adapter include the adapter JAR file,
34 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
racf2Profile.jar. Using the Import feature of the Tivoli Identity Manager Server, you
can import the adapter profile into the server as a service profile.
The racf2Profile.jar file includes all of the files that are needed to define the
adapter schema, account form, service form, and profile properties. The
racf2Profile.jar file will be referenced in this document to make any changes to the
schema or the profile. You will be required to extract the files from the JAR file,
make changes to the necessary files, and repackage the JAR file with the updated
files.
An adapter profile defines the types of resources that the Tivoli Identity Manager
Server can manage. You must import the adapter profile into the Tivoli Identity
Manager Server before using the RACF Adapter. The profile is used to create a
RACF Adapter service on the Tivoli Identity Manager Server and to communicate
with the adapter.
Before you begin to import the adapter profile, verify that the following conditions
are met:
v The Tivoli Identity Manager Server must be installed and running.
v You must have root or Administrator authority on the Tivoli Identity Manager
Server.
In order to import the adapter profile, complete the following steps:
1. Log into the Tivoli Identity Manager Server using an account that has the
authority to perform administrative tasks.
2. On the Main Menu Navigation Bar, select the Configuration tab.
3. On the Configuration window, select Import/Export → Import tabs.
4. On the Import window, in the File to Upload field, type the location of the
racf2Profile.jar file, or click Browse to locate the file.
5. Click the Import data into Identity Manager link to import the adapter profile
into the Tivoli Identity Manager Server.
v If the adapter profile import completes successfully, the following message is
displayed:
Profile installation complete.
v If the adapter profile import fails, the following message is displayed:
Profile installation failed.
When you import the adapter profile, if you receive an error related to the
schema, the trace.log file will contain information about that error. The
trace.log file location is specified by the handler.file.fileDir property that
is defined in the Tivoli Identity Manager enRoleLogging.properties file,
which is in the Tivoli Identity Manager \data directory.
Creating a RACF service
After the adapter profile is imported into the Tivoli Identity Manager Server, you
must create a provisioning service to allow Tivoli Identity Manager to
communicate with the adapter.
In order to create a provisioning service, complete the following steps:
1. Log into the Tivoli Identity Manager Server using an account that has the
authority to perform administrative tasks.
2. On the Main Menu Navigation Bar, click the Provisioning tab.
3. On the Provisioning window, click the Manage Services tab.
Chapter 3. Installing and configuring the RACF adapter 35
4. On the Manage Services window, click Add.
5. From the list of service types, select RACF Profile, and then click Continue.
The RACF Adapter service form is displayed. The service form contains the
following fields:
Service Name
Specify a name that defines this RACF service on the Tivoli Identity
Manager Server. Service Name is a required field.
Service Description
Specify a description that will identify this service for your
environment. Service Description is not a required field.
URL Specify the location and port number of the RACF Adapter. The port
number is defined in the protocol configuration using the agentCfg
program. For additional information about protocol configuration
settings, see “Changing protocol configuration settings” on page 41.
URL is a required field.
If https is specified as part of the URL, the adapter must be configured
to use SSL authentication. If the adapter is not configured to use SSL
authentication, specify http for the URL. For additional information
about configuring the adapter to use SSL authentication, see Chapter 5,
“Configuring SSL authentication for the RACF adapter,” on page 71.
User Id
Specify the name that has been defined in the adapter registry on the
z/OS platform. The default value is agent. User Id is a required field.
Password
Specify the password for the user ID. The default value is agent.
Password is a required field.
RACF ID under which requests will be processed
Specify a RACF user ID, other than the one that is used by the adapter.
This user ID should have group special authority over a subset of users
within the RACF database. RACF ID is not required.
Owner
Specify the service owner, if any. Owner is an optional field.
Service Prerequisite
Specify an existing Tivoli Identity Manager service that is a prerequisite
for the RACF service. Service Prerequisite is an optional field.6. To verify the connection, press Test.
7. To create the service, press Submit.
Step 7: Starting and stopping the adapter
It is preferable to start the RACF Adapter as a started task, where the started task
JCL has been customized and installed into a system procedure library.
To start, issue the MVS console start command:
START ITIAGNT
Where ITIAGNT is the name of the JCL procedure representing the adapter.
36 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
The adapter may also be started as a batch job stream, or may be started from
UNIX System Services, by initiating the UNIX System Services script to start the
adapter.
When the ITIAGNT task is running, it will listen on two IP ports. One port is for
adapter communication between the ITIM server and this adapter and the other
port is utilized for the agentCfg utility.
If the UNIX System Services environment is running with _BPX_SHAREAS=YES,
run the MVS stop command to stop the adapter, for example:
STOP ITIAGNT
or
P ITIAGNT
If the adapter is initiated as a started task, you may stop the RACF Adapter by
issuing an MVS CANCEL command, as follows:
CANCEL ITIAGNT
Chapter 3. Installing and configuring the RACF adapter 37
38 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity
Manager
Use the adapter configuration program, agentCfg, to view or modify the RACF
Adapter parameters. All changes that you make to parameters with this tool take
effect immediately.
Starting the adapter configuration tool
In order to start the adapter configuration tool, agentCfg, for RACF Adapter
parameters, complete these step:
Note: The agentCfg program requires DLLs from the ./lib directory. As such, the
./lib directory must be in your LIBPATH environment variable, prior to
execution of agentCfg.
1. Log into the RACF Adapter system. Logon to the MVS system through TSO.
2. Enter the Unix System Services shell environment, with the OMVS command.
You can optionally directly enter the Unix System Services environment
through a telnet session.
3. In the command prompt window, change to the /bin directory for the adapter.
For example, type the following command, if the RACF Adapter directory is in
the default location: (Assume a user called ″itim″ has /home/itim as the home
directory.)
# cd home/itim/RACFAgent/bin
4. Type the following command:
agentCfg -agent RACFAgent
The adapter name is the name chosen when configuring your adapter. You can
find the adapter names active by executing agentCfg as follows:
agentCfg -list
You can also use agentCfg to view or change configuration settings from a
remote computer. See the table in “Accessing help and additional options” on
page 68 for procedures on using additional arguments.
5. At the Enter configuration key for Agent ’RACFAgent’: prompt, type the
configuration key for the RACF Adapter.
The default configuration key is agent. You must change the configuration key
once installation completes, to prevent unauthorized access to the configuration
of the adapter. See “Changing protocol configuration settings” on page 41 for
procedures to change the configuration key.
The Main Configuration Menu is displayed.
© Copyright IBM Corp. 2003, 2005 39
RACFAgent 4.6 Agent Main Configuration Menu
-------------------------------------------
A. Configuration Settings.
B. Protocol Configuration.
C. Event Notification.
D. Change Configuration Key.
E. Activity Logging.
F. Registry Settings.
G. Advanced Settings.
H. Statistics.
I. Codepage Support.
X. Done
Select menu option:
From the Main Menu, you can configure the protocol, view statistics, and modify
settings, including configuration, registry, and advanced settings.
Table 5. Options for the main configuration menu
Option Configuration task For more information
A Viewing configuration settings See page 40.
B Changing protocol configuration
settings
See page 41.
C Configuring event notification See page 44.
D Changing the configuration key See page 61.
E Changing activity logging settings See page 61.
F Changing registry settings See page 63.
G Changing advanced settings See page 64.
H Viewing statistics See page 66.
I Changing code page settings See page 66.
Viewing configuration settings
The following procedure describes how to view the RACF Adapter configuration
settings.
1. At the Agent Main Configuration Menu, type A. The configuration settings for
the RACF Adapter are displayed. The following screen is an example of the
RACF Adapter configuration settings.
40 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Configuration Settings
-------------------------------------------
Name : RACFAgent
Version : 4.6
ADK Version : 4.36
ERM Version : 4.36
enRole Version : 4.0
License : NONE
Asynchronous ADD Requests : FALSE (Max.Threads:3)
Asynchronous MOD Requests : FALSE (Max.Threads:3)
Asynchronous DEL Requests : FALSE (Max.Threads:3)
Asynchronous SEA Requests : FALSE (Max.Threads:3)
Available Protocols : DAML
Configured Protocols : DAML
Logging Enabled : TRUE
Logging Directory : /home/itim/RACFAgent/log
Log File Name : RACFAgent.log
Max. log files : 3
Max.log file size (Mbytes) : 1
Debug Logging Enabled : TRUE
Detail Logging Enabled : FALSE
Thread Logging Enabled : FALSE
Press any key to continue
2. Press any key to return to the Main Menu.
Changing protocol configuration settings
The RACF Adapter uses the DAML protocol to communicate with the Tivoli
Identity Manager Server. By default, when the adapter is installed, the DAML
protocol is configured to be used in nonsecure mode. In order to configure a secure
environment, you must configure the DAML protocol to use SSL and install a
certificate. Refer to “Installing the certificate” on page 80 for more information
about installing certificates.
In previous versions of this adapter, you could add and remove protocols.
However, in the latest version of this adapter, the DAML protocol is the only
supported protocol that you can use. Therefore, you will not need to add or
remove a protocol.
In order to configure the DAML protocol for the RACF Adapter, complete the
following steps:
1. At the Agent Main Configuration Menu, type B. The DAML protocol is
configured and available by default for the RACF Adapter.
Agent Protocol Configuration Menu
-----------------------------------
Available Protocols: DAML
Configured Protocols: DAML
A. Add Protocol.
B. Remove Protocol.
C. Configure Protocol.
X. Done
Select menu option
2. At the Agent Protocol Configuration Menu, type C. The Configure Protocol
Menu is displayed.
3. At the Configure Protocol Menu, type C. The Protocol Properties Menu for the
configured protocol is displayed with protocol properties. The properties on
your menu might be different from the ones shown in the examples.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 41
The following screen is an example of the DAML protocol properties:
DAML Protocol Properties
--------------------------------------------------------------------
A. USERNAME ****** ;Authorized user name.
B. PASSWORD ****** ;Authorized user password.
C. MAX_CONNECTIONS 100 ;Max Connections.
D. PORTNUMBER 45580 ;Protocol Server port number.
E. USE_SSL FALSE ;Use SSL secure connection.
F. SRV_NODENAME 9.38.215.20 ;Event Notif. Server name.
G. SRV_PORTNUMBER 9443 ;Event Notif. Server port number.
H. VALIDATE_CLIENT_CE FALSE ;Require client certificate.
I. REQUIRE_CERT_REG FALSE ;Require registered certificate.
X. Done
Select menu option:
4. Type the letter of the menu option for the protocol property that you want to
configure.
See Table 6 below for additional information about the properties that you can
configure for the DAML protocol.
Table 6. Options for the DAML protocol menu
Option Configuration task
A The following prompt is displayed:
Modify Property ’USERNAME’:
Type a user ID, for example, admin.
This value is the user ID that the Tivoli Identity Manager Server uses to
connect to the adapter.
B The following prompt is displayed:
Modify Property ’PASSWORD’:
Type a password, for example, admin.
This value is the password for the user ID that the Tivoli Identity
Manager Server uses to connect to the adapter.
C The following prompt is displayed:
Modify Property ’MAX_CONNECTIONS’:
Enter the maximum number of concurrent open connections that the
adapter supports.
The default number is 100.
D The following prompt is displayed:
Modify Property ’PORTNUMBER’:
Type a different port number.
This value is the port number that the Tivoli Identity Manager Server
uses to connect to the adapter. The default port number is 45580.
42 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 6. Options for the DAML protocol menu (continued)
Option Configuration task
E The following prompt is displayed:
Modify Property ’USE_SSL’:
Enter TRUE or FALSE to specify whether a secure SSL connection will
be used to connect to or from the adapter.
The default value is FALSE.
You must install a certificate when USE_SSL is set to TRUE. For more
information on certificate installation, see “Installing the certificate” on
page 80.
F The following prompt is displayed:
Modify Property ’SRV_NODENAME’:
Type a server name or an IP address, for example, 9.38.215.20.
This value is the DNS name or IP address of the Tivoli Identity Manager
Server that is used for event notification and asynchronous request
processing.
Note: If your platform supports Internet Protocol version 6 (IPv6)
connections, you can specify an IPv6 server.
G The following prompt is displayed:
Modify Property ’SRV_PORTNUMBER’:
Type a different port number to access the Tivoli Identity Manager
Server.
This value is the port number that the adapter uses to connect to the
Tivoli Identity Manager Server. The default port number is 9443.
H The following prompt is displayed:
Modify Property ’VALIDATE_CLIENT_CE’:
Type TRUE to require the Tivoli Identity Manager Server to send a
certificate when it communicates with the adapter.
Type FALSE to allow the Tivoli Identity Manager Server to communicate
with the adapter without a certificate. The default value is FALSE.
Notes:
1. If you set this option to TRUE, you must configure options D
through H.
2. The property name is actually VALIDATE_CLIENT_CERT. It is
truncated by agentCfg to fit onto the screen.
3. You must use CertTool to install the appropriate CA certificates and
optionally register the Tivoli Identity Manager Server certificate. For
more information on using CertTool, see “Managing SSL certificates
using CertTool” on page 77.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 43
Table 6. Options for the DAML protocol menu (continued)
Option Configuration task
I The following prompt is displayed:
Modify Property ’REQUIRE_CERT_REG’:
This value only applies when option H is set to TRUE.
Type TRUE to require the client certificate from the Tivoli Identity
Manager Server to be registered with the adapter before it will accept an
SSL connection.
Type FALSE to require the client certificate only be verified against the
list of CA certificates. The default value is FALSE.
For more information on certificates, see Chapter 5, “Configuring SSL
authentication for the RACF adapter,” on page 71.
5. At the prompt, change the value, and press Enter.
The Protocol Properties Menu is displayed with your new settings.
If you do not want to change the value, just press Enter to return to the
Protocol Properties Menu.
6. Repeat steps 4 and 5 to configure as many protocol properties as you need to.
7. At the Protocol Properties Menu, type X to exit the menu.
Configuring event notification
Event notification is a feature of the RACF Adapter that updates the Tivoli Identity
Manager Server at set intervals. Event notification detects changes that are made
on the managed resource and updates the Tivoli Identity Manager Server with the
changes. You can enable event notification if you want to have updated
information from the managed resource sent back to the Tivoli Identity Manager
Server between full reconciliations. Event notification is not intended to replace
reconciliations on the Tivoli Identity Manager Server.
When event notification is enabled, a database of the reconciliation data is kept on
the machine where the adapter is installed. The database is updated with the
changes that are requested by the Tivoli Identity Manager Server and will stay in
sync with the server. You can specify an interval for the event notification process
to compare the database to data that currently exists on the managed resource.
When the interval has elapsed, any differences between the managed resource and
the database are forwarded to the Tivoli Identity Manager Server and updated in
the local snapshot database.
There are several basic steps to enabling event notification. These steps assume that
the adapter has been deployed on the managed host and is communicating
successfully with the Tivoli Identity Manager server.
Required information
Implementation of event notification requires the following information:
v If Secure Sockets Layer (SSL) is utilized for communications between the Tivoli
Identity Manager server and the adapter on the managed resource, Tivoli
Identity Manager’s digital certificate must be obtained to be installed into the
adapter’s registry.
44 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
v The IP address of the hosting platform of Tivoli Identity Manager must be
known.
v The IP port of the hosting platform of Tivoli Identity Manager must be known.
You will require one of the following port numbers:
– The SSL port, if SSL communications is utilized, or
– The non-SSL port, if SSL is not utilized.
These ports are actually the port numbers of the Web application server on the
Tivoli Identity Manager server. When Tivoli Identity Manager is utilizing
WebSphere, the default SSL port is 9443, and the non-SSL port is 9080.
v The pseudo Distinguished Name (DN) of the Tivoli Identity Manager service
defined on the Tivoli Identity Manager server must be known, and defined into
an event notification context in the adapter’s registry. The DN is NOT a typical
LDAP DN, and is unique for the use of Tivoli Identity Manager. It identifies a
specific service instance defined on the Tivoli Identity Manager server. Details on
determining this target DN are detailed below.
v Optionally, there are credentials passed to an adapter, to identify the service
instance to the managed resource adapter. Use of these attributes depends upon
the specific adapter being utilized. These credentials are additional information
that allow the adapter to connect to the managed resource, or discretely identify
different areas of the managed resource.
Example definition
This section provides an example definition for demonstration purposes. This
example uses the following variables:
v SSL will be utilized for communications.
v The IP address of the host where Tivoli Identity Manager executes is 9.38.214.54.
v The IP port of the host of the web application server’s SSL port is 9443.
v We will name the adapter context RACF.
v For the RACF adapter, there is an optional attribute that constitutes additional
credentials to the adapter. On the service form, there is a field labeled RACF ID
under which requests will be processed. In this example, the value of this field
is ADMNBU1.
v Because SSL is utilized, the adapter will be receiving a digital certificate from the
Tivoli Identity Manager server. In this case, the certificate is self signed, so the
certificate itself must be installed into the adapter registry as a Certificate
Authority (CA) certificate.
v The pseudo DN of the Tivoli Identity Manager services as a target of event
notification is:
erservicenname=z/OS RACF 4.5.1016 ENTEST, o=Acme Inc, ou=Acme,dc=my_suffix
The details below describe how this pseudo-DN is constructed.
Setting the protocol properties
Usually, SSL will be utilized. This will have already been determined while
configuring the adapter, outside of the topic of event notification. All of these
properties are defined under the DAML protocol environment.
In the following example, the Tivoli Identity Manager host IP and port addresses
will be set through the agentCfg utility.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 45
BETA451017 4.5.1017 Agent Main Configuration Menu
-------------------------------------------
A. Configuration Settings.
B. Protocol Configuration.
C. Event Notification.
D. Change Configuration Key.
E. Activity Logging.
F. Registry Settings.
G. Advanced Settings.
H. Statistics.
I. Codepage Support.
X. Done
Select menu option:b
Agent Protocol Configuration Menu
--------------------------------------
Available Protocols : DAML
Configured Protocols: DAML
A. Add Protocol.
B. Remove Protocol.
C. Configure Protocol.
X. Done
Select menu option:c
Configure Protocol Menu
------------------------------
A. DAML
X. Done
Select menu option:a
DAML Protocol Properties
------------------------------------
A. USERNAME ****** ;Authorized user name.
B. PASSWORD ****** ;Authorized user password.
C. MAX_CONNECTIONS 100 ;Max Connections.
D. PORTNUMBER 45581 ;Protocol Server port number.
E. USE_SSL TRUE ;Use SSL secure connection
F. SRV_NODENAME ----- ;Event Notif. Server name.
G. SRV_PORTNUMBER 7003 ;Event Notif. Server port number.
H. VALIDATE_CLIENT_CE FALSE ;Require client certificate.
I. REQUIRE_CERT_REG FALSE ;Require registered certificate.
X. Done
Select menu option:f
Modify Property ’SRV_NODENAME’: 9.38.215.20
DAML Protocol Properties
------------------------------------
A. USERNAME ****** ;Authorized user name.
B. PASSWORD ****** ;Authorized user password.
C. MAX_CONNECTIONS 100 ;Max Connections.
D. PORTNUMBER 45581 ;Protocol Server port number.
E. USE_SSL TRUE ;Use SSL secure connection
F. SRV_NODENAME 9.38.215.20 ;Event Notif. Server name.
G. SRV_PORTNUMBER 9443 ;Event Notif. Server port number.
H. VALIDATE_CLIENT_CE FALSE ;Require client certificate.
I. REQUIRE_CERT_REG FALSE ;Require registered certificate.
X. Done
46 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Select menu option:g
Modify Property ’SRV_PORTNUMBER’: 9443
DAML Protocol Properties
------------------------------------
A. USERNAME ****** ;Authorized user name.
B. PASSWORD ****** ;Authorized user password.
C. MAX_CONNECTIONS 100 ;Max Connections.
D. PORTNUMBER 45581 ;Protocol Server port number.
E. USE_SSL TRUE ;Use SSL secure connection
F. SRV_NODENAME 9.38.215.20 ;Event Notif. Server name.
G. SRV_PORTNUMBER 9443 ;Event Notif. Server port number.
H. VALIDATE_CLIENT_CE FALSE ;Require client certificate.
I. REQUIRE_CERT_REG FALSE ;Require registered certificate.
X. Done
Select menu option:x
Configure Protocol Menu
------------------------------
A. DAML
X. Done
Select menu option:x
Installing the CA certificate into the adapter
Tivoli Identity Manager and its adapters are typically configured to utilize SSL for
communications, where server-side authentication is employed. This means that
the adapter must identify itself to the server, when the Tivoli Identity Manager
server contacts the adapter. The adapter must have installed a private key and
corresponding digital certificate. The server must have installed a Certificate
Authority certificate that signed the adapter’s certificate.
When event notification is employed, the adapter side must contact the Tivoli
Identity Manager server. In this case, the Tivoli Identity Manager server identifies
itself to the adapter. Because of this, you must install the Certificate Authority
digital certificate (which signed the Tivoli Identity Manager server’s digital
certificate) into the adapter’s registry.
When event notification is configured and enabled, you must install the Tivoli
Identity Manager server’s CA certificate into the adapter’s environment. This is not
the certificate in the /itim46/cert directory, but the certificate of the web
application server (such as WebSphere). The CA certificate is the digital certificate,
which signed the certificate presented in the SSL handshake. If the server is using a
simple self-signed digital certificate, then the server’s certificate acts also as a CA
certificate. In this case, only the server’s digital certificate is required.
The adapter ships with the WebSphere self-signed digital certificate. If you are
utilizing a different Java application server, you must install its CA certificate
The server’s self-signed certificate, or CA signing certificate must be obtained in an
exported X.509 DER form, and transferred to the adapter host. It should be stored
into the ./data directory, for subsequent installation by utilizing the certTool utility
(provided with the adapter). Because the certificate is in DER form, binary file
transfer of the certificate to the adapter platform is necessary. A text file transfer
will not work.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 47
There are many different ways this certificate may be obtained and transferred to
the adapter host.
The following steps are valid ONLY for obtaining a self-signed certificate from a
Web server :
1. Open Internet Explorer.
2. Attempt connection to the Tivoli Identity Manager server platform, utilizing
HTTPS (HTTP over SSL). The following URL is an example:
https://9.38.215.20:9443/enrole/login
3. Press Enter, and a dialog box will be displayed, indicating security alert. This
is because the certificate presented by the site to your Web browser is not
issued by a company you have chosen to trust. Click on the View Certificate
button.
4. A dialog box shows details of the certificate presented to your browser. Select
the tab across the top titled Details.
5. Click the Copy to File button to launch the certificate export wizard. Click
Next to proceed.
6. You will now be provided with a choice of formats in which the digital
certificate of the Tivoli Identity Manager server may be exported. Select DER
encoded X.509 (.CER), then click Next.
7. Specify a directory and a file name on your local workstation to store the
certificate. Click Next.
8. A completion dialog indicates the success of the export wizard. Note of the
full path of the File Name in this display. Click OK to close the success dialog
box.
9. Click OK again to close the certificate dialog box.
10. The security alert dialog box is displayed. Click either:
v Yes to connect to the Tivoli Identity Manager server, or
v No to deny the connection.
Either choice is irrelevant, since you have now captured the certificate to your
workstation.
11. The exported certificate must now be transferred to the host where the
adapter resides. The following example shows an FTP session, transferring the
certificate to the adapter host:
48 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
C:\temp>dir *.cer
Volume in drive C is Local Disk
Volume Serial Number is 289F-D3F5
Directory of C:\temp
10/26/2004 04:37p 742 rhea.cer
1 File(s) 742 bytes
0 Dir(s) 3,924,729,856 bytes free
C:\temp>ftp 9.38.214.54
Connected to 9.38.214.54.
220-FTPD1 IBM FTP CS V1R4 at AGENTHOST.IBM.COM, 00:59:19 on 2004-10-30.
220 Connection will close if idle for more than 5 minutes.
User (9.38.214.54:(none)): agntusr
331 Send password please.
Password:
230 JOHNY is logged on. Working directory is "JOHNY.".
ftp> cd /u/itim/data
250 HFS directory /u/itim/data is the current working directory
ftp> bin
200 Representation type is Image
ftp> put rhea.cer
200 Port request OK.
125 Storing data set /u/itim/data/rhea.cer
250 Transfer completed successfully.
ftp: 742 bytes sent in 0.02Seconds 37.10Kbytes/sec.
ftp> quit
221 Quit command received. Goodbye.
C:\temp>exit
12. Now connect to the adapter host so that you can execute the certTool utility
and install the certificate you have just uploaded. Here is a sample terminal
session on the adapter host to do the installation:
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 49
/u/itim/data/data:>ls -al
total 10328
drwxrwxr-x 2 AGNTUSR SYS1 8192 Oct 29 14:22 .
drwxrwxr-x 6 AGNTUSR SYS1 8192 Oct 7 16:44 ..
-rw-rw-r-- 1 AGNTUSR SYS1 888 Oct 15 17:12 DamlCACerts.pem
-rwx------ 1 AGNTUSR SYS1 7173 Oct 29 14:09 RACFAGENT.dat
-rw------- 1 AGNTUSR SYS1 1581 Oct 7 16:45 damlserver.pfx
-rw-r----- 1 AGNTUSR SYS1 1970 Oct 20 18:00 damlsrvr2.pfx
-rw-r----- 1 AGNTUSR SYS1 729 Oct 29 17:59 rhea.cer
-rw------- 1 AGNTUSR SYS1 5242908 Oct 29 14:21 rhea_local.dat
/u/itim/data/data:>../bin/certTool -agent racfagent
IBM Tivoli Agent DAML Protocol Certificate Tool 4.60
------------------------------------------------------
Main menu - Configuring agent: RACFAGENT
------------------------------
A. Generate private key and certificate request
B. Install certificate from file
C. Install certificate and key from PKCS12 file
D. View current installed certificate
E. List CA certificates
F. Install a CA certificate
G. Delete a CA certificate
H. List registered certificates
I. Register certificate
J. Unregister a certificate
K. Export certificate and key to PKCS12 file
X. Quit
Choice: f
Enter name of certificate file: rhea.cer
Subject: /C=US/O=IBM/OU=SWG/CN=jserver
Install this CA (Y/N)? y
Main menu - Configuring agent: RACFAGENT
------------------------------
A. Generate private key and certificate request
B. Install certificate from file
C. Install certificate and key from PKCS12 file
D. View current installed certificate
E. List CA certificates
F. Install a CA certificate
G. Delete a CA certificate
H. List registered certificates
I. Register certificate
J. Unregister a certificate
K. Export certificate and key to PKCS12 file
X. Quit
Choice: x
13. The self-signed digital certificate for the Tivoli Identity Manager server is now
installed in the managed host adapter, as a CA certificate. This will allow the
event notification process to connect to the Tivoli Identity Manager server
utilizing SSL.
50 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Adding an event notification context
Event Notification updates the Tivoli Identity Manager Server at set intervals, with
information that has changed since the last server initiated reconciliation. The
following procedure is an example of adding an event notification context.
The example menu shows all the options displayed when Event Notification is
enabled. If Event Notification is disabled, not all of the options are displayed. In
order to set Event Notification for the Tivoli Identity Manager Server, complete the
following steps:
1. At the Agent Main Configuration Menu, type C. The Event Notification Menu is
displayed.
Event Notification Menu
--------------------------------------
* Reconciliation interval : 1 day(s)
* Next Reconciliation time : 23 hour(s) 41 min(s). 37 sec(s).
* Last processing time : 53 sec(s).
* Configured Contexts : RHEA
A. Enabled
B. Time interval between reconciliations.
C. Set processing cache size.(currently: 50 Mbytes)
D. Start event notification now.
E. Set attributes to be reconciled.
F. Add Event Notification Context.
G. Modify Event Notification Context.
H. Remove Event Notification Context.
I. List Event Notification Contexts.
X. Done
Select menu option:
Note: This menu shows all the options that are displayed when Event
Notification is enabled. If Event Notification is disabled, all of the
options will not be displayed.
2. Type the letter of the menu option that you want to change.
Option A must be enabled in order for the values of the other options to take
affect.
Press Enter to return to the Agent Event Notification Menu without changing
the value.
Table 7. Options for the event notification menu
Option Configuration task
A If this option is enabled, the adapter updates the Tivoli Identity Manager
Server with changes to the adapter at regular intervals.
When the option is set to:
v Disabled, pressing the A key changes to enabled
v Enabled, pressing the A key changes to disabled
Type A to toggle between the options.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 51
Table 7. Options for the event notification menu (continued)
Option Configuration task
B The following prompt is displayed:
Enter new interval
([ww:dd:hh:mm:ss])
Type a different reconciliation interval. For example:
[00:01:00:00:00]
Note: This value is the interval to wait once event notification completes
before it is run again. The event notification process is resource intense,
therefore this value must not be set to run too frequently.
C The following prompt is displayed:
Enter new cache size[5]:
Type a different value to change the processing cache size.
D If this option is selected, event notification is started.
E The Event Notification Entry Types Menu is displayed. See “Setting
attributes to be reconciled” on page 58 for more information.
F The following prompt is displayed:
Enter new thread priority [1-10]:
Type a different thread value to change the event notification process
priority.
Setting the thread priority to a lower value reduces the impact that the
event notification process has on the performance of the adapter. A
lower value might also cause event notification to take longer.
G The following prompt is displayed:
Context name:
Type the new context name, and press Enter. The new context is added.
H A menu listing the available contexts is displayed. See “Modifying an
event notification context” on page 59 for more information.
I The Remove Context Menu is displayed. Select the context to remove.
The following prompt is then displayed:
Delete context context1? [no]:
Press Enter to exit without deleting the context, or type Yes and press
Enter to delete the context.
J The Event Notification Contexts are displayed in the following format:
Context Name : Context1
Target DN :
erservicename=context1,o=IBM,
ou=IBM,dc=com
--- Attributes for search request ---
{search attributes listed}
-----------------------------------------------
3. To add an event notification context, select option F to add a context. You will
be prompted for a context name, then returned to the Event Notification Menu:
52 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Select menu option:F
Enter new context name: RACF
Event Notification Menu
--------------------------------------
* Reconciliation interval : 1 day(s)
* Next Reconciliation time : 22 hour(s) 24 min(s). 52 sec(s).
* Configured Contexts : RACF
A. Enabled
B. Time interval between reconciliations.
C. Set processing cache size.(currently: 50 Mbytes)
D. Start event notification now.
E. Set attributes to be reconciled.
F. Add Event Notification Context.
G. Modify Event Notification Context.
H. Remove Event Notification Context.
I. List Event Notification Contexts.
X. Done
Select menu option:
4. If you changed the value for options B, C, E, or F, press Enter. The other
options are automatically changed when you type the corresponding letter of
the menu option.
The Event Notification Menu is displayed with your new settings.
Configuring the target DN for event notification contexts
Once an event notification context has been added, it must be modified through
option G to add information to the context. At minimum, a target pseudo DN must
be specified. To determine how to construct this target DN, refer to “Determining
pseudo-distinguished name values” on page 55.
Select menu option: G
Modify Context: RACF
------------------------------------
A. Set attributes for search
B. Target DN:
X. Done
Select menu option:b
Enter Target DN: erservicenname=z/OS RACF 4.5.1016 ENTEST,o=Acme Inc,
ou=Acme,dc=my_suffix
Modify Context: RACF
------------------------------------
A. Set attributes for search
B. Target DN: erservicenname=z/OS RACF 4.5.1016 ENTEST,o=Acme Inc,
ou=Acme,dc=my_suffix
X. Done
Select menu option:
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 53
Specifying attributes for search
For some adapters, you may need to specify an attribute/value pair for one or
more contexts. These attribute/value pairs, which are defined within the context
under Set attributes for search, serve multiple purposes:
v When multiple service instances on the Tivoli Identity Manager server reference
this adapter, each service instance must allow for specification of an
attribute/value pair, so the adapter will know which service instance is
requesting work.
v This attribute will be passed to the event notification process, when the event
notification interval has occurred or is manually initiated. This will allow the
adapter to process information indicated by this attribute/value pair.
v When a server initiated reconciliation process is initiated, the adapter will be
directed to entirely replace the local database that represents this service
instance.
Below is a partial list of possible attribute/value pairs that may be specified for Set
attributes for search. Please reference current schema information for the various
adapter types for accurate information.
Table 8. Attributes for search
Service type Form label Attribute name Value
racf2profile RACF ID under which
requests will be
processed
erracfrequester A group special
RACF user ID
which manages
users within this
service.
ernt40profile Domain Server Name erntdomainservername The domain name
of the Windows NT
server being
managed. For
example:
\\mydomain
w2kprofile Base Point DN erw2kdomainname The Windows 2000
base point,
describing the
subset of the
domain to be
managed. For
example:
xxxxxxxxx
Exchange2kProfile Base Point DN erw2kdomainname The Windows 2000
base point,
describing the
subset of the
domain to be
managed. For
example:
xxxxxxxxx
54 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 8. Attributes for search (continued)
Service type Form label Attribute name Value
ADProfile Base Point DN eradbasepoint The Windows 2000
base point,
describing the
subset of the
domain to be
managed. For
example:
xxxxxxxxx
Select menu option:g
Modify Context Menu
------------------------------
A. RACF
X. Done
Select menu option:a
Modify Context: RACF
------------------------------------
A. Set attributes for search
B. Target DN:
Select menu option:a
Reconciliation Attributes Passed to Agent for context: RACF
-------------------------------------------------
A. Add new attribute
B. Modify attribute value
C. Remove attribute
X. Done
Select menu option:a
Attribute name : erracfrequester
Attribute value: admnbu1
Reconciliation Attributes Passed to Agent for context: RACF
-------------------------------------------------
01. erracfrequester ’admnbu1’
-------------------------------------------------
A. Add new attribute
B. Modify attribute value
C. Remove attribute
X. Done
Select menu option:x
Determining pseudo-distinguished name values
The Target DN field holds the pseudo-distinguished name of the service that
receives event notification updates. To assist in determining the correct entries, this
name may be considered to contain the following components, in the order
A+B+C+D+E:
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 55
Note: None of the Tivoli Identity Manager defined components of the pseudo DN
should contain commas, as the comma is used to delimit between fields of
the resulting pseudo DN.
Table 9. Name values and their descriptions
Component Item Description
A erServicename The value of the erServicename attribute of the
service
B Zero or more
occurrences of ou
and/or 1.
In the event the service is not directly associated
with the organization, additional specification of ou,
and l must be specified.
The specification of these values, will be in reverse
order of their appearance within the Tivoli Identity
Manager organization chart.
C o The value of the o attribute of an organization to
which the service belongs, at the highest level.
This may be determined by examining the Tivoli
Identity Manager organization chart.
D ou This ou component is established at Tivoli Identity
Manager installation.
This is found in the Tivoli Identity Manager
configuration file named enRole.properties, on
configuration item named enrole.defaulttenant.id=
E dc The dc component was established at Tivoli Identity
Manager installation.
This is the root suffix of the LDAP environment.
This is found in the Tivoli Identity Manager
configuration file named enRole.properties, on
configuration item named enrole.ldapserver.root=
EXAMPLE ONE:
A:
The service name on the Tivoli Identity Manager server is z/OS RACF
4.5.1016 ENTEST. This name will become component A of the pseudo-DN:
erservicename=z/OS RACF 4.5.1016 ENTEST
B:
Here is an example display of the Tivoli Identity Manager organization
chart, indicating the location of the service within this organization:
Table 10. Organization chart example
+ Identity Manager Home Tivoli Identity Manager Home
+ Acme Inc Base organization o
Since this service is directly associated with the organization at the top of
the organization chart, there will be no component B required.
C:
The organization this service is associated with, shown on the Tivoli
Identity Manager organization chart is named Acme Inc. This will become
component C of the pseudo-DN:
o=Acme Inc
D:
56 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Through examination, or prior knowledge, of the contents of the
enRole.properties definition file on the Tivoli Identity Manager server, the
value of the property named enrole.defaulttenant.id= will become
component D of the pseudo-DN. Here is an excerpt from the file:
###########################################################
## Default tenant information
###########################################################
enrole.defaulttenant.id=Acme
Thus, the D component of the pseudo-DN will be: ou=Acme
E:
Through examination, or prior knowledge, of the contents of the
enRole.properties definition file on the Tivoli Identity Manager server, the
value of the property named enrole.ldapserver.root= will become
component E of the pseudo-DN. Here is an excerpt from the file:
###########################################################
## LDAP server information
###########################################################
enrole.ldapserver.root=dc=my_suffix
Thus, the E component of the pseudo-DN will be:
dc=my_suffix
Putting all the components together results in the following pseudo-DN
(A+C+D+E; no component B was required):
erservicename=z/OS RACF 4.5.1016 ENTEST,o=Acme Inc,ou=Acme,dc=my_suffix
EXAMPLE TWO:
A:
The service name on the Tivoli Identity Manager server is Irvine Sales.
This name will become component A of the pseudo-DN:
erservicename=Irvine Sales
B:
Here is an example display of the Tivoli Identity Manager organization
chart, indicating the location of the service within this organization:
Table 11. Organization chart example
+ Identity Manager Home Tivoli Identity Manager Home
-Acme Inc Base organization o
- Irvine
Sales
LocationOrganizational Unit
lou
The Irvine Sales service is defined under organizational unit (ou) named
Sales, which is defined under location (l) named Irvine.
Component B of the pseudo-DN will be:
ou=Sales,l=Irvine
C:
The organization this service is associated with, shown on the Tivoli
Identity Manager organization chart is named Acme Inc. This will become
component C of the pseudo-DN:
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 57
o=Acme Inc
D:
Through examination, or prior knowledge, of the contents of the
enRole.properties definition file on the Tivoli Identity Manager server, the
value of the property named enrole.defaulttenant.id= will become
component D of the pseudo-DN. Here is an excerpt from the file:
###########################################################
## Default tenant information
###########################################################
enrole.defaulttenant.id=Acme
Thus, the D component of the pseudo-DN will be:
ou=Acme
E:
Through examination, or prior knowledge, of the contents of the
enRole.properties definition file on the Tivoli Identity Manager server, the
value of the property named enrole.ldapserver.root= will become
component E of the pseudo-DN. Here is an excerpt from the file:
###########################################################
## LDAP server information
###########################################################
enrole.ldapserver.root=dc=my_suffix
Thus, the E component of the pseudo-DN will be:
dc=my_suffix
Putting all the components together results in the following pseudo-DN
(A+C+D+E; no component B was required):
erservicename=Irvine Sales, ou=Sales,l=Irvine o=Acme Inc,ou=Acme,dc=my_suffix
Setting attributes to be reconciled
Setting attributes to be reconciled consists of selecting attributes that will trigger
event notifications when their values change. Attributes that change frequently
(password age or last successful logon, for example) can be omitted.
Note: The event notification entry types and attributes will NOT appear until the
first reconciliation, with event notification enabled, has been performed.
1. Type E (Set attributes to be reconciled) at the Event Notification Menu.
The Event Notification Entry Types Menu appears.
Select menu option:e
Event Notification Entry Types
--------------------------------------
A. erRacfAcct
B. erRacfGrp
X. Done
Select menu option:
2. Type A for attributes returned during a user reconciliation or type B for
attributes returned during a group reconciliation.
The Event Notification Attribute Listing for the selected reconciliation type
appears.
58 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Note: The default setting lists all attributes the adapter supports.
Select menu option:a
Event Notification Attribute Listing
----------------------------------------------------------------------------
{A} ** eraccountstatus {B} ** erracconxml {C} ** erracuclauth
{D} ** erracucredate {E} ** erracudfltgrp {F} ** erracuinstdata
{G} ** erracuisadsp {H} ** erracuisaudit {I} ** erracuisgrpacc
{J} ** erracuisomvsseg {K} ** erracuisoper {L} ** erracuisprotect
{M} ** erracuisrestrict {O} ** erracuisspecial {Q} ** erracuistsoseg
{R} ** erracuisuaudit {S} ** erraculogtime {T} ** erracuname
(p)rev Page 1 of 2 (n)ext
----------------------------------------------------------------------------
X. Done
Select menu option:
3. Type the letter option of the attribute to exclude from an event notification.
Attributes that are marked with the asterisks are returned during the event
notification. Attributes that are not marked with asterisks are not returned
during the event notification.
Modifying an event notification context
An event notification context corresponds to a service on the Tivoli Identity
Manager Server. Some adapters support multiple services. One RACF Adapter can
have several Tivoli Identity Manager services, by specifying a different base point
for each service. You can have multiple event notification contexts, but you must
have at least one adapter. In the example screen below, note that Context1,
Context2, and Context3 are 3 different contexts, all having a different base point.
In order to modify an event notification context, complete the following steps:
1. At the Event Notification Menu, type H. The Modify Context Menu is
displayed.
Modify Context Menu
------------------------------
A. Context1
B. Context2
C. Context3
X. Done
Select menu option:
2. Type the letter of the menu option that you want to modify. The Modify
Context Menu for the selected context is displayed.
A. Set attributes for search
B. Target DN:
C. Delete Baseline Database
X. Done
Select menu option:
Table 12. Options for the modify context menu
Option Configuration task For more information
A Adding search attributes for event notification See page 60.
B Configuring the target DN for event notification
contexts
See page 60.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 59
Table 12. Options for the modify context menu (continued)
Option Configuration task For more information
C Removing the baseline database for event
notification contexts
See page 61.
Adding search attributes for event notification
For some adapters, you might need to specify an attribute-value pair for one or
more contexts. These attribute-value pairs, which are defined by completing the
steps below, serve multiple purposes:
v When multiple services are supported by a single adapter, each service needs to
specify one or more attributes to differentiate it from the other services.
v The search attributes are passed to the event notification process, once the event
notification interval has occurred or is started manually. For each context, a full
search request is sent to the adapter. Additionally, the attributes specified for
that context are passed to the adapter.
v When the Tivoli Identity Manager Server initiates a reconciliation process, the
adapter replaces the local database that represents this service with the new
database.
In order to add search attributes, complete the following steps:
1. At the Modify Context Menu for the context, type A. The Reconciliation
Attribute Passed to Agent Menu is displayed.
Reconciliation Attributes Passed to Agent for Context: Context1
----------------------------------------------------
----------------------------------------------------
A. Add new attribute
B. Modify attribute value
C. Remove attribute
X. Done
Select menu option:
2. Type the letter of the menu option that you want to change.
The supported attribute names will be displayed with two asterisks (**) in front
of each name. When you type the letter of an attribute, it will toggle the
asterisks on and off. Attributes without asterisks will not be updated during an
event notification.
The Reconciliation Attributes Passed to Agent Menu is displayed with the
changes displayed.
Configuring the target DN for event notification contexts
The target DN field holds the unique name of the service that receives event
notification updates.
In order to configure the target DN, complete the following steps:
1. At the Modify Context Menu for the context, type B. The following prompt is
displayed:
Enter Target DN:
2. Type the target DN for the context, and press Enter. The target DN for the
event notification context must be in the following format:
erservicename=erservicename,o=organizationname,ou=tenantname,rootsuffix
60 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Each element of the DN is defined as follows:
Table 13. DN elements and definitions
Element Definition
erservicename Specifies the name of the target service
o Specifies the name of the organization
ou Specifies the name of the tenant in which
the organization is in. If this is an enterprise
installation, this is the name of the
organization.
rootsuffix Specifies the root of the directory tree. This
value is the same as the value of Identity
Manager DN Location which is specified
during the Tivoli Identity Manager Server
installation.
The Modify Context Menu is displayed with the new target DN listed.
Removing the baseline database for event notification contexts
This option is only available after a context is created and a reconciliation is run on
the context to create a Baseline Database file.
At the Modify Context Menu for the context, type C. The Modify Context Menu is
displayed with the Delete Baseline Database option removed.
Changing the configuration key
You use the configuration key as a password to access the configuration tool for
the adapter.
In order to change the RACF Adapter configuration key, complete the following
steps:
1. At the Main Menu prompt, type D.
2. Change the value of the configuration key, and press Enter.
Press Enter to return to the Main Configuration Menu without changing the
configuration key. The default configuration key is agent. Make sure that you
choose high-quality passwords that cannot be easily guessed.
The following message is displayed:
Configuration key successfully changed.
The configuration program exits, and the Main Menu prompt is displayed.
Changing activity logging settings
When you enable logging, Tivoli Identity Manager maintains a dated log file of all
transactions, RACFAgent.log. By default, the log file is in the \log directory.
In order to change the RACF Adapter activity logging settings, complete the
following steps:
1. At the Main Menu prompt, type E.
The Agent Activity Logging Menu is displayed. The following example shows
the default activity logging settings.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 61
Agent Activity Logging Menu
-------------------------------------
A. Activity Logging (Enabled).
B. Logging Directory (current: /home/itim/RACFAgent/Log).
C. Activity Log File Name (current: RACFAgent.log).
D. Activity Logging Max. File Size ( 1 mbytes)
E. Activity Logging Max. Files ( 3 )
F. Debug Logging (Enabled).
G. Detail Logging (Disabled).
H. Base Logging (Disabled).
I. Thread Logging (Disabled).
X. Done
Select menu option:
2. Type letter of the menu option that you want to change.
Option A must be enabled in order for the values of the other options to take
effect.
Press Enter to return to the Agent Activity Logging Menu without changing the
value.
Table 14. Options for the activity logging menu
Option Configuration task
A Set this option to enabled to have the adapter maintain a dated log file
of all transactions.
When the option is set to:
v Disabled, pressing the A key changes to enabled
v Enabled, pressing the A key changes to disabled
Type A to toggle between the options.
B The following prompt is displayed:
Enter log file directory:
Type a different value for the logging directory, for example,
/home/Log. When the logging option is enabled, details about each
access request are stored in the logging file that is in this directory.
C The following prompt is displayed:
Enter log file name:
Type a different value for the log file name. When the logging option is
enabled, details about each access request are stored in the logging file.
D The following prompt is displayed:
Enter maximum size of log files (mbytes):
Type a new value, for example, 10. The oldest data is archived when the
log file reaches the maximum file size. File size is measured in
megabytes. It is possible for the activity log file size to exceed disk
capacity.
E The following prompt is displayed:
Enter maximum number of log files to retain:
Type a new value up to 100, for example, 5. The adapter automatically
deletes the oldest activity logs beyond the specified limit.
62 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 14. Options for the activity logging menu (continued)
Option Configuration task
F If this option is set to enabled, the adapter includes the debug
statements in the log file of all transactions.
When the option is set to:
v Disabled, pressing the F key changes the value to enabled
v Enabled, pressing the F key changes the value to disabled
Type F to toggle between the options.
G If this option is set to enabled, the adapter maintains a detailed log file
of all transactions. The detail logging option must be used for diagnostic
purposes only. Detailed logging enables more messages from the adapter
and might increase the size of the logs.
When the option is set to:
v Disabled, pressing the G key changes the value to enabled
v Enabled, pressing the G key changes the value to disabled
Type G to toggle between the options.
H If this option is set to enabled, the adapter maintains a log file of all
transactions in the Agent Development Kit (ADK) and library files. Base
logging will substantially increase the size of the logs.
When the option is set to:
v Disabled, pressing the H key changes the value to enabled
v Enabled, pressing the H key changes the value to disabled
Type H to toggle between the options.
I If this option is enabled, the log file will contain thread IDs, in addition
to a date and timestamp on every line of the file.
When the option is set to:
v Disabled, pressing the I key changes the value to enabled
v Enabled, pressing the I key changes the value to disabled
Type I to toggle between the options.
3. Press Enter if you changed the value for option B, C, D, or E. The other options
are changed automatically when you type the corresponding letter of the menu
option.
The Agent Activity Logging Menu is displayed with your new settings.
Changing registry settings
In order to change the RACF Adapter registry settings, complete the following
steps:
Refer to Appendix B, “Registry settings,” on page 107 for a table containing the
valid registry options, their values and meanings.
1. At the Main Menu, type F. The Registry Menu is displayed.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 63
RACFAgent 4.6 Agent Registry Menu
-------------------------------------------
A. Modify Non-encrypted registry settings.
B. Modify encrypted registry settings.
C. Multi-instance settings.
X. Done
Select menu option:
2. See the following procedures on modifying registry settings.
Modifying non-encrypted registry settings
1. At the Agent Registry Menu, type A. The Non-encrypted Registry Settings
Menu is displayed.
Agent Registry Items
-------------------------------------------------
01. APPCCMD ’ITIMCMD’
02. APPCRECO ’ITIMRECO’
03. ENROLE_VERSION ’4.0’
04. PASSEXPIRE ’FALSE’
-------------------------------------------------
Page 1 of 1
A. Add new attribute
B. Modify attribute value
C. Remove attribute
X. Done
Select menu option:
2. Type the letter of the menu option for the action that you want to perform on
an attribute.
Table 15. Attribute configuration option descriptions
Option Configuration task
A Add new attribute
B Modify attribute value
C Remove attribute
3. Type the registry item name, and press Enter.
4. If you selected option A or B, type the registry item value and press Enter.
The non-encrypted registry settings menu reappears and displays your new
setting(s).
Changing advanced settings
You can change the RACF Adapter thread count settings for the following types of
requests:
v System Login Add
v System Login Change
v System Login Delete
v Reconciliation
These settings determine the maximum number of requests that the RACF Adapter
processes concurrently. In order to change these settings, complete the following
steps:
64 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
1. At the Main Menu prompt, type G.
The Advanced Settings Menu is displayed. The following example shows the
default thread count settings.
RACFAgent 4.6 Advanced Settings Menu
-------------------------------------------
A. Single Thread Agent (current:TRUE)
B. ADD max. thread count. (current:3)
C. MODIFY max. thread count. (current:3)
D. DELETE max. thread count. (current:3)
E. SEARCH max. thread count. (current:3)
F. Allow User EXEC procedures (current:FALSE)
G. Archive Request Packets (current:FALSE)
H. UTF8 Conversion support (current:TRUE)
I. Pass search filter to agent (current:FALSE)
J. Thread Priority Level (1-10) (current:4)
X. Done
Select menu option:
2. Type letter of the menu option that you want to change. For a description of
each option, see Table 16.
Table 16. Options for the advanced settings menu
Option Description
A Forces the adapter to allow only one request at a time.
The default value is TRUE.
B Controls how many simultaneous ADD requests can run at one time.
The default value is 3.
C Controls how many simultaneous MODIFY requests can run at one time.
The default value is 3.
D Controls how many simultaneous DELETE requests can run at one time.
The default value is 3.
E Controls how many simultaneous SEARCH requests can run at one time.
The default value is 3.
F Determines whether the adapter allows pre- and post-exec functions.
Enabling this option is a potential security risk.
The default value is FALSE.
G This option is no longer supported.
H This option is no longer supported.
I Currently, this adapter does not support processing filters directly. This
option must always be FALSE.
J Sets the thread priority level for the adapter.
The default value is 4.
3. Change the value, and press Enter.
The Advanced Settings Menu is displayed with your new settings.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 65
Viewing statistics
In order to view an event log for the RACF Adapter, complete the following steps:
1. At the Main Menu prompt, type H.
The activity history for the adapter is displayed.
RACFAgent 4.6 Agent Request Statistics
--------------------------------------------------------------------
Date Add Mod Del Ssp Res Rec
-----------------------------------------------------------------
10/19/2004 000000 000004 000000 000000 000000 000004
-----------------------------------------------------------------
X. Done
2. Type X to return to the Main Configuration Menu.
Changing code page settings
Default adapter code page locale
The default code page setting for adapters is US-ASCII for ASCII based adapters.
For EBCDIC hosts, such as z/OS, the default code page is IBM-1047-s390.
Obtaining a list of valid code pages
To obtain a list of valid code page locale names, you need to run agentCfg as
follows:
agentCfg -ag adaptername -codepages
The adapter must already be activated, and the adapter configuration key will
have to be entered. This will display the list of valid code page names available for
this adapter. The following is a partial session with agentCfg displaying a list of
valid code pages:
66 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
IBMUSER:/u/ibmuser/racfagent/bin: >agentCfg -ag racfagent -codepages
Enter configuration key for Agent ’racfagent’:
List of codepage supported by ICU :
UTF-8
UTF-16
UTF-16BE
UTF-16LE
UTF-32
UTF-32BE
UTF-32LE
UTF16_PlatformEndian
UTF16_OppositeEndian
UTF32_PlatformEndian
UTF32_OppositeEndian
ISO-8859-1
US-ASCII
.
.
.
ibm-37_P100-1995,swaplfnl
ibm-1047_P100-1995,swaplfnl
ibm-1140_P100-1997,swaplfnl
ibm-1142_P100-1997,swaplfnl
ibm-1143_P100-1997,swaplfnl
ibm-1144_P100-1997,swaplfnl
ibm-1145_P100-1997,swaplfnl
ibm-1146_P100-1997,swaplfnl
ibm-1147_P100-1997,swaplfnl
ibm-1148_P100-1997,swaplfnl
ibm-1149_P100-1997,swaplfnl
ibm-1153_P100-1999,swaplfnl
ibm-12712_P100-1998,swaplfnl
ibm-16804_X110-1999,swaplfnl
ebcdic-xml-us
IBMUSER:/u/ibmuser
Setting the code page
In order to change the code page settings for the RACF Adapter, complete the
following steps:
1. At the Main Menu prompt, type I.
The Code Page Support Menu for the adapter is displayed.
RACFAgent 4.6 Codepage Support Menu
-------------------------------------------
* Configured codepage: US-ASCII
-------------------------------------------
*
*******************************************
* Restart Agent After Configuring Codepages
*******************************************
A. Codepage Configure.
X. Done
Select menu option:
2. Type A to configure a code page.
Note: The RACFAgent uses unicode, therefore this option is not applicable.
3. Type X to return to the Main Configuration Menu.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 67
Once a code page has been selected, you must restart the adapter for the setting to
take effect.
Here is a sample session with agentCfg, altering the default code page, from US
EBCDIC (IBM-1047) to Spanish EBCDIC (IBM-1145):
IBMUSER:/u/ibmuser: >agentCfg -ag racfagent
Enter configuration key for Agent ’racfagent’:
RACFAGENT 4.6 Agent Main Configuration Menu
-------------------------------------------
A. Configuration Settings.
B. Protocol Configuration.
C. Event Notification.
D. Change Configuration Key.
E. Activity Logging.
F. Registry Settings.
G. Advanced Settings.
H. Statistics.
I. Codepage Support.
X. Done
Select menu option:i
RACFAGENT 4.5.1017 Codepage Support Menu
-------------------------------------------
* Configured codepage: IBM-1047-s390
-------------------------------------------
*
*******************************************
* Restart Agent After Configuring Codepages
*******************************************
A. Codepage Configure.
X. Done
Select menu option:a
Enter Codepage: ibm-1145
RACFAGENT 4.5.1017 Codepage Support Menu
-------------------------------------------
* Configured codepage: ibm-1145
-------------------------------------------
*
*******************************************
* Restart Agent After Configuring Codepages
*******************************************
A. Codepage Configure.
X. Done
Select menu option:x
Accessing help and additional options
In order to access the agentCfg help menu and use the help arguments, complete
the following steps:
1. At the Main Menu prompt, type X. The DOS command prompt is displayed,
and you are in the \bin directory.
2. Type agentCfg -help at the prompt to view the help menu.
The following list of possible commands is displayed:
68 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
-version ; Show version
-hostname < value> ; Target nodename to connect to (Default:Local host IP address)
-findall ; Find all agents on target node
-list ; List available agents on target node
-agent <value> ; Name of agent
-tail ; Display agent’s activity log
-schema ; Display agent’s attribute schema
-portnumber <value>; Specified agent’s TCP/IP port number
-netsearch <value> ; Lookup agents hosted on specified subnet
-confidencetest ; Confidence test
-setup ; Confidence test setup
-help ; Display this help screen
Table 17 describes each argument.
Table 17. Arguments and descriptions for the agentCfg help menu
Argument Description
-version Use this argument to display the version of the agentCfg tool.
-hostname <value> Use the -hostname argument with any of the following
arguments to specify a different host:
v -findall
v -list
v -tail
v -agent
Enter a host name or IP address as the value.
-findall Use this argument to search and display all port addresses
between 44970 and 44994 and their assigned adapter names.
This option will timeout on unused port numbers, so it might
take several minutes to complete.
Add the -hostname argument to search a remote host.
-list Use this argument to display the adapters that are installed
on the local host of the RACF Adapter. By default, the first
time you install an adapter, it is either assigned to port
address 44970 or to the next available port number. All
subsequently installed adapters are then assigned to the next
available port address. Once an unused port is found, the
listing stops.
Use the -hostname argument to search a remote host.
-agent <value> Use this argument to specify the adapter that you want to
configure. Enter an adapter name as the value. Use this
argument with the -hostname argument to modify the
configuration setting from a remote host. You can also use
this argument with the -tail argument.
-tail Use this argument with the -agent argument to display the
activity log for an adapter. Add the -hostname argument to
display the log file for an adapter on a different host.
-schema This option is no longer supported.
-portnumber <value> Use this argument with the -agent argument to specify the
port number that is used for connections for the agentCfg
tool.
-netsearch <value> Use this argument with the -findall argument to display all
active adapters on the system. You must specify a subnet
address as the value.
Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 69
Table 17. Arguments and descriptions for the agentCfg help menu (continued)
Argument Description
-confidencetest Use this argument to run a test to add, modify, search, and
delete a request to the adapter. The confidence test allows
you to test the connection between the adapter and the MVS
RACF. This allows you to verify that the adapter can connect
to MVS RACF without the Tivoli Identity Manager Server.
-setup Use this argument, along with the −confidence argument, to
configure the confidence test.
-help Use this argument to display the Help information for the
agentCfg command.
3. Type agentCfg and one or more of the supported arguments at the prompt.
You must type agentCfg before every argument to run the adapter
configuration tool.
Type agentCfg -list to list all of the adapters on the local host IP address.
Note that the default node for the Tivoli Identity Manager Server is 44970. The
output is similar to the following output:
Agent(s) installed on node ’127.0.0.1’
-----------------------
RACFAgent (44970)
Type agentCfg -agent RACFAgent to display the Main Menu of the agentCfg
tool, which is used to view or modify the RACF Adapter parameters.
Type agentCfg -list -hostname 192.9.200.7 to list the adapters on a host
whose IP address is 192.9.200.7. Note that the default node for the RACF
Adapter is 44970. The output is similar to the following output:
Agent(s) installed on node ’192.9.200.7’
------------------
RACFAgent (44970)
Type agentCfg -agent RACFAgent -hostname 192.9.200.7 to display the Main
Menu of the agentCfg tool for a host whose IP address is 192.9.200.7. Use the
menu options to view or modify the RACF Adapter parameters.
70 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Chapter 5. Configuring SSL authentication for the RACF
adapter
In order to establish a secure connection between a Tivoli Identity Manager
adapter and the Tivoli Identity Manager Server, you must configure the adapter
and the server to use the Secure Sockets Layer (SSL) authentication with the
default communication protocol, DAML. By configuring the adapter for SSL, you
ensure that the Tivoli Identity Manager Server verifies the identity of the adapter
before a secure connection is established.
You can configure SSL authentication for connections that originate from the Tivoli
Identity Manager Server or from the adapter. Typically, the Tivoli Identity Manager
Server initiates a connection to the adapter in order to set or retrieve the value of a
managed attribute on the adapter. However, depending on the security
requirements of your environment, you might need to configure SSL authentication
for connections that originate from the adapter. For example, if the adapter uses
events to notify the Tivoli Identity Manager Server of changes to attributes on the
adapter, you can configure SSL authentication for Web connections that originate
from the adapter to the Web server used by the Tivoli Identity Manager Server.
In a production environment, you need to enable SSL security; however, for testing
purposes you might want to disable SSL. If an external application that
communicates with the adapter (such as the Tivoli Identity Manager Server) is set
to use server authentication, you must enable SSL on the adapter to verify the
certificate that the application presents.
This chapter presents an overview of SSL authentication, certificates, and how to
enable SSL authentication using the CertTool utility.
Overview of SSL and digital certificates
When you deploy Tivoli Identity Manager in an enterprise network, you must
secure communication between the Tivoli Identity Manager Server and the
software products and components with which the server communicates. The
industry-standard SSL protocol, which uses signed digital certificates from a
certificate authority (CA) for authentication, is used to secure communication in a
Tivoli Identity Manager deployment. Additionally, SSL provides encryption of the
data exchanged between the applications. Encryption makes data transmitted over
the network intelligible only to the intended recipient.
Signed digital certificates enable two applications connecting in a network to
authenticate each other’s identity. An application acting as an SSL server presents
its credentials in a signed digital certificate to verify to an SSL client that it is the
entity it claims to be. An application acting as an SSL server can also be configured
to require the application acting as an SSL client to present its credentials in a
certificate, thereby completing a two-way exchange of certificates. Signed
certificates are issued by a third-party certificate authority for a fee. Some utilities,
such as those provided by OpenSSL, can also issue signed certificates.
A certificate-authority certificate (CA certificate) must be installed to verify the
origin of a signed digital certificate. When an application receives another
application’s signed certificate, it uses a CA certificate to verify the originator of
© Copyright IBM Corp. 2003, 2005 71
the certificate. A certificate authority can be well-known and widely used by other
organizations, or it can be local to a specific region or company. Many applications,
such as Web browsers, are configured with the CA certificates of well−known
certificate authorities to eliminate or reduce the task of distributing CA certificates
throughout the security zones in a network.
Private keys, public keys, and digital certificates
Keys, digital certificates, and trusted certificate authorities are used to establish and
verify the identities of applications.
SSL uses public key encryption technology for authentication. In public key
encryption, a public key and a private key are generated for an application. Data
encrypted with the public key can only be decrypted using the corresponding
private key. Similarly, the data encrypted with the private key can only be
decrypted using the corresponding public key. The private key is
password-protected in a key database file so that only the owner can access the
private key to decrypt messages that are encrypted using the corresponding public
key.
A signed digital certificate is an industry-standard method of verifying the
authenticity of an entity, such as a server, client, or application. In order to ensure
maximum security, a certificate is issued by a third-party certificate authority. A
certificate contains the following information to verify the identity of an entity:
Organizational information
This section of the certificate contains information that uniquely identifies
the owner of the certificate, such as organizational name and address. You
supply this information when you generate a certificate using a certificate
management utility.
Public key
The receiver of the certificate uses the public key to decipher encrypted
text sent by the certificate owner to verify its identity. A public key has a
corresponding private key that encrypts the text.
Certificate authority’s distinguished name
The issuer of the certificate identifies itself with this information.
Digital signature
The issuer of the certificate signs it with a digital signature to verify its
authenticity. This signature is compared to the signature on the
corresponding CA certificate to verify that the certificate originated from a
trusted certificate authority.
Web browsers, servers, and other SSL-enabled applications generally accept as
genuine any digital certificate that is signed by a trusted certificate authority and is
otherwise valid. For example, a digital certificate can be invalidated because it has
expired or the CA certificate used to verify it has expired, or because the
distinguished name in the digital certificate of the server does not match the
distinguished name specified by the client.
Self-signed certificates
You can use self-signed certificates to test an SSL configuration before you create
and install a signed certificate issued by a certificate authority. A self-signed
certificate contains a public key, information about the owner of the certificate, and
the owner’s signature. It has an associated private key, but it does not verify the
origin of the certificate through a third-party certificate authority. Once you
72 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
generate a self-signed certificate on an SSL server application, you must extract it
and add it to the certificate registry of the SSL client application.
This procedure is the equivalent of installing a CA certificate that corresponds to a
server certificate. However, you do not include the private key in the file when
you extract a self-signed certificate to use as the equivalent of a CA certificate.
Use a key management utility to generate a self-signed certificate and a private
key, to extract a self-signed certificate, and to add a self-signed certificate.
Where and how you choose to use self-signed certificates depends on your security
requirements. In order to achieve the highest level of authentication between
critical software components, do not use self-signed certificates, or use them
selectively. For example, you can choose to authenticate applications that protect
server data with signed digital certificates, and use self-signed certificates to
authenticate Web browsers or Tivoli Identity Manager adapters.
If you are using self-signed certificates, in the following procedures you can
substitute a self-signed certificate for a certificate and CA certificate pair.
Certificate and key formats
Certificates and keys are stored in files with the following formats:
.pem format
A privacy-enhanced mail (.pem ) format file begins and ends with the
following lines:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
A .pem file format supports multiple digital certificates, including a
certificate chain. If your organization uses certificate chaining, use this
format to create CA certificates.
.arm format
An .arm file contains a base-64 encoded ASCII representation of a
certificate, including its public key, but not its private key. An .arm file
format is generated and used by the IBM Key Management utility.
.der format
A .der file contains binary data. A .der file can only be used for a single
certificate, unlike a .pem file, which can contain multiple certificates.
.pfx format (PKCS12)
A PKCS12 file is a portable file that contains a certificate and a
corresponding private key. This format is useful for converting from one
type of SSL implementation to a different implementation. For example,
you can create and export a PKCS12 file using the IBM Key Management
utility, then import the file to another machine using the CertTool utility.
The use of SSL authentication
When you start the adapter, the available connection protocols are loaded. The
DAML protocol is the only available protocol that supports the use of SSL
authentication. You can specify to use the DAML SSL implementation.
The DAML SSL implementation uses a certificate registry to store private keys and
certificates. The location of the certificate registry is managed internally by the
Chapter 5. Configuring SSL authentication for the RACF adapter 73
CertTool key and certificate management tool; therefore, you do not specify the
location of the registry when you perform certificate management tasks.
For more information on the DAML protocol, see “Changing protocol
configuration settings” on page 41.
Configuring certificates for SSL authentication
Use the following procedures to configure the adapter for one-way or two-way SSL
authentication using signed certificates. In order to perform these procedures, use
the CertTool utility.
Configuring certificates for one-way SSL authentication
In this scenario, the Tivoli Identity Manager Server and the Tivoli Identity Manager
adapter are set to use SSL. Client authentication is not set on either application.
The Tivoli Identity Manager Server operates as the SSL client and initiates the
connection. The adapter operates as the SSL server and responds by sending its
signed certificate to the Tivoli Identity Manager Server. The Tivoli Identity
Manager Server uses the CA certificate that is installed to validate the certificate
sent by the adapter.
In Figure 4, Application A operates as the Tivoli Identity Manager Server, and
Application B operates as the Tivoli Identity Manager adapter.
In order to configure one-way SSL, perform the following tasks for each
application:
1. On the adapter, complete these steps:
a. Start the CertTool utility.
b. In order to configure the SSL-server application with a signed certificate
issued by a certificate authority:
1) Create a certificate signing request (CSR) and private key. This step
creates the certificate with an embedded public key and a separate
private key and places the private key in the PENDING_KEY registry
value.
2) Submit the CSR to the certificate authority using the instructions
supplied by the CA. When you submit the CSR, specify that you want
the root CA certificate returned with the server certificate.2. On the Tivoli Identity Manager Server, complete one of these steps:
Hello
Tivoli Identity ManagerServer (SSL client)
KeystoreCA
CertificateA
1
Send Certificate B
Tivoli Identity Manageradapter (SSL server)C
CertificateA
Verify
Figure 4. One-way SSL authentication (server authentication)
74 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
v If you are configuring the use of a signed certificate issued by a well-known
CA, ensure that the Tivoli Identity Manager Server has stored the root
certificate of the CA (CA certificate) in its keystore. If the keystore does not
contain the CA certificate, extract the CA certificate from the adapter and add
it to the keystore of the server.
v If you are configuring the use of self-signed certificates:
– If you generated the self-signed certificate on the Tivoli Identity Manager
Server, the certificate is already installed in its keystore.
– If you generated the self-signed certificate using the key management
utility of another application, extract the certificate from that application’s
keystore and add it to the keystore of the Tivoli Identity Manager Server.
Configuring certificates for two-way SSL authentication
In this scenario, the Tivoli Identity Manager Server and the Tivoli Identity Manager
adapter are set to use SSL and the adapter is set to use client authentication. Once
sending its certificate to the Tivoli Identity Manager Server, the adapter requests
identity verification from the server, which sends its signed certificate to the
adapter. Both applications are configured with signed certificates and
corresponding CA certificates.
In Figure 5, the Tivoli Identity Manager Server operates as Application A, and the
Tivoli Identity Manager adapter operates as Application B.
The following procedure assumes that you have already configured the adapter
and Tivoli Identity Manager Server for one-way SSL authentication using the
procedure described in “Configuring certificates for one-way SSL authentication”
on page 74. Therefore, if you are using signed certificates from a CA:
v The adapter is configured with a private key and a signed certificate that was
issued by a CA.
v The Tivoli Identity Manager Server is configured with the CA certificate of the
CA that issued the signed certificate of the adapter.
In order to complete the certificate configuration for two-way SSL, perform the
following tasks:
CHello
KeystoreCA
CertificateA
CertificateB
CertificateA
CACertificate
B
Send Certificate A
Tivoli Identity Manageradapter (SSL server) C
Tivoli Identity ManagerServer (SSL client)
Send Certificate AVerify
Verify
Send Certificate B
Figure 5. Two-way SSL authentication (client authentication)
Chapter 5. Configuring SSL authentication for the RACF adapter 75
1. On the Tivoli Identity Manager Server, create a CSR and private key, obtain a
certificate from a CA, install the CA certificate, install the newly signed
certificate, and extract the CA certificate to a temporary file.
2. On the adapter, add the CA certificate that was extracted from the keystore of
the Tivoli Identity Manager Server to the adapter.
When you have finished the two-way certificate configuration, each application has
its own certificate and private key and the CA certificate of the CA that issued the
certificates for each application.
Configuring certificates when the adapter operates as an SSL
client
In this scenario, the adapter operates as an SSL client in addition to operating as
an SSL server. This scenario applies if the adapter initiates a connection to the Web
server (used by the Tivoli Identity Manager Server) to send an event notification.
For example, the adapter initiates the connection and the Web server responds by
presenting its certificate to the adapter.
Figure 6 illustrates how a Tivoli Identity Manager adapter operates as an SSL sever
and an SSL client. When communicating with the Tivoli Identity Manager Server,
the adapter sends its certificate for authentication. When communicating with the
Web server, the adapter receives the certificate of the Web server.
If the Web Server is configured for two-way SSL authentication, it verifies the
identity of the adapter, which sends its signed certificate to the Web server (not
shown in the illustration). In order to enable two-way SSL authentication between
the adapter and Web server, use the following procedure:
1. Configure the Web server to use client authentication.
2. Follow the procedure for creating and installing a signed certificate on the Web
server.
3. Install the CA certificate on the adapter using the CertTool utility.
4. Add the CA certificate corresponding to the signed certificate of the adapter to
the Web server.
TivoliIdentityManagerAdapter
TivoliIdentityManagerServer
CA Certificate ACertificate ACA Certificate C
Certificate C
Web server
A B
C
Hello
Certificate A
Hello
Certificate C
Figure 6. Tivoli Identity Manager adapter operating as an SSL server and an SSL client
76 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
For more information on configuring certificates when the adapter initiates a
connection to the Web server (used by the Tivoli Identity Manager Server) to send
an event notification, see the Tivoli Identity Manager Information Center.
Managing SSL certificates using CertTool
The procedures in this section describe how to use the CertTool utility to manage
private keys and certificates.
This section includes instructions for performing the following tasks:
v “Starting CertTool.”
v “Generating a private key and certificate request” on page 79.
v “Installing the certificate” on page 80.
v “Installing the certificate and key from a PKCS12 file” on page 80.
v “Viewing the installed certificate” on page 81.
v “Viewing CA certificates” on page 81.
v “Installing a CA certificate” on page 81.
v “Deleting a CA certificate” on page 81.
v “Viewing registered certificates” on page 82.
v “Registering a certificate” on page 82.
v “Unregistering a certificate” on page 82.
Starting CertTool
In order to start the certificate configuration tool, CertTool, for the RACF Adapter,
complete these steps:
1. Log into the RACF Adapter.
2. Change to the bin directory for the adapter. For example, if the RACF Adapter
directory is in the default location, type the following command:
# cd home/itim/RACFAgent/bin
3. Type CertTool -agent RACFAgent at the prompt. The Main Menu is displayed:
Main menu - Configuring agent: RACFAgent
------------------------------
A. Generate private key and certificate request
B. Install certificate from file
C. Install certificate and key from PKCS12 file
D. View current installed certificate
E. List CA certificates
F. Install a CA certificate
G. Delete a CA certificate
H. List registered certificates
I. Register certificate
J. Unregister a certificate
K. Export certificate and key to PKCS12 file
X. Quit
Choice:
From the Main Menu, you can generate a private key and certificate request, install
and delete certificates, register and unregister certificates, and list certificates. The
following sections summarize the purpose of each group of options.
Chapter 5. Configuring SSL authentication for the RACF adapter 77
The first set of options (A through D) allows you to generate a CSR and install the
returned signed certificate on the adapter.
A. Generate private key and certificate request
Generate a CSR and the associated private key that is sent to the certificate
authority. For more information on option A, see “Generating a private key
and certificate request” on page 79.
B. Install certificate from file
Install a certificate from a file. This file must be the signed certificate
returned by the CA in response to the CSR that is generated by option A.
For more information on option B, see “Installing the certificate” on page
80.
C. Install certificate and key from a PKCS12 file
Install a certificate from a PKCS12 format file that includes both the public
certificate and a private key. If options A and B are not used to obtain a
certificate, the certificate that you use must be in PKCS12 format. For more
information on option C, see “Installing the certificate and key from a
PKCS12 file” on page 80.
D. View current installed certificate
View the certificate that is installed on the system. For more information
on option D, see “Viewing the installed certificate” on page 81.
The second set of options enable you to install root CA certificates on the adapter.
A CA certificate is used by the Tivoli Identity Manager adapter to validate the
corresponding certificate presented by a client, such as the Tivoli Identity Manager
Server.
E. List CA certificates
Show the installed CA certificates. The adapter only communicates with
Tivoli Identity Manager Servers whose certificates are validated by one of
the installed CA certificates.
F. Install a CA certificate
Install a new CA certificate so that certificates generated by this CA can be
validated. The CA certificate file can either be in X.509 or PEM encoded
formats. For more information on how to install a CA certificate, see
“Installing a CA certificate” on page 81.
G. Delete a CA certificate
Remove one of the installed CA certificates. For more information on how
to delete a CA certificate, see “Deleting a CA certificate” on page 81.
The remaining options (H through K) apply to adapters that must authenticate the
application (for example, the Tivoli Identity Manager Server or the Web server) to
which the adapter is sending information. These options enable you to register
certificates on the adapter. For Tivoli Identity Manager Version 4.5 or earlier, the
signed certificate of the Tivoli Identity Manager Server must be registered with an
adapter to enable client authentication on the adapter. If you do not intend to
upgrade an existing adapter to use CA certificates for client authentication, the
signed certificate presented by the Tivoli Identity Manager Server must be
registered with the adapter.
If you configure the adapter to use event notification, or client authentication is
enabled in DAML, then you must install the CA certificate corresponding to the
signed certificate of the Tivoli Identity Manager Server using the Install a CA
certificate option, option F.
78 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
H. List registered certificates
List all registered certificates that will be accepted for communications. For
more information on listing registered certificates, see “Viewing registered
certificates” on page 82.
I. Register a certificate
Register a new certificate. The certificate to be registered be in Base 64
encoded X.509 format or PEM. For more information on registering
certificates, see “Registering a certificate” on page 82.
J. Unregister a certificate
Unregister (remove) a certificate from the registered list. For more
information on unregistering certificates, see “Unregistering a certificate”
on page 82.
K. Export certificate and key to PKCS12 file
Export a previously installed certificate and private key. You will be
prompted for the filename and a password for encryption. For more
information on exporting a certificate and key to a PKCS12 file, see
“Exporting a certificate and key to PKCS12 file” on page 82.
Generating a private key and certificate request
A certificate signing request is an unsigned certificate that is a text file. When you
submit an unsigned certificate to a certificate authority, the CA signs the certificate
with the private digital signature that is included in their corresponding CA
certificate. When the CSR is signed, it becomes a valid certificate. A CSR contains
information about your organization, such as the organization name, country, and
the public key for your Web server.
In order to generate a CSR file, complete these steps:
1. At the Main Menu of the CertTool, type A. The following message and prompt
are displayed:
Enter values for certificate request (press enter to skip value)
-------------------------------------------------------------------------
2. At the Organization prompt, type your organization name, and press Enter.
3. At the Organizational Unit prompt, type the organizational unit, and press
Enter.
4. At the Agent Name prompt, type the name of the adapter you are requesting
a certificate for, and press Enter.
5. At the Email prompt, type the e-mail address for the contact person for this
request, and press Enter.
6. At the State prompt, type the state in which the adapter resides (if the adapter
is in the United States), and press Enter. Some certificate authorities do not
accept two letter abbreviations for states, so you must type the full name of
the state.
7. At the Country prompt, type the country in which the adapter resides, and
press Enter.
8. At the Locality prompt, type the name of the city in which the adapter
resides, and press Enter.
9. At the Accept these values prompt, type Y to accept the values displayed, or
type N to re-enter the values, and press Enter.
The private key and certificate request are generated once the values are
accepted.
Chapter 5. Configuring SSL authentication for the RACF adapter 79
10. At the Enter name of file to store PEM cert request prompt, type the name of
the file that you want to use to store the values you specified during the
previous steps, and press Enter.
11. Press Enter to continue. The certificate request and input values are written to
the file you specified, and the Main Menu is displayed again.
You can now request a certificate from a trusted CA by sending the .pem file that
you just generated to a certificate authority vendor.
Example of certificate signing request
Your CSR file will look similar to the following example:
-----BEGIN CERTIFICATE REQUEST-----
MIIB1jCCAT8CAQAwgZUxEjAQBgNVBAoTCWFjY2VzczM2MDEUMBIGA1UECxMLZW5n
aW5lZXJpbmcxEDAOBgNVBAMTB250YWdlbnQxJDAiBgkqhkiG9w0BCQEWFW50YWdl
bnRAYWNjZXNzMzYwLmNvbTELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3Ju
aWExDzANBgNVBAcTBklydmluZTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA
mR6AcPnwf6hLLc72BmUkAwaXcebtxCoCnnTH9uc8VuMHPbIMAgjuC4s91hPrilG7
UtlbOfy6X3R3kbeR8apRR9uLYrPIvQ1b4NK0whsytij6syCySaFQIB6V7RPBatFr
6XQ9hpsARdkGytZmGTgGTJ1hSS/jA6mbxpgmttz9HPECAwEAAaAAMA0GCSqGSIb3
DQEBAgUAA4GBADxA1cDkvXhgZntHkwT9tCTqUNV9sim8N/U15HgMRh177jVaHJqb
N1Er46vQSsOOOk4z2i/XwOmFkNNTXRVl9TLZZ/D+9mGZcDobcO+lbAKlePwyufxK
Xqdpu3d433H7xfJJSNYLYBFkrQJesITqKft0Q45gIjywIrbctVUCepL2
-----END CERTIFICATE REQUEST-----
Installing the certificate
Once you receive your certificate from your trusted CA, you install it in the
registry of the adapter. In order to install the certificate, complete these steps:
1. If you received the certificate as part of an e-mail message, copy the text of the
certificate to a text file, and copy that file to the bin directory for the adapter.
For example,
home/itim/RACFAgent/bin
2. At the Main Menu of the CertTool, type B. The following prompt is displayed:
Enter name of certificate file:
-------------------------------------------------------------------------
3. At the Enter name of certificate file prompt, type the full path to the
certificate file, and press Enter.
The certificate is installed in the registry for the adapter, and the Main Menu is
displayed again.
Installing the certificate and key from a PKCS12 file
If you do not use the CertTool utility to generate a CSR to obtain a certificate, you
must install both the certificate and private key, which must be stored in a PKCS12
file. The CA might send a password−protected file, or PKCS12 file (a file with the
.pfx extension), which includes both the certificate and private key. In order to
install the certificate from this PKCS12 file, complete these steps:
1. Copy the PKCS12 file to the bin directory for the adapter. For example,
home/itim/RACFAgent/bin
2. At the Main Menu for the CertTool, type C. The following prompt is displayed:
Enter name of PKCS12 file:
-------------------------------------------------------------------------
3. At the Enter name of PKCS12 file prompt, type the name of the PKCS12 file
that has the certificate and private key information, and press Enter. For
example, DamlSrvr.pfx.
4. At the Enter password prompt, type the password to access the file, and press
Enter.
80 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
The certificate and private key are installed in the adapter registry, and the Main
Menu is displayed.
Viewing the installed certificate
In order to list the certificate that is installed on your system, at the Main Menu of
CertTool, type D.
The installed certificate is listed, and the Main Menu is displayed. The following
example lists an installed certificate:
The following certificate is currently installed.
Subject: c=US,st=California,l=Irvine,o=DAML,cn=DAML Server
Installing a CA certificate
If you are using client authentication, you need to install a CA certificate. The CA
certificate you install is issued by a certificate authority vendor.
In order to install a CA certificate that was extracted into a temporary file,
complete the following steps:
1. At the Main Menu prompt, type F (Install a CA certificate).
The following prompt is displayed:
Enter name of certificate file:
2. At the Enter name of certificate file prompt, type the name of the certificate
file, such as DamlCACerts.pem, and press Enter.
The certificate file is opened, and the following prompt is displayed:
[email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng
Install the CA? (Y/N)
3. At the Install the CA prompt, type Y to install the certificate, and press Enter.
The certificate file is installed in the CACerts.pem file.
Viewing CA certificates
CertTool only installs one certificate and one private key. In order to list the CA
certificate that is installed on the adapter, type E at the Main Menu prompt.
The installed CA certificates are displayed and the Main Menu is displayed. The
following example lists an installed CA certificate:
Subject: o=IBM,ou=SampleCACert,cn=TestCA
Valid To: Wed Jul 26 23:59:59 2006
Deleting a CA certificate
In order to delete a CA certificate from the adapter directories, complete the
following steps:
1. At the Main Menu prompt, type G.
A list of all CA certificates installed on the adapter is displayed.
0 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng
1 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Support,cn=Support
Enter number of CA certificate to remove:
2. At the Enter number of CA certificate to remove prompt, type the number of
the CA certificate that you want to remove, and press Enter.
The CA certificate is deleted from the CACerts.pem file, and the Main Menu is
displayed.
Chapter 5. Configuring SSL authentication for the RACF adapter 81
Viewing registered certificates
Only requests that present a registered certificate will be accepted by the adapter
when client validation is enabled.
In order to view a list of all registered certificates available to the adapter, at the
Main Menu prompt, type H.
The registered certificates are displayed and the Main Menu is displayed. The
following example lists registered certificates:
0 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng
1 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Support,cn=Support
Registering a certificate
In order to register a certificate for the adapter, complete the following steps:
1. At the Main Menu prompt, type I.
The following prompt is displayed:
Enter name of certificate file:
2. At the Enter name of certificate file prompt, type the name of the certificate
file that you want to register, and press Enter.
The subject of the certificate is displayed, and a prompt is displayed, for
example:
[email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng
Register this CA? (Y/N)
3. At the Register this CA prompt, type Y to register the certificate, and press
Enter.
The certificate is registered to the adapter, and the Main Menu is displayed.
Unregistering a certificate
In order to unregister a certificate for the adapter, complete the following steps:
1. At the Main Menu prompt, type J.
The registered certificates are displayed. The following example lists registered
certificates:
0 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng
1 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Support,cn=Support
2. Type the number of the certificate file that you want to unregister, and press
Enter.
The subject of the selected certificate is displayed, and a prompt is displayed,
for example:
[email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng
Unregister this CA? (Y/N)
3. At the Unregister this CA prompt, type Y to unregister the certificate, and
press Enter.
The certificate is removed from the registered certificate list for the adapter, and
the Main Menu is displayed.
Exporting a certificate and key to PKCS12 file
In order to export a certificate and key to a PKCS12 file for the adapter, complete
the following steps:
1. At the Main Menu prompt, type K.
The following prompt is displayed:
82 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Enter name of PKCS12 file:
2. At the Enter name of PKCS12 file prompt, type the name of the PKCS12 file
for the installed certificate or private key, and press Enter.
3. At the Enter Password prompt, type the password for the PKCS12 file, and
press Enter.
4. At the Confirm Password prompt, type the password again, and press Enter.
The certificate or private key is exported to the PKCS12 file, and the Main
Menu is displayed.
Chapter 5. Configuring SSL authentication for the RACF adapter 83
84 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Chapter 6. Customizing the RACF adapter
There are two REXX execs provided with the installation, that allow an installation
to tailor the RACF Adapter to perform specific functions based upon an
installation’s needs:
v “ITIMEXIT”
v “ITIMEXEC” on page 86
ITIMEXIT
This REXX exec is executed in response to a processing request. There are four
instances implemented where this exit will get control:
Pre add processing
The request to add a user has been received, but not yet processed.
Post add processing
The request to add a user has been completed successfully
Pre delete processing
The request to delete a user has been received, but not yet processed.
Post delete processing
The request to delete a user has been completed successfully.
Exit processing may indicate success (return code zero), or failure (non-zero return
code) to be conveyed to the RACF Adapter. For the pre-add and pre-delete exits,
any non-zero return code will fail the processing of the current RACF user being
processed. For the post-add and post-delete exits, a non-zero return code will
return a warning for the current RACF user being processed.
The environment in which the exit exec gets control is within a TSO batch
environment, running within the APPC/MVS environment. You may call other
programs, and/or perform file I/O as necessary. Processing is performed under the
authority of the RACF ID that will perform the RACF commands to accomplish
the function. Any valid TSO command may be performed, as long as it does not
attempt to prompt a terminal user for input.
The ITIMEXIT exec should always be present, whether or not it performs any
functions. The sample ITIMEXIT provided has an exit 0 as the first executable
statement. You must modify or alter this exit to meet your needs.
The sample exit provides some function you may wish to use or customize to your
needs. Some examples of its use are:
v Defining a user’s catalog alias in one or more master catalogs at POST ADD exit
time.
v Defining a user’s data set profile at POST ADD exit time.
v Defining a user’s OMVS (Unix System Services) home directory at POST ADD
exit time.
v Deleting a users data set profiles at PRE DELETE exit time.
v Deleting a user’s catalog alias at POST DELETE exit time.
© Copyright IBM Corp. 2003, 2005 85
Be aware that any of the above functions that you wish to make the exit capable of
doing, must have proper RACF authorization given to the processing ID.
The following information is made available to the exit:
Table 18. ITIMEXIT processing information
Parameter # Meaning Possible values When present
1 Verb
Indicates what
operation is calling
the exit.
ADD or DELETE Always
2 Object
The object name of
the transaction.
USER indicating this
is a RACF user object
being processed.
Always
3 Prepost
Qualifies whether
this is PRE or POST
processing entry to
the exit.
PRE or POST Always
4 Name
The name of the
RACF object.
The RACF user ID
being processed.
Always
5 Dfltgrp
The RACF user ID’s
default group.
What was specified
from the Tivoli
Identity Manager
Server for this user’s
default group.
Only at PRE-ADD or
POST-ADD exit. Not
present for DELETE
processing.
6 Owner
The RACF user ID’s
owner.
What was specified
from the Tivoli
Identity Manager
Server for this user’s
owner.
Only at PRE-ADD or
POST-ADD exit. Not
present for DELETE
processing.
ITIMEXEC
This exit is provided for backward compatibility with the prior version of the
RACF Adapter.
There is no provision for passing back to the RACF Adapter the success or failure
of processing within the exit. There is no way to convey the success or failure of
exit processing back to the Tivoli Identity Manager Server. As such, any return
codes are ignored.
The environment in which the exit exec gets control is within a TSO batch
environment, running within the APPC/MVS environment. You may call other
programs, and/or perform file I/O as necessary. Processing is performed under the
authority of the RACF ID that will perform the RACF commands to accomplish
the function. Any valid TSO command may be performed, as long as it does not
attempt to prompt a terminal user for input.
86 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 19. ITIMEXEC processing information
Parameter # Source Value When present
1 Tivoli Identity
Manager attribute of
erRacfExecname
The value of
erRacfExecname
Always, as this
attribute’s presence
indicates this exit
should be invoked.
2 Tivoli Identity
Manager attribute of
erRacfExecvar
The value of
erRacfExecvar
Depends upon the
request generated by
the Tivoli Identity
Manager Server.
This exit will ONLY be invoked if the erRacfExecname attribute has been sent by
the Tivoli Identity Manager Server to the adapter. The erRacfExecvar attribute will
optionally be present, depending upon the processing that occurs on the Tivoli
Identity Manager Server.
Chapter 6. Customizing the RACF adapter 87
88 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Chapter 7. Troubleshooting the adapter
Troubleshooting is the process of determining why a product does not function as
it is designed to function. This chapter provides information to use while
attempting to identify and resolve problems related to the RACF Adapter
installation. It also provides information about troubleshooting errors that occur
due to improper input during installation.
Adapter log files
When the RACF Adapter is initially configured, a default directory is chosen to
contain the log files, which contain activity from the adapter.
The log files are kept within the Unix System Services file system, typically, under
the installation path of the adapter, in a sub directory of log/.
The adapter log name is the adapter instance name, followed by an extension of
.log. When the extension is simply .log, this is the current log file. Older log files
will have a slightly different extension, such as .log_001, .log_002 and so on.
For instance, if an installation path name is /usr/itim, and the adapter name
configured is racfagent, then you will find the log files in the /usr/itim/log/
directory, and you will find one or more files named racfagent.log,
racfagent.log_001, racfagent.log_002, and so on.
You may use the UNIX tail command, obrowse, or any other UNIX based utility
to inspect these adapter logs.
Adapter logging is configured with the agentCfg program. Each instance of an
adapter may have a different directory, but by default, will all be contained in the
same directory underneath the installation path.
The size of a log file, the number of log files, the directory path, and the detail
level of logging are all configured with the agentCfg program.
Please refer to Chapter 4, “Configuring the RACF adapter in IBM Tivoli Identity
Manager,” on page 39 for details.
© Copyright IBM Corp. 2003, 2005 89
90 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Appendix A. Agent attributes
In order for access to be granted, a target platform requires certain information
about the user. This information is collected in the Access Request Form (a value
for each attribute) during the Access Request process and is sent to the adapter by
the Tivoli Identity Manager Server. The adapter uses these values to create the user
access. Which attributes are needed depends upon the transaction requested, such
as System Login Add or Database Login Change.
Once the adapter software is installed on a platform and the adapter is defined by
Agent Maintenance, you identify the attribute data needed to create the user
access. You identify these attributes to Tivoli Identity Manager when defining the
Access Request Form for access through Request Maintenance.
Agent attributes by object
The following MVS RACF keywords can be used to create or modify RACF Access
Request Forms. MVS RACF requires only a user ID, password, and Default Group
for valid access. Be sure you include these keywords when creating the MVS RACF
Access Request Forms. A * denotes attributes for future release.
Note: Reconciliations return group data as well as user data.
erRacUser
This class represents a user account on the RACF database. There is one base user
object for each user defined in a RACF database.
Table 20. erRacUser attribute information
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erAccountStatus
Whether this user is in REVOKED
status, or not.
Boolean Bit Single RW No
erPassword
Password of user. Must be
alphanumeric, and can include ’@#$’.
Case insensitive.
String 8 Single RW No
erRacfExecName
Exec name - not a RACF attribute,
but for compatibility with old
RASEXEC.
String 44 Single W No
erRacfExecVar
Exec Attribute - not a RACF
attribute, but for compatibility with
old RASEXEC.
String 44 Single W No
erRacfRequester
RACF ID of requesting user. This is
the ID of the person within Identity
Manager who is making the
provisioning request.
String 8 Single W No
© Copyright IBM Corp. 2003, 2005 91
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUCategory
B1 Security categories.
String 8 Multiple RW No
erRacUClauth
A list of RACF resource classes this
user has rights to administer. Any
class in the Class Descriptor Table
(CDT), and USER is valid. GROUP
and DATASET are invalid.
String 8 Multiple RW No
erRacUCreDate
Date user was created.
Date Single R No
erRacUDfltgrp
Name of existing group that is the
initial and default group this user is
associated with.
String 8 Single RW Yes
erRacUInstData
Installation defined data that may be
associated with a user.
String 254 Single RW No
erRacUIsADSP
User may or may not automatically
create discrete data set profiles.
Boolean Bit Single RW No
erRacUIsAudit
User has system auditor ability.
Boolean Bit Single RW No
erRacUIsCatalog
Run Script to create catalog Alias for
this user.
Boolean Bit Single W No
erRacUIsCICSSeg
CICS segment is present.
User CICS information. Since this is
an optional object, its presence has
meaning, even if it contains no
values for attributes. CICS this
information assigns the user specific
characteristics.
Boolean Bit Single RW No
erRacUCICSIsForc
Whether this user will be forced off
if current system fails over to a
backup system.
Boolean Bit Single RW No
erRacUCICSOpclas
Operator class. Valid values are 1 to
24.
Integer 2 Multiple RW No
erRacUCICSOpid
Operator ID. 1 to 3 characters. Any
value acceptable.
String 3 Single RW No
erRacUCICSPrty
Operator priority, value may be 0 to
255.
Integer 3 Single RW No
92 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUCICSTimout
User timeout value, in the form of
HHMM.
Time 4 Single RW No
erRacUIsDCESeg
DCE segment is present.
DCE information. This information
describes the user in the context of a
DCE (Distributed Computing
Environment). Since this is an
optional object, its presence has
meaning, even if it contains no
values for attributes.
Boolean Bit Single RW No
erRacUDCEIsAutoL
Whether this user should be
automatically identified to DCE
through AUTOLOGIN or not.
Boolean Bit Single RW No
erRacUDCEHomeC
DCE Home Cell name.
String 1023 Single RW No
erRacUDCEHomeU
UUID for the cell that this user is
defined to. String must have the
delimiter of ″-″ in character positions
9, 14, 19, and 24. The general format
for the UUID string is
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, in which x represents
a valid numeric or hexadecimal
character.
String 36 Single RW No
erRacUDCEName
DCE Principal name.
String 1023 Single RW No
erRacUDCEUUID
UUID of this instance of the user.
This string must have the delimiter
of ″-″ in character positions 9, 14, 19,
and 24. The general format for the
UUID string is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, in which x
represents a valid numeric or
hexadecimal character.
String 36 Single RW No
erRacUIsDFPSeg
DFP segment is present.
The following attributes are user
DFP information. Since this is an
optional object, its presence has
meaning, even if it contains no
values for attributes. DFP uses this
information to determine data
management and disk storage
characteristics when a user creates a
new data set.
Boolean Bit Single RW No
Appendix A. Agent attributes 93
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUDFPAppl
Name of a user defined application.
String 8 Single RW No
erRacUDFPData
DATACLAS name to be used for
new file creation.
String 8 Single RW No
erRacUDFPMgmt
MGMTCLAS name to be used for
new file creation.
String 8 Single RW No
erRacUDFPStor
STORCLAS name to be used for new
file creation.
String 8 Single RW No
erRacUIsEimSeg
EIM segment is present.
EnterPrise Identity Management
(EIM). This object contains a name
from the LDAPBIND general
resource profile class, of the user as
it is known to the Enterprise Identity
Mapping environment. Since this is
an optional object, its presence has
meaning, even if it contains no
values for attributes.
Boolean Bit Single RW No
erRacUEimLDAPNam
Name of profile in the LDAPBIND
class.
String 246 Single RW No
erRacUIsGrpacc
Permits group level access of
UPDATE to the group under the
High Level Qualifier of any dataset
profile created through ADSP by this
user.
Boolean Bit Single RW No
erRacUIsKerbSeg
Kerberos segment is present.
Kerberos information. This object
describes Kerberos information that
relates to this instance of the user.
Since this is an optional object, its
presence has meaning, even if it
contains no values for attributes.
Boolean Bit Single RW No
erRacUKerbIsDES
Single length DES keys allowed.
Boolean Bit Single RW No
erRacUKerbIsDES3
Triple DES keys allowed.
Boolean Bit Single RW No
erRacUKerbIsDESD
Double DES keys allowed.
Boolean Bit Single RW No
94 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUKerbName
Kerberos Principal name. can consist
of any character except the @+
(X’7C’) character. It is highly
recommended that you avoid using
any of the EBCDIC variant characters
be avoided to prevent problems
between different code pages.
String 240 Single RW Yes
erRacUKerbTickMx
Maximum ticket life, in seconds.
Valid value range is 1 to
2,147,483,647.
Integer 10 Single RW No
erRacUIsLangSeg
Language segment is present.
User Language information. Since
this is an optional object, its presence
has meaning, even if it contains no
values for attributes.
Boolean Bit Single RW No
erRacULangPrime
Primary user language.
String 3 Single RW No
erRacULangSec
Secondary user language.
String 3 Single RW No
erRacUIsLNotes
Lotus Notes segment present.
Lotus Notes information. This object
contains a Lotus Notes short name,
of the user as it is known to this
RACF system. Since this is an
optional object, its presence has
meaning, even if it contains no
values for attributes.
Boolean Bit Single RW No
erRacULnotesSNam
Lotus Notes Short Name. You can
specify the following characters:
upper and lower case alphabetic (A
through Z, and a through z), 0
through 9, & (X’50’), - (X’60’), .
(X’4B’), _ (X’6D’), and (X’40’). The
hex values shown are EBCDIC.
String 64 Single RW No
erRacUIsNDSSeg
NDS segment is present.
Boolean Bit Single RW No
Appendix A. Agent attributes 95
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUIsNetvSeg
NetView segment is present.
NetView information. This object
may or may not be present. It
contains attributes that describe this
user’s instance in the IBM Netview
environment. Since this is an
optional object, its presence has
meaning, even if it contains no
values for attributes.
Boolean Bit Single RW No
erRacUNetvCons
Console name user will assume
when console commands are issued.
String 8 Single RW No
erRacUNetvCtl
Only the specific values are allowed
Default is ’Specific’. Values allowed
are: General Global Specific.
String 8 Single RW No
erRacUNetvDomain
List of commands a Netview
operator my run in another Netview
Domain.
String 5 Multiple RW No
erRacUNetvGSpan
Not well documented. The best
information found within Netview
documentation indicates this is a
maximum of 8 characters.
String 8 Single RW No
erRacUNetvIC
Initial command to be run when this
Netview user enters the Netview
subsystem.
String 255 Single RW No
erRacUNetvIsGMF
Whether this user may utilize the
Netview Graphic Monitor Facility or
not.
Boolean Bit Single RW No
erRacUNetvIsMR
Whether this user may receive
unsolicited messages or not.
Boolean Bit Single RW No
erRacUNetvOpclas
Netview Operator classes. May be a
values of 1 to 2040.
Integer 4 Multiple RW No
erRacUIsOMVSSeg
OMVS segment is present.
OMVS (Unix) information. Since this
is an optional object, its presence has
meaning, even if it contains no
values for attributes.
Boolean Bit Single RW No
96 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUOMVSCPU
Maximum CPU time, in seconds, this
user may accumulate before
processes will be purged. Valid value
range 7 to 2,147,483,647.
Integer 10 Single RW No
erRacUOMVSFiles
Maximum number of files per
process. Valid value range is 3 to
262,143.
Integer 6 Single RW No
erRacUOMVSHome
Home directory of user. Case
sensitive. Path must be valid for user
may use the shell.
String 1024 Single RW No
erRacUOMVSIsHome
This attribute is set to true, if the
home (erRacUOMVSPath) directory
is to be created.
Boolean Bit Single W No
erRacUOMVSIsShar
If NOT set, and the UID specified is
already assigned, and Shared UID
support is enabled, the UID
assignment may fail.
Boolean Bit Single W No
erRacUOMVSMmap
Maximum number of pages for
memory mapped files. Valid value
range is 1 to 16,777,216.
Integer 8 Single RW No
erRacUOMVSProc
Maximum processes per user. Valid
value range is 3 to 32,767.
Integer 5 Single RW No
erRacUOMVSShell
Shell program for user. Case
sensitive. Must be a valid shell name
for user to use the shell. Should be a
fully qualified name, as the
environment has not yet been
established.
String 1024 Single RW No
erRacUOMVSStor
Maximum amount of storage, in
bytes, this user may use. Valid value
range is 10,485,760 to 2,147,483,647.
Integer 10 Single RW No
erRacUOMVSThread
Maximum number of threads per
process. Valid value range is 0 to
100,000. Must be non-zero to allow
use of ptthread_create.
Integer 6 Single RW No
Appendix A. Agent attributes 97
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUOMVSuid
Unix uid assigned to this user. Valid
values are 0 to 2,147,483,647. Zero (0)
means superuser.’*’ means that the
UID will be automatically assigned.
Specific profiles for AUTOUID
support must be set up prior to its
usage.
String 10 Single RW No
erRacUIsOper
User has system Operations ability
(ability to read/modify any file).
Boolean Bit Single RW No
erRacUIsOperSeg
Operparm segment is present.
Operparm information. Attributes
describe settings as a system
operator. Since this is an optional
object, its presence has meaning,
even if it contains no values for
attributes.
Boolean Bit Single RW No
erRacUOpAltgrp
Alternate Console group used in
recovery.
Character 8 Single RW No
erRacUOpAuth
Console Authority. Valid values are:
v Master
v All
v Info
v Cons
v Io
v Sys
Character 6 Single RW No
erRacUOpAuto
Whether or not the extended console
can receive messages which have
been automated by the MPF facility.
Boolean Bit Single RW No
erRacUOpCmdsys
Console name or ’*’. A-Z, 0-9, @, #, $
are valid values, in addition to ’*’.
Character 8 Single RW No
erRacUOpDom
Valid values are ’Normal’, ’All’, or
’None’.
Character 6 Single RW No
erRacUOpKey
One to 8 character key to display
information from all consoles with
this key. Valid values are A-Z, 0-9, @,
#, $.
Character 8 Single RW No
98 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUOpLevel
Level of information that can be
displayed. Valid values are:
v NB
v R
v CE
v E
v IN
v ALL
If ALL is specified, no others may be
specified.
Character 3 Multi RW No
erRacUOpLogcmd
Valid values are SYSTEM or NONE.
Boolean Bit Single RW No
erRacUOpMform
Message form of the messages
displayed upon the extended
console. Valid values are:
v J
v M
v S
v T
v X
Character Bit Multi RW No
erRacUOpMigid
Whether or not a migration ID is to
be assigned to this extended console.
Boolean Bit Single RW No
erRacUOpMonitor
Valid values are:
v JOBNAMES or JOBNAMEST
v SESS or SESST
v STATUS
Character 9 Multi RW No
erRacUOpMscope
Valid system names for which
messages can be received from. Valid
values are system names, ’*’ and
’*ALL’.
Character 8 Multi RW No
erRacUOpRoutCode
The Routing Codes this console is to
receive. Value range is 1 to 128.
Integer 3 Multi RW No
erRacUOpStor
Valid value range is 1 to 2000.
Integer 4 Single RW No
erRacUOpUD
Whether or not this console is to
receive undeliverable messages.
Boolean Bit Single RW No
erRacUIsProtect
User may not be signed on to with a
password.
Boolean Bit Single RW No
Appendix A. Agent attributes 99
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUIsPrxSeg
PROXY segment is present.
PROXY segment information. This
object contains a name from the
LDAPBIND general resource profile
class, of the user as it is known to
the Enterprise Identity Mapping
environment. Since this is an
optional object, its presence has
meaning, even if it contains no
values for attributes.
Boolean Bit Single RW No
erRacUPrxBindDN
Bind DN of user on target host.
Binary 1023 Single RW No
erRacUPrxBindHst
A URL of a host, which the local
z/OS LDAP server will contact on
user’s behalf.
Binary 1023 Single RW No
erRacUPrxBindPW
Bind password for
erRacUPrxBindDN.
String 128 Single W No
erRacUIsRestrict
User cannot be granted access
through UACC or ID(*) in resource
profiles.
Boolean Bit Single RW No
erRacUIsSpecial
User has system Special. System
Security Administrator.
Boolean Bit Single RW No
erRacUIsTSOSeg
TSO segment is present.
User TSO information. Since this is
an optional object, its presence
allows a user access to the
time-sharing environment, even if all
attribute values are null.
Boolean Bit Single RW No
erRacUTSOAcct
Name of a user defined application.
String 40 Single RW No
erRacUTSOCmd
Initial command to be executed upon
connecting to TSO.
String 80 Single RW No
erRacUTSODest
Default destination for system
output. Must begin with A-Z, @#$,
remaining data may be numeric.
String 8 Single RW No
erRacUTSOHold
Default system output class for the
held queue. Must be alphanumeric.
String 1 Single RW No
100 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUTSOMsg
Default system output message class.
Must be alphanumeric.
String 1 Single RW No
erRacUTSOJob
Default system job execution class.
Must be alphanumeric.
String 1 Single RW No
erRacUTSOMax
Maximum amount of storage user
may request. Amount is specified in
K bytes. Zero means no limit.
Integer 7 Single RW No
erRacUTSOProc
Default TSO logon procedure. Must
begin with A-Z, @#$, remaining data
may be numeric.
String 8 Single RW No
erRacUTSOSize
Requested amount of storage to be
used by this session. Zero means no
limit.
Integer 7 Single RW No
erRacUTSOSlbl
Default Security Label. See notes
about B1 support. Should probably
be excluded.
String 8 Single RW No
erRacUTSOSout
Default system output message class.
Must be alphanumeric.
String 1 Single RW No
erRacUTSOUnit
Default allocation unit name.
String 8 Single RW No
erRacUTSOUdata
Hexadecimal value, defined by the
user installation. Typically, this is
unused.
String 4 Single RW No
erRacUIsUaudit
All user’s activity will be logged.
Boolean Bit Single RW No
erRacUIsWASeg
Work attribute is present.
Work Attribute information. It
describes user location specifics. This
object is/was primarily created for
APPC/MVS. Since this is an optional
object, its presence has meaning,
even if it contains no values for
attributes.
Boolean Bit Single RW No
erRacUWAAcct
Account number. This field only has
(real) meaning for APPC/MVS tasks.
String 255 Single RW No
Appendix A. Agent attributes 101
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUWAAcct
Account number. This field only has
(real) meaning for APPC/MVS tasks.
String 255 Single RW No
erRacUWAAddr1
Address line 1.
String 60 Single RW No
erRacUWAAddr2
Address line 2.
String 60 Single RW No
erRacUWAAddr3
Address line 3.
String 60 Single RW No
erRacUWAAddr4
Address line 4.
String 60 Single RW No
erRacUWABldg
Building.
String 60 Single RW No
erRacUWADept
Department.
String 60 Single RW No
erRacUWAName
Name.
String 60 Single RW No
erRacUWARoom
Room.
String 60 Single RW No
erRacULogdate
Date user last signed on. Field is set
to current date if password has been
reset, or if the user’s account status
has been resumed.
Date Single R No
erRacULogtime
Time user last signed on. Field is set
to current time if password has been
reset, or if the user’s account status
has been resumed.
Time Single R No
erRacUModel
The name of a data set profile this
user may use as a model for creating
new data set profiles.
String 44 Single RW No
erRacUName
The name of the defined user. Value
is nullified by setting it to 20 pound
(#) signs:
####################
String 20 Single RW No
erRacUOwner
Name of existing user or group that
owns this user account.
String 8 Single RW Yes
102 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 20. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacUPassdate
Date user is required to change
password. If 0, current password
must be changed upon initial use.
Date Single R No
erRacUPWInterval
Password interval. May be between 0
and 255. Zero means no password
interval. Maximum value imposed by
RACF system wide options.
Integer 3 Single RW No
erRacUPWNoExpire
Whether or not a password assigned
to this user is to be noted as ’not
expired’. Must be used in
conjunction with the ’erPassword’.
This has no meaning without a
password. This field have been
removed from the schema. It will
instead be an adapter option.
Boolean Bit Single W No
erRacUResumeDate
MM/DD/YY date field, indicates
future date when this account is to
be reactivated (RESUMEd).
Date 8 Single RW No
erRacURevokeDate
MM/DD/YY date field, indicates
future date when this account is to
be inactivated (revoked).
Date 8 Single RW No
erRacUSeclabel
B1 Security Label. User’s default
security label.
String 8 Single RW No
erRacUSeclevel
B1 Security Level.
String 8 Single RW No
erRacUWhenDays
Days of the week a user may sign
on. Valid values are:
v SUNDAY
v MONDAY
v TUESDAY
v WEDNESDAY
v THURSDAY
v FRIDAY
v SATURDAY
v ANYDAY
String 9 Multi RW No
erRacUWhenTime
Time range when user may sign on
to the system.
Time 9 Single RW No
erUid
ID of user on RACF being created,
updated or deleted.
String 8 Single RW Yes
Appendix A. Agent attributes 103
erRacConnect
This class represents a user’s connection to a group within RACF. The following
connect object is associated with the base user object, and must have at least 1, but
may have over 7,000 occurrences, but typically no more than 100. Varies upon
customer environment.
Table 21. erRacUser attribute information
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacConAuth
Group authority. Valid values are:
v USE
v CREATE
v CONNECT
v JOIN
String 7 Single RW No
erRacConCDate
Connect entry creation date.
Date 7 Single R No
erRacConCount
Connect count. Max value of 65,535.
Integer 5 Single R No
erRacConGroup
Name of group to which user is
connected.
String 8 Single RW Yes
erRacConIsADSP
User may or may not automatically
create discrete data set profiles.
Boolean Bit Single RW No
erRacConIsAudit
User has system Auditor ability.
Boolean Bit Single RW No
erRacConIsGrpac
Permits group level access of
UPDATE to the group under the
High Level Qualifier of any dataset
profile created through ADSP by this
user.
Boolean Bit Single RW No
erRacConIsOper
User has system Operations ability
(ability to read/modify any file).
Boolean Bit Single RW No
erRacConIsSpec
UUser has system Special. System
security Administrator.
Boolean Bit Single RW No
erRacConLogdate
Date user last signed on, using this
group as default group or specified
group.
Date Single R No
erRacConLogtime
Time user last signed on, using this
group as default group or specified
group.
Time Single R No
104 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Table 21. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacConOwner
Owner of this connect entry.
String 8 Single RW Yes
erRafConResumDt
MM/DD/YY date field, indicates
future date when this account is to
be reactivated (RESUMEd).
Date 8 Single R No
erRacConRevokDt
MM/DD/YY date field, indicates
future date when this account is to
be inactivated (revoked).
Date 8 Single R No
erRacConUACC
Default universal access to all data
set and TAPEVOL profiles created by
this user. Valid Values are:
v NONE
v READ
v UPDATE
v CONTROL
v ALTER
String 7 Single RW No
erRacConXML
This attribute will actually carry an
XML string that represents all the
data for a single connect entry. It will
carry all the information that
comprises a RACF connect entry.
This is due to the server flattening
out all the data elements.
String ??? Multi RW Yes
erRacGroup
This class represents a group definition within RACF. The RACF group represents
a group definition within the RACF database. Its presence is required to allow
Identity Manager to understand the RACF group tree structure, to know what
groups are within or outside of management policy. This information is read-only,
and is not managed nor updated by Identity Manager at this time. Although
optional segments are provided in this documentation, implementation of them is
to be decided later.
Table 22. erRacUser attribute information
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacGrpCDate
Creation date of this group.
Date 8 Single RW Yes
erRacGrpData
Installation data, user defined
purpose.
String 255 Single RW No
erRacGrpDFPAppl
DFP segment, DATAAPPL field.
String 8 Single RW No
Appendix A. Agent attributes 105
Table 22. erRacUser attribute information (continued)
Attribute Data type Maximum length
Single or multiple
value
Read or
write Required?
erRacGrpDFPData
DFP segment, Data class.
String 8 Single RW No
erRacGrpDFPMgmt
DFP segment, management class.
String 8 Single RW No
erRacGrpDFPStor
DFP segment, storage class.
String 8 Single RW No
erRacGrpIsDFP
Indicates presence of DFP segment
information.
Boolean Bit Single RW No
erRacGrpIsOMVS
Indicates presence of OMVS segment
information.
Boolean Bit Single RW No
erRacGrpIsTME
Indicates presence of TME role
segment information.
Boolean Bit Single RW No
erRacGrpIsUni
Indicates this is a Universal Group
(Unlimited number of users
connected).
Boolean Bit Single RW No
erRacGrpName
Name of group to which user is
connected.
String 8 Single RW Yes
erRacGrpOMVSGid
OMVS Group ID. Valid values are 0
to 2,147,483,647.
Integer 10 Single RW No
erRacGrpOwner
Owner of this group.
String 8 Single RW Yes
erRacGrpSubgrp
Subordinate groups to this group.
String 8 Multiple RW No
erRacGrpSuper
Superior group to this group.
String 8 Single RW Yes
erRacGrpTMERole
Role groups that this group is part
of.
String 8 Multiple RW No
erRacGrpTUACC
Terminal Universal Access utilized or
not.
Boolean Bit Single RW No
106 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Appendix B. Registry settings
For the RACF adapter, the following table contains valid registry options, their
values and meanings.
Table 23. Registry settings and additional information
Option
attribute
Default value Valid values Function and meaning Required?
APPCCMD ITIMCMD 1 to 64 EBCDIC
characters, case
sensitive.
This is the APPC/MVS back end
command executor transaction name.
No
APPCRECO ITIMRECO 1 to 64 EBCDIC
characters, case
sensitive.
This is the APPC/MVS back end
reconciliation transaction name.
No
PASSEXPIRE TRUE TRUE, FALSE, or
TRUEADD
When defaulted, or set to TRUE, all
password changes executed are expired
passwords, requiring change upon next
logon.
If set to FALSE, all password changes will
be set to non-expired passwords.
When set to TRUEADD, a password for a
new user will be set to EXPIRED. A
password set on an existing user will be
set to non-EXPIRED.
In each case, READ or UPDATE access to
the FACILITY class profile,
IRR.PASSWORD.RESET will be required.
No
SCOPING None TRUE, FALSE If this registry attribute is not specified,
then the function of a scoped
reconciliation is based upon the presence
of a RACF ID specified on the service
form.
If there is an ID in the service form, a
scoped recon will be performed.
If it is left blank, a full recon will be
performed.
If this registry attribute is set to TRUE it
will always perform a scoped recon,
based upon the RACF ID the it is
executing as, either the specified
surrogate (from the service form) or the
adapter’s RACF ID.
If this registry attribute is set to FALSE it
will always perform a full recon,
irrespective of the RACF ID it is
executing as.
Yes
© Copyright IBM Corp. 2003, 2005 107
Table 23. Registry settings and additional information (continued)
Option
attribute
Default value Valid values Function and meaning Required?
APPCOLU None 1 to 8 EBCDIC
characters, case
sensitive, must be
upper case.
This is the originating APPC/MVS logical
unit, from which the adapter will
communicate.
No
APPCDLU None 1 to 8 EBCDIC
characters, case
sensitive, must be
upper case.
This is the destination APPC/MVS logical
unit, to which the adapter will
communicate. THIS LU MUST BE ON
THE SAME HOST AS THE ’APPCOLU’.
No
APPCMODE None 1 to 8 EBCDIC
characters, case
sensitive, must be
upper case.
This is the VTAM ’LOGMODE’ entry to
be utilized by the APPC connection. The
modetable utilized by the APPCOLU
logical unit must have this LOGMODE
entry defined within it.
No
108 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Appendix C. Support information
This section describes the following options for obtaining support for IBM
products:
v “Searching knowledge bases”
v “Obtaining fixes” on page 110
v “Contacting IBM Software Support” on page 110
Searching knowledge bases
If you have a problem with your IBM software, you want it resolved quickly. Begin
by searching the available knowledge bases to determine whether the resolution to
your problem is already documented.
Search the information center on your local system or
network
IBM provides extensive documentation that can be installed on your local
computer or on an intranet server. You can use the search function of this
information center to query conceptual information, instructions for completing
tasks, reference information, and support documents.
Search the Internet
If you cannot find an answer to your question in the information center, search the
Internet for the latest, most complete information that might help you resolve your
problem. To locate Internet resources for your product, open one of the following
Web sites:
v IBM Tivoli Identity Manager Performance Tuning Guide
Provides information needed to tune Tivoli Identity Manager Server for a
production environment, available on the Web at:
http://publib.boulder.ibm.com/tividd/td/tdprodlist.html
Click the I character in the A-Z product list, and then, click the Tivoli Identity
Manager link. Browse the information center for the Technical Supplements
section.
v Redbooks and white papers are available on the Web at:
http://www.ibm.com/software/sysmgmt/products/support/IBMTivoliIdentityManager.html
Browse to the Self Help section, in the Learn category, and click the Redbooks
link.
v Technotes are available on the Web at:
http://www.redbooks.ibm.com/redbooks.nsf/tips/
v Field guides are available on the Web at:
http://www.ibm.com/software/sysmgmt/products/support/Field_Guides.html
v For an extended list of other Tivoli Identity Manager resources, search the
following IBM developerWorks Web address:
http://www.ibm.com/developerworks/
© Copyright IBM Corp. 2003, 2005 109
Obtaining fixes
A product fix might be available to resolve your problem. You can determine what
fixes are available for your IBM software product by checking the product support
Web site:
1. Go to the IBM Software Support Web site
(http://www.ibm.com/software/support).
2. Under Products support pages A to Z, select the letter for your product name.
3. In the list of specific products, click IBM Tivoli Identity Manager.
4. Under Self help, you find a list of fixes, fix packs, and other service updates
for your product.
5. Click the name of a fix to read the description and optionally download the fix.
To receive weekly e-mail notifications about fixes and other news about IBM
products, follow these steps:
1. From the support page for any IBM product, click My support in the upper-left
corner of the page.
2. If you have already registered, skip to the next step. If you have not registered,
click register in the upper-right corner of the support page to establish your
user ID and password.
3. Sign in to My support.
4. On the My support page, click Edit profiles in the left navigation pane, and
scroll to Select Mail Preferences. Select a product family and check the
appropriate boxes for the type of information you want.
5. Click Submit.
6. For e-mail notification for other products, repeat Steps 4 and 5.
For more information about types of fixes, see the Software Support Handbook
(http://techsupport.services.ibm.com/guides/handbook.html).
Contacting IBM Software Support
IBM Software Support provides assistance with product defects.
Before contacting IBM Software Support, your company must have an active IBM
software maintenance contract, and you must be authorized to submit problems to
IBM. The type of software maintenance contract that you need depends on the
type of product you have:
v For IBM distributed software products (including, but not limited to, Tivoli,
Lotus, and Rational products, as well as DB2 and WebSphere products that run
on Windows or UNIX operating systems), enroll in Passport Advantage in one
of the following ways:
– Online: Go to the Passport Advantage Web page
(http://www.lotus.com/services/passport.nsf/WebDocs/
Passport_Advantage_Home) and click How to Enroll
– By phone: For the phone number to call in your country, go to the IBM
Software Support Web site
(http://techsupport.services.ibm.com/guides/contacts.html) and click the
name of your geographic region.v For IBM eServer software products (including, but not limited to, DB2 and
WebSphere products that run in zSeries, pSeries, and iSeries environments), you
can purchase a software maintenance agreement by working directly with an
IBM sales representative or an IBM Business Partner. For more information
110 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
about support for eServer software products, go to the IBM Technical Support
Advantage Web page (http://www.ibm.com/servers/eserver/techsupport.html).
If you are not sure what type of software maintenance contract you need, call
1-800-IBMSERV (1-800-426-7378) in the United States or, from other countries, go to
the contacts page of the IBM Software Support Handbook on the Web
(http://techsupport.services.ibm.com/guides/contacts.html) and click the name of
your geographic region for phone numbers of people who provide support for
your location.
Follow the steps in this topic to contact IBM Software Support:
1. Determine the business impact of your problem.
2. Describe your problem and gather background information.
3. Submit your problem to IBM Software Support.
Determine the business impact of your problem
When you report a problem to IBM, you are asked to supply a severity level.
Therefore, you need to understand and assess the business impact of the problem
you are reporting. Use the following criteria:
Severity 1 Critical business impact: You are unable to use the program,
resulting in a critical impact on operations. This condition
requires an immediate solution.
Severity 2 Significant business impact: The program is usable but is
severely limited.
Severity 3 Some business impact: The program is usable with less
significant features (not critical to operations) unavailable.
Severity 4 Minimal business impact: The problem causes little impact on
operations, or a reasonable circumvention to the problem has
been implemented.
Describe your problem and gather background information
When explaining a problem to IBM, be as specific as possible. Include all relevant
background information so that IBM Software Support specialists can help you
solve the problem efficiently. To save time, know the answers to these questions:
v What software versions were you running when the problem occurred?
v Do you have logs, traces, and messages that are related to the problem
symptoms? IBM Software Support is likely to ask for this information.
v Can the problem be re-created? If so, what steps led to the failure?
v Have any changes been made to the system? (For example, hardware, operating
system, networking software, and so on.)
v Are you currently using a workaround for this problem? If so, please be
prepared to explain it when you report the problem.
Submit your problem to IBM Software Support
You can submit your problem in one of two ways:
v Online: Go to the ″Submit and track problems″ page on the IBM Software
Support site (http://www.ibm.com/software/support/probsub.html). Enter
your information into the appropriate problem submission tool.
Appendix C. Support information 111
v By phone: For the phone number to call in your country, go to the contacts page
of the IBM Software Support Handbook on the Web
(http://techsupport.services.ibm.com/guides/contacts.html) and click the name
of your geographic region.
If the problem you submit is for a software defect or for missing or inaccurate
documentation, IBM Software Support creates an Authorized Program Analysis
Report (APAR). The APAR describes the problem in detail. Whenever possible,
IBM Software Support provides a workaround for you to implement until the
APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the
IBM product support Web pages daily, so that other users who experience the
same problem can benefit from the same resolutions.
For more information about problem resolution, see Searching knowledge bases
and Obtaining fixes.
112 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Appendix D. 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-0032, 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.
© Copyright IBM Corp. 2003, 2005 113
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
2ZA4/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 information 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.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
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.
Trademarks
The following terms are trademarks or registered trademarks of International
Business Machines Corporation in the United States, other countries, or both:
IBM
IBM logo
AIX
DB2
Novell
SecureWay
Tivoli
Tivoli logo
Universal Database
WebSphere
Lotus is a registered trademark of Lotus Development Corporation and/or IBM
Corporation.
Domino is a trademark of International Business Machines Corporation and Lotus
Development Corporation in the United States, other countries, or both.
114 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
Intel, Intel Inside (logos), MMX and Pentium are trademarks of Intel Corporation
in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Linux is a trademark of Linus Torvalds in the U.S., other countries, or both.
Sun, Sun Microsystems, and the Sun Logo are trademarks or registered trademarks
of Sun Microsystems, Inc. in the United States and other countries.
Java and all Java-based trademarks are trademarks of Sun
Microsystems, Inc. in the United States, other countries, or
both.
Other company, product, and service names may be trademarks or service marks
of others.
Appendix D. Notices 115
116 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
Index
Aaccessibility
pdf format, for screen-reader software ix
statement for documentation ix
text, alternative for document images ix
activity logging 61
adapterprofile purpose 35
adapter attributes 91, 104, 105
adapter form attributes 91
agentCfgarguments 68
changing adapter parametersconfiguration key 61
protocol settings 41
registry settings 63
request processing 64
menusactivity logging 61
advanced settings 65
event notification 44
help 68
Main Configuration 39
registry 63
viewing configuration settings 40
Bbooks
see publications ix
Ccertificate authority
definition 71
certificate signing request (CSR) 80
certificatesCA
available functions 78
deleting 81
installing 81
viewing installed 81
certificate management toolsSee CertTool
definition 71
examplescertificate signing request (CSR) 80
install 80
installationfrom file 80
sample 80
key formats 73
overview 71
private keys and digital certificates 72
protocol configuration toolSee CertTool
register 78
registeredregistering 82
removing 82
certificates (continued)registered (continued)
viewing 82
request 79
self-signed 72
viewinginstalled 81
registered 82
viewing installed 81
viewing registered 82
CertToolCA certificate
deleting 81
installing 81
viewing 81
certificateinstall 80
register 78
request 79
viewing installed 81
viewing registered 82
changing adapter parametersaccessing 73, 77
options 78
client authentication 78
install certificate 80
private key, generating 79
registered certificateregistering 82
removing 82
viewing 82
character sets, supported 65
client authentication 75
client validation, SSL 76
configurationkey
changing with agentCfg 61
default value 39, 61
purpose 39
settingschanging with agentCfg 39
default value 40
viewing with agentCfg 40
SSL 74
contextbaseline database 61
deleting 52
listing 52
modifying 59
target DN 60
conventionsHOME directory
Tivoli_Common_Directory xii
DB_INSTANCE_HOME x
HTTP_HOME xi
ITIM_HOME xii
LDAP_HOME xi
WAS_HOME xii
WAS_MQ_HOME xii
WAS_NDM_HOME xii
typeface ix
© Copyright IBM Corp. 2003, 2005 117
conventions (continued)UNIX variable, directory notation x
used in this document ix
CSRdefinition 79
file, generating 79
customer supportsee Software Support 110
DDAML protocol
configuring with agentCfg 41
encryptiondefault value 42
type 42
options 42
properties, changing with agentCfgoptions 42
password 42
portnumber 42
require_cert_reg 44
srv_nodename 43
srv_portnumber 43
username 42
validate_client_ce 43
SSL authentication 73
DB_INSTANCE_HOMEDB2 UDB installation directory x
definition x
debug logdefault value 62
enable/disable with agentCfg 61
purpose 63
detail logdefault value 62
enable/disable with agentCfg 61
purpose 63
directoryDB_INSTANCE_HOME x
HTTP_HOME xi
installationDB2 UDB x
IBM Directory Server xi
IBM HTTP Server xi
WebSphere Application Server base product xii
WebSphere Application Server Network Deployment
product xii
WebSphere MQ xii
installation for Sun ONE Directory Server xi
ITIM_HOME xii
LDAP_HOME xi
names, UNIX notation x
WAS_HOME xii
WAS_MQ_HOME xii
WAS_NDM_HOME xii
disabilities, using documentation ix
documentsrelated viii
Tivoli Identity Manager library v
Eenable/disable with agentCfg 61
encrypted registry settings 63
encryptionDAML protocol
default value 42
type 42
SSL 71, 72
environment variableUNIX notation x
event notificationcache size 52
changing with agentCfg 44
contextbaseline database 61
deleting 52
listing 52
modifying 59
search attributes 60
target DN 60
enable/disable 51
reconciliationattributes 52
context 52
intervals 52
modifying 52
process priority 52
starting manually 52
Ffixes, obtaining 110
Hhelp menu for agentCfg 68
accessing with -help command 68
home directoriesDB_INSTANCE_HOME x
HTTP_HOME xi
ITIM_HOME xii
LDAP_HOME xi
WAS_HOME xii
WAS_MQ_HOME xii
WAS_NDM_HOME xii
HTTP_HOMEdefinition xi
IBM HTTP Server installation directory xi
Iimport
adapter profile 34
PKCS12 file 73
information centers, searching to find software problem
resolution 109
installationcertificate 80
directoryDB2 UDB x
IBM Directory Server xi
IBM HTTP Server xi
Sun ONE Directory Server xi
WebSphere Application Server base product xii
WebSphere Application Server Network Deployment
product xii
WebSphere MQ xii
profile 34
118 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
installation prerequisitesnetwork connectivity 9
operating system 9
server communication 9
Tivoli Identity Manager Server 9
Internet, searching to find software problem resolution 109,
110
ITIM_HOMEdefinition xii
directory xii
Kknowledge bases, searching to find software problem
resolution 109
LLDAP_HOME
definition xi
IBM Directory Server installation directory xi
Sun ONE Directory Server installation directory xi
logsactivity settings, changing 40
debug 61
detail 61
directory, changing with agentCfg 62
display using agentCfg 69
enable/disable, changing with agentCfg 62
file name, changing with agentCfg 61
settings, changing with adapterCfg 62
settings, changing with agentCfglog file name 62
max file size 62
settings, default values 61
trace.log file 35
view events 40
viewing statistics 66
Mmanuals
see publications ix
Nnetwork connectivity prerequisites 9
non-encrypted registry settings 63, 64
Oonline publications
accessing ix
operating system prerequisites 9
Ppassword protected file
See PKCS12 file
passwordschanging configuration key 61
configuration key, default value 39, 61
passwords, changing with agentCfgDAML protocol 42
path names, notation x
pdf format, for screen-reader software ix
PKCS12 filecertificate and key installation 80
export certificate and key 82
portnumberchanging with agentCfg 42
portnumber, changing with agentCfg 42
private keydefinition 71
private key, generating 79
problem determinationdescribing problem for IBM Software Support 111
determining business impact for IBM Software
Support 111
submitting problem to IBM Software Support 111
properties, changing with agentCfg 42
protocolDAML
configuring with agentCfg 41
encryption default value 42
encryption type 42
properties, changing with agentCfg 42
SSLoverview 71
server-to-adapter configuration 74
two-way configuration 75, 76
public key 72
publicationsaccessing online ix
related viii
Tivoli Identity Manager library v
Rreconciliation
attributes 52
context 52
intervals 52
modifying 52
process priority 52
registry settingsencrypted 63
non-encrypted 63, 64
require_cert_reg, changing with agentCfg 44
Sself-signed certificate 72
server communication prerequisites 9
Software Supportcontacting 110
describing problem for IBM Software Support 111
determining business impact for IBM Software
Support 111
submitting problem to IBM Software Support 111
srv_nodename, changing with agentCfg 43
srv_portnumber, changing with agentCfg 43
SSLcertificate installation 71
certificate signing request 79
encryption 71
key formats 73
overview 71
private keys and digital certificates 72
self-signed certificates 72
Index 119
SSL (continued)server-to-adapter configuration 74
two-way configuration 75, 76
SSL implementations, DAML protocol 73
Ttext, alternative for document images ix
thread count settingschanging with agentCfg 64
default values 64
maximum concurrent requests 64
reconciliation requests 65
system login add requests 65
system login change requests 65
system login delete requests 65
Tivoli Identity Manager Adaptercommunication with the server 75, 76
SSL communication 75, 76
Tivoli Identity Manager Servercommunication with the adapter 74
importing adapter profile 34
SSL communication 74
Tivoli Identity Manager Server prerequisites 9
Tivoli software information center ix
Tivoli_Common_Directorydefinition xii
trace.log file 35
two-way configurationSSL
client 75
client and server 76
typeface conventions ix
Uupgrade
adapter profile 35
username, changing with agentCfg 42
UTF8 support 65
Vvalidate_client_ce, changing with agentCfg 43
WWAS_HOME
definition xii
WebSphere Application Server base installation
directory xii
WAS_MQ_HOMEdefinition xii
WebSphere MQ installation directory xii
WAS_NDM_HOMEdefinition xii
WebSphere Application Server Network Deployment
installation directory xii
western European character set, support 65
120 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide
����
Printed in USA
SC32-1490-08